Typia Guide Documents

`toVercelTools()` function

undefined

@typia/vercel


export function toVercelTools(props: {
  controllers: Array<ILlmController | IHttpLlmController>;
  prefix?: boolean | undefined;
}): Record<string, Tool>;

undefined

@typia/interface


import { ILlmApplication } from "./ILlmApplication";
 
/**
 * Controller of TypeScript class-based LLM function calling.
 *
 * `ILlmController` is a controller for registering TypeScript class methods as
 * LLM function calling tools. It contains {@link ILlmApplication} with
 * {@link ILlmFunction function calling schemas}, {@link name identifier}, and
 * {@link execute class instance} for method execution.
 *
 * You can create this controller with `typia.llm.controller<Class>()` function,
 * and register it to MCP server with {@link registerMcpControllers}:
 *
 * ```typescript
 * import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 * import typia from "typia";
 * import { registerMcpControllers } from "@typia/mcp";
 *
 * class Calculator {
 *   add(input: { a: number; b: number }): number {
 *     return input.a + input.b;
 *   }
 *   subtract(input: { a: number; b: number }): number {
 *     return input.a - input.b;
 *   }
 * }
 *
 * const server = new McpServer({ name: "my-server", version: "1.0.0" });
 * registerMcpControllers({
 *   server,
 *   controllers: [
 *     typia.llm.controller<Calculator>(
 *       "calculator",
 *       new Calculator(),
 *     ),
 *   ],
 * });
 * ```
 *
 * For OpenAPI/HTTP-based controller, use {@link IHttpLlmController} instead.
 *
 * @author Jeongho Nam - https://github.com/samchon
 * @template Class Class type of the function executor
 */
export interface ILlmController<Class extends object = any> {
  /** Protocol discriminator. */
  protocol: "class";
 
  /** Identifier name of the controller. */
  name: string;
 
  /** Application schema of function calling. */
  application: ILlmApplication<Class>;
 
  /** Target class instance for function execution. */
  execute: Class;
}

undefined

@typia/interface


import { IHttpConnection } from "./IHttpConnection";
import { IHttpLlmApplication } from "./IHttpLlmApplication";
import { IHttpLlmFunction } from "./IHttpLlmFunction";
import { IHttpResponse } from "./IHttpResponse";
 
/**
 * Controller of HTTP LLM function calling.
 *
 * `IHttpLlmController` is a controller for registering OpenAPI operations as
 * LLM function calling tools. It contains {@link IHttpLlmApplication} with
 * {@link IHttpLlmFunction function calling schemas}, {@link name identifier},
 * and {@link connection} to the API server.
 *
 * You can create this controller with {@link HttpLlm.controller} function,
 * and register it to MCP server with {@link registerMcpControllers}:
 *
 * ```typescript
 * import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 * import { HttpLlm } from "@typia/utils";
 * import { registerMcpControllers } from "@typia/mcp";
 *
 * const server = new McpServer({ name: "my-server", version: "1.0.0" });
 * registerMcpControllers({
 *   server,
 *   controllers: [
 *     HttpLlm.controller({
 *       name: "shopping",
 *       document: await fetch(
 *         "https://shopping-be.wrtn.io/editor/swagger.json",
 *       ).then((r) => r.json()),
 *       connection: {
 *         host: "https://shopping-be.wrtn.io",
 *         headers: {
 *           Authorization: "Bearer ********",
 *         },
 *       },
 *     }),
 *   ],
 * });
 * ```
 *
 * For TypeScript class-based controller, use {@link ILlmController} instead.
 *
 * @author Jeongho Nam - https://github.com/samchon
 */
export interface IHttpLlmController {
  /** Protocol discriminator. */
  protocol: "http";
 
  /** Identifier name of the controller. */
  name: string;
 
  /** Application schema of function calling. */
  application: IHttpLlmApplication;
 
  /**
   * Connection to the server.
   *
   * Connection to the API server including the URL and headers.
   */
  connection: IHttpConnection;
 
  /**
   * Executor of the API function.
   *
   * Default executor is {@link HttpLlm.execute} function, and you can override
   * it with your own function.
   *
   * @param props Properties of the API function call
   * @returns HTTP response of the API function call
   */
  execute?:
    | undefined
    | ((props: {
        /** Connection to the server. */
        connection: IHttpConnection;
 
        /** Application schema. */
        application: IHttpLlmApplication;
 
        /** Function schema. */
        function: IHttpLlmFunction;
 
        /**
         * Arguments of the function calling.
         *
         * It is an object of key-value pairs of the API function's parameters.
         * The property keys are composed by below rules:
         *
         * - Parameter names
         * - Query parameter as an object type if exists
         * - Body parameter if exists
         */
        arguments: object;
      }) => Promise<IHttpResponse>);
}

undefined

@typia/utils


import {
  IHttpConnection,
  IHttpLlmApplication,
  IHttpLlmController,
  IHttpLlmFunction,
  IHttpMigrateApplication,
  IHttpResponse,
  ILlmFunction,
  OpenApi,
  OpenApiV3,
  OpenApiV3_1,
  SwaggerV2,
} from "@typia/interface";
 
import { HttpMigration } from "./HttpMigration";
import { HttpLlmApplicationComposer } from "./internal/HttpLlmApplicationComposer";
import { HttpLlmFunctionFetcher } from "./internal/HttpLlmFunctionFetcher";
import { LlmDataMerger } from "./internal/LlmDataMerger";
 
/**
 * LLM function calling utilities for OpenAPI documents.
 *
 * `HttpLlm` converts OpenAPI documents into LLM function calling applications
 * and executes them. Supports all OpenAPI versions (Swagger 2.0, OpenAPI 3.0,
 * 3.1) through automatic conversion to {@link OpenApi} format.
 *
 * Main functions:
 *
 * - {@link controller}: Create {@link IHttpLlmController} from OpenAPI document
 * - {@link application}: Convert OpenAPI document to {@link IHttpLlmApplication}
 * - {@link execute}: Call an LLM function and return the response body
 * - {@link propagate}: Call an LLM function and return full HTTP response
 * - {@link mergeParameters}: Merge LLM-filled and human-filled parameters
 *
 * Typical workflow:
 *
 * 1. Load OpenAPI document (JSON/YAML)
 * 2. Call `HttpLlm.application()` to get function schemas
 * 3. Send function schemas to LLM for function selection
 * 4. Call `HttpLlm.execute()` with LLM's chosen function and arguments
 *
 * @author Jeongho Nam - https://github.com/samchon
 */
export namespace HttpLlm {
  /* -----------------------------------------------------------
    COMPOSERS
  ----------------------------------------------------------- */
  /**
   * Create HTTP LLM controller from OpenAPI document.
   *
   * Composes {@link IHttpLlmController} from OpenAPI document with connection
   * info. The controller can be used with {@link registerMcpControllers} to
   * register all API operations as MCP tools at once.
   *
   * @param props Controller properties
   * @returns HTTP LLM controller
   */
  export const controller = (props: {
    /** Identifier name of the controller. */
    name: string;
 
    /** OpenAPI document to convert. */
    document:
      | OpenApi.IDocument
      | SwaggerV2.IDocument
      | OpenApiV3.IDocument
      | OpenApiV3_1.IDocument;
 
    /** Connection to the API server. */
    connection: IHttpConnection;
 
    /** LLM schema conversion configuration. */
    config?: Partial<IHttpLlmApplication.IConfig>;
 
    /**
     * Custom executor of the API function.
     *
     * Default executor is {@link HttpLlm.execute} function.
     */
    execute?: IHttpLlmController["execute"];
  }): IHttpLlmController => ({
    protocol: "http",
    name: props.name,
    application: application({
      document: props.document,
      config: props.config,
    }),
    connection: props.connection,
    execute: props.execute,
  });
 
  /**
   * Convert OpenAPI document to LLM function calling application.
   *
   * Converts API operations to LLM-callable functions. Use
   * {@link mergeParameters} if `separate` option is configured.
   *
   * @param props Composition properties
   * @returns LLM function calling application
   */
  export const application = (props: {
    /** OpenAPI document to convert. */
    document:
      | OpenApi.IDocument
      | SwaggerV2.IDocument
      | OpenApiV3.IDocument
      | OpenApiV3_1.IDocument;
 
    /** LLM schema conversion configuration. */
    config?: Partial<IHttpLlmApplication.IConfig>;
  }): IHttpLlmApplication => {
    // MIGRATE
    const migrate: IHttpMigrateApplication = HttpMigration.application(
      props.document,
    );
    return HttpLlmApplicationComposer.application({
      migrate,
      config: {
        reference: props.config?.reference ?? true,
        strict: props.config?.strict ?? false,
        separate: props.config?.separate ?? null,
        maxLength: props.config?.maxLength ?? 64,
        equals: props.config?.equals ?? false,
      },
    });
  };
 
  /* -----------------------------------------------------------
    FETCHERS
  ----------------------------------------------------------- */
  /** Properties for LLM function call. */
  export interface IFetchProps {
    /** LLM function calling application. */
    application: IHttpLlmApplication;
 
    /** Function to call. */
    function: IHttpLlmFunction;
 
    /** HTTP connection info. */
    connection: IHttpConnection;
 
    /** Function arguments. */
    input: object;
  }
 
  /**
   * Execute LLM function call.
   *
   * Calls API endpoint and returns response body. Throws {@link HttpError} on
   * non-2xx status.
   *
   * @param props Function call properties
   * @returns Response body
   * @throws HttpError on non-2xx status
   */
  export const execute = (props: IFetchProps): Promise<unknown> =>
    HttpLlmFunctionFetcher.execute(props);
 
  /**
   * Propagate LLM function call.
   *
   * Calls API endpoint and returns full response including non-2xx. Use when
   * you need to handle error responses yourself.
   *
   * @param props Function call properties
   * @returns Full HTTP response
   * @throws Error only on connection failure
   */
  export const propagate = (props: IFetchProps): Promise<IHttpResponse> =>
    HttpLlmFunctionFetcher.propagate(props);
 
  /* -----------------------------------------------------------
    MERGERS
  ----------------------------------------------------------- */
  /** Properties for parameter merging. */
  export interface IMergeProps {
    /** Target function metadata. */
    function: ILlmFunction;
 
    /** LLM-provided arguments. */
    llm: object | null;
 
    /** Human-provided arguments. */
    human: object | null;
  }
 
  /**
   * Merge separated parameters.
   *
   * Combines human and LLM parameters when `separate` option was used. Throws
   * error if `separate` was not configured.
   *
   * @param props Merge properties
   * @returns Merged parameters
   */
  export const mergeParameters = (props: IMergeProps): object =>
    LlmDataMerger.parameters(props);
 
  /**
   * Merge two values.
   *
   * Objects are merged at property level. Primitives return `y ?? x`.
   *
   * @param x First value
   * @param y Second value (preferred)
   * @returns Merged value
   */
  export const mergeValue = (x: unknown, y: unknown): unknown =>
    LlmDataMerger.value(x, y);
}

Vercel AI SDK integration for typia.

toVercelTools() converts TypeScript classes or OpenAPI documents into Vercel AI SDK Record<string, Tool> at once.

Every class method becomes a tool, JSDoc comments become tool descriptions, and TypeScript types become JSON schemas — all at compile time. For OpenAPI documents, every API endpoint is converted to a Vercel tool with schemas from the specification.

Validation feedback is embedded automatically.

Setup

Terminal


npm install @typia/vercel ai
npm install typia
npx typia setup

From TypeScript Class

Vercel AI Tools

src/main.ts


import { openai } from "@ai-sdk/openai";
import { toVercelTools } from "@typia/vercel";
import { generateText, GenerateTextResult, Tool } from "ai";
import typia from "typia";
 
import { Calculator } from "./Calculator";
 
const tools: Record<string, Tool> = toVercelTools({
  controllers: [
    typia.llm.controller<Calculator>("calculator", new Calculator()),
  ],
});
 
const result: GenerateTextResult = await generateText({
  model: openai("gpt-4o"),
  prompt: "What is 10 + 5?",
  tools,
});

undefined

Calculator.ts


export class Calculator {
  /**
   * Add two numbers.
   *
   * @param p The input containing two numbers to add
   * @returns The sum of a and b
   */
  add(p: Calculator.IProps): number {
    return p.x + p.y;
  }
 
  /**
   * Subtract two numbers.
   *
   * @param p The input containing two numbers to subtract
   * @returns The difference of a and b
   */
  subtract(p: Calculator.IProps): number {
    return p.x - p.y;
  }
 
  /**
   * Multiply two numbers.
   *
   * @param p The input containing two numbers to multiply
   * @returns The product of a and b
   */
  multiply(p: Calculator.IProps): number {
    return p.x * p.y;
  }
 
  /**
   * Divide two numbers.
   *
   * @param p The input containing two numbers to divide
   * @returns The quotient of a and b
   */
  divide(p: Calculator.IProps): number {
    if (p.y === 0) {
      throw new Error("Division by zero is not allowed");
    }
    return p.x / p.y;
  }
}
export namespace Calculator {
  export interface IProps {
    /** First operand */
    x: number;
 
    /** Second operand */
    y: number;
  }
}

undefined

BbsArticleService.ts


import { tags } from "typia";
 
import { IBbsArticle } from "./IBbsArticle";
 
export declare class BbsArticleService {
  /**
   * Get all articles.
   *
   * List up every articles archived in the BBS DB.
   *
   * @returns List of every articles
   */
  public index(): IBbsArticle[];
 
  /**
   * Create a new article.
   *
   * Writes a new article and archives it into the DB.
   *
   * @param props Properties of create function
   * @returns Newly created article
   */
  public create(props: {
    /** Information of the article to create */
    input: IBbsArticle.ICreate;
  }): IBbsArticle;
 
  /**
   * Update an article.
   *
   * Updates an article with new content.
   *
   * @param props Properties of update function
   * @param input New content to update
   */
  public update(props: {
    /** Target article's {@link IBbsArticle.id}. */
    id: string & tags.Format<"uuid">;
 
    /** New content to update. */
    input: IBbsArticle.IUpdate;
  }): void;
 
  /**
   * Erase an article.
   *
   * Erases an article from the DB.
   *
   * @param props Properties of erase function
   */
  public erase(props: {
    /** Target article's {@link IBbsArticle.id}. */
    id: string & tags.Format<"uuid">;
  }): void;
}

undefined

IBbsArticle.ts


import { tags } from "typia";
 
/**
 * Article entity.
 *
 * `IBbsArticle` is an entity representing an article in the BBS (Bulletin Board
 * System).
 */
export interface IBbsArticle extends IBbsArticle.ICreate {
  /** Primary Key. */
  id: string & tags.Format<"uuid">;
 
  /** Creation time of the article. */
  created_at: string & tags.Format<"date-time">;
 
  /** Last updated time of the article. */
  updated_at: string & tags.Format<"date-time">;
}
export namespace IBbsArticle {
  /** Information of the article to create. */
  export interface ICreate {
    /**
     * Title of the article.
     *
     * Representative title of the article.
     */
    title: string;
 
    /**
     * Content body.
     *
     * Content body of the article written in the markdown format.
     */
    body: string;
 
    /**
     * Thumbnail image URI.
     *
     * Thumbnail image URI which can represent the article.
     *
     * If configured as `null`, it means that no thumbnail image in the article.
     */
    thumbnail:
      | null
      | (string & tags.Format<"uri"> & tags.ContentMediaType<"image/*">);
  }
 
  /**
   * Information of the article to update.
   *
   * Only the filled properties will be updated.
   */
  export type IUpdate = Partial<ICreate>;
}

Create controllers from TypeScript classes with typia.llm.controller<Class>(), and pass them to toVercelTools().

controllers: Array of controllers created via typia.llm.controller<Class>() or HttpLlm.controller()
prefix: When true (default), tool names are formatted as {controllerName}_{methodName}. Set to false to use bare method names

From OpenAPI Document

src/main.ts


import { toVercelTools } from "@typia/vercel";
import { HttpLlm } from "@typia/utils";
import { Tool } from "ai";
 
const tools: Record<string, Tool> = toVercelTools({
  controllers: [
    HttpLlm.controller({
      name: "shopping",
      document: await fetch(
        "https://shopping-be.wrtn.ai/editor/swagger.json",
      ).then((r) => r.json()),
      connection: {
        host: "https://shopping-be.wrtn.ai",
        headers: { Authorization: "Bearer ********" },
      },
    }),
  ],
});

Create controllers from OpenAPI documents with HttpLlm.controller(), and pass them to toVercelTools().

name: Controller name used as prefix for tool names
document: Swagger/OpenAPI document (v2.0, v3.0, or v3.1)
connection: HTTP connection info including host and optional headers

Validation Feedback

Validation Test

test_vercel_class_controller_validation.ts


import type { Tool } from "ai";
import { TestValidator } from "@nestia/e2e";
import { ILlmController, IValidation } from "@typia/interface";
import { stringifyValidationFailure } from "@typia/utils";
import { toVercelTools } from "@typia/vercel";
import typia from "typia";
 
import { Calculator } from "../structures/Calculator";
 
export const test_vercel_class_controller_validation =
  async (): Promise<void> => {
    // 1. Create class-based controller using typia.llm.controller
    const controller: ILlmController<Calculator> =
      typia.llm.controller<Calculator>("calculator", new Calculator());
 
    // 2. Convert to Vercel tools
    const tools: Record<string, Tool> = toVercelTools({
      controllers: [controller],
    });
 
    // 3. Test validation failure: wrong type (string instead of number)
    const addTool: Tool = tools["calculator_add"]!;
    const result: unknown = await addTool.execute!(
      { x: "not a number", y: 5 },
      { toolCallId: "test-1", messages: [], abortSignal: undefined as any },
    );
 
    // 4. Verify the result contains validation error
    const expected: IValidation = typia.validate<Calculator.IProps>({
      x: "not a number",
      y: 5,
    });
    if (expected.success === true)
      throw new Error("Expected validation to fail, but it succeeded.");
 
    const expectedMessage: string = stringifyValidationFailure(expected);
 
    TestValidator.predicate("result should be an error object", () => {
      const res = result as { error?: boolean; message?: string };
      return res.error === true && typeof res.message === "string";
    });
 
    TestValidator.predicate("error message should contain validation info", () => {
      const res = result as { error: boolean; message: string };
      return res.message === expectedMessage;
    });
  };

validation-feedback-concept.ts


import { ILlmApplication, ILlmFunction, IValidation } from "@samchon/openapi";
import { FunctionCall } from "pseudo";
 
export const correctFunctionCall = (props: {
  functionCall: FunctionCall;
  application: ILlmApplication<"chatgpt">;
  retry: (reason: string, errors?: IValidation.IError[]) => Promise<unknown>;
}): Promise<unknown> => {
  // FIND FUNCTION
  const func: ILlmFunction<"chatgpt"> | undefined =
    props.application.functions.find((f) => f.name === call.name);
  if (func === undefined) {
    // never happened in my experience
    return props.retry(
      "Unable to find the matched function name. Try it again.",
    );
  }
 
  // VALIDATE
  const result: IValidation<unknown> = func.validate(
    props.functionCall.arguments,
  );
  if (result.success === false) {
    // 1st trial: 30% (gpt-4o-mini in shopping mall chatbot)
    // 2nd trial with validation feedback: 99%
    // 3nd trial with validation feedback again: never have failed
    return props.retry(
      "Type errors are detected. Correct it through validation errors",
      {
        errors: result.errors,
      },
    );
  }
  return result.data;
};

When LLM sends { x: "not a number", y: 5 }, the result is returned as { error: true, message: "..." } with detailed validation errors from stringifyValidationFailure(). The LLM reads this and self-corrects on the next turn.

In my experience, OpenAI gpt-4o-mini makes type-level mistakes about 70% of the time on complex schemas (Shopping Mall service). With validation feedback, the success rate jumps from 30% to 99% on the second attempt. Third attempt has never failed.

The embedded typia.validate<T>() creates validation logic by analyzing TypeScript source codes and types at the compilation level — more accurate and detailed than any runtime validator.

Components	`typia`	`TypeBox`	`ajv`	`io-ts`	`zod`	`C.V.`
Easy to use	✅	❌	❌	❌	❌	❌
Object (simple)	✔	✔	✔	✔	✔	✔
Object (hierarchical)	✔	✔	✔	✔	✔	✔
Object (recursive)	✔	❌	✔	✔	✔	✔
Object (union, implicit)	✅	❌	❌	❌	❌	❌
Object (union, explicit)	✔	✔	✔	✔	✔	❌
Object (additional tags)	✔	✔	✔	✔	✔	✔
Object (template literal types)	✔	✔	✔	❌	❌	❌
Object (dynamic properties)	✔	✔	✔	❌	❌	❌
Array (rest tuple)	✅	❌	❌	❌	❌	❌
Array (hierarchical)	✔	✔	✔	✔	✔	✔
Array (recursive)	✔	✔	✔	✔	✔	❌
Array (recursive, union)	✔	✔	❌	✔	✔	❌
Array (R+U, implicit)	✅	❌	❌	❌	❌	❌
Array (repeated)	✅	❌	❌	❌	❌	❌
Array (repeated, union)	✅	❌	❌	❌	❌	❌
Ultimate Union Type	✅	❌	❌	❌	❌	❌

C.V. means class-validator

This validation feedback strategy also covers restriction properties:

string: minLength, maxLength, pattern, format, contentMediaType
number: minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf
array: minItems, maxItems, uniqueItems, items

Structured Output

Use typia.llm.parameters<T>() with Vercel’s jsonSchema() to generate structured output with validation:

src/main.ts


import { openai } from "@ai-sdk/openai";
import { dedent, stringifyValidationFailure } from "@typia/utils";
import { generateObject, jsonSchema } from "ai";
import typia, { tags } from "typia";
 
interface IMember {
  email: string & tags.Format<"email">;
  name: string;
  age: number & tags.Minimum<0> & tags.Maximum<100>;
  hobbies: string[];
  joined_at: string & tags.Format<"date">;
}
 
const { object } = await generateObject({
  model: openai("gpt-4o"),
  schema: jsonSchema<IMember>(typia.llm.parameters<IMember>(), {
    validate: (value) => {
      const result = typia.validate<IMember>(value);
      if (result.success) return { success: true, value: result.data };
      return {
        success: false,
        error: new Error(stringifyValidationFailure(result)),
      };
    },
  }),
  prompt: dedent`
    I am a new member of the community.
 
    My name is John Doe, and I am 25 years old.
    I like playing basketball and reading books,
    and joined to this community at 2022-01-01.
  `,
});

Terminal


{
  email: 'john.doe@example.com',
  name: 'John Doe',
  age: 25,
  hobbies: [ 'playing basketball', 'reading books' ],
  joined_at: '2022-01-01'
}

The IMember interface is the single source of truth. typia.llm.parameters<IMember>() generates the JSON schema, and typia.validate<IMember>() validates the output — all from the same type.

Error Handling

Error Handling Test

test_vercel_class_controller_error_handling.ts


import type { Tool } from "ai";
import { TestValidator } from "@nestia/e2e";
import { ILlmController } from "@typia/interface";
import { toVercelTools } from "@typia/vercel";
import typia from "typia";
 
import { Calculator } from "../structures/Calculator";
 
export const test_vercel_class_controller_error_handling =
  async (): Promise<void> => {
    // 1. Create class-based controller using typia.llm.controller
    const controller: ILlmController<Calculator> =
      typia.llm.controller<Calculator>("calculator", new Calculator());
 
    // 2. Convert to Vercel tools
    const tools: Record<string, Tool> = toVercelTools({
      controllers: [controller],
    });
 
    // 3. Test divide by zero (throws an error)
    const divideTool: Tool = tools["calculator_divide"]!;
    const result: unknown = await divideTool.execute!(
      { x: 10, y: 0 },
      { toolCallId: "test-1", messages: [], abortSignal: undefined as any },
    );
 
    // 4. Verify the result contains error
    TestValidator.predicate("result should be an error object", () => {
      const res = result as { error?: boolean; message?: string };
      return res.error === true && typeof res.message === "string";
    });
 
    TestValidator.predicate("error message should contain division by zero", () => {
      const res = result as { error: boolean; message: string };
      return res.message.includes("Division by zero");
    });
  };

When a tool execution throws a runtime error (e.g., division by zero), @typia/vercel catches the exception and returns { error: true, message: "Error: Division by zero is not allowed" }. This is different from validation errors — validation errors indicate wrong argument types, while runtime errors indicate the function itself failed.

toVercelTools() function

undefined

undefined

undefined

undefined

Setup

From TypeScript Class

Vercel AI Tools

undefined

undefined

undefined

From OpenAPI Document

Validation Feedback

Validation Test

undefined

Structured Output

Error Handling

Error Handling Test

undefined

`toVercelTools()` function