Omnigent: um meta-harness para CLIs de agentes

O que é o Omnigent

O Omnigent é um meta-harness open source: uma camada de orquestração que controla as ferramentas de linha de comandos (CLIs) de agentes que já tem instaladas. Não substitui Claude Code, Codex, Cursor, OpenCode, Hermes ou Pi. Inicia essas ferramentas, atribui uma tarefa a cada uma e supervisiona o resultado numa única sessão, com um único conjunto de políticas. A Databricks publicou o repositório em junho de 2026 sob a licença Apache 2.0, e a página inicial continua a apresentar Status: alpha.

A afirmação prática é limitada e deve ser feita de forma clara. Descreve um agente uma vez, em YAML, e indica o harness que o executa. Altere essa única linha e o mesmo agente será executado pela CLI de outro fornecedor. Nada mais na configuração muda, porque o Omnigent controla o ciclo acima dos agentes, e não o ciclo dentro deles.

O que é um meta-harness e em que difere de um framework?

Um harness é o programa que envolve um modelo num ciclo. Lê o seu prompt, chama ferramentas, edita ficheiros e devolve os resultados. Claude Code é um harness. Codex é um harness. Instala-o, inicia sessão e ele trabalha de forma autónoma.

Um framework é uma biblioteca contra a qual escreve código. Importa-a, define os passos em Python e o seu programa torna-se o agente. Alterar o fornecedor nesse caso exige editar o seu código, porque o cliente do fornecedor está integrado no seu programa.

Um meta-harness fica um nível acima de ambos. É um supervisor que executa harnesses como processos-filho. Omnigent inicia a CLI do fornecedor, entrega-lhe trabalho e lê o que ela devolve. Mantém a CLI que já instalou e a subscrição ou a chave de API (application programming interface) que já a utiliza. Essa é toda a diferença. Ela também define para quem a ferramenta serve: pessoas que já têm várias CLIs de agentes a funcionar e estão cansadas de as controlar uma de cada vez, a partir de um terminal.

Que problema uma camada de orquestração resolve?

• Mudar de fornecedor requer alterar uma linha. A definição do agente contém harness e model como dados, por isso mover uma função de um fornecedor para outro exige editar o ficheiro YAML, não reescrevê-lo.
• A revisão pode abranger vários fornecedores. Um diff escrito por um modelo é lido por um modelo de outra empresa. Dois modelos da mesma família tendem a partilhar os mesmos pontos cegos, por isso uma segunda opinião do mesmo fornecedor tem menos valor.
• A política fica num único local. Os limites de despesas e os pedidos de aprovação são declarados no ficheiro do agente e aplicam-se a todos os subagentes abaixo dele.
• A sessão não depende de uma ferramenta específica. Um único transcript abrange o trabalho realizado por vários CLIs, para que possa consultar o que aconteceu sem juntar quatro históricos de terminal.

O custo é a própria camada. Todos os bugs no Omnigent passam a ser bugs entre si e um agente que antes funcionava de forma autónoma. Na fase alpha, este é um custo real, não teórico.

Onde um harness multiagente se encaixa em relação às ferramentas de agente único

Se ainda não executou um agente num servidor, comece por aí. O nosso guia sobre executar um agente de programação numa VPS cobre o caso de um único agente de ponta a ponta, e é essa a configuração que o Omnigent pressupõe que já tenha. O campo mais amplo dos agentes de IA auto-hospedados é onde escolhe os próprios agentes. Se a terminologia for nova, aprender como os agentes funcionam na prática é um ponto de partida melhor.

O Omnigent também representa um eixo diferente de uma camada de conectores. Trabalhos como dar aos agentes acesso às suas próprias fontes de dados dizem respeito ao que um agente pode alcançar. O Omnigent diz respeito a qual agente é executado, em que ordem e sob que limites. Pode precisar dos dois ao mesmo tempo. Eles não se sobrepõem.

O que é necessário antes da instalação

• Python 3.12 ou mais recente. O pacote publicado declara requires-python >= 3.12.
• tmux, porque os harnesses de terminal são executados nele.
• Pelo menos uma CLI de fornecedor, já instalada e com autenticação concluída.
• Node.js 22 apenas se compilar a partir de um checkout do git. O wheel no PyPI já inclui os recursos web compilados, portanto a instalação normal não precisa do Node.

Instale uma versão fixada, não a branch main

curl -fsSL https://raw.githubusercontent.com/omnigent-ai/omnigent/main/scripts/install_oss.sh | sh -s -- --version 0.7.0

A parte sh -s -- não é decorativa. Sem ela, sh interpreta --version como uma opção própria e o instalador nunca recebe a flag. Assim, você instala o que estiver mais recente naquele dia. Em um repositório que lança alterações incompatíveis a cada poucas semanas, essa é a diferença entre um servidor reproduzível e uma surpresa.

O instalador usa uv, o gerenciador de pacotes Python da Astral, e oferece instalar o uv primeiro se ele não estiver presente. Se o uv já estiver instalado, ignore o script:

uv tool install --force --python 3.12 "omnigent==0.7.0"

Os extras seguem o mesmo padrão, e a flag se repete: --extra e2b --extra kubernetes no script ou "omnigent[e2b,kubernetes]" com uv. Observe que a tag git é v0.7.0, enquanto a versão do pacote no PyPI é 0.7.0.

O uv coloca o binário no diretório indicado por uv tool dir --bin, geralmente ~/.local/bin, e o instalador oferece adicionar esse diretório ao perfil do seu shell. Se o comando não for encontrado imediatamente após uma instalação limpa, esse é o motivo. Verifique o que foi instalado:

omni upgrade --check

Isso compara a versão instalada com a versão publicada mais recente e informa se existe uma atualização, sem executá-la. omni e omnigent são o mesmo programa com dois nomes.

Aponte-o para um fornecedor de modelos

omni setup

O assistente procura as credenciais já presentes no seu ambiente e solicita as que estiverem em falta. Gere chaves de API, subscrições de fornecedores, gateways como OpenRouter ou Ollama e workspaces do Databricks. Se já executar um servidor de modelos local com Ollama na mesma máquina, aponte um gateway para esse servidor e o tráfego nunca sai da máquina.

Uma execução mínima com vários agentes

Os agentes de exemplo estão no repositório. Por isso, clone a mesma tag que instalou, em vez de main.

git clone --depth 1 --branch v0.7.0 https://github.com/omnigent-ai/omnigent.git
cd omnigent
omnigent run examples/polly/

Polly é o orquestrador de programação multiagente incluído no repositório. A configuração define subagentes chamados claude_code, codex, opencode, cursor, hermes e pi, além de uma regra que torna todo o exercício útil: a revisão é sempre feita por um fornecedor diferente daquele que implementou a alteração. Polly não escreve código. Planeia, divide o objetivo em itens de trabalho, delega cada um e encaminha cada diff para um revisor de outro fornecedor.

Antes de delegar qualquer tarefa, Polly executa uma verificação preliminar para determinar quais CLIs dos subagentes existem efetivamente na máquina. Se apenas a CLI de um fornecedor estiver instalada, não haverá ninguém para receber o diff. Por isso, instale pelo menos dois fornecedores antes de avaliar o resultado. Debby, o outro exemplo incluído, é um agente de debate com duas cabeças: uma Claude e outra GPT:

omni debby

É uma forma rápida de confirmar que dois fornecedores estão configurados, porque o agente precisa de ambos para produzir qualquer resposta.

Os subagentes são declarados como ferramentas

O ficheiro do agente está em YAML. executor define o harness, o modelo e a autenticação. tools contém servidores MCP (model context protocol), funções Python e subagentes. Um subagente é uma ferramenta com type: agent e um executor próprio. Esse é o mecanismo subjacente a tudo o que foi descrito acima.

name: orchestrator
prompt: |
  You coordinate coding and review tasks.

executor:
  harness: claude-sdk
  model: databricks-claude-sonnet-4-6

tools:
  coder:
    type: agent
    prompt: Write and test code.
    executor:
      harness: claude-sdk
      model: databricks-claude-opus-4-7
  reviewer:
    type: agent
    prompt: Review proposed changes.
    executor:
      harness: claude-sdk
      model: databricks-claude-sonnet-4-6

omnigent run path/to/my_agent.yaml

Esses IDs de modelo vêm do exemplo docs/AGENT_YAML_SPEC.md do próprio projeto e são nomes alojados no Databricks. Substitua harness e model pelos valores que omni setup configurou no seu sistema. Outros valores de harness na especificação incluem antigravity, copilot, kimi, qwen e acp:<slug> para qualquer componente que utilize o protocolo genérico. A especificação também suporta pass_history: true num subagente, o que lhe transmite a conversa principal. Isso consome tokens em cada delegação. Por isso, deixe essa opção desativada nos subagentes que só precisam da tarefa atual. Um programador cujo prompt lhe indique para fazer a menor alteração que funcione fornece ao revisor um diff suficientemente curto para ser lido. Neste caso, isso é mais importante do que o modelo escolhido para qualquer uma das funções.

Por que a orquestração de longa duração deve ficar num VPS

Uma execução multiagente não é um comando de dois minutos. Planeie, delegue, aguarde os worktrees Git paralelos, reveja e reveja novamente. Fechar a tampa do portátil encerra tudo. Um VPS (servidor virtual privado) permanece ativo e mantém a ligação de rede, por isso a sessão continua enquanto não a acompanha.

omnigent server --background
omnigent server status

O servidor aloja uma interface web na porta 6767. omnigent server status indica se existe uma em execução, e omnigent stop encerra-a. Nas releases anteriores à v0.7.0, este comando era omni server start, que foi removido. Por isso, os textos e as capturas de ecrã mais antigos não correspondem ao que o terminal apresenta.

Não publique a porta 6767 num endereço público. Existem duas formas seguras. Mantenha a porta fechada na firewall e encaminhe-a por SSH com ssh -N -L 6767:localhost:6767 you@your-server. Em seguida, abra a interface web em http://localhost:6767 no seu próprio computador. Ou termine o TLS (segurança da camada de transporte) à frente da interface e ative a autenticação:

OMNIGENT_AUTH_ENABLED=1 omnigent server --background

A parte da firewall é uma tarefa normal, abordada em noções básicas da firewall ufw para um VPS. Se o servidor já executar contentores atrás do Traefik à frente de várias aplicações Docker Compose, o Omnigent é apenas mais um serviço no mesmo padrão.

Numa implementação com contentores, o diretório deploy/ do repositório contém uma configuração Compose: ./bootstrap.sh gera os segredos em .env, e docker compose up -d inicia o Omnigent e o Postgres na porta 6767. DATABASE_URL seleciona Postgres ou SQLite, e OMNIGENT_AUTH_ENABLED assume 1 como valor predefinido dentro dos contentores. Esse é o valor predefinido correto para qualquer serviço acessível a partir do exterior.

Quanto ao dimensionamento, as notas da implementação estimam o conjunto de trabalho do servidor em aproximadamente 512 MB a 1 GB, e a configuração do Fly.io fixa 1 GB. Esse valor corresponde apenas ao supervisor. Cada subagente é um processo separado, com o seu próprio checkout e o seu próprio cliente de modelo. Por isso, dimensione o servidor de acordo com os agentes. Depois de o servidor estar ativo, omnigent login https://your-host seguido de omnigent host https://your-host regista o seu portátil nele, e omnigent attach <session_id> retoma uma sessão em execução a partir de outro dispositivo.

Coloque cada subagente numa sandbox antes de terminar

O Omnigent fornece uma sandbox ao nível do sistema operativo chamada Omnibox. No Linux, usa namespaces do bubblewrap e seccomp, por isso é o kernel que impõe o limite, e não o prompt do agente. Um agente ao qual tenha sido injetado um prompt não consegue convencer o kernel a ignorar uma regra. Instale primeiro a dependência:

sudo apt install bubblewrap

A configuração fica em os_env no ficheiro do agente:

os_env:
  type: caller_process
  cwd: .
  sandbox:
    type: linux_bwrap
    write_paths: [.]
    write_files: []
    read_paths: []
    allow_network: true
    cwd_allow_hidden: [.venv]
    env_passthrough: []
    egress_rules: []
    credential_proxy: []

O diretório de trabalho é só de leitura até o incluir em write_paths, por isso um agente que falhe não consegue escrever fora do workspace. Os dotfiles permanecem ocultos, a menos que sejam indicados em cwd_allow_hidden, o que impede que uma permissão ampla de leitura exponha silenciosamente .ssh ou .aws. Defina egress_rules e todo o tráfego HTTP e HTTPS passará por um proxy com negação por defeito, com cada regra escrita como "METHODS host/path-glob". credential_proxy vai mais longe: o agente só mantém um placeholder, e o proxy substitui-o pelo segredo real quando o pedido sai, por isso uma transcrição exposta não revela nada utilizável. Numa configuração com vários harnesses, cada subagente tem o seu próprio bloco de sandbox no respetivo ficheiro de configuração, em agents/, para que seja possível impedir o revisor de aceder à rede enquanto o implementador continua a ter acesso.

A documentação indica este limite, que é importante. A sandbox do sistema operativo aplica-se às chamadas de ferramentas sys_os_* e aos terminais. Não abrange servidores MCP nem o próprio processo supervisor do Omnigent. Um servidor MCP que tenha iniciado corre fora da sandbox com as suas permissões. Essa lacuna é o motivo pelo qual o padrão mais seguro continua a ser uma máquina descartável por agente. Esse é o tema de executar agentes de programação numa VM descartável. A outra parte do trabalho são as credenciais, e manter os segredos fora do alcance de um agente torna-se mais difícil, e não mais fácil, quando seis subagentes partilham o mesmo host.

Os limites de despesa são políticas declaradas no mesmo ficheiro:

policies:
  budget:
    type: function
    handler: omnigent.policies.builtins.cost.cost_budget
    factory_params:
      max_cost_usd: 5.00
      ask_thresholds_usd: [1.00, 3.00]

Uma execução que planeia com um fornecedor, implementa com um segundo e revê com um terceiro está a gastar em três locais ao mesmo tempo. Por isso, defina o limite antes da primeira execução sem supervisão, e não depois da primeira fatura. As opções integradas também incluem max_tool_calls_per_session e ask_on_os_tools, que pedem aprovação antes das operações em ficheiros e na shell. As nossas notas sobre controlar os custos de agentes de IA num VPS aplicam-se diretamente aqui, e com mais razão, porque os subagentes paralelos multiplicam a taxa de consumo.

Com que rapidez este repositório evolui?

[
  {
    "version": "v0.2.0",
    "released": "2026-06-19",
    "interval": 3
  },
  {
    "version": "v0.3.0",
    "released": "2026-06-27",
    "interval": 8
  },
  {
    "version": "v0.4.0",
    "released": "2026-07-03",
    "interval": 6
  },
  {
    "version": "v0.5.0",
    "released": "2026-07-10",
    "interval": 7
  },
  {
    "version": "v0.5.1",
    "released": "2026-07-10",
    "interval": 0
  },
  {
    "version": "v0.6.0",
    "released": "2026-07-21",
    "interval": 11
  },
  {
    "version": "v0.7.0",
    "released": "2026-07-27",
    "interval": 6
  }
]

Estas são as datas de lançamento publicadas na própria página de releases do projeto, consultada em 3 de agosto de 2026. 7 releases identificadas foram publicadas entre 2026-06-19 e 2026-07-27, e o maior intervalo entre duas delas foi de 11 dias. v0.5.1 foi publicada no mesmo dia que a release anterior. A primeira release, 0.1.1, de 16 de junho de 2026, não aparece no gráfico porque não existe uma tag anterior para calcular o intervalo.

Duas dessas releases alteraram comandos que já tinham sido documentados em guias. A v0.7.0 removeu omni server start em favor de omni server --background. A v0.6.0 mudou o nome do extra omnigent[memory] para omnigent[hindsight], por isso uma linha de instalação copiada de um artigo de junho falha numa build de julho. Isto justifica usar --version no comando de instalação e uma tag no seu git clone; não é uma preferência de estilo.

O que eu ainda não confiaria a ele

Em agosto de 2026, o repositório tinha cerca de 8.1k estrelas, 1.2k forks e aproximadamente 350 issues abertas, com a primeira release pública feita há sete semanas. As estrelas medem interesse, e interesse não é maturidade. O projeto diz que está em alpha, e o histórico de releases acima mostra que alpha é mesmo o que isso significa.

• Eu não o executaria num host que armazena credenciais de produção, porque o sandbox não abrange servidores MCP nem o supervisor.
• Eu não deixaria uma execução sem supervisão sem uma política cost_budget, porque três fornecedores podem faturar em paralelo e nada mais os impede.
• Eu não exporia o servidor num endereço IP público sem definir OMNIGENT_AUTH_ENABLED e sem TLS à frente dele.
• Eu ainda não trataria o YAML do agent como estável entre versões minor, por isso fixe a versão e leia as release notes antes de atualizar.

Há mais uma coisa que deve saber antes de ser surpreendido: a v0.6.0 adicionou telemetria de utilização anonimizada, e o projeto documenta-a numa página dedicada à telemetria. Leia essa página e tome uma decisão consciente se a máquina processar trabalho de clientes.

Atualmente, o Omnigent é realmente bom naquilo para que foi criado. Tem três ou quatro CLIs de agents, já paga por elas e quer que uma escreva enquanto outra faz a revisão. Isso funciona agora, numa máquina, com sandboxing real no Linux. Considere tudo além disso promissor, mas ainda incompleto.

FAQ

O Omnigent é um agente ou algo que executa agentes?

Ele executa agentes. O Omnigent é um meta-harness: inicia as CLIs dos fornecedores que já instalou, como Claude Code, Codex ou OpenCode, atribui trabalho a cada uma e supervisiona os resultados numa única sessão. Não inclui um modelo próprio. Por isso, é diferente de um framework, no qual escreve Python com base numa biblioteca e o seu próprio programa se torna o agente.

Preciso de ter Claude Code e Codex instalados antes de o Omnigent ser útil?

Precisa de ter pelo menos uma CLI de fornecedor instalada e autenticada, porque o Omnigent controla esses programas em vez de os substituir. Para o exemplo Polly incluído, são recomendadas duas ou mais CLIs de fornecedores diferentes. A regra do Polly é que a revisão seja sempre feita por um fornecedor diferente daquele que implementou a alteração. Com uma única CLI instalada, não existe um segundo fornecedor para o qual enviar o diff.

Como instalo uma versão específica do Omnigent em vez da mais recente?

Passe --version ao script de instalação com sh -s --, como em sh -s -- --version 0.7.0. Sem -s --, a flag é consumida pelo próprio sh e o script instala a versão mais recente. Se o uv já estiver instalado, uv tool install --force --python 3.12 "omnigent==0.7.0" faz o mesmo. A tag do git é v0.7.0, enquanto a string de versão do PyPI é 0.7.0.

O sandbox do Omnibox é suficiente para executar agentes sem supervisão?

É forte no que cobre e deixa claro o que não cobre. No Linux, usa bubblewrap e seccomp. Assim, o kernel aplica os limites de ficheiros e de rede, e o agente não os pode contornar. A documentação indica que se aplica a sys_os_* chamadas de ferramentas e terminais, mas não abrange servidores MCP nem o processo supervisor do Omnigent. Por isso, um servidor MCP é executado com as suas permissões normais. Para trabalhos sem supervisão, uma máquina virtual descartável por agente continua a oferecer um isolamento mais forte.

De quanta memória precisa um servidor Omnigent numa VPS?

As notas de implementação do projeto indicam um conjunto de trabalho de aproximadamente 512 MB a 1 GB para o servidor, e a configuração do Fly.io fixa 1 GB. Isto cobre apenas o supervisor e a interface web na porta 6767. Cada subagente é um processo separado, com a sua própria cópia de trabalho e cliente de modelo. As execuções ao estilo Polly também usam worktrees git paralelas. Por isso, dimensione a RAM e o disco para o número de agentes que pretende executar em simultâneo, e não para o servidor.