Pular para o conteúdo principal
O rastreamento de tarefas fornece uma forma estruturada de gerenciar tarefas e exibir o progresso aos usuários. O Claude Agent SDK inclui funcionalidade integrada de tarefas que ajuda a organizar fluxos de trabalho complexos e manter os usuários informados sobre a progressão das tarefas.
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:
  1. Criadas como pending quando as tarefas são identificadas
  2. Ativadas para in_progress quando o trabalho começa
  3. Concluídas quando a tarefa termina com sucesso
  4. 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
Pode pular tarefas para solicitações muito curtas ou de uma única etapa.

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 subtipo error_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 chamada TodoWrite 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.