O Agent SDK é um harness, não uma permissão

O problema

Um time configura um agente com o Claude Agent SDK e escreve, no prompt do sistema, a instrução: "sempre rode o linter depois de editar um arquivo". Funciona na maior parte das vezes. Mas "na maior parte das vezes" não é uma garantia — em produção, uma instrução em linguagem natural pode ser esquecida, reinterpretada ou simplesmente não seguida quando o modelo está ocupado resolvendo outra parte do problema. Quando esse comportamento precisa ser garantido, não apenas provável, a resposta certa não é escrever a instrução de um jeito mais enfático. É sair do prompt e entrar no código: um hook.

O Agent SDK existe exatamente para separar essas duas categorias: o que o modelo decide (julgamento, ambiguidade, síntese) e o que o harness garante (determinismo, controle, limites). Confundir as duas é a fonte mais comum de sistemas agênticos que funcionam em demonstração e falham em produção.

O Agent SDK é um harness, não uma permissão

Uma leitura errada comum: "o Agent SDK dá ao agente permissão para fazer mais coisas". Na verdade é o oposto — o SDK é a camada que restringe e estrutura o que o agente pode fazer, tornando comportamento controlável em vez de apenas provável. Gerenciamento de sessão, hooks, subagentes e configuração de ferramentas permitidas (allowedTools) são mecanismos de controle, não de expansão de capacidade.

Hooks: controle determinístico onde um prompt não garante

Um hook roda código real em pontos específicos do ciclo de vida de uma sessão — antes ou depois de uma chamada de ferramenta, por exemplo — e pode aplicar uma regra sem depender da interpretação do modelo. Exemplos de uso correto:

• Rodar um linter automaticamente depois de toda edição de arquivo, sem depender de o modelo lembrar de fazer isso.
• Bloquear uma chamada de ferramenta específica (como git push --force) antes que ela execute, independente do que o modelo decidiu.
• Normalizar o formato de um resultado de ferramenta antes de devolvê-lo ao modelo.

A régua para decidir entre "colocar isso no prompt" e "colocar isso num hook" é simples: se a falha em seguir a regra é aceitável ocasionalmente, um prompt basta. Se a regra precisa valer sempre, é hook.

allowedTools e isolamento de contexto por subagente

Quando uma tarefa é delegada a um subagente, duas decisões de configuração controlam o raio de ação dele:

• allowedTools: restringe quais ferramentas aquele subagente específico pode chamar. Um subagente cuja função é só ler e resumir um arquivo não deveria ter acesso a Bash ou Write — não porque ele necessariamente usaria mal, mas porque o princípio de menor privilégio reduz o dano possível de um erro de julgamento do modelo.
• Isolamento de contexto: um subagente pode operar com um contexto próprio, sem herdar automaticamente todo o histórico da sessão principal. Isso evita que informação irrelevante (ou sensível) do contexto principal vaze para uma tarefa que não precisa dela, e mantém o subagente focado no escopo que lhe foi delegado.

Decomposição sequencial vs. adaptativa

Uma tarefa complexa pode ser dividida de duas formas:

• Sequencial: os passos são conhecidos de antemão e executados em ordem fixa. Funciona bem quando o problema já está bem entendido.
• Adaptativa: cada passo é decidido com base no resultado do anterior, porque o caminho não pode ser totalmente previsto de antemão (por exemplo, uma investigação de causa raiz onde o próximo passo depende do que foi encontrado).

Forçar decomposição sequencial numa tarefa que exige adaptação produz um plano rígido que quebra no primeiro imprevisto. Forçar decomposição adaptativa numa tarefa já bem conhecida desperdiça previsibilidade e torna o comportamento mais difícil de testar. A escolha depende de quanto do caminho já é conhecido antes de começar.

Coloque em prática

O laboratório desta lição pede pra você implementar um sistema de hooks simplificado em Python: um registro de hooks que rodam antes e depois de uma "chamada de ferramenta" simulada, capaz de bloquear uma chamada especificamente perigosa antes dela executar — e demonstrar que esse bloqueio funciona mesmo quando o "modelo" (nos testes, uma função que decide o que chamar) tenta contornar a regra.