인터페이스: ToolDefinitionInstance<TInput, TOutput, TName, TContext, TNeedsApproval, TApprovalSchema>
정의 위치: packages/ai/src/activities/chat/tools/tool-definition.ts:146
직접 사용하거나 서버/클라이언트용으로 인스턴스화할 수 있는 도구 정의입니다.
확장
Tool<TInput,TOutput,TName,TContext>
확장됨
타입 매개변수
TInput
TInput extends SchemaInput | undefined = undefined
TOutput
TOutput extends SchemaInput | undefined = undefined
TName
TName extends string = string
TContext
TContext = unknown
TNeedsApproval
TNeedsApproval extends boolean = false
TApprovalSchema
TApprovalSchema extends
| ApprovalSchemaConfig
| undefined = undefined
속성
__toolSide
__toolSide: "definition";
정의 위치: packages/ai/src/activities/chat/tools/tool-definition.ts:154
[toolApprovalCapability]?
readonly optional [toolApprovalCapability]?: object;
정의 위치: packages/ai/src/activities/chat/tools/tool-definition.ts:161
approvalSchema
approvalSchema: TApprovalSchema;
needsApproval
needsApproval: TNeedsApproval;
approvalSchema
approvalSchema: TApprovalSchema;
정의 위치: packages/ai/src/activities/chat/tools/tool-definition.ts:160
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가 모델의 인수로 함수를 자동 실행하고 그 결과를 모델에 다시 전달합니다. 이를 통해 자율적인 도구 사용 루프가 가능합니다.
모든 값을 반환할 수 있으며, 필요한 경우 자동으로 문자열화됩니다.
Param
args
모델의 도구 호출에서 파싱된 인수입니다(inputSchema에 대해 검증됨).
반환값
모델에 다시 보낼 결과입니다(outputSchema가 제공된 경우 이에 대해 검증됨).
예제
execute: async (args) => {
const weather = await fetchWeather(args.location);
return weather; // Can return object or string
}
상속됨
inputSchema
inputSchema: TInput;
정의 위치: packages/ai/src/activities/chat/tools/tool-definition.ts:157
도구의 입력 매개변수를 설명하는 스키마입니다.
Standard JSON Schema 호환 스키마(Zod, ArkType, Valibot 등) 또는 일반 JSON Schema 객체일 수 있습니다. 도구가 허용하는 인수의 구조와 타입을 정의합니다. 모델은 이 스키마에 맞는 인수를 생성합니다. Standard JSON Schema 호환 스키마는 LLM 공급자를 위해 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(시스템 프롬프트에서 제외되고 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)을 따라야 합니다. tools 배열 내에서 고유해야 합니다.
예제
"get_weather", "search_database", "sendEmail"
상속됨
needsApproval?
optional needsApproval?: TNeedsApproval;
정의 위치: packages/ai/src/activities/chat/tools/tool-definition.ts:159
true이면 도구를 실행하기 전에 사용자 승인이 필요합니다. 서버 도구와 클라이언트 도구 모두에서 작동합니다.
재정의
outputSchema
outputSchema: TOutput;
정의 위치: packages/ai/src/activities/chat/tools/tool-definition.ts:158
도구 출력을 검증하기 위한 선택적 스키마입니다.
Standard JSON Schema 호환 스키마 또는 일반 JSON Schema 객체일 수 있습니다. Standard Schema 호환 스키마가 제공되면 도구 결과를 모델에 다시 보내기 전에 이 스키마에 대해 검증합니다. 이를 통해 도구 구현의 버그를 발견하고 일관된 출력 형식을 보장합니다.
참고: 이는 클라이언트 측 검증만 수행하며 LLM 공급자에는 전송되지 않습니다. 참고: 일반 JSON Schema 출력 검증은 런타임에 수행되지 않습니다.
예제
// Using Zod
z.object({
temperature: z.number(),
conditions: z.string(),
forecast: z.array(z.string()).optional()
})