Использование инструментов с Claude

«Tool use» (использование инструментов), также называемое «function calling» (вызов функций), позволяет Claude вызывать функции, которые определяете вы или предоставляет Anthropic. Claude решает, когда вызвать инструмент, исходя из запроса пользователя и описания инструмента. Затем он возвращает структурированный вызов, который выполняет ваше приложение («client tools», клиентские инструменты) или Anthropic («server tools», серверные инструменты).

Вот минимальный пример с серверным инструментом — инструментом веб-поиска, который Anthropic выполняет за вас:

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-5-5",
    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)

Claude выполняет поиск в инфраструктуре Anthropic и возвращает результаты с цитатами в том же ответе. Чтобы Claude вызвал функцию, которую определяете вы, передайте инструмент с input_schema, а затем выполните вызов, когда Claude вернёт блок tool_use. В разделе Как работает использование инструментов этот полный цикл обмена показан от начала до конца. Узнайте больше об определении инструментов и обработке вызовов инструментов.

Как работает использование инструментов

Инструменты различаются прежде всего тем, где выполняется код. Клиентские инструменты (включая пользовательские инструменты и инструменты со схемами, определёнными Anthropic, такие как bash и text_editor) выполняются в вашем приложении. Claude отвечает с stop_reason: "tool_use" и одним или несколькими блоками tool_use. Ваш код выполняет операцию и отправляет обратно tool_result. Серверные инструменты (такие как web_search, web_fetch, code_execution и tool_search) выполняются в инфраструктуре Anthropic: вы получаете результаты напрямую, не занимаясь выполнением, если только Claude не вызывает инструмент в той же группе параллельных вызовов инструментов, что и один из ваших клиентских инструментов (см. Причины остановки и резервные варианты).

Вот этот цикл обмена целиком для клиентского инструмента. Первый запрос определяет инструмент get_weather, и Claude отвечает на вопрос, вызывая его: ответ содержит блок tool_use, ваш код выполняет поиск данных, а второй запрос отправляет результат обратно в блоке tool_result, чтобы Claude мог дать ответ.

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a given location.",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    }
]
messages = [{"role": "user", "content": "What's the weather in San Francisco?"}]

# Claude отвечает блоком tool_use с именем инструмента и его аргументами.
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=tools,
    # Запрашивайте не более одного вызова инструмента за ход.
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages,
)
tool_use = next(block for block in response.content if block.type == "tool_use")
print(f"Claude called {tool_use.name} with {json.dumps(tool_use.input)}")

# Выполните инструмент, затем отправьте результат обратно в блоке tool_result.
weather = "15 degrees Celsius, partly cloudy"  # your weather lookup goes here
messages += [
    {"role": "assistant", "content": response.content},
    {
        "role": "user",
        "content": [
            {"type": "tool_result", "tool_use_id": tool_use.id, "content": weather}
        ],
    },
]
followup = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages,
)

# Claude использует результат, чтобы ответить на исходный вопрос.
final_text = next(block for block in followup.content if block.type == "text")
print(final_text.text)

Claude called get_weather with {"location": "San Francisco, CA"}
The current weather in San Francisco is 15 degrees Celsius with partly cloudy skies.

В разделе Обработка вызовов инструментов подробно рассматривается каждый шаг, включая форматирование результатов и сигнализацию об ошибках; в разделе Параллельное использование инструментов рассматриваются ответы, в которых вызывается сразу несколько инструментов. Чтобы не писать этот цикл обмена самостоятельно, используйте Tool Runner: SDK выполняют ваши инструменты и автоматически отправляют результаты обратно.

Полную концептуальную модель, включая «agentic loop» (агентный цикл) и рекомендации по выбору каждого подхода, см. в разделе Как работает использование инструментов.

Чтобы подключиться к серверам «Model Context Protocol», или MCP, см. коннектор MCP. Чтобы создать собственный клиент MCP, см. руководство Model Context Protocol по созданию клиента MCP.

Когда Claude использует инструменты

При значении tool_choice по умолчанию {"type": "auto"} Claude на каждом ходе определяет, вызвать ли инструмент или ответить напрямую. Он вызывает инструмент, когда запрос соответствует описанной возможности этого инструмента, а ответа ещё нет в контексте. Он отвечает напрямую в случае устойчивых знаний, творческих задач и разговорных реплик.

Эту границу можно регулировать через вашу «system prompt» (системную подсказку). Если 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.

Страница каждого серверного инструмента более подробно описывает его собственную границу срабатывания.

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

Выбор инструмента

Строки type, версии и бета-заголовки см. в Справочнике по инструментам.

Ваши собственные инструменты

Для инструментов, которые определяете вы, вы пишете схему, а ваше приложение выполняет каждый вызов.

Клиентские инструменты со схемой Anthropic

Anthropic публикует схему и обучает Claude на ней. Ваше приложение по-прежнему выполняет каждый вызов и возвращает tool_result.

Серверные инструменты

Серверные инструменты выполняются на инфраструктуре Anthropic без кода обработчиков в вашем приложении. Общие для них механизмы см. в разделе Серверные инструменты.

Цены

Запросы с использованием инструментов (tool use) тарифицируются на основе:

1. Общего количества входных токенов, отправленных модели (включая параметр tools)
2. Количества сгенерированных выходных токенов
3. Для серверных инструментов — дополнительной тарификации на основе использования (например, веб-поиск взимает плату за каждый выполненный поиск)

Клиентские инструменты тарифицируются так же, как и любой другой запрос к Claude API, хотя серверные инструменты могут повлечь дополнительные расходы в зависимости от их конкретного использования.

Дополнительные токены при использовании инструментов возникают из:

• Параметра tools в запросах API (имена инструментов, описания и схемы)
• Блоков содержимого tool_use в запросах и ответах API
• Блоков содержимого tool_result в запросах API

Когда вы используете tools, API также автоматически включает специальную системную подсказку (system prompt) для модели, которая обеспечивает использование инструментов. Количество токенов использования инструментов, необходимое для каждой модели, указано в следующей таблице (без учёта дополнительных токенов, перечисленных выше). Обратите внимание, что таблица предполагает, что предоставлен как минимум 1 инструмент. Если tools не предоставлены, то выбор инструмента none использует 0 дополнительных токенов системной подсказки.

Model	Tool use system prompt tokens
Name	Tool choice	Token count
Claude Opus 5.5For long-running agentic coding and knowledge work	auto, none	286 tokens
Claude Sonnet 5.5The best combination of speed and intelligence	auto, none	286 tokens
Claude Haiku 4.5The fastest model with near-frontier intelligence	auto, none	496 tokens
	any, tool	588 tokens
Additional models
Claude Opus 5	auto, none	286 tokens
	any, tool	406 tokens
Claude Opus 4.8	auto, none	290 tokens
	any, tool	410 tokens
Claude Opus 4.7	auto, none	675 tokens
	any, tool	804 tokens
Claude Opus 4.6	auto, none	497 tokens
	any, tool	589 tokens
Claude Opus 4.5	auto, none	496 tokens
	any, tool	588 tokens
Claude Opus 4.1	auto, none	313 tokens
	any, tool	315 tokens
Claude Opus 4	auto, none	313 tokens
	any, tool	315 tokens
Claude Sonnet 5	auto, none	354 tokens
	any, tool	474 tokens
Claude Sonnet 4.6	auto, none	497 tokens
	any, tool	589 tokens
Claude Sonnet 4.5	auto, none	496 tokens
	any, tool	588 tokens
Claude Sonnet 4	auto, none	313 tokens
	any, tool	315 tokens
Claude Haiku 3.5	auto, none	264 tokens
	any, tool	355 tokens

Эти количества токенов добавляются к вашим обычным входным и выходным токенам для расчёта общей стоимости запроса.

Актуальные цены по моделям см. в таблице Обзор моделей.

Когда вы отправляете подсказку с использованием инструментов, как и при любом другом запросе API, ответ включает количество как входных, так и выходных токенов в сообщаемых метриках usage.

Некоторые серверные инструменты добавляют плату на основе использования сверх токенов: их тарифы см. в разделах Инструмент веб-поиска и Инструмент выполнения кода.

Следующие шаги