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

Реализация многоходовых диалогов с использованием инструментов Claude

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

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

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

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

Например, в коде это может выглядеть так:

if response.stop_reason != "tool_use":
    # Claude завершил работу, инструменты больше не нужны, можно выводить финальный ответ
    break 

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

Цикл диалога

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

1. Отправка сообщения и инструментов: В начале каждого хода мы отправляем текущий контекст диалога (историю сообщений) и список доступных инструментов Claude.
2. Получение ответа от Claude: Claude обрабатывает запрос и возвращает ответ, который может содержать текст, запросы на использование инструментов или и то, и другое.
3. Проверка на использование инструментов: Мы проверяем поле stop_reason в ответе Claude.
4. Выполнение инструментов: Если stop_reason равен "tool_use", это означает, что Claude запросил один или несколько инструментов. Система должна выполнить эти инструменты.
5. Отправка результатов инструментов обратно: Результаты выполнения инструментов форматируются и отправляются обратно Claude как часть нового сообщения пользователя, чтобы модель могла использовать их для продолжения диалога.
6. Повторение: Цикл повторяется, пока Claude не вернет ответ, в котором stop_reason не равен "tool_use", что сигнализирует об окончательном ответе.

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

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

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

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

Структура блока tool_result включает:

• "type": "tool_result": указывает тип блока.
• "tool_use_id": tool_request.id: уникальный идентификатор, связывающий результат с конкретным запросом инструмента.
• "content": json.dumps(tool_output): фактический результат работы инструмента, обычно в формате JSON.
• "is_error": False: флаг, указывающий, была ли ошибка при выполнении инструмента.

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

Надежное выполнение инструментов и обработка ошибок

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

Для этого используется конструкция try-except. Если выполнение инструмента завершается успешно, мы создаем блок tool_result с "is_error": False и фактическим результатом. Если же возникает исключение, мы создаем блок tool_result с "is_error": True и сообщением об ошибке в поле content. Это позволяет Claude получить обратную связь о неудаче и, возможно, предпринять альтернативные действия или сообщить пользователю о проблеме.

try:
    tool_output = run_tool(tool_request.name, tool_request.input)
    tool_result_block = {
        "type": "tool_result",
        "tool_use_id": tool_request.id,
        "content": json.dumps(tool_output),
        "is_error": False
    }
except Exception as e:
    tool_result_block = {
        "type": "tool_result",
        "tool_use_id": tool_request.id,
        "content": f"Error: {e}",
        "is_error": True
    }

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

Масштабируемая маршрутизация инструментов

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

def run_tool(tool_name, tool_input):
    if tool_name == "get_current_datetime":
        return get_current_datetime(**tool_input)
    elif tool_name == "another_tool":
        return another_tool(**tool_input)
    # Добавляйте больше инструментов по мере необходимости
    else:
        raise ValueError(f"Unknown tool: {tool_name}")

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

Полный рабочий процесс многоходового диалога

Итак, полный многоходовый диалог с использованием инструментов работает следующим образом:

1. Пользователь отправляет сообщение в систему.
2. Система отправляет сообщение пользователя Claude вместе со схемами всех доступных инструментов.
3. Claude обрабатывает запрос и отвечает либо текстом, либо запросами на использование одного или нескольких инструментов (или и тем, и другим).
4. Если Claude запросил инструменты, система выполняет все запрошенные инструменты и формирует соответствующие блоки результатов (tool_result).
5. Система отправляет эти блоки результатов обратно Claude как часть нового сообщения пользователя в истории диалога.
6. Шаги 3-5 повторяются до тех пор, пока Claude не предоставит окончательный ответ, который не содержит запросов на использование инструментов.
7. Система выводит окончательный ответ Claude пользователю.

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

Заключение

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