Acesso de agentes de IA a APIs: tokens diretos ou ações mediadas?

Um agente de programação com IA não deve receber um token SaaS geral só porque precisa chamar uma API. Entregar o token diretamente transforma o processo do agente em um portador de credencial, com todas as formas comuns de vazamento: um comando detalhado demais, um subprocesso, um pacote de diagnóstico enviado para outro lugar, o resultado de uma ferramenta ou uma instrução que manda o agente imprimir sua configuração.

Isso não significa que toda chamada de API precise de um ritual. Significa separar a autoridade para executar uma ação da posse da credencial que a autoriza. Dê ao agente uma forma limitada de solicitar trabalho útil, mantenha a credencial no componente que executa a ação e inclua uma decisão humana quando a consequência justificar isso.

Essa diferença costuma passar despercebida porque um comando curl bem-sucedido parece inofensivo. O problema começa quando o agente pode criar uma implantação em produção, fechar um chamado de cliente, alterar uma issue ou executar um comando remoto. Nesse momento, o token deixa de ser um detalhe de configuração. Ele passa a ser autoridade operacional sem julgamento associado.

Entregar o token diretamente transforma o agente em uma fronteira de credenciais

Quando você coloca SAAS_TOKEN no ambiente do agente, em um arquivo de configuração, na definição de uma ferramenta ou em um repositório de segredos acessível pelo prompt, o agente pode fazer solicitações autenticadas sem que outro componente decida se cada solicitação faz parte da tarefa. O token pode ter escopos razoáveis, mas ainda fica disponível para todos os comportamentos daquele processo e, muitas vezes, para os programas que ele inicia.

Desenvolvedores costumam dizer que o agente não consegue «ver» uma variável de ambiente. Essa afirmação não resiste ao uso normal de ferramentas. Um agente pode pedir ao shell que inspecione o ambiente, executar um script que herda a variável, rodar uma ferramenta de testes com logs de depuração ou gravar uma cópia da configuração em um repositório. O caminho exato depende do agente e de suas ferramentas. Por isso, a suposição segura é simples: se o processo consegue usar diretamente um token bearer, normalmente também pode fazer o token aparecer em algum lugar que você não planejou.

Um token bearer tem outra característica desagradável. O serviço SaaS não consegue distinguir o agente pretendido de qualquer pessoa que tenha copiado a string. A especificação RFC 6750, OAuth 2.0 Bearer Token Usage, afirma que tokens bearer precisam ser protegidos contra divulgação durante o armazenamento e o trânsito, pois possuí-los já é suficiente para usá-los. Isso não é uma formulação acadêmica. Depois que um agente imprime o token em um log de build, o serviço vê um chamador válido, não um erro.

O acesso direto também confunde a responsabilidade. Os logs de auditoria do serviço podem identificar uma conta de robô, mas raramente informam qual execução do agente criou a solicitação, quais instruções recebeu, qual usuário a iniciou ou se alguém aprovou o efeito resultante. Você obtém um evento da API depois do fato, mas não a trilha de decisão que o explica.

Um token direto pode ser tolerável em um sandbox local descartável quando todas estas condições forem verdadeiras:

• O token expira rapidamente e tem apenas o escopo mínimo fora de produção.
• O destino não contém dados de clientes, funcionários ou produção.
• O agente executa em um ambiente isolado que pode ser descartado.
• Uma pessoa consegue revogar a credencial sem interromper o trabalho compartilhado.

As equipes transformam essa exceção em prática rotineira porque copiar um token é rápido. A velocidade é real, mas também é real o trabalho de limpeza quando o token cai em um artefato ou quando o agente segue uma instrução maliciosa inserida na descrição de uma issue.

Escopos limitam permissões, mas não controlam a intenção

Escopos OAuth, funções de API e permissões de repositório respondem a «o que esta identidade pode fazer?». Eles não respondem a «esta solicitação deve acontecer agora?». São controles diferentes, e tratá-los como equivalentes deixa uma grande lacuna.

Considere um token de rastreador de issues com permissão para editar issues em um projeto. Esse escopo pode ser correto para um agente encarregado de classificar bugs. Uma injeção de prompt em uma issue importada ainda pode mandar o agente fechar todas as issues abertas, alterar prioridades ou publicar comentários enganosos. Cada solicitação está dentro do escopo. Ainda assim, todas podem estar erradas.

O mesmo problema aparece em uma plataforma de implantação. Um token limitado a um aplicativo não sabe se o agente deve implantar o commit atual, reverter uma versão, alterar uma variável de ambiente ou excluir um ambiente de prévia. O serviço vê chamadas de API autorizadas. Apenas o seu fluxo de trabalho pode decidir se elas correspondem à tarefa e a um destino aceitável.

As boas práticas atuais de segurança do OAuth 2.0 do IETF recomendam tokens de curta duração, tokens vinculados ao emissor quando possível e privilégios mais estreitos para reduzir os danos de tokens bearer copiados. São boas práticas. Elas reduzem a vida útil e o alcance de uma credencial copiada. Não acrescentam aprovação a uma ação destrutiva, embora corretamente limitada, nem explicam a intenção do agente.

Não responda criando um catálogo enorme de regras que tente prever cada endpoint e argumento. As equipes criam esses catálogos e depois passam meses mantendo exceções para novas APIs e procedimentos de lançamento incomuns. Uma interface estreita de ações, combinada com aprovação humana no momento certo, costuma funcionar melhor no trabalho real do que uma linguagem de políticas que ninguém consegue ler com segurança.

Rastreadores de issues precisam de caminhos de escrita que preservem o julgamento humano

Rastreadores de issues parecem ter baixo risco até que um agente comece a fazer alterações em grande volume. Fechar uma issue pode ocultar um relato de cliente. Alterar labels pode quebrar relatórios de triagem. Publicar um comentário pode expor raciocínios internos a colaboradores externos. Adicionar uma pessoa a um chamado pode ampliar o acesso a um contexto sensível.

Separe o trabalho do agente entre observação e mutação. Permita que ele recupere issues, pesquise labels, examine pull requests relacionadas e prepare uma alteração proposta. Encaminhe a mutação final por uma ação que informe o projeto, a issue, os campos alterados e o texto do comentário. O revisor deve ver o conteúdo real antes que o serviço o receba.

Um contrato de solicitação torna essa fronteira concreta. O agente deve enviar uma intenção estruturada, não montar uma linha de comando que carregue credenciais.

{
  "service": "issue-tracker",
  "action": "update_issue",
  "issue": "APP-184",
  "changes": {
    "labels_add": ["needs-reproduction"],
    "comment": "I reproduced this on the current release and attached the failing test."
  }
}

O executor deve injetar sua própria credencial e retornar um resultado limitado:

{
  "ok": true,
  "issue": "APP-184",
  "updated_fields": ["labels", "comment"],
  "request_id": "service-request-id"
}

Não retorne o cabeçalho Authorization bruto, um rastreamento HTTP completo nem um objeto de depuração que inclua segredos. Isso parece óbvio até que alguém habilite diagnósticos HTTP detalhados durante uma integração difícil. Mantenha os diagnósticos em um caminho de solução de problemas operado por uma pessoa e teste a ocultação de dados, em vez de apenas presumir que ela funciona.

Um agente ainda pode tomar uma decisão ruim depois que uma pessoa aprova a sessão. Por isso, alterações destrutivas em issues merecem uma opção de aprovação separada. A autorização da sessão responde se o programa em execução pode usar a integração. A aprovação por chamada responde se aquela mutação específica deve ocorrer. A diferença é mais importante quando o agente consegue ler texto não confiável em chamados, documentos ou comentários de pull requests.

APIs de implantação têm consequências que vão além do botão de lançamento

Uma API de implantação geralmente expõe mais do que «implantar esta versão». Ela pode alterar variáveis de ambiente, iniciar builds, reiniciar cargas de trabalho, criar domínios, reverter versões, buscar logs ou excluir recursos. Um token amplo de implantação vira um controle remoto conveniente para um agente que já elaborou um plano errado.

Use categorias de ação diferentes para o trabalho de implantação. Ler o status de um build e recuperar os metadados públicos de uma implantação costuma ser rotina. Promover um artefato para produção, reverter uma versão, alterar uma referência de segredo e excluir um ambiente têm consequências diferentes. Não agrupe tudo em uma aprovação única chamada «acesso à implantação».

Uma solicitação adequada pede uma referência imutável ao artefato e um destino explícito. Rejeite entradas vagas como «latest» quando o serviço puder resolver um commit, digest de imagem ou identificador de build. Labels mutáveis criam um intervalo entre aprovação e execução: o revisor aprova uma coisa, mas a ação executa outra.

{
  "service": "deployment-platform",
  "action": "promote_release",
  "application": "billing-api",
  "environment": "production",
  "artifact": {
    "git_commit": "8cf4f3a",
    "build_id": "build-4921"
  },
  "reason": "Fixes the confirmed invoice retry failure"
}

O executor deve verificar se os identificadores aprovados correspondem à solicitação que enviará. Também deve registrar o identificador retornado pelo serviço e o ambiente de destino. Registrar apenas «implantação concluída» ajuda muito pouco às duas da manhã, quando alguém pergunta qual artefato foi movido e quem o autorizou.

Não faça o agente extrair informações de um painel web para compensar uma API mal planejada. A automação do navegador esconde detalhes da revisão, quebra sem aviso e pode clicar em uma página desatualizada. Se a plataforma oferecer uma API, use uma ação mediada e estreita sobre essa API. Se oferecer apenas um painel, aceite que algumas operações continuarão sendo trabalho humano até que você consiga criar um conector confiável.

Ferramentas de suporte ao cliente exigem minimização de dados antes da automação

Sistemas de suporte ao cliente combinam ações operacionais com dados pessoais. Um ticket pode conter dados da conta, informações de contato, anexos, histórico de pedidos, logs e mensagens carregadas de emoção. O acesso direto do agente levanta duas perguntas: ele consegue ler material de que não precisa e consegue enviar uma resposta prejudicial em nome da empresa?

Não resolva isso enviando por padrão a transcrição completa dos tickets ao agente. Busque apenas os campos necessários para a tarefa. Se o agente precisa classificar um ticket, talvez precise do assunto, de um corpo redigido e da área do produto. Provavelmente não precisa de todas as notas internas anteriores, do registro de cobrança ou dos anexos.

Ações de escrita precisam de uma revisão mais rigorosa do que a classificação. Um padrão útil é preparar primeiro e enviar depois. O agente cria uma proposta de resposta com referências ao ticket e a qualquer fonte interna consultada. Uma pessoa verifica o tom, as afirmações factuais, os detalhes específicos da conta e se a resposta revela acidentalmente notas internas. Só então um executor deve publicar a mensagem.

Fechar, mesclar ou reatribuir tickets também exige semântica explícita de ação. «Resolver ticket» é vago demais se enviar silenciosamente um e-mail de encerramento, alterar o relógio de um acordo de nível de serviço ou excluir um rascunho. O esquema da solicitação deve identificar o efeito colateral que o serviço de suporte executará.

É nesse ponto que uma conta de serviço ampla se torna especialmente tentadora. Ela evita dificuldades de permissão e permite que o agente cuide de qualquer fila. Também significa que uma única instrução incorreta pode atravessar limites entre contas. Atribua identidades de serviço a filas ou equipes quando o provedor permitir e limite a interface de ações mediadas às operações de que aquela equipe realmente precisa.

SSH é autoridade de execução, não uma credencial de API com outra sintaxe

O SSH merece tratamento separado porque uma chave privada pode levar a um shell, transferência de arquivos, encaminhamento de portas e acesso a ferramentas que têm suas próprias credenciais. Uma API de implantação pode oferecer um conjunto finito de operações. Um shell remoto pode combinar novas operações no momento.

Dar uma chave privada SSH a um agente de programação cria dois riscos ao mesmo tempo. A chave pode vazar e o agente pode gerar comandos remotos arbitrários. Restringir a conta ajuda, mas uma conta restrita com acesso a scripts de implantação, credenciais de CLI da nuvem ou configurações de produção ainda pode fazer muito mais do que a tarefa original sugeria.

Use um mediador que mantenha a chave privada e receba o host, o comando e os argumentos solicitados. Faça com que a ação registre o host resolvido e o comando exato depois do tratamento dos argumentos. Não aprove uma string de shell que o agente possa reinterpretar depois por meio de aspas aninhadas, substituição de comandos ou um script remoto baixado de um branch não confiável.

Para hosts sensíveis, prefira operações remotas fixas ao acesso geral ao shell. Um comando como release-status --service billing-api é mais fácil de revisar do que bash -lc '...'. Se for necessário permitir um comando geral, mostre-o exatamente como será executado e exija aprovação por chamada. Trate sudo, instalação de pacotes, leitura de arquivos de segredos, redirecionamento do shell e comandos de cópia para fora da rede como casos de maior risco, não como manutenção comum.

A verificação do host SSH também importa. O cliente deve verificar a chave do servidor contra uma entrada conhecida gerenciada. Aceitar automaticamente a impressão digital de um host novo permite que um erro de rede ou DNS se transforme em um evento de uso de credencial. Isso anula o cuidado de esconder a chave privada.

Ações mediadas contêm credenciais e criam um ponto de decisão

Um sistema de ações mediadas mantém o token SaaS ou a chave privada SSH dentro de um executor e oferece ao agente uma interface para pedir que ele execute um trabalho definido. O executor anexa as credenciais, faz a solicitação e retorna o resultado. O agente nunca recebe um segredo, nem mesmo um marcador que poderia substituir acidentalmente em um comando.

Isso muda o modo de falha. Um agente com acesso direto que aceita uma instrução maliciosa pode decidir e executar uma ação usando uma credencial reutilizável. Um agente mediado ainda pode solicitar uma ação ruim, pois nenhum controle de segurança torna perfeito o julgamento de um modelo de linguagem. Mas o executor pode identificar o chamador, exigir que uma pessoa aprove a chamada, manter as credenciais indisponíveis ao agente e registrar a solicitação e o resultado.

O Sallyport usa esse modelo para chamadas de APIs HTTP e comandos SSH: um agente compatível com MCP se conecta por meio de sp mcp, enquanto o aplicativo macOS mantém as credenciais de API e SSH em seu cofre criptografado e executa as ações. O bloqueio do cofre nega todas as ações enquanto ele estiver trancado, que é o comportamento correto quando a pessoa responsável está longe da máquina.

Não confunda um mediador com um proxy man-in-the-middle. Um proxy observa ou retransmite tráfego geral. Um gateway de ações recebe uma solicitação específica, aplica seus controles de autorização, usa uma credencial que mantém consigo e retorna um resultado. Esse formato mais restrito é útil porque fornece um ponto de aprovação e um registro de auditoria, em vez de tentar interpretar todo o tráfego depois que o agente já o formou.

As melhores interfaces mediadas são deliberadamente simples. Elas expõem poucos verbos compreensíveis, aceitam parâmetros estruturados, rejeitam destinos ambíguos e informam o suficiente para verificar o efeito. Um endpoint universal que aceita URLs, cabeçalhos e corpos arbitrários pode recriar silenciosamente o acesso direto, apenas com mais etapas.

O design da aprovação falha quando as pessoas não conseguem avaliar a solicitação

Um aviso de aprovação deve ajudar uma pessoa a decidir, não apenas interrompê-la. «O agente solicita acesso à ferramenta de suporte» pede que o revisor aprove um futuro desconhecido. «Publicar esta resposta no ticket 4821 como a equipe de suporte» oferece uma ação concreta para inspeção.

Na primeira chamada de um novo processo de agente, mostre a identidade do processo e a autoridade de assinatura de código. A identidade do processo não é decoração. Em uma máquina de desenvolvimento, vários terminais, extensões e programas auxiliares podem solicitar a mesma integração. O revisor deve saber qual programa assinado está fazendo a solicitação antes de conceder uma sessão.

Depois, escolha o nível certo de autorização:

• Use aprovação de sessão para trabalho de baixo impacto que precise de leituras repetidas ou chamadas rotineiras durante uma execução do agente.
• Use aprovação por chamada para mensagens externas, alterações de estado, implantações, comandos remotos e ações com efeitos irreversíveis.
• Bloqueie o cofre de credenciais quando estiver ausente, para que toda ação falhe em vez de aguardar uma aprovação sem supervisão.
• Revogue a sessão atual quando a tarefa mudar, o agente se comportar de forma estranha ou você deixar de reconhecer o processo.

A fadiga de aprovação é uma falha de design. Se uma pessoa precisa aprovar cada consulta inofensiva, ela aprende a clicar sem ler. Se uma aprovação concede ao agente uma tarde inteira de mutações em produção, a interface esconde autoridade demais atrás da conveniência. Separe os tipos de ação de acordo com a consequência e torne a atividade comum silenciosa, deixando a atividade relevante específica.

Evite textos de aprovação que repitam a descrição vaga do próprio agente. A camada de ações já tem campos estruturados. Use-os. Mostre o serviço, a conta ou função autenticada, o projeto ou host de destino, a operação e todo conteúdo voltado a pessoas que sairá da organização. Oculte credenciais e campos privados de que o revisor não precisa.

Os logs devem conectar uma execução do agente a cada efeito externo

Os logs dos provedores de serviço sozinhos não bastam para o trabalho de agentes, pois começam na fronteira da API. As transcrições do agente também não bastam, pois podem omitir a solicitação real ou ser editadas. Você precisa de um registro da execução e de um registro de cada chamada, ligados por uma conexão confiável.

Um diário da execução deve identificar o processo do agente, o início e o fim da sessão, a aprovação que a permitiu e uma forma de revogá-la imediatamente. Um diário de chamadas deve registrar a solicitação, o resultado da autorização, o resultado da execução, o destino e o identificador da solicitação do serviço, quando existir. Mantenha corpos sensíveis fora das exibições comuns quando contiverem conteúdo de clientes, mas preserve evidências protegidas suficientes para investigar um incidente.

A evidência de adulteração importa quando os logs podem responder a uma contestação. Um arquivo de texto local simples mostra um histórico útil, mas um usuário ou processo comprometido pode reescrevê-lo. Uma cadeia de hashes faz cada registro depender do anterior, de modo que alterações posteriores quebram a verificação. Isso não torna o log infalível. Torna mais difícil reescrevê-lo sem ser detectado e fornece ao investigador uma propriedade de integridade verificável.

O Sallyport projeta seus diários Sessions e Activity a partir de um log de auditoria criptografado, encadeado por hash e protegido contra escrita. É possível verificar a cadeia de texto cifrado offline com sp audit verify, sem a chave do cofre. Uma verificação saudável deve ter um formato semelhante a este:

Audit chain: valid
Records checked: 184
First sequence: 1
Last sequence: 184

Se a verificação informar uma sequência quebrada ou uma divergência de hash, preserve os arquivos e investigue antes de confiar no diário. Não «repare» um log suspeito apagando a parte final problemática. Isso pode remover a única evidência de quando e como o registro foi alterado.

Uma migração de tokens diretos deve começar pela credencial mais arriscada

Não tente redesenhar todas as integrações em uma semana. Comece pela credencial cujo uso indevido criaria a recuperação mais difícil: autoridade de implantação em produção, acesso amplo ao suporte de clientes ou uma chave SSH que alcance sistemas compartilhados. A migração deve remover os segredos utilizáveis do agente antes de tentar aperfeiçoar cada fluxo de trabalho.

Use esta sequência para cada integração:

1. Faça um inventário de onde o agente obtém a credencial hoje. Inclua variáveis de ambiente, arquivos do repositório, segredos de CI, perfis do shell, configurações de ferramentas e prompts copiados.
2. Liste as operações que o agente realmente executa e separe leituras, rascunhos, mutações e execução remota. A maioria dos tokens diretos permite muito mais do que essa lista.
3. Crie solicitações de ações estruturadas para as operações necessárias. Vincule cada escrita a um destino nomeado e cada implantação a uma referência imutável do artefato.
4. Mova a credencial para um executor que o agente não consiga ler. Substitua a credencial antiga depois de provar que o novo caminho funciona.
5. Teste as falhas de propósito: bloqueie o cofre, negue uma aprovação, revogue uma sessão, envie um destino inválido e execute a verificação de auditoria. Uma demonstração do caminho feliz quase não prova nada.

A etapa de substituição identifica um erro muito comum: a equipe adiciona um mediador, mas deixa o token original no ambiente do agente «como alternativa». Isso mantém duas rotas para a mesma autoridade, e a menos controlada acabará sendo usada. Remova a alternativa. Se o caminho mediado ainda não suportar uma operação necessária, documente a exceção temporária, limite seu escopo e sua duração e atribua sua remoção a uma pessoa identificada.

Entregar diretamente um token é fácil porque passa a decisão difícil para uma string no ambiente do processo. Em sandboxes descartáveis, essa troca pode ser razoável. Para serviços que afetam clientes, implantações ou infraestrutura compartilhada, mantenha as credenciais fora do agente e torne a ação visível antes que ela aconteça.