O que é um harness de agente?

O que é um harness de agente

Um harness de agente é o programa que executa em torno de um modelo de linguagem e o transforma num agente. Mantém o ciclo que continua a chamar o modelo, as definições das ferramentas que o modelo pode chamar, as regras de permissões que determinam quais dessas chamadas são realmente executadas, o estado da sessão que persiste entre interações e o diretório de trabalho onde as operações decorrem. O modelo pode ser substituído dentro dele.

A última frase é a mais importante. Um modelo, por si só, responde a uma pergunta e esquece-se de si. Um harness pergunta ao modelo o que fazer a seguir, executa o comando solicitado pelo modelo, devolve o resultado e pergunta novamente. É essa repetição que as pessoas querem dizer quando usam o termo "agente". Se a terminologia envolvente ainda não estiver clara, a diferença entre um agente de IA, um LLM e um assistente esclarece os termos antes de escolher uma ferramenta.

O harness não é o modelo

Os dois são confundidos porque os fornecedores os distribuem sob uma única marca.

dsh e DeepSeek são produtos diferentes. O DeepSeek Harness, publicado em github.com/deepseek-ai/deepseek-harness em 13 August 2026 sob a licença MIT, é um programa Node que se instala numa máquina. Os modelos DeepSeek são pesos disponibilizados por uma API (interface de programação de aplicações). Aponte dsh para um modelo de outro fornecedor e ele continuará a funcionar, porque o harness só precisa de algo que aceite mensagens e devolva chamadas de ferramentas.

Claude Code e Claude formam o mesmo par. Claude Code é um harness: um programa de terminal com um loop, um sistema de permissões e ferramentas para ficheiros e shell. Claude é a família de modelos que ele chama por predefinição. Codex e Gemini CLI fazem a mesma separação.

Este é o teste que resolve a questão sempre. Instale um harness. Chame um modelo. Se o componente tiver uma versão no disco e um ficheiro de configuração no seu diretório pessoal, é um harness. Se for uma cadeia dentro desse ficheiro de configuração, algo como deepseek-chat, é o modelo.

O que o loop realmente faz

Uma iteração de um loop de harness funciona assim. Leia esta sequência com atenção, porque quase todas as diferenças entre harnesses estão dentro destes cinco passos.

1. O harness envia ao modelo a conversa até ao momento, juntamente com uma lista de definições de ferramentas.
2. O modelo responde com texto ou com um pedido para chamar uma dessas ferramentas.
3. O harness verifica esse pedido de acordo com as suas regras de permissões e executa-o ou para para lhe pedir confirmação.
4. O harness executa a ferramenta, captura o resultado e o código de saída e trunca o resultado se for muito longo.
5. O harness acrescenta esse resultado à conversa e regressa ao passo 1.

O passo 3 é onde os harnesses mais diferem na utilização diária. Um harness que pede confirmação antes de cada comando é seguro, mas cansativo. Um harness que nunca pede confirmação acabará por executar um comando destrutivo num caminho que o modelo interpretou incorretamente. Atualmente, todos os harnesses sérios têm uma opção intermédia: uma allowlist de comandos que são executados sem confirmação e um pedido de confirmação para tudo o resto.

O passo 1 é onde está a maior parte das restantes diferenças. O harness também escreve o system prompt que acompanha cada um desses pedidos. O Claude Code disponibiliza-lhe diretamente esse controlo, porque um estilo de saída edita o system prompt que envia e, por isso, altera todas as respostas recebidas. A conversa cresce a cada iteração e um modelo tem uma janela de contexto fixa. Por isso, o harness tem de decidir o que descartar, o que resumir e o que escrever num ficheiro para ler mais tarde. Essa decisão explica grande parte da razão por que dois harnesses que utilizam o mesmo modelo produzem trabalho com qualidades diferentes. Se estes cinco passos ainda parecem abstratos, a solução é escrever uma versão simples do loop, que é exatamente o que um percurso faseado para aprender agentes de IA o leva a construir logo no início.

Atualmente, a maioria dos harnesses liga ferramentas externas através de MCP (model context protocol), uma forma padrão de disponibilizar uma ferramenta a qualquer harness compatível, permitindo que uma integração seja utilizada por vários harnesses. Executar servidores MCP num VPS aborda esse lado. A pesquisa na Web costuma ser a primeira ferramenta que as pessoas adicionam. Apontar o agente para a sua própria instância SearXNG mantém as consultas fora de serviços de terceiros e deixa claro que todas as páginas que o agente lê em seguida são entradas não confiáveis recebidas dentro do loop.

Harness de agente vs framework de agente

Esta pergunta surge sempre que aparece um novo harness, e as respostas divergem, em parte porque os fornecedores também divergem. Esta é a versão que se mantém válida.

Um framework é uma biblioteca que importa. Você escreve o loop, decide quando chamar o modelo e trata os resultados das ferramentas por conta própria. LangChain é o exemplo mais conhecido: você recebe blocos de construção e monta o agente no código.

Um harness é um programa que executa. O loop já está escrito, as ferramentas já existem e o modelo de permissões já tem uma configuração predefinida. Você obtém um agente funcional no primeiro comando e configura-o a partir daí.

O teste de instalação normalmente resolve a questão. Se instala o software e depois escreve código, é um framework. Se instala o software e depois interage com ele, é um harness.

A fronteira é realmente discutida, e a evidência mais clara está na própria documentação do LangChain. Em August 2026, ela descreve Deep Agents como um framework "opinionated, batteries-included" criado sobre LangGraph, enquanto o repositório langchain-ai/deepagents se denomina "the batteries-included agent harness". As duas descrições são válidas. Deep Agents é um Python SDK (software development kit) que você importa, portanto o teste de instalação classifica-o como uma biblioteca, e inclui comportamento predefinido suficiente para que as pessoas o utilizem como um harness. A Microsoft disponibilizou um harness e agentes alojados para disponibilidade geral em August 2026, mostrando que a palavra agora designa uma categoria de produto, e não apenas jargão.

Por isso, faça antes a pergunta que melhor prevê a sua carga de trabalho. Se você escreve o loop, fica responsável pelo loop: pelas novas tentativas, pela redução do contexto, pelos pedidos de permissão e pelo registo do que aconteceu. Se o loop já vem incluído, você herda a resposta de outra pessoa para todos esses pontos. Isso torna o início muito mais rápido, mas dificulta alterações posteriores.

Como um harness difere de uma janela de chat

Uma janela de chat e um harness mostram o resultado produzido pelo modelo. A diferença está em qual computador o trabalho é executado. Numa janela de chat, qualquer código executado pelo modelo corre dentro do sandbox do fornecedor, sobre os ficheiros que carregou, e desaparece quando a sessão termina. Um harness executa ferramentas na máquina onde o iniciou, com o utilizador que o iniciou, sobre os seus ficheiros reais e com as suas credenciais reais disponíveis no ambiente.

Esse é o benefício completo e o risco completo, em duas frases. O agente pode finalmente executar o trabalho. O agente também pode apagar esse trabalho.

Os harnesses que as pessoas estão realmente a executar

Esta lista é datada de 19 August 2026 de propósito. A categoria muda semanalmente e qualquer compilação fica rapidamente desatualizada.

• Claude Code e Codex são harnesses dos fornecedores. Funcionam primeiro no terminal, estão associados por predefinição aos modelos do próprio fornecedor e têm a gestão de permissões mais aperfeiçoada. Comparação entre Claude Code, Cursor, Codex e Copilot analisa-os em detalhe.
• DeepSeek Harness (dsh) tem licença MIT e baseia-se numa única ideia: tudo é um plugin. Os modelos, as ferramentas, as sessões, as sandboxes e a interface de utilizador são componentes substituíveis. Cada plugin instalado é executado com as próprias permissões do agente. Por isso, verificar a que recursos um plugin dsh pode aceder antes de o adicionar é mais importante aqui do que num harness com um conjunto de ferramentas fixo. Tinha aproximadamente 166,800 estrelas no GitHub em 19 August 2026, seis dias depois de ser publicado.
• Hermes, da Nous Research, é um agente autónomo de uso geral, não uma ferramenta de programação. Foi lançado com licença MIT em February 2026 e guarda as memórias e competências numa base de dados SQLite local na própria máquina. Alojamento próprio do Hermes numa VPS explica o processo.
• Omnigent é um meta-harness: controla outros harnesses, incluindo Claude Code e Codex, através de uma API única, com sessões partilhadas, limites de despesa e uma sandbox ao nível do sistema operativo. Omnigent como harness multiagente explica as vantagens.
• OneCLI é um harness com sandbox dirigido a equipas. Baseia-se num gateway que injeta credenciais reais nos pedidos de saída, para que o próprio agente veja apenas chaves de substituição.

Três deles aparecem tantas vezes na mesma lista final que vale a pena ler DeepSeek Harness, Claude Code e Omnigent lado a lado para comparar o acoplamento ao modelo, a licença, a maturidade e o que cada um exige para ser executado num servidor.

O arranque rápido do dsh é um único comando. Executá-lo uma vez é a forma mais rápida de perceber o que é um harness. É necessário ter Node.js instalado na máquina.

npx @deepseek-ai/dsh web

Isto inicia a interface web (user interface) em http://127.0.0.1:3080. Leia o README antes de depender dele, porque o dsh identifica-se como uma versão preliminar para programadores e afirma claramente que haverá alterações incompatíveis. Se o primeiro comando falhar imediatamente ou obtiver uma build diferente da esperada, fixar uma versão exata do dsh e limpar a cache do npx costuma resolver o problema. Executar o DeepSeek Harness numa VPS explica a instalação no servidor, e por que razão esse endereço começa por 127.0.0.1 explica a predefinição de loopback.

Os routers ficam acima do harness

Um router de modelos é um proxy local entre o harness e a API do provider. O Claude Code Router é o exemplo mais comum: por padrão, faz bind em 127.0.0.1:3456, aceita os pedidos que o Claude Code teria enviado para o seu próprio fornecedor e encaminha-os para o provider configurado. O harness não sabe que algo mudou.

Os routers existem porque o modelo pode ser substituído, por isso são uma boa demonstração do ponto principal deste artigo. Também concentram riscos, porque o proxy vê todos os prompts e armazena todas as chaves dos providers. Trate-o como infraestrutura, não como uma conveniência. Onde um harness mantém as suas chaves de API e definições de modelos é o mesmo problema, uma camada abaixo.

O que muda quando o harness é executado numa VPS

Quatro coisas mudam quando o harness sai do seu portátil e passa a ser executado num servidor que arrendou.

Continua a ser executado quando fecha a tampa. Uma tarefa longa sobrevive à deslocação e à bateria. Inicie-a dentro de tmux e desligue-se dela:

tmux new -s agent
# start the harness, then press Ctrl-b and then d to detach
tmux attach -t agent

Para tudo o que deve voltar a ser executado depois de um reboot, um serviço de utilizador é melhor do que uma sessão de terminal:

loginctl enable-linger $USER
systemctl --user status my-agent.service

loginctl enable-linger é a parte que muitas pessoas esquecem. Sem ele, o systemd interrompe os serviços do seu utilizador assim que a última sessão SSH (secure shell) é fechada. Por isso, o agente termina quando sai da sessão e não apresenta qualquer erro. Executar o dsh sem interface sob o systemd contém o ficheiro da unidade. Depois de uma sessão estar a ser executada nesse servidor, uma segunda sessão não acrescenta qualquer custo, e duas sessões do Claude Code na mesma máquina podem trocar mensagens, pelo que a sessão iniciada de manhã pode entregar uma tarefa à outra sem que tenha de retransmitir tudo manualmente.

Guarda as suas chaves. A chave do fornecedor passa a estar num ficheiro de configuração nesse servidor. Verifique quem pode lê-la:

ls -l ~/.config

Qualquer processo executado como o seu utilizador pode ler esse ficheiro. Isso inclui o agente e tudo o que o agente decidir executar.

Pode aceder às suas outras máquinas. Uma VPS na mesma rede privada que as outras máquinas dá ao agente uma rota até elas. Esse é precisamente o objetivo, mas também define o raio de impacto.

Pode ser acedida a partir de qualquer lugar. A maioria dos harnesses expõe uma interface web, e a maioria associa-a a loopback por uma razão. Verifique a sua:

ss -tlnp | grep 3080

127.0.0.1:3080 significa que apenas o próprio servidor pode estabelecer ligação. 0.0.0.0:3080 significa que qualquer pessoa que descubra o endereço pode fazê-lo. Aceda a uma interface loopback através de um túnel SSH, em vez de alterar o endereço de associação:

ssh -N -L 3080:127.0.0.1:3080 you@your-server

Depois, abra http://127.0.0.1:3080 no browser do portátil. O tráfego passa dentro da sessão SSH, pelo que nada de novo fica exposto à internet.

Todas essas propriedades também constituem argumentos de segurança

Leia novamente as quatro propriedades da perspetiva de um atacante.

O agente é executado sem supervisão, por isso ninguém observa o momento em que o modelo interpreta incorretamente um caminho. O agente tem acesso às suas chaves, por isso um único ficheiro de configuração legível dá acesso a toda a sua conta no fornecedor. O agente consegue alcançar as suas outras máquinas, por isso uma injeção de prompt, ou seja, instruções ocultas numa página Web ou num ficheiro lido pelo agente, passa a ter um caminho para o seu servidor de base de dados. O agente está acessível a partir de qualquer lugar, por isso uma interface Web ligada a 0.0.0.0 sem palavra-passe equivale a uma shell na Internet pública.

A correção é simples em cada caso e é sempre a mesma. Dê ao agente a sua própria conta de utilizador sem privilégios, em vez da sua:

sudo adduser --disabled-password --gecos "" agent

Mantenha a interface Web em loopback e aceda-lhe através de SSH. Dê ao agente as credenciais mais restritas que ainda lhe permitam concluir o trabalho. O artigo manter segredos fora dos agentes de IA explica este tema corretamente. Para qualquer processo executado sem supervisão, uma máquina descartável é melhor do que uma máquina cuidadosamente configurada: executar agentes de programação numa VM descartável e executar o Claude Code com segurança num VPS seguem ambos essa abordagem.

Você precisa de um harness de agente?

Se o seu trabalho consiste em uma pergunta de cada vez, uma janela de chat é suficiente, e um harness apenas acrescenta um loop que você precisa supervisionar. Um harness começa a compensar quando uma tarefa exige várias etapas em ficheiros reais ou quando precisa de continuar a funcionar enquanto você dorme.

A maior parte desta categoria é recente. dsh indica developer preview no seu próprio README em agosto de 2026, e os restantes avançam com rapidez suficiente para que um ficheiro de configuração criado hoje possa precisar de edição no próximo mês. Isso é motivo para manter a configuração pequena e reproduzível e para registar o que foi alterado. A mesma contenção ajuda dentro do loop, onde uma skill que orienta o agente para fazer a menor alteração que funcione deixa um diff que você consegue realmente ler no fim de uma execução sem supervisão. Comece com um harness num servidor, atribua-lhe uma tarefa e uma key restrita e amplie o acesso apenas depois de essa primeira tarefa ter decorrido sem incidentes durante uma semana. Os agentes self-hosted que vale a pena executar atualmente são um ponto de partida razoável para escolher o primeiro.

FAQ

O que é um agent harness em termos simples?

É o programa que envolve o modelo. O modelo produz texto e pedidos para utilizar ferramentas. O harness executa o ciclo que continua a fazer pedidos, executa as ferramentas solicitadas pelo modelo, aplica as regras sobre as ferramentas que podem ser executadas sem autorização e mantém o estado da sessão e os ficheiros entre interações. Se trocar o modelo e o harness continuar a funcionar, essa é a indicação mais clara de que são componentes separados.

O Claude Code é um modelo ou um harness?

O Claude Code é um harness. É um programa de terminal com um ciclo, um sistema de permissões e ferramentas integradas para ficheiros e shell. Claude é a família de modelos que utiliza por predefinição. A mesma separação aplica-se ao DeepSeek Harness (dsh), que é um programa Node que instala, e aos modelos DeepSeek, que são disponibilizados através de uma API. Instala um harness numa máquina. Chama um modelo através da rede.

Qual é a diferença entre um agent harness e um agent framework?

Um framework é uma biblioteca que importa e utiliza no código, pelo que fica responsável pelo ciclo, pelas novas tentativas e pelo tratamento do contexto. Um harness é um programa que executa, pelo que tudo isso já vem com predefinições que configura em vez de implementar. Na prática, a distinção não é rígida: Deep Agents, da LangChain, é um SDK que pode ser importado e cujo próprio repositório designa como um agent harness completo, em agosto de 2026. Pergunte se terá de implementar o ciclo. Essa resposta determina qual dos termos se aplica à sua situação.

Preciso de um VPS para executar um agent harness?

Não. Todos os harnesses mencionados aqui são executados num portátil. Um servidor altera quatro aspetos: o agente continua a executar quando fecha a tampa, mantém as suas chaves numa máquina que está sempre ligada, pode aceder aos seus outros servidores e permite retomar a mesma sessão a partir de qualquer dispositivo. Cada um desses aspetos também envolve considerações de segurança, por isso atribua ao agente a sua própria conta de utilizador e mantenha qualquer interface Web limitada a 127.0.0.1.

Posso utilizar um modelo diferente dentro do mesmo harness?

Normalmente, sim. Essa é a propriedade que define um harness. A maioria aceita um nome de modelo e um URL base na configuração, pelo que apontá-lo para outro fornecedor exige uma alteração, não uma reescrita. Quando um harness não permite essa alteração diretamente, um router local como o Claude Code Router pode ficar entre o harness e o fornecedor e traduzir os pedidos, ficando associado a 127.0.0.1:3456 por predefinição. Tenha cuidado com esse proxy, porque vê todos os prompts e mantém todas as chaves.