Tool Runner (SDK)

«Tool runner» (исполнитель инструментов) берёт на себя агентный цикл, обёртывание ошибок и типобезопасность, чтобы вам не приходилось делать это вручную. Если вам нужно одобрение человеком в цикле, пользовательское логирование или условное выполнение, используйте вместо этого ручной цикл.

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

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



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

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

В зависимости от сигнатуры инструмента в SDK инструмент возвращает свой результат в виде строки или в виде блоков контента (текстовых блоков, блоков изображений или документов), поэтому инструмент может возвращать мультимодальные результаты. Возвращённая строка становится одним текстовым блоком контента. Чтобы вернуть структурированные данные, например объект JSON или число, сначала закодируйте их как строку.



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

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

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

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



Расширенное использование

Внутри цикла вы можете читать каждое ответное сообщение и изменять состояние runner перед следующим вызовом API. Каждая итерация следует этому жизненному циклу:

1. Runner отправляет запрос к Messages API со своим текущим состоянием.
2. Runner выдаёт ответное сообщение в тело вашего цикла.
3. Выполняется тело вашего цикла. Вы можете прочитать сообщение и при желании изменить состояние runner.
4. Когда тело вашего цикла возвращает управление, runner проверяет, изменили ли вы его историю сообщений.
   • Если вы не изменяли историю сообщений: runner добавляет сообщение ассистента к своему состоянию. Если сообщение содержит вызовы инструментов, runner запускает их и добавляет результаты. Если вызовов инструментов нет, цикл завершается.
   • Если вы изменили историю сообщений: runner пропускает автоматическое добавление и использует ваше состояние без изменений. См. Перехват управления историей сообщений.



Перехват управления историей сообщений

По умолчанию runner управляет состоянием диалога за вас: после каждого хода он добавляет сообщение ассистента и все результаты инструментов в свою собственную историю сообщений. Вы перехватываете управление историей сообщений, когда хотите повторить ход (отбросить ответ и отправить заново), вставить последующее сообщение или построить результат инструмента самостоятельно.

Вы перехватываете управление, изменяя сообщения runner изнутри тела цикла. Точный метод зависит от SDK. См. вкладки для каждого языка ниже.

Когда вы перехватываете управление на итерации, runner не добавляет сообщение ассистента или результаты инструментов из этого хода. Вы становитесь ответственными за поддержание корректности диалога: добавьте сообщение ассистента и результат инструмента самостоятельно (если хотите, чтобы ход засчитался), изменяйте состояние условно, чтобы цикл всё ещё мог завершиться при отсутствии вызовов инструментов, и передавайте max_iterations для ограничения цикла. Все семь SDK поддерживают max_iterations.



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

Для длительных агентных задач tool runner в Python, TypeScript и Ruby поддерживает автоматическое сжатие, которое генерирует сводки, когда использование токенов превышает порог, чтобы диалог мог продолжаться за пределами ограничений контекстного окна. Во всех трёх SDK эта клиентская опция объявлена устаревшей в пользу серверного редактирования контекста, которое доступно в каждом SDK. Tool runner в Go, Java, C# и PHP не включает клиентское сжатие.



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

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

То, что SDK логирует, зависит от языка. Python SDK логирует полное исключение, включая его трассировку стека, через стандартный модуль logging всякий раз, когда инструмент выбрасывает необработанное исключение. Python, TypeScript и Java SDK читают переменную окружения ANTHROPIC_LOG для включения логирования SDK, которое включает детали запросов и ответов:

# Логирование на уровне info
export ANTHROPIC_LOG=info

# Логирование на уровне debug для более подробного вывода
export ANTHROPIC_LOG=debug

Go, Ruby, C# и PHP SDK не читают ANTHROPIC_LOG. За пределами Python ни один SDK не логирует сбой инструмента: чтобы увидеть, почему инструмент завершился с ошибкой, перехватите и залогируйте исключение внутри функции инструмента перед возвратом или повторным выбрасыванием.



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

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

В Python и TypeScript SDK используйте метод ответа инструмента (generate_tool_call_response() в Python, generateToolResponse() в TypeScript), чтобы перехватить результаты инструментов и проверить их на ошибки до отправки Claude. Другие SDK не предоставляют этот хук. Их вкладки описывают ближайшую альтернативу:



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

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

В Python и TypeScript SDK используйте метод ответа инструмента, чтобы получить результат инструмента, затем измените его до того, как runner продолжит работу. Нужно ли явно добавлять изменённый результат или изменять его на месте, зависит от SDK. См. комментарии в коде на каждой вкладке.



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

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



Дальнейшие шаги