O que é Harness Engineering e Loop Engineering e como eles se diferenciam

Por

A rápida evolução dos agentes de IA (os chamados agentic systems) trouxe uma enxurrada de novos termos para o vocabulário de arquitetura de software: Prompt Engineering, Context Engineering, Harness Engineering e, mais recentemente, Loop Engineering.

Com tantos neologismos, é fácil dispensar essas nomenclaturas como mero buzzword. No entanto, a confusão entre Harness Engineering e Loop Engineering é a razão primária pela qual muitos projetos de agentes de IA falham ao tentar sair do ambiente de testes (sandbox) para a produção.

Neste post, vou desmistificar esses dois conceitos, entender suas diferenças fundamentais, onde eles se conectam e como aplicar um framework prático para decidir qual construir primeiro.

A Diferença Essencial

  • Harness Engineering (Engenharia de Armação/Scaffolding): Define os limites, a infraestrutura e a segurança do ambiente onde o agente opera. Trata de o que o agente tem permissão de fazer e como garantimos que a execução seja segura e observável.
  • Loop Engineering (Engenharia de Loop): Define a orquestração e a cadência autônoma de execução que substitui o humano disparando prompts. Trata de como o sistema encontra o trabalho, itera até atingir o objetivo e sabe a hora exata de parar.

Harness Engineering: A Infraestrutura de Proteção

O termo harness remete à estrutura rígida ou aos cintos de segurança que mantêm algo sob controle. Na engenharia de software para IA, o harness é o código determinístico que envolve o modelo probabilístico.

Quando um modelo de linguagem (LLM) precisa invocar ferramentas (APIs, bancos de dados, terminais), o harness é a camada de software responsável por:

  • Gerenciamento de permissões e segurança: Limitar o blast radius (raio de impacto). O agente pode ler o banco de dados? Pode fazer commit direto na main ou apenas criar uma branch?
  • Validação determinística: Verificar se o output do modelo segue esquemas (JSON Schemas, validações de compilação, testes unitários) antes que a ação seja de fato aplicada no sistema real.
  • Observabilidade e auditoria: Logar o contexto enviado ao LLM, as respostas brutas, os chamadas de ferramentas e os custos/latência de cada passo.
  • Tratamento estruturado de erros: Transformar stack traces em mensagens acionáveis para que o modelo consiga se recuperar de falhas de execução.

Sem Harness Engineering: Você tem um agente “sem freios”. Ele pode entrar em um ciclo infinito de chamadas de API, vazar credenciais ou apagar acidentalmente dados de produção.

Loop Engineering: A Automação do Prompting

Como definir a transição do modelo tradicional de prompting para o loop engineering?

Em vez de um humano interagir turno por turno com o chat (“Analise este erro” -> “Agora corrija” -> “Agora rode os testes”), o Loop Engineering cria uma arquitetura de orquestração autônoma:

  • Geração e descoberta de trabalho: O loop monitora eventos ou agendas (ex: falhas de CI/CD na madrugada, novos tickets no Jira) e formula metas autonomamente.
  • Ciclo ReAct / OODA: O agente planeja, executa, observa os resultados e decide a próxima ação sem intervenção humana a cada passo.
  • Condições de término (Stopping Criteria): Regras claras de convergência para saber quando a tarefa foi concluída ou quando atingiu o teto de iterações.
  • Validação Maker/Checker: Divisão do trabalho entre sub-agentes (um agente executa a tarefa e outro agente/validador avalia se o critério de aceite foi atingido).

Sem Loop Engineering: Seu agente exige supervisão constante a cada interação. Ele até possui boas ferramentas e segurança, mas depende de um humano alimentando novos prompts manualmente a todo instante.

Comparativo Direto: Harness vs. Loop Engineering

AspectoHarness EngineeringLoop Engineering
Foco principalLimites, segurança, ferramentas e observabilidade.Cadência, iteração, autonomia e tomada de decisão.
Escopo de atuaçãoPor sessão / por execução do modelo.Através de múltiplas execuções e ao longo do tempo.
Artefatos típicosConfigurações de API, linters, policy gates, sandboxes, logs.Estratégias de retry, sub-agentes, gerenciadores de estado e triggers.
Pergunta-chaveComo garantir que a ação executada seja segura e válida?O que o agente deve fazer a seguir e quando ele deve parar?
Sintoma de ausênciaAções não auditadas, vazamento de escopo, custos descontrolados.Gargalo humano, incapacidade de rodar tarefas em segundo plano.

Qual Construir Primeiro? (Framework de Decisão)

O erro mais comum das equipes de engenharia é tentar implementar Loop Engineering (agentes autônomos rodando em background) sem antes construir um Harness sólido.

Para estruturar seu projeto de forma segura:

  1. Priorize o Harness no início: Se seu agente ainda está rodando com supervisão humana direta, invista em validação de outputs, permissões de ferramentas e registros de auditoria. Garanta que o agente não consiga causar danos ao ambiente.
  2. Implemente o Loop quando o comportamento do agente estiver maduro: Assim que o comportamento individual do agente em um ambiente controlado for confiável, desenhe os loops autônomos para agendar, iterar e verificar o trabalho sem intervenção humana.
  3. Mantenha o pragmatismo técnico: Nem tudo precisa de um loop orientado a agentes de IA. Se a tarefa puder ser resolvida por um script determinístico em Python de 10 linhas, use o script. Reserve loops de IA apenas para problemas que exigem julgamento dinâmico em tempo de execução.

Harness e Loop Engineering não são abordagens concorrentes, mas sim camadas complementares na pilha de software para sistemas inteligentes: o Harness torna o agente confiável em produção, enquanto o Loop o torna verdadeiramente autônomo.

Ao separar essas duas disciplinas no seu time, você evita surpresas com estouro de orçamento de tokens e constrói sistemas que não apenas funcionam na sua máquina, mas performam de forma segura e escalável em produção.

Exemplo prático para diferenciar

Para ilustrar como Harness Engineering e Loop Engineering atuam juntos, considere o desenvolvimento de um Agente de Correção Automática de Bugs em Código (Bug Fixer) para um pipeline de CI/CD.

Abaixo está o exemplo prático da arquitetura dividida entre os dois conceitos.

O objetivo do sistema é simples: quando a suíte de testes de um projeto falha no GitHub, o agente analisa a falha, altera o código, valida se o erro foi resolvido e abre um Pull Request (PR).

1. O Harness (A Camada de Limites e Segurança)

O Harness é o código determinístico responsável por controlar o ambiente de execução e as ferramentas que o modelo de linguagem (LLM) utilizará. Ele não toma decisões autônomas de alto nível; ele executa ações e impõe regras.

Componentes do Harness:

  • Sandbox de Execução: O agente roda dentro de um container Docker isolado, sem acesso à rede externa (evitando data exfiltration).
  • Definição de Ferramentas (Tool Calling):
    • read_file(filepath): Lê apenas arquivos dentro do diretório do projeto.
    • write_file(filepath, content): Escreve arquivos no código-fonte, mas bloqueia alterações em arquivos de configuração crítica (ex: .env, Dockerfile).
    • run_tests(): Executa o comando pytest e captura a saída textual.
  • Validação Determinística: Antes de permitir que o agente salve uma alteração, um linter estático (como o flake8) verifica se a sintaxe do Python é válida. Se o código for sintaticamente inválido, o Harness rejeita a alteração diretamente, sem nem rodar os testes.
  • Política de Segurança e Limites (Guardrails):
    • Limite máximo de $2.00 por sessão de API do LLM.
    • Bloqueio de commits diretos na branch main. O Harness força a criação de uma branch temporária fix/bug-id.

2. O Loop (A Cadência Autônoma e Tomada de Decisão)

O Loop é o fluxo contínuo de raciocínio e execução que substitui o humano digitando prompts no ChatGPT.

Fluxo de Execução do Loop:

  1. Trigger de Entrada (Geração de Trabalho):
    • O GitHub Webhook notifica uma falha nos testes e dispara o ciclo do agente.
  2. Loop de Raciocínio (Ciclo ReAct):
    • Turno 1: O agente chama a ferramenta run_tests() via Harness e obtém a stack trace do erro.
    • Turno 2: O agente analisa o log, descobre qual arquivo falhou e chama read_file("src/calculator.py").
    • Turno 3: O agente propõe a correção e chama write_file("src/calculator.py", updated_code).
    • Turno 4: O agente chama run_tests() para verificar se o problema foi resolvido.
  3. Condições de Término (Stopping Criteria):
    • Sucesso: Todos os testes do pytest passaram (código de retorno 0). O Loop encerra e chama a API do GitHub para abrir o PR.
    • Falha de Limite: Se o Loop atingir 5 iterações sem que os testes passem, ele aborta a execução, desfaz as alterações e marca o ticket no Jira como “Falha ao corrigir automaticamente: intervenção humana necessária”.

O que acontece quando um dos dois falta?

CenárioO que acontece na prática
Apenas Loop (Sem Harness)O agente tenta corrigir o erro, entra num ciclo infinito modificando o arquivo .env, apaga testes de validação para fazer o comando passar “na marra” e estoura $50 em chamadas de API em 10 minutos.
Apenas Harness (Sem Loop)As ferramentas de leitura, escrita e testes funcionam com total segurança e isolamento, mas o agente só executa um passo de cada vez. Um engenheiro precisa ficar dando prompts manuais: “agora leia o arquivo X”, “agora aplique o fix”, “agora rode o teste”.

Exemplo de Código (Pseudocódigo da Arquitetura)

# HARNESS: Interface determinística de controle
class Harness:
    def __init__(self, sandbox_dir, max_cost=2.0):
        self.sandbox_dir = sandbox_dir
        self.max_cost = max_cost
        self.current_cost = 0.0

    def run_tests(self):
        # Executa testes isolados no container e retorna o resultado
        return execute_in_docker(self.sandbox_dir, "pytest")

    def safe_write_file(self, filepath, content):
        if filepath in ["Dockerfile", ".env"]:
            raise PermissionError("Alteração em arquivo crítico bloqueada.")
        if not check_python_syntax(content):
            return "Erro de sintaxe no código fornecido. Verifique e tente novamente."
        return write_to_disk(filepath, content)


# LOOP: Orquestração autônoma do raciocínio
def run_fixer_loop(harness, bug_description):
    max_iterations = 5
    iteration = 0
    state = f"Objetivo: Corrigir o seguinte erro:\n{bug_description}"

    while iteration < max_iterations and harness.current_cost < harness.max_cost:
        iteration += 1
        
        # 1. Envia estado atual ao LLM e recebe a decisão de ação
        response = call_llm(state)
        
        # 2. Executa a ferramenta solicitada pelo LLM através do Harness
        tool_output = harness.execute_tool(response.chosen_tool, response.tool_args)
        
        # 3. Atualiza o contexto do loop
        state += f"\nAção {iteration}: {response.chosen_tool}\nResultado: {tool_output}"
        
        # 4. Condição de Término (Sucesso)
        if "0 failed, ALL PASSED" in tool_output:
            harness.open_pull_request()
            return "Bug corrigido com sucesso!"

    return "Não foi possível resolver o bug dentro do limite de iterações."
Code language: Python (python)

Deixe um comentário