Tool Search
Tool Search (툴 검색)
toolSearch()는 모델이 모든 툴의 정의를 초기 컨텍스트에 로드하지 않고 필요한 툴을 찾을 수 있게 해줘요. deferLoading: true로 툴을 등록하세요. 검색이 툴의 이름과 설명을 매칭하고 다음 모델 스텝에서 사용 가능하게 만들어요.
출처: 문서
본문
generateText, streamText, ToolLoopAgent, 또는 @ai-sdk/workflow의 WorkflowAgent와 함께 사용하세요. 팩토리는 인자를 받지 않으며, 모델이 검색 쿼리를 제공해요. WorkflowAgent는 직접 툴 호출을 지원해요. 다른 API들은 캐시를 보존하는 코드 모드도 지원해요.
직접 툴 호출 (Direct Tool Calling)
모델은 처음에 search만 볼 수 있어요. 검색 후 매칭된 정의가 프로바이더의 툴 목록에 추가되고 모델이 그 툴들을 직접 호출해요. 이는 툴 정의를 변경하고 캐시된 프롬프트 접두사를 무효화할 수 있어요.
import { generateText, isStepCount, tool, toolSearch } from 'ai';
import { z } from 'zod/v4';
const weather = tool({
deferLoading: true,
description: 'Get the weather forecast for a city.',
inputSchema: z.object({ city: z.string() }),
execute: async ({ city }) => ({ city, forecast: 'Rain tomorrow.' }),
});
const result = await generateText({
model: __MODEL__,
tools: { search: toolSearch(), weather },
stopWhen: isStepCount(5),
prompt: 'Will it rain in Bangalore tomorrow?',
});
코드 모드 (Code Mode)
코드 모드에서는 모델이 생성된 코드를 통해 툴을 검색하고 호출해요. toolDiscovery: 'conversation'으로 설정하면 프로바이더가 보는 코드 툴은 변경하지 않으면서 사용자 메시지에서 발견된 정의를 알려줘요. 이렇게 하면 툴이 발견되면서 툴 정의 캐시가 보존돼요. 실제 프롬프트 캐시 재사용은 프로바이더에 따라 달라요.
위에서 정의한 weather 툴을 사용해요:
import { experimental_codeModeTool as codeModeTool } from '@ai-sdk/code-mode';
const result = await generateText({
model: __MODEL__,
tools: {
code: codeModeTool({ toolDiscovery: 'conversation' }),
search: toolSearch(),
weather,
},
experimental_toolCallers: {
search: ['code'],
weather: ['code'],
},
stopWhen: isStepCount(5),
prompt: 'Will it rain in Bangalore tomorrow?',
});
모델은 먼저 tools.search({ query: 'weather forecast' })를 실행해요. 다음 스텝에서는 업데이트된 기능 카탈로그를 받고 tools.weather({ city: 'Bangalore' })를 호출할 수 있어요.
두 모드 모두에서 검색은 최대 5개의 매칭을 로드하고, activeTools와 호출자 라우팅을 존중하며, 발견된 툴을 생성이 끝날 때까지 사용 가능하게 유지해요. MCP 클라이언트 툴도 동작해요. client.tools()가 반환한 툴에 deferLoading: true를 추가하세요.
입력, 출력, 매칭 세부사항은 toolSearch() 참조를 참고하세요.