도구 사용이란 무엇인가요?
기존 워크플로우는 프로젝트 관리 소프트웨어, 데이터베이스, 파일 등 다양한 기술에 의존합니다. Claude는 이러한 것들을 직접 확인할 수 없습니다. 대신 Claude는 도구에 의존하며, 이를 통해 외부 데이터와 액션에 접근합니다.
도구란 무엇인가
간단히 말해, 도구는 여러분이 정의하여 Claude에 노출시키는 함수입니다. 도구가 무엇을 하는지, 어떤 입력을 받는지 설명하면, Claude가 언제 이를 호출할지 결정합니다.
여기서 반드시 기억해야 할 핵심은 이것입니다: Claude가 도구를 직접 실행하는 것이 아니라, 여러분의 코드가 실행합니다. 흐름은 다음과 같습니다:
- Claude가 요청합니다 도구 호출을요.
- 여러분의 코드가 실행합니다 해당 함수를요.
- 결과가 다시 Claude에게 전달되고, Claude는 계속 진행합니다.
도구가 정의되는 방식
도구는 세 부분으로 구성된 JSON 스키마입니다: 이름, 설명, 그리고 입력 스키마입니다. 이를 요청 본문에 tools 배열로 전달합니다.
설명은 Claude가 도구를 호출할지 여부를 결정하기 위해 읽는 부분입니다. 설명을 모호하게 작성하면 도구 사용 결과도 나빠집니다. 이는 에이전트가 오작동하거나 사용 가능한 도구를 제대로 활용하지 못하는 가장 큰 원인입니다. 구체적으로 작성하세요.
도구 정의는 다음과 같이 생겼습니다:
{
"name": "lookup_building_code",
"description": "Look up a specific building code section by its identifier. Returns the full text of that code section.",
"input_schema": {
"type": "object",
"properties": {
"section": {
"type": "string",
"description": "The building code section to look up"
}
},
"required": ["section"]
}
}그러면 이를 사용할 때 어떤 일이 일어날까요? 에이전트에게 규정 준수 보고서를 보낸다고 가정해 봅시다. 첫 번째 턴에서 Claude는 stop_reason: "tool_use" 를 반환합니다 — 이것이 우리에게 보내는 신호입니다. 해당 응답은 다음과 같이 생겼습니다:

우리의 루프는 Claude가 요청한 매개변수로 lookup_building_code를 호출한 다음, 결과를 도구 결과로 다시 전달합니다 — 이는 도구 호출의 id와 연결된 tool_result 블록을 담은 사용자 메시지입니다:

그러면 Claude는 계속 진행합니다. 이 시점에서, 우리는 필요한 것을 얻을 때까지 도구를 계속 호출하고 결과를 Claude에 반환할 수 있습니다.
여러 개의 도구: Claude가 선택하도록 하기
도구 하나만으로도 유용하지만, 흥미로운 부분은 Claude에게 여러 개의 도구를 제공하고 Claude가 어떤 순서로 어떤 도구를 선택하는지 지켜보는 것입니다.
다음과 같은 시나리오를 상상해 보세요: 여러분은 덴버로 3일간 여행을 떠나기 위해 짐을 싸고 있고, 오늘의 날씨와 앞으로 며칠간의 예보를 모두 알고 싶어합니다. 그래서 우리는 도구 하나 대신 두 개를 선언합니다:
const tools = [
{
name: "get_weather",
description: "Get today's current weather for a city.",
input_schema: {
type: "object",
properties: {
city: { type: "string", description: "The city to check" }
},
required: ["city"]
}
},
{
name: "get_forecast",
description: "Get the weather forecast for the next few days for a city.",
input_schema: {
type: "object",
properties: {
city: { type: "string", description: "The city to check" }
},
required: ["city"]
}
}
];이 루프는 우리가 이미 본 에이전트 루프와 동일합니다. 유일하게 새로운 부분은 switch 문을 사용해 도구 이름에 따라 분기하는 runTool 함수입니다 — 이 코드 블록이 바로 여러분의 코드가 실제로 실행되는 지점입니다. 여기에는 여러분이 실행해볼 수 있도록 두 개의 하드코딩된 조회와 시작 메시지도 추가되어 있으며, "Your first API call"에서 사용한 client를 그대로 사용합니다:
// 두 개의 하드코딩된 조회입니다. 실제 앱이라면 기상 서비스를 호출했을 것입니다.
const getWeather = (city) => `${city} today: 34F, snow flurries`;
const getForecast = (city) => `${city}, next three days: 38F, 45F, and 52F, sunny`;
const messages = [
{
role: "user",
content:
"I'm packing for a three-day trip to Denver. What's the weather today and over the next few days?",
},
];
function runTool(name, input) {
switch (name) {
case "get_weather":
return getWeather(input.city);
case "get_forecast":
return getForecast(input.city);
}
}
while (true) {
const response = await client.messages.create({
model: "claude-sonnet-5",
max_tokens: 1024,
messages,
tools,
});
if (response.stop_reason !== "tool_use") {
// Claude가 완료됨 — 이것이 최종 답변입니다
for (const block of response.content) {
if (block.type === "text") console.log(block.text);
}
break;
}
messages.push({ role: "assistant", content: response.content });
const toolResults = response.content
.filter((block) => block.type === "tool_use")
.map((block) => ({
type: "tool_result",
tool_use_id: block.id,
content: runTool(block.name, block.input),
}));
messages.push({ role: "user", content: toolResults });
}그리고 그것이 패턴의 전부입니다. 세 번째 도구가 필요하신가요? 배열에 추가하고, switch 문에 case를 추가하면 끝입니다.
이를 실행하면, Claude가 get_weather를 호출한 다음 get_forecast를 호출하는 것을 볼 수 있습니다 — 때로는 같은 턴에서, 때로는 순차적으로요. 그런 다음 Claude는 답변합니다: 겹겹이 입을 것, 오늘은 눈발이 날릴 것, 주중에는 점점 따뜻해질 것이라고요.
이제 Claude가 어떻게 선택했는지 주목해 보세요. Claude는 설명을 읽고, 여러분의 프롬프트를 "오늘의 날씨"와 "앞으로 며칠간"에 매핑한 다음, 각각에 맞는 도구를 선택했습니다. 그렇기 때문에 도구 설명이 정말 중요합니다.
도구 러너: 반복 작업 건너뛰기
여러분은 이미 방금 작성한 코드에서 두 가지 경고 신호를 발견했을 것입니다:
- 단순한 두 개의 조회 작업치고는 코드 양이 너무 많습니다.
- 실제 코드베이스에서는 가지고 있는 모든 함수에 대해 JSON 스키마를 직접 작성하고 싶지 않을 것입니다. 코드를 두 번 작성하는 것과 같으니까요.
바로 이때 도구 러너가 등장합니다. 이는 Claude SDK들에서 베타로 제공됩니다: TypeScript, Python, Ruby, C#, Go, Java, PHP입니다. 각 도구를 한 번만 정의하면, 러너가 내부적으로 전체 도구 사용/도구 결과 루프를 처리합니다.
TypeScript에서는, 러너가 권장하는 헬퍼인 betaZodTool()이 Zod로 작성된 짧은 스키마로 각 도구를 설명합니다. Zod는 데이터의 형태를 선언하고 검증하기 위한 TypeScript 라이브러리입니다. 이 헬퍼는 Zod 3.25.0 이상이 필요하며, 새로 설치하면 해당 버전을 얻을 수 있습니다:
npm install zod여러분의 코드는 다음과 같이 줄어듭니다: 도구를 설명하고, 프롬프트를 보내고, 결과를 기다립니다. 동일한 두 가지 날씨 도구 데모를 도구 러너를 통해 연결한 코드는 다음과 같습니다:
import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod";
import { z } from "zod";
// 직접 실행했던 동일한 두 조회를 짧은 Zod 스키마와 함께 래핑
const weatherTool = betaZodTool({
name: "get_weather",
description: "Get today's current weather for a city.",
inputSchema: z.object({
city: z.string().describe("The city to check"),
}),
run: async ({ city }) => getWeather(city),
});
const forecastTool = betaZodTool({
name: "get_forecast",
description: "Get the weather forecast for the next few days for a city.",
inputSchema: z.object({
city: z.string().describe("The city to check"),
}),
run: async ({ city }) => getForecast(city),
});
const runner = client.beta.messages.toolRunner({
model: "claude-sonnet-5",
max_tokens: 1024,
messages: [
{
role: "user",
content:
"I'm packing for a three-day trip to Denver. What's the weather today and over the next few days?",
},
],
tools: [weatherTool, forecastTool],
});
// 도구 핑퐁이 모두 정리된 후 최종 메시지를 받기 위해 runner를 await
const finalMessage = await runner;
for (const block of finalMessage.content) {
if (block.type === "text") console.log(block.text);
}동일한 시나리오지만, 코드 양은 훨씬 적습니다:
- while 루프도 없고, stop reason을 확인하는 switch 문도 없으며, 도구 결과를 수동으로 메시지에 다시 넣을 필요도 없습니다 — 러너가 이 모든 것을 처리합니다.
- 직접 작성한 JSON 스키마도 없고, 각 도구당 짧은 Zod 스키마만 있을 뿐이며, 이는 Claude가 보낸 입력도 검증합니다.
- 각
run함수는 우리가 조금 전 직접 실행했던 것과 동일한 조회 작업을 감싸고 있습니다. - 러너를 await하면 모든 것이 정리된 후 최종 어시스턴트 메시지가 반환됩니다.
실행해 보면, 동일한 답을 얻을 수 있습니다.
실제 도구는 기존 코드를 감쌉니다
실제 상황에서는, 도구가 하드코딩된 날씨 데이터는 아닐 것입니다. 대신 여러분의 애플리케이션에 이미 존재하는 실제 함수를 감싸게 될 것입니다.
규정 준수 검토 에이전트를 예로 들어보겠습니다. 이 에이전트의 도구는 코드베이스에 이미 존재하는 lookup_building_code와 search_building_code 함수를 얇게 감싼 래퍼입니다. 도구 러너를 사용하면, 각 함수를 자체 Zod 스키마를 가진 짧은 도구 정의로 감싸게 되고, 에이전트는 작성하는 모든 발견 사항에서 구체적인 법규 조항을 인용하게 됩니다:

요약
- 도구는 Claude에게 여러분의 시스템에 대한 접근 권한을 부여합니다. 도구는 여러분이 정의하여 노출시키는 함수입니다. Claude는 언제 이를 호출할지 결정하고, 여러분의 코드가 이를 실행합니다.
- 도구는 이름, 설명, 입력 스키마로 구성된 JSON 스키마이며, 요청에서
tools배열로 전달됩니다. - 구체적인 설명을 작성하세요. 모호한 설명은 에이전트가 오작동하는 가장 큰 원인입니다.
stop_reason: "tool_use"는 도구를 실행하고 결과를 도구 결과로 다시 전달하라는 신호입니다.- 여러 개의 도구를 사용할 경우, 도구 이름에 따라 분기하세요. 도구를 추가한다는 것은 배열에 추가하고 case를 추가한다는 의미입니다.
- SDK의 도구 러너(모든 Claude SDK에서 베타로 제공됨)는 전체 루프를 처리하며, TypeScript에서는 각 도구가 Zod 스키마를 가진 짧은 정의로 표현됩니다. 혹은 직접 루프를 실행할 수도 있습니다.
- 여러분이 직접 실행하거나, 혹은 루프를 위임할 수 있습니다. 그 스펙트럼의 가장 끝에서는, 관리형 에이전트가 전체 에이전트를 Anthropic에 위임합니다.