A partir do TypeScript Agent SDK 0.3.142 e Claude Code v2.1.142, as sessões usam as ferramentas Task estruturadas
TaskCreate, TaskUpdate, TaskGet e TaskList em vez de TodoWrite. O SDK Python obtém essa mudança da CLI Claude Code que ele inicia, não da versão do pacote Python: a mudança se aplica uma vez que essa CLI — a cópia incluída dentro do pacote pip, ou uma que você aponta com cli_path — é v2.1.142 ou posterior. Consulte Migrar para ferramentas Task para saber como o código de monitoramento muda. Os exemplos nesta página definem CLAUDE_CODE_ENABLE_TASKS=0 para continuar mostrando TodoWrite para sessões que ainda não foram migradas.Ciclo de Vida das Tarefas
As tarefas seguem um ciclo de vida previsível:- Criadas como
pendingquando as tarefas são identificadas - Ativadas para
in_progressquando o trabalho começa - Concluídas quando a tarefa termina com sucesso
- Removidas quando todas as tarefas em um grupo são concluídas
Quando as Tarefas São Usadas
O SDK cria tarefas para a maioria dos trabalhos com múltiplas etapas, como:- Tarefas complexas com múltiplas etapas que exigem 3 ou mais ações distintas
- Listas de tarefas fornecidas pelo usuário quando vários itens são mencionados
- Operações não triviais que se beneficiam do rastreamento de progresso
- Solicitações explícitas quando os usuários pedem organização de tarefas
Exemplos
Antes de executar estes exemplos, instale o Claude Agent SDK seguindo o guia de início rápido. Cada exemplo é executado até que o agente termine e produza sua mensagem de resultado final. Se uma sessão atingir seu limite de turnos primeiro, essa mensagem de resultado terá o subtipoerror_max_turns. Verifique subtype para detectar esse encerramento.
Estes exemplos usam chamadas query() de um único disparo. Após produzir um resultado error_max_turns, query() lança um erro que inclui Reached maximum number of turns. Cada exemplo envolve seu loop em um bloco try para sair corretamente quando isso acontece.
Consulte Lidar com o resultado para os subtipos de resultado.
Monitorando Mudanças de Tarefas
Exibição de Progresso em Tempo Real
Migrar para ferramentas Task
As ferramentas Task dividem a única chamadaTodoWrite em TaskCreate para cada novo item e TaskUpdate para cada mudança de status, com TaskList e TaskGet disponíveis para o modelo ler de volta a lista atual. Seu código de monitoramento ainda inspeciona blocos tool_use no fluxo do assistente, mas mantém um mapa codificado por ID de tarefa em vez de substituir a lista inteira a cada chamada. As ferramentas Task são o padrão a partir do TypeScript Agent SDK 0.3.142 e Claude Code v2.1.142, portanto nenhuma mudança em options.env é necessária.
O ID de tarefa atribuído não está na entrada de
TaskCreate. Ele volta no tool_result correspondente como { task: { id, subject } }, então capture-o do bloco de resultado para codificar seu mapa. O exemplo a seguir mostra a mudança mínima para o loop Monitorando Mudanças de Tarefas. Ele lê apenas entradas de tool_use e ignora a captura de IDs de blocos tool_result. Para renderizar uma lista completa, observe um resultado de ferramenta TaskList no fluxo ou acumule resultados de TaskCreate e entradas de TaskUpdate em um mapa.
O input tool_use transmitido é a forma bruta que o modelo emitiu. Claude Code repara alguns nomes de chave próximos mas incorretos antes da execução, mapeando id ou task_id para taskId e active_form para activeForm, mas esse reparo não é refletido no fluxo. Leia os campos de entrada de TaskUpdate defensivamente, como os exemplos abaixo fazem, em vez de assumir que o nome canônico está sempre presente.