Guardrails de produção para agentes de IA com autonomia segura

Guardrails de produção para agentes de IA precisam resistir a mais do que um prompt educado. Um agente de programação autônomo pode interpretar um target incorretamente, repetir uma operação, expor uma credencial na explicação ou continuar após uma resposta ambígua. Por isso, a segurança em produção precisa existir na interface executável, no modelo de autorização e no audit trail — não apenas nas instruções.

Dockup combina orientações comportamentais no skill do Claude Code e do Codex com enforcement no nível do CLI: secrets são mascarados, operações destrutivas exigem --yes, falhas retornam códigos estáveis, deploys podem aguardar um estado terminal e as mutações aparecem no audit log.

Por que os guardrails precisam ser aplicados abaixo do prompt?

Um prompt é uma política útil, mas não é uma security boundary. O contexto do agente pode ser truncado, as instruções podem entrar em conflito e o modelo pode escolher uma interpretação incorreta. A ferramenta subjacente deve tornar comportamentos inseguros difíceis ou impossíveis.

Considere uma solicitação de exclusão. O design fraco expõe um comando que exclui imediatamente e depende de o agente se lembrar de pedir confirmação. O design mais robusto rejeita a operação, a menos que uma flag de confirmação separada esteja presente.

Dockup usa o padrão mais robusto:

dockup up production/api --prune --json

Sem confirmação explícita, a limpeza destrutiva é recusada e o JSON inclui code:"needs_confirm". Nada é removido. O agente precisa apresentar esse resultado a uma pessoa, receber aprovação e então executar novamente de forma deliberada:

dockup up production/api --prune --yes --json

Isso é defense in depth. O skill do Dockup instrui o agente a parar, enquanto o CLI impede a execução acidental mesmo que a instrução seja ignorada.

Como o mascaramento de secrets protege agentes autônomos?

Os agentes frequentemente incluem o output dos comandos no raciocínio ou na resposta final. Se uma operação de leitura retornar um token de produção, o secret poderá se espalhar pelo histórico do chat, logs, telemetria, screenshots ou notas de incidentes copiadas.

Uma interface segura de configuração separa os metadados dos secrets dos valores dos secrets. Dockup retorna as chaves das variáveis de ambiente e o marcador isSecret, mas os valores armazenados dos secrets são null ou mascarados.

dockup env list -s production/api --json

O agente pode definir um secret sem recuperá-lo posteriormente:

dockup env set API_KEY="$API_KEY" \
  --secret \
  -s production/api \
  --json

O mascaramento de secrets não elimina a necessidade de gerenciar cuidadosamente os processos. O valor original ainda existe no ambiente do shell durante a operação de definição. Evite set -x, não faça echo da variável e não crie strings de comandos que sejam capturadas por logging detalhado.

Senhas de banco de dados, API keys, tokens de registry, credenciais SSH e credenciais de Windows RDP devem ser tratadas como outputs de uso único ou restritos. Um agente deve armazená-las em um secret manager aprovado ou encaminhá-las diretamente ao próximo processo, sem reproduzi-las em texto.

A abordagem mais ampla no nível da aplicação é apresentada em security best practices.

Como deve funcionar a aprovação de ações destrutivas?

Nem toda mutação exige o mesmo nível de cerimônia. Um modelo de autonomia útil separa as operações por reversibilidade e blast radius:

Nível	Exemplo	Comportamento padrão do agente
Somente leitura	Listar serviços, ler status, visualizar logs	Executar e resumir
Escrita reversível	Definir uma variável, iniciar um deploy	Executar dentro do escopo aprovado
Recuperação operacional	Reiniciar, executar novamente um deploy antigo	Executar se o runbook permitir; relatar evidências
Destrutiva	Destruir um serviço, excluir um banco de dados, sair do projeto	Parar e solicitar aprovação explícita
Destrutiva ampla	Aplicar --prune, transferir ownership	Exigir confirmação humana específica para o target

A aprovação explícita deve incluir o target exato e a consequência. “Sim, prossiga” é mais fraco do que “Exclua staging/old-api e os recursos de serviço associados”. O agente não deve reutilizar uma aprovação concedida para outro comando ou target.

O config as code do Dockup é aditivo por padrão. dockup up não remove variáveis de ambiente ou domínios ausentes no manifesto. A exclusão exige a flag explícita --prune:

dockup plan production/api --json
dockup up production/api --prune --json

O plan é somente leitura e deve ser revisado primeiro. Mesmo com --prune, secrets, serviços, bancos de dados e volumes ficam protegidos contra esse caminho de limpeza do manifesto. Consulte dockup.yaml config as code para ver o workflow completo.

Como erros estruturados mantêm a autonomia dentro de limites?

Um agente precisa de um conjunto finito de branches seguras. Mensagens em texto livre são úteis para pessoas, mas códigos de erro estáveis tornam a primeira resposta determinística.

Código	Resposta correta
not_logged_in	Parar e obter uma credencial válida
not_linked	Resolver o target ou informá-lo explicitamente
no_target	Executar a descoberta de serviços; nunca inventar um slug
needs_confirm	Solicitar aprovação humana
deploy_trigger_failed	Informar por que a operação não pôde ser iniciada
deploy_failed	Inspecionar os build logs
deploy_timeout	Informar a incerteza sobre um estado não terminal

Um deploy deve usar a espera por estado terminal:

dockup deploy production/api --wait --json

O timeout padrão é de 900 segundos. O exit 0 comprova que o deploy alcançou o sucesso. Um exit diferente de zero impede que o agente prossiga para alterações de domínio, migrations ou anúncios como se a produção estivesse pronta.

Esse design é analisado em AI agent CLI design. O princípio é simples: a ferramenta precisa tornar explícito qualquer resultado ambíguo.

O que um audit log deve registrar?

Autonomia sem atribuição é dívida operacional. Um audit trail de produção deve responder quem realizou a ação, qual interface foi usada, qual target foi alterado, se a operação foi de leitura ou escrita, quando ocorreu e se foi bem-sucedida.

Dockup registra ações realizadas pelo CLI, pela UI e pela API. Operadores podem consultar as mutações recentes:

dockup audit --writes --json
dockup audit --number 30 --json
dockup audit --search domains --json

O próprio report do agente deve complementar o registro da plataforma. Inclua:

1. O target project/service resolvido.
2. A categoria do comando, sem valores de secrets.
3. Os IDs de deploy ou de recursos retornados pela plataforma.
4. O exit code e o status estruturado.
5. As evidências coletadas após a mutação.
6. Qualquer aprovação recebida para trabalho destrutivo.
7. Incertezas restantes ou próximos passos.

Audit logs não servem apenas para atribuir culpa após um incidente. Eles permitem que outro agente ou operador humano reconstrua o estado sem repetir comandos arriscados.

Como as equipes podem aumentar a autonomia dos agentes com segurança?

Comece com acesso de leitura e um serviço de baixo risco. Expanda apenas quando o agente demonstrar descoberta correta de targets, higiene de secrets, tratamento adequado de falhas e capacidade de gerar reports.

Uma progressão prática é:

Etapa 1: Observar

Permita a listagem de serviços, status, histórico de deploys, build logs, runtime logs, uptime, usage e leituras de security scan. Compare o resumo do agente com o JSON bruto.

Etapa 2: Fazer deploy em um target fixo

Permita o deploy de um serviço com --wait. Exija um health check e um report estruturado de conclusão. Não conceda permissões de exclusão ou de gerenciamento de equipes.

Etapa 3: Gerenciar configurações reversíveis

Permita atualizações de variáveis com e sem secrets, configuração de health checks e definição de custom domains conforme um runbook revisado. Exija um novo deploy após alterações no ambiente.

Etapa 4: Executar ações de recuperação

Permita restart ou rollback apenas quando o agente selecionar um ID exato de um deploy conhecido e preservar as evidências da falha.

Etapa 5: Trabalho destrutivo com aprovação

Mantenha as flags destrutivas protegidas por aprovação humana explícita, mesmo quando a credencial permitir essas operações tecnicamente. Use API keys com escopo definido sempre que possível e revise o audit trail regularmente.

A instalação do skill do agente reforça esses comportamentos:

npm install -g dockup-cli
dockup skill install
dockup skill status --json

A referência do Dockup CLI documenta o comportamento imposto aos comandos. O agente deve verificar o schema local em vez de depender de um exemplo memorizado.

Checklist de revisão dos guardrails

Antes de conceder acesso à produção, responda a cada pergunta:

• O agente consegue descobrir os targets exatos sem fazer suposições?
• Os valores dos secrets são mascarados em todos os caminhos de leitura?
• Toda mutação com falha retorna um valor diferente de zero?
• Operações longas podem aguardar um estado terminal?
• Ações destrutivas são bloqueadas sem confirmação explícita?
• As credenciais têm escopo definido e são fornecidas fora dos prompts?
• Toda mutação pode ser encontrada em um audit log?
• Existe um procedimento testado de rollback ou recuperação?
• As versões do skill e do executável podem ficar dessincronizadas?
• O report final separa fatos de incertezas?

Um “não” é uma tarefa de design, não uma tarefa de escrita de prompt. A autonomia em produção só deve crescer à medida que as garantias subjacentes também crescem.

Teste os guardrails como casos de falha

Uma revisão só está completa quando a equipe aciona deliberadamente os limites. Execute um deploy com um token inválido, solicite um target desconhecido, permita que um build de teste falhe, defina um timeout muito curto e tente executar um comando destrutivo sem confirmação. Cada caso deve produzir um exit diferente de zero, um código estável, nenhum vazamento de secret e nenhuma mutação não intencional.

Esses testes transformam os guardrails de produção para agentes de IA em garantias observáveis. Repita-os após atualizações do CLI ou das políticas, assim como você repetiria testes de autenticação e autorização de uma aplicação. Um guardrail que existe apenas em uma apresentação não protegerá um release não supervisionado.

Coloque o workflow em produção

Instale o skill, inspecione suas instruções e teste todos os guardrails — incluindo um comando destrutivo bloqueado — antes de emitir um token de produção.

npm install -g dockup-cli
dockup skill install

O primeiro comando instala o CLI. O segundo instala o skill correspondente do Dockup para Claude Code e Codex. Comece gratuitamente em app.dockup.ai.

FAQ

As instruções do prompt são suficientes para manter um agente de IA seguro em produção?

Não. Os prompts ajudam a orientar o comportamento, mas controles críticos como mascaramento de secrets, confirmação, autorização, exit codes e logging de auditoria precisam ser aplicados pela ferramenta e pela plataforma.

Como o Dockup bloqueia operações destrutivas?

Comandos destrutivos se recusam a executar sem a flag explícita --yes e retornam o código estruturado needs_confirm, permitindo que o agente pare e solicite ajuda humana.

Um agente de IA pode ler valores de secrets de ambiente no Dockup?

Os valores armazenados dos secrets são mascarados no output. O agente pode ver a chave e o marcador de secret e pode substituir o valor, mas não recebe o secret armazenado.

Por que códigos de erro estruturados são importantes para a autonomia?

Eles limitam o agente a branches de recuperação conhecidas, como solicitar autenticação, descobrir o target exato, ler build logs ou pedir confirmação.

Como uma equipe deve começar a conceder acesso à produção?

Comece com operações somente leitura, depois permita o deploy em um único target de baixo risco e avance para configuração reversível e recuperação apenas quando o agente relatar consistentemente evidências verificáveis.