본문으로 건너뛰기

인터페이스: Tool<TInput, TOutput, TName, TContext>

정의 위치: packages/ai/src/types.ts:694

함수 호출을 위한 도구/함수 정의입니다.

도구를 사용하면 모델이 외부 시스템 및 API와 상호작용하거나 계산을 수행할 수 있습니다. 모델은 사용자의 요청과 도구 설명에 따라 도구를 호출할 시점을 결정합니다.

도구는 Standard JSON Schema를 준수하는 모든 라이브러리(Zod, ArkType, Valibot 등) 또는 일반 JSON Schema 객체를 사용하여 런타임 검증과 타입 안전성을 제공할 수 있습니다.

참고​

확장 대상​

타입 매개변수​

TInput​

TInput extends SchemaInput | undefined = SchemaInput

TOutput​

TOutput extends SchemaInput | undefined = SchemaInput

TName​

TName extends string = string

TContext​

TContext = unknown

속성​

description​

description: string;

정의 위치: packages/ai/src/types.ts:718

도구가 수행하는 작업에 대한 명확한 설명입니다.

이는 매우 중요합니다. 모델은 이 설명을 사용하여 도구 호출 시점을 결정합니다. 도구가 수행하는 작업, 필요한 매개변수, 반환하는 값을 구체적으로 작성해야 합니다.

예제​

"Get the current weather in a given location. Returns temperature, conditions, and forecast."

execute?​

optional execute?: ToolExecuteFunction<TInput, TOutput, TContext>;

정의 위치: packages/ai/src/types.ts:798

모델이 이 도구를 호출할 때 실행할 선택적 함수입니다.

제공하면 SDK가 모델의 인수로 함수를 자동 실행하고 결과를 모델에 다시 전달합니다. 이를 통해 자율적인 도구 사용 루프를 구현할 수 있습니다.

어떤 값이든 반환할 수 있으며, 필요한 경우 자동으로 문자열로 변환됩니다.

매개변수​

args

모델의 도구 호출에서 파싱된 인수입니다(inputSchema에 대해 검증됨).

반환값​

모델에 다시 보낼 결과입니다(outputSchema가 제공된 경우 이에 대해 검증됨).

예제​

execute: async (args) => {
  const weather = await fetchWeather(args.location);
  return weather; // Can return object or string
}

inputSchema?​

optional inputSchema?: TInput;

정의 위치: packages/ai/src/types.ts:758

도구의 입력 매개변수를 설명하는 스키마입니다.

Standard JSON Schema를 준수하는 모든 스키마(Zod, ArkType, Valibot 등) 또는 일반 JSON Schema 객체를 사용할 수 있습니다. 도구가 허용하는 인수의 구조와 타입을 정의합니다. 모델은 이 스키마에 맞는 인수를 생성합니다. Standard JSON Schema를 준수하는 스키마는 LLM provider용 JSON Schema로 변환됩니다.

참고​

예제​

// Using Zod v4+ schema (natively supports Standard JSON Schema)
import { z } from 'zod';
z.object({
  location: z.string().describe("City name or coordinates"),
  unit: z.enum(["celsius", "fahrenheit"]).optional()
})
// Using ArkType (natively supports Standard JSON Schema)
import { type } from 'arktype';
type({
  location: 'string',
  unit: "'celsius' | 'fahrenheit'"
})
// Using plain JSON Schema
{
  type: 'object',
  properties: {
    location: { type: 'string', description: 'City name or coordinates' },
    unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
  },
  required: ['location']
}

lazy?​

optional lazy?: boolean;

정의 위치: packages/ai/src/types.ts:804

true이면 이 도구는 지연 도구이며, 지연 도구 검색 메커니즘을 통해 검색된 후에만 LLM으로 전송됩니다. chat()(합성 검색 도구)과 Code Mode 모두에서 작동합니다(system prompt에서 제외되고 discover_tools를 통해 공개됨).

metadata?​

optional metadata?: Record<string, any>;

정의 위치: packages/ai/src/types.ts:807

어댑터 또는 사용자 지정 확장을 위한 추가 메타데이터입니다.

name​

name: TName;

정의 위치: packages/ai/src/types.ts:708

도구의 고유한 이름입니다(모델이 도구를 호출할 때 사용).

명확해야 하며 네이밍 규칙 (예: snake_case 또는 camelCase) 을 따라야 합니다. 도구 배열 내에서 고유해야 합니다.

예제​

"get_weather", "search_database", "sendEmail"

needsApproval?​

optional needsApproval?: boolean;

정의 위치: packages/ai/src/types.ts:801

true이면 실행 전에 사용자 승인이 필요합니다. 서버 도구와 클라이언트 도구 모두에서 작동합니다.

outputSchema?​

optional outputSchema?: TOutput;

정의 위치: packages/ai/src/types.ts:779

도구 출력을 검증하기 위한 선택적 스키마입니다.

표준 JSON 스키마 준수 스키마 또는 평면 JSON 스키마 객체일 수 있습니다. 표준 스키마 준수 스키마를 제공하면 도구 결과가 모델에 다시 전송되기 전에 이 스키마에 따라 유효성 검사를 수행합니다. 이는 도구 구현의 버그를 포착하고 일관된 출력 형식을 보장합니다.

참고: 이는 클라이언트 측 검증만 수행하며 LLM provider로 전송되지 않습니다. 참고: 일반 JSON Schema 출력 검증은 런타임에 수행되지 않습니다.

예제​

// Using Zod
z.object({
  temperature: z.number(),
  conditions: z.string(),
  forecast: z.array(z.string()).optional()
})