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

Выбор модели

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

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

Определение клиентских инструментов

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

Полный набор необязательных свойств, доступных в любом определении инструмента, включая cache_control, strict, defer_loading и allowed_callers, см. в справочнике по инструментам.

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

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

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 для предоставления примеров, проверенных по схеме. Подробнее см. в разделе Предоставление примеров использования инструментов.
• Объединяйте связанные операции в меньшее число инструментов. Вместо создания отдельного инструмента для каждого действия (create_pr, review_pr, merge_pr) сгруппируйте их в один инструмент с параметром action. Меньшее количество более функциональных инструментов снижает неоднозначность выбора и упрощает для Claude навигацию по набору инструментов.
• Используйте осмысленные пространства имён в именах инструментов. Когда ваши инструменты охватывают несколько сервисов или ресурсов, добавляйте к именам префикс сервиса (например, github_list_prs, slack_send_message). Это делает выбор инструмента однозначным по мере роста вашей библиотеки и особенно важно при использовании поиска инструментов.
• Проектируйте ответы инструментов так, чтобы они возвращали только значимую информацию. Возвращайте семантические, стабильные идентификаторы (например, слаги или UUID), а не непрозрачные внутренние ссылки, и включайте только те поля, которые нужны Claude для рассуждения о следующем шаге. Раздутые ответы расходуют контекст и затрудняют для Claude извлечение важного.

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

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

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

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

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

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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?"}],
)

print(response)

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

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

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

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

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

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

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

Например, на подсказку «What's the weather like in San Francisco right now, and what time is it there?» 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 может использовать различные формулировки и подходы при объяснении своих действий. Ваш код должен обрабатывать эти ответы как любой другой текст, сгенерированный ассистентом, и не полагаться на конкретные соглашения о форматировании.

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