Ferramentas de agentes sem segredos: contratos de ação que resistem

Os agentes devem solicitar ações, não receber os meios para se passar por uma pessoa ou por uma conta de serviço. Isso parece óbvio até você examinar uma ferramenta de agente típica: uma função http_request aceita URL, cabeçalhos, método e corpo, enquanto o agente recebe um bearer token de uma variável de ambiente. A chamada da ferramenta parece organizada. A autoridade está espalhada pelo texto do prompt, pela memória do processo, pelos logs, pelo histórico do shell e por qualquer subprocesso que o agente iniciar em seguida.

Um design sem segredos cria uma fronteira rígida entre intenção e execução. O agente diz: «crie uma implantação para este serviço neste ambiente». Uma camada que possui as credenciais decide se a ação pode ser executada, escolhe a identidade correta, faz a chamada autenticada e retorna o resultado. Isso muda o que você pode auditar, aprovar e revogar. Também obriga você a escrever interfaces que realmente mereçam autonomia.

Um contrato deve descrever a intenção, não o transporte

Um contrato de ação nomeia a operação que uma pessoa reconhece e limita suas entradas aos fatos necessários para essa operação. Os detalhes de transporte ficam atrás da fronteira. A diferença é fácil de ignorar porque o HTTP faz toda ação parecer um método, uma URL, cabeçalhos e um corpo JSON.

Considere duas interfaces de ferramenta para abrir uma solicitação de mudança. A primeira é comum e insegura para um processo autônomo:

{
  "name": "http_request",
  "input": {
    "method": "POST",
    "url": "https://code.example/api/projects/alpha/changes",
    "headers": {
      "Authorization": "Bearer ${TOKEN}",
      "Content-Type": "application/json"
    },
    "body": {
      "title": "Fix timeout",
      "branch": "agent/fix-timeout"
    }
  }
}

Essa interface dá ao agente autoridade sobre o destino, o método de autenticação e o formato da solicitação. Remover o token literal não resolve o problema se o agente puder escolher um alias de cabeçalho, um identificador de credencial, uma URL de proxy ou um comando de shell que leia um token em outro lugar. Você moveu o segredo, mas não reduziu a autoridade.

Uma interface orientada por contrato se parece mais com isto:

{
  "name": "create_change_request",
  "input": {
    "project": "alpha",
    "source_branch": "agent/fix-timeout",
    "title": "Fix timeout in retry path",
    "description": "Adds a bounded retry and a regression test."
  }
}

A camada de execução mapeia project para um endpoint conhecido e uma conta aprovada. Ela mesma fornece o cabeçalho de autenticação. Pode recusar o nome da branch, verificar o repositório de destino, pedir aprovação ou retornar um erro do serviço remoto. O agente não tem nenhum parâmetro que signifique «use a credencial que conceder mais acesso».

Essa é uma distinção que as pessoas confundem com frequência: não ter segredos não é o mesmo que ocultar tokens. A ocultação tenta controlar o que o agente vê depois que ele recebe autoridade. Um contrato de ação impede que o agente tenha essa autoridade desde o início. Se um prompt de modelo vazar, se uma transcrição de ferramenta for copiada ou se um subprocesso ler o ambiente, o primeiro design já perdeu uma credencial. O segundo pode expor dados operacionais, que precisam de seus próprios controles, mas não entrega o material de assinatura.

Um contrato também não deve fingir que todo endpoint merece uma ferramenta personalizada. Ações personalizadas fazem sentido quando uma pessoa consegue declarar o resultado pretendido em uma frase. «Reinicie esta carga de trabalho de staging» é um resultado. «Envie um PATCH para qualquer URL» é um primitivo de transporte. Se você precisa do primitivo para um trabalho de manutenção, entregue-o a uma integração separada e rigorosamente limitada, não a um agente de programação de uso geral.

O proprietário da credencial deve executar a solicitação

Um contrato não protege nada se o agente ainda fizer a chamada de rede final com um segredo montado em seu processo. O componente que armazena a credencial deve fazer a própria solicitação HTTP ou conexão SSH.

Isso significa que a fronteira de execução tem cinco responsabilidades:

• Resolver o nome da ação para um destino fixo e um comportamento de protocolo definido.
• Escolher uma identidade armazenada de um pequeno conjunto aprovado.
• Injetar a credencial apenas na solicitação de saída ou na autenticação SSH.
• Registrar a solicitação, a decisão e o resultado sem gravar material secreto no registro.
• Retornar uma resposta moldada para a ação, não uma cópia do estado interno.

O processo do modelo não deve receber um token nem uma chave privada, nem mesmo temporários. Evite convenções de shell como TOKEN=$(vault read ...), arquivos de credenciais no diretório de trabalho, valores de Authorization em comandos curl gerados e agentes SSH compartilhados com um shell executado pelo agente. Cada uma parece conveniente porque preserva scripts existentes. Cada uma transforma o processo do agente em um proprietário de credenciais.

O OAuth 2.0 Security Best Current Practice do IETF destaca o mesmo ponto prático em outro contexto: bearer tokens precisam ser protegidos em armazenamento e trânsito porque qualquer pessoa que possua um pode usá-lo. Um bearer token não se torna seguro por você dizer a um modelo para não imprimi-lo. A posse é a verificação de autorização. Para uma ferramenta de agente, o design melhor é evitar que o processo tenha a posse.

No SSH, a fronteira precisa controlar mais que a chave privada. Uma interface bruta como ssh host command dá ao agente amplo alcance mesmo quando a chave nunca sai de um auxiliar. O auxiliar deve selecionar uma definição de host e uma identidade armazenadas, e então impor um formato de comando adequado a esse host. Um host de implantação pode permitir status, restart-service e tail-release-log com um nome de serviço. Ele não deve aceitar silenciosamente bash -c só porque alguém quis um atalho.

Não confunda isso com um proxy man-in-the-middle. Um proxy retransmite tráfego arbitrário do cliente e costuma ver as credenciais em trânsito. Uma camada de ações que possui as credenciais recebe uma solicitação para uma operação nomeada, constrói a chamada de saída e mantém a credencial em seu próprio cofre. A distinção determina se o agente pode transformar uma ação aprovada em outra.

O design dos parâmetros decide quanta autoridade vaza

Cada campo de um contrato cria um grau de liberdade. Bons campos identificam o objeto de trabalho ou fornecem conteúdo de que a ação realmente precisa. Campos ruins alteram para onde vai a autoridade, qual identidade será usada ou qual operação de baixo nível será executada.

Aplique este teste a cada entrada proposta: se o agente mudar este valor, poderá redirecionar uma solicitação privilegiada para outro sistema, ampliar o conjunto de recursos afetados ou alterar a autenticação? Se a resposta for sim, remova o campo, transforme-o em um enum mapeado pelo executor ou divida a operação em contratos separados.

Uma interface de implantação ilustra o ponto:

{
  "name": "deploy_release",
  "input_schema": {
    "type": "object",
    "additionalProperties": false,
    "required": ["service", "environment", "version", "reason"],
    "properties": {
      "service": {"type": "string", "enum": ["api", "worker"]},
      "environment": {"type": "string", "enum": ["test", "production"]},
      "version": {"type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"},
      "reason": {"type": "string", "maxLength": 500}
    }
  }
}

O esquema impede campos inesperados como url, headers, credential_name ou command. O executor pode mapear service e environment para um destino de implantação conhecido. additionalProperties: false é mais importante do que parece. Sem ele, um validador permissivo pode preservar um campo não reconhecido, e alguém pode conectá-lo depois a um cliente HTTP «por flexibilidade». É assim que um ponto de extensão aparentemente inofensivo vira uma saída para credenciais.

Enums nem sempre são a resposta. Um nome de repositório, branch, número de tarefa ou caminho de arquivo pode precisar variar. Valide esses valores de acordo com seu domínio e aplique uma verificação de fronteira após a resolução. Por exemplo, resolva um identificador de repositório por meio de uma lista de permissões local e use a localização remota mapeada. Não aceite uma URL de repositório para depois decidir se ela parece segura.

Texto livre exige uma avaliação separada. Um agente pode precisar escrever a descrição de uma tarefa, o resumo de um pull request ou uma resposta de suporte. Esse texto é conteúdo, não autoridade, mas ainda pode causar danos por meio de menções, marcação, modelos ou comandos incorporados consumidos pelo serviço de destino. Limite seu tamanho, deixe explícito como será renderizado e nunca o interpole em um comando de shell. Quando uma ação precisar executar um comando, construa diretamente o vetor de argumentos e mantenha o texto não confiável em um argumento de dados, nunca em uma string de comando.

Ferramentas genéricas de solicitação criam mecanismos de políticas ocultos

Uma ferramenta HTTP genérica é popular porque permite conectar um agente a qualquer serviço em uma tarde. Ela é inadequada para a maioria dos trabalhos privilegiados de agentes porque cada prompt, descrição de ferramenta e ramo de código vira uma política informal de autorização.

Uma equipe costuma começar com um wrapper como:

request(method, url, headers, body)

Depois adiciona barreiras. Bloqueia alguns domínios. Remove Authorization. Permite certos métodos. Analisa um prefixo de URL. Rejeita localhost. Exige uma caixa de aprovação para chamadas arriscadas. Meses depois, alguém precisa de um novo endpoint com um cabeçalho personalizado, adiciona uma exceção e o wrapper passa a ter uma linguagem de políticas sem testes nem responsável claro.

O problema não é que ferramentas genéricas sejam sempre ruins. Elas servem para um console de depuração operado por uma pessoa, em que o operador já possui a autoridade e pode inspecionar cada byte. Também servem para um serviço de integração que recebe chamadas de código sob seu controle e tem uma identidade de rede limitada. Um agente autônomo é diferente porque pode fazer muitas chamadas, descobrir caminhos inesperados e agir sobre texto não confiável. Ele precisa de menos graus de liberdade.

Crie ações nomeadas em torno de unidades de trabalho estáveis. Para um serviço de controle de código-fonte, prefira read_merge_request, comment_on_merge_request e create_branch a um cliente REST universal. Para operações, prefira get_service_status, fetch_release_logs e request_deployment. Você talvez precise de mais contratos, mas cada um terá um responsável, um conjunto de testes, um rótulo de aprovação claro e um raio de impacto que pode ser revisado.

Também não esconda uma solicitação genérica dentro de uma ação nomeada. Uma ferramenta chamada update_ticket que aceita path, method e body arbitrários só mudou o rótulo. O contrato precisa vincular esses detalhes. Ele pode expor um objeto de patch controlado quando a API de destino exigir isso, mas o executor deve decidir o endpoint, o método HTTP, o tipo de conteúdo e a conta.

A especificação do Model Context Protocol ajuda na descoberta de ferramentas porque permite que um servidor publique nomes, descrições e esquemas de entrada JSON para um cliente. Esse esquema é útil, mas não torna segura uma ação ampla demais. Um JSON Schema pode informar que uma URL é uma string. Ele não pode informar que essa URL é o único endpoint de cobrança ao qual sua credencial de produção deve chegar. A autorização continua sendo responsabilidade da camada de execução.

A aprovação deve nomear a ação que uma pessoa pode avaliar

A aprovação humana funciona quando a pessoa vê uma solicitação reconhecível e pode recusá-la rapidamente. Ela falha quando o prompt pede aprovação para um pacote opaco de detalhes de transporte depois que o agente já tomou as decisões importantes.

Compare estes cartões de aprovação:

Allow POST https://api.example/v1/resources/882?
Headers: Authorization, X-Region, X-Client

Deploy version 2.14.3 of api to production
Reason: Fixes failed payment retries
Requested by: signed agent process build-worker

O segundo cartão permite que o operador avalie a intenção. Ele também dá ao registro de auditoria uma frase útil. O primeiro pede que o operador reconstrua o significado a partir de uma URL e de uma lista de cabeçalhos, o que favorece a fadiga de aprovação. As pessoas clicam em prompts ilegíveis, especialmente quando uma execução normal do agente cria vários deles.

Use a aprovação no ponto em que uma decisão muda a autoridade. Uma camada de execução pode autorizar um novo processo de agente uma vez por sessão e exigir uma nova decisão para credenciais sensíveis selecionadas ou ações destrutivas. Essa separação mantém o trabalho rotineiro utilizável sem tratar todas as credenciais como equivalentes. Um token de projeto somente leitura e uma identidade de implantação de produção não devem compartilhar uma regra de aprovação apenas porque ambos viajam em cabeçalhos HTTP.

A linguagem da aprovação deve dizer quem solicitou a operação. A identidade do processo é útil porque um agente no terminal, um auxiliar em segundo plano e um executável desconhecido não merecem o mesmo nível de confiança. No macOS, a autoridade de assinatura de código pode fornecer à pessoa que aprova uma execução um sinal concreto de origem. Isso não prova que toda instrução do prompt é segura, mas responde à primeira pergunta: qual processo está pedindo para agir com esta conta?

Nunca faça da aprovação o único controle. Uma pessoa pode interpretar mal um prompt, aprovar sob pressão ou deixar uma sessão aberta. O contrato ainda precisa de entradas restritas e uma rota fixa para a credencial. Da mesma forma, não crie uma linguagem de políticas quando um contrato de ação claro e uma escolha de aprovação já resolvem a necessidade. Regras que comparam campos arbitrários, janelas de tempo, expressões regulares e declarações de usuário rapidamente viram outro programa que ninguém consegue revisar com confiança durante um incidente.

Uma implantação malsucedida mostra onde contratos frouxos falham

Uma falha conhecida começa com um agente que pode fazer implantações em test por meio de uma ferramenta de shell. A equipe armazena um token de nuvem no ambiente do agente porque a CLI de implantação espera por ele. O esquema da ferramenta aceita environment e extra_args, que pareciam inofensivos quando só existia test.

Uma tarefa pede ao agente para «verificar a correção urgente em test e compartilhar o resultado». O agente executa o comando esperado. Depois encontra uma mensagem antiga de implantação no repositório e tenta um argumento extra copiado de um script antigo. Esse argumento seleciona production, altera uma conta de destino ou injeta uma expansão de shell. O token tinha escopo de produção porque manter credenciais separadas parecia trabalhoso. Nesse ponto, a formulação do prompt não salva você. O processo já possui autoridade ampla e a interface permite que ele escolha o destino.

Uma fronteira de contrato muda a sequência:

1. O agente chama deploy_release com serviço, ambiente, versão e motivo enumerados.
2. O executor resolve o ambiente para um destino fixo e seleciona a identidade atribuída a esse destino.
3. O executor pede uma decisão se essa identidade exigir uma, e então registra o resultado na execução do agente que fez a solicitação.
4. O executor retorna um identificador e o status da implantação, ou uma recusa estruturada que informa ao agente por que ele não pode prosseguir.

O agente não pode adicionar --account, definir um endpoint de nuvem nem ler um token. Um valor incorreto de production continua sendo possível, pois pessoas e modelos podem pedir a coisa errada. Mas o texto da aprovação agora diz production em linguagem clara, a identidade selecionada pode ter apenas a autoridade pretendida para implantações de produção e o registro da ação vincula a decisão ao processo e à solicitação.

Essa distinção importa durante o diagnóstico. No design frouxo, os investigadores costumam encontrar fragmentos: uma transcrição do shell, eventos de auditoria da nuvem, um log de CI e talvez um valor de token que agora precisa ser substituído. No design baseado em contratos, eles podem examinar a ação solicitada, o destino resolvido, o rótulo da identidade, o resultado da aprovação, o status da resposta e a sessão que iniciou tudo. Um registro de auditoria não apaga um erro, mas reduz o tempo gasto tentando descobrir qual caminho foi executado.

As respostas de erro devem orientar a recuperação sem expor detalhes internos

Uma camada segura de ações deve retornar erros sobre os quais um agente possa agir sem receber o segredo, dados de assinatura da solicitação ou a estrutura interna do cofre. Falhas vagas levam os agentes a tentar novamente e procurar alternativas. Falhas detalhadas demais transformam os logs de erro em um canal de informação.

Use códigos de erro estáveis e um formato público pequeno:

{
  "ok": false,
  "error": {
    "code": "APPROVAL_REQUIRED",
    "message": "Deployment to production needs user approval.",
    "retryable": true,
    "request_id": "act_01H..."
  }
}

Um cofre bloqueado deve informar VAULT_LOCKED; uma decisão de usuário que recusou a ação deve informar APPROVAL_DENIED; uma violação do contrato deve informar INVALID_ARGUMENT; um 429 do serviço remoto pode informar REMOTE_RATE_LIMITED. O agente pode comunicar o estado, aguardar, tentar novamente quando a condição indicada mudar ou escolher uma alternativa não destrutiva. Ele não deve receber um erro que inclua um cabeçalho de autorização bruto, dados do assunto do token, configuração de host privado ou uma solicitação assinada completa.

Separe falha de autorização de falha remota. «Permissão negada» pode significar que o executor local recusou a ação, que a conta remota selecionada não tem permissão ou que o serviço de destino rejeitou uma autenticação malformada. Cada caso exige uma correção diferente. A mensagem pública pode continuar concisa, enquanto o registro de auditoria protegido do executor guarda o motivo preciso e o status remoto.

As tentativas repetidas precisam de semântica de contrato. Operações de leitura costumam tolerar novas tentativas. Criar uma tarefa, enviar uma mensagem ou iniciar uma implantação pode não tolerar. Inclua um identificador de idempotência quando a API remota oferecer suporte, gerado pelo executor ou fornecido como um identificador de solicitação restrito. Registre a associação antes de enviar a solicitação e reutilize-a em uma nova tentativa. Não deixe que um agente invente novos identificadores sempre que encontrar um timeout, pois ele pode criar trabalho duplicado tentando ajudar.

Para ações sem suporte remoto a idempotência, use uma preparação seguida de confirmação. A ação de preparação retorna um plano de curta duração com o destino e a diferença. A ação de confirmação referencia esse plano e exige uma aprovação atual. Isso custa uma ida e volta extra, mas é mais barato que repetir um pagamento, uma exclusão ou uma alteração de produção depois de uma falha de rede ambígua.

Os registros de auditoria precisam de duas visões e uma fonte de verdade

Um sistema de auditoria útil responde a duas perguntas diferentes: o que esta tentativa de execução do agente fez e o que cada chamada privilegiada realizou? Se você juntar tudo em um único fluxo de eventos indiferenciado, será difícil reconstruir uma sessão ou encontrar uma solicitação específica.

Mantenha um diário de sessão para a execução. Ele deve mostrar a identidade do processo, início e fim, decisão de autorização, estado de revogação e ações solicitadas durante a execução. Mantenha um diário de atividades para as chamadas. Ele deve mostrar o nome da ação, parâmetros normalizados, rótulo da credencial selecionada sem o segredo, resultado da aprovação, horários, classe do destino e resultado.

As duas visões devem derivar do mesmo registro somente de acréscimo. Caso contrário, a tela da sessão e o log de chamadas podem discordar quando um gravador falhar ou filtrar eventos de maneira diferente. Um log criptografado que não precisa ser lido para receber novas gravações também tem uma vantagem prática: o componente que acrescenta um evento não precisa descriptografar registros antigos apenas para gravar um novo.

A evidência contra adulteração precisa de uma verificação offline. Uma cadeia de hashes permite que um verificador detecte exclusão, substituição ou reordenação de registros quando possui a sequência do log. A verificação deve ser feita sobre o texto cifrado, para que um auditor confirme a continuidade sem receber a chave do cofre. Isso não prova que uma máquina comprometida nunca deixou de registrar um evento. Prova que uma cadeia mantida não foi editada silenciosamente depois. Trate essas afirmações como coisas diferentes.

Um verificador de linha de comando deve tornar as falhas compreensíveis. A saída pode ser simples:

$ sp audit verify audit.log
verified: 184 records
first sequence: 9012
last sequence: 9195
chain: valid

Se o registro 9137 tiver sido alterado, o comando deve identificar a primeira sequência quebrada e terminar com código diferente de zero. Não informe apenas «verification failed». Quem responde a incidentes precisa saber onde as evidências deixam de ser confiáveis.

O Sallyport usa essa divisão entre sessões de agentes e atividades individuais, projetando ambas a partir de um único registro de auditoria criptografado e encadeado por hash que sp audit verify pode verificar sem a chave do cofre. Esse é o formato adequado para um gateway local de agentes, porque revogar uma sessão em execução e investigar uma chamada individual são tarefas diferentes.

Os contratos precisam de testes que tentem escapar deles

Testes de caminho feliz provam que uma ação funciona. Testes de segurança provam que as entradas declaradas são os únicos controles disponíveis para quem chama. Escreva esses testes antes de adicionar um parâmetro de conveniência, pois é por esses parâmetros que a autoridade costuma voltar a crescer.

Para cada ação, teste pelo menos estes casos:

• Recusar um campo inesperado, incluindo headers, url, command e referências a credenciais.
• Recusar valores que sejam resolvidos fora do conjunto de recursos permitido pela ação.
• Confirmar que as solicitações HTTP de saída recebem credenciais somente depois que o executor constrói o destino.
• Confirmar que as entradas de auditoria não incluem valores de tokens, material de chaves privadas nem campos de autorização assinados.
• Confirmar que uma sessão recusada ou revogada não pode reutilizar uma aprovação anterior.

Use um servidor de saída falso nos testes e inspecione a solicitação recebida. O teste deve verificar a URL, o método, os cabeçalhos construídos pelo executor e a ausência de autenticação controlada pelo chamador. Simular apenas o cliente interno do executor deixa de fora a pergunta importante: o que sairia da máquina se o agente fornecesse parâmetros hostis?

Teste também as entradas estranhas que um modelo eventualmente produzirá: um identificador de repositório com prefixo de esquema, um nome de branch com pontuação de shell, um caractere Unicode parecido em um rótulo de ambiente, campos JSON repetidos, uma descrição enorme e um timeout depois que o serviço remoto aceitou a ação. A validação do contrato deve falhar de forma segura. Se o executor não puder resolver um destino solicitado com confiança, deve recusar a chamada e retornar um erro útil.

Revise contratos como código com autoridade. Pergunte se um novo campo dá ao chamador um caminho para outro host, uma conta mais ampla, um comando diferente ou outra classe de objeto. Se der, torne a autoridade explícita no nome da ação e no comportamento da aprovação. Uma ação simples como delete_file com um caminho absoluto livre é muito mais difícil de analisar que remove_preview_asset com um identificador de ativo resolvido dentro de um projeto conhecido.

O primeiro contrato que vale a pena corrigir costuma ser aquele que aceita uma URL arbitrária ou uma string de shell. Substitua-o pela menor ação nomeada que cubra o trabalho de que as pessoas realmente precisam. A interface fica menos engenhosa, e o agente fica menos poderoso de maneiras que você não precisará explicar depois. Isso é progresso.