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

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

Мы рады сообщить, что использование инструментов теперь находится в стадии публичной бета-версии! Чтобы получить доступ к этой функции, вам нужно включить заголовок anthropic-beta: tools-2024-05-16 в ваши запросы к API.

Мы будем дорабатывать эту открытую бета-версию в ближайшие недели, поэтому мы ценим все ваши отзывы. Пожалуйста, поделитесь своими идеями и предложениями, используя эту форму.

Вот пример того, как предоставить инструменты Claude с помощью Messages API:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: tools-2024-05-16" \
  -d '{
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "tools": [
      {
        "name": "get_weather",
        "description": "Получить текущую погоду в указанном месте",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "Город и штат, например, Сан-Франциско, Калифорния"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Какая погода в Сан-Франциско?"
      }
    ]
  }'

Пожалуйста, обратите внимание, что в период бета-тестирования:

  • Хотя функция готова к использованию в продакшене, мы можем представить несколько бета-версий до окончательного релиза.
  • Использование инструментов пока недоступно на сторонних платформах, таких как Vertex AI или AWS Bedrock, но скоро появится. См. Устаревшее использование инструментов для получения рекомендаций о том, как использовать инструменты на Vertex AI и AWS Bedrock прямо сейчас.

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

Использование инструментов с Claude включает следующие шаги:

  1. Предоставьте Claude инструменты и пользовательский запрос: (запрос к API)
    • Определите набор инструментов, к которым вы хотите предоставить доступ Claude, включая их названия, описания и схемы входных данных.
    • Предоставьте пользовательский запрос, который может потребовать использования одного или нескольких из этих инструментов для ответа, например, “Какая погода в Сан-Франциско?“.
  2. Claude использует инструмент: (ответ API)
    • Claude оценивает пользовательский запрос и решает, помогут ли какие-либо из доступных инструментов с запросом или задачей пользователя. Если да, он также решает, какой инструмент(ы) использовать и с какими входными данными.
    • Claude создает правильно отформатированный запрос на использование инструмента.
    • Ответ API будет иметь stop_reason равный tool_use, указывающий, что Claude хочет использовать внешний инструмент.
  3. Извлеките входные данные инструмента, запустите код и верните результаты: (запрос к API)
    • На стороне клиента вы должны извлечь название инструмента и входные данные из запроса Claude на использование инструмента.
    • Запустите фактический код инструмента на стороне клиента.
    • Верните результаты Claude, продолжив разговор с новым сообщением user, содержащим блок контента tool_result.
  4. Claude использует результат инструмента для формулирования ответа: (ответ API)
    • После получения результатов инструмента Claude будет использовать эту информацию для формулирования своего окончательного ответа на исходный пользовательский запрос.

Шаги (3) и (4) являются необязательными - для некоторых рабочих процессов использование инструмента Claude - это вся информация, которая вам нужна, и вам может не потребоваться возвращать результаты инструмента обратно в Claude.

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

Важно отметить, что Claude не имеет доступа к каким-либо встроенным инструментам на стороне сервера. Все инструменты должны быть явно предоставлены вами, пользователем, в каждом запросе к API. Это дает вам полный контроль и гибкость над инструментами, которые может использовать Claude.


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

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

  • name: Название инструмента. Должно соответствовать регулярному выражению ^[a-zA-Z0-9_-]{1,64}$.
  • description: Подробное текстовое описание того, что делает инструмент, когда его следует использовать и как он работает.
  • input_schema: Объект JSON Schema, определяющий ожидаемые параметры для инструмента.

Вот пример простого определения инструмента:

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

Этот инструмент с названием get_weather ожидает входной объект с обязательной строкой location и необязательной строкой unit, которая должна быть либо “celsius”, либо “fahrenheit”.

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

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

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

Вот пример хорошего описания инструмента:

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

В отличие от этого, вот пример плохого описания инструмента:

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

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


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

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

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

Вот пример ответа API с блоком контента tool_use:

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-opus-20240229",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Мне нужно использовать get_weather, и пользователь хочет SF, что, вероятно, означает Сан-Франциско, Калифорния.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "Сан-Франциско, Калифорния", "unit": "celsius"}
    }
  ]
}

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

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

Вот пример возврата успешного результата инструмента:

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

Изображения также поддерживаются в content:

JSON
{
  "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...",
          }
        }
      ]
    }
  ]
}

И вот пример возврата результата ошибки:

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

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

Вы также можете вернуть безошибочный результат инструмента с пустым content, указывающим, что инструмент выполнился успешно без какого-либо вывода:

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

Отличия от других API

Вы можете быть знакомы с другими API, которые возвращают использование инструмента отдельно от основного вывода модели или которые используют специальное сообщение tool или function с role.

В отличие от этого, модели и API Anthropic построены вокруг чередующихся сообщений user и assistant, где каждое сообщение представляет собой массив насыщенных блоков контента: text, image, tool_use и tool_result.

В этом формате сообщения user представляют контент, управляемый клиентской стороной и пользователем/человеком, а сообщения assistant представляют контент, управляемый сервером и ИИ. Таким образом, нет специального сообщения tool или function с role, и вы должны включать блоки tool_result в content ваших сообщений user.


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

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

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

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

Вы также можете указать Claude использовать любой из предоставленных инструментов через {"type": "any"}. По умолчанию tool_choice равен {"type": "auto"}, что позволяет Claude решать, использовать ли инструмент.

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


Вывод JSON

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


Обработка ошибок

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

Ошибка выполнения инструмента

Если сам инструмент выдает ошибку во время выполнения (например, сетевую ошибку при получении данных о погоде), вы можете вернуть сообщение об ошибке в content вместе с "is_error": true:

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

Затем Claude включит эту ошибку в свой ответ пользователю, например: “Извините, я не смог получить текущую погоду, потому что сервис погоды недоступен. Пожалуйста, попробуйте позже.”

Превышено максимальное количество токенов

Если ответ Claude обрезан из-за достижения лимита max_tokens, и усеченный ответ содержит неполный блок использования инструмента, вам нужно будет повторить запрос с более высоким значением max_tokens, чтобы получить полное использование инструмента.

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

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

Однако вы также можете продолжить разговор с tool_result, который указывает на ошибку, и Claude попытается использовать инструмент снова с заполненной недостающей информацией:

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

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

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

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

JSON
{
  "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": "Сан-Франциско, Калифорния"}
    }
  ]
}

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

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

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


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

При использовании инструментов с Claude имейте в виду следующие ограничения и лучшие практики:

  • Используйте Claude 3 Opus для навигации по сложному использованию инструментов, Haiku - если имеете дело с простыми инструментами: Opus способен обрабатывать наибольшее количество одновременных инструментов и лучше справляется с отсутствующими аргументами по сравнению с другими моделями. Он с большей вероятностью запросит уточнение в неоднозначных случаях, когда аргумент явно не указан или когда инструмент может не потребоваться для выполнения запроса пользователя. Haiku по умолчанию пытается использовать инструменты чаще (даже если они не имеют отношения к запросу) и будет выводить отсутствующие параметры, если они не указаны явно.
  • Количество инструментов: Все модели Claude 3 могут поддерживать точность >90% даже при работе с сотнями простых инструментов и меньшим количеством сложных инструментов. “Сложным” инструментом будет тот, который имеет большое количество параметров или параметры со сложными схемами (например, вложенные объекты).
  • Сложные и глубоко вложенные инструменты: Как и человеку, Claude может лучше работать с более простыми интерфейсами и более простыми инструментами. Если Claude испытывает трудности с правильным использованием вашего инструмента, попробуйте упростить схему ввода, отойдя от глубоко вложенных объектов JSON, и уменьшить количество входных данных.
  • Последовательное использование инструментов: Claude обычно предпочитает использовать один инструмент за раз, а затем использовать вывод этого инструмента для информирования о своем следующем действии. Хотя вы можете подсказать Claude использовать несколько инструментов параллельно, тщательно разработав свою подсказку и инструменты, это может привести к тому, что Claude будет заполнять фиктивные значения для параметров, которые зависят от результатов более раннего использования инструмента. Для достижения наилучших результатов разрабатывайте свой рабочий процесс и инструменты так, чтобы вызывать и работать с серией последовательных использований инструментов от Claude.
  • Повторные попытки: Если запрос Claude на использование инструмента недействителен или отсутствуют обязательные параметры, вы можете вернуть ответ об ошибке, и Claude обычно повторит запрос с заполненной недостающей информацией. Однако после 2-3 неудачных попыток Claude может сдаться и вернуть извинения пользователю вместо дальнейших повторных попыток.
  • Отладка: При отладке неожиданного поведения использования инструмента обращайте внимание на вывод цепочки мыслей Claude (если есть), чтобы понять, почему он делает тот или иной выбор. Вы также можете попробовать подсказать Claude использовать определенный инструмент, чтобы посмотреть, привед ет ли это к ожидаемому поведению. Если Claude неправильно использует инструмент, дважды проверьте, что описания и схемы ваших инструментов ясны и однозначны.
  • Теги <search_quality_reflection>: Иногда при использовании инструментов поиска модель может возвращать XML-теги <search_quality_reflection> и оценку качества поиска в своем ответе. Чтобы остановить модель от этого, добавьте предложение “Не отражайте качество возвращенных результатов поиска в своем ответе.” в конец вашей подсказки.

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


История версий бета-версии

  • tools-2024-05-16
    • Изменение системной подсказки для Opus для лучшей обработки сценариев, когда может потребоваться несколько использований инструментов за один ход
  • tools-2024-04-04: Первый выпуск бета-версии для использования инструментов

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

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

Некоторые потенциальные следующие шаги для изучения:

  • Просмотрите наши сборники рецептов по использованию инструментов: изучите наш репозиторий готовых к реализации примеров кода использования инструментов, таких как:
  • Улучшите качество и надежность использования инструментов: Итерируйте и улучшайте описания ваших инструментов и подсказки, чтобы вызвать более надежное и точное использование инструментов от Claude.
  • Расширьте возможности Claude:
    • Экспериментируйте с различными инструментами и схемами, чтобы посмотреть, как Claude обрабатывает различные типы форматов ввода и вывода.
    • Объединяйте несколько инструментов для разбиения сложных задач на серию более простых шагов.
    • Создавайте агентные оркестрации, где Claude может выполнять различные задачи от начала до конца, как если бы он был ассистентом.
    • Исследуйте сложные архитектуры использования инструментов, такие как предоставление Claude инструментов для поиска RAG или вызова субагентов меньших моделей, таких как Haiku, для выполнения задач от его имени.

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

Мы с нетерпением ждем возможности увидеть, как вы используете инструменты, чтобы раздвинуть границы возможного с Claude. Счастливого создания!