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

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

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

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" \
  -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": "Какая погода в Сан-Франциско?"
      }
    ]
  }'

​

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

Использование инструментов с 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.

​

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

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

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

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

{
  "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 предложениям на описание инструмента, больше, если инструмент сложный.
• Отдавайте приоритет описаниям, а не примерам. Хотя вы можете включить примеры использования инструмента в его описание или в сопроводительный запрос, это менее важно, чем наличие четкого и всеобъемлющего объяснения цели и параметров инструмента. Добавляйте примеры только после того, как полностью проработали описание.

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

{
  "name": "get_stock_price",
  "description": "Получает текущую цену акции для заданного тикера. Тикер должен быть действительным символом для публично торгуемой компании на крупной фондовой бирже США, такой как NYSE или NASDAQ. Инструмент вернет последнюю цену сделки в долларах США. Его следует использовать, когда пользователь спрашивает о текущей или самой последней цене конкретной акции. Он не предоставит никакой другой информации об акции или компании.",
  "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 решает использовать один из предоставленных вами инструментов, он вернет ответ с stop_reason равным tool_use и один или несколько блоков контента tool_use в ответе API, которые включают:

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

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

{
  "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, если выполнение инструмента привело к ошибке.

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

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

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

{
  "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",
      "content": "ConnectionError: сервис погоды недоступен (HTTP 500)",
      "is_error": true
    }
  ]
}

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

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

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

​

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

В некоторых случаях вы можете захотеть, чтобы 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:

{
  "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 попытается использовать инструмент снова с заполненной недостающей информацией:

{
  "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 может ответить:

{
  "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 для решения широкого спектра задач.

​

История версий бета (устаревшее)

Использование инструментов больше не находится в бета-версии и общедоступно с 30 мая 2024 года.

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

​

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

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

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

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

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

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