도구
도구
대규모 언어 모델(LLMs)은 놀라운 생성 능력을 갖추고 있지만, 수학과 같은 이산적인 작업이나 날씨 정보를 가져오는 것처럼 외부 세계와 상호작용하는 일에는 어려움을 겪어요.
도구(Tools)는 LLM이 호출할 수 있는 동작이에요. 이러한 동작의 결과는 LLM에게 다시 전달되어 다음 응답을 만들 때 참고할 수 있답니다.
예를 들어, LLM에게 "런던의 날씨"를 물어보고 날씨 도구가 준비되어 있다면, LLM은 런던을 인자로 사용해 도구를 호출할 수 있어요. 그러면 도구가 날씨 데이터를 가져와 LLM에게 반환하고, LLM은 이 정보를 바탕으로 응답을 생성할 수 있게 돼요.
출처: 문서
본문
도구란 무엇인가요?
도구는 모델이 특정 작업을 수행하기 위해 호출할 수 있는 객체입니다.
generateText 및
streamText와 함께 tools 매개변수에 하나 이상의 도구를 전달하여 도구를 사용할 수 있습니다.
도구는 세 가지 속성으로 구성됩니다:
description: 도구가 선택되는 시점에 영향을 줄 수 있는 선택적 설명입니다. 함수 도구와 동적 도구는 문자열 또는 도구의 컨텍스트와 실험적 샌드박스에서 설명을 파생하는 함수를 사용할 수 있습니다.inputSchema: 도구 실행에 필요한 입력을 정의하는 Zod 스키마 또는 JSON 스키마입니다. 이 스키마는 LLM이 사용하며, LLM 도구 호출을 검증하는 데도 사용됩니다.execute: 도구 호출의 인수와 함께 호출되는 선택적 비동기 함수입니다.
LLM이 도구를 사용하기로 결정하면 도구 호출을 생성합니다.
execute 함수가 있는 도구는 이러한 호출이 생성될 때 자동으로 실행됩니다.
도구 호출의 출력은 도구 결과 객체를 사용하여 반환됩니다.
다단계 호출을 streamText 및 generateText와 함께 사용하여 도구 결과를 LLM에 자동으로 다시 전달할 수 있습니다.
도구 유형
AI SDK는 각각 다른 장단점을 가진 네 가지 유형의 도구를 지원합니다:
함수 도구
함수 도구는 설명, 입력 스키마, 선택적 실행 함수를 포함하여 완전히 직접 정의하는 도구입니다. 프로바이더에 구애받지 않으며 완전한 제어 권한을 제공합니다.
import { tool } from 'ai';
import { z } from 'zod';
const weatherTool = tool({
description: 'Get the weather in a location',
inputSchema: z.object({
location: z.string().describe('The location to get the weather for'),
}),
execute: async ({ location }) => {
// Your implementation
return { temperature: 72, conditions: 'sunny' };
},
});
언제 사용하나요?: 완전한 제어가 필요하거나, 프로바이더 이식성이 필요하거나, 애플리케이션별 기능을 구현할 때 사용합니다.
동적 도구
동적 도구는 입력 및 출력 유형이 개발 시점에 알려지지 않은 함수 스타일 도구입니다. MCP 서버, 사용자 정의 함수 또는 데이터베이스와 같은 외부 소스에서 로드된 도구에 유용합니다.
import { dynamicTool } from 'ai';
import { z } from 'zod';
const runtimeTool = dynamicTool({
description: 'Execute a tool loaded at runtime',
inputSchema: z.object({}),
execute: async input => {
// input is typed as unknown
return runRuntimeTool(input);
},
});
언제 사용하나요?: 도구가 런타임에 발견되거나 생성되고, 코드를 작성할 때 정확한 TypeScript 입력/출력 유형을 알 수 없을 때 사용합니다.
프로바이더 정의 도구
프로바이더 정의 도구는 프로바이더가 도구의 inputSchema와 description을 지정하지만, execute 함수는 직접 제공하는 도구입니다. 실행이 사용자 측에서 이루어지기 때문에 "클라이언트 도구"라고도 합니다.
예를 들어 Anthropic의 bash 및 text_editor 도구가 있습니다. 모델은 이러한 도구를 효과적으로 사용하도록 특별히 훈련되었으며, 지원되는 작업에서 더 나은 성능을 발휘할 수 있습니다.
import { anthropic } from '@ai-sdk/anthropic';
import { generateText } from 'ai';
const result = await generateText({
model: anthropic('claude-opus-4-5'),
tools: {
bash: anthropic.tools.bash_20250124({
execute: async ({ command }) => {
// Your implementation to run the command
return runCommand(command);
},
}),
},
prompt: 'List files in the current directory',
});
언제 사용하나요?: 프로바이더가 모델이 잘 사용하도록 훈련된 도구를 제공하고, 해당 특정 작업에 대해 더 나은 성능을 원할 때 사용합니다.
프로바이더 실행 도구
프로바이더 실행 도구는 전적으로 프로바이더의 서버에서 실행되는 도구입니다. 설정은 직접 하지만 실행은 프로바이더가 처리합니다. "서버 측 도구"라고도 합니다.
예를 들어 OpenAI의 웹 검색과 Anthropic의 코드 실행이 있습니다. 인프라를 직접 구축할 필요 없이 즉시 사용 가능한 기능을 제공합니다.
import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';
const result = await generateText({
model: openai('gpt-6-astra'),
tools: {
web_search: openai.tools.webSearch(),
},
prompt: 'What happened in the news today?',
});
언제 사용하나요?: 인프라를 직접 관리하지 않고 웹 검색이나 샌드박스 코드 실행과 같은 강력한 기능을 원할 때 사용합니다.
비교
| 항목 | 함수 도구 | 동적 도구 | 프로바이더 정의 도구 | 프로바이더 실행 도구 |
|---|---|---|---|---|
| 실행 | 사용자 코드 | 사용자 코드 | 사용자 코드 | 프로바이더 서버 |
| 스키마 | 사용자 정의 | 런타임 정의 | 프로바이더 정의 | 프로바이더 정의 |
| 이식성 | 모든 프로바이더와 호환 | 모든 프로바이더와 호환 | 프로바이더별 | 프로바이더별 |
| 모델 훈련 | 일반 도구 사용 | 일반 도구 사용 | 도구에 최적화 | 도구에 최적화 |
| 설정 | 모든 것을 직접 구현 | 도구를 로드하거나 생성 | execute 구현 |
설정만 |
스키마
스키마는 도구 입력, 도구 출력 및 구조화된 출력 생성을 정의하고 검증하는 데 사용됩니다.
AI SDK는 다음 스키마를 지원합니다:
- Zod v3 및 v4를 직접 또는
zodSchema()를 통해 사용 @ai-sdk/valibot의valibotSchema()를 통한 Valibot- 표준 JSON 스키마 호환 스키마
jsonSchema()를 통한 원시 JSON 스키마
도구 입력 다듬기
LLM 프로바이더마다 동일한 도구 입력 유형에 대해 약간 다른 도구 입력을 생성할 수 있습니다.
예를 들어, 한 프로바이더는 선택적 필드에 대해 null을 생성하는 반면 다른 프로바이더는 빈 문자열을 생성할 수 있습니다.
타사 패키지의 도구와 같이 도구를 소유하지 않은 경우,
도구의 inputSchema를 변경하여 두 형태를 모두 수용하지 못할 수 있습니다.
이러한 경우 실험적 experimental_refineToolInput 옵션을 사용하여
파싱된 도구 입력이 실행되기 전과 출력, 수명 주기 콜백 및 텔레메트리에 나타나기 전에 정규화할 수 있습니다.
import { generateText, tool } from 'ai';
import { z } from 'zod';
const result = await generateText({
model: 'openai/gpt-6-luna',
tools: {
search: tool({
inputSchema: z.object({
query: z.string(),
category: z.string().nullable(),
}),
execute: async ({ query, category }) => {
return search({ query, category });
},
}),
},
experimental_refineToolInput: {
search: input => ({
...input,
category: input.category === '' ? null : input.category,
}),
},
prompt: 'Search for ski jackets with no category.',
});
다듬기 함수는 도구별로 유형이 지정됩니다. 각 함수는 해당 도구의 유형화된 입력을 받아 동일한 유형 형태의 입력을 반환해야 합니다.
도구 패키지
도구는 JavaScript 객체이므로 다른 라이브러리처럼 npm을 통해 패키징하고 배포할 수 있어요. 덕분에 재사용 가능한 도구를 여러 프로젝트와 커뮤니티에 쉽게 공유할 수 있답니다.
기성 도구 패키지 사용하기
도구 패키지를 설치하고 필요한 도구를 가져오세요:
pnpm add some-tool-package
그런 다음 generateText, streamText 또는 에이전트 정의에 직접 전달하면 돼요:
import { generateText, isStepCount } from 'ai';
import { searchTool } from 'some-tool-package';
const { text } = await generateText({
model: 'anthropic/claude-haiku-4.5',
prompt: 'When was Vercel Ship AI?',
tools: {
webSearch: searchTool,
},
stopWhen: isStepCount(10),
});
나만의 도구 게시하기
다른 사람들이 사용할 수 있도록 나만의 도구 패키지를 npm에 게시할 수 있어요. 패키지에서 도구 객체를 내보내기만 하면 돼요:
import { tool } from 'ai';
import { z } from 'zod';
export const myTool = tool({
description: 'A helpful tool',
inputSchema: z.object({
query: z.string(),
}),
execute: async ({ query }) => {
// your tool logic
return result;
},
});
그러면 누구나 도구를 임포트해서 설치하고 사용할 수 있어요.
시작하려면 AI SDK Tool Package Template을 사용하면 돼요. 이 템플릿은 나만의 도구를 게시하기 위한 바로 사용 가능한 시작점을 제공한답니다.
도구 세트
도구로 작업할 때는 보통 애플리케이션별 도구와 범용 도구를 함께 사용해야 해요. 커뮤니티에서는 도구를 만들고 사용하는 데 도움이 되는 다양한 도구 세트와 리소스를 만들어 두었어요.
바로 사용 가능한 도구 패키지
이 패키지들은 설치하고 바로 사용할 수 있는 미리 만들어진 도구를 제공해요:
- @exalabs/ai-sdk - AI가 웹을 검색하고 실시간 정보를 얻을 수 있게 해주는 웹 검색 도구예요.
- @parallel-web/ai-sdk-tools - Parallel Web API 기반의 웹 검색 및 추출 도구로, 실시간 정보와 콘텐츠 추출을 지원해요.
- @perplexity-ai/ai-sdk - Perplexity의 Search API로 실시간 결과와 고급 필터링을 제공하는 웹 검색 도구예요.
- @tavily/ai-sdk - 엔터프라이즈급 에이전트가 웹을 실시간으로 탐색할 수 있게 해주는 검색, 추출, 크롤링, 맵 도구예요.
- Stripe agent tools - Stripe와 상호작용하기 위한 도구예요.
- StackOne ToolSet - 수백 개의 엔터프라이즈 SaaS 플랫폼을 위한 에이전틱 통합 도구예요.
- agentic - Exa나 E2B 같은 외부 API에 연결되는 20개 이상의 도구 모음이에요.
- Amazon Bedrock AgentCore - Browser(에이전트가 웹 애플리케이션과 상호작용하고, 양식을 작성하고, 웹사이트를 탐색하며, 정보를 추출할 수 있게 해주는 빠르고 안전한 클라우드 기반 브라우저 런타임)와 Code Interpreter(에이전트가 Python, JavaScript, TypeScript로 코드를 실행할 수 있는 격리된 샌드박스 환경으로, 정확성을 높이고 복잡한 엔드투엔드 작업을 해결하는 능력을 확장해 줘요)를 포함한 완전 관리형 AI 에이전트 서비스예요.
- @airweave/vercel-ai-sdk - AI 에이전트를 위해 35개 이상의 데이터 소스(Notion, Slack, Google Drive, 데이터베이스 등)를 통합하는 시맨틱 검색 도구예요.
- Composio - GitHub, Gmail, Salesforce 등 250개 이상의 도구를 제공해요.
- JigsawStack - 특정 용도에 맞게 미세 조정된 30개 이상의 소형 커스텀 모델을 제공해요.
- AI Tools Registry - AI SDK를 위한 Shadcn 호환 도구 정의 및 컴포넌트 레지스트리예요.
- Toolhouse - 25가지 이상의 다양한 작업을 단 3줄의 코드로 구현하는 AI 함수 호출 도구예요.
- bash-tool - AI 에이전트를 위한
bash,readFile,writeFile도구를 제공해요. 완전한 VM 격리를 위해 @vercel/sandbox를 지원한답니다.
MCP 도구
MCP 서버로 제공되는 미리 만들어진 도구들이에요:
- Smithery - Browserbase와 Exa를 포함한 6,000개 이상의 MCP를 제공하는 오픈 마켓플레이스예요.
- Pipedream - 앱이나 AI 에이전트에 3,000개 이상의 통합을 쉽게 추가할 수 있는 개발자 툴킷이에요.
- Apify - Apify는 웹 스크래핑, 데이터 추출, 브라우저 자동화를 위한 수천 개의 도구를 마켓플레이스에서 제공해요.
도구 제작 튜토리얼
이 튜토리얼과 가이드는 특정 서비스와 통합되는 나만의 도구를 만드는 데 도움을 줘요:
- browserbase - 헤드리스 브라우저를 실행하는 브라우저 도구를 만드는 튜토리얼이에요.
- browserless - 브라우저 자동화(자체 호스팅 또는 클라우드 기반)를 통합하는 가이드예요.
- AI Tool Maker - OpenAPI 스펙에서 AI SDK 도구를 생성하는 CLI 유틸리티예요.
- Interlify - API를 도구로 변환하는 가이드예요.
- DeepAgent - Tavily, E2B, Airtable 등 다양한 API와 원활하게 연결되는 50개 이상의 AI 도구 및 통합 모음이에요.
더 알아보기
AI SDK Core의 Tool Calling 및 Agents 문서에서 도구와 도구 호출에 대한 자세한 내용을 확인할 수 있어요.