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

Выбор модели

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

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

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

Клиентские инструменты (как Anthropic-schema, так и определяемые пользователем) указываются в параметре 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-7",
    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-schema клиентских инструментах, но не на серверных инструментах, таких как веб-поиск или выполнение кода
• Стоимость токенов - Примеры добавляются к токенам запроса: ~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 может использовать различные формулировки и подходы при объяснении своих действий. Ваш код должен обрабатывать эти ответы как любой другой текст, созданный помощником, и не полагаться на определенные соглашения форматирования.

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