Fundamentos: o que é um harness

Aula 1

Agente = modelo + harness

A definição que aparece em praticamente todas as fontes recentes é curta: um agente é um modelo mais um harness. O modelo é o componente que raciocina e gera texto. O harness é tudo o que não é o modelo: o loop que chama o modelo repetidas vezes, as ferramentas que ele pode usar, o que entra na janela de contexto a cada passo, as instruções do projeto, os testes que verificam o trabalho, o sandbox que limita o que ele pode tocar e os registros que permitem auditar o que aconteceu.

A palavra vem do inglês harness, o arreio que permite usar a força de um cavalo numa direção útil. A analogia é boa: o modelo tem muita capacidade, mas sem arreio essa capacidade se dispersa. Addy Osmani resume a consequência prática: um bom harness pode valer mais do que trocar por um modelo melhor.

Isso muda a pergunta que um time deve fazer. Em vez de "qual é o melhor modelo?", a pergunta passa a ser "qual é o melhor sistema para este modelo trabalhar?". Ferramentas como Claude Code, Codex CLI, Cursor e Gemini CLI usam modelos parecidos, mas entregam resultados diferentes porque os harnesses são diferentes: cada um decide de forma própria como buscar contexto, como editar arquivos, quando pedir permissão e como verificar o próprio trabalho.

Há dois papéis para quem estuda harness. O usuário de um agente de código (quem usa Claude Code ou Codex no dia a dia) configura o harness por meio de arquivos como AGENTS.md, skills, hooks, permissões e testes. O construtor de um agente próprio (quem usa o Claude Agent SDK, LangGraph ou um loop escrito à mão) projeta o harness inteiro. O curso cobre os dois papéis, porque os princípios são os mesmos.

Fontes desta aula: Addy Osmani: Agent Harness Engineering · Sydney Runkle: How to Build a Custom Agent Harness · Barbaste et al.: Harness Engineering (arXiv)

Aula 2

Framework, runtime e harness: três camadas

Harrison Chase, da LangChain, propôs uma separação útil entre três camadas que costumam ser confundidas. Um framework oferece abstrações para montar aplicações com LLMs: classes para mensagens, ferramentas, cadeias e integrações. Um runtime oferece execução durável: estado persistido, retomada depois de falhas, streaming e intervenção humana no meio do fluxo. Um harness é a camada mais opinativa, já vem com prompts padrão, ferramentas de planejamento, acesso ao sistema de arquivos e políticas de uso de ferramentas prontas.

O próprio autor reconhece que as fronteiras são borradas e que ainda não há consenso. A separação é útil mesmo assim, porque deixa claro onde cada decisão mora. Escolher como persistir o estado de um agente que roda por horas é uma decisão de runtime. Escolher quais ferramentas ele vê e como o histórico é compactado é uma decisão de harness.

Um dado curioso do estudo de código-fonte de onze agentes de código de produção (Barbaste et al., 2026) reforça a distinção: nenhum dos onze sistemas analisados usa um framework genérico de agentes. Todos escrevem o próprio loop. O valor está no harness, e frameworks genéricos tendem a esconder justamente as decisões que mais importam.

Fontes desta aula: Harrison Chase: Frameworks, Runtimes, and Harnesses · Barbaste et al.: Harness Engineering (arXiv)

Aula 3

Workflows vs. agentes: quanto de autonomia dar

O artigo Building effective agents, da Anthropic, separa dois tipos de sistemas. Em um workflow, o código define o caminho: o LLM é chamado em passos pré-definidos. Em um agente, o próprio modelo decide o caminho: escolhe quais ferramentas usar, em que ordem e quando parar. Workflows são previsíveis e baratos. Agentes são flexíveis e lidam com problemas abertos, mas custam mais e erram de formas menos previsíveis.

O artigo cataloga padrões de workflow que funcionam bem antes de partir para a autonomia total:

• Encadeamento de prompts: a saída de uma chamada vira a entrada da próxima, com checagens entre etapas.
• Roteamento: uma chamada classifica a entrada e direciona para um fluxo especializado.
• Paralelização: várias chamadas trabalham ao mesmo tempo em partes da tarefa, ou votam na mesma pergunta.
• Orquestrador e trabalhadores: um modelo divide a tarefa e delega as partes para outros.
• Avaliador e otimizador: um modelo gera e outro critica, em ciclos, até atingir o critério.

A recomendação central é começar pelo mais simples que resolve o problema e só adicionar autonomia quando ela comprovadamente melhorar o resultado. Isso conversa diretamente com harness: quanto mais autonomia, mais o harness precisa compensar com contexto bem selecionado, ferramentas claras e verificação automática. Um agente sem harness é só um workflow que perdeu os trilhos.

Andrej Karpathy chama essa escolha de controle deslizante de autonomia: bons produtos deixam o usuário decidir quanto entregar ao agente, de sugestões pontuais até tarefas inteiras. O harness é o mecanismo que torna cada posição desse controle segura.

Fontes desta aula: Anthropic: Building effective agents

Aula 4

Anatomia: os subsistemas de um harness de produção

O estudo de Barbaste et al. analisou o código-fonte de onze agentes de código em produção, entre eles Claude Code, Codex CLI e Gemini CLI, e mapeou sete subsistemas recorrentes. Combinando esse mapa com as cinco camadas propostas pela Faros AI e com a divisão de Birgitta Böckeler entre guias e sensores, chega-se a uma anatomia que serve de índice para o restante do curso:

O estudo traz achados concretos sobre o que harnesses reais fazem. Nenhum dos onze usa recuperação por embeddings vetoriais para navegar no código: todos preferem busca determinística, como grep, leitura de arquivos e listagem de diretórios. Skills no formato SKILL.md aparecem em nove dos onze sistemas, à frente do MCP, presente em oito. O artigo também cataloga 29 padrões de design recorrentes e 18 recomendações.

A leitura prática é que harness engineering é, na maior parte, engenharia de software comum aplicada a um novo tipo de executor. Ferramentas bem desenhadas, arquivos de instrução curtos, testes rápidos, permissões mínimas e métricas. O que é novo é que o "usuário" dessas peças é um modelo, que lê tudo literalmente, esquece o que saiu da janela de contexto e repete erros até que algo no ambiente o impeça.

Fontes desta aula: Barbaste et al.: Harness Engineering (arXiv) · Faros AI: Harness engineering guide · Böckeler: Harness engineering for coding agent users

Erros comuns ao começar

• Trocar de modelo antes de olhar o harness. Quando o agente erra, a primeira suspeita costuma ser o modelo. Na maioria dos casos o problema é contexto faltando, ferramenta mal descrita ou ausência de teste que avise o erro.
• Começar pelo agente mais autônomo possível. Um workflow simples resolve muitos casos com menos custo e menos risco. Autonomia é algo a ser conquistado com evidência.
• Adotar um framework pesado para "ter um agente". Os harnesses de produção analisados escrevem o próprio loop. Abstrações demais escondem as decisões que você mais precisa ajustar.
• Tratar o harness como configuração feita uma vez. O harness evolui a cada falha observada. Sem esse ciclo, as mesmas falhas voltam.

Aplicação prática: faça o inventário do seu harness

Antes do próximo módulo, abra o repositório em que você mais usa um agente e responda por escrito, em uma página:

1. Quais arquivos de instrução existem (AGENTS.md, CLAUDE.md, regras do editor) e quantas linhas cada um tem?
2. Quais ferramentas o agente tem disponíveis, incluindo servidores MCP, e quais ele de fato usa?
3. Quais comandos rápidos verificam o trabalho (testes, lint, checagem de tipos) e quanto tempo levam?
4. O que o agente pode fazer sem pedir permissão, e o que acontece se ele ler conteúdo malicioso?
5. Como você sabe se o agente está melhorando ou piorando com o tempo?

As respostas mostram onde está o harness hoje e quais módulos deste curso vão render mais para você.

Siglas usadas neste módulo

LLM:

Large Language Model, modelo de linguagem de grande escala.

SDK:

Software Development Kit, kit de desenvolvimento de software.

MCP:

Model Context Protocol, protocolo aberto para conectar agentes a ferramentas e dados.

CLI:

Command-Line Interface, interface de linha de comando.