본문으로 건너뛰기

인터페이스: ToolDefinition<TInput, TOutput, TName, TNeedsApproval, TApprovalSchema>

정의 위치: packages/ai/src/activities/chat/tools/tool-definition.ts:229

공유 정의에서 서버 도구 또는 클라이언트 도구를 만들 수 있는 도구 정의 빌더입니다.

확장​

타입 매개변수​

TInput​

TInput extends SchemaInput | undefined = undefined

TOutput​

TOutput extends SchemaInput | undefined = undefined

TName​

TName extends string = string

TNeedsApproval​

TNeedsApproval extends boolean = false

TApprovalSchema​

TApprovalSchema extends | ApprovalSchemaConfig | undefined = undefined

속성​

__toolSide​

__toolSide: "definition";

정의 위치: packages/ai/src/activities/chat/tools/tool-definition.ts:154

상속 출처​

ToolDefinitionInstance.__toolSide

[toolApprovalCapability]?​

readonly optional [toolApprovalCapability]?: object;

정의 위치: packages/ai/src/activities/chat/tools/tool-definition.ts:161

approvalSchema​

approvalSchema: TApprovalSchema;

needsApproval​

needsApproval: TNeedsApproval;

상속 출처​

ToolDefinitionInstance.[toolApprovalCapability]

approvalSchema​

approvalSchema: TApprovalSchema;

정의 위치: packages/ai/src/activities/chat/tools/tool-definition.ts:160

상속 출처​

ToolDefinitionInstance.approvalSchema

client​

client: <TContext>(execute?) => ClientTool<TInput, TOutput, TName, TContext, TNeedsApproval, TApprovalSchema> & BuiltToolSchemaFields<TInput, TOutput, TApprovalSchema>;

정의 위치: packages/ai/src/activities/chat/tools/tool-definition.ts:263

선택적인 execute 함수를 사용해 클라이언트 측 도구를 만듭니다. 정의의 needsApproval 리터럴을 클라이언트 도구로 전달하므로 도구 호출 부분의 approval 필드는 해당 값에 따라 제한됩니다.

타입 매개변수​

TContext​

TContext = unknown

매개변수​

execute?​

ToolExecuteFunction&lt;TInput, TOutput, TContext>

반환값​

ClientTool&lt;TInput, TOutput, TName, TContext, TNeedsApproval, TApprovalSchema> & BuiltToolSchemaFields&lt;TInput, TOutput, TApprovalSchema>

description​

description: string;

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

도구가 수행하는 작업을 명확하게 설명합니다.

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

예시​

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

상속 출처​

ToolDefinitionInstance.description

execute?​

optional execute?: (args, context?) => 
  | InferSchemaType<TOutput>
| Promise<InferSchemaType<TOutput>>;

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

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

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

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

매개변수​

args​

InferSchemaType&lt;TInput>

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

context?​

ToolExecutionContext&lt;unknown>

반환값​

| InferSchemaType&lt;TOutput> | Promise&lt;InferSchemaType&lt;TOutput>>

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

예시​

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

상속 출처​

ToolDefinitionInstance.execute

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']
}

상속 출처​

ToolDefinitionInstance.inputSchema

lazy?​

optional lazy?: boolean;

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

true이면 이 도구는 지연 도구이며, 지연 도구 검색 메커니즘을 통해 검색된 후에만 LLM으로 전송됩니다. chat()(합성 검색 도구)과 Code Mode(시스템 프롬프트에 포함되지 않고 discover_tools를 통해 공개됨) 모두에서 작동합니다.

상속 출처​

ToolDefinitionInstance.lazy

metadata?​

optional metadata?: Record<string, any>;

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

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

상속 출처​

ToolDefinitionInstance.metadata

name​

name: TName;

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

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

설명적이어야 하며 명명 규칙(예: snake_case 또는 camelCase)을 따라야 합니다. tools 배열 내에서 고유해야 합니다.

예시​

"get_weather", "search_database", "sendEmail"

상속 출처​

ToolDefinitionInstance.name

needsApproval?​

optional needsApproval?: TNeedsApproval;

정의 위치: packages/ai/src/activities/chat/tools/tool-definition.ts:159

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

상속 출처​

ToolDefinitionInstance.needsApproval

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()
})

상속 출처​

ToolDefinitionInstance.outputSchema

server​

server: <TContext>(execute) => ServerTool<TInput, TOutput, TName, TContext, TNeedsApproval, TApprovalSchema> & BuiltToolSchemaFields<TInput, TOutput, TApprovalSchema>;

정의 위치: packages/ai/src/activities/chat/tools/tool-definition.ts:246

execute 함수가 있는 서버 측 도구를 만듭니다.

타입 매개변수​

TContext​

TContext = unknown

매개변수​

execute​

ToolExecuteFunction&lt;TInput, TOutput, TContext>

반환값​

ServerTool&lt;TInput, TOutput, TName, TContext, TNeedsApproval, TApprovalSchema> & BuiltToolSchemaFields&lt;TInput, TOutput, TApprovalSchema>