Доступность моделей
The following tools are available by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5. On every other model, including model IDs Claude Code doesn’t recognize, they aren’t available unless you opt in:
TodoWriteTaskCreateTaskGetTaskUpdateTaskList
TodoWrite instead when you set CLAUDE_CODE_ENABLE_TASKS=0.This default set applies in Claude Code v2.1.268 and later, which the TypeScript Agent SDK bundles from v0.3.268.tool_use для них в потоке сообщений. Agent SDK применяет эти значения по умолчанию через двоичный файл Claude Code, который он включает. Если вы указываете pathToClaudeCodeExecutable (TypeScript) или cli_path (Python) на вашу собственную установку Claude Code, вы получаете те инструменты, которые предоставляет эта установка, в соответствии с её собственными значениями по умолчанию. Чтобы увидеть точный набор в работающем сеансе, проверьте, какие инструменты доступны. Чтобы подключить сеанс, выполните одно из следующих действий:
- Назовите один из инструментов в опции
allowedTools(TypeScript) илиallowed_tools(Python) - Перечислите инструменты в опции
tools, которая ограничивает встроенные инструменты сеанса только теми, которые она называет. Включите нужные вам инструменты вместе с другими встроенными инструментами, которые вы используете - Установите
CLAUDE_CODE_ENABLE_TODO_TOOLS=1в опцииenv, как это делают примеры на этой странице. В TypeScriptenvзаменяет окружение подпроцесса, поэтому распределите...process.envдля сохранения унаследованных переменных. В Pythonenvобъединяется с унаследованным окружением
Жизненный цикл задач
Claude перемещает каждую задачу через предсказуемый жизненный цикл:- Созданы: Claude добавляет задачу как
pendingкогда выявляет задачу - Активированы: Claude устанавливает задачу в
in_progressкогда начинает работу - Завершены: Claude отмечает её завершённой когда задача успешно завершается
- Удалены: Claude удаляет задачу, которая ей больше не нужна, установив
status: "deleted"в вызовеTaskUpdate
Когда Claude создаёт задачи
В сеансе, который имеет инструменты отслеживания задач, Claude создаёт задачи для большинства многошаговой работы, такой как:- Сложные многошаговые задачи, требующие трёх или более отдельных действий
- Списки задач, предоставленные пользователем, когда упоминаются несколько элементов
- Более длительные операции, которые выигрывают от отслеживания прогресса
- Явные запросы, когда пользователи просят организовать задачи
Примеры
Перед запуском этих примеров установите Claude Agent SDK, следуя краткому руководству. Каждый пример на этой странице использует одну и ту же настройку разрешений и поведение выхода:- Режим разрешений: примеры подсказок просят Claude выполнить реальную работу над проектом, поэтому каждый пример устанавливает
permissionMode: "acceptEdits"(TypeScript) илиpermission_mode="acceptEdits"(Python) для автоматического одобрения редактирования файлов, которое производит работа. Смотрите Режимы разрешений для альтернатив. - Лимит ходов: каждый пример работает до завершения агентом и выдачи его финального сообщения результата. Если сеанс сначала достигает лимита ходов, то сообщение результата имеет подтип
error_max_turns. Проверьтеsubtype, чтобы обнаружить это завершение. - Обработка ошибок: эти примеры используют однократные вызовы
query(). После выдачи результатаerror_max_turns,query()выбрасывает ошибку, которая включаетReached maximum number of turns. Каждый пример оборачивает свой цикл в блок try для чистого выхода при возникновении этого события. Смотрите Обработка результата для подтипов результатов.
Системные сообщения задач,
SDKTaskNotificationMessage (TypeScript) или TaskNotificationMessage (Python) среди них, сообщают о фоновых задачах, таких как фоновые команды и подагенты. В потоке сообщений вы видите активность задач как блоки tool_use в сообщениях помощника.Мониторинг изменений задач
Следующий пример наблюдает за потоком помощника для блоковtool_use TaskCreate и TaskUpdate и выводит строку + с предметом каждой новой задачи и строку обновления с ID задачи каждого изменения статуса и новым статусом. Используйте эту форму когда вы хотите логирование активности задач вместо отображаемого дисплея. Строки + не включают назначенные ID, поэтому этот логирование не может сопоставить обновления обратно их созданиям. Чтобы сохранить это соответствие, захватите ID как это делает Отображение прогресса в реальном времени.
Потоковый ввод tool_use — это необработанная форма, которую выдала модель. Claude Code исправляет некоторые близкие, но неправильные имена ключей перед выполнением, сопоставляя id или task_id с taskId и active_form с activeForm, но это исправление не отражается в потоке. Читайте поля ввода TaskUpdate защитно, как это делают оба примера на этой странице, а не предполагайте, что каноническое имя всегда присутствует.
Отображение прогресса в реальном времени
Следующий пример наблюдает за потоком помощника для блоковtool_use TaskCreate и TaskUpdate и ведёт карту задач, индексированную по ID задачи в классе TaskTracker, переотображая сводку прогресса при каждом изменении. Сводка подсчитывает завершённые и выполняемые задачи и показывает метку activeForm каждого активного элемента вместо его subject. Используйте эту форму когда ваше приложение ведёт дисплей прогресса вместо логирования каждого события.
Назначенный ID задачи отсутствует во вводе TaskCreate. Claude Code доставляет структурированный вывод каждого инструмента в сообщение пользователя, которое несёт его блок tool_result, в поле tool_use_result. Для TaskCreate, этот объект задокументирован для TypeScript как TaskCreateOutput в разделе Типы вывода инструментов, и в Python поле является простым dict той же формы. Трекер сопоставляет каждый блок tool_result с его вызовом tool_use по tool_use_id и читает task.id из tool_use_result сопоставленного сообщения. Claude может прочитать список обратно с помощью TaskList и полные детали одной задачи с помощью TaskGet.
Связанная документация
- Справочник Agent SDK - TypeScript: опции, типы и схемы инструментов для TypeScript SDK, включая типы ввода и вывода инструмента Task
- Справочник Agent SDK - Python: опции, типы и документация инструментов для Python SDK
- Потоковый ввод: два режима ввода и когда использовать потоковый ввод вместо однократных вызовов, которые используют эти примеры
- Предоставьте Claude пользовательские инструменты: определите свои собственные инструменты с помощью встроенного MCP сервера SDK