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

Использование инструментов позволяет Claude вызывать функции, которые определяете вы или которые предоставляет Anthropic. Claude определяет, когда вызвать инструмент, на основе запроса пользователя и описания инструмента. Затем он возвращает структурированный вызов, который выполняет ваше приложение (клиентские инструменты) или Anthropic (серверные инструменты).

Вот минимальный пример с использованием серверного инструмента — инструмента веб-поиска, который 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)

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 не вызывает инструмент в той же группе параллельных вызовов инструментов, что и один из ваших клиентских инструментов (см. Причины остановки и резервное поведение).

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

Для подключения к серверам Model Context Protocol (MCP) см. MCP-коннектор. Для создания собственного MCP-клиента см. руководство Model Context Protocol по созданию MCP-клиента.



Когда 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.

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



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

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



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

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



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

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



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

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



Цены

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

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

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

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

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

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

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

Текущие цены для каждой модели см. в таблице Обзор моделей.

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

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



Дальнейшие шаги