Erros de ferramentas de agentes que ajudam sem expor segredos

Os erros das ferramentas de agentes precisam ter estrutura suficiente para que o agente se recupere, mas não podem transformar cada solicitação malsucedida em uma exportação de credenciais. É fácil descrever esse limite, mas ele é violado com frequência na prática: um wrapper captura uma exceção, retorna a mensagem da biblioteca e entrega discretamente ao modelo uma URL, um cabeçalho Authorization, um assunto de certificado, um destino SSH ou um fragmento de token.

Já vi o problema começar com um campo de depuração bem-intencionado. Alguém adiciona request_headers porque um agente continuava recebendo respostas 401. O agente copia o erro para suas anotações de trabalho. Essas anotações são coladas em um pull request, enviadas para um sistema de suporte ou mantidas em um registro de avaliação. A falha original passou. O segredo, não.

O design correto oferece ao agente uma explicação limitada do que aconteceu, do que ele pode fazer com segurança em seguida e um identificador de correlação para a pessoa operadora. As evidências brutas permanecem atrás da fronteira da ação. Não é preciso escolher entre erros úteis e erros seguros para os segredos. O trabalho é desenhar uma boa interface.

Uma resposta de erro faz parte da fronteira de segurança

Um agente trata a saída de uma ferramenta como memória de trabalho. Ele pode citar essa saída para uma pessoa usuária, colocá-la em um arquivo, enviá-la para outra ferramenta ou usá-la para decidir se deve tentar novamente. Portanto, todo campo retornado por um gateway de ações deve ser tratado como uma divulgação a um chamador não confiável, mesmo quando o chamador é um agente iniciado por uma pessoa desenvolvedora que controla a máquina.

Uma chamada de ferramenta tem dois públicos. O agente precisa de fatos operacionais: a ação foi executada, ele pode tentar novamente, precisa de consentimento e que entrada deve alterar? A pessoa operadora precisa de fatos forenses: qual credencial foi selecionada, qual rota exata foi chamada, qual resolvedor DNS falhou e o que o par remoto respondeu. Não atenda ao segundo público despejando essas evidências para o primeiro.

A distinção é mais importante quando um agente pode invocar ferramentas repetidamente. Uma pessoa que vê um erro detalhado uma vez pode notar um token bearer nele. Um agente pode preservá-lo por dezenas de turnos e depois incluí-lo em código gerado ou em um fixture de teste. Não é necessária uma intenção maliciosa do modelo para isso acontecer.

Construa a interface em torno de uma regra explícita: o chamador recebe apenas campos que continuam seguros se forem copiados para um issue público. Se um campo falhar nesse teste, armazene-o em diagnósticos protegidos ou omita-o.

Dê decisões aos agentes, não strings de exceção

Uma resposta útil informa ao agente que tipo de decisão ele precisa tomar. Exceções brutas não fazem isso de modo confiável nem seguro. Sua redação muda entre versões do sistema operacional e da biblioteca cliente, e muitas vezes mistura uma causa técnica com material que precisa permanecer privado.

Use um vocabulário pequeno e documentado de códigos. Cada código deve corresponder a um comportamento específico do chamador. Não torne os códigos tão detalhados que você acabe recriando toda falha possível do sistema upstream.

Uma estrutura prática de resposta é esta:

{
  "ok": false,
  "code": "AUTH_FAILED",
  "message": "The remote service rejected the stored credential.",
  "action": "stop_and_report",
  "retryable": false,
  "request_id": "act_7f3c2a91",
  "http_status": 401
}

O agente pode parar, informar à pessoa usuária que a autenticação precisa de atenção e incluir o ID da solicitação. Ele não precisa do token bearer, do esquema de autorização, do e-mail da conta nem de uma cópia do corpo da resposta para tomar essa decisão.

action é mais útil que um booleano genérico. Um booleano informa se o tempo talvez resolva o problema. Uma ação diz ao agente o que ele deve fazer. Mantenha os valores permitidos restritos:

• retry_after_delay para operações temporárias que podem ser repetidas com segurança.
• repair_input para uma solicitação que o agente pode corrigir sem obter nova autoridade.
• request_approval quando uma pessoa precisa autorizar a ação.
• stop_and_report para falhas que exigem trabalho da pessoa operadora.
• inspect_outcome quando uma gravação pode ter chegado ao serviço remoto.

O último valor merece atenção especial. Um timeout depois do envio de uma gravação não é igual a um timeout ocorrido antes do envio. Se você transformar os dois casos em NETWORK_ERROR, o agente tentará novamente uma ação que talvez já tenha sido concluída. É assim que surgem chamados, implantações, registros e comandos destrutivos duplicados.

Exponha http_status apenas quando ele for significativo e seguro. Ele costuma ser um contexto útil em chamadas HTTP, mas não finja que oferece a resposta completa. Um 403 pode significar uma falha de autorização no upstream, uma restrição no nível do recurso ou uma decisão do gateway. O código da ferramenta precisa indicar qual comportamento o agente deve adotar.

Mantenha uma taxonomia de códigos pequena o bastante para ser testada

Uma taxonomia de códigos deve descrever responsabilidade e recuperação, não cada camada da pilha de rede. Se sua lista chegar a cinquenta códigos na primeira semana, provavelmente você está exportando detalhes de implementação com outro nome.

Comece com categorias que permitam ao chamador tomar uma ação diferente:

Não use ERROR, FAILED ou EXCEPTION como seu contrato principal. Esses rótulos transferem ao agente o trabalho de interpretação, fazendo com que ele deduza uma solução a partir da prosa. Ele pode deduzir errado.

Mantenha estáveis os significados dos códigos. Você pode melhorar a mensagem humana, adicionar um campo retry_after_seconds ou incluir um novo valor de status seguro. Não faça AUTH_FAILED passar a significar tanto credenciais incorretas quanto recusa de aprovação local. Em algum momento, os agentes e a orquestração ao redor deles tomarão decisões com base nesse código.

A RFC 9457, «Problem Details for HTTP APIs», oferece uma boa base: as respostas podem conter um tipo estável de problema, um título, status, detalhe e referência à instância. O aviso da RFC é a parte que as equipes costumam ignorar. Ela diz que detail deve ajudar a corrigir o problema e que os detalhes do problema podem expor informações sensíveis. Em ferramentas de agentes, faça do tipo ou código estável o contrato, mantenha o detalhe curto e use a instância ou o ID da solicitação para conectar a pessoa operadora às evidências protegidas.

Cabeçalhos de solicitação e erros de conexão são evidências, não contexto

As equipes costumam chamar cabeçalhos brutos e mensagens de transporte de «contexto». Eles são evidências. Evidências devem ficar em um registro de auditoria com controles de acesso, não em uma resposta para o agente.

Considere uma solicitação de API que falhou. Uma exceção típica de uma biblioteca HTTP pode incluir a URL completa solicitada, o local de redirecionamento, o endereço do proxy, os cabeçalhos da resposta e parte do corpo da resposta. Qualquer um desses itens pode carregar segredos. Parâmetros de consulta ainda carregam chaves de API em APIs antigas. Cabeçalhos Location frequentemente contêm URLs assinadas de download. Cookies e cabeçalhos de autenticação personalizados são vazamentos óbvios. Campos menos evidentes, como X-Request-Id, podem ser aceitáveis, enquanto X-Forwarded-Host ou um cabeçalho de serviço interno pode revelar uma infraestrutura que o agente nunca precisou conhecer.

Erros de SSH exigem a mesma disciplina. Não retorne uma linha de comando contendo um destino privado, um caminho de known_hosts, um arquivo de identidade oferecido ou o texto bruto de uma incompatibilidade de chave do host. Uma incompatibilidade de chave tem um significado relevante para o chamador: a conexão foi bloqueada porque a identidade remota não pôde ser verificada. Retorne esse significado. Preserve a comparação das impressões digitais, os caminhos e os diagnósticos da biblioteca para a pessoa operadora.

O OAuth 2.0 deixa esse ponto especialmente claro. A RFC 6750 diz que um token bearer dá acesso a quem o possui e orienta os clientes a proteger os tokens contra divulgação no armazenamento e no transporte. Um manipulador de erros que copia um token bearer para um trace violou essa exigência, mesmo que a solicitação original tenha usado TLS corretamente.

Faça a sanitização antes da serialização, não depois que os registros se espalharem. Um filtro de redação em um destino geral de registros é útil como proteção adicional, mas não é a fronteira. Até lá, uma exceção lançada já pode ter sido anexada a um resultado de ferramenta, a um evento de telemetria ou a um relatório de falha.

Use uma lista de permissões para os campos que atravessam até o agente. Uma lista de bloqueio acaba deixando passar x-api-token, um parâmetro de consulta assinado, um campo de sessão específico do fornecedor ou uma nova propriedade da biblioteca. Uma lista de permissões começa sem divulgar nada e adiciona apenas campos com uma utilidade identificada para o chamador.

Separe o que falhou de saber se uma ação foi executada

Um design seguro de erros precisa informar ao agente se o lado remoto pode ter executado a ação. É aqui que a maior parte das orientações sobre novas tentativas se torna perigosa.

Suponha que um agente envie POST /deployments e a conexão sofra timeout. O gateway sabe que tentou fazer a chamada. Não sabe se o upstream a recebeu, se criou uma implantação ou se a resposta desapareceu no caminho de volta. Retornar TEMPORARY_FAILURE convida o agente a enviar outra solicitação de implantação. Retornar AUTH_FAILED é simplesmente falso. O estado correto é OUTCOME_UNKNOWN.

A resposta deve dizer isso com clareza:

{
  "ok": false,
  "code": "OUTCOME_UNKNOWN",
  "message": "The connection ended after the request started. The remote action may have completed.",
  "action": "inspect_outcome",
  "retryable": false,
  "request_id": "act_9b18d4e0",
  "operation": "create_deployment"
}

operation nomeia uma classe genérica de ação, não a rota ou o payload completos. Agora o agente pode usar uma chamada de status separada e somente de leitura, se a integração oferecer uma. Se a API aceitar referências de idempotência, o gateway pode associar a referência segura à operação e consultá-la internamente. Não exponha um valor de idempotência se ele também funcionar como material de acesso no sistema-alvo.

Operações de leitura também não são automaticamente seguras para repetir. Uma leitura pode gerar cobrança, atualizar um estado remoto ou executar um comando com efeitos colaterais por trás de um nome aparentemente inofensivo. A pessoa responsável pela integração precisa indicar se uma operação pode ser repetida. Não peça a um modelo de linguagem que decida isso com base no nome do método.

Defina um limite de novas tentativas no gateway. Uma resposta pode incluir um atraso limitado, como retry_after_seconds: 30, mas apenas quando o upstream fornecer um valor seguro ou quando o gateway controlar o limite. Não permita que um agente tente novamente indefinidamente porque uma mensagem disse «temporário». Falhas repetidas geram ruído, consomem limites de taxa e dificultam uma investigação posterior.

A negação humana precisa ter seu próprio significado

Uma pessoa que recusa uma aprovação não está causando um erro de autenticação remota. Isso significa que a ação solicitada não foi executada. Essa distinção protege a segurança e a usabilidade.

Se uma ferramenta mapear uma aprovação negada para AUTH_FAILED, o agente poderá tentar credenciais alternativas, pedir a rotação de um segredo ou enviar uma solicitação ligeiramente alterada. Nenhuma dessas ações respeita a pessoa que disse não. Se o mapeamento for para uma falha interna genérica, a pessoa usuária não saberá se o gateway apresentou um defeito.

Retorne USER_DENIED com uma mensagem curta, como «A ação solicitada não foi aprovada e não foi executada». Evite mencionar o nome do segredo, a conta selecionada ou o destino exato se esses detalhes ainda não fizerem parte do contrato de entrada segura da ferramenta. O chamador precisa parar. Uma pessoa pode decidir se deve iniciar uma nova solicitação visível.

Um cofre de segredos bloqueado é outra situação. VAULT_LOCKED significa que o gateway recusou a ação antes de poder selecionar ou usar uma credencial. A solução segura é pedir a uma pessoa que desbloqueie o gateway, não pedir ao agente que forneça um token. Isso evita uma falha comum em que o modelo compensa a indisponibilidade de credenciais gerenciadas procurando outro segredo em seu contexto.

O Sallyport usa essa separação diretamente: enquanto a entrada do cofre está bloqueada, ele nega todas as ações, e sua autorização por sessão consegue distinguir um novo processo que precisa de aprovação de um serviço remoto que rejeitou uma chamada autenticada. O agente recebe o resultado da ação, enquanto a credencial permanece no cofre criptografado do aplicativo.

Não tente compensar o cansaço com aprovações fornecendo mais detalhes de diagnóstico. Se as pessoas aprovam rotineiramente chamadas que não inspecionaram, corrija o agrupamento das ações, o escopo e a identidade do processo apresentados para aprovação. Negativas mais detalhadas não tornam o consentimento apressado mais seguro.

Crie um caminho de diagnóstico com dois registros

Um registro deve ser seguro para o agente e outro deve ser completo o bastante para uma pessoa operadora autorizada. Tentar fazer um único registro cumprir os dois trabalhos produz uma experiência de suporte opaca ou um vazamento de segredo.

O registro seguro para o chamador precisa de um código, uma mensagem, uma ação, orientação sobre novas tentativas, um ID de solicitação e talvez um status de protocolo. O registro protegido pode conter o identificador do registro da credencial selecionada, o destino normalizado, o método, os tempos, os metadados da resposta do upstream, a impressão digital sanitizada do payload, a exceção bruta e um trace da decisão do gateway. Armazene o registro protegido em um local que os agentes não possam consultar por meio das ferramentas comuns.

Um ID de solicitação deve ser opaco. Gere-o independentemente das credenciais e dos destinos. Não codifique um nome de host, um nome de usuário, um horário que revele padrões de atividade ou um ID incremental de banco de dados se esses detalhes forem importantes no seu ambiente. O ID permite que uma pessoa diga «inspecione act_9b18d4e0», sem entregar os diagnósticos subjacentes.

Para ações de alto valor, registre se o gateway alcançou cada fronteira: validação da entrada, seleção da credencial, autorização da pessoa usuária, início da conexão, envio dos bytes da solicitação, recebimento da resposta e retorno do resultado. Essa sequência oferece à pessoa operadora uma explicação defensável de OUTCOME_UNKNOWN sem mostrar ao agente a solicitação bruta.

A evidência de adulteração também importa nesse caminho interno. Se alguém puder apagar silenciosamente tentativas de autorização malsucedidas ou reescrever o motivo pelo qual uma ação foi bloqueada, o registro de auditoria se tornará apenas um log de conveniência. O Sallyport projeta as visualizações de sessões e chamadas a partir de um registro de auditoria criptografado e encadeado por hash, e sp audit verify verifica a cadeia offline sobre texto cifrado. Isso é útil quando uma pessoa operadora precisa confiar no registro sem conceder ao agente acesso ao seu conteúdo.

Um registro protegido de exemplo poderia ser assim. Ele intencionalmente não é uma resposta para o agente:

{
  "request_id": "act_9b18d4e0",
  "event": "http_call_failed",
  "credential_record": "cred_42",
  "destination": "api.internal.example",
  "method": "POST",
  "path_template": "/deployments",
  "bytes_sent": true,
  "response_received": false,
  "exception_class": "ReadTimeout",
  "result_code": "OUTCOME_UNKNOWN"
}

Mesmo aqui, revise os campos com cuidado. Um caminho completo pode expor identificadores de recursos. Em geral, um corpo de solicitação deve se tornar uma impressão digital de mão única, um nome de esquema ou uma representação cuidadosamente redigida. As pessoas operadoras costumam precisar comparar duas tentativas, não ler todos os valores enviados.

As mensagens de erro precisam de uma política deliberada de redação

Redação não é apenas substituir um token por oito asteriscos. Isso trata somente dos formatos de segredo que você já reconhece. Uma política adequada classifica os campos antes que eles entrem em mensagens, registros, métricas e resultados de ferramentas.

Primeiro, classifique os segredos diretos: tokens bearer, senhas, chaves privadas, cookies, URLs assinadas, cabeçalhos de autorização e certificados de cliente. Depois, classifique o contexto sensível: nomes DNS internos, caminhos locais, nomes de usuários, nomes de repositórios, IDs de recursos, corpos de solicitações e cabeçalhos que revelem a topologia da implantação. A segunda classe pode ser aceitável em um registro protegido, mas raramente pertence a um erro visível ao agente.

Não retorne «a credencial terminada em 7KQ2 foi rejeitada». As equipes adicionam isso porque existem várias credenciais e as pessoas operadoras querem saber qual falhou. Isso cria um identificador persistente que pode ser correlacionado entre traces. Retorne AUTH_FAILED ao agente. A pessoa operadora pode inspecionar o registro da credencial por meio do ID de solicitação protegido.

Evite repetir a entrada da ferramenta por padrão. O agente já sabe o que tentou, mas o gateway não pode presumir que a própria entrada seja segura para repetir. Uma URL pode conter uma string de consulta assinada. Um comando pode incluir uma atribuição de ambiente. Um payload JSON pode conter uma credencial temporária que o agente recebeu de outro sistema. Retorne um erro de validação por campo, como invalid_fields: ["repository"], e não o valor inválido copiado.

Teste a redação com fixtures hostis. Inclua segredos em letras maiúsculas e minúsculas incomuns, cabeçalhos duplicados, userinfo de URL, valores de consulta codificados em porcentagem, JSON aninhado, causas de exceção e argumentos de comandos SSH. Depois, confirme que nenhum segredo do fixture aparece na resposta serializada da ferramenta, nos registros gerais, nos rótulos de métricas ou nos payloads de falha. Um teste que verifica apenas o caminho feliz não prova nada sobre o tratamento de falhas.

Trate as mensagens remotas como entradas não confiáveis

Uma API remota pode retornar um corpo de erro útil, uma página HTML de login ou uma string criada para influenciar quem a lê. O gateway não deve passar esse conteúdo diretamente para o contexto de um agente.

Isso é parcialmente um problema de segredos. Servidores às vezes refletem valores da solicitação em páginas de erro. Um cabeçalho Authorization, cookie, parâmetro de consulta ou campo JSON inválido pode voltar em uma resposta de diagnóstico do upstream. Repassá-lo transforma um eco remoto em um vazamento de credencial.

Também é um problema de integridade das instruções. Se um erro do upstream disser «execute este comando para corrigir suas credenciais», o agente poderá tratá-lo como orientação operacional. O serviço remoto não pode definir a política de recuperação do gateway.

Mapeie campos seguros conhecidos a partir de uma resposta de protocolo do upstream. Por exemplo, um status HTTP numérico e um atraso documentado de limite de taxa podem ser úteis. Trate corpos de texto livre como evidências protegidas, a menos que você tenha um analisador específico para o formato e uma lista de permissões clara. Se uma integração precisar de um motivo remoto legível por humanos, normalize-o na linguagem do gateway, como «O serviço rejeitou o recurso solicitado», em vez de copiar sua prosa.

A RFC 9110 define a semântica dos status HTTP, mas seus status não concedem permissão para divulgar o corpo da resposta de uma origem. Mantenha essa separação clara. Informações de protocolo podem ajudar na recuperação; texto arbitrário do upstream não é um contrato de diagnóstico seguro.

Coloque o contrato sob testes focados em falhas

A maioria das equipes testa se uma solicitação válida retorna dados úteis. Teste se toda solicitação inválida ou interrompida retorna apenas os dados que o agente deve ver.

Faça do esquema de erro um contrato versionado. Valide-o nos testes e, durante o desenvolvimento, rejeite campos desconhecidos na fronteira de serialização. Uma lista de permissões é mais fácil de auditar quando o objeto tem uma estrutura rígida.

Use um segredo de fixture feio o bastante para capturar transformações acidentais e force falhas em cada etapa. Sua matriz de testes deve incluir validação antes das credenciais, cofre bloqueado, consentimento recusado, respostas remotas 401 e 403, limitação de taxa, falha de DNS, falha na validação de TLS, timeout antes que os bytes saiam, timeout depois que os bytes saiam, JSON inválido do upstream e uma exceção lançada pelo próprio gateway.

Para cada caso, verifique quatro pontos:

• A resposta da ferramenta contém o código esperado e a ação permitida.
• O segredo do fixture não aparece em nenhum campo serializado visível ao chamador.
• A resposta não contém cabeçalhos brutos, texto bruto do corpo do upstream nem detalhes locais da conexão.
• O registro de diagnóstico protegido contém o ID da solicitação e estado suficiente para que uma pessoa operadora investigue.

Não se limite a verificações com expressões regulares. Procure o segredo exato do fixture, sua forma codificada em URL, sua forma em base64 quando relevante e prefixos ou sufixos comuns. Depois, inspecione manualmente uma resposta de erro capturada sempre que atualizar uma dependência HTTP, SSH, de telemetria ou de geração de relatórios de falha. As bibliotecas alteram a formatação das exceções sem pedir sua permissão.

A parte difícil é resistir à vontade de fazer o erro do agente se parecer com o console de depuração da pessoa operadora. Mantenha o contrato do chamador pequeno, estável e orientado a ações. Mantenha as evidências protegidas e correlacionadas. Quando chegar a próxima interrupção, essa separação dará ao agente o suficiente para agir com segurança e à pessoa o suficiente para corrigir a falha real.