# Teste de acesso de agentes à API antes de uma implantação em produção

Um agente conquista acesso às APIs de produção quando se comporta corretamente diante de uma solicitação negada, malformada, lenta ou perigosa, não quando produz uma resposta bem-sucedida em um sandbox. Uma demonstração tranquila esconde as falhas que realmente importam: uma aprovação direcionada ao processo errado, um token copiado para a transcrição do agente, um loop de novas tentativas que sobrecarrega um limite de taxa ou um diário incapaz de explicar quem aprovou uma chamada destrutiva.

Teste todo o caminho da ação em um destino que não seja de produção antes de entregar uma capacidade de produção ao agente. Esse caminho inclui a solicitação do agente, a autorização, a injeção da credencial, a resposta da API remota, a interpretação da falha pelo agente e um registro de cada chamada que sobreviva à sessão. Se uma parte estiver faltando, você testou um cliente de API, não um agente autônomo.

## Um endpoint de não produção precisa ser separado nos aspectos que realmente importam

Um endpoint de teste útil tem credenciais e dados separados, além de um limite de danos que você consiga explicar em uma frase. Chamar um hostname de produção com um parâmetro de consulta que supostamente ativa o modo de teste não atende a esse requisito quando o mesmo token ainda lê registros de clientes ou pode gastar dinheiro.

Use um sandbox do fornecedor quando ele oferecer uma conta isolada e credenciais de teste. Use um tenant dedicado quando o serviço não tiver sandbox. Se nenhuma das duas opções existir, coloque um serviço pequeno sob seu controle atrás de outro hostname e alimente-o com dados descartáveis. O ponto não é um rótulo como staging. O ponto é que uma solicitação equivocada não consiga afetar usuários, saldos ou segredos de produção.

Faça o endpoint provar que não é de produção. Retorne um campo de ambiente evidente em toda resposta bem-sucedida e faça com que as rotas destrutivas escrevam apenas em um livro-caixa de teste. Uma resposta como esta impede que um operador confunda um teste bem-sucedido com uma alteração em produção:

```json
{
  "environment": "test",
  "request_id": "req_7f1a",
  "status": "accepted",
  "resource_id": "demo-order-184"
}
```

Mantenha os dados de teste realistas o bastante para exercitar paginação, campos ausentes, permissões e conflitos. Um único registro perfeito ensina maus hábitos ao agente. Inclua alguns registros que ele possa ler, um que possa atualizar e outro que nunca possa acessar. Você não precisa de um conjunto enorme de dados. Precisa de variação suficiente para encontrar código que presume que toda resposta é limpa e completa.

Não reutilize um token bearer de produção em um ambiente de teste por conveniência. Já vi equipes chamarem isso de atalho temporário e depois deixarem tudo como estava porque cada tarefa seguinte parecia mais urgente. Uma identidade de teste deve ter nome, responsável, data de expiração e permissões correspondentes aos casos de teste específicos. Se ninguém consegue dizer qual teste exige determinada permissão, remova-a.

## A primeira execução deve testar o limite de autorização, não a API

Antes de validar o comportamento de negócio, prove que um processo de agente não reconhecido não consegue agir em silêncio. Inicie um processo novo do agente e faça com que ele tente uma leitura inofensiva no endpoint de teste. O resultado esperado é um evento de autorização antes que a solicitação chegue à API.

Isso revela uma distinção que as equipes costumam confundir: aprovação do usuário não é aprovação do processo. Um operador pode confiar no próprio terminal e desconfiar de um plugin, de um script copiado ou de um agente iniciado por outro aplicativo. A tela de aprovação deve mostrar ao operador qual autoridade executável está tentando agir. Um botão «Permitir» sem esse contexto pede que as pessoas aprovem um processo desconhecido.

Para este teste, registre quatro observações:

- O novo processo recebe uma solicitação de aprovação antes da chamada externa.
- A aprovação identifica o processo de uma forma que o operador consegue reconhecer.
- A aprovação dura apenas durante a execução pretendida, não para todos os processos futuros.
- Encerrar o processo remove a autorização da sessão.

Recuse a solicitação uma vez antes de aprová-la. A recusa deve deixar o agente com um sinal de falha útil, não com um sucesso inventado. Boas instruções para agentes dizem o que fazer depois de uma recusa: interromper a operação, informar que a aprovação foi negada e não procurar uma segunda rota para o mesmo endpoint.

Depois, reinicie o agente e repita a leitura inofensiva. Se o segundo processo herdar a permissão do primeiro, descubra o motivo. A autorização armazenada em cache costuma parecer eficiente em uma demonstração e se transforma em uma concessão silenciosa de permissão quando um agente reinicia depois de uma atualização ou quando outro iniciador chama o mesmo comando.

A aprovação de sessão do Sallyport vem ativada por padrão e mostra a autoridade de assinatura de código do processo na primeira chamada de um novo processo de agente. Esse é o momento certo para testar o julgamento humano, antes que uma solicitação com credenciais chegue ao serviço externo.

## A injeção de credenciais precisa provar que o agente nunca teve o segredo

A injeção de credenciais só passa quando o agente consegue solicitar uma ação sem conseguir recuperar a credencial usada nela. Ocultar um token na saída do console não é proteção. Um token que entrou em uma variável de ambiente, em uma resposta de ferramenta, em um prompt, no histórico do shell ou em um arquivo local estava disponível para o agente, mesmo que ninguém tenha chegado a imprimi-lo.

Configure uma credencial de teste que o serviço remoto consiga identificar sem expor seu valor. Muitas APIs oferecem um rótulo de token, um identificador de cliente ou um campo de auditoria. Se a sua não oferecer, crie uma rota de teste que retorne a identidade da credencial que recebeu, não a credencial em si. O resultado deve provar qual identidade de teste autenticou a chamada.

Para uma API com token bearer, a solicitação no nível da rede normalmente tem esta forma:

```http
GET /v1/test/projects/demo HTTP/1.1
Host: api.test.example
Authorization: Bearer [injected outside the agent]
Accept: application/json
```

O texto entre colchetes é documentação, não um valor que o agente deve preencher. O agente deve fornecer o método, o destino e os argumentos permitidos da solicitação. O gerenciador de credenciais adiciona o cabeçalho de autorização somente depois da decisão de aprovação. Esquemas de autenticação básica e de cabeçalhos personalizados precisam do mesmo teste, porque falham em pontos diferentes quando a configuração está errada.

Inspecione a transcrição do agente, o histórico de solicitações de ferramentas, o ambiente do shell exposto ao agente e todos os arquivos criados durante a execução. Procure tanto o material literal do token quanto vazamentos indiretos, como um objeto de solicitação com um cabeçalho de autorização. Fazer a limpeza depois não conserta um desenho que entregou o segredo ao processo.

Depois, faça a rotação da credencial de teste e execute a mesma solicitação. Uma segunda execução bem-sucedida prova que o caminho da ação lê a credencial atual armazenada, em vez de um valor antigo incorporado à configuração do agente. Uma execução malsucedida também pode ser útil se o erro indicar falha de autenticação sem imprimir o segredo rejeitado.

Não teste com um token capaz de fazer mais do que o cenário exige. Credenciais somente de leitura já expõem o suficiente para provar a injeção. Mais tarde, acrescente uma permissão de escrita que possa ser revertida de forma limitada para os testes de alteração. A pessoa que revisa o teste nunca deve precisar acessar o token bruto para decidir se ele passou.

## O atrito da aprovação deve corresponder ao dano da chamada

A aprovação de uma sessão e a aprovação a cada uso resolvem problemas diferentes. A aprovação da sessão estabelece que uma determinada execução do agente pode usar uma capacidade limitada. A aprovação a cada uso obriga alguém a revisar cada solicitação feita com uma credencial sensível. Tratá-las como substitutas resulta em uma enxurrada inútil de avisos ou em um caminho sem supervisão para erros caros.

Use uma credencial de baixo risco para testar o limite da sessão. Exija aprovação a cada uso para uma credencial que possa criar, excluir, transferir, publicar ou alterar acessos. Peça ao agente que faça duas chamadas de teste diferentes com essa credencial. Você deve ver duas decisões, e a segunda solicitação não deve aproveitar a aprovação concedida para a primeira.

O teste precisa incluir uma recusa. Aprove a primeira ação de teste e recuse a segunda. Confirme estes fatos no relatório do agente e no registro da ação:

1. A primeira ação chegou ao serviço de teste e retornou seu identificador de solicitação.
2. A ação recusada nunca chegou ao serviço de teste.
3. O agente não afirmou que fez a alteração.
4. A sessão continuou disponível para operações que não exigiam a credencial recusada.

Esse quarto ponto detecta um modo de falha especialmente ruim. Algumas integrações tratam uma solicitação sensível recusada como motivo para encerrar todas as operações seguintes. Outras ignoram a recusa e repetem a tentativa até que alguém aprove por acidente. Os dois comportamentos tornam o controle humano mais difícil do que deveria ser.

A fadiga causada por aprovações é uma falha de projeto, mas remover a aprovação normalmente não é a solução. Reduza-a agrupando o trabalho em uma sessão curta, diminuindo o número de chamadas sensíveis ou dando ao agente uma operação em lote mais segura. Não resolva avisos excessivos concedendo um token permanente e amplo a um processo cujo plano pode mudar no meio da tarefa.

## Os códigos de status HTTP devem orientar o comportamento do agente

Um agente precisa de um comportamento explícito para cada classe de falha, porque sucesso HTTP e sucesso da tarefa não são a mesma coisa. A RFC 9110 define a semântica dos códigos de status de resposta HTTP, incluindo que uma resposta 401 indica credenciais de autenticação ausentes ou inválidas e que uma resposta 403 significa que o servidor entendeu a solicitação, mas se recusa a atendê-la. Trate essas respostas de forma diferente. Repetir qualquer uma delas com a mesma solicitação normalmente acrescenta ruído, não progresso.

Monte uma tabela de falhas antes da implantação e exercite cada linha no endpoint de teste. Mantenha as ações exigidas restritas o bastante para que um revisor consiga verificar se o agente as seguiu.

| Resposta de teste | Ação do agente | O que o registro deve mostrar |
| --- | --- | --- |
| Falha de autenticação 401 | Parar e informar um problema de credencial | Destino, status, referência da credencial, nenhum segredo |
| Falha de autorização 403 | Parar e informar permissão insuficiente | Destino, método, status, operação tentada |
| Recurso ausente 404 | Perguntar se o identificador do recurso está errado | Identificador fornecido e status |
| Conflito 409 | Ler o estado atual antes de propor outra escrita | Identificador do recurso, status, nenhuma nova tentativa cega |
| Limite de taxa 429 | Esperar conforme as orientações do servidor ou parar | Status e tempo para nova tentativa, se fornecido |
| 500 ou 503 | Repetir apenas dentro de um limite definido e depois informar o resultado | Número de tentativas, status, resultado final |

Uma resposta 400 merece mais atenção do que costuma receber. Ela frequentemente revela uma incompatibilidade entre o esquema da ferramenta do agente e o contrato real da API remota. Faça o servidor de teste retornar erros de validação por campo e verifique se o agente informa o argumento incorreto sem inventar um valor substituto. Um agente que tenta adivinhar campos pode transformar um erro de validação inofensivo em uma solicitação para a conta errada.

Teste a falha de transporte separadamente de um HTTP 503. Desconecte o serviço de teste ou direcione uma solicitação controlada para um endereço inacessível. O agente deve distinguir entre ausência de resposta e resposta do servidor. Essa diferença importa quando a operação pode ter chegado ao serviço, mas a resposta foi perdida. Repetir uma operação de criação depois de um tempo limite ambíguo pode gerar duplicatas.

Use identificadores de idempotência quando a API oferecer suporte a eles. Se não oferecer, faça o agente verificar se já existe um resultado antes de repetir uma chamada potencialmente mutável. Dizer «tente três vezes» não é um plano de recuperação quando cada tentativa pode cobrar um cartão, criar um usuário ou enviar uma mensagem.

## Uma implantação malsucedida muitas vezes começa com um loop inofensivo de novas tentativas

Uma falha comum começa com um agente instruído a criar um recurso de teste e depois verificá-lo. A solicitação de criação é bem-sucedida no serviço, mas uma interrupção de rede oculta a resposta. O agente vê um erro, repete a chamada de criação e recebe um segundo resultado bem-sucedido. Depois, busca um recurso pelo nome presumido e informa sucesso. O operador agora tem alterações duplicadas e nenhum registro claro de qual solicitação causou cada uma.

Você pode reproduzir isso sem colocar a produção em risco. Faça uma rota de teste aceitar uma solicitação de criação, armazenar o objeto de teste e fechar deliberadamente a conexão antes de retornar a resposta. Execute o agente com um identificador de solicitação fixo. O comportamento seguro esperado é consultar o serviço de teste por esse identificador antes de repetir a criação. Se o agente não conseguir fazer isso, deve parar e informar que o resultado é ambíguo.

Um contrato mínimo para o serviço de teste pode tornar a verificação concreta:

```json
POST /v1/test/jobs
{
  "request_id": "rollout-042",
  "name": "reconcile-demo"
}

GET /v1/test/jobs?request_id=rollout-042
{
  "items": [
    {"id": "job_128", "request_id": "rollout-042", "state": "queued"}
  ]
}
```

É também aqui que você encontra prompts que pedem ao agente para continuar tentando até funcionar. Essa instrução parece sensata para quem observa um operador humano. Ela é insegura para um agente capaz de fazer chamadas mais rápido do que qualquer pessoa consegue perceber. Substitua-a por uma regra de novas tentativas limitada, uma verificação de duplicidade e uma condição que exija revisão humana.

O OWASP API Security Top 10 destaca o consumo irrestrito de recursos e a autorização quebrada no nível do objeto. Ambos aparecem nas implantações de agentes como erros comuns de comportamento: um loop que ignora um limite e um agente que substitui um identificador de objeto próximo depois que o solicitado falha. Seu teste precisa incluir um objeto proibido e uma rota limitada por taxa, porque um conjunto de dados de caminho feliz nunca revelará nenhum desses hábitos.

## Os registros precisam explicar a decisão e o efeito externo

Um registro de chamada deve permitir que alguém reconstrua o que aconteceu sem reconstruir todo o raciocínio privado do agente. Guarde os fatos que estabelecem autoridade e efeito: qual sessão agiu, qual processo solicitou, qual destino e método foram usados, qual referência de credencial se aplicou, se uma pessoa aprovou, quando aconteceu e qual resultado foi retornado.

Não coloque corpos brutos de solicitações em todos os registros por reflexo. Alguns payloads contêm dados de clientes, tokens de terceiros ou conteúdo que o agente recebeu instruções para processar. Armazene um resumo seguro ou campos selecionados quando isso atender à necessidade de investigação. O identificador de solicitação do serviço remoto é especialmente útil porque conecta seu registro local à própria trilha de auditoria do serviço.

Separe o registro da execução do registro da chamada. O registro da execução responde se um determinado processo de agente foi autorizado a operar e se alguém o revogou depois. O registro da chamada responde ao que aconteceu em cada ação externa. Misturar os dois em uma transcrição de chat elimina a estrutura necessária quando uma execução faz muitas solicitações.

O Sallyport projeta os diários de sessão e de atividade a partir de um único registro de auditoria criptografado e encadeado por hash. O comando `sp audit verify` pode verificar essa cadeia offline sobre o texto cifrado, sem uma chave do cofre, o que torna prático testar a integridade dos registros separadamente do acesso aos segredos.

Execute a verificação depois de um teste normal, copie o arquivo de auditoria criptografado para um local de teste e altere alguns bytes na cópia. O comando deve indicar uma falha para a cópia alterada, enquanto o original deve continuar sendo verificado. Faça isso somente com uma cópia descartável. O exercício ensina à equipe de revisão como é um relatório válido antes que ela precise dele durante uma investigação de produção.

Evidência de adulteração não significa que todo operador pode ler todos os detalhes e não substitui os registros da API remota. Ela responde a uma pergunta mais restrita: a sequência local de registros permaneceu intacta? Mantenha os identificadores de solicitação e os horários do endpoint de teste para que um investigador possa comparar os dois lados.

## A revogação precisa interromper a próxima chamada, não apenas fechar uma janela

Teste a revogação enquanto o agente ainda estiver em execução. Aprove uma sessão, faça uma solicitação inofensiva, revogue a sessão e peça ao mesmo processo que faça outra solicitação inofensiva. A segunda solicitação deve falhar antes de chegar ao endpoint de não produção. Se for bem-sucedida porque uma conexão existente ou uma credencial armazenada em cache sobreviveu, isso impede a implantação em produção.

Depois, teste o bloqueio do cofre separadamente. Bloqueie o armazenamento de credenciais e tente fazer a solicitação novamente. Um cofre bloqueado deve negar todas as ações, inclusive uma solicitação que um operador tenha aprovado anteriormente para a sessão. Esse é um controle mais forte do que revogar uma única execução, porque interrompe todos os caminhos de ação que dependem do cofre.

Observe o endpoint durante os dois testes. Não aceite uma mensagem do agente dizendo que o acesso foi negado como prova. O registro de solicitações no servidor deve mostrar que nenhuma segunda solicitação chegou. Essa verificação simples detecta integrações que informam uma falha de aprovação depois de já terem enviado a solicitação HTTP.

Se o agente também puder executar tarefas SSH, além de chamadas HTTP, repita o teste em um host descartável. Use uma conta sem privilégios e um comando com resultado inequívoco, como criar um arquivo em um diretório temporário. A revogação deve impedir um novo comando SSH assim como impede uma solicitação de API. Um gateway que trate os dois canais de forma diferente cria um ponto cego em que os operadores presumem que o controle ainda existe.

## A promoção precisa de um pacote de evidências, não da confiança de uma demonstração

Passe para a produção somente quando um revisor puder inspecionar um registro de teste compacto e responder se o agente permaneceu dentro da autoridade pretendida. O pacote deve conter a identidade e as permissões de teste, o limite do endpoint, o comportamento esperado de aprovação, resultados representativos de sucesso e falha, o resultado da verificação dos registros e o resultado observado da revogação.

Não promova todas as permissões de teste com o agente. Crie uma credencial de produção separadamente e comece com o menor conjunto de operações que sustente a primeira tarefa real. Designe um operador capaz de aprovar ou revogar execuções e registre quais estados de resposta exigem que o agente pare. Se a equipe não conseguir indicar essa pessoa, delegou o controle operacional ao acaso.

Execute a primeira tarefa de produção com as aprovações ativadas e inspecione seus registros imediatamente depois. Compare o número real de solicitações, os destinos e os resultados com a execução de teste. Se o agente entrar em contato com um endpoint não planejado, pedir uma credencial mais ampla ou repetir tentativas de forma diferente com dados de produção, interrompa a implantação e leve esse comportamento de volta ao endpoint de não produção.

A primeira implantação correta em produção é deliberadamente sem graça. O agente faz um pequeno número de chamadas esperadas, uma pessoa consegue interrompê-lo, a credencial nunca entra no contexto do agente e cada efeito externo tem um registro correspondente ao próprio identificador de solicitação do serviço. Isso é prova suficiente para expandir com cuidado. Uma demonstração bem-acabada não é.