A partire da TypeScript Agent SDK 0.3.142 e Claude Code v2.1.142, le sessioni utilizzano i tool Task strutturati
TaskCreate, TaskUpdate, TaskGet e TaskList al posto di TodoWrite. L’SDK Python riceve questo cambiamento dalla CLI Claude Code che avvia, non dalla versione del pacchetto Python: il passaggio si applica una volta che quella CLI — la copia inclusa nel pacchetto pip, o una a cui punti con cli_path — è v2.1.142 o successiva. Vedere Migrazione ai tool Task per come monitorare i cambiamenti del codice. Gli esempi in questa pagina impostano CLAUDE_CODE_ENABLE_TASKS=0 per continuare a mostrare TodoWrite per le sessioni che non hanno ancora eseguito la migrazione.Ciclo di vita dei Todo
I todo seguono un ciclo di vita prevedibile:- Creati come
pendingquando le attività vengono identificate - Attivati a
in_progressquando il lavoro inizia - Completati quando l’attività termina con successo
- Rimossi quando tutte le attività in un gruppo sono completate
Quando vengono utilizzati i Todo
L’SDK crea todo per la maggior parte del lavoro multi-step, come:- Attività complesse multi-step che richiedono 3 o più azioni distinte
- Elenchi di attività forniti dall’utente quando vengono menzionati più elementi
- Operazioni non banali che traggono beneficio dal tracciamento dei progressi
- Richieste esplicite quando gli utenti chiedono l’organizzazione dei todo
Esempi
Prima di eseguire questi esempi, installare Claude Agent SDK seguendo la guida rapida. Ogni esempio viene eseguito fino a quando l’agente non termina e produce il suo messaggio di risultato finale. Se una sessione raggiunge prima il limite di turni, quel messaggio di risultato ha il sottotipoerror_max_turns. Controllare subtype per rilevare quella conclusione.
Questi esempi utilizzano chiamate query() a singolo scatto. Dopo aver prodotto un risultato error_max_turns, query() genera un errore che include Reached maximum number of turns. Ogni esempio racchiude il suo ciclo in un blocco try per uscire correttamente quando ciò accade.
Vedere Gestire il risultato per i sottotipi di risultato.
Monitoraggio dei cambiamenti dei Todo
Visualizzazione dei progressi in tempo reale
Migrazione ai tool Task
I tool Task dividono la singola chiamataTodoWrite in TaskCreate per ogni nuovo elemento e TaskUpdate per ogni cambio di stato, con TaskList e TaskGet disponibili affinché il modello possa leggere di nuovo l’elenco corrente. Il codice di monitoraggio continua a ispezionare i blocchi tool_use nel flusso dell’assistente, ma mantiene una mappa con chiave dell’ID attività invece di sostituire l’intero elenco ad ogni chiamata. I tool Task sono l’impostazione predefinita a partire da TypeScript Agent SDK 0.3.142 e Claude Code v2.1.142, quindi non è necessario alcun cambio options.env.
L’ID attività assegnato non è nell’input
TaskCreate. Ritorna nel tool_result corrispondente come { task: { id, subject } }, quindi acquisiscilo dal blocco del risultato per inserire la chiave nella mappa. L’esempio seguente mostra il cambio minimo al ciclo Monitoraggio dei cambiamenti dei Todo. Legge solo gli input tool_use e salta l’acquisizione degli ID dai blocchi tool_result. Per renderizzare un elenco completo, guarda un risultato dello strumento TaskList nel flusso o accumula i risultati TaskCreate e gli input TaskUpdate in una mappa.
L’input tool_use trasmesso è la forma grezza che il modello ha emesso. Claude Code ripara alcuni nomi di chiave quasi corretti ma non del tutto prima dell’esecuzione, mappando id o task_id a taskId e active_form a activeForm, ma questa riparazione non si riflette nel flusso. Leggi i campi di input TaskUpdate in modo difensivo, come fanno gli esempi seguenti, piuttosto che assumere che il nome canonico sia sempre presente.