Перейти к основному содержанию
Отслеживание задач предоставляет структурированный способ управления задачами и отображения прогресса пользователям. Claude Agent SDK включает встроенную функциональность задач, которая помогает организовать сложные рабочие процессы и держать пользователей в курсе хода выполнения задач.
Начиная с 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 для сеансов, которые еще не перешли на новую версию.

Жизненный цикл задач

Задачи следуют предсказуемому жизненному циклу:
  1. Созданы как pending при выявлении задач
  2. Активированы в in_progress при начале работы
  3. Завершены при успешном завершении задачи
  4. Удалены при завершении всех задач в группе

Когда используются задачи

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 защитно, как это делают примеры ниже, а не предполагайте, что каноническое имя всегда присутствует.