Disponibilidade de modelos
As seguintes ferramentas estão disponíveis por padrão apenas em Claude Opus 4.7, Claude Sonnet 4.6, Claude Haiku 4.5 e modelos anteriores. Em todos os outros modelos, incluindo IDs de modelo que Claude Code não reconhece, elas não estão disponíveis a menos que você opte por usá-las:
TodoWriteTaskCreateTaskGetTaskUpdateTaskList
TodoWrite em vez disso quando você define CLAUDE_CODE_ENABLE_TASKS=0.Este conjunto padrão se aplica em Claude Code v2.1.268 e posterior, que o TypeScript Agent SDK agrupa a partir de v0.3.268.tool_use para elas no fluxo de mensagens. O Agent SDK aplica esses padrões através do binário Claude Code que ele agrupa. Se você apontar pathToClaudeCodeExecutable (TypeScript) ou cli_path (Python) para sua própria instalação do Claude Code, você obtém quaisquer ferramentas que essa instalação fornece, sob seus próprios padrões. Para ver o conjunto exato em uma sessão em execução, verifique quais ferramentas estão disponíveis. Para optar por uma sessão, faça um dos seguintes:
- Nomeie uma das ferramentas na opção
allowedTools(TypeScript) ouallowed_tools(Python) - Liste as ferramentas na opção
tools, que restringe as ferramentas integradas da sessão àquelas que ela nomeia. Inclua as ferramentas que você deseja junto com as outras ferramentas integradas que você usa - Defina
CLAUDE_CODE_ENABLE_TODO_TOOLS=1na opçãoenv, como os exemplos nesta página fazem. No TypeScript,envsubstitui o ambiente do subprocesso, então espalhe...process.envpara manter variáveis herdadas. No Python,envé mesclado no topo do ambiente herdado
Ciclo de vida das tarefas
Claude move cada tarefa através de um ciclo de vida previsível:- Criada: Claude adiciona a tarefa como
pendingquando identifica uma tarefa - Ativada: Claude define a tarefa como
in_progressquando inicia o trabalho - Concluída: Claude marca como concluída quando a tarefa termina com sucesso
- Removida: Claude deleta uma tarefa que não precisa mais definindo
status: "deleted"em uma chamadaTaskUpdate
Quando Claude cria tarefas
Em uma sessão que possui as ferramentas de rastreamento de tarefas, Claude cria tarefas para a maioria dos trabalhos com múltiplas etapas, como:- Tarefas complexas com múltiplas etapas que exigem três ou mais ações distintas
- Listas de tarefas fornecidas pelo usuário quando vários itens são mencionados
- Operações mais longas 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 nesta página compartilha a mesma configuração de permissões e comportamento de saída:- Modo de permissão: os exemplos de prompt pedem ao Claude para fazer trabalho real em um projeto, então cada exemplo define
permissionMode: "acceptEdits"(TypeScript) oupermission_mode="acceptEdits"(Python) para aprovar automaticamente as edições de arquivo que o trabalho produz. Veja Modos de permissão para as alternativas. - Limite de turnos: 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. Verifiquesubtypepara detectar esse encerramento. - Tratamento de erros: estes exemplos usam chamadas
query()de um único disparo. Após produzir um resultadoerror_max_turns,query()lança um erro que incluiReached maximum number of turns. Cada exemplo envolve seu loop em um bloco try para sair corretamente quando isso acontece. Veja Lidar com o resultado para os subtipos de resultado.
As mensagens do sistema de tarefas,
SDKTaskNotificationMessage (TypeScript) ou TaskNotificationMessage (Python) entre elas, relatam tarefas em segundo plano, como comandos em segundo plano e suagentes. No fluxo de mensagens, você vê atividade de tarefas como blocos tool_use nas mensagens do assistente.Monitorar mudanças de tarefas
O exemplo a seguir observa o fluxo do assistente para blocostool_use TaskCreate e TaskUpdate e imprime uma linha + com o assunto de cada nova tarefa e uma linha de atualização com o ID da tarefa e o novo status de cada mudança de status. Use esta forma quando você deseja um registro de atividade de tarefas em vez de uma exibição renderizada. As linhas + não incluem os IDs atribuídos, então este registro não pode corresponder atualizações de volta às suas criações. Para manter essa correlação, capture os IDs como Exibir progresso em tempo real faz.
A entrada tool_use transmitida é 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 ambos os exemplos nesta página fazem, em vez de assumir que o nome canônico está sempre presente.
Exibir progresso em tempo real
O exemplo a seguir observa o fluxo do assistente para blocostool_use TaskCreate e TaskUpdate e mantém um mapa de tarefas codificadas por ID de tarefa em uma classe TaskTracker, renderizando novamente um resumo de progresso a cada mudança. O resumo conta tarefas concluídas e em progresso e mostra o rótulo activeForm de cada item ativo no lugar de seu subject. Use esta forma quando sua aplicação mantém uma exibição de progresso em vez de registrar cada evento.
O ID de tarefa atribuído não está na entrada de TaskCreate. Claude Code entrega a saída estruturada de cada ferramenta na mensagem do usuário que carrega seu bloco tool_result, no campo tool_use_result. Para TaskCreate, esse objeto é documentado para TypeScript como TaskCreateOutput em Tipos de Saída de Ferramenta, e em Python o campo é um dict simples da mesma forma. O rastreador emparelha cada bloco tool_result com sua chamada tool_use por tool_use_id e lê task.id da mensagem emparelhada tool_use_result. Claude pode ler a lista de volta com TaskList e os detalhes completos de uma tarefa com TaskGet.
Documentação relacionada
- Referência do Agent SDK - TypeScript: as opções, tipos e esquemas de ferramentas para o SDK TypeScript, incluindo os tipos de entrada e saída da ferramenta Task
- Referência do Agent SDK - Python: as opções, tipos e documentação de ferramentas para o SDK Python
- Entrada de Streaming: os dois modos de entrada e quando usar entrada de streaming em vez das chamadas de um único disparo que estes exemplos usam
- Dê ao Claude ferramentas personalizadas: defina suas próprias ferramentas com o servidor MCP em processo do SDK