O que é um agent harness e como ele funciona

O que é um agent harness

Um agent harness é 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 efetivamente executadas, o estado da sessão que persiste entre interações e o diretório de trabalho onde as operações são realizadas. O modelo pode ser substituído dentro desse programa.

A última frase é a que deve ser retida. Um modelo isolado 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 o mesmo nome de marca.

dsh e DeepSeek são produtos diferentes. O DeepSeek Harness, publicado em github.com/deepseek-ai/deepseek-harness em 13 de agosto de 2026 sob a licença MIT, é um programa Node que você 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á funcionando, porque o harness só precisa de algo que aceite mensagens e retorne chamadas de ferramentas.

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

Este é o teste que resolve a questão todas as vezes. Você instala um harness. Você chama um modelo. Se o componente tem uma versão no disco e um arquivo de configuração no seu diretório pessoal, ele é um harness. Se é uma string dentro desse arquivo de configuração, algo como deepseek-chat, é o modelo.

O que o loop realmente faz

Uma execução do loop de um harness funciona assim. Leia 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 solicita uma chamada a uma dessas ferramentas.
3. O harness verifica essa solicitação de acordo com as suas regras de permissões e executa-a ou para para lhe pedir confirmação.
4. O harness executa a ferramenta, recolhe 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 no uso diário. 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 relevantes têm uma configuração intermédia: uma allowlist de comandos que são executados sem confirmação e um prompt para todos os restantes.

O passo 1 é onde está a maior parte das outras diferenças. A conversa cresce a cada execução e o 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 a maior parte do motivo por que dois harnesses que usam o mesmo modelo produzem trabalhos com qualidades diferentes.

Atualmente, a maioria dos harnesses liga ferramentas externas através de MCP (model context protocol), uma forma padrão de expor uma ferramenta a qualquer harness compatível, permitindo que uma integração seja usada por vários harnesses. Executar servidores MCP numa VPS aborda esse aspeto.

Harness de agentes vs framework de agentes

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

Um framework é uma biblioteca que importa. Escreve o loop, decide quando chamar o modelo e trata dos resultados das ferramentas. LangChain é o exemplo mais conhecido: 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. 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 a ferramenta e depois escreve código, é um framework. Se instala a ferramenta e depois fala com ela, é um harness.

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

Em vez disso, faça a pergunta que melhor prevê a sua carga de trabalho. Se escreve o loop, fica responsável por ele: 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, herda as respostas de outra pessoa para todos esses problemas. Isso permite começar muito mais depressa, mas torna as alterações mais difíceis posteriormente.

Como um harness difere de uma janela de chat

Uma janela de chat e um harness mostram a saída do modelo. A diferença está no computador onde o trabalho é executado. Numa janela de chat, qualquer código executado pelo modelo é executado 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.

Estas duas frases resumem toda a vantagem e todo o risco. O agente pode finalmente executar o trabalho. O agente também pode apagar esse trabalho.

Os harnesses que as pessoas estão realmente a utilizar

Esta lista está 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 do fornecedor. 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 refinada. Comparação entre Claude Code, Cursor, Codex e Copilot analisa-os em detalhe.
• DeepSeek Harness (dsh) é disponibilizado sob a licença MIT e baseia-se numa ideia central: tudo é um plugin. Assim, modelos, ferramentas, sessões, sandboxes e a interface de utilizador são componentes substituíveis. 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 sob a licença MIT em February 2026 e mantém as memórias e competências numa base de dados SQLite local na sua 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 única API com sessões partilhadas, limites de gastos e uma sandbox ao nível do sistema operativo. Omnigent como harness multiagente explica as vantagens.
• OneCLI é um harness isolado numa sandbox, destinado 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.

O início rápido de dsh consiste num ú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 dela, porque dsh se identifica como uma versão de pré-visualização para programadores e afirma claramente que haverá alterações incompatíveis. Executar o DeepSeek Harness numa VPS explica a instalação no servidor, e por que esse endereço começa por 127.0.0.1 explica o valor predefinido do loopback.

Os routers ficam acima do harness

Um router de modelos é um proxy local entre o harness e a API do fornecedor. O Claude Code Router é o exemplo mais comum: fica associado a 127.0.0.1:3456 por predefinição, aceita os pedidos que o Claude Code teria enviado para o seu próprio fornecedor e encaminha-os para o fornecedor que configurou. O harness não sabe que alguma coisa mudou.

Os routers existem porque o modelo pode ser substituído. Por isso, são uma boa demonstração do ponto principal deste texto. Também concentram riscos, porque o proxy vê todos os prompts e guarda todas as chaves dos fornecedores. Trate-o como infraestrutura, não como uma conveniência. Onde um harness guarda as chaves da API e as definições do modelo é o mesmo problema numa camada inferior.

O que muda quando o harness é executado numa VPS

Quatro coisas mudam quando o harness sai do seu portátil e passa para um servidor alugado.

Continua a ser executado quando fecha a tampa. Uma tarefa longa sobrevive à viagem e à bateria. Inicie-a dentro de tmux e desassocie-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 isso, o systemd para os serviços do seu utilizador assim que a última sessão SSH (secure shell) é fechada. Por isso, o agente termina quando termina sessão e nada apresenta um erro. Executar o dsh sem interface sob o systemd contém o ficheiro da unidade. Depois de uma sessão estar em execução nesse servidor, uma segunda não lhe custa nada adicional. Além disso, duas sessões do Claude Code no mesmo servidor podem enviar mensagens entre si, pelo que a sessão iniciada de manhã pode entregar uma tarefa à outra sem que tenha de a retransmitir 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 com 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 os seus outros servidores dá ao agente uma rota até eles. Esse é precisamente o objetivo, mas também define o raio de impacto.

Pode ser acedido a partir de qualquer lugar. A maioria dos harnesses expõe uma interface web e, normalmente, associa-a à interface de 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 ligar-se. 0.0.0.0:3080 significa que qualquer pessoa que encontre o endereço pode ligar-se. Aceda a uma interface de 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 seu portátil. O tráfego passa dentro da sessão SSH, pelo que nada de novo fica exposto à internet.

Cada uma dessas propriedades também é um argumento de segurança

Leia novamente as quatro propriedades como um atacante as leria.

O agente funciona sem supervisão, portanto ninguém observa o momento em que o modelo interpreta incorretamente um caminho. Ele guarda as suas chaves, portanto um único ficheiro de configuração legível dá acesso a toda a sua conta no fornecedor. Ele consegue chegar às suas outras máquinas, portanto 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 até ao seu servidor de base de dados. Ele está acessível a partir de qualquer lugar, portanto 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 todos os casos e é sempre a mesma. Dê ao agente a sua própria conta de utilizador sem privilégios, em vez de usar a 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 ponto corretamente. Para qualquer tarefa executada 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 numa pergunta de cada vez, uma janela de chat é suficiente, e um harness apenas acrescenta um loop que terá de supervisionar. Um harness começa a compensar quando uma tarefa exige muitas etapas sobre ficheiros reais ou quando tem de continuar a trabalhar enquanto você dorme.

A maior parte desta categoria ainda é recente. O dsh indica “developer preview” no próprio README em agosto de 2026, e os restantes avançam com rapidez suficiente para que um ficheiro de configuração escrito hoje possa precisar de edição no próximo mês. Isso é uma razão para manter a configuração pequena e reproduzível e para registar as alterações feitas. A mesma contenção é útil dentro do loop, onde uma skill que orienta o agente para a menor alteração que funciona deixa um diff que você consegue realmente ler no fim de uma execução não supervisionada. Comece com um harness num servidor, atribua-lhe uma tarefa e uma chave restrita e só amplie o acesso depois de essa primeira tarefa ter decorrido sem incidentes durante uma semana. Os agentes self-hosted que vale a pena executar hoje 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 quais ferramentas podem ser executadas sem permissão e mantém o estado da sessão e os ficheiros entre interações. Se trocar o modelo, o harness continua a funcionar. Esse é o sinal mais claro 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 de execução, 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 contra a qual escreve código. Por isso, fica responsável pelo ciclo, pelas novas tentativas e pelo tratamento do contexto. Um harness é um programa que executa. Todos esses componentes já vêm com valores predefinidos que configura em vez de implementar. Na prática, a distinção não é nítida: o Deep Agents da LangChain é um SDK que pode ser importado e cujo próprio repositório descreve como um agent harness completo, em agosto de 2026. Pergunte se vai escrever o ciclo por si próprio. Essa resposta determina qual dos termos se aplica à sua situação.

Preciso de um VPS para executar um agent harness?

Não. Todos os harness aqui mencionados executam 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 vinculada 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. Assim, apontá-lo para outro fornecedor é uma alteração de configuração, não uma reescrita. Quando um harness não permite essa alteração diretamente, um router local como o Claude Code Router fica entre o harness e o fornecedor e traduz os pedidos, vinculando-se a 127.0.0.1:3456 por predefinição. Tenha cuidado com esse proxy, porque ele vê todos os prompts e mantém todas as chaves.