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

Обработка блоков сообщений при работе с инструментами Claude

В процессе разработки приложений с использованием API Claude вы, вероятно, уже привыкли к тому, что ответы модели представляют собой простой текстовый блок. Однако, когда вы начинаете использовать расширенные возможности Claude, такие как интеграция с внешними инструментами (tools), структура ответов модели значительно меняется. Вместо одного текстового блока Claude теперь может возвращать многоблочные сообщения (multi-block messages), которые содержат как обычный текст, так и информацию о вызове инструментов.

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

Выполнение API-запросов с поддержкой инструментов

Чтобы Claude мог использовать внешние инструменты, вам необходимо явно указать их в вашем API-запросе. Это делается с помощью параметра tools, который принимает список JSON schemas. Каждая схема описывает одну функцию, которую Claude потенциально может вызвать, включая ее имя, описание и параметры. Это позволяет модели "понять", какие действия она может предпринять и как их выполнить.

Вот как может выглядеть структура такого запроса:

messages = []
messages.append({
    "role": "user",
    "content": "Какое сейчас точное время в формате ЧЧ:ММ:СС?"
})

response = client.messages.create(
    model=model,
    max_tokens=1000,
    messages=messages,
    tools=[get_current_datetime_schema], # Здесь передается схема инструмента
)

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

Понимание многоблочных сообщений

Когда Claude решает использовать инструмент, он возвращает сообщение от роли assistant, которое содержит несколько блоков в своем списке content. Это существенное отличие от простых текстовых ответов, с которыми вы, возможно, работали ранее. Многоблочное сообщение обычно включает в себя две основные части:

• Человекочитаемый текст: Это объяснение того, что Claude собирается сделать или уже делает. Например: "Я могу помочь вам узнать текущее время. Позвольте мне найти эту информацию для вас." Этот текст предназначен для пользователя и делает взаимодействие более естественным.
• Инструкции для вашего кода: Это структурированная информация о том, какой инструмент необходимо вызвать и какие параметры использовать. Эти инструкции предназначены для вашей программы, а не для конечного пользователя.

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

Структура блока ToolUse

Блок, содержащий инструкции для вызова инструмента, называется блоком ToolUse. Он является частью списка content в ответе Claude и имеет следующую структуру:

• id: Уникальный идентификатор для отслеживания конкретного вызова инструмента. Это полезно для сопоставления вызовов и их результатов.
• name: Имя функции, которую необходимо вызвать (например, "get_current_datetime"). Это имя должно соответствовать имени функции, описанной в JSON schema, которую вы передали в параметре tools.
• input: Входные параметры для функции, отформатированные как словарь. Например, если функция требует город, здесь будет {"city": "New York"}. В случае с get_current_datetime, параметры могут быть пустыми или содержать специфические запросы, если это предусмотрено схемой.
• type: Обозначение типа блока, которое всегда будет "tool_use" для таких блоков.

Примерно так может выглядеть часть ответа Claude, содержащая блок ToolUse:

[
    {
        "type": "text",
        "text": "Я могу помочь вам узнать текущее время. Позвольте мне найти эту информацию для вас."
    },
    {
        "type": "tool_use",
        "id": "toolu_01A0B1C2D3E4F5G6H7I8J9K0L1M2N3O4",
        "name": "get_current_datetime",
        "input": {}
    }
]

Ваша программа должна будет проанализировать этот список content, найти блок с "type": "tool_use", извлечь из него name и input, а затем выполнить соответствующую функцию в вашей серверной части или клиентском приложении.

Управление историей диалога с многоблочными сообщениями

Важно помнить, что Claude, как и большинство современных LLM (Large Language Models), не хранит историю диалога. Вы должны управлять ею вручную, передавая всю необходимую контекстную информацию с каждым новым API-запросом. При работе с ответами, содержащими вызовы инструментов, крайне важно сохранять всю структуру content, включая все блоки, как текстовые, так и ToolUse.

Вот как следует правильно добавлять многоблочное сообщение от assistant в вашу историю диалога:

messages.append({
    "role": "assistant",
    "content": response.content # Сохраняем весь список блоков
})

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

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

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

1. Отправка сообщения пользователя с описанием инструмента: Вы отправляете запрос пользователя в Claude, включая параметр tools со JSON schemas доступных функций.
2. Получение сообщения от ассистента с текстовым блоком и блоком ToolUse: Claude отвечает сообщением, которое содержит как объяснение своих действий, так и инструкции для вызова инструмента.
3. Извлечение информации об инструменте и выполнение фактической функции: Ваша программа парсит ответ Claude, извлекает имя функции и ее параметры из блока ToolUse, а затем вызывает соответствующую функцию в вашей системе.
4. Отправка результата выполнения инструмента обратно в Claude вместе с полной историей диалога: После выполнения функции вы формируете новое сообщение, содержащее результат работы инструмента, и отправляете его Claude, при этом обязательно включая всю предыдущую историю диалога.
5. Получение окончательного ответа от Claude: Claude обрабатывает результат выполнения инструмента и предоставляет окончательный, осмысленный ответ пользователю.

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

Адаптация вспомогательных функций

Если вы использовали вспомогательные функции, такие как add_user_message() или add_assistant_message(), для упрощения работы с историей диалога, вам потребуется обновить их. Предыдущие версии этих функций, вероятно, были разработаны для обработки только одиночных текстовых блоков. Теперь же им необходимо уметь работать с более сложными структурами content, которые могут включать как текстовые блоки, так и блоки ToolUse.

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

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