Confiabilidade
Hooks do Agent SDK interceptam chamadas de ferramentas de forma programatica. O tipo mais importante e o PostToolUse, que intercepta resultados de ferramentas antes que o modelo os processe.
Casos de uso de hooks:
- Normalizacao de dados — Converter timestamps para ISO 8601, padronizar status codes, formatar valores monetarios
- Bloqueio por politica — Bloquear reembolsos acima de um threshold, impedir acesso a dados sensiveis
- Auditoria — Registrar todas as chamadas de ferramentas para compliance
Retry com error-feedback e uma tecnica poderosa: quando a validacao falha, voce adiciona os erros especificos ao contexto e pede ao modelo para corrigir.
A chave e fornecer feedback especifico, nao generico:
- Correto: "Campo 'data_nascimento' esta no formato DD/MM/YYYY, esperado YYYY-MM-DD"
- Errado: "Erro de validacao, tente novamente"
Padrao de Self-Correction
Envie o documento original + erros de validacao na mensagem de retry. O campo detected_pattern pode ajudar a identificar falsos positivos sistematicos.
Erros genericos sao um anti-pattern grave. O modelo precisa de contexto estruturado para tomar decisoes inteligentes de recuperacao.
Todo erro deve incluir:
errorCategory— transient (timeout), validation (input invalido), business (politica), permissionisRetryable— boolean indicando se vale a pena tentar novamente- Resultados parciais — O que ja foi obtido antes da falha
- Alternativas — Outras abordagens que o modelo pode tentar
A flag isError sinaliza para o modelo que a resposta da ferramenta representa uma falha, nao um resultado valido.
O contexto e o recurso mais precioso e fragil de um agente. Tres problemas centrais:
- Lost in the middle — Modelos processam bem o inicio e o fim do contexto, mas podem omitir informacoes do meio. Coloque fatos criticos no inicio ou use section headers.
- Progressive summarization — Resumos perdem valores numericos, datas e expectativas especificas. Extraia fatos transacionais para um bloco persistente de "case facts".
- Tool results accumulation — Resultados de ferramentas acumulam tokens sem proporcao com sua relevancia. Corte outputs verbosos.
Padrao Recomendado
Mantenha um bloco de "case facts" persistente com dados criticos (nome do cliente, numero do pedido, valores). Resumos ficam no inicio do contexto com section headers claros. Use /compact para reduzir contexto quando necessario.
Evolua o extrator da Camada 2 para um agente de suporte ao cliente com garantias de confiabilidade:
- Compliance via hooks — PostToolUse para bloquear reembolsos acima do limite e normalizar dados do cliente
- Escalation patterns — Criterios explicitos para escalar: cliente pede humano, lacuna de politica, incapacidade de progredir
- Handoff estruturado — Ao escalar, incluir: detalhes do cliente, causa raiz, acoes tomadas, recomendacoes
- Erros com contexto — Cada falha de ferramenta retorna errorCategory, isRetryable e alternativas
Evolucao do Projeto
O extrator agora e confiavel: hooks garantem compliance, erros estruturados permitem recuperacao inteligente, e o contexto e gerenciado ativamente. Na Camada 4, voce escalara para multi-agente.