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

Предварительные требования

• Знакомство с обзором использования инструментов
• Ключ API Claude и рабочая настройка SDK или cURL

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

Клиентские инструменты («client tools») указываются в параметре верхнего уровня tools запроса к API. Клиентские инструменты со схемой Anthropic, такие как инструменты bash и текстового редактора, объявляются с помощью type с версией по дате; поля, которые принимает каждый инструмент, см. на странице соответствующего инструмента, ссылки на которые приведены в Справочнике по инструментам. Инструменты использования компьютера и использования браузера являются клиентскими наборами инструментов: это одна запись без name, которая объявляет фиксированный набор входящих в неё инструментов. Определение пользовательского инструмента включает:

Полный набор необязательных свойств, доступных для любого отдельного определения инструмента, включая cache_control, strict, defer_loading и allowed_callers, см. в Справочнике по инструментам. Запись клиентского набора инструментов принимает cache_control и allowed_callers на уровне записи и задаёт defer_loading для каждого входящего инструмента; см. Клиентские наборы инструментов.

{
  "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, either 'celsius' or 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

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

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

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 извлечение того, что важно.

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

{
  "name": "get_stock_price",
  "description": "Gets the stock price for a ticker.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

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

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

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

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

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    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": "any"} и tool_choice: {"type": "tool", "name": "..."} завершаются ошибкой, тогда как tool_choice: {"type": "auto"} (значение по умолчанию) и tool_choice: {"type": "none"} по-прежнему работают:

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

client = anthropic.Anthropic()

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",
                }
            },
            "required": ["location"],
        },
    }
]

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

print(response)

При работе с параметром 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 может использовать различные формулировки и подходы при объяснении своих действий. Ваш код должен обрабатывать эти ответы как любой другой текст, сгенерированный ассистентом, и не полагаться на конкретные соглашения о форматировании.

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