AI Brasil
AI Avançado

Hugging Face treina harness adapters que cortam custo e token de agentes de IA sem retreinar o modelo

Hugging Face publicou em 20 de novembro de 2026 uma receita que treina um adaptador LoRA via aprendizado por reforço dentro do próprio harness do agente: o Qwen3.8-27B saiu de 39% para 55% de acerto no Terminal-Bench 2.1 usando quase metade dos tokens por tarefa.

Lucas FerrazColunista

· 8 min de leitura

Este artigo foi escrito por Lucas Ferraz. Conteúdo produzido por agente de IA da redação AI Brasil, sob revisão editorial humana. Saiba como produzimos no expediente.

Imagem gerada por IA

O problema que ninguém resolve só trocando de modelo

Todo modelo de linguagem que você conecta a um agente (o conjunto de código que decide quando chamar uma ferramenta, como montar o prompt e quando parar de pensar, chamado de harness no jargão de RL) foi treinado para ser bom em geral, não para ser bom no SEU harness com as SUAS tarefas. Isso sobra em tokens gastos, chamadas de ferramenta redundantes e respostas erradas na primeira tentativa.

Em 20 de novembro de 2026, o Hugging Face publicou uma receita chamada harness adapters: em vez de re-treinar o modelo inteiro, você treina um adaptador pequeno (LoRA, Low-Rank Adaptation: uma matriz de pesos extra, bem menor que o modelo, que se soma aos pesos originais sem alterá-los) especificamente para o par modelo mais harness que você já usa em produção. O modelo base fica congelado. Só o adaptador aprende.

O número que importa: menos tokens, mais acerto, no mesmo harness

O exemplo que a equipe usa para resumir o ganho é direto: rodando Qwen3.8-27B no harness Pi (versão 1.5.2), o modelo base cravou 39% de acerto (pass@1) no Terminal-Bench 2.1, benchmark de tarefas de terminal, gastando em média 2,9 mil tokens por tarefa. Com os pesos do modelo congelados e um adaptador LoRA treinado por reforço especificamente para esse harness, o mesmo par foi a 55% de acerto usando em média 1,5 mil tokens por tarefa.

O ganho não vem de o modelo "pensar mais": vem do contrário. Segundo a publicação, a maior parte da melhora é o modelo raciocinando menos, chamando menos ferramentas e acertando de primeira com mais frequência. Para quem paga por token de inferência, isso é custo caindo quase pela metade na mesma chamada, sem trocar de fornecedor de modelo.

Como o treino funciona: RL de dentro do harness, não uma cópia dele

A maioria dos frameworks de RL para agentes reimplementa o loop do agente dentro do próprio framework (o AgentLoop do verl, os ambientes do SkyRL-Gym, as classes de agente do rLLM, as funções de rollout do slime, o cliente do ART). O modelo aprende contra uma versão aproximada do harness real.

A equipe do Hugging Face fez diferente: o harness roda exatamente como ele é distribuído em produção (Pi 1.5.2, OpenCode 2.2.7 e Hermes Agent v0.22.6, cada um numa imagem Docker própria), e um proxy entre o harness e o servidor vLLM registra os tokens exatos que ele produziu. O treinador aprende em cima desses tokens reais, não de uma simulação. A publicação cita dois trabalhos recentes na mesma direção: Agent Lightning v1.0, que também mantém o harness de produção no loop via proxy (RL agentic "com harness"), e a integração do SkyRL com Harbor, que converte históricos de chat de trials do Harbor em tokens de treino.

O treino em si usa o AsyncGRPOTrainer da biblioteca TRL, que aplica GRPO (group relative policy optimization: cada tentativa do agente é pontuada contra as outras tentativas na mesma tarefa, sem precisar de um modelo crítico separado) e não espera todos os rollouts terminarem antes de seguir para o próximo passo de otimização. Toda a infraestrutura, do dataset ao rollout do agente, rodou em Hugging Face Jobs, usando OpenEnv e a integração com Harbor.

De onde vêm as tarefas, e por que a maioria foi descartada

Treinar com RL exige tarefas que o agente consiga tentar, um verificador que pontue cada tentativa corretamente, e prova de que esse verificador não está mentindo. Um verificador que aceita resposta errada ensina o comportamento errado; uma tarefa que o modelo já resolve sempre não ensina nada.

A equipe partiu de uma busca no Hub por ambientes no formato Harbor (o mesmo formato do Terminal-Bench 2.1) e encontrou cerca de 59 mil tarefas, cheias de duplicatas e conjuntos de avaliação. Depois de filtrar, sobraram três fontes:

  • SWE-smith (Python e Go): injeta bugs em repositórios reais com reescrita por LLM ou mutação de código; os testes que pegam o bug viram a tarefa.
  • SWE-Gym (empacotado como TaskTrove): transforma issues reais do GitHub e seus merges de correção em tarefas.
  • Tasksmith: gera tarefas a partir de pull requests mergeados; um agente de LLM escreve a instrução e os testes, e o pipeline verifica se a solução de referência passa e se uma solução errada conhecida falha.

Cada tarefa passou por dois filtros com o comando openenv validate, que pode ser rodado por qualquer um:

openenv validate path/to/task --sandbox hf-sandbox

O primeiro filtro é semântico: a solução de referência precisa tirar a nota máxima, não fazer nada precisa tirar nota claramente menor, nenhum atalho ("canário") pode pontuar mais que não fazer nada, e repetir a mesma solução precisa dar a mesma nota. De 1.127 candidatas do Hub, 858 passaram; as falhas pegaram defeitos reais, incluindo um verificador do próprio Terminal-Bench 2.1 que aceitava respostas erradas por causa de um regex mal feito.

O segundo filtro é de dificuldade: o Qwen3.8-27B tentou cada tarefa de 4 a 8 vezes antes do treino. Das 442 tarefas pontuadas, ele resolveu 151 sempre e 120 nunca. Só as 171 que ele acerta às vezes (nem sempre, nem nunca) entraram no treino de RL, porque são as únicas que geram sinal de aprendizado no GRPO.

FonteTipo de tarefaTarefas totaisQualificadas para RL
SWE-smithBugs injetados em Python e Go717144
SWE-Gym (TaskTrove)Issues reais do GitHub13027
TasksmithGeradas de pull requests mergeados2422

O dataset final, publicado como harness-hub/agentic-coding-envs, reúne 871 tarefas de 35 repositórios (limitadas a 40 por repositório para nenhum projeto dominar), com 171 delas qualificadas para o treino de RL.

Um adaptador por harness, depois um só para os três

A equipe treinou um LoRA separado para cada harness (Pi, OpenCode, Hermes Agent), cada um em duas GPUs NVIDIA B200 (uma rodando o servidor vLLM, outra rodando o treino), usando a flag all-linear para anexar o adaptador a todas as camadas lineares do modelo. O modo de raciocínio estendido ficou desligado durante os rollouts para ganhar velocidade, e foi reativado só na avaliação final para comparação.

Uma varredura de taxa de aprendizado em 50 passos mostrou o quanto esse ajuste é sensível: 1e-5 quase não mudou a taxa de acerto (de 0,52 para 0,50), 1e-4 colapsou os rollouts (o agente passou de 18 para 6 turnos por tentativa, com a entropia subindo), e só 5e-5 melhorou de forma clara (de 0,49 para 0,60 no passo 40). Rodadas mais longas em 5e-5 mostraram sinais de instabilidade, então o valor final usado foi 2e-5. A recompensa combinou o acerto do verificador com um bônus pequeno (0,1) por eficiência de chamadas de ferramenta.

Depois de treinados os três adaptadores separados, a equipe testou se dava para juntar os três em um só. A similaridade de cosseno entre as atualizações de peso de cada adaptador ficou entre 0,01 e 0,02, ou seja, cada um empurrou o modelo numa direção quase ortogonal às outras, o cenário ideal para fundir sem perder desempenho.

A fusão usada foi a concatenação ao longo da dimensão de rank do PEFT (combination_type="cat"), somando as três atualizações com um peso de escala. Testaram três pesos nas 89 tarefas do Terminal-Bench 2.1, sob cada harness:

Peso aplicadoPiHermesOpenCodeMédia dos trêsChamadas de ferramenta por tarefa
Modelo base39,1%46,0%44,8%43,3%49,2
⅓ (média simples)49,4%51,2%47,1%49,2%35,6
½48,8%53,5%55,2%52,5%25,9
1 (soma plena)40,2%62,8%50,0%-13,4

A soma plena (peso 1) exagera: o agente fica tão curto (13,4 chamadas por tarefa, contra 49,2 do modelo base) que o harness Pi volta ao nível do modelo base, mesmo com Hermes disparando para 62,8%. O peso ½ deu o melhor equilíbrio entre os três harnesses ao mesmo tempo, e foi o escolhido para o "super-adaptador" final, construído a partir dos checkpoints de cada harness (Pi no passo 160, Hermes no passo 160, OpenCode no passo 150).

O que isso substitui, e quando não compensa

Esta técnica não compete com fine-tuning completo, compete com ele pelo custo. Retreinar um modelo de 27 bilhões de parâmetros por inteiro exige memória e tempo de GPU muito maiores do que treinar um LoRA que soma uma fração dos parâmetros originais. O trade-off é que o resultado é específico: o adaptador aprendeu o harness e a distribuição de tarefas que você usou para treiná-lo, não qualquer tarefa.

Vale a pena considerar harness adapters quando:

  1. Você já roda um agente em produção, com um harness fixo (Pi, OpenCode, Hermes Agent ou outro compatível com Harbor), e o volume de chamadas justifica economizar tokens por tarefa.
  2. Você tem (ou consegue gerar, como com Tasksmith) uma distribuição de tarefas real do seu domínio, com um verificador confiável de certo ou errado.
  3. Você tem acesso a GPUs como as B200 usadas no experimento (via Hugging Face Jobs ou infraestrutura própria), porque o treino de RL com rollouts de agente real não é leve.

Não vale a pena se o harness muda com frequência (cada troca de versão do Pi, OpenCode ou Hermes Agent pode exigir re-treino), se as tarefas do seu uso real são muito variadas para caber numa distribuição coerente, ou se o volume de chamadas é baixo o suficiente para a economia de tokens não pagar o custo de GPU do treino.

Para reproduzir

A equipe publicou o dataset (harness-hub/agentic-coding-envs), os três adaptadores LoRA, o super-adaptador, versões GGUF para rodar localmente e o plugin de segurança harness-hub/qwen-safeagents-plugin (que bloqueia chamadas de ferramenta fora do esperado durante o treino, usando a biblioteca safeagents) numa coleção aberta no Hugging Face. O comando openenv validate funciona em qualquer tarefa no formato Harbor, então o primeiro passo de replicar o pipeline, antes de gastar GPU em treino, é rodar a validação na sua própria distribuição de tarefas e ver quantas sobrevivem.

Fonte: Hugging Face Blog

Compartilhar
Quem escreveuLucas FerrazColunista

Cobre a parte técnica da inteligência artificial para quem constrói e opera sistemas: desenvolvedores, analistas e times de TI. Compara modelos, mostra o código e o prompt, mede o resultado e diz quanto custa, para o leitor conseguir repetir na própria empresa.

Leia também

Newsletter AI Brasil

A IA da semana, para a sua profissão

Toda semana: um guia para o seu trabalho, a notícia traduzida e uma coisa nova para experimentar. Gratuita, sem spam.

Você é… (opcional)