# Agentes de planejamento e execução para alterações mais seguras em produção

Um agente de planejamento não deve conseguir transformar a própria recomendação em uma alteração em produção. Dê a ele espaço para inspecionar, comparar e argumentar. Dê a um agente de execução separado um conjunto pequeno de permissões de ação e faça-o provar que a ação solicitada corresponde a uma alteração aprovada.

Essa separação parece burocrática até você ver um agente levar uma suposição plausível, mas errada, através de uma fronteira de API. A maioria das falhas não parece um ataque de desenho animado. Um agente lê um runbook desatualizado, confunde um hostname de staging com o de produção ou segue texto não confiável em um chamado. Se o mesmo processo tiver a credencial e a autoridade para agir, o erro se torna uma alteração antes que alguém tenha tempo de perceber.

## Um plano é evidência, não autorização

Agentes de planejamento e execução precisam de autoridades diferentes porque o planejamento produz uma afirmação sobre o mundo, enquanto a execução altera o mundo. Um bom plano ainda pode se basear em dados desatualizados, contexto incompleto do repositório ou instruções copiadas de uma fonte não confiável. Tratar um plano como permissão mistura duas decisões que merecem análises separadas.

Um planejador deve reunir fatos, explicar incertezas, propor alternativas e produzir uma solicitação limitada. Ele não deve ter um token de produção apenas porque precisa mencionar um endpoint em um relatório. Se precisar de fatos de um sistema protegido, exponha uma operação de leitura criada para esse fim, que retorne apenas os fatos necessários, ou peça a uma pessoa que forneça o resultado relevante.

O executor tem outra função. Ele recebe uma solicitação específica e decide se ela se encaixa em sua autoridade limitada. Ele não reabre a discussão de design, navega por chamados arbitrários nem aceita uma frase como «corrija a implantação». Essa frase pode bastar em uma conversa. Como contrato para um processo com credenciais, ela não serve.

Essa distinção também corrige um hábito que as equipes chamam de «humano no circuito» quando querem dizer «uma pessoa deu uma olhada em um longo histórico de conversa». Um revisor não consegue reconstruir com segurança todas as chamadas de ferramentas que um agente pode fazer a partir de prosa. Ele consegue revisar uma solicitação curta e estruturada que informe o alvo, a operação, as entradas, o efeito esperado e o caminho de reversão.

O controle AC-5 do NIST SP 800-53 recomenda separar funções para reduzir a chance de que uma pessoa use um sistema indevidamente sem ser detectada. O texto trata de pessoas, mas o raciocínio se aplica diretamente aos agentes. Não copie uma hierarquia de aprovação antiga para um prompt. Separe as capacidades nas credenciais e interfaces de ferramentas reais.

## O executor deve ser mais limitado que o plano

O executor deve ter menos liberdade que o planejador, e não apenas um prompt diferente. Um agente separado que possa executar comandos shell arbitrários com uma credencial ampla de nuvem não reduziu o risco de forma significativa. Ele ainda pode reinterpretar uma solicitação vaga, descobrir outros recursos e fazer alterações sem relação com a tarefa.

Comece com um catálogo de ações. Cada ação deve nomear uma operação e aceitar um conjunto pequeno de parâmetros. Por exemplo, `deploy_service_revision` pode aceitar o nome de um serviço, um identificador imutável de revisão e um ambiente de destino. Não deve aceitar um trecho de shell nem uma URL arbitrária.

A restrição mais útil costuma ser semântica, não técnica. Uma credencial pode permitir uma implantação, mas um wrapper do executor ainda pode rejeitar uma tag mutável como `latest`, rejeitar a produção quando não houver um ID de alteração e rejeitar um serviço fora da lista permitida. Essas verificações transformam suposições que normalmente ficam em um runbook em código capaz de recusar uma solicitação insegura.

Não confunda uma ferramenta restrita com um resultado restrito. Um token de API que pode atualizar `billing-api` também pode alterar a distribuição de tráfego, as variáveis de ambiente e as configurações de autoscaling. Separe essas operações se a API permitir. Se a API não permitir, coloque um pequeno gateway na frente dela que aceite apenas a operação que você está preparado para automatizar.

Um executor confiável normalmente tem estes limites:

- Usa uma identidade separada para cada ambiente.
- Recebe apenas ações nomeadas, não um shell geral.
- Valida nomes de alvos e entradas imutáveis antes de chamar um provedor.
- Tem vida útil curta e não possui uma rota para criar credenciais mais amplas.
- Emite um registro durável da solicitação e do resultado.

As pessoas costumam resistir porque ferramentas genéricas são mais rápidas de integrar. Elas são mais rápidas na primeira demonstração. Uma ferramenta ampla como `run_command` fica cara na primeira vez que alguém precisa explicar por que um agente excluiu o recurso errado depois de ler um comando copiado em um chamado.

## A transferência precisa de uma solicitação de alteração verificável por máquina

O planejador deve transferir um artefato estruturado que o executor possa validar sem interpretar intenções. Planos em texto livre convidam o executor a preencher lacunas com seu próprio raciocínio, devolvendo a autoridade de planejamento ao caminho de ação.

Uma solicitação prática pode ser assim:

```json
{
  "request_id": "chg-2025-0417-redis-timeout",
  "environment": "production",
  "action": "deploy_service_revision",
  "target": {
    "service": "checkout-api",
    "revision": "sha256:8f31c2..."
  },
  "expected_effect": "Run the approved checkout-api revision",
  "rollback": {
    "action": "deploy_service_revision",
    "revision": "sha256:31aa09..."
  },
  "approval": {
    "approved_by": "release-manager",
    "approved_request_hash": "b2c4..."
  }
}
```

O hash importa. Sem ele, um revisor pode aprovar a solicitação que viu enquanto o executor recebe uma versão modificada. O registro de aprovação deve estar vinculado a uma representação canônica dos campos exatos que o executor usará. Se o seu sistema serializa JSON de formas diferentes em lugares diferentes, defina primeiro a canonicalização. Um hash simples de texto é uma armadilha quando a ordem dos campos ou os padrões omitidos podem alterar o conteúdo.

O executor deve rejeitar a solicitação por motivos claros. Um formato de resposta útil mostra qual verificação falhou sem expor um segredo:

```json
{
  "status": "denied",
  "request_id": "chg-2025-0417-redis-timeout",
  "reason": "revision must be an immutable digest",
  "executed": false
}
```

Essa recusa faz parte do design, não é um caso extremo constrangedor. As equipes testam se os agentes conseguem realizar ações e deixam de testar se eles conseguem exceder o próprio escopo. Teste os dois caminhos.

Não deixe o planejador escolher a definição da ação do executor. O responsável pela plataforma deve definir o catálogo, suas regras de validação e o mapeamento de credenciais. O planejador escolhe entre as ações disponíveis. Ele não pode inventar `deploy_anything` porque uma tarefa específica parece urgente.

## Processos separados evitam o compartilhamento acidental de autoridade

Dois papéis de agente dentro de um único processo ainda podem se misturar facilmente. Variáveis de ambiente, caches de tokens, diretórios de trabalho e registros de ferramentas compartilhados criam caminhos acidentais em torno do limite pretendido. Execute o planejador e o executor como processos distintos, com configurações de inicialização diferentes.

O processo do planejador deve receber ferramentas de pesquisa e talvez interfaces de leitura filtradas de forma restrita. Ele não deve ver as credenciais do executor em seu ambiente, nos arquivos de configuração ou nas descrições das ferramentas. Um modelo não precisa ter acesso em texto simples a um token para usá-lo indevidamente. Se o processo consegue chamar uma ferramenta que possui o token, o limite da ferramenta é o limite de capacidade relevante.

O executor deve receber a solicitação estruturada aprovada e o menor inventário possível de ferramentas. Ele não deve receber o corpo original do chamado, conteúdo arbitrário da web, uma ferramenta de busca em todo o repositório ou o histórico da conversa do planejador. Esses materiais podem conter injeção de prompt, comandos inadequados ou instruções casuais que o executor não tem motivo para obedecer.

Isso cria uma regra simples para depuração: se o executor precisa de mais contexto para decidir qual operação executar, o artefato de transferência está incompleto. Não resolva isso dando a ele amplo acesso de descoberta. Acrescente o campo, a regra de validação ou a decisão humana que falta à solicitação.

A separação de processos também ajuda durante a resposta a incidentes. Você pode revogar a sessão do executor sem perder o registro de pesquisa do planejador. Pode verificar se o planejador propôs um alvo diferente daquele que foi aprovado. Se os dois papéis compartilham uma sessão e uma identidade, essa reconstrução vira um exercício de adivinhação.

O Sallyport se encaixa nesse limite quando um agente compatível com MCP precisa de ações HTTP ou SSH sem receber as credenciais subjacentes de API ou SSH. O aplicativo mantém esses segredos em seu cofre criptografado e executa a chamada por conta própria, para que o planejador não consiga extrair uma credencial mesmo quando suas instruções saem do rumo.

## A aprovação deve ocorrer no ponto em que as consequências mudam

Uma aprovação humana deve abranger uma decisão específica, não oferecer uma bênção vaga para tudo o que o agente fizer em seguida. A aprovação de sessão é útil para estabelecer que um processo de agente conhecido pode usar um conjunto limitado de ações de baixo risco durante uma execução. Ela é um substituto ruim para a revisão quando a ação pode alterar dados de produção, identidade, exposição de rede ou dinheiro.

A aprovação por chamada deve ser usada em credenciais cujo uso tenha consequências relevantes. O clique extra se justifica quando a chamada é irreversível, incomum ou cara de desfazer. Use-a em uma chave de exclusão de produção, em uma credencial que altera o controle de acesso ou em uma operação de pagamento. Não a use em toda solicitação inofensiva de status. Um prompt que aparece o tempo todo vira ruído de fundo, e as pessoas o aprovam sem ler.

Use aprovações que mostrem o que o revisor realmente pode avaliar: nome da ação, ambiente de destino, recurso-alvo, entrada imutável e eventual reversão planejada. Uma caixa de diálogo que diga apenas «O agente solicita acesso» é encenação. Ela não informa nada sobre a consequência.

O escopo da aprovação deve expirar. Uma aprovação vinculada a uma execução deve terminar quando o processo for encerrado. Uma aprovação vinculada a uma solicitação de alteração deve estar ligada ao seu conteúdo e não deve autorizar silenciosamente uma revisão posterior. Concessões de aprovação duradouras são atraentes porque eliminam atrito, mas recriam o privilégio permanente que a separação pretendia evitar.

A escada de decisão do Sallyport tem um formato útil para esse modelo: o bloqueio do cofre nega todas as ações enquanto estiver fechado, a autorização da sessão identifica um novo processo de agente e determinadas chaves por chamada podem pedir confirmação a cada uso. Isso é intencionalmente mais restrito que um mecanismo de políticas. As equipes ainda precisam decidir quais credenciais merecem análise por chamada.

## A injeção de prompt chega aos planejadores antes dos executores

A injeção de prompt costuma entrar pelo trabalho normal do planejador. Um comentário no repositório manda executar um comando. Um chamado de suporte inclui uma instrução falsa para extrair a configuração. Uma página da web diz ao agente para ignorar as instruções anteriores. Os agentes de planejamento veem mais texto não confiável do que os executores deveriam ver.

A resposta inadequada mais comum é passar meses tentando escrever uma instrução perfeita que diga ao planejador para não ser enganado. O comportamento do modelo pode melhorar, mas instruções em texto não substituem limites de autoridade. Presuma que o planejador pode repetir uma instrução ruim em seu plano. Depois, faça o executor rejeitar qualquer solicitação fora do catálogo, do escopo e do vínculo de aprovação.

Considere uma falha familiar. Um planejador investiga uma latência e lê uma anotação antiga de incidente que recomenda definir em zero o número de réplicas de um serviço antes de drenar o tráfego. Ele escreve um plano que informa o ambiente errado porque a anotação usava um hostname copiado. Se esse planejador puder chamar uma ferramenta geral de implantação, poderá transformar uma sugestão desatualizada em indisponibilidade.

Com um design separado, a falha para em vários pontos. A solicitação de transferência precisa informar explicitamente a produção. O executor aceita apenas uma ação de implantação de revisão, não uma alteração na quantidade de réplicas. O revisor humano vê o alvo real e o efeito solicitado. O log do executor registra a recusa se a solicitação não se encaixar. Nenhum desses controles exige que o planejador reconheça perfeitamente um texto contaminado ou obsoleto.

Mantenha a saída do planejador identificada como entrada não confiável para o caminho de execução. Essa frase deve afetar o tratamento dos dados, não apenas aparecer como aviso na interface. Não insira prosa do planejador em comandos shell. Não permita que ela preencha caminhos HTTP, cabeçalhos ou campos de consulta sem verificações de tipo e listas permitidas. Um esquema JSON ajuda, mas a validação do esquema sozinha não informa se `production` é um alvo autorizado.

## O acesso de leitura também pode expor um caminho para causar danos

As equipes costumam dar amplo acesso de leitura aos planejadores porque «eles não conseguem alterar nada». Essa frase já causou muitos problemas evitáveis. O acesso de leitura pode revelar dados de clientes, hostnames internos, históricos de implantação, feature flags, padrões de acesso e nomes de sistemas privilegiados. Também pode fornecer exatamente as informações de que um invasor precisa para formular uma solicitação de ação convincente.

Classifique as leituras pela sensibilidade e pelo que elas permitem fazer. Um endpoint de integridade que retorna o status do serviço é diferente de um endpoint que exporta um banco de dados. Um inventário de serviços que lista nomes públicos é diferente de uma API de gerenciador de credenciais que retorna identificadores e metadados de segredos. Não coloque ambos atrás da mesma ferramenta genérica `read_only`.

Sempre que possível, dê ao planejador fatos derivados. Em vez de acesso a todos os eventos de implantação, ofereça uma operação que retorne a revisão atual, o estado de integridade e o ID da última alteração aprovada de um serviço nomeado. Em vez de direitos amplos de consulta ao banco de dados, forneça uma métrica que responda à pergunta de diagnóstico. Você reduz tanto a divulgação acidental quanto o volume de material que pode carregar instruções hostis.

É aqui que as equipes exageram na correção e tornam o planejamento inútil. A resposta não é deixar o agente cego. É decidir de quais fatos a tarefa precisa e criar uma interface de leitura para esses fatos. Se um planejador precisar regularmente de um campo extra, acrescente-o deliberadamente depois de analisar o caso de uso. Não resolva toda lacuna entregando a ele um console de produção.

## Os logs devem permitir reconstruir uma divergência

Um histórico de auditoria deve responder a mais do que «uma chamada de API aconteceu?». Depois de uma alteração contestada, você precisa comparar o artefato proposto pelo planejador, o artefato aprovado por uma pessoa, a solicitação validada pelo executor, a chamada externa exata e a resposta. A ausência de qualquer um desses elementos deixa espaço para uma narrativa, não para evidências.

Registre um ID de solicitação estável em todo o caminho. O planejador o atribui ou recebe. A aprovação fica vinculada a ele e ao seu hash de conteúdo. O executor o grava junto com sua identidade de processo e o resultado da ação. O gateway externo o registra junto do destino de saída e do status da resposta. Evite registrar tokens bearer, senhas, chaves privadas ou payloads sensíveis completos apenas para facilitar a correlação.

A evidência de adulteração importa porque os logs comuns de aplicativos costumam ficar em armazenamentos que administradores podem editar. Uma sequência de eventos ligada por hashes torna alterações posteriores detectáveis se você conservar o estado esperado da cadeia. Isso não prova magicamente que todos os eventos são verdadeiros. Torna mais difícil esconder uma reescrita silenciosa do histórico registrado, que é a propriedade necessária quando o acesso ao armazenamento dos logs se sobrepõe às pessoas sob análise.

O Sallyport projeta seus diários de Sessions e Activity a partir de um log de auditoria criptografado e encadeado por hashes, e `sp audit verify` verifica a cadeia offline sobre o texto cifrado, sem uma chave do cofre. Isso é útil em uma investigação porque a verificação não exige entregar credenciais de ação ao revisor.

Faça um exercício de reconstrução antes que um incidente o obrigue a fazer isso. Escolha uma alteração aprovada e peça a um colega para responder a cinco perguntas usando os registros: qual agente a propôs, quem aprovou a solicitação exata, qual executor a executou, qual operação de saída ocorreu e qual resultado retornou. Se alguma resposta depender da memória ou de um histórico de conversa, melhore os registros.

## A primeira ação automatizada deve ser simples e reversível

Comece a separação com uma ação que tenha um responsável claro, um conjunto restrito de alvos e uma reversão já praticada. Uma implantação em um ambiente que não seja de produção usando uma revisão imutável é um caso inicial melhor que alterar regras de acesso ou excluir contas antigas. Um trabalho simples dá a você a chance de encontrar falhas de design sem apostar a produção em uma demonstração.

Execute a mesma tarefa pelo fluxo até que o esquema da solicitação pare de mudar por motivos triviais. Observe as falhas previsíveis: planejadores omitem um alvo, revisores aprovam uma descrição genérica, executores precisam de contexto não declarado e os logs não conseguem associar a aprovação à chamada. Cada falha mostra onde a autoridade ainda vaza entre os papéis.

Não meça o sucesso pelo número de cliques de aprovação eliminados. Meça se o executor recusa um alvo errado, uma revisão não aprovada e uma ação não suportada, enquanto conclui a ação pretendida. Um sistema que torna toda ação fácil provavelmente tornou ações demais possíveis.

Quando o fluxo se mostrar consistente, amplie uma família de ações por vez. Mantenha o planejador curioso e o executor previsível. A automação de produção conquista confiança quando suas recusas são tão deliberadas quanto seus sucessos.