Tool use с Claude

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

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

Вот простейший пример с использованием server tool, где выполнение берёт на себя 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-7",
    "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-7 \
  --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-7",
    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-7",
  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);

Как работает tool use

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

Полную концептуальную модель, включая агентский цикл и то, когда выбрать каждый подход, смотрите в How tool use works.

Про подключение к MCP-серверам — см. MCP connector. Про создание собственного MCP-клиента — modelcontextprotocol.io.

Доступ к инструментам — один из самых сильных по отдаче примитивов, которые можно дать агенту. На бенчмарках вроде LAB-Bench FigQA (интерпретация научных иллюстраций) и SWE-bench (реальная разработка ПО) добавление даже базовых инструментов даёт непропорционально большой прирост возможностей, часто превосходящий экспертные базовые показатели людей.

Примеры tool use

Полное практическое руководство — в туториале. Референсные примеры отдельных концепций — в Define tools и Handle tool calls.

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

Цены

Запросы с tool use тарифицируются на основе:

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

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

Дополнительные токены от tool use приходят из:

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

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

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

Текущие цены по моделям — см. сравнительную таблицу моделей.

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

Дальше

Выберите свой путь