`tool()`

tool은 자신의 execute 메서드와 라이프사이클 콜백의 툴 입력과 컨텍스트를 추론하는 헬퍼 함수입니다. 런타임 동작은 없지만 TypeScript가 툴 콜백의 타입을 추론하도록 돕습니다. 이 헬퍼가 없으면 TypeScript는 inputSchema와 contextSchema 속성을 툴 콜백에 연결할 수 없고, 콜백 인자 타입을 추론할 수 없습니다.

runtimeContext, toolsContext, 툴 context 및 민감한 컨텍스트 필터링의 전체 모델은 Runtime and Tool Context를 참고하세요.

Tool 타입은 네 가지 툴 종류의 합집합입니다.

FunctionTool: 알려진 입력/출력 타입을 가진 사용자 정의 함수 스타일 툴입니다.
DynamicTool: 런타임에 정의되며 unknown 입력/출력 타입을 가진 함수 스타일 툴입니다.
ProviderDefinedTool: 프로바이더가 정의하고 코드가 실행하는 툴입니다.
ProviderExecutedTool: 프로바이더가 정의하고 프로바이더가 실행하는 툴입니다.

출처: 문서

본문

import { tool } from 'ai';
import { z } from 'zod';

export const weatherTool = tool({
  description: 'Get the weather in a location',
  inputSchema: z.object({
    location: z.string().describe('The location to get the weather for'),
  }),
  // location below is inferred to be a string:
  execute: async ({ location }) => ({
    location,
    temperature: 72 + Math.floor(Math.random() * 21) - 10,
  }),
});

Import

import { tool } from "ai"

API Signature

Parameters (파라미터)

tool: Tool — 툴 정의입니다.
- description: string | ((options: { context: CONTEXT; experimental_sandbox?: Experimental_SandboxSession }) => string) (선택) — 모델이 언제 어떻게 사용할 수 있는지에 대한 세부 정보를 포함한 툴의 목적 정보입니다. 고정 설명에는 문자열을, 각 모델 호출 전에 툴별 컨텍스트와 선택적 실험적 샌드박스에서 설명을 도출하려면 함수를 제공하세요.
- deferLoading: boolean (선택) — toolSearch가 발견할 때까지 이 툴을 모델 컨텍스트 밖에 둡니다. toolDiscovery: 'conversation'와 함께 직접 호출 또는 코드 모드를 지원합니다. 발견된 툴은 다음 모델 스텝에서 사용 가능해집니다. 기본값은 false입니다.
- title: string (선택) — deprecated 되었습니다. 소스별 툴 표시 메타데이터에는 providerMetadata를 사용하세요.
- needsApproval: boolean | ((input: INPUT, options: { toolCallId: string; messages: ModelMessage[]; context: CONTEXT }) => boolean | Promise<boolean>) (선택) — deprecated 되었습니다. generateText, streamText, ToolLoopAgent에서는 toolApproval로 승인을 구성하세요. 기존 needsApproval 사용은 호환성 폴백으로 여전히 동작합니다. 사용 시 불리언이거나 툴 입력과 타이핑된 context를 포함한 실행 메타데이터를 받는 함수일 수 있습니다.
- inputSchema: Zod Schema | JSON Schema — 툴이 기대하는 입력의 스키마입니다. 언어 모델이 입력을 생성하는 데 사용할 것이며, 언어 모델 출력을 검증하는 데도 사용됩니다. 언어 모델이 이해할 수 있도록 설명(description)을 사용하세요. Zod 스키마 또는 JSON 스키마(jsonSchema 함수 사용) 중 하나를 전달할 수 있습니다.
- inputExamples: Array<{ input: INPUT }> (선택) — 언어 모델에게 입력이 어떤 모습이어야 하는지 보여주는 선택적 입력 예제 목록입니다.
- contextSchema: Zod Schema | JSON Schema (선택) — 툴이 기대하는 툴별 컨텍스트를 설명하는 선택적 스키마입니다. 제공되면 execute, needsApproval 및 입력 라이프사이클 콜백의 context 타입이 이 스키마에서 추론됩니다. 값은 toolsContext의 해당 툴 항목을 통해 공급됩니다.
- strict: boolean (선택) — 툴의 strict 모드 설정입니다. strict 모드를 지원하는 프로바이더는 이 설정을 사용해 입력 생성 방식을 결정합니다. strict 모드는 항상 유효한 입력을 생성하지만 지원되는 입력 스키마가 제한될 수 있습니다.
- execute: async (input: INPUT, options: ToolExecutionOptions<CONTEXT>) => RESULT | Promise<RESULT> | AsyncIterable<RESULT> (선택) — 툴 호출의 인자로 호출되어 결과 또는 결과 이터러블을 생성하는 비동기 함수입니다. 이터러블이 제공되면 마지막 결과를 제외한 모든 결과는 예비(preliminary)로 간주됩니다. 제공되지 않으면 툴은 자동으로 실행되지 않습니다.
  - toolCallId: string — 툴 호출의 ID입니다. 예를 들어 스트림 데이터로 툴 호출 관련 정보를 보낼 때 사용할 수 있습니다.
  - messages: ModelMessage[] — 툴 호출을 포함한 응답을 시작하기 위해 언어 모델로 전송된 메시지들입니다. 시스템 프롬프트와 툴 호출을 포함한 어시스턴트 응답은 포함하지 않습니다.
  - abortSignal: AbortSignal (선택) — 전체 작업이 중단되어야 함을 나타내는 선택적 abort 신호입니다.
  - context: CONTEXT — 툴 실행에 전달되는 툴별 컨텍스트입니다. contextSchema가 제공되면 이 타입은 해당 스키마에서 추론되고 toolsContext의 일치 항목에서 공급됩니다.
  - experimental_sandbox: Experimental_SandboxSession (선택) — 생성 또는 에이전트 호출에서 전달된 선택적 실험적 샌드박스 환경입니다. 툴이 실험적 샌드박스에서 명령이나 코드를 실행해야 할 때 사용하세요.
- outputSchema: Zod Schema | JSON Schema (선택) — 툴이 생성하는 출력의 스키마입니다. 타입 추론에 사용됩니다.
- toModelOutput: ({toolCallId: string; input: INPUT; output: OUTPUT}) => ToolResultOutput | PromiseLike<ToolResultOutput> (선택) — 툴 결과를 언어 모델이 사용할 수 있는 출력으로 매핑하는 선택적 변환 함수입니다. 제공되지 않으면 툴 결과는 JSON 객체로 전송됩니다. 이 함수는 "convertToModelMessages"에 의해 서버에서 호출되므로, 동일한 "tools"(ToolSet)를 "convertToModelMessages"와 "streamText"(또는 다른 생성 API) 모두에 전달해야 합니다.
- onInputStart: (options: ToolExecutionOptions<CONTEXT>) => void | PromiseLike<void> (선택) — 모델이 툴 입력 생성을 시작할 때 호출되는 선택적 함수입니다. 비스트리밍 컨텍스트에서는 onInputAvailable 직전에 호출됩니다.
- onInputDelta: (options: { inputTextDelta: string } & ToolExecutionOptions<CONTEXT>) => void | PromiseLike<void> (선택) — 인자 스트리밍 델타가 준비될 때 호출되는 선택적 함수입니다. 툴이 스트리밍 컨텍스트에서 사용될 때만 호출됩니다.
- onInputAvailable: (options: { input: INPUT } & ToolExecutionOptions<CONTEXT>) => void | PromiseLike<void> (선택) — execute 함수가 제공되지 않아도 툴 호출을 시작할 수 있을 때 호출되는 선택적 함수입니다.
- providerOptions: ProviderOptions (선택) — 추가 프로바이더별 메타데이터입니다. AI SDK에서 프로바이더로 전달되어 프로바이더에 완전히 캡슐화될 수 있는 프로바이더별 기능을 활성화합니다.
- metadata: JSONObject (선택) — 툴 자체에 대한 선택적 메타데이터입니다 (예: 소스). 결과 툴 호출의 toolMetadata로 전파되어 소비자가 툴 호출/결과 파트와 UI 메시지 파트에서 읽을 수 있습니다. 동적 툴의 소스(예: MCP 서버)가 스스로를 식별하는 데 유용합니다.
- type: 'function' | 'dynamic' | 'provider' (선택) — 툴의 유형입니다. 일반 툴은 기본값이 "function"입니다. 런타임에 정의된 툴에는 "dynamic", 프로바이더별 툴에는 "provider"를 사용하세요.
- id: `${string}.${string}` (선택) — 프로바이더 툴의 ID입니다. <provider-name>.<unique-tool-name> 형식을 따라야 합니다. type이 "provider"일 때 필수입니다.
- isProviderExecuted: boolean (선택) — 프로바이더 툴이 프로바이더에 의해 실행되는지 여부입니다. ProviderDefinedTool에는 false, ProviderExecutedTool에는 true로 설정하세요. type이 "provider"일 때 필수입니다.
- args: Record<string, unknown> (선택) — 프로바이더 툴을 구성하는 인자입니다. 이 툴에 대해 프로바이더가 정의한 예상 인자와 일치해야 합니다. type이 "provider"일 때 필수입니다.
- supportsDeferredResults: boolean (선택) — 프로바이더가 실행하는 툴이 현재 응답의 일치하는 툴 호출 없이 도착하는 결과를 지원하는지 여부입니다. ProviderExecutedTool에서만 사용할 수 있습니다.

Returns (반환값)

전달된 툴을 반환합니다.

`tool()`

tool()

본문

Import

API Signature

Parameters (파라미터)

Returns (반환값)

더 알아보기 (Learn more)

`tool()`