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

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

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

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-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",
    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",
    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 выполняют ваши инструменты и автоматически отправляют результаты обратно.

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

Для подключения к серверам 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. Для серверных инструментов — дополнительной тарификации на основе использования (например, веб-поиск тарифицируется за каждый выполненный поиск)

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

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

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

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

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

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

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

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



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