Использование инструментов с Claude
Подключите Claude к внешним инструментам и API. Узнайте, где выполняются инструменты, когда Claude их вызывает и какой инструмент подходит для вашей задачи.
«Tool use» (использование инструментов), также называемое «function calling» (вызов функций), позволяет Claude вызывать функции, которые определяете вы или которые предоставляет Anthropic. Claude определяет, когда вызывать инструмент, на основе запроса пользователя и описания инструмента. Затем он возвращает структурированный вызов, который выполняет ваше приложение (клиентские инструменты) или Anthropic (серверные инструменты).
Вот минимальный пример с использованием серверного инструмента веб-поиска, который Anthropic выполняет за вас:
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
tools=[{"type": "web_search_20260209", "name": "web_search"}],
messages=[{"role": "user", "content": "What is 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.В разделе Обработка вызовов инструментов подробно рассматривается каждый шаг, включая форматирование результатов и сигнализацию об ошибках; в разделе Параллельное использование инструментов рассматриваются ответы, которые вызывают несколько инструментов одновременно. Чтобы не писать этот цикл самостоятельно, используйте исполнитель инструментов: 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.
Страница каждого серверного инструмента более подробно описывает его собственную границу срабатывания.
Если подсказка пользователя не содержит достаточно информации для заполнения всех обязательных параметров инструмента, Claude Opus с гораздо большей вероятностью распознает, что параметр отсутствует, и запросит его. Claude Sonnet может спросить, особенно если ему предложено подумать перед выводом запроса инструмента. Но он также может вывести разумное значение самостоятельно.
Например, при наличии инструмента get_weather, требующего параметр location, если вы спросите Claude «Какая погода?», не указав местоположение, Claude (особенно Claude Sonnet) может угадать значения, которые вы не предоставили:
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_weather",
"input": { "location": "New York, NY", "unit": "fahrenheit" }
}Такое поведение не гарантируется, особенно для более неоднозначных подсказок и менее способных моделей.
Выбор инструмента
Строки type, версии и бета-заголовки см. в Справочнике по инструментам.
Ваши собственные инструменты
Для инструментов, которые вы определяете, вы пишете схему, а ваше приложение выполняет каждый вызов.
Задавайте схемы инструментов, пишите описания и управляйте тем, когда Claude вызывает ваши инструменты.
Разбирайте блоки tool_use, форматируйте ответы tool_result и обрабатывайте ошибки.
Клиентские инструменты со схемой Anthropic
Anthropic публикует схему и обучает на ней Claude. Ваше приложение по-прежнему выполняет каждый вызов и возвращает tool_result.
Сохраняйте и извлекайте информацию между разговорами в файлах, которые вы контролируете.
Выполняйте команды оболочки в постоянном сеансе, сохраняющем состояние.
Просматривайте и изменяйте текстовые файлы для отладки, исправления и улучшения кода.
Делайте снимки экрана и управляйте мышью и клавиатурой в среде рабочего стола.
Перемещайтесь по веб-страницам, читайте их и взаимодействуйте с ними в вашей собственной браузерной среде.
Серверные инструменты
Серверные инструменты выполняются на инфраструктуре Anthropic без кода обработчиков в вашем приложении. Общие для них механизмы см. в разделе Серверные инструменты.
Ищите в интернете информацию за пределами даты отсечения знаний, с цитируемыми источниками.
Получайте полное содержимое указанных веб-страниц и PDF-документов.
Выполняйте код Python и Bash в изолированном контейнере для анализа данных и создания файлов.
Позвольте более быстрой модели-исполнителю консультироваться с более интеллектуальной моделью-советником в процессе генерации.
Работайте с тысячами инструментов, обнаруживая и загружая их по требованию.
Подключайтесь к удалённым серверам MCP из Messages API без отдельного клиента MCP.
Цены
Запросы с использованием инструментов (tool use) тарифицируются на основе:
- Общего количества входных токенов, отправленных модели (включая параметр
tools). - Количества сгенерированных выходных токенов.
- Для серверных инструментов — дополнительной тарификации на основе использования (например, веб-поиск взимает плату за каждый выполненный поиск).
Клиентские инструменты тарифицируются так же, как и любой другой запрос к Claude API, хотя серверные инструменты могут повлечь дополнительные расходы в зависимости от их конкретного использования.
Дополнительные токены при использовании инструментов возникают из:
- Параметра
toolsв запросах API (имена инструментов, описания и схемы) - Блоков содержимого
tool_useв запросах и ответах API - Блоков содержимого
tool_resultв запросах API
Когда вы используете tools, API также автоматически включает специальную системную подсказку (system prompt) для модели, которая обеспечивает использование инструментов. В следующей таблице указано количество токенов использования инструментов, которое требуется каждой модели (без учёта дополнительных токенов, перечисленных выше). Таблица предполагает, что вы предоставляете как минимум один инструмент. Если вы не предоставляете tools, то выбор инструмента none использует 0 дополнительных токенов системной подсказки.
| Модель | Токены системного промпта при использовании инструментов | |
|---|---|---|
| Название | Количество токенов | |
Claude Opus 5.5For long-running agentic coding and knowledge work | auto, none | 286 токенов |
Claude Sonnet 5.5The best combination of speed and intelligence | auto, none | 286 токенов |
Claude Haiku 5.5For high-volume, latency-sensitive tasks such as classification, extraction, and routing | auto, none | 286 токенов |
any, tool | 406 токенов | |
auto, none | 286 токенов | |
any, tool | 406 токенов | |
auto, none | 290 токенов | |
any, tool | 410 токенов | |
auto, none | 675 токенов | |
any, tool | 804 токенов | |
auto, none | 497 токенов | |
any, tool | 589 токенов | |
auto, none | 496 токенов | |
any, tool | 588 токенов | |
Claude Opus 4.1 | auto, none | 313 токенов |
any, tool | 315 токенов | |
Claude Opus 4 | auto, none | 313 токенов |
any, tool | 315 токенов | |
auto, none | 354 токенов | |
any, tool | 474 токенов | |
auto, none | 497 токенов | |
any, tool | 589 токенов | |
auto, none | 496 токенов | |
any, tool | 588 токенов | |
Claude Sonnet 4 | auto, none | 313 токенов |
any, tool | 315 токенов | |
auto, none | 496 токенов | |
any, tool | 588 токенов | |
Эти количества токенов добавляются к вашим обычным входным и выходным токенам для расчёта общей стоимости запроса.
Актуальные цены по моделям см. в таблице Все модели.
Когда вы отправляете подсказку с использованием инструментов, как и при любом другом запросе API, ответ включает количество как входных, так и выходных токенов в сообщаемых метриках usage.
Некоторые серверные инструменты добавляют плату за использование сверх токенов: их тарифы см. в разделах Использование и цены инструмента веб-поиска и Использование и цены инструмента выполнения кода.
Следующие шаги
Разберитесь в цикле использования инструментов, в том, где выполняются инструменты и когда использовать инструменты вместо текстового ответа.
Пошаговое руководство от одного вызова инструмента до готового к продакшену агентного цикла.
Каталог инструментов, предоставляемых Anthropic, и справочник по необязательным свойствам определения инструментов.
Эта страница была полезной?