Claude의 도구 사용(Tool use)

Claude를 외부 도구 및 API와 연결하세요. 도구가 어디에서 실행되는지, 그리고 에이전트 루프가 어떻게 동작하는지 알아봅니다.

도구 사용을 활용하면 Claude가 여러분이 정의한 함수, 또는 Anthropic이 제공하는 함수를 호출할 수 있습니다. Claude는 사용자의 요청과 도구 설명을 바탕으로 언제 도구를 호출할지 스스로 판단한 뒤, 구조화된 호출을 반환합니다. 이 호출은 여러분의 애플리케이션이 실행하거나(클라이언트 도구), Anthropic이 실행합니다(서버 도구).

다음은 Anthropic이 실행을 처리하는 서버 도구를 사용한 가장 간단한 예시입니다.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 1024,
    "tools": [{"type": "web_search_20260209", "name": "web_search"}],
    "messages": [{"role": "user", "content": "What'\''s the latest on the Mars rover?"}]
  }'

ant messages create --transform content --format yaml \
  --model claude-opus-4-8 \
  --max-tokens 1024 \
  --tool '{type: web_search_20260209, name: web_search}' \
  --message '{role: user, content: "What is the latest on the Mars rover?"}'

import anthropic

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[{"type": "web_search_20260209", "name": "web_search"}],
    messages=[{"role": "user", "content": "What's the latest on the Mars rover?"}],
)
print(response.content)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();
const response = await client.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  tools: [{ type: "web_search_20260209", name: "web_search" }],
  messages: [{ role: "user", content: "What's the latest on the Mars rover?" }]
});
console.log(response.content);

using Anthropic;
using Anthropic.Models.Messages;

AnthropicClient client = new();

var parameters = new MessageCreateParams
{
    Model = Model.ClaudeOpus4_8,
    MaxTokens = 1024,
    Tools = [new ToolUnion(new WebSearchTool20260209())],
    Messages = [new() { Role = Role.User, Content = "What's the latest on the Mars rover?" }]
};

var message = await client.Messages.Create(parameters);
Console.WriteLine(message.Content);

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/anthropics/anthropic-sdk-go"
)

func main() {
	client := anthropic.NewClient()

	response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
		Model:     anthropic.ModelClaudeOpus4_8,
		MaxTokens: 1024,
		Tools: []anthropic.ToolUnionParam{
			{OfWebSearchTool20260209: &anthropic.WebSearchTool20260209Param{}},
		},
		Messages: []anthropic.MessageParam{
			anthropic.NewUserMessage(anthropic.NewTextBlock("What's the latest on the Mars rover?")),
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response.Content)
}

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.WebSearchTool20260209;

void main() {
    AnthropicClient client = AnthropicOkHttpClient.fromEnv();

    MessageCreateParams params = MessageCreateParams.builder()
        .model(Model.CLAUDE_OPUS_4_8)
        .maxTokens(1024L)
        .addTool(WebSearchTool20260209.builder().build())
        .addUserMessage("What's the latest on the Mars rover?")
        .build();

    Message response = client.messages().create(params);
    IO.println(response.content());
}

<?php

use Anthropic\Client;

$client = new Client();

$message = $client->messages->create(
    model: 'claude-opus-4-8',
    maxTokens: 1024,
    tools: [
        ['type' => 'web_search_20260209', 'name' => 'web_search'],
    ],
    messages: [
        ['role' => 'user', 'content' => "What's the latest on the Mars rover?"],
    ],
);

echo $message;

require "anthropic"

client = Anthropic::Client.new

message = client.messages.create(
  model: "claude-opus-4-8",
  max_tokens: 1024,
  tools: [{ type: "web_search_20260209", name: "web_search" }],
  messages: [{ role: "user", content: "What's the latest on the Mars rover?" }]
)
puts message.content

도구 사용의 동작 방식

도구는 주로 코드가 어디에서 실행되는가에 따라 구분됩니다. 클라이언트 도구(사용자가 직접 정의한 도구, 그리고 bash나 text_editor처럼 Anthropic 스키마를 따르는 도구 포함)는 여러분의 애플리케이션에서 실행됩니다. 즉, Claude가 stop_reason: "tool_use"와 하나 이상의 tool_use 블록을 응답으로 내놓으면, 여러분의 코드가 해당 작업을 실행한 뒤 tool_result를 되돌려 보냅니다. 반면 서버 도구(web_search, code_execution, web_fetch, tool_search)는 Anthropic의 인프라에서 실행되므로, 여러분이 실행을 직접 처리하지 않고도 결과를 바로 받아볼 수 있습니다.

에이전트 루프를 포함한 전체 개념 모델과 각 방식을 언제 선택해야 하는지에 대해서는 "도구 사용의 동작 방식" 문서를 참고하세요.

MCP 서버에 연결하는 방법은 MCP 커넥터를, 직접 MCP 클라이언트를 만드는 방법은 modelcontextprotocol.io를 참고하세요.

엄격한(strict) 도구 사용으로 스키마 준수 보장하기

도구 정의에 strict: true를 추가하면 Claude의 도구 호출이 항상 여러분의 스키마와 정확히 일치하도록 보장할 수 있습니다. "Strict tool use"를 참고하세요.

도구 접근 권한은 에이전트에게 부여할 수 있는 가장 효과적인 능력 중 하나입니다. LAB-Bench FigQA(과학 도표 해석)나 SWE-bench(실제 소프트웨어 엔지니어링) 같은 벤치마크에서는, 기본적인 도구를 추가하는 것만으로도 성능이 크게 오르며, 인간 전문가 기준선을 넘어서는 경우도 많습니다.

Claude가 도구를 사용하는 시점

tool_choice의 기본값인 {"type": "auto"}를 쓰면, Claude는 매 턴마다 도구를 호출할지 아니면 곧바로 응답할지를 스스로 결정합니다. 요청이 특정 도구가 설명하는 기능에 부합하고, 그 답이 아직 맥락에 들어 있지 않을 때 도구를 호출합니다. 반대로 잘 변하지 않는 지식, 창의적인 작업, 일상적인 대화 같은 경우에는 도구 없이 바로 응답합니다.

이 경계는 시스템 프롬프트를 통해 조정할 수 있습니다. Claude가 기대만큼 도구를 호출하지 않는다면, "Use the tools to investigate before responding."(응답하기 전에 도구로 먼저 조사하라) 같은 가벼운 지시만으로도 도구 사용을 눈에 띄게 늘릴 수 있습니다. "Always call a tool first before responding."(응답하기 전에 항상 도구를 먼저 호출하라)처럼 더 강한 표현을 쓰면 그 경향이 한층 강해집니다. 반대로 "Use your judgment about whether to call a tool or respond directly."(도구를 호출할지 직접 응답할지는 스스로 판단하라)라고 하면 호출 동작을 보수적으로 유지할 수 있습니다.

단순한 유도가 아니라 확실한 보장이 필요하다면 tool_choice를 사용하세요.

각 서버 도구의 문서 페이지에는 해당 도구의 트리거 경계가 더 자세히 설명되어 있습니다. 예로 웹 검색 도구나 코드 실행 도구 문서를 참고하세요.

도구 사용 예시

처음부터 끝까지 직접 따라 해 보는 완전한 실습은 튜토리얼을 참고하세요. 개별 개념에 대한 참고 예시는 "Define tools"와 "Handle tool calls"를 참고하세요.

사용자의 프롬프트에 도구의 필수 매개변수를 모두 채울 만큼 충분한 정보가 들어 있지 않을 때, Claude Opus는 매개변수가 빠졌다는 것을 알아차리고 이를 되묻는 경우가 훨씬 많습니다. Claude Sonnet도 되물을 수 있으며, 특히 도구 요청을 출력하기 전에 생각하도록 프롬프트했을 때 그렇습니다. 다만 Sonnet은 합리적인 값을 추론하려고 최선을 다하기도 합니다.

예를 들어 location 매개변수가 필수인 get_weather 도구가 있을 때, 위치를 지정하지 않고 Claude에게 "날씨가 어때?"라고 물으면, Claude(특히 Claude Sonnet)는 도구 입력값을 추측해 채워 넣을 수 있습니다.

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "get_weather",
  "input": { "location": "New York, NY", "unit": "fahrenheit" }
}

이런 동작이 항상 보장되는 것은 아니며, 프롬프트가 더 모호하거나 모델의 성능이 낮을수록 더욱 그렇습니다. Claude Opus는 필수 매개변수를 채울 만한 맥락이 부족하면, 도구를 호출하기보다 명확히 해 달라고 되묻는 경우가 훨씬 많습니다.

가격

도구 사용 요청의 가격은 다음을 기준으로 책정됩니다.

1. 모델에 전송된 전체 입력 토큰 수(tools 매개변수에 포함된 토큰 포함)
2. 생성된 출력 토큰 수
3. 서버 측 도구의 경우, 사용량 기반의 추가 요금(예: 웹 검색은 수행된 검색 건당 과금)

클라이언트 측 도구는 다른 일반 Claude API 요청과 동일하게 과금되는 반면, 서버 측 도구는 도구별 사용량에 따라 추가 요금이 발생할 수 있습니다.

도구 사용으로 추가되는 토큰은 다음에서 비롯됩니다.

• API 요청의 tools 매개변수(도구 이름, 설명, 스키마)
• API 요청과 응답에 포함된 tool_use 콘텐츠 블록
• API 요청에 포함된 tool_result 콘텐츠 블록

tools를 사용하면, API는 도구 사용을 활성화하는 특수 시스템 프롬프트도 모델에 자동으로 포함시킵니다. 모델별로 필요한 도구 사용 토큰 수는 아래에 정리되어 있습니다(위에서 언급한 추가 토큰은 제외). 이 표는 도구가 최소 1개 제공되었다고 가정합니다. tools를 전혀 제공하지 않으면, 도구 선택값 none은 추가 시스템 프롬프트 토큰을 0개 사용합니다.

이 토큰 수는 일반적인 입력·출력 토큰에 더해져 요청의 총비용에 반영됩니다.

모델별 현재 가격은 모델 개요 표를 참고하세요.

도구 사용 프롬프트를 보내면, 다른 API 요청과 마찬가지로 응답의 usage 지표에 입력 및 출력 토큰 수가 함께 보고됩니다.

다음 단계

• 도구 사용 루프, 도구가 실행되는 위치, 그리고 산문 대신 도구를 사용해야 하는 시점을 이해해 보세요.
• 단일 도구 호출에서 프로덕션 수준의 에이전트 루프까지 안내하는 가이드를 따라가 보세요.
• Anthropic이 제공하는 도구 목록과, 도구 정의 시 선택 가능한 속성에 대한 참고 자료를 확인해 보세요.