Разработка с Claude API

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

Взаимодействие с большими языковыми моделями (LLM), такими как Claude, часто выходит за рамки простого обмена сообщениями. Чтобы Claude мог выполнять сложные задачи, требующие доступа к актуальной информации или внешним системам, мы используем механизм инструментов (tools). Это позволяет Claude "вызывать" функции, которые вы определяете, будь то поиск информации в базе данных, отправка электронного письма или получение текущего времени. Однако сам по себе вызов инструмента — это лишь половина дела. После того как Claude запрашивает использование инструмента, ваша задача — выполнить соответствующую функцию и, что самое главное, отправить результаты обратно. Только так Claude получит необходимую информацию и сможет завершить рабочий процесс, предоставив пользователю осмысленный ответ.

Выполнение функции инструмента

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

Для доступа к параметрам, которые Claude хочет передать вашей функции, вы обычно обращаетесь к свойству input внутри блока ToolUse. Например, если ответ Claude находится в переменной response, параметры могут быть доступны через response.content[1].input. Это свойство возвращает словарь, содержащий аргументы, которые Claude хочет передать вашей функции.

Предположим, у вас есть функция Python, которая ожидает именованные аргументы, например, get_current_datetime(timezone="UTC"). Поскольку Claude передает параметры в виде словаря, вы можете использовать синтаксис распаковки словаря Python (**) для удобной передачи этих аргументов вашей функции. Например:

get_current_datetime(**response.content[1].input)

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

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

После успешного выполнения функции инструмента (или в случае возникновения ошибки) вам необходимо сообщить Claude о результате. Для этого используется специальный блок tool_result, который включается в сообщение пользователя. Этот блок служит мостом между вашей внешней функцией и Claude, информируя модель о том, что произошло во время выполнения инструмента.

Блок tool_result имеет несколько важных свойств, которые обеспечивают правильное сопоставление и интерпретацию результатов:

• tool_use_id: Это свойство является критически важным. Оно должно точно соответствовать id блока ToolUse, который Claude отправил ранее. Это гарантирует, что Claude точно знает, к какому запросу инструмента относится данный результат.
• content: Здесь вы помещаете фактический вывод вашей функции. Этот вывод должен быть сериализован в строку. Например, если ваша функция вернула объект даты и времени, вы преобразуете его в читаемую строку, такую как "15:04:22".
• is_error: Это булево значение (True или False), которое указывает, произошла ли ошибка при выполнении инструмента. Если True, Claude будет знать, что инструмент не смог выполнить свою задачу, и сможет соответствующим образом скорректировать свой ответ.

Этот блок tool_result всегда помещается внутрь сообщения с ролью "user", так как именно пользователь (или система от его имени) предоставляет Claude информацию о внешнем мире.

Обработка нескольких вызовов инструментов

Claude — достаточно умная модель, чтобы понимать сложные запросы. В некоторых случаях он может запросить выполнение нескольких инструментов в одном ответе. Например, если пользователь спрашивает: "Сколько будет 10 + 10 и сколько 30 + 30?", Claude может ответить двумя отдельными блоками ToolUse, каждый из которых запрашивает выполнение функции калькулятора с разными аргументами.

В таких сценариях каждый вызов инструмента получает уникальный идентификатор (id). Крайне важно, чтобы вы сопоставляли эти идентификаторы при отправке результатов обратно. Это гарантирует, что Claude точно знает, какой результат соответствует какому запросу, даже если результаты поступают в другом порядке (например, из-за асинхронного выполнения функций). Правильное сопоставление tool_use_id с id запроса инструмента является залогом корректной работы всего механизма.

Построение последующего запроса к Claude

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

Структура сообщения с результатами инструмента выглядит следующим образом:

messages.append({
    "role": "user",
    "content": [{
        "type": "tool_result",
        "tool_use_id": response.content[1].id, // ID из исходного ToolUse блока
        "content": "15:04:22", // Результат выполнения функции
        "is_error": False // Индикатор ошибки
    }]
})

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

• Исходное сообщение пользователя.
• Сообщение ассистента (Claude) с блоком ToolUse.
• Новое сообщение пользователя с блоком ToolResult.

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

Отправка окончательного запроса и завершение цикла

Когда вы отправляете последующий запрос, содержащий историю сообщений и блок tool_result, важно помнить об одном нюансе: вы должны включить схему инструмента (tool schema) в параметр tools вашего запроса, даже если вы не ожидаете, что Claude сделает еще один вызов инструмента в этом конкретном ответе. Claude нуждается в схеме инструмента, чтобы правильно интерпретировать ссылки на инструменты в вашей истории разговора и полностью понять контекст. Без схемы Claude может "забыть" о возможностях инструмента или неправильно обработать предыдущие упоминания о нем.

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

client.messages.create(
    model=model,
    max_tokens=1000,
    messages=messages, // Полная история сообщений
    tools=[get_current_datetime_schema] // Схема инструмента
)

После получения этого запроса Claude обработает результаты инструмента и сгенерирует окончательный ответ, который будет естественным образом включать полученную информацию. Например, если инструмент вернул текущее время, Claude может ответить: "Текущее время в вашем часовом поясе 15:04:22. Могу ли я еще чем-то помочь?". На этом этапе рабочий процесс использования инструмента считается завершенным: вы успешно позволили Claude получить доступ к реальной информации через вашу пользовательскую функцию и интегрировать ее в осмысленный диалог.