Tool Runner (SDK)

Tool Runner обрабатывает цикл агента, обёртывание ошибок и безопасность типов, чтобы вам не пришлось это делать. Используйте ручной цикл только когда вам нужно одобрение человека в цикле, пользовательское логирование или условное выполнение. Доступен в Python, TypeScript и Ruby SDK.

Tool Runner предоставляет готовое решение для выполнения инструментов с Claude. Вместо ручной обработки вызовов инструментов, результатов инструментов и управления беседой, tool runner автоматически:

Выполняет инструменты, когда Claude их вызывает
Обрабатывает цикл запроса/ответа
Управляет состоянием беседы
Обеспечивает безопасность типов и валидацию

Используйте tool runner для большинства реализаций использования инструментов.

Tool Runner в настоящее время находится в бета-версии и доступен в Python, TypeScript и Ruby SDK.

Автоматическое управление контекстом с компактификацией

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

Базовое использование

Определите инструменты, используя помощники SDK, затем используйте tool runner для их выполнения.

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

Итерация по tool runner

Tool Runner — это итерируемый объект, который выдаёт сообщения от Claude. Это часто называют «циклом вызова инструмента». На каждой итерации runner проверяет, запросил ли Claude использование инструмента. Если да, он вызывает инструмент и автоматически отправляет результат обратно в Claude, затем выдаёт следующее сообщение от Claude для продолжения вашего цикла.

Вы можете завершить цикл на любой итерации с помощью оператора break. Runner будет циклиться до тех пор, пока Claude не вернёт сообщение без использования инструмента.

Если вам не нужны промежуточные сообщения, вы можете получить финальное сообщение напрямую:

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

В цикле вы можете полностью настроить следующий запрос tool runner к Messages API. Runner автоматически добавляет результаты инструментов в историю сообщений, поэтому вам не нужно управлять ими вручную. Вы можете опционально проверить результат инструмента для логирования или отладки и изменить параметры запроса перед следующим вызовом API.

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

Когда инструмент выбрасывает исключение, tool runner перехватывает его и возвращает ошибку Claude как результат инструмента с is_error: true. По умолчанию включается только сообщение об исключении, а не полная трассировка стека.

Для просмотра полных трассировок стека и информации отладки установите переменную окружения ANTHROPIC_LOG:

# View info-level logs including tool errors
export ANTHROPIC_LOG=info

# View debug-level logs for more verbose output
export ANTHROPIC_LOG=debug

Когда включено, SDK логирует полные детали исключения (используя модуль logging Python, консоль в TypeScript или логгер Ruby), включая полную трассировку стека при сбое инструмента.

Перехват ошибок инструмента

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

Используйте метод ответа инструмента для перехвата результатов инструмента и проверки ошибок перед их отправкой в Claude:

Изменение результатов инструмента

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

Используйте метод ответа инструмента для получения результата инструмента, затем измените его перед тем, как runner продолжит. Явно ли вы добавляете изменённый результат или мутируете его на месте, зависит от SDK; см. комментарии кода в каждой вкладке.

Добавление cache_control к результатам инструмента особенно полезно, когда инструменты возвращают большие объёмы данных (например, результаты поиска документов), которые вы хотите кэшировать для последующих вызовов API. Дополнительные сведения о стратегиях кэширования см. в разделе Кэширование подсказок.

Потоковая передача

Включите потоковую передачу для получения событий по мере их поступления. Каждая итерация выдаёт объект потока, который вы можете итерировать для получения событий.

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

Для ручного управления циклом вызова инструмента см. Обработка вызовов инструментов.
Для запуска нескольких инструментов одновременно см. Параллельное использование инструментов.
Для полного рабочего процесса использования инструментов см. Определение инструментов.