Melhores Práticas do Claude Agent SDK

Regras práticas para transformar um agente Claude Agent SDK de um protótipo funcional em algo seguro para rodar em produção, cobrindo escopo de ferramentas, checkpoints, subagentes e sessões.

Como Usar Esta Lista

• Percorra cada grupo com letras antes de implantar um agente que toque em dados reais, sistemas reais ou usuários reais.
• Os grupos estão ordenados aproximadamente pela importância em relação ao ciclo de vida de um agente: escopo e ferramentas primeiro, depois portões de segurança, e por último delegação e continuidade.
• Trate isto como um checklist de revisão, não como um tutorial; cada item linka de volta para a página que explica o raciocínio em profundidade.

A - Escopo de Ferramentas

• Habilite apenas as famílias de ferramentas que uma tarefa realmente necessita. Um agente que apenas escreve arquivos não precisa de bash, web_search ou web_fetch; cada ferramenta habilitada é uma área de superfície adicional sobre a qual o loop pode agir sem supervisão.
• Escope bash para uma lista explícita de comandos permitidos em vez de conceder um shell aberto. Acesso bash irrestrito transforma uma ferramenta em uma capacidade de execução de código arbitrário; uma lista de comandos permitidos a mantém nas operações específicas que a tarefa requer.
• Restrinja file_edit aos caminhos que uma tarefa deve realmente tocar. Restrições de caminho ou glob impedem que um agente de um monorepo edite arquivos fora do pacote ou diretório em que foi solicitado a trabalhar.
• Prefira web_fetch sobre web_search quando o URL já é conhecido. web_search é uma capacidade mais ampla e menos previsível; reserve-a para tarefas de pesquisa genuinamente abertas.
• Reaudite o escopo da ferramenta sempre que o prompt de uma tarefa mudar significativamente. Decisões de escopo feitas para uma versão de uma tarefa podem se tornar silenciosamente muito amplas ou muito restritas à medida que o comportamento real da tarefa evolui.

B - Checkpoints Human-in-the-Loop

• Faça checkpoint de ações destrutivas ou irreversíveis, não de cada chamada de ferramenta. Bloquear leituras inofensivas junto com riscos genuínos treina os revisores a aprovar sem ler.
• Dê a cada hook de checkpoint um timeout explícito com um padrão seguro. Um hook que pode bloquear para sempre esperando por uma decisão humana pode travar uma execução de produção; defina como rejeitar quando a janela expirar.
• Construa um canal de aprovação real antes de implantar em um ambiente hospedado. Um prompt de terminal bloqueante não tem terminal para ler assim que um agente roda sem supervisão em um servidor; direcione as aprovações através de uma fila, dashboard ou webhook.
• Registre cada decisão de checkpoint junto com a chamada à qual se aplicou. Sem uma trilha de auditoria do que foi aprovado ou rejeitado e por quem, os checkpoints perdem a responsabilidade que deveriam fornecer.
• Camada de checkpoints sobre o escopo de ferramentas, nunca como um substituto. O escopo fecha classes inteiras de ações; checkpoints apenas capturam as chamadas específicas que você se lembrou de sinalizar.

C - Subagentes

• Delegue apenas tarefas que são genuinamente independentes. Dividir uma tarefa com dependências reais entre subagentes força você a sequenciar e passar resultados manualmente, o que apaga o benefício de delegar em primeiro lugar.
• Escreva descrições de subagentes tão especificamente quanto descrições de ferramentas. Uma descrição vaga não dá ao modelo pai nenhum sinal confiável para quando invocar esse subagente.
• Escope as ferramentas de cada subagente independentemente, não copiando o escopo do pai. Um subagente não herda nada automaticamente; conceda a ele apenas o que seu trabalho específico requer.
• Não divida uma tarefa simples em um subagente apenas para se sentir completo. O overhead de um novo contexto e um loop interno completo não vale a pena para uma etapa que uma única chamada de ferramenta resolveria igualmente bem.
• Execute subagentes independentes concorrentemente quando a tarefa permitir. O despacho sequencial de subagentes não relacionados desperdiça o paralelismo que o isolamento deveria habilitar.

D - Sessões e Continuidade

• Persista IDs de sessão em um armazenamento que sobreviva ao processo. O SDK fornece o mecanismo para retomar; se o ID não for armazenado de forma durável, ele se perde assim que o processo é encerrado.
• Chaveie sessões por um identificador de tarefa estável, não por um valor aleatório novo a cada chamada. Uma nova chave a cada invocação significa que você nunca retoma nada.
• Trate um ID de sessão ausente ou expirado como um caso de falha explícito. Retomar com um ID obsoleto deve falhar previsivelmente e voltar para uma nova execução, não produzir silenciosamente uma sessão vazia.
• Defina uma política de retenção para dados de sessão armazenados. O histórico de sessões pode conter resultados de ferramentas sensíveis; mantê-lo para sempre sem limpeza é um risco, não uma conveniência.
• Não confie em resume para reproduzir efeitos colaterais. Retomar restaura o registro do que já aconteceu; não reexecuta comandos bash ou rebusca URLs da sessão anterior.

E - Implantação e Operações

• Combine o formato de implantação com a presença de um humano. Execuções de binários CLI locais se adequam a fluxos de trabalho interativos de operador único; execução hospedada se adequa a cargas de trabalho não supervisionadas, agendadas ou multi-tenant.
• Reconstrua o roteamento de checkpoint explicitamente ao mudar de local para hospedado. Um fluxo de aprovação baseado em terminal que funcionou localmente se torna um bloqueio silencioso ou um no-op assim que o agente roda sem um terminal anexado.
• Mova segredos de arquivos locais antes de implantar em um ambiente hospedado. Leia credenciais do gerenciador de segredos da plataforma, não de arquivos de ambiente locais que não existirão nesse ambiente.
• Adicione logging estruturado assim que nenhum operador estiver assistindo um terminal ao vivo. Execuções hospedadas precisam de observabilidade embutida, já que não há ninguém presente para notar um problema conforme ele acontece.

FAQs

Relacionados

• O Modelo Mental do Claude Agent SDK - os conceitos em que essas práticas se baseiam
• Habilitando Ferramentas de Edição de Arquivo, Bash e Web no Agent SDK - escopo de ferramentas em profundidade
• Adicionando Checkpoints Human-in-the-Loop a um Fluxo de Trabalho do Agent SDK - mecânica de checkpoints em profundidade
• Delegando Trabalho para Subagentes no Claude Agent SDK - delegação de subagentes em profundidade
• Persistindo Sessões Entre Execuções com o Claude Agent SDK - persistência de sessão em profundidade
• Referência de Padrões de Implantação do Claude Agent SDK - trade-offs de implantação local vs. hospedada

Versões de Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5 - e o Claude Agent SDK (último lançamento, Python e TypeScript). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.