Omnigent: como orquestrar várias CLIs de agentes

O que é o Omnigent

Omnigent é um meta-harness de código aberto: uma camada de orquestração que executa as ferramentas de linha de comandos (CLIs) de agentes que já estão 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 apresentada de forma direta. Descreva um agente uma vez, em YAML, e indique o harness que o executa. Altere essa única linha para executar o mesmo agente na CLI de outro fornecedor. Nada mais na sua 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 de execução. 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 funciona 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 implica editar o seu código, porque o cliente do fornecedor está integrado no programa.

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

Que problema uma camada de orquestração resolve?

• Mudar de fornecedor exige uma linha. A definição do agente contém harness e model como dados. Assim, transferir uma função de um fornecedor para outro consiste em editar o ficheiro YAML, não em reescrever a implementação.
• A revisão pode abranger vários fornecedores. Um diff produzido por um modelo é analisado por um modelo de uma empresa diferente. 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 centralizada. Os limites de despesa e os pedidos de aprovação são declarados no ficheiro do agente e aplicam-se a todos os subagentes subordinados.
• A sessão não depende de uma única ferramenta. Um único transcript regista o trabalho feito por vários CLIs. Assim, pode rever o que aconteceu sem juntar quatro históricos de terminal.

O custo é a própria camada. Cada bug no Omnigent passa a ser um bug entre si e um agente que antes funcionava de forma autónoma. Na fase alpha, esse é um custo real, não teórico.

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

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 autoalojados é onde escolhe os próprios agentes, e aprender como os agentes funcionam na prática é o melhor ponto de partida se esta terminologia for nova.

O Omnigent também atua numa dimensão diferente da de uma camada de conectores. O trabalho de dar aos agentes acesso às suas próprias fontes de dados trata dos recursos a que um agente pode aceder. O Omnigent trata de qual agente é executado, por que ordem e com que limites. Pode precisar dos dois ao mesmo tempo, e eles não se sobrepõem.

O que precisa antes de instalar

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

Instale uma versão fixada, não a 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, é instalada a versão mais recente disponível nesse dia. Num repositório que lança alterações incompatíveis a cada poucas semanas, isto determina se o sistema é reproduzível ou se haverá uma surpresa.

O instalador usa uv, o gestor de pacotes Python da Astral, e propõe instalar o uv primeiro se ele não estiver disponível. 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 repete-se: --extra e2b --extra kubernetes no script ou "omnigent[e2b,kubernetes]" com uv. 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, normalmente ~/.local/bin, e o instalador propõe adicionar esse diretório ao perfil da shell. Se o comando não for encontrado imediatamente depois de uma instalação limpa, essa é a causa. Verifique o resultado:

omni upgrade --check

Isto compara a versão instalada com a versão publicada mais recente e indica se existe uma atualização, sem a executar. omni e omnigent são o mesmo programa com dois nomes.

Aponte-o para um fornecedor de modelos

omni setup

O assistente procura credenciais já presentes no seu ambiente e pede as que estão em falta. Trata de 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 codificação com vários agentes incluído no repositório. A respetiva configuração declara subagentes com os nomes claude_code, codex, opencode, cursor, hermes e pi. Também define uma regra que torna este exercício útil: a revisão é sempre feita por um fornecedor diferente do implementador. 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 de subagentes estão efetivamente disponíveis na máquina. Se apenas uma CLI de fornecedor estiver instalada, não haverá outro fornecedor para receber o diff. Por isso, instale pelo menos duas 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 ambos são necessários para produzir qualquer resposta.

Subagentes são declarados como ferramentas

O ficheiro do agente está em YAML. executor identifica 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 o seu próprio executor. 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 correspondem a 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, mantenha essa opção desativada nos subagentes que só precisam da tarefa atual.

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

Uma execução multiagente não é um comando de dois minutos. É necessário planear, delegar, aguardar o trabalho paralelo em worktrees do git, rever e corrigir. Fechar a tampa do portátil encerra tudo. Um VPS (virtual private server) permanece ativo e mantém a ligação de rede, para que a sessão continue enquanto não está a acompanhá-la.

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, isto era feito com omni server start, que foi removido. Por isso, tutoriais e capturas de ecrã antigos não correspondem ao que o terminal apresenta.

Não publique a porta 6767 num endereço público. Existem duas configurações seguras. Mantenha a porta fechada na firewall e encaminhe-a por SSH com ssh -N -L 6767:localhost:6767 you@your-server. Depois, abra a interface web em http://localhost:6767 no seu próprio computador. Em alternativa, termine o TLS (transport layer security) à frente da aplicação e ative a autenticação:

OMNIGENT_AUTH_ENABLED=1 omnigent server --background

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

Numa instalaçã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 usa 1 por predefinição dentro dos contentores. Esta é a predefinição correta para qualquer serviço acessível a partir do exterior.

Quanto ao dimensionamento, as notas da instalaçã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 aplica-se 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 para os agentes. Depois de o servidor estar ativo, omnigent login https://your-host seguido de omnigent host https://your-host regista o portátil no servidor, 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

Omnigent disponibiliza uma sandbox ao nível do sistema operativo chamada Omnibox. No Linux, utiliza namespaces do bubblewrap e seccomp, para que o kernel aplique o limite de segurança em vez de depender do prompt do agente. Um agente ao qual foi injetado um prompt não consegue contornar uma regra do kernel através de instruções. 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 é apenas de leitura até o listar em write_paths, pelo que um agente que tenha um comportamento incorreto não consegue escrever fora do workspace. Os dotfiles permanecem ocultos, exceto se forem indicados em cwd_allow_hidden. Assim, uma permissão ampla de leitura não expõe silenciosamente .ssh nem .aws. Defina egress_rules para encaminhar todo o tráfego HTTP e HTTPS através de um proxy com bloqueio por predefinição, com cada regra escrita como "METHODS host/path-glob". credential_proxy vai mais longe: o agente mantém apenas um placeholder, e o proxy substitui-o pelo segredo real quando o pedido sai. Assim, 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/. Desta forma, pode impedir o acesso à rede do agente de revisão enquanto mantém esse acesso para o agente de implementação.

A documentação indica este limite, e ele é importante. A sandbox do sistema operativo aplica-se a sys_os_* chamadas de ferramentas e aos terminais. Não abrange servidores MCP nem o próprio processo supervisor do Omnigent. Um servidor MCP que iniciar é executado fora da sandbox, com as suas permissões. Por esse motivo, 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. 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 faz o planeamento com um fornecedor, a implementação com um segundo e a revisão com um terceiro gera despesas 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 funcionalidades integradas também incluem max_tool_calls_per_session e ask_on_os_tools, que pedem aprovação antes de operações em ficheiros e na shell. As nossas notas sobre controlar os custos de agentes de IA numa VPS aplicam-se diretamente aqui, e com maior importância, porque os subagentes paralelos multiplicam a taxa de consumo.

Qual é a velocidade de evolução deste repositório?

[
  {
    "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 marcadas foram lançadas entre 2026-06-19 e 2026-07-27, e o maior intervalo entre duas releases foi de 11 dias. v0.5.1 foi lançada 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 a partir da qual medir o intervalo.

Duas dessas releases alteraram comandos que já estavam documentados em guias. A v0.7.0 removeu omni server start e passou a usar 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. Esta é a razão para fixar --version no comando de instalação e usar uma tag no seu git clone, e não apenas uma preferência de estilo.

Aquilo em que eu ainda não confiaria

Em agosto de 2026, o repositório tinha cerca de 8.1k estrelas, 1.2k forks e aproximadamente 350 issues abertas, com a primeira versão pública lançada há sete semanas. As estrelas medem o interesse, e o interesse não é maturidade. O projeto declara-se alpha, e o histórico de versões acima mostra que isso significa alpha.

• Eu não o executaria num host que armazene credenciais de produção, porque a 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 colocar TLS à sua frente.
• Eu ainda não trataria o YAML do agente como estável entre versões minor, por isso fixe a versão e leia as notas da versão antes de atualizar.

Há mais uma coisa que deve saber antes de ser surpreendido por ela: 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 deliberada 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 agentes, já paga por elas e quer que uma escreva enquanto outra faz a revisão. Isso já funciona, numa máquina, com sandboxing real no Linux. Considere tudo além disso promissor, mas incompleto.

FAQ

O Omnigent é um agente ou executa agentes?

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 sobre uma 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 um fornecedor instalada e autenticada, porque o Omnigent controla esses programas em vez de os substituir. Para o exemplo Polly incluído, precisa de 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 apenas uma CLI instalada, não existe um segundo fornecedor para receber 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 já tiver uv instalado, uv tool install --force --python 3.12 "omnigent==0.7.0" faz o mesmo. A tag git é v0.7.0, enquanto a string de versão do PyPI é 0.7.0.

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

É forte no que abrange e é claro quanto ao que não abrange. No Linux, utiliza bubblewrap e seccomp, pelo que 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 chamadas de ferramentas sys_os_* e a 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 trabalho sem supervisão, uma máquina virtual descartável por agente continua a proporcionar 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 utilizam worktrees git paralelas. Por isso, dimensione a RAM e o disco de acordo com o número de agentes que pretende executar em simultâneo, e não apenas de acordo com o servidor.