본문으로 건너뛰기

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

다음에 정의되어 있습니다: packages/ai/src/activities/chat/tools/tool-definition.ts:86

서버 측 도구를 위한 마커 타입입니다.

확장​

  • Tool<TInput, TOutput, TName, TContext>.ToolApprovalCapabilityMarker<TNeedsApproval, TApprovalSchema>

타입 매개변수​

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: "server";

다음에 정의되어 있습니다: packages/ai/src/activities/chat/tools/tool-definition.ts:97

[toolApprovalCapability]?​

readonly optional [toolApprovalCapability]?: object;

다음에 정의되어 있습니다: packages/ai/src/activities/chat/tools/tool-definition.ts:26

approvalSchema​

approvalSchema: TApprovalSchema;

needsApproval​

needsApproval: TNeedsApproval;

상속 출처​

ToolApprovalCapabilityMarker.[toolApprovalCapability]

approvalSchema?​

optional approvalSchema?: TApprovalSchema;

다음에 정의되어 있습니다: packages/ai/src/activities/chat/tools/tool-definition.ts:101

description​

description: string;

다음에 정의되어 있습니다: packages/ai/src/types.ts:718

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

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

예시​

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

상속 출처​

Tool.description

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
}

상속 출처​

Tool.execute

inputSchema?​

optional inputSchema?: TInput;

다음에 정의되어 있습니다: packages/ai/src/activities/chat/tools/tool-definition.ts:98

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

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

재정의​

Tool.inputSchema

lazy?​

optional lazy?: boolean;

다음에 정의되어 있습니다: packages/ai/src/types.ts:804

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

상속 출처​

Tool.lazy

metadata?​

optional metadata?: Record<string, any>;

다음에 정의되어 있습니다: packages/ai/src/types.ts:807

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

상속 출처​

Tool.metadata

name​

name: TName;

다음에 정의되어 있습니다: packages/ai/src/types.ts:708

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

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

예시​

"get_weather", "search_database", "sendEmail"

상속 출처​

Tool.name

needsApproval?​

optional needsApproval?: TNeedsApproval;

다음에 정의되어 있습니다: packages/ai/src/activities/chat/tools/tool-definition.ts:100

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

재정의​

Tool.needsApproval

outputSchema?​

optional outputSchema?: TOutput;

다음에 정의되어 있습니다: packages/ai/src/activities/chat/tools/tool-definition.ts:99

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

Standard JSON Schema 호환 스키마 또는 일반 JSON Schema 객체일 수 있습니다. Standard Schema 호환 스키마를 제공하면 도구 결과를 모델에 다시 보내기 전에 이 스키마에 대해 검증합니다. 이를 통해 도구 구현의 버그를 찾아 일관된 출력 형식을 보장합니다.

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

예시​

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

재정의​

Tool.outputSchema