본문으로 건너뛰기

인터페이스: ProviderTool<TProvider, TKind>

정의 위치: packages/ai/src/tools/provider-tool.ts:19

어댑터 패키지 팩토리가 생성하는 provider별 도구입니다 (예: @tanstack/ai-anthropic/tools의 webSearchTool).

~ 접두사가 붙은 두 필드는 타입 전용 팬텀 브랜드이며 런타임에 할당되지 않습니다. 이를 통해 코어 타입 시스템이 팩토리의 출력을 선택한 모델의 supports.tools 목록과 대조하고, 조합이 지원되지 않으면 컴파일 시간 오류를 표시할 수 있습니다.

사용자 정의 도구(toolDefinition()을 통해 생성)는 일반 Tool로 유지되며 모든 모델에 할당할 수 있습니다.

확장​

타입 매개변수​

TProvider​

TProvider extends string

provider 식별자(예: 'anthropic', 'openai')입니다.

TKind​

TKind extends string

provider의 supports.tools 항목과 일치하는 표준 도구 종류 문자열입니다 (예: 'web_search', 'code_execution').

속성​

~provider​

readonly ~provider: TProvider;

정의 위치: packages/ai/src/tools/provider-tool.ts:23

~toolKind​

readonly ~toolKind: TKind;

정의 위치: packages/ai/src/tools/provider-tool.ts:24

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?: (args, context?) => any;

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

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

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

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

매개변수​

args​

any

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

context?​

ToolExecutionContext<unknown>

반환값​

any

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

예제​

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

상속됨​

Tool.execute

inputSchema?​

optional inputSchema?: SchemaInput;

정의 위치: 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']
}

상속됨​

Tool.inputSchema

lazy?​

optional lazy?: boolean;

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

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

상속됨​

Tool.lazy

metadata?​

optional metadata?: Record<string, any>;

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

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

상속됨​

Tool.metadata

name​

name: string;

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

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

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

예제​

"get_weather", "search_database", "sendEmail"

상속됨​

Tool.name

needsApproval?​

optional needsApproval?: boolean;

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

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

상속됨​

Tool.needsApproval

outputSchema?​

optional outputSchema?: SchemaInput;

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

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

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