A integração de agentes autônomos deve começar com um cofre bloqueado

Agentes autônomos devem conquistar acesso em etapas. Se você começa entregando a um agente um token de produção e pedindo que ele «tenha cuidado», pulou justamente a parte da configuração que ensina como os controles se comportam sob pressão.

O caminho do primeiro dia deve começar com um cofre que nega tudo, passar por uma ação HTTP de baixo risco, depois incluir SSH e, por fim, exigir aprovação a cada uso das credenciais que merecem esse nível de controle. Termine verificando o registro de auditoria enquanto a execução ainda está fresca na sua memória. A ordem importa porque cada etapa isola uma falha diferente.

O objetivo não é tornar o agente útil o mais rápido possível. O objetivo é descobrir exatamente o que ele pode fazer, o que você precisa aprovar, o que ele registra e como interrompê-lo antes de conectá-lo a um trabalho com consequências.

Comece com um cofre que recusa todas as ações

Seu primeiro teste bem-sucedido deve ser uma negação. Um cofre bloqueado precisa recusar uma ação do agente mesmo quando o pedido parece perfeitamente razoável e a credencial já está configurada.

Isso parece estranho até você observar um agente tentando novamente uma ação que falhou. Agentes não hesitam. Quando uma ferramenta informa que o acesso está indisponível, o agente pode tentar outro endpoint, alterar um argumento, chamar uma ferramenta relacionada ou pedir aprovação. Você quer que o limite de segurança responda antes que qualquer credencial saia do armazenamento protegido.

No Mac, confirme que o app está em execução, mas deixe o cofre bloqueado. Inicie o agente pelo fluxo normal de desenvolvimento e faça uma solicitação deliberadamente inofensiva, como buscar um recurso de teste em uma API que você ainda não autorizou.

O resultado esperado é simples: a solicitação não é executada. Não contorne a negação colando o token em uma variável de ambiente, no perfil do shell, em um prompt, em um arquivo do projeto ou em um arquivo de configuração do agente. Esse atalho ensina a lição errada, porque transforma o primeiro teste em um problema convencional de gerenciamento de segredos.

Anote o que o agente informou. Você está verificando três coisas:

• O agente consegue alcançar o gateway de ações por meio da conexão MCP.
• O bloqueio do cofre interrompe a ação enquanto ele está bloqueado.
• Nenhum segredo apareceu na transcrição do agente, na saída do terminal ou nos argumentos da ferramenta.

A diferença entre uma credencial indisponível e um cofre bloqueado importa. Uma credencial indisponível normalmente indica um problema de configuração. Um cofre bloqueado mostra que a configuração funciona e que o acesso está fechado de propósito. Se você tratar as duas falhas como «o token não funcionou», acabará desativando o controle que estava protegendo você.

O Sallyport usa esse comportamento como o primeiro controle da sua escada de decisão: enquanto o cofre está bloqueado, todas as ações são negadas. Em Macs compatíveis, o bloqueio do cofre usa Secure Enclave e Touch ID, em vez de pedir ao agente que prove alguma coisa sobre si mesmo.

Conecte o agente sem entregar um segredo

Um agente precisa de um caminho para executar ações, não de uma cópia da credencial. Essa é a regra que impede uma automação útil de se transformar em uma distribuição descontrolada de segredos.

Configure o agente compatível com MCP para usar o shim stdio integrado:

sp mcp

O shim é um servidor MCP comum. O agente conversa com ele, solicita uma ação HTTP ou SSH e recebe um resultado. A credencial permanece no cofre criptografado dentro do app. O agente não recebe um token em texto simples, um token substituto ou um marcador com aparência de segredo que possa usar de forma indevida depois.

Esse limite é mais preciso do que o adotado por muitas equipes. Elas costumam dizer «o agente tem acesso limitado», quando na verdade querem dizer que o agente tem um token no ambiente com permissões limitadas. São sistemas diferentes.

Com uma variável de ambiente, todo processo que consegue ler o ambiente talvez possa copiar o segredo. Uma entrada no histórico do shell, um log de depuração, um relatório de falha, um processo filho, uma exportação de prompt ou uma transcrição colada do terminal pode prolongar a vida útil desse segredo. Com um gateway de ações, o agente pode solicitar uma ação específica, mas não consegue inspecionar o material de credencial que a autoriza.

Antes de desbloquear qualquer coisa, procure os vazamentos comuns na configuração do agente:

• Remova tokens de arquivos .env, arquivos de inicialização do shell, instruções do agente e documentação do projeto.
• Não adicione uma credencial a um argumento da ferramenta apenas porque ela aceita um campo token.
• Evite permitir que o agente leia o mesmo gerenciador de senhas, arquivo de segredos ou diretório de credenciais de nuvem que você está tentando proteger.
• Mantenha a primeira execução do agente separada de qualquer sessão de terminal que tenha variáveis de ambiente privilegiadas carregadas.

É também aqui que os desenvolvedores fazem uma recomendação popular, mas ruim: «Use primeiro um token temporário e reforce a segurança depois». Um token temporário continua sendo um segredo assim que entra no contexto do agente. Use uma credencial temporária para limitar o impacto, sim. Não a use como desculpa para abandonar o limite entre o agente e o segredo.

Faça uma única solicitação HTTP simples antes de qualquer outra coisa

A primeira ação permitida deve ser uma solicitação HTTP usando uma credencial com finalidade restrita. O acesso somente leitura é preferível. Uma conta de teste é melhor. Um endpoint que retorne um objeto conhecido e não sensível é o ideal.

Escolha uma solicitação que você possa verificar de forma independente. Bons exemplos incluem ler os metadados de um repositório de teste, buscar um perfil de sandbox que você criou ou chamar um endpoint de status ligado a uma conta que não seja de produção. Evite endpoints que listem clientes reais, código-fonte, dados de cobrança ou configurações amplas da conta. Uma leitura bem-sucedida ainda pode revelar mais do que você pretendia.

Configure a credencial HTTP no cofre usando o formato de autenticação esperado pelo serviço: autenticação bearer, autenticação básica ou um cabeçalho personalizado. Dê à credencial um nome claro o suficiente para que você a reconheça mais tarde em um cartão de aprovação. «Leitura da API de teste» é melhor do que «token 2». Seu futuro eu não deveria precisar abrir um gerenciador de senhas para saber se um clique é seguro.

Agora desbloqueie o cofre e inicie um processo novo do agente. A autorização por sessão vem ativada por padrão, então a primeira ação desse novo processo deve mostrar um cartão de aprovação. Leia a autoridade de assinatura de código exibida ali antes de aprovar.

Não reduza essa verificação a «reconheço o nome do agente». Um nome de comando familiar pode ser iniciado por um wrapper inesperado, um binário copiado ou outra ferramenta de desenvolvimento. O cartão de aprovação destaca a autoridade de assinatura de código porque o processo que solicitou o acesso importa mais do que a tarefa em linguagem natural que ele afirma estar executando.

Aprove a execução somente se todas estas condições forem verdadeiras:

1. Você mesmo iniciou o processo do agente.
2. A identidade de assinatura é a esperada para esse processo.
3. A credencial solicitada tem o escopo restrito que você pretendia.
4. A solicitação é aquela que você pediu ao agente para fazer.

Depois, peça ao agente para fazer exatamente uma chamada. Compare o resultado retornado com uma solicitação manual feita fora do fluxo do agente. Você não está provando que o HTTP funciona. Está provando que o agente consegue solicitar uma ação, que o gateway consegue inserir a credencial armazenada e que o resultado pode voltar sem expor a própria credencial.

Um registro útil do primeiro dia é curto:

Credencial: Leitura da API de teste
Tarefa do agente: Buscar um objeto de teste conhecido
Resultado esperado: Apenas o identificador e o status do objeto
Comparação manual: Mesmo identificador e status
Dados inesperados retornados: Nenhum

Se a resposta incluir mais campos do que você esperava, pare por aí. Não peça ao agente para resumir os dados extras e continuar. Reduza o escopo da API, use um objeto de teste menor ou escolha um endpoint mais específico. A primeira chamada HTTP deve criar confiança por meio da contenção, não de um resultado impressionante.

A aprovação da sessão dá permissão para uma execução, não um cheque em branco

A autorização por sessão responde a uma pergunta específica: você aprova esse processo do agente durante toda esta execução? Ela não responde se toda credencial ou toda ação solicitada merece o mesmo tratamento.

Depois que você aprova uma execução, o agente pode fazer várias chamadas antes de sair. Isso é útil quando você supervisiona uma tarefa coerente, como ler metadados de teste e gerar um relatório local. É arriscado quando a execução recebe um prompt aberto, pode iniciar trabalhos relacionados ou tem acesso a credenciais com consequências diferentes.

Trate uma sessão como uma unidade de trabalho limitada. Inicie-a para uma tarefa. Observe as primeiras ações. Encerre-a quando a tarefa terminar. Inicie um novo processo para a próxima tarefa distinta e obtenha outra decisão de autorização.

O diário de sessões deve ajudar nesse hábito. Ele registra as execuções dos agentes, e você pode revogar uma execução instantaneamente. Use a revogação quando o agente começar a sair do rumo, quando perceber que aprovou o processo errado ou quando a tarefa mudar de natureza no meio do caminho.

Veja um padrão de falha que vale a pena reconhecer. Você pede a um agente para «verificar a API de teste e corrigir qualquer problema óbvio». Ele começa com uma solicitação GET inofensiva. Você aprova a sessão. O agente encontra uma divergência de configuração, vê um endpoint de escrita entre as ações disponíveis e decide que a correção óbvia é atualizar a configuração. A credencial pode permitir isso, e a aprovação original ainda pode abranger a execução.

Nada nessa história exige um agente malicioso ou uma ferramenta quebrada. A falha está no limite da tarefa. Você deu à mesma sessão uma fase de descoberta e outra de correção, esperando que a aprovação original mantivesse o mesmo significado nas duas.

Divida o trabalho. Aprove uma sessão de descoberta somente leitura. Revise os resultados. Depois inicie uma execução separada para uma alteração proposta, de preferência usando outra credencial com permissão de escrita mais restrita. A aprovação se torna significativa quando acompanha uma unidade de trabalho que você consegue descrever em uma frase.

Adicione SSH somente depois que o limite HTTP parecer normal

SSH não é «HTTP, mas para servidores». Ele traz consequências maiores porque uma conexão bem-sucedida pode executar comandos arbitrários, inspecionar arquivos, alterar permissões e mover dados por canais que uma API restrita nunca expõe.

Comece com um host descartável ou uma máquina de desenvolvimento isolada. Crie uma conta remota sem acesso à produção, sem credenciais compartilhadas e sem motivo para tocar no seu diretório pessoal ou na configuração da nuvem. Coloque nesse host um arquivo inofensivo com uma linha de texto conhecida. A primeira tarefa SSH do agente deve buscar apenas essa linha.

O Sallyport encaminha as ações SSH pelo helper Go sem estado integrado, sp-ssh. O agente solicita a ação pelo mesmo modelo de gateway, enquanto a credencial SSH armazenada permanece no cofre, em vez de se tornar um arquivo de chave privada que o agente possa ler.

O primeiro exercício SSH deve ser deliberadamente restrito:

Host: host de desenvolvimento isolado
Conta remota: conta de teste restrita
Tarefa permitida: Ler um arquivo de texto conhecido
Resposta esperada: A linha exata colocada nesse arquivo
Condição de parada: Qualquer tentativa de inspecionar outros caminhos ou executar um segundo comando

Não comece com «executar diagnósticos». Essa frase é ampla demais. Diagnósticos costumam significar listagens de processos, configuração de rede, inventários de pacotes, arquivos de log, diretórios pessoais e configurações de aplicações. Um agente capaz interpretará a solicitação de forma ampla porque essa costuma ser a maneira de concluir uma tarefa.

Observe um erro operacional comum: desenvolvedores testam SSH com uma conta conveniente, em vez de segura. Ela tem acesso a um host conhecido, talvez por meio de uma chave pessoal já existente, e o teste é rápido. Então a primeira experiência SSH do agente inclui repositórios, credenciais de deploy, histórico do shell, arquivos de configuração e tudo mais que essa conta consegue ler. Você descobriu que o túnel funciona, mas não aprendeu nada útil sobre contenção.

Uma conta de teste restrita torna a falha compreensível. Se o agente solicitar um caminho inesperado, você verá a ação tentada no diário e poderá negá-la ou revogar a sessão sem se perguntar se ele já encontrou um arquivo mais sensível.

A aprovação por uso pertence às credenciais com consequências

A aprovação por uso pede que você confirme cada uso de uma credencial. Ative essa opção antes de testar uma credencial que possa alterar um sistema, acessar material sensível ou alcançar um host onde um único comando de shell possa causar um efeito amplo.

Desenvolvedores costumam resistir porque solicitações repetidas parecem ineficientes. Eles têm razão quanto ao custo. Uma solicitação para cada leitura de baixo risco vai treiná-lo a clicar sem ler. Isso é fadiga de aprovação e torna o controle pior do que sua ausência, porque cria uma falsa sensação de segurança.

Use a configuração por uso quando cada ação precisar de uma nova decisão humana. Bons candidatos incluem credenciais que podem:

• criar, modificar ou excluir recursos remotos;
• ler registros pessoais, de clientes, financeiros ou relacionados à segurança;
• chamar métodos administrativos de APIs;
• abrir acesso SSH a uma máquina compartilhada de desenvolvimento, staging ou próxima da produção;
• acionar um deploy, job, workflow ou notificação externa.

Mantenha leituras de teste de baixo risco sob aprovação por sessão enquanto aprende o fluxo. Coloque um bloqueio por uso na próxima credencial adicionada que tenha uma consequência real. Depois dê ao agente uma tarefa que exija duas chamadas separadas, como ler uma configuração de teste e propor, sem aplicar, uma alteração. Confirme que é preciso aprovar cada uso quando a credencial está configurada dessa forma.

A diferença é importante. A aprovação por sessão pergunta se determinado processo pode agir durante esta execução. A aprovação por uso pergunta se determinada credencial pode ser usada agora. Uma diz respeito à identidade do processo e à duração da execução. A outra diz respeito à consequência associada a um segredo armazenado. Tratá-las como equivalentes leva as equipes a aprovar de forma ampla demais ou a solicitar aprovação tantas vezes que ninguém lê o cartão.

Quando a solicitação aparecer, inspecione mais do que o nome da credencial. Verifique a ação, o destino e se a tarefa atual do agente ainda a justifica. Se não justificar, negue o uso e peça ao agente que explique seu plano em linguagem simples antes de aprovar qualquer outra coisa.

O diário de atividades transforma surpresas em evidências

Um registro de sessão informa qual execução do agente recebeu aprovação. Um registro de atividade informa o que aconteceu dentro dela. Você precisa dos dois porque um processo de aparência limpa ainda pode tomar uma decisão ruim, e uma chamada suspeita significa pouco se não for possível ligá-la à execução que a provocou.

Depois do teste HTTP, abra o diário de atividades e leia cada chamada individual. Faça o mesmo depois do teste SSH. Compare o registro com o exercício escrito: o endpoint ou host esperado, a ação esperada e o resultado esperado. Você está treinando a capacidade de perceber uma divergência enquanto ainda é fácil explicá-la.

Preste atenção especial às chamadas que parecem inofensivas isoladamente, mas não combinam com a tarefa. Um endpoint de metadados pode revelar a estrutura da conta. Uma sondagem do host pode levar a um comando mais amplo. Uma nova tentativa pode ser inofensiva ou indicar que o agente alterou os parâmetros depois que a primeira resposta falhou. O contexto vem da sessão e da sequência, não de uma única linha vista isoladamente.

Não dependa da narrativa do agente como registro. Agentes podem resumir com precisão, omitir um detalhe, interpretar mal a resposta de uma ferramenta ou produzir uma explicação bem escrita para uma ação que você não teria aprovado. O diário serve para verificar o que aconteceu, não para avaliar o texto que o acompanha.

É também aqui que a revogação instantânea mostra seu valor. Se você perceber que o agente passou da tarefa combinada para a exploração, revogue primeiro a sessão. Depois você pode avaliar se a chamada era inofensiva, pois já terá interrompido novas ações. Esperar uma explicação completa faz sentido em uma reunião, mas é uma resposta ruim a um processo ativo com credenciais.

Verifique a cadeia de auditoria antes de precisar dela

Um registro de auditoria só é útil se você consegue detectar adulterações no próprio registro. Ler uma lista de eventos mostra o que a interface exibe naquele momento. A verificação mostra se a cadeia hash do log de auditoria criptografado continua íntegra.

Execute isto depois dos dois primeiros exercícios:

sp audit verify

O Sallyport consegue verificar a cadeia hash offline sobre o texto cifrado, então essa verificação não exige acesso ao segredo do cofre. Isso é prático durante uma investigação. Você pode conferir a integridade do registro sem desbloquear primeiro o mesmo armazenamento que controla as ações do agente.

Execute o comando uma vez enquanto tudo está tranquilo. Anote onde você guardará o resultado para uma alteração, teste ou incidente. Depois repita a verificação após uma ação deliberadamente negada, uma chamada HTTP aprovada e uma chamada SSH aprovada. Você estará verificando uma sequência de eventos conhecidos, o que facilita reconhecer um resultado inesperado mais tarde.

Não espere surgir uma questão séria de produção para descobrir quem pode executar o comando, onde ficam os logs ou se sua equipe sabe diferenciar um registro de sessão de uma chamada individual. Esse é o erro comum. As equipes instalam o logging, confiam que ele existe e só o abrem quando alguém pergunta: «Quem aprovou isso?» Nesse momento, tentam aprender a ferramenta e reconstruir o evento ao mesmo tempo.

O log de auditoria é projetado nos diários de sessões e atividades a partir de um único registro criptografado, encadeado por hash e sem possibilidade de leitura durante a escrita. Isso oferece duas visões para as operações sem transformar essas visões na única evidência que você pode consultar.

Torne a primeira semana mais difícil do que a primeira demonstração

Uma demonstração bem-feita termina quando a solicitação HTTP é concluída. Um caminho de integração utilizável continua até que você tenha negado uma ação, aprovado uma execução limitada, revogado uma execução de propósito, inspecionado chamadas individuais, exercitado SSH em um host isolado, usado aprovação por uso e verificado a cadeia de auditoria.

Mantenha a primeira semana pequena o suficiente para explicar cada ação. Adicione apenas uma credencial ou capacidade nova por vez. Se uma nova configuração exige várias exceções, escopos amplos e uma solicitação que você não consegue interpretar rapidamente, ela ainda não está pronta para um agente autônomo.

O teste prático é direto: quando o agente pede para agir, você consegue dizer quem está solicitando, qual credencial armazenada será usada, qual sistema externo receberá a ação e onde você procurará o registro depois? Se alguma resposta for vaga, volte à etapa anterior e restrinja o teste.

Isso é mais lento do que copiar um token para um arquivo de configuração. Também é assim que você evita descobrir, às duas da manhã, que a primeira execução real do seu agente foi o momento em que seus controles de credenciais deixaram de controlar qualquer coisa.