Начиная с TypeScript Agent SDK 0.3.142 и Claude Code v2.1.142, сеансы используют структурированные инструменты Task
TaskCreate, TaskUpdate, TaskGet и TaskList вместо TodoWrite. Python SDK получает это изменение из Claude Code CLI, который он запускает, а не из версии пакета Python: переключение применяется после того, как этот CLI — копия, включенная в пакет pip, или та, на которую вы указываете с помощью cli_path — имеет версию v2.1.142 или позже. Смотрите Миграция на инструменты Task для информации о том, как отслеживать изменения кода. Примеры на этой странице устанавливают CLAUDE_CODE_ENABLE_TASKS=0 для продолжения отображения TodoWrite для сеансов, которые еще не перешли на новую версию.Жизненный цикл задач
Задачи следуют предсказуемому жизненному циклу:- Созданы как
pendingпри выявлении задач - Активированы в
in_progressпри начале работы - Завершены при успешном завершении задачи
- Удалены при завершении всех задач в группе
Когда используются задачи
SDK создает задачи для большинства многошаговых работ, таких как:- Сложных многошаговых задач, требующих 3 или более отдельных действий
- Списков задач, предоставленных пользователем, когда упоминаются несколько элементов
- Нетривиальных операций, которые выигрывают от отслеживания прогресса
- Явных запросов, когда пользователи просят организовать задачи
Примеры
Перед запуском этих примеров установите Claude Agent SDK, следуя краткому руководству. Каждый пример выполняется до завершения агентом и выдачи его финального сообщения результата. Если сеанс сначала достигает лимита ходов, то сообщение результата имеет подтипerror_max_turns. Проверьте subtype, чтобы обнаружить это завершение.
Эти примеры используют однократные вызовы query(). После выдачи результата error_max_turns, query() выбрасывает ошибку, которая включает Reached maximum number of turns. Каждый пример оборачивает свой цикл в блок try для чистого выхода при возникновении этого события.
См. Обработка результата для получения информации о подтипах результатов.
Мониторинг изменений задач
Отображение прогресса в реальном времени
Миграция на инструменты Task
Инструменты Task разделяют единый вызовTodoWrite на TaskCreate для каждого нового элемента и TaskUpdate для каждого изменения статуса, с TaskList и TaskGet, доступными для модели для чтения текущего списка. Ваш код мониторинга по-прежнему проверяет блоки tool_use в потоке помощника, но поддерживает карту, индексированную по ID задачи, вместо замены всего списка при каждом вызове. Инструменты Task являются стандартными начиная с TypeScript Agent SDK 0.3.142 и Claude Code v2.1.142, поэтому изменение options.env не требуется.
Назначенный ID задачи отсутствует во вводе
TaskCreate. Он возвращается в соответствующем tool_result как { task: { id, subject } }, поэтому захватите его из блока результата, чтобы индексировать вашу карту. Следующий пример показывает минимальное изменение цикла Мониторинг изменений задач. Он читает только вводы tool_use и пропускает захват ID из блоков tool_result. Для отображения полного списка смотрите результат инструмента TaskList в потоке или накопите результаты TaskCreate и вводы TaskUpdate в карту.
Потоковый ввод tool_use — это необработанная форма, которую выдала модель. Claude Code исправляет некоторые близкие, но неправильные имена ключей перед выполнением, сопоставляя id или task_id с taskId и active_form с activeForm, но это исправление не отражается в потоке. Читайте поля ввода TaskUpdate защитно, как это делают примеры ниже, а не предполагайте, что каноническое имя всегда присутствует.