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

Выбор модели

Мы рекомендуем использовать последнюю модель Claude Opus (4.6) для сложных инструментов и неоднозначных запросов; она лучше справляется с несколькими инструментами и запрашивает уточнения при необходимости.

Используйте модели Claude Haiku для простых инструментов, но имейте в виду, что они могут выводить отсутствующие параметры.

Указание клиентских инструментов

Клиентские инструменты (как определённые Anthropic, так и определённые пользователем) указываются в параметре tools верхнего уровня запроса API. Каждое определение инструмента включает:

Системный запрос для использования инструментов

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

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}

Лучшие практики для определений инструментов

Чтобы получить лучшую производительность Claude при использовании инструментов, следуйте этим рекомендациям:

• Предоставляйте чрезвычайно подробные описания. Это, безусловно, наиболее важный фактор производительности инструмента. Ваши описания должны объяснять каждую деталь инструмента, включая:
  • Что делает инструмент
  • Когда его следует использовать (и когда не следует)
  • Что означает каждый параметр и как он влияет на поведение инструмента
  • Любые важные предостережения или ограничения, такие как какую информацию инструмент не возвращает, если имя инструмента неясно. Чем больше контекста вы можете дать Claude о ваших инструментах, тем лучше он будет решать, когда и как их использовать. Стремитесь к минимум 3-4 предложениям на описание инструмента, больше, если инструмент сложный.
• Приоритизируйте описания, но рассмотрите использование input_examples для сложных инструментов. Чёткие описания наиболее важны, но для инструментов со сложными входами, вложенными объектами или параметрами, чувствительными к формату, вы можете использовать поле input_examples для предоставления примеров, проверенных по схеме. См. Предоставление примеров использования инструментов для получения подробной информации.

Хорошее описание ясно объясняет, что делает инструмент, когда его использовать, какие данные он возвращает и что означает параметр ticker. Плохое описание слишком краткое и оставляет Claude с множеством открытых вопросов о поведении и использовании инструмента.

Предоставление примеров использования инструментов

Вы можете предоставить конкретные примеры допустимых входов инструментов, чтобы помочь Claude более эффективно понять, как использовать ваши инструменты. Это особенно полезно для сложных инструментов с вложенными объектами, необязательными параметрами или входами, чувствительными к формату.

Базовое использование

Добавьте необязательное поле input_examples в определение вашего инструмента с массивом примеров входных объектов. Каждый пример должен быть действительным в соответствии с input_schema инструмента:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature",
                    },
                },
                "required": ["location"],
            },
            "input_examples": [
                {"location": "San Francisco, CA", "unit": "fahrenheit"},
                {"location": "Tokyo, Japan", "unit": "celsius"},
                {
                    "location": "New York, NY"  # 'unit' is optional
                },
            ],
        }
    ],
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

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

Требования и ограничения

• Проверка схемы - Каждый пример должен быть действительным в соответствии с input_schema инструмента. Недействительные примеры возвращают ошибку 400
• Не поддерживается для серверных инструментов - Только определённые пользователем инструменты могут иметь примеры входов
• Стоимость токенов - Примеры добавляют к токенам запроса: ~20-50 токенов для простых примеров, ~100-200 токенов для сложных вложенных объектов

Средство запуска инструментов (бета)

Средство запуска инструментов предоставляет готовое решение для выполнения инструментов с Claude. Вместо ручного управления вызовами инструментов, результатами и управлением разговором, средство запуска инструментов автоматически:

• Выполняет инструменты, когда Claude их вызывает
• Обрабатывает цикл запроса/ответа
• Управляет состоянием разговора
• Обеспечивает безопасность типов и валидацию

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

Базовое использование

Определите инструменты, используя помощники SDK, затем используйте средство запуска инструментов для их выполнения.

Функция инструмента должна возвращать блок содержимого или массив блоков содержимого, включая текст, изображения или блоки документов. Это позволяет инструментам возвращать богатые, мультимодальные ответы. Возвращённые строки будут преобразованы в блок содержимого текста. Если вы хотите вернуть структурированный объект JSON в Claude, закодируйте его в строку JSON перед возвратом. Числа, логические значения или другие примитивы, не являющиеся строками, также должны быть преобразованы в строки.

Итерация по средству запуска инструментов

Средство запуска инструментов — это итерируемый объект, который выдаёт сообщения от Claude. Это часто называют "циклом вызова инструмента". На каждой итерации средство запуска проверяет, запросил ли Claude использование инструмента. Если да, оно вызывает инструмент и автоматически отправляет результат обратно в Claude, затем выдаёт следующее сообщение от Claude, чтобы продолжить ваш цикл.

Вы можете завершить цикл на любой итерации с помощью оператора break. Средство запуска будет циклически повторяться, пока Claude не вернёт сообщение без использования инструмента.

Если вам не нужны промежуточные сообщения, вы можете получить финальное сообщение напрямую:

Продвинутое использование

В цикле вы можете полностью настроить следующий запрос средства запуска инструментов к Messages API. Средство запуска автоматически добавляет результаты инструментов в историю сообщений, поэтому вам не нужно управлять ими вручную. Вы можете опционально проверить результат инструмента для логирования или отладки и изменить параметры запроса перед следующим вызовом API.

Отладка выполнения инструмента

Когда инструмент выбрасывает исключение, средство запуска инструментов перехватывает его и возвращает ошибку Claude как результат инструмента с is_error: true. По умолчанию включается только сообщение об исключении, а не полная трассировка стека.

Для просмотра полных трассировок стека и информации отладки установите переменную окружения ANTHROPIC_LOG:

# View info-level logs including tool errors
export ANTHROPIC_LOG=info

# View debug-level logs for more verbose output
export ANTHROPIC_LOG=debug

Когда включено, SDK регистрирует полные детали исключения (используя модуль logging Python, консоль в TypeScript или логгер Ruby), включая полную трассировку стека, когда инструмент не работает.

Перехват ошибок инструмента

По умолчанию ошибки инструмента передаются обратно в Claude, который затем может ответить соответствующим образом. Однако вы можете захотеть обнаружить ошибки и обработать их иначе — например, чтобы остановить выполнение рано или реализовать пользовательскую обработку ошибок.

Используйте метод ответа инструмента для перехвата результатов инструмента и проверки ошибок перед их отправкой в Claude:

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

Вы можете изменить результаты инструмента перед их отправкой обратно в Claude. Это полезно для добавления метаданных, таких как cache_control, для включения кэширования запросов на результатах инструмента или для преобразования выходных данных инструмента.

Используйте метод ответа инструмента для получения результата инструмента, его изменения, затем добавления вашей изменённой версии в сообщения:

Потоковая передача

Включите потоковую передачу для получения событий по мере их поступления. Каждая итерация выдаёт объект потока, который вы можете итерировать для получения событий.

Управление выходом Claude

Принудительное использование инструмента

В некоторых случаях вы можете захотеть, чтобы Claude использовал конкретный инструмент для ответа на вопрос пользователя, даже если Claude думает, что может предоставить ответ без использования инструмента. Вы можете сделать это, указав инструмент в поле tool_choice следующим образом:

tool_choice = {"type": "tool", "name": "get_weather"}

При работе с параметром tool_choice у нас есть четыре возможных варианта:

• auto позволяет Claude решить, вызывать ли какие-либо предоставленные инструменты или нет. Это значение по умолчанию, когда предоставлены tools.
• any говорит Claude, что он должен использовать один из предоставленных инструментов, но не принуждает к использованию конкретного инструмента.
• tool позволяет нам принудить Claude всегда использовать конкретный инструмент.
• none предотвращает использование Claude любых инструментов. Это значение по умолчанию, когда tools не предоставлены.

Эта диаграмма иллюстрирует, как работает каждый вариант:

Обратите внимание, что когда у вас есть tool_choice как any или tool, мы предварительно заполним сообщение ассистента, чтобы принудить использование инструмента. Это означает, что модели не будут выдавать естественный языковой ответ или объяснение перед блоками содержимого tool_use, даже если явно об этом попросить.

Наше тестирование показало, что это не должно снижать производительность. Если вы хотите, чтобы модель предоставила естественный языковой контекст или объяснения при этом запрашивая использование конкретного инструмента, вы можете использовать {"type": "auto"} для tool_choice (по умолчанию) и добавить явные инструкции в сообщение user. Например: What's the weather like in London? Use the get_weather tool in your response.

JSON вывод

Инструменты не обязательно должны быть функциями клиента — вы можете использовать инструменты в любое время, когда хотите, чтобы модель возвращала JSON вывод, соответствующий предоставленной схеме. Например, вы можете использовать инструмент record_summary с определённой схемой. Полный рабочий пример см. в разделе Использование инструментов с Claude.

Ответы модели с инструментами

При использовании инструментов Claude часто комментирует свои действия или естественно отвечает пользователю перед вызовом инструментов.

Например, при запросе «Какая погода в Сан-Франциско прямо сейчас и какое там время?» Claude может ответить:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll help you check the current weather and time in San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

Этот естественный стиль ответа помогает пользователям понять, что делает Claude, и создаёт более разговорное взаимодействие. Вы можете направлять стиль и содержание этих ответов через системные подсказки и предоставляя <examples> в ваших подсказках.

Важно отметить, что Claude может использовать различные формулировки и подходы при объяснении своих действий. Ваш код должен рассматривать эти ответы как любой другой текст, сгенерированный ассистентом, и не полагаться на определённые соглашения форматирования.

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

По умолчанию Claude может использовать несколько инструментов для ответа на запрос пользователя. Вы можете отключить это поведение:

• Установив disable_parallel_tool_use=true когда тип tool_choice — auto, что гарантирует, что Claude использует максимум один инструмент
• Установив disable_parallel_tool_use=true когда тип tool_choice — any или tool, что гарантирует, что Claude использует ровно один инструмент

Максимизация параллельного использования инструментов

Хотя модели Claude 4 имеют отличные возможности параллельного использования инструментов по умолчанию, вы можете увеличить вероятность параллельного выполнения инструментов во всех моделях с помощью целевых подсказок:

Обработка блоков содержимого использования инструментов и результатов инструментов

Ответ Claude отличается в зависимости от того, использует ли он клиентский или серверный инструмент.

Обработка результатов от клиентских инструментов

Ответ будет иметь stop_reason равный tool_use и один или несколько блоков содержимого tool_use, которые включают:

• id: Уникальный идентификатор для этого конкретного блока использования инструмента. Это будет использоваться для сопоставления результатов инструментов позже.
• name: Имя используемого инструмента.
• input: Объект, содержащий входные данные, передаваемые инструменту, соответствующие input_schema инструмента.

Когда вы получаете ответ использования инструмента для клиентского инструмента, вы должны:

1. Извлечь name, id и input из блока tool_use.
2. Запустить фактический инструмент в вашей кодовой базе, соответствующий этому имени инструмента, передав входные данные инструмента.
3. Продолжить разговор, отправив новое сообщение с role равным user и блоком content, содержащим тип tool_result и следующую информацию:
   • tool_use_id: id запроса использования инструмента, для которого это результат.
   • content: Результат инструмента в виде строки (например, "content": "15 degrees"), список вложенных блоков содержимого (например, "content": [{"type": "text", "text": "15 degrees"}]) или список блоков документов (например, "content": ["type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}]). Эти блоки содержимого могут использовать типы text, image или document.
   • is_error (опционально): Установите значение true, если выполнение инструмента привело к ошибке.

{"role": "user", "content": [
  {"type": "text", "text": "Here are the results:"},  // ❌ Text before tool_result
  {"type": "tool_result", "tool_use_id": "toolu_01", ...}
]}

{"role": "user", "content": [
  {"type": "tool_result", "tool_use_id": "toolu_01", ...},
  {"type": "text", "text": "What should I do next?"}  // ✅ Text after tool_result
]}

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

Обработка результатов от серверных инструментов

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

Обработка причины остановки max_tokens

Если ответ Claude обрезан из-за достижения лимита max_tokens, и обрезанный ответ содержит неполный блок использования инструмента, вам нужно будет повторить запрос с более высоким значением max_tokens для получения полного использования инструмента.

# Check if response was truncated during tool use
if response.stop_reason == "max_tokens":
    # Check if the last content block is an incomplete tool_use
    last_block = response.content[-1]
    if last_block.type == "tool_use":
        # Send the request with higher max_tokens
        response = client.messages.create(
            model="claude-opus-4-6",
            max_tokens=4096,  # Increased limit
            messages=messages,
            tools=tools,
        )

Обработка причины остановки pause_turn

При использовании серверных инструментов, таких как веб-поиск, API может вернуть причину остановки pause_turn, указывающую, что API приостановил долгоживущий ход.

Вот как обработать причину остановки pause_turn:

import anthropic

client = anthropic.Anthropic()

# Initial request with web search
response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
        }
    ],
    tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
)

# Check if the response has pause_turn stop reason
if response.stop_reason == "pause_turn":
    # Continue the conversation with the paused content
    messages = [
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
        },
        {"role": "assistant", "content": response.content},
    ]

    # Send the continuation request
    continuation = client.messages.create(
        model="claude-3-7-sonnet-latest",
        max_tokens=1024,
        messages=messages,
        tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
    )

    print(continuation)
else:
    print(response)

При обработке pause_turn:

• Продолжите разговор: Передайте приостановленный ответ как есть в последующем запросе, чтобы позволить Claude продолжить свой ход
• Измените при необходимости: Вы можете опционально изменить содержимое перед продолжением, если хотите прервать или перенаправить разговор
• Сохраните состояние инструмента: Включите те же инструменты в запрос продолжения, чтобы сохранить функциональность

Устранение неполадок ошибок

Существует несколько различных типов ошибок, которые могут возникнуть при использовании инструментов с Claude: