SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor

O que é um harness de agente?

Entenda o programa que envolve o modelo: loop de execução, ferramentas, permissões, estado da sessão e diretório de trabalho, e como ele difere de frameworks.

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 distribuem-nos com 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 August 2026 sob a licença MIT, é um programa Node que instala numa máquina. Os modelos DeepSeek são pesos disponibilizados através de uma API (application programming interface). 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 são o mesmo par. Claude Code é um harness: um programa de terminal com um ciclo de execução, 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 seguem a mesma separação.

Este é o teste que resolve a questão todas as vezes. Instala-se um harness. Chama-se um modelo. Se o componente tiver uma versão no disco e um ficheiro de configuração no diretório pessoal, é um harness. Se for uma cadeia dentro desse ficheiro de configuração, como deepseek-flash, é o modelo.

O que o loop do orquestrador faz na prática

Uma execução de um loop do orquestrador funciona assim. Leia com atenção, porque quase todas as diferenças entre orquestradores estão dentro destes cinco passos.

  1. O orquestrador 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 a execução de uma dessas ferramentas.
  3. O orquestrador 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 orquestrador executa a ferramenta, captura o resultado e o código de saída e trunca o resultado se for muito extenso.
  5. O orquestrador acrescenta esse resultado à conversa e volta ao passo 1.

O passo 3 é onde os orquestradores mais diferem no uso diário. Um orquestrador que pede confirmação antes de cada comando é seguro e cansativo. Um orquestrador que nunca pede confirmação acabará por executar um comando destrutivo num caminho que o modelo interpretou incorretamente. O Claude Code suporta uma configuração intermédia: uma lista de permissões de comandos que são executados sem confirmação e um pedido de confirmação para os restantes comandos.

O passo 1 é onde reside o resto da diferença. O orquestrador também escreve o prompt de sistema que acompanha cada uma dessas solicitações, e o Claude Code dá-lhe acesso direto a esse controlo, porque um estilo de saída altera o prompt de sistema que envia e, por isso, altera todas as respostas devolvidas. A conversa cresce a cada execução e um modelo tem uma janela de contexto fixa. Por isso, o orquestrador tem de decidir o que descartar, o que resumir e o que escrever num ficheiro para ler mais tarde. Essa decisão explica em grande parte por que razão dois orquestradores que utilizam o mesmo modelo produzem trabalhos com qualidades diferentes. Se estes cinco passos ainda parecerem abstratos, a solução é escrever uma versão simples do loop uma vez. É exatamente isso que um percurso faseado para aprender agentes de IA lhe pede para construir logo no início.

A maioria dos orquestradores liga atualmente ferramentas externas através de MCP (protocolo de contexto do modelo), uma forma standard de disponibilizar uma ferramenta a qualquer orquestrador compatível, permitindo que uma integração seja usada por vários orquestradores. Executar servidores MCP num VPS aborda esse aspeto. A pesquisa na Web costuma ser a primeira ferramenta que as pessoas adicionam, e apontar o agente para a sua própria instância SearXNG mantém as consultas fora de terceiros e deixa claro que todas as páginas que o agente lê depois são entradas não confiáveis recebidas dentro do loop.

Harness de agente versus framework de agente

Esta pergunta surge sempre que chega um novo harness, e as respostas divergem, em parte porque os fornecedores também divergem. Esta é a versão que se sustenta.

Um framework é uma biblioteca que você importa. Você monta o agente no código, usando o loop do framework ou escrevendo o seu próprio. LangChain é o exemplo conhecido: você recebe blocos de construção e monta o agente no código.

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

O teste de instalação normalmente decide. Se você instala e depois escreve código, é um framework. Se você instala e depois conversa com ele, é um harness.

A fronteira é realmente contestada, e a evidência mais clara está na própria documentação do LangChain. Em outubro de 2026, ela chama Deep Agents de "an agent harness" e também de "a standalone library built on top of LangChain's core building blocks for agents", enquanto o repositório langchain-ai/deepagents se autodenomina "the batteries-included agent harness". As duas descrições são válidas. Deep Agents é um Python SDK (kit de desenvolvimento de software) que você importa, portanto o teste de instalação o classifica como uma biblioteca, e ele fornece comportamento padrão suficiente para que as pessoas o usem como um harness. A Microsoft anunciou a disponibilidade geral de Hosted Agents no Foundry Agent Service em 9 July 2026, e a publicação de 22 July 2026 anuncia o lançamento do Microsoft Agent Framework Harness, mostrando que o termo agora é uma categoria de produto, e não apenas jargão.

Portanto, faça a pergunta que prevê melhor a sua carga de trabalho. Se você escreve o loop, você é responsável por ele: pelas tentativas, pela redução do contexto, pelos prompts de permissão e pelo registro do que aconteceu. Se o loop já vem pronto, você herda a resposta de outra pessoa para todos esses pontos, o que torna o início muito mais rápido e as alterações posteriores mais difíceis.

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á em qual computador o trabalho é executado. Em uma janela de chat, qualquer código executado pelo modelo roda dentro do sandbox do fornecedor, usando os arquivos que você enviou. Um harness executa ferramentas na máquina em que você o iniciou, como o usuário que o iniciou, usando seus arquivos reais e as credenciais reais disponíveis no ambiente.

Essa é toda a vantagem e todo o risco, em duas frases. O agente finalmente pode realizar o trabalho. O agente também pode excluir o trabalho.

As ferramentas que as pessoas realmente estão executando

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

  • Claude Code e Codex são ferramentas dos fornecedores. São focadas primeiro no terminal, vinculadas por padrão aos modelos do próprio fornecedor e têm o tratamento de permissões mais bem desenvolvido. Comparação entre Claude Code, Cursor, Codex e Copilot analisa essas ferramentas em detalhe.
  • DeepSeek Harness (dsh) é licenciado sob a licença MIT e baseia-se em uma ideia: tudo é um plugin. Modelos, ferramentas, sessões, sandboxes e a interface de usuário são componentes substituíveis. Cada plugin instalado é executado com as próprias permissões do agente. Por isso, verificar o que um plugin dsh pode acessar antes de adicioná-lo é mais importante aqui do que em uma ferramenta com um conjunto fixo de ferramentas.
  • Hermes, da Nous Research, é um agente autônomo geral, e não uma ferramenta de programação. Foi lançado sob a licença MIT em February 2026, e o armazenamento integrado é local: as memórias e habilidades ficam como arquivos em ~/.hermes, e o histórico das sessões fica em um banco de dados SQLite local. Isso deixa de ser toda a realidade quando você ativa um dos provedores externos opcionais de memória, como Mem0 ou Hindsight. Em October 2026, a documentação do Hermes informa que um provedor ativo recebe cada turno da conversa depois de cada resposta e uma cópia de cada gravação de memória integrada. Portanto, seus dados também passam a ficar armazenados com esse provedor. Comparação entre Hindsight e Mem0 vale a leitura antes de ativar um deles, e Hospedar o Hermes em um VPS explica o restante.
  • Omnigent é uma meta-ferramenta: executa outras ferramentas, incluindo Claude Code e Codex, por meio de uma única API, com sessões compartilhadas, limites de gastos e um sandbox no nível do sistema operacional. Omnigent como ferramenta multiagente explica o que isso oferece.
  • OneCLI é uma ferramenta em sandbox voltada para equipes. Ela usa um gateway que injeta credenciais nas requisições de saída do agente. Assim, o agente nunca vê as chaves reais.

Três dessas ferramentas aparecem com frequência suficiente na mesma lista de opções para que valha a pena ler DeepSeek Harness, Claude Code e Omnigent lado a lado sobre acoplamento ao modelo, licença, maturidade e os requisitos para executar cada uma em um servidor.

O início rápido do dsh consiste em um único comando. Executá-lo uma vez é a forma mais rápida de entender o que é uma ferramenta desse tipo. Node.js precisa estar instalado na máquina.

npx @deepseek-ai/dsh web

Isso inicia a interface web em http://127.0.0.1:3080. Leia o README antes de depender dela, porque dsh se descreve como uma versão de prévia para desenvolvedores e informa claramente que haverá mudanças incompatíveis. Se o primeiro comando falhar imediatamente ou baixar uma compilação inesperada, fixar uma versão exata do dsh e limpar o cache do npx normalmente permite continuar. Executar o DeepSeek Harness em um VPS explica a instalação no servidor, e por que esse endereço começa com 127.0.0.1 explica o padrã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 em um VPS

Quatro coisas mudam quando o harness sai do seu laptop e passa a ser executado em um servidor que você aluga.

Ele continua em execução quando você fecha a tampa. Uma tarefa longa sobrevive ao seu deslocamento e à bateria. Inicie-a dentro de tmux e desconecte-se dela:

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

Para qualquer tarefa que precise voltar depois de um reboot, um serviço de usuário é melhor 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 padrão do systemd é parar o gestor de serviços do usuário 10 segundos depois do encerramento da última sessão. Portanto, um serviço de usuário não mantém o agente em execução depois do logout. Executar dsh sem interface no systemd contém o arquivo da unidade. Quando uma sessão já estiver em execução nesse servidor, você poderá iniciar uma segunda sessão. Duas sessões do Claude Code na mesma máquina podem enviar mensagens entre si, então a sessão iniciada pela manhã pode encaminhar uma tarefa para a outra sem que você precise retransmiti-la manualmente.

Ele armazena suas chaves. A chave do provedor agora fica em um arquivo de configuração nesse servidor. Verifique quem pode lê-lo:

ls -l ~/.config

Qualquer processo executado com o seu usuário pode ler esse arquivo. Isso inclui o agente e tudo o que ele decidir executar.

Ele pode alcançar suas outras máquinas. Um VPS na mesma rede privada que os seus outros servidores fornece ao agente uma rota até eles. Esse é exatamente o objetivo, mas também define o raio de impacto.

Ele pode ser acessado de onde você estiver. A maioria dos harnesses expõe uma interface web, e a maioria a associa ao loopback por um motivo. Verifique a sua:

ss -tlnp | grep 3080

127.0.0.1:3080 significa que somente o próprio servidor pode se conectar. 0.0.0.0:3080 significa que a interface escuta em todas as interfaces. Assim, qualquer pessoa que consiga alcançar o endereço público do servidor pode se conectar, a menos que um firewall à frente dele bloqueie a porta. Em outubro de 2026, dsh rejeita um endereço curinga desse tipo durante a inicialização, mas muitas outras interfaces web aceitam esse endereço. Acesse uma interface ligada ao loopback por meio 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 navegador do seu laptop. O tráfego passa dentro da sessão SSH, portanto nada novo fica exposto à internet.

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

Leia novamente as quatro propriedades da forma como um atacante as leria.

O programa funciona sem supervisão, por isso ninguém observa o momento em que o modelo interpreta incorretamente um caminho. Ele contém as suas chaves, por isso um único ficheiro de configuração legível dá acesso a toda a conta do seu fornecedor. Ele consegue contactar as suas outras máquinas, por isso uma prompt injection, ou seja, instruções ocultas numa página Web ou num ficheiro lido pelo agente, passa a ter um caminho até ao servidor da base de dados. Ele está acessível a partir de qualquer lugar, por isso uma interface Web que escuta num endereço público, sem firewall à frente e sem autenticação própria, funciona como uma shell para qualquer pessoa que a encontre. dsh coloca um token de processo no URL que apresenta no arranque, o que ajuda, mas esse URL passa a ser uma credencial. Partilhe-o com o mesmo cuidado que teria com uma palavra-passe.

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 de usar a sua:

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

Mantenha a interface Web em loopback e aceda a ela através de SSH. Dê ao agente as credenciais mais restritas que ainda lhe permitam concluir o trabalho. O tópico manter segredos fora dos agentes de IA explica isto corretamente. Para tudo o que funciona 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 muitas etapas em ficheiros reais ou quando precisa de continuar a trabalhar enquanto você dorme.

A maior parte desta categoria é recente. dsh indica developer preview no próprio README em outubro de 2026, e os restantes estão a evoluir suficientemente depressa para que um ficheiro de configuração escrito hoje possa precisar de alterações no próximo mês. Isso é um 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 funciona deixa um diff que você consegue realmente ler no fim de uma execução não supervisionada. Comece com um único harness num único servidor, atribua-lhe uma tarefa e uma chave com permissões restritas, 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 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 fica em torno do modelo. O modelo produz texto e solicita o uso de ferramentas. O harness executa o loop que continua perguntando, 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 arquivos entre os turnos. Troque o modelo e o harness continuará funcionando. 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 loop, um sistema de permissões e ferramentas integradas para arquivos e shell. Claude é a família de modelos chamada por padrão. A mesma separação se aplica ao DeepSeek Harness (dsh), que é um programa Node que você instala, e aos modelos DeepSeek, que são disponibilizados por uma API. Você instala um harness em uma máquina. Você chama um modelo pela rede.

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

Um framework é uma biblioteca que você importa e usa no código, aproveitando o loop existente ou escrevendo o seu próprio. Um harness é um programa que você executa. O loop, as tentativas e o gerenciamento de contexto vêm com padrões que você configura, em vez de implementar. Na prática, a distinção não é rígida: o Deep Agents do LangChain é um SDK importável que o próprio repositório chama de agent harness completo, em outubro de 2026. Pergunte a si mesmo se você escreverá o loop. Essa resposta determina qual termo se aplica à sua situação.

Preciso de um VPS para executar um agent harness?

Não. Todos os harnesses mencionados aqui são executados em um laptop. Um servidor muda quatro aspectos: o agente continua executando quando você fecha a tampa, mantém suas chaves em uma máquina que está sempre ligada, pode acessar os outros servidores e permite retornar à mesma sessão a partir de qualquer dispositivo. Cada um desses aspectos também envolve uma consideração de segurança. Portanto, dê ao agente sua própria conta de usuário e mantenha qualquer interface web vinculada a 127.0.0.1.

Posso usar um modelo diferente dentro do mesmo harness?

Geralmente sim, e essa é a propriedade que define um harness. A maioria aceita o nome do modelo e uma URL base na configuração. Assim, apontar um harness para outro provedor exige uma edição, não uma reescrita. Quando um harness não permite isso diretamente, um roteador local como o Claude Code Router fica entre o harness e o provedor e traduz as solicitações, vinculando-se a 127.0.0.1:3456 por padrão. Tenha cuidado com esse proxy, pois ele vê todos os prompts e mantém todas as chaves.

Este artigo foi útil?