Passer au contenu principal
Le suivi des tâches fournit un moyen structuré de gérer les tâches et d’afficher la progression aux utilisateurs. Le SDK Claude Agent inclut une fonctionnalité de tâches intégrée qui aide à organiser les flux de travail complexes et à tenir les utilisateurs informés de la progression des tâches.
À partir du TypeScript Agent SDK 0.3.142 et Claude Code v2.1.142, les sessions utilisent les outils Task structurés TaskCreate, TaskUpdate, TaskGet et TaskList à la place de TodoWrite. Le SDK Python obtient ce changement à partir de la CLI Claude Code qu’il lance, et non à partir de la version du package Python : le changement s’applique une fois que cette CLI — la copie fournie dans le package pip, ou celle vers laquelle vous pointez avec cli_path — est v2.1.142 ou ultérieure. Consultez Migrer vers les outils Task pour savoir comment le code de surveillance change. Les exemples de cette page définissent CLAUDE_CODE_ENABLE_TASKS=0 pour continuer à afficher TodoWrite pour les sessions qui n’ont pas encore migré.

Cycle de vie des tâches

Les tâches suivent un cycle de vie prévisible :
  1. Créées en tant que pending lorsque les tâches sont identifiées
  2. Activées en tant que in_progress lorsque le travail commence
  3. Complétées lorsque la tâche se termine avec succès
  4. Supprimées lorsque toutes les tâches d’un groupe sont complétées

Quand les tâches sont utilisées

Le SDK crée des tâches pour la plupart des travaux multi-étapes, tels que :
  • Les tâches complexes multi-étapes nécessitant 3 actions distinctes ou plus
  • Les listes de tâches fournies par l’utilisateur lorsque plusieurs éléments sont mentionnés
  • Les opérations non triviales qui bénéficient du suivi de la progression
  • Les demandes explicites lorsque les utilisateurs demandent une organisation des tâches
Il peut ignorer les tâches pour les demandes très courtes ou à une seule étape.

Exemples

Avant d’exécuter ces exemples, installez le Claude Agent SDK en suivant le démarrage rapide. Chaque exemple s’exécute jusqu’à ce que l’agent se termine et produise son message de résultat final. Si une session atteint d’abord sa limite de tours, ce message de résultat a le sous-type error_max_turns. Vérifiez subtype pour détecter cette fin. Ces exemples utilisent des appels query() uniques. Après avoir produit un résultat error_max_turns, query() lève une erreur qui inclut Reached maximum number of turns. Chaque exemple enveloppe sa boucle dans un bloc try pour quitter proprement quand cela se produit. Voir Gérer le résultat pour les sous-types de résultat.

Surveillance des modifications des tâches

Affichage de la progression en temps réel

Migrer vers les outils Task

Les outils Task divisent l’appel unique TodoWrite en TaskCreate pour chaque nouvel élément et TaskUpdate pour chaque changement de statut, avec TaskList et TaskGet disponibles pour que le modèle relise la liste actuelle. Votre code de surveillance inspecte toujours les blocs tool_use dans le flux assistant, mais maintient une carte indexée par ID de tâche au lieu de remplacer la liste entière à chaque appel. Les outils Task sont le défaut à partir du TypeScript Agent SDK 0.3.142 et Claude Code v2.1.142, donc aucun changement options.env n’est nécessaire. L’ID de tâche assigné ne se trouve pas dans l’entrée TaskCreate. Il revient dans le bloc tool_result correspondant sous la forme { task: { id, subject } }, donc capturez-le à partir du bloc de résultat pour indexer votre carte. L’exemple suivant montre le changement minimal à la boucle Surveillance des modifications des tâches. Il lit uniquement les entrées tool_use et ignore la capture des ID à partir des blocs tool_result. Pour rendre une liste complète, regardez un résultat d’outil TaskList dans le flux ou accumulez les résultats TaskCreate et les entrées TaskUpdate dans une carte. Le flux tool_use d’entrée est la forme brute que le modèle a émise. Claude Code répare certains noms de clés proches mais incorrects avant l’exécution, en mappant id ou task_id à taskId et active_form à activeForm, mais cette réparation n’est pas reflétée dans le flux. Lisez les champs d’entrée TaskUpdate de manière défensive, comme le font les exemples ci-dessous, plutôt que de supposer que le nom canonique est toujours présent.