Phase 14 - Lesson 31

Engenharia de Bancada de Agente: Por Que Modelos Capazes Ainda Falham

Um modelo capaz não é suficiente. Agentes confiáveis precisam de uma bancada: instruções, estado, escopo, feedback, verificação, revisão e transição. Remova esses elementos e até mesmo um modelo de fronteira produzirá um trabalho que não é seguro para enviar para produção.

Tipo: Aprender + Construir Linguagens: Python (stdlib) Pré-requisitos: Fase 14 · 01 (Loop de Agente), Fase 14 · 26 (Modos de Falha) Tempo: ~45 minutos

Objetivos de Aprendizado

• Separar a capacidade do modelo da confiabilidade da execução.
• Nomear as sete superfícies da bancada que decidem se um agente pode ser enviado para produção.
• Comparar uma execução apenas com prompt contra uma execução guiada por bancada em uma tarefa de repositório pequeno.
• Produzir um relatório de modos de falha que mapeia cada superfície ausente ao sintoma causado.

O Problema

Você insere um modelo de fronteira em um repositório real e pede para ele adicionar validação de entrada. Ele abre quatro arquivos, escreve um código plausível, declara sucesso e para. Você executa os testes. Dois falham. Um terceiro arquivo que não tinha nada a ver com validação é modificado. Não há registro do que o agente assumiu, do que tentou primeiro ou do que resta fazer.

O modelo não estava errado sobre Python. Ele estava errado sobre o trabalho. Ele não tinha ideia do que era considerado concluído, onde tinha permissão para escrever, quais testes eram autoritativos ou como a próxima sessão deveria continuar.

Isso não é um bug de modelo. É um bug de bancada. Faltam na superfície ao redor do agente as partes que transformam uma geração única (one-shot) em uma engenharia confiável e retomável.

O Conceito

Uma bancada é o ambiente operacional que envolve o modelo durante uma tarefa. Ela possui sete superfícies:

flowchart LR
  Task[Tarefa] --> Scope[Contrato de Escopo]
  Scope --> State[Memória do Repositório]
  State --> Agent[Loop do Agente]
  Agent --> Feedback[Feedback de Execução]
  Feedback --> Verify[Portão de Verificação]
  Verify --> Review[Revisor]
  Review --> Handoff[Transição]
  Handoff --> State

O loop se fecha no arquivo de estado, não no histórico do chat. O chat é volátil. O repositório é o sistema de registro.

Engenharia de bancada versus engenharia de prompt

O prompt diz ao modelo o que você quer neste turno. Uma bancada diz ao modelo como realizar o trabalho ao longo de turnos e sessões. A maioria das histórias de falhas de agentes são falhas de bancada vestidas de engenharia de prompt.

Bancada versus framework

Um framework fornece um ambiente de execução (LangGraph, AutoGen, Agents SDK). Uma bancada dá ao agente um lugar para trabalhar dentro desse ambiente de execução. Você precisa de ambos. Esta mini-trilha é sobre a segunda parte.

Raciocinando a partir de primitivos, não de taxonomias de fornecedores

Há muitos textos sobre "engenharia de harness" (harness engineering) sendo publicados agora. Addy Osmani, OpenAI, Anthropic, LangChain, Martin Fowler, MongoDB, HumanLayer, Augment Code, Thoughtworks, a lista awesome da walkinglabs e um fluxo constante de artigos no Medium e no Hacker News estão abordando o assunto. Eles discordam sobre o limite do que é um harness, o que está no escopo e qual vocabulário usar. Não precisamos escolher um lado. As sete superfícies são uma camada de UX; por baixo de cada bancada está o mesmo conjunto de primitivos de sistemas distribuídos que sustentam qualquer backend confiável.

Remova o rótulo de agente por um momento. A execução de um agente é uma computação que atravessa tempo, processos e máquinas. Para tornar isso confiável, você precisa dos mesmos primitivos que qualquer sistema de produção precisa.

Agora mapeie as sete superfícies da bancada nesses primitivos.

• Instruções — política + metadados da função. Regras são verificações (funções). O roteador (AGENTS.md) é a política anexada à inicialização do runtime.
• Estado — persistência de sessão. Um armazenamento indexado por chave que o runtime lê a cada etapa. Arquivo, KV ou banco de dados; a semântica da persistência importa, o backend de armazenamento não.
• Escopo — política de autorização por tarefa. Globs permitidos/proibidos são uma ACL. As aprovações necessárias são uma estrutura de permissões (permission lattice).
• Feedback — log de invocação gravado em uma fila. Cada chamada de terminal é um registro durável e reproduzível.
• Verificação — uma função. Determinística em relação às entradas. Disparada no encerramento da tarefa. Falha no modo seguro (fails closed).
• Revisão — um worker separado com autorização de apenas leitura nos artefatos do construtor e autorização de apenas escrita nos relatórios de revisão.
• Transição — um registro durável emitido por um gatilho de fim de sessão. O gatilho de inicialização da próxima sessão o lê.

O próprio loop do agente é um worker que consome eventos (mensagem do usuário, resultado da ferramenta, tick de cronômetro), chama funções (o modelo e, em seguida, as ferramentas que o modelo escolhe), grava registros (estado, feedback) e emite gatilhos (verificar, revisar, transição). Sem mistério; tem o mesmo formato de um processador de jobs.

Padrões em circulação, traduzidos para primitivos

Todo padrão popular de harness se reduz aos oito primitivos. Tabela de tradução.

Every entry in that table is the agent community arriving at a primitive that already had a name in distributed systems and giving it a new one. Useful labels for marketing; not useful as engineering vocabulary.

O que as evidências realmente dizem

A afirmação de que o harness é superior ao modelo agora possui números que a sustentam. Vale a pena saber disso, pois eles também são o único argumento honesto contra o pensamento de "apenas esperar por um modelo mais inteligente".

• Terminal Bench 2.0 — mesmo modelo, a mudança de harness levou um agente de programação de fora do top 30 para o quinto lugar (LangChain, Anatomy of an Agent Harness).
• Vercel — deletou 80% das ferramentas de seu agente; a taxa de sucesso saltou de 80% para 100% (MongoDB).
• Harvey — agentes jurídicos mais que dobraram a precisão apenas através da otimização do harness (MongoDB).
• 88% dos projetos de agentes de IA corporativos falham em chegar à produção. As falhas se concentram em torno do runtime, não do raciocínio (preprints.org, Harness Engineering for Language Agents, março de 2026).
• Um estudo de benchmark de 2025 em três frameworks open-source populares relatou ~50% de conclusão de tarefas; o WebAgent de contexto longo desmoronou de 40-50% para menos de 10% em condições de contexto longo, principalmente devido a loops infinitos e perda de objetivos (amplamente coberto em artigos no início de 2026).

A lição não é "o harness vence para sempre". Os modelos absorvem os truques de harness ao longo do tempo. A lição é que, hoje, a engenharia de sustentação está em torno do modelo, não dentro dele, e os primitivos que suportam essa carga são os mesmos que todo sistema de produção sempre precisou.

Onde os artigos dos fornecedores ficam curtos

Esta é a parte sobre a qual você não precisa ser educado.

• O artigo Anatomy of an Agent Harness da LangChain enumera onze componentes — prompts, ferramentas, hooks, sandboxes, orquestração, memória, habilidades, subagentes e um "loop simples" de runtime. Ele não cita filas, workers como unidade de implantação, semântica de gatilhos, persistência de sessão como uma preocupação separada ou política de autorização. Ele trata o harness como um objeto que você configura, não como um sistema que você implanta.
• O texto Agent Harness Engineering de Addy Osmani define a estrutura Agent = Model + Harness e o padrão ratchet, mas não explica de que o harness é feito. Ele soa como uma postura, não como uma especificação.
• A Anthropic e a OpenAI vão mais fundo nas superfícies, mas permanecem dentro de seus próprios runtimes. O anúncio de "separação harness-computação" no Agents SDK de abril de 2026 é o primeiro texto de fornecedor que apoia explicitamente a divisão plano de controle / plano de dados. Essa é uma ideia primitiva, não uma novidade.
• O livro agentic_harness trata o harness como um objeto de configuração (capítulo 6 de Agentic Engineering de Jaymin West) e a afirmação mais forte nele é "o harness é a barreira de segurança primária em um sistema agentivo". Isso é apenas política de autorização reformulada.
• As discussões no Hacker News continuam chegando ao mesmo lugar. A discussão de abril de 2026 The agent harness belongs outside the sandbox argumenta que o harness deveria se comportar "mais como um hypervisor que fica fora de tudo e autoriza o acesso com base no contexto e no usuário". Isso é, novamente, a política de autorização como um plano separado.

Você não precisa discordar de nenhum desses textos para notar a lacuna. Eles estão escrevendo descrições de UX de um sistema que já existe. Nós estamos escrevendo o sistema. Quando o sistema é construído corretamente, as sete superfícies surgem naturalmente dos primitivos. Quando é construído de forma errada, nenhuma quantidade de polimento em AGENTS.md corrige uma fila ausente.

Portanto, quando ouvir "engenharia de harness" (harness engineering) em outro lugar, traduza para primitivos. Prompts e regras são política e funções. Scaffolding é o runtime. Barreiras de segurança (guardrails) são autorização + verificação. Hooks são gatilhos. Memória é persistência de sessão. O Ralph Loop é enfileirar novamente (requeue). Subagentes são workers. Sandboxes são planos de computação. O vocabulário muda; a engenharia não. A bancada é a UX voltada para o agente; o harness, no sentido que sobrevive à próxima reformulação de fornecedores, é composto por funções, workers, gatilhos, runtimes, filas, persistência e políticas conectados corretamente.

Construa

code/main.py executa uma tarefa pequena de repositório duas vezes. Primeiro apenas com prompt, depois com as sete superfícies conectadas. Mesmo modelo, mesma tarefa. O script conta quais superfícies estavam ausentes na execução com falha e imprime um relatório de modo de falha.

A tarefa do repositório é pequena de propósito: adicionar validação de entrada a um handler no estilo FastAPI de arquivo único e escrever um teste que passe.

Execute:

python3 code/main.py

Saída: um log lado a lado das duas execuções, um failure_modes.json resumindo a execução apenas com prompt e um veredito de uma linha para a execução com a bancada.

O agente é um esboço simples baseado em regras; o ponto principal são as superfícies, não o modelo. Ao longo do restante desta mini-trilha, você reconstruirá cada superfície como um artefato real e reutilizável.

Use

Três lugares onde superfícies de bancada já existem no mundo real, mesmo que ninguém as chame assim:

• Claude Code, Codex, Cursor. AGENTS.md e CLAUDE.md são a superfície de instruções. Comandos de barra são o escopo. Hooks são a verificação.
• LangGraph, OpenAI Agents SDK. Checkpoints e armazenamentos de sessão são a superfície de estado. As transições são a superfície de transição.
• CI em um repositório real. Testes, linter e verificação de tipo são a verificação. O template de PR é a transição. CODEOWNERS é a revisão.

A engenharia de bancada é a disciplina de tornar essas superfícies explícitas e reutilizáveis, em vez de deixar que cada equipe as redescubra.

Envie para Produção

outputs/skill-workbench-audit.md é uma habilidade portátil que audita um repositório existente em busca das sete superfícies de bancada e relata quais estão ausentes, quais são parciais e quais estão saudáveis. Coloque-o ao lado de qualquer configuração de agente; ele diz o que corrigir primeiro.

Exercícios

1. Escolha um repositório onde você já roda um agente. Dê uma nota de 0 (ausente) a 2 (saudável) para as sete superfícies. Qual é a sua superfície mais fraca?
2. Estenda main.py de modo que a execução apenas com prompt também produza uma alegação de "sucesso" falsa. Verifique se o portão de verificação a teria capturado.
3. Adicione uma oitava superfície para o seu próprio produto. Justifique por que ela não se reduz a uma das sete existentes.
4. Execute o script novamente com um agente de simulação diferente que alucine a escrita de um arquivo extra. Qual superfície o captura primeiro?
5. Mapeie os cinco modos de falha recorrentes na indústria da Fase 14 · 26 nas sete superfícies. Qual modo cada superfície foi projetada para absorver?

Termos-Chave

Leitura Adicional

Leia-os como pontos de dados, não como autoridades. Cada um é uma taxonomia parcial. Traduza cada conceito de volta para um primitivo (função, worker, gatilho, runtime, HTTP/RPC, fila, persistência, política) antes de decidir se deve adotá-lo.

Abordagens de fornecedores:

• Addy Osmani, Agent Harness Engineering — Agent = Model + Harness e o padrão ratchet; raso em infraestrutura
• LangChain, The Anatomy of an Agent Harness — onze componentes: prompts, ferramentas, hooks, orquestração, sandboxes, memória, habilidades, subagentes, runtime; omite filas, implantação, autorização
• OpenAI, Harness engineering: leveraging Codex in an agent-first world — a visão da equipe do Codex sobre as superfícies ao redor do seu runtime
• OpenAI, Unrolling the Codex agent loop — o loop do agente reduzido a um while sobre chamadas de função
• Anthropic, Effective harnesses for long-running agents — superfícies de longo horizonte dentro de um runtime específico
• Anthropic, Harness design for long-running application development — notas de design aplicado
• LangChain Deep Agents harness capabilities — superfície de configuração do runtime

Artigos de profissionais com detalhes práticos:

• Martin Fowler / Birgitta Böckeler, Harness engineering for coding agent users — guias (feedforward) + sensores (feedback); a estrutura de teoria de controle mais limpa
• HumanLayer, Skill Issue: Harness Engineering for Coding Agents — "não é um problema de modelo, é um problema de configuração"
• MongoDB, The Agent Harness: Why the LLM Is the Smallest Part of Your Agent System — comprovações: Vercel 80% a 100%, Harvey 2x de precisão, Terminal Bench do Top 30 para o Top 5
• Augment Code, Harness Engineering for AI Coding Agents — passo a passo focado primeiro em restrições
• Sequoia podcast, Harrison Chase on Context Engineering Long-Horizon Agents — preocupações com runtime superando preocupações com o modelo

Livros, artigos acadêmicos e implementações de referência:

• Jaymin West, Agentic Engineering — Chapter 6: Harnesses — tratamento em formato de livro, aborda o harness como o limite primário de segurança
• preprints.org, Harness Engineering for Language Agents (March 2026) — estrutura acadêmica como controle / agência / runtime
• walkinglabs/awesome-harness-engineering — lista de leitura curada abrangendo contexto, avaliação, observabilidade e orquestração
• ai-boost/awesome-harness-engineering — lista curada alternativa (ferramentas, avaliações, memória, MCP, permissões)
• andrewgarst/agentic_harness — implementação de referência pronta para produção com memória baseada em Redis e suíte de avaliação
• HKUDS/OpenHarness — harness de agente aberto com agente pessoal integrado

Discussões do Hacker News que vale a pena ler pelas divergências, não pelo consenso:

• HN: Effective harnesses for long-running agents
• HN: Improving 15 LLMs at Coding in One Afternoon. Only the Harness Changed
• HN: The agent harness belongs outside the sandbox — argumenta a favor de autorização como um plano separado

Referências cruzadas dentro deste currículo:

• Fase 14 · 23 — Convenções GenAI do OpenTelemetry: a camada de observabilidade para a qual a literatura de sensores aponta
• Fase 14 · 26 — Catálogo de modos de falha que as sete superfícies foram projetadas para absorver
• Fase 14 · 27 — Defesas contra injeção de prompt que se situam no primitivo de política de autorização
• Fase 14 · 29 — Runtimes de produção (fila, evento, cron): onde vivem os primitivos desta lição em implantação