Criar um agente de IA que investiga com ferramentas e testar que ele não chuta respostas

## Separar o mecanismo de investigação dos plugins de cada serviço Organize o sistema em camadas explícitas: pontos de entrada voltados ao usuário, carregamento de configuração, um mecanismo de investigação, um gerenciador de ferramentas e fontes, conjuntos de ferramentas, prompts e destinos conectáveis. Os pontos de entrada devem encaminhar solicitações e configurar os registros; a configuração deve validar as definições e construir integrações; o mecanismo deve selecionar ferramentas, coletar evidências, analisar resultados e, opcionalmente, devolver as descobertas a um destino autorizado. Mantenha o comportamento específico de cada provedor por trás de plugins para que o ciclo central possa raciocinar com base em um contrato de ferramenta estável. Carregue as integrações dinamicamente a partir de configurações validadas e mantenha separadas a ingestão de fontes, a investigação e as gravações nos destinos, para que um diagnóstico somente leitura não se transforme silenciosamente em uma alteração de estado externo. ## Fazer de cada ferramenta um invólucro fino que explique as falhas com exatidão Prefira um encapsulamento leve em torno de um único endpoint ou operação externa. Forneça a cada integração um pequeno objeto de configuração validado, um pré-requisito explícito ou uma verificação de integridade e uma função de ferramenta cujos parâmetros correspondam diretamente à solicitação subjacente. Evite abstrações pesadas de cliente quando uma chamada transparente de transporte facilitar a inspeção do comportamento e dos erros. Retorne contexto de falha suficiente para que o chamador consiga se corrigir: a consulta ou o comando exato, o intervalo de tempo, os filtros, os parâmetros relevantes, o status da resposta e a mensagem de erro subjacente. Um resultado sem dados deve declarar o que foi pesquisado e onde. Preserve os controles de acesso, valide comandos executáveis, mantenha as ferramentas somente leitura por padrão e nunca exponha nem registre segredos no controle de versão. ## Limitar quantos dados uma ferramenta devolve antes que a IA os leia Nunca exponha uma coleção sem limites por meio de uma ferramenta. Exija filtros no servidor para endpoints que possam retornar grandes conjuntos de resultados e projete o esquema para que os chamadores não possam omitir o parâmetro de escopo mais importante. Um estouro de tokens ou memória causado por uma operação de listagem sem restrições é um defeito do contrato da ferramenta, não um problema do prompt. Quando o serviço remoto não puder filtrar adequadamente, adicione controles explícitos no cliente, como profundidade máxima, limites de resultados, seleção de campos ou uma expressão de consulta estruturada. Relate o truncamento e os limites aplicados. Mantenha a resposta padrão compacta, mas permita a expansão direcionada quando a investigação precisar de mais evidências. ## Manter nomes antigos de configuração funcionando e pôr o comportamento comum no nível de classe certo Ao renomear um campo de configuração, aceite os nomes descontinuados como entrada adicional, associe-os ao campo atual e emita um aviso de descontinuação. Mantenha apenas os nomes atuais no esquema público e na saída serializada, para que a compatibilidade não contamine a configuração gerada nem a lógica posterior. Antes de adicionar um campo, método, tempo limite ou política de novas tentativas a uma integração específica, examine sua hierarquia de classes e as implementações semelhantes. Coloque o comportamento compartilhado no nível mais geral que realmente precise dele. Use um mecanismo comprovado de novas tentativas, com políticas explícitas de tentativas e atrasos; crie um ciclo personalizado apenas quando o mecanismo padrão não puder expressar o requisito e documente o motivo. ## Testar em três camadas, dos testes unitários à avaliação completa do agente Use três camadas complementares. Testes unitários isolam o comportamento local, testes de integração exercitam os limites entre ferramentas e serviços, e avaliações de agentes verificam o comportamento completo da investigação com prompts e dados de teste realistas. Novos comportamentos locais precisam de cobertura unitária, novas integrações precisam de cobertura de limites, e investigações complexas precisam de casos de avaliação. Mantenha alinhadas a estrutura do código-fonte e a dos testes. Use simulações HTTP na camada de transporte ao testar o comportamento das solicitações, para que cabeçalhos, URLs, parâmetros e adaptadores sejam exercitados em vez de substituir uma função de alto nível. Execute ferramentas reais apenas em um ambiente configurado intencionalmente e diferencie testes determinísticos comuns de avaliações que exijam credenciais do modelo ou serviços externos. ## Criar avaliações que detectem respostas inventadas (alucinações) Faça cada prompt solicitar os fatos exatos verificados pela avaliação. Prefira valores esperados que só possam ser descobertos por consulta, como um identificador único inserido, uma contagem exata, um título ou um código de erro. A resposta esperada deve permanecer invisível para o agente. Se a resposta for genérica demais para comprovar a descoberta, exija evidências de que a ferramenta correta foi chamada. Teste a descoberta, não o reconhecimento. Use nomes de recursos neutros, cenários realistas e prompts que não revelem a implementação nem a solução provável. Evite asserções genéricas que um modelo poderia deduzir a partir do conhecimento do domínio. Use apenas tags de teste registradas, nomes de recursos únicos, versões fixadas de dependências ou imagens e saídas explícitas com falha quando a preparação não puder comprovar que o serviço está funcionando. ## Deixar várias execuções de teste compartilharem recursos na nuvem sem quebrar umas às outras Presuma que avaliações baseadas em nuvem de várias ramificações possam se sobrepor na mesma conta. A preparação deve ser idempotente: crie ou reutilize recursos sem falhar quando eles já existirem. A limpeza nunca deve excluir um recurso compartilhado estático que outra execução ainda possa estar usando; omita a limpeza ou limite-a a um identificador único no escopo da execução. Verifique o funcionamento por meio de uma resposta real da API, não apenas pelo estado de prontidão. Faça sondagens com repetições limitadas para lidar com condições de corrida durante a criação, falhe cedo quando o conteúdo esperado nunca aparecer e capture diagnósticos quando o tempo limite se esgotar. Reutilize a infraestrutura compartilhada padronizada quando vários testes precisarem do mesmo serviço, mas mantenha isolados os dados e identificadores de cada teste. ## Achar a causa de falhas de tela no terminal e de quedas na avaliação com registros reais Para defeitos em terminais interativos, reproduza o problema por meio de um pseudoterminal e capture as sequências de escape brutas. Compare o movimento do cursor e as operações de apagamento com a altura do quadro renderizado e depois teste o renderizador com um fluxo em memória forçado a se comportar como terminal. Corrija o contrato de quadro ou atualização que causa o desvio; não altere cegamente o movimento do cursor quando o comportamento for diferente na parte inferior do terminal. Para regressões em avaliações de agentes, compare um rastreamento de referência e um rastreamento atual para o mesmo teste e modelo antes de confiar em diferenças do código-fonte ou estatísticas agregadas. Inspecione os prompts renderizados, a ordem das chamadas de ferramentas, as métricas por chamada e as evidências retornadas. Um template pode crescer no código-fonte e encolher em tempo de execução, e a variância agregada pode ocultar uma mudança determinística em cada execução. Leia o conjunto completo de alterações de uma revisão suspeita antes de reverter apenas o arquivo mais visível. ## Formatar e verificar só os arquivos do escopo e não fazer push sem permissão Siga as políticas específicas do repositório para estilo, tipagem, testes e controle de versão, mas não execute correções automáticas amplas, formatação ou verificações em todo o repositório quando elas forem conhecidas por modificar arquivos não relacionados, a menos que o usuário ou o fluxo de trabalho aplicável as solicite explicitamente. Limite a formatação automática e a análise estática aos arquivos no escopo e mantenha as revisões focadas com os testes correspondentes. Posicione as importações e os utilitários compartilhados de acordo com as convenções do projeto, preserve um histórico reversível e evite a reescrita forçada do histórico, a menos que seja explicitamente autorizada. Uma tarefa local não autoriza, por si só, fazer commit, fazer push, publicar ou alterar o estado externo. Relate qual verificação foi executada e quais verificações foram excluídas intencionalmente. ## Atualizar todas as referências quando uma página ou título da documentação mudar Use a documentação do repositório como fonte principal do comportamento do projeto antes de consultar o site público. Quando uma página for movida, um nome de arquivo mudar ou um título tiver sua âncora alterada, pesquise o caminho e a âncora antigos em todo o repositório, incluindo a documentação, cadeias de caracteres do código-fonte, guias de nível superior e comentários, e atualize todas as referências afetadas. Atualize a fonte real de navegação do sistema de documentação, não uma configuração de nome semelhante que esteja inativa. Preserve a estrutura específica do renderizador, incluindo as linhas em branco obrigatórias e uma hierarquia válida de títulos. Evite listas desatualizadas de recursos e textos repetitivos de segurança; prefira exemplos concisos e blocos consolidados de solução de problemas. Ao adicionar uma integração, atualize em conjunto sua visão geral, índice, página dedicada, entrada de navegação e recurso visual.