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

​

Выбор модели

В общем случае, используйте Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 или Claude Opus 3 для сложных инструментов и неоднозначных запросов; они лучше справляются с несколькими инструментами и запрашивают уточнения при необходимости.

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

​

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

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

​

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

Когда вы вызываете API Anthropic с параметром 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 предложениям на описание каждого инструмента, больше, если инструмент сложный.
• Отдавайте приоритет описаниям, а не примерам. Хотя вы можете включать примеры использования инструмента в его описание или в сопроводительный промпт, это менее важно, чем наличие четкого и всестороннего объяснения назначения и параметров инструмента. Добавляйте примеры только после того, как вы полностью проработали описание.

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

​

Управление выводом 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, мы предварительно заполним сообщение ассистента, чтобы принудительно использовать инструмент. Это означает, что модели не будут выводить блок содержимого цепочки рассуждений text перед блоками содержимого tool_use, даже если их явно попросили сделать это.

Наше тестирование показало, что это не должно снижать производительность. Если вы хотите сохранить цепочку рассуждений (особенно с Opus), но при этом запрашивать, чтобы модель использовала определенный инструмент, вы можете использовать {"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 Opus 3 будет делать это, если tool_choice установлен на auto (это значение по умолчанию, см. Принудительное использование инструмента), а Sonnet и Haiku можно побудить делать это.

Например, учитывая промпт “What’s the weather like in San Francisco right now, and what time is it there?”, Claude может ответить:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>To answer this question, I will: 1. Use the get_weather tool to get the current weather in San Francisco. 2. Use the get_time tool to get the current time in the America/Los_Angeles timezone, which covers San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

Эта цепочка рассуждений дает представление о процессе рассуждения Claude и может помочь вам отладить неожиданное поведение.

В модели Claude Sonnet 3 цепочка рассуждений по умолчанию менее распространена, но вы можете побудить Claude показать свои рассуждения, добавив что-то вроде "Before answering, explain your reasoning step-by-step in tags." в сообщение пользователя или системный промпт.

Важно отметить, что хотя теги <thinking> являются общепринятым соглашением, которое Claude использует для обозначения своей цепочки рассуждений, точный формат (например, как называется этот XML-тег) может меняться со временем. Ваш код должен рассматривать цепочку рассуждений как любой другой текст, сгенерированный ассистентом, и не полагаться на наличие или конкретное форматирование тегов <thinking>.

​

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

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

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

​

Обработка блоков содержимого tool use и tool result

Ответ 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"}]). Эти блоки содержимого могут использовать типы text или image.
   • is_error (необязательно): Установите значение true, если выполнение инструмента привело к ошибке.

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

​

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

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

​

Обработка причины остановки 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 могут возникнуть несколько различных типов ошибок: