Harness Engineering: Quando Humanos Direcionam e Agentes Executam

O agente funcionou perfeitamente. Depois deletou o banco de dados.

Três semanas em produção, um AI coding agent em uma empresa SaaS de médio porte executou um script de migração ao contrário. Não maliciosamente. Não aleatoriamente. O agente seguiu suas instruções com precisão: "limpar tabelas não utilizadas." O problema não foi o raciocínio do agente. O problema foi que nada no sistema impediu o agente de interpretar "não utilizadas" como "não consultadas nos últimos 30 dias," o que incluia a tabela de billing durante um período sazonal de baixo tráfego. Nenhum humano revisou a ação antes da execução. Nenhuma restrição existia para sinalizar operações destrutivas. Nenhum harness.

product.engineer define harness engineering como a disciplina de projetar as restrições, checkpoints e superficies de controle que permitem agentes de AI operar com autonomia significativa enquanto previnem resultados catastroficos. E a prática de construir o sistema ao redor do agente, garantindo que o julgamento humano governe decisões irreversiveis enquanto a velocidade do agente cuida de todo o resto.

Essa é a lacuna de habilidades definidora para o product engineer construindo com AI em 2026. Você pode ter agentes brilhantes. Você pode ter context windows perfeitas. Mas se você não tem um harness, você não tem um sistema de produção. Você tem uma demo com um cronômetro contando até o primeiro incidente.

O termo ganhou tracao depois que as palestras do AI Engineer World's Fair (que coletivamente acumularam mais de 200.000 visualizações entre sessões sobre confiabilidade de agentes) formalizaram o que praticantes vinham convergindo independentemente: o código mais importante em um sistema de agentes não é o agente em si. E o código que envolve, restringe e direciona o agente. O harness.

Por que agentes precisam de harnesses, não apenas prompts

A abordagem ingenue para segurança de agentes e instruções. "Não delete dados de produção." "Sempre peça confirmação antes de ações destrutivas." "Nunca modifique arquivos fora do diretorio do projeto." Você escreve isso no system prompt e torce pelo melhor.

Torcer não é uma estratégia de engenharia.

Um estudo de 2025 da University of Illinois (publicado no NeurIPS) testou a confiabilidade de seguir instruções em modelos foundation principais para diretivas críticas de segurança. Mesmo os modelos mais fortes (Claude 3.5 Sonnet, GPT-4 Turbo) violaram restrições explícitas do system prompt 4-7% das vezes em tarefas agênticas multi-step. Essa porcentagem parece pequena até você calcular o que significa em escala. Um agente que processa 100 tarefas por dia com uma taxa de violação de 5% vai produzir 35 violacoes por semana. Se mesmo 10% dessas violacoes forem consequentes, são 3-4 incidentes semanais em produção.

Instruções são necessárias. Elas não são suficientes.

Essa é a mesma licao que sistemas distribuídos nos ensinaram há uma década. Você não protege um microservice dizendo "não aceite requests não autorizados." Você coloca uma camada de autenticação na frente. Você não previne race conditions adicionando um comentário que diz "não chame isso concorrentemente." Você usa um mutex. O mecanismo de enforcement e arquitetural, não verbal.

Um harness é esse enforcement arquitetural para agentes de AI. Ele opera no nível do sistema, fora do processo de raciocínio do modelo, onde não pode ser contornado, ignorado ou mal interpretado. O agente não consegue conversar para passar pelo harness da mesma forma que consegue conversar para passar por uma instrução de prompt.

O padrão harness: anatomia do controle de agente production-grade

Tendo passado anos na AWS construindo sistemas onde falhas são medidas em impacto ao cliente, e tendo orientado mais de 12.000 engenheiros em como lançar software confiável, eu observei o padrão harness emergir independentemente em todos os times construindo sistemas serios de agentes. O padrão é consistente o suficiente para formalizar. Ele tem quatro camadas, cada uma servindo uma função distinta que não pode ser colapsada nas outras.

Camada 1: Classificação de ações

Antes de um agente executar qualquer ação, o harness a classifica. Não o agente. O harness. Essa distinção e crítica. Se você pede ao agente para auto-classificar suas ações como "seguras" ou "perigosas," você está pedindo ao mesmo sistema que quer tomar a ação para avaliar se deveria. Isso é um conflito de interesse embutido na arquitetura.

A camada de classificação opera sobre a ação em si, independente do raciocínio do agente:

• Operações de leitura: Leituras de arquivo, API GETs, queries de banco de dados, web fetches. Risco baixo. Executar imediatamente.
• Escritas limitadas: Modificações de arquivo dentro de escopo definido, chamadas de API com semantica idempotente, updates de banco com suporte a transação. Risco médio. Logar e executar.
• Escritas ilimitadas: Delecoes de arquivo, mudanças de schema, deploys em produção, transações financeiras. Risco alto. Requer aprovação humana.
• Modificações de sistema: Mudanças de permissão, alterações de infraestrutura, operações com credenciais. Risco crítico. Requer autorização humana explícita com audit trail.

O Claude Code da Anthropic implementa exatamente esse padrão. Cada tool call e classificada antes da execução. Operações de leitura prosseguem silenciosamente. Operações de escrita requerem reconhecimento. Operações destrutivas requerem aprovação explícita. O agente nunca decide seu próprio nível de permissão. O harness decide.

Camada 2: Limites de escopo

Limites de escopo definem o perimetro operacional. Eles respondem: onde esse agente pode operar, é onde é proibido ir?

Os sistemas internos de agentes da Linear, como descrito pelo time de engenharia deles, implementam limites de escopo no nível do projeto. Um agente com a tarefa de "corrigir o bug de auth" tem acesso de leitura ao codebase inteiro mas acesso de escrita apenas a arquivos que mudaram nos últimos 30 dias dentro do módulo de auth. Ele não pode modificar código de infraestrutura. Não pode tocar no sistema de billing. Não pode fazer push para main. Esses limites são enforced pelo harness, não solicitados pelo prompt.

Limites de escopo incluem:

• Limites de file system: Quais diretorios e arquivos o agente pode ler, modificar, criar ou deletar
• Limites de rede: Quais APIs o agente pode chamar, quais endpoints são permitidos ou bloqueados
• Limites de tempo: Quanto tempo o agente pode executar antes de terminacao forcada
• Limites de recursos: Quanto compute, memória ou budget de API o agente pode consumir
• Limites de blast radius: Quantos arquivos, registros ou recursos uma única operação pode afetar

O product engineer projetando um harness pensa em blast radius do mesmo jeito que um SRE pensa em domínios de falha. Se algo der errado, quao ruim pode ficar? Então você projeta o limite para que a resposta seja "não muito."

Camada 3: Checkpoint gates

Checkpoint gates são momentos no fluxo de execução onde o harness pausa o agente e apresenta o estado para um humano revisar. Eles não são confirmacoes ("prosseguir? s/n"). São pontos de inspecao onde o humano vê o que o agente planeja fazer, entende o porque, e pode redirecionar, modificar ou abortar.

O desafio de design e posicionamento. Checkpoints demais e você perde a vantagem de velocidade dos agentes por completo. Poucos demais e você volta ao cenário de "deletou a tabela de billing." O posicionamento ótimo segue o que eu chamo de Princípio da Irreversibilidade: posicione checkpoints antes de ações que são caras de desfazer.

O produto v0 da Vercel demonstra isso bem. O agente pode gerar, modificar e pre-visualizar código livremente. Essas ações são baratas de desfazer. Mas quando se trata de fazer deploy, modificar variáveis de ambiente ou mudar registros DNS, o sistema insere checkpoints explícitos. O humano vê a ação planejada, o estado atual é o estado proposto. Só então a execução prossegue.

Uma comparação de estratégias de checkpoint:

A maioria dos sistemas em produção usa baseada em categoria ou baseada em milestone, dependendo do perfil de risco do domínio.

Camada 4: Observação e correção

A camada final e observação continua. Não logging (embora logging faca parte). Observação significa que o harness monitora o comportamento do agente ao longo do tempo e detecta drift, anomalias ou padrões que sugerem que o agente saiu do trilho antes que as consequências se tornem visíveis.

É aqui que context engineering se cruza com harness engineering. A camada de observação alimenta informação de volta no contexto do agente, criando um loop de correção. Se o agente começa a fazer chamadas de API repetidas para o mesmo endpoint (sugerindo um retry loop), o harness pode injetar contexto: "Você chamou esse endpoint 5 vezes. A resposta foi a mesma todas as vezes. Considere uma abordagem alternativa." Isso não é um hard stop. E um nudge. Mas é um nudge de fora do processo de raciocínio do agente, o que da um peso epistemico diferente.

As ferramentas internas de engenharia do PostHog implementam observação como um dashboard em tempo real. Engenheiros podem assistir seus AI coding agents em ação, ver o padrão de tool calls e intervir antes que uma trajetória problematica alcance a execução. A camada de observação torna o comportamento do agente legivel para humanos de um jeito que logs brutos nunca conseguiriam.

O toolkit de harness engineering

Como um harness realmente se parece em código? Deixe-me percorrer os componentes que todo harness de AI production-grade precisa.

Sistemas de permissão

Toda ação mapeia para uma permissão. Permissões são definidas fora do agente, versionadas junto com o código da aplicação e aplicáveis em runtime. Isso não é ciência da computacao nova. E RBAC (Role-Based Access Control) aplicado a agentes de AI em vez de usuários humanos.

agent_permissions:
  codebase_reader:
    allow:
      - file.read:**
      - git.log
      - git.diff
    deny:
      - file.write:**
      - git.push
      - git.commit
  
  codebase_writer:
    allow:
      - file.read:**
      - file.write:src/**
      - git.commit
    deny:
      - file.write:infrastructure/**
      - file.write:.env*
      - git.push:main
      - git.force_push

O sistema de permissão é o sistema imunologico do harness. Ele define o que é possível independente do que o agente decida tentar.

Sandboxes de execução

O agente roda em um sandbox. Suas ações afetam um ambiente controlado, não produção diretamente. Mudanças se acumulam no sandbox até que um humano revise é as promova.

A abordagem da Stripe (referenciada no blog de engenharia deles) roda todas as mudanças de código geradas por AI em um ambiente isolado que espelha produção mas não tem acesso a dados reais de clientes. O agente pode escrever, testar e iterar livremente dentro do sandbox. Quando as mudanças estão prontas, um humano revisa o diff, roda contra suites de teste representativas de produção e só então faz merge.

Isso também não é uma ideia nova. E como fazemos deploy de código há décadas: ambientes de staging, canary deployments, feature flags. O harness aplica o mesmo princípio ao trabalho gerado por agentes.

Kill switches

Todo sistema de agentes precisa de um kill switch. Não "por favor pare quando for conveniente." Um stop imediato e duro que termina a execução, faz rollback de quaisquer mudanças em progresso e retorna o sistema para um estado bom conhecido.

Isso parece óbvio. Na prática, muitos sistemas de agentes carecem de caminhos limpos de terminacao. O agente está no meio de uma operação multi-step. Você aperta stop. Mas os três primeiros passos já executaram, é os passos restantes eram os que teriam feito cleanup dos três primeiros. Agora você tem uma operação parcial com estado inconsistente.

Harnesses de produção implementam semantica transacional: ou todos os passos completam, ou toda a operação sofre rollback para o estado pre-execução. Isso requer que o harness mantenha um log de checkpoint de estado antes de cada ação, habilitando rollback confiável em qualquer ponto da sequência de execução.

Quando o harness e apertado demais: o problema de over-constraint

Existe um modo de falha no extremo oposto. Harnesses tão restritivos que eliminam o valor do agente por completo. O agente pode ler arquivos mas não modifica-los. Pode sugerir código mas não escreve-lo. Pode planejar mas não executar. Nesse ponto, você construiu um sistema de autocomplete muito caro.

A arte de harness engineering e calibração. Você quer o agente operando em autonomia útil máxima dentro de risco aceitavel mínimo. Essa é uma decisão de produto, não apenas técnica, é por isso o product engineer esta unicamente posicionado para acertar. Você entende as necessidades do usuário. Você entende o risco de negócio. Você entende as restrições técnicas. Você pode calibrar o harness onde um engenheiro de infraestrutura puro definiria restrição máxima por padrão é um product manager puro definiria autonomia máxima por padrão.

O framework de calibração que eu uso quando aconselho times:

1. Comece restritivo. Novos agentes começam com permissões read-only e checkpoints obrigatórios em toda escrita.
2. Meça a taxa de violação. Rastreie com que frequência o agente tenta ações fora de seu limite de permissão.
3. Expanda onde violacoes são seguras. Se o agente repetidamente tenta fazer algo é essa ação teria sido ok, expanda a permissão.
4. Aperte onde erros são custosos. Se o agente ocasionalmente produz outputs problematicos em uma categoria, adicione um checkpoint gate.
5. Itere na cadência. Revise a configuração do harness semanalmente no primeiro mês, depois mensalmente.

Isso não é diferente de progressive disclosure em design de UX. O agente ganha confiança através de confiabilidade demonstrada, é o harness se ajusta de acordo.

O AI harness em sistemas multi-agent

Harness engineering se torna exponencialmente mais importante em arquiteturas multi-agent. Quando múltiplos agentes coordenam em uma tarefa, o blast radius de um harness mal configurado se multiplica. Agente A produz output que Agente B consome. Se o harness do Agente A permite que ele produza output malformado, Agente B pode processa-lo incorretamente, e Agente C pode agir sobre esse processamento incorreto.

O padrão de harness para sistemas multi-agent adiciona uma camada de contrato inter-agente. O output de cada agente e validado pelo harness contra um schema antes de poder ser consumido pelo próximo agente. Isso é exatamente como contratos de API funcionam entre microservices. O harness é o API gateway do mundo dos agentes.

O sistema de produção da Factory AI (que processa milhares de tarefas de código diariamente) implementa harnesses inter-agente como interfaces tipadas. O output do agente Drafter deve estar em conformidade com um formato de diff estruturado. Se ele produz qualquer outra coisa, o harness rejeita antes do agente Reviewer sequer ver. O output do Reviewer deve estar em conformidade com um formato de feedback estruturado. Se ele produz texto livre, o harness rejeita antes do Integrator consumir.

Essa validação inter-agente captura uma classe de erros que harnesses por-agente não pegam. Não é suficiente que cada agente seja individualmente restrito. As interfaces entre eles também devem ser restritas.

Harness engineering vs. testes tradicionais

Uma pergunta natural: isso não é apenas testes? Se eu tenho bons testes, preciso de um harness?

Não. Testes verificam que o agente produziu output correto após a execução. Um harness previne execução incorreta de ocorrer. São complementares, não substituiveis.

Você precisa de ambos. Testes validam a qualidade de raciocínio do agente. O harness garante que as ações do agente permanecam dentro de limites aceitaveis independente da qualidade do raciocínio. Um agente bem testado em um harness bem projetado é o padrão de produção. Qualquer um sozinho e insuficiente.

Padrões reais de harness em produção

Deixe-me compartilhar padrões que vi funcionar em times que orientei e sistemas que construi. Esses não são hipoteticos. Estão rodando em produção hoje.

O padrão "draft, diff, deploy"

Usado por times na Shopify e plataformas de comércio similares. O agente faz draft das mudanças em uma branch scratch. O harness gera um diff legivel para humanos mostrando exatamente o que mudou é por que. Um humano revisa o diff (checkpoint gate). Somente após aprovação o harness faz deploy das mudanças pelo pipeline normal de CI/CD.

Esse padrão funciona porque preserva os mecanismos de segurança de deployment existentes. O harness não substitui seu CI/CD. Ele alimenta o CI/CD. O agente acelera a criação de mudanças. O harness garante que essas mudanças passem pelos mesmos quality gates que código escrito por humanos.

O padrão "budget and burn"

Usado para agentes com acesso a APIs (agentes de busca, agentes de enriquecimento de dados, agentes de suporte ao cliente). O harness atribui um budget: número de chamadas de API, tokens consumidos ou tempo de execução. O agente executa livremente dentro do budget. Quando o budget se esgota, a execução termina é os resultados são apresentados como estão.

Isso previne custos descontrolados e execução descontrolada. Um incidente de 2025 em uma startup bem financiada (reportado em um postmortem no Hacker News) envolveu um agente de AI que consumiu $14.000 em creditos de API em quatro horas, chamando recursivamente uma API de busca para "reunir mais contexto" para uma query ambígua. Um harness de budget com um cap de $50 teria limitado o dano a $50.

O padrão "shadow mode"

Usado para domínios de alto risco (serviços financeiros, saúde, juridico). O agente roda em paralelo com um operador humano. O agente produz seus outputs. O humano produz seus outputs independentemente. O harness compara. Discrepancias são logadas e analisadas.

Com o tempo, conforme os outputs do agente convergem com o julgamento humano, o harness pode migrar de shadow mode para suggestion mode (agente sugere, humano aprova) para autonomous mode (agente executa, humano revisa assincronamente). Essa autonomia graduada é como você constrói confiança em sistemas de alto risco sem aceitar risco alto durante a fase de construção de confiança.

A vantagem do product engineer em design de harness

A razao pela qual harness engineering pertence ao product engineer e não a um "time de AI safety" especializado é que design de harness é fundamentalmente uma decisão de produto. Cada configuração de harness representa uma compensação entre velocidade e segurança, entre autonomia e controle, entre capacidade e risco.

Essas compensações não podem ser avaliadas isoladamente do contexto do produto. Um harness perfeitamente calibrado para uma ferramenta de geração de código e catastroficamente errado para um assistente de diagnóstico medico. Um harness apropriado para uma ferramenta interna de desenvolvimento e insuficiente para um agente voltado ao cliente lidando com transações financeiras.

O product engineer entende:

• O que o usuário precisa que o agente realize (determina capacidade mínima)
• Como falha se parece da perspectiva do usuário (determina tolerância a risco)
• O que o negócio pode absorver em termos de incidentes (determina margens de segurança)
• O que competidores demandam em termos de velocidade (determina nível de autonomia)

Ninguém mais na mesa segura essas quatro perspectivas simultaneamente. E por isso que harness engineering é uma disciplina de product engineering, não uma preocupacao puramente de infraestrutura.

Construindo seu primeiro AI harness: uma sequência prática

Se você está começando do zero, aqui está a sequência que eu recomendo baseado em ter lançado sistemas de agentes na AWS e orientado times em seus primeiros deploys em produção.

1. Enumere todas as ações do agente. Liste toda tool call, request de API, operação de arquivo e efeito colateral que seu agente pode produzir. Seja exaustivo. Se você perder uma ação, ela roda sem harness.

2. Classifique por reversibilidade. Para cada ação, responda: se isso der errado, quao difícil e consertar? Operações de leitura são sempre reversiveis (não mudam nada). Escritas em arquivo são geralmente reversiveis (git reset). Mudanças de schema de banco são dificeis de reverter. Emails enviados para clientes são irreversiveis.

3. Atribua níveis de controle. Baseado na reversibilidade: auto-executar (reversivel), logar-e-executar (moderadamente reversivel), checkpoint (difícil de reverter), bloquear (irreversível sem humano).

4. Implemente a camada de permissão. Codifique as regras de allow/deny. Essa e sua primeira linha de defesa é a mais importante de acertar.

5. Adicione observação. Instrumente o harness para emitir eventos estruturados para cada ação tomada. Você vai precisar desses dados para calibrar checkpoints depois.

6. Faca deploy em shadow mode. Rode o harness junto com seu processo existente. Não de ao agente poder de execução real ainda. Observe. Aprenda. Calibre.

7. Gradue para produção. Uma vez que o shadow mode demonstre padrões de comportamento aceitaveis (tipicamente 2-4 semanas), habilite execução real com todos os checkpoint gates ativos.

Essa sequência e deliberadamente lenta. Quando o downside de se mover rápido é um incidente de produção, se mover devagar é o caminho mais rápido para valor.

O futuro do AI harness

Harness engineering e jovem. Os padrões estão se estabilizando, mas o tooling ainda é primitivo. Hoje, a maioria dos times constrói harnesses customizados do zero. Até 2027, eu espero que frameworks de harness sejam tão comuns quanto web frameworks. Você não vai construir um sistema de agentes em produção sem um, assim como você não construiria uma web app de produção sem um framework.

Os times que dominarem harness engineering agora terão uma vantagem composta. Cada semana operando um harness em produção gera dados de calibração. Esses dados tornam o harness mais preciso: menos checkpoints desnecessarios, limites mais apertados que ainda permitem autonomia útil máxima, melhor detecção de anomalias a partir de baselines comportamentais mais ricos.

O time de AI da Notion descreveu esse efeito em um post de blog de engenharia de 2025: após seis meses de operação do harness, a taxa de aprovação de checkpoint deles excedeu 97%, significando que humanos aprovaram 97% das ações gated sem modificacao. O harness havia aprendido (através de calibração, não ML) exatamente quais ações genuinamente precisavam de revisão humana e quais estavam sendo gated desnecessariamente. A velocidade do agente deles aumentou 3x sem nenhuma redução em segurança, puramente por calibração do harness.

Essa melhoria de 3x esta disponível para todo time disposto a investir no harness cedo.

Principais conclusões

• Harness engineering constrói restrições arquiteturais fora do raciocínio do modelo para que agents não possam contornar regras de segurança.
• Até modelos top violam restrições explicitas do system prompt 4-7% das vezes em tarefas multi-step, tornando segurança apenas por prompt insuficiente.
• As quatro camadas de harness são: classificação de ações, limites de escopo, gates de checkpoint e observação continua.
• Comece restritivo, depois expanda permissões baseado em comportamento observado; mire em uma taxa de aprovacao de checkpoint de 85-95%.
• Design de harness e uma decisão de produto porque equilibra velocidade, segurança, autonomia e necessidades do usuário simultaneamente.

FAQ

O que é harness engineering em sistemas de AI?

Harness engineering é a prática de projetar restrições, checkpoints e superficies de controle que envolvem agentes de AI, permitindo que operem com autonomia útil enquanto previnem ações perigosas ou irreversiveis. O harness opera no nível do sistema, fora do processo de raciocínio do modelo, fornecendo enforcement que não pode ser contornado pela própria tomada de decisão do agente.

Como um AI harness e diferente de prompt engineering?

Prompt engineering diz ao agente o que fazer através de instruções na sua context window. Um harness enforces o que o agente pode fazer através de restrições arquiteturais fora do controle do modelo. Prompts podem ser mal interpretados ou ignorados (taxa de falha de 4-7% em tarefas multi-step). Restrições de harness não podem ser contornadas por raciocínio porque operam na camada de execução, não na camada de raciocínio.

Preciso de um harness se meu agente e usado apenas internamente?

Sim. Agentes internos ainda podem causar danos significativos: deletar dados de produção, consumir creditos de API excessivos, modificar configuração de infraestrutura ou vazar informações sensiveis entre limites de time. O harness deve ser calibrado diferentemente para agentes internos vs. externos (harnesses internos podem ser menos restritivos), mas eliminar o harness completamente para uso interno é um erro comum que leva a incidentes.

Qual é a relação entre harness engineering e context engineering?

Context engineering determina com quais informações o agente raciocina. Harness engineering determina quais ações o agente pode tomar independente de seu raciocínio. São disciplinas complementares. Context engineering melhora a qualidade das decisões do agente. Harness engineering limita as consequências de decisões ruins. Sistemas de produção precisam de ambos.

Quao restritivo um harness de produção deveria ser?

Comece mais restritivo do que você acha necessário, depois calibre baseado em comportamento observado. A métrica chave e sua taxa de aprovação de checkpoint: se humanos aprovam mais de 95% das ações gated sem modificacao, seu harness provavelmente e restritivo demais e deveria ser afrouxado. Se a taxa de aprovação cai abaixo de 80%, seu harness pode ser permissivo demais. Mire em 85-95% de taxa de aprovação para balanco ótimo entre velocidade e segurança.

Leitura relacionada

• What Is a Product Engineer? - A definição fundacional do papel para engenheiros que são donos de resultados, não apenas outputs
• Agentic Engineering: Working With AI, Not Just Using It - Como product engineers projetam sistemas para colaboração humano-agente
• Context Engineering: The Skill That Replaced Prompt Engineering - A disciplina de estruturar ambientes de informação para agentes de AI
• The Multi-Agent Architecture That Actually Ships - Padrões de produção para sistemas de agentes coordenados
• How to Become a Product Engineer - O caminho de carreira para engenheiros que querem ser donos do full stack e do resultado completo