Ir para o conteúdo principal
Zubnet AI › Aprender › Wiki › Harness de agente
Usar AI

Harness de agente

Também conhecido como: Agent Harness, Scaffolding, Agent Scaffold
O software em volta de um modelo que o transforma em agente, incluindo o loop, as ferramentas, o gerenciamento de contexto, as permissões e a memória.

Por que isso importa

O mesmo modelo pode ter desempenhos muito diferentes dependendo do harness. Em benchmarks de programação como SWE-bench Verified e Terminal-Bench, mudar apenas o harness pode mover as pontuações em muitos pontos, e é por isso que os rankings listam o modelo e o sistema de agente juntos. Quando um produto de agente parece mais inteligente do que uma chamada direta à API do mesmo modelo, o motivo é o harness.

Para quem constrói, o harness é onde vai a maior parte da engenharia. Em geral você não pode mudar o modelo, mas pode mudar o que ele vê, quais ferramentas ele tem e o que acontece quando algo dá errado.

Em profundidade

Um modelo de linguagem sozinho apenas mapeia texto para texto. Ele não consegue ler um arquivo, executar um comando ou lembrar o que fez uma hora atrás. O harness é o programa em volta do modelo que torna essas coisas possíveis. Ele envia um prompt ao modelo, executa as chamadas de ferramentas que o modelo pede, devolve os resultados e repete até a tarefa terminar.

Um atalho útil: agente = modelo + harness. O Claude Code, o Codex CLI da OpenAI, o modo agente do Cursor e projetos open source como OpenHands e SWE-agent são todos harnesses. Também são os frameworks que as pessoas usam para construir o seu, como o Claude Agent SDK, o OpenAI Agents SDK e o LangGraph. Pesquisadores costumam chamar a mesma coisa de scaffolding (andaime).

O que um harness faz

  • O loop: chamar o modelo, executar as chamadas de ferramentas, devolver os resultados, repetir e decidir quando parar.
  • Ferramentas: defini-las, validar os argumentos, executá-las e formatar os resultados para que sejam curtos e úteis. O artigo do SWE-agent chamou isso de agent-computer interface e mostrou que o design das ferramentas importa tanto quanto os prompts.
  • Gerenciamento de contexto: montar o prompt de sistema, carregar as instruções do projeto, resumir o histórico antigo (compactação) quando a janela de contexto enche e manter o cache de prompt intacto.
  • Permissões e sandboxing: decidir quais ações rodam automaticamente, quais precisam de aprovação humana e no que o agente pode mexer.
  • Memória e estado: anotações, listas de tarefas e arquivos que sobrevivem além de uma janela de contexto, além de checkpoints para desfazer.
  • Orquestração: disparar subagentes, rodar ferramentas em paralelo, tentar de novo após erros e impor limites de passos e de tokens.

Um harness mínimo

O loop central é pequeno:

messages = [{"role": "user", "content": task}]
while True:
    reply = model(messages, tools=tools)
    messages.append(reply)
    if not reply.tool_calls:
        break
    for call in reply.tool_calls:
        messages.append(run_tool(call))

Todo o resto em um harness de produção existe para lidar com o que esse loop ignora: tarefas longas, falhas, segurança e custo.

Cada vez mais fino

Os primeiros sistemas de agentes precisavam de muito andaime: planos rígidos, parsers de saída, recuperação construída à mão e muitos prompts especializados. À medida que os modelos melhoraram no uso de ferramentas e no planejamento, boa parte disso se tornou desnecessária ou até prejudicial, porque impedia o modelo de usar o próprio julgamento. É a lição amarga aplicada aos agentes. Muitos dos harnesses mais fortes de hoje são deliberadamente simples: um bom loop, algumas ferramentas gerais como um shell e um editor de arquivos, e um gerenciamento cuidadoso do contexto.

Disso decorre um hábito prático: quando sair um modelo novo, experimente remover partes do seu harness e veja se os resultados melhoram.

Harness e avaliação

Como o harness muda os resultados, os números de benchmark só são comparáveis quando o harness é o mesmo. Nas avaliações de segurança, um harness fraco é um risco real, porque pode fazer um modelo parecer menos capaz do que é. Por isso os avaliadores investem em elicitação: dar ao modelo boas ferramentas e orçamento suficiente para mostrar o que ele realmente consegue fazer.

Escolher ou construir um

Comece com um harness ou SDK existente, a menos que você tenha necessidades incomuns. Invista primeiro em ferramentas com descrições claras e saídas compactas, depois no gerenciamento de contexto e depois nas permissões. Registre em log cada passo do loop. Quando algo falhar, leia a transcrição: a maioria das falhas de agentes vem do que foi mostrado ao modelo, não da capacidade do modelo.

← Todos os termos
ESC