Использование инструментов (вызов функций)

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

Вот пример того, как предоставить инструменты Claude, используя API сообщений:

​

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

Интегрируйте внешние инструменты с Claude в следующие этапы:

Примечание: Шаги 3 и 4 являются необязательными. Для некоторых рабочих процессов запрос на использование инструмента Claude (шаг 2) может быть всем, что вам нужно, без отправки результатов обратно Claude.

​

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

​

Выбор модели

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

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

​

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

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

{
  "name": "get_weather",
  "description": "Получить текущую погоду в заданном месте",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "Город и штат, например San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "Единица измерения температуры, либо 'celsius', либо 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

​

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

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

В этой среде у вас есть доступ к набору инструментов, которые вы можете использовать для ответа на вопрос пользователя.
{{ ИНСТРУКЦИИ ПО ФОРМАТИРОВАНИЮ }}
Строковые и скалярные параметры должны быть указаны как есть, в то время как списки и объекты должны использовать формат JSON. Обратите внимание, что пробелы для строковых значений не удаляются. Вывод не обязательно должен быть валидным XML и анализируется с помощью регулярных выражений.
Вот доступные функции в формате JSONSchema:
{{ ОПРЕДЕЛЕНИЯ ИНСТРУМЕНТОВ В ФОРМАТЕ JSON SCHEMA }}
{{ СИСТЕМНЫЙ ЗАПРОС ПОЛЬЗОВАТЕЛЯ }}
{{ КОНФИГУРАЦИЯ ИНСТРУМЕНТОВ }}

​

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

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

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

{
  "name": "get_stock_price",
  "description": "Получает текущую цену акций для заданного тикерного символа. Тикерный символ должен быть действительным символом для публично торгуемой компании на основной фондовой бирже США, такой как NYSE или NASDAQ. Инструмент вернет последнюю цену сделки в USD. Его следует использовать, когда пользователь спрашивает о текущей или самой последней цене конкретной акции. Он не предоставит никакой другой информации об акции или компании.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "Тикерный символ акции, например AAPL для Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

{
  "name": "get_stock_price",
  "description": "Получает цену акции для тикера.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

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

​

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

​

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

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

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

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

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

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

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

Наше тестирование показало, что это не должно снижать производительность. Если вы хотите сохранить цепочку рассуждений (особенно с Opus), продолжая запрашивать использование конкретного инструмента, вы можете использовать {"type": "auto"} для tool_choice (по умолчанию) и добавить явные инструкции в сообщение user. Например: Какая погода в Лондоне? Используйте инструмент get_weather в вашем ответе.

​

Вывод JSON

Инструменты не обязательно должны быть кл

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

​

Цепочка рассуждений

При использовании инструментов Claude часто показывает свою “цепочку рассуждений”, т.е. пошаговые рассуждения, которые он использует для разбора проблемы и принятия решения о том, какие инструменты использовать. Модель Claude 3 Opus будет делать это, если tool_choice установлен на auto (это значение по умолчанию, см. Принудительное использование инструмента), а Sonnet и Haiku можно побудить делать это.

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

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Чтобы ответить на этот вопрос, я: 1. Использую инструмент get_weather, чтобы узнать текущую погоду в Сан-Франциско. 2. Использую инструмент get_time, чтобы узнать текущее время в часовом поясе America/Los_Angeles, который охватывает Сан-Франциско, Калифорния.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

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

С моделью Claude 3 Sonnet цепочка рассуждений менее распространена по умолчанию, но вы можете побудить Claude показать свои рассуждения, добавив что-то вроде "Прежде чем отвечать, объясните свои рассуждения пошагово в тегах." в сообщение пользователя или системный запрос.

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

​

Отключение параллельного использования инструментов

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

• Когда тип tool_choice - auto, это гарантирует, что Claude использует максимум один инструмент
• Когда тип tool_choice - any или tool, это гарантирует, что Claude использует ровно один инструмент

​

Обработка блоков контента tool_use и tool_result

Когда Claude решает использовать один из предоставленных вами инструментов, он вернет ответ с stop_reason равным tool_use и одним или несколькими блоками контента tool_use в API-ответе, которые включают:

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

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20241022",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Мне нужно использовать get_weather, и пользователь хочет SF, что, вероятно, означает San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

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

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

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 градусов"
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "15 градусов"},
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRg...",
          }
        }
      ]
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
    }
  ]
}

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

​

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

При использовании инструментов с Claude могут возникнуть несколько типов ошибок:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: сервис погоды недоступен (HTTP 500)",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Ошибка: Отсутствует обязательный параметр 'location'",
      "is_error": true
    }
  ]
}

​

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

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

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20241022",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Мне нужно вызвать функцию get_weather, и пользователь хочет SF, что, вероятно, означает San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20241022",
  "stop_reason": "stop_sequence",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Текущая погода в Сан-Франциско составляет 15 градусов Цельсия (59 градусов Фаренгейта). Прохладный день в городе у залива!"
    }
  ]
}

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "get_weather",
  "input": {"location": "New York, NY", "unit": "fahrenheit"}
}

​

Ценообразование

Запросы на использование инструментов оцениваются так же, как и любой другой запрос API Claude, на основе общего количества входных токенов, отправленных модели (включая параметр tools), и количества сгенерированных выходных токенов.”

Дополнительные токены от использования инструментов происходят из:

• Параметра tools в API-запросах (имена инструментов, описания и схемы)
• Блоков контента tool_use в API-запросах и ответах
• Блоков контента tool_result в API-запросах

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

net (June) | auto

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

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

​

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

Изучите наш репозиторий готовых к реализации примеров кода использования инструментов в наших руководствах: