Como usar o Omnigent para gerenciar CLIs de agentes
Aprenda a configurar o Omnigent como meta-harness para orquestrar CLIs de agentes. Veja como fixar a release 0.7.0 e isolar cada instância em um ambiente VPS com segurança.
O que é o Omnigent
O 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. Ele não substitui Claude Code, Codex, Cursor, OpenCode, Hermes ou Pi. O Omnigent 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 o PyPI ainda classifica o pacote como alpha.
A afirmação prática é restrita e deve ser apresentada de forma direta. Descreve-se um agente uma vez, em YAML, e indica-se o harness que o executa. Altere essa linha e o mesmo agente será executado pela CLI de outro fornecedor. Nada mais na configuração precisa de ser alterado, 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?
- Custos de troca de fornecedor em uma linha. A definição do agente mantém
harnessemodelcomo dados, portanto, mover uma função de um fornecedor para outro é uma edição no arquivo YAML, não uma reescrita. - A revisão pode cruzar fornecedores. Um diff escrito por um modelo é lido por um modelo de uma empresa diferente. Dois modelos da mesma família tendem a compartilhar os mesmos pontos cegos, então uma segunda opinião do mesmo fornecedor vale menos.
- A política tem um único local. Limites de orçamento e solicitações de aprovação são declarados no arquivo do agente e aplicam-se a cada subagente abaixo dele.
- A sessão sobrevive a qualquer ferramenta individual. Uma transcrição cobre o trabalho realizado por várias CLIs, permitindo que você releia o que aconteceu sem precisar juntar quatro históricos de terminal.
O custo é a própria camada. Cada bug no Omnigent agora é um bug posicionado entre você e um agente que costumava funcionar sozinho. Na fase alpha, esse é 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 precisa de ter 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 dentro dele.- Pelo menos uma CLI de fornecedor, já instalada e autenticada.
- Node.js 22 ou mais recente com
npm, porque os harnesses Claude, Codex e Pi precisam desses componentes. O instalador verifica se existe o Node 22.10 ou posterior e apresenta um aviso se estiver em falta. O Omnigent não precisa de Node: o wheel publicado no PyPI inclui os recursos Web compilados, e apenas uma compilação a partir de um checkout git torna o Node um requisito obrigatório.
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.0A parte sh -s -- não é decorativa. Sem ela, sh interpreta --version como uma opção própria e o instalador nem sequer é executado. Quando sh é Bash, imprime a própria versão do Bash e termina com sucesso. Assim, nada é instalado e nenhum aviso é emitido. Com -s --, sh lê o script a partir do pipe e passa --version 0.7.0 ao instalador. Num repositório que introduz alterações incompatíveis a cada poucas semanas, essa é a diferença entre um sistema reproduzível e uma surpresa.
A versão 0.7.0 continua publicada no PyPI em 29 October 2026, mas a versão mais recente é agora a 0.22.0, de 13 November 2026. A versão anterior 0.19.1 é uma atualização focada na segurança, sem funcionalidades novas: atualiza as dependências depois do comprometimento da autoridade de certificação intermédia da eMudhra, e o projeto recomenda a atualização. O que importa é a fixação, não o número: fixe a versão que testou e leia as alterações incompatíveis nas notas da versão antes de a atualizar. Uma versão fixada não é motivo para ignorar uma versão de segurança. Atualize-a quando uma for publicada.
O instalador usa uv, o gestor de pacotes Python da Astral, e propõe instalar primeiro o uv se este estiver ausente. 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. O script também adiciona o extra databricks, a menos que passe --no-databricks, enquanto a linha com uv acima instala o pacote sem esse extra. Note 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, 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 --checkIsto compara a versão instalada com a versão mais recente publicada 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 setupO 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 sub-agentes 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 sub-agentes. Um sub-agente é uma ferramenta com type: agent e um executor próprio. Esse é o mecanismo subjacente a tudo o que foi referido 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-6omnigent run path/to/my_agent.yamlEsses 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 e qwen. A especificação atual em main também documenta acp:<slug> para qualquer servidor Agent Client Protocol, mas a especificação v0.7.0 não o lista. Confirme se funciona na versão fixada antes de depender dele. A especificação também suporta pass_history: true num sub-agente, que lhe transmite a conversa do agente-pai. Isso consome tokens em cada delegação. Por isso, deixe essa opção desativada nos sub-agentes que só precisam da tarefa atual. Um programador cujo prompt lhe indique para fazer a alteração mais pequena que funcione entrega ao revisor um diff suficientemente curto para ser lido de facto. 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 ser executada num VPS
Uma execução multi-agente não é um comando de dois minutos. Envolve planear, delegar, aguardar por worktrees do git em paralelo, rever e corrigir. Fechar a tampa do portátil termina tudo isto. Um VPS (servidor privado virtual) permanece ligado e mantém a sua rede, pelo que a sessão sobrevive enquanto não a está a monitorizar.
omnigent server --background
omnigent server statusO servidor aloja uma interface web na porta 6767. omnigent server status reporta se existe uma instância em execução e omnigent stop encerra a mesma. A v0.7.0 removeu o omni server start em favor do omni server --background; a v0.9.0 restaurou-o como um alias obsoleto.
Não exponha a porta 6767 num endereço público. Existem duas formas seguras. Mantenha a porta fechada na firewall e encaminhe-a via SSH com ssh -N -L 6767:localhost:6767 you@your-server, acedendo depois à interface web em http://localhost:6767 na sua própria máquina. Ou termine o TLS (transport layer security) à frente da mesma e ative a autenticação:
OMNIGENT_AUTH_ENABLED=1 omnigent server --backgroundA parte da firewall é uma tarefa comum, descrita em noções básicas de firewall ufw para um VPS, e se a máquina já executa contentores atrás de Traefik à frente de várias aplicações Docker Compose, então o Omnigent é apenas mais um serviço no mesmo padrão.
Para uma implementação em contentor, o diretório deploy/docker/ do repositório contém uma configuração Compose: ./bootstrap.sh gera segredos para o .env, depois docker compose up -d inicia o Omnigent e o Postgres, com o servidor na porta 8000 em vez da 6767. OMNIGENT_PORT altera essa porta do host. O Compose calcula o DATABASE_URL para si (noutros alvos de implementação, a mesma variável seleciona Postgres ou SQLite), e o OMNIGENT_AUTH_ENABLED assume por omissão 1 dentro dos contentores, que é o valor correto para qualquer serviço acessível a partir do exterior.
Quanto ao dimensionamento, as notas de implementação indicam que o uso de memória em repouso do servidor é de aproximadamente 275 MB RSS, e a configuração do Fly.io define uma máquina de 1 GB. A medição em repouso refere-se apenas ao supervisor; o 1 GB é a memória alocada à máquina. Os sub-agentes podem partilhar o diretório de trabalho e o ambiente do progenitor, incluindo o seu sandbox através do os_env: inherit. Worktrees do git separadas são uma escolha de orquestração, por isso dimensione a máquina de acordo com os harnesses e agentes que executa simultaneamente. Assim que o servidor estiver operacional, omnigent login https://your-host seguido de omnigent host https://your-host regista o seu portátil no mesmo, 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, pelo que o kernel impõe o limite em vez de depender do prompt do agente. Um agente sujeito a prompt injection não consegue contornar uma regra do kernel apenas através do diálogo. Instale primeiro a dependência:
sudo apt install bubblewrapA 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é ser listado em write_paths, pelo que um agente com comportamento incorreto não consegue escrever fora do workspace. Os dotfiles de nível superior no diretório de trabalho e cada raiz read_paths permanecem ocultos, exceto quando são indicados em cwd_allow_hidden. Assim, uma permissão ampla de leitura não expõe silenciosamente os diretórios .ssh ou .aws de nível superior. Os dotfiles aninhados continuam visíveis por predefinição; defina cwd_hidden_scan_recursive: true para os ocultar em toda a árvore. Defina egress_rules e todo o tráfego HTTP e HTTPS passará por um proxy com negação por predefinição, 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. Assim, um transcript exposto não revela nada utilizável. Numa configuração com vários harnesses, cada subagente tem o seu próprio bloco de sandbox no seu próprio ficheiro de configuração em agents/. Deste modo, pode negar a rede ao revisor e mantê-la disponível para o implementador.
A documentação declara este limite, e ele é 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 iniciar corre fora da sandbox com as suas permissões. Esta lacuna é o motivo pelo qual o padrão mais forte 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 metade do trabalho são as credenciais, e manter os segredos fora do alcance de um agente torna-se mais difícil, não mais fácil, quando seis subagentes partilham o mesmo host.
Os limites de gasto 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]A política cost_budget pede aprovação nos limites flexíveis e bloqueia todos os modelos em max_cost_usd por predefinição. Definir uma lista expensive_models não vazia transforma o limite numa barreira de downgrade: os modelos que não estão nessa lista podem continuar a gastar. Uma execução que planeia com um fornecedor, implementa com um segundo e faz a revisão com um terceiro está a gastar em três locais ao mesmo tempo. Por isso, defina os limites antes da primeira execução sem supervisão, e não depois da primeira fatura. As opções incorporadas 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 manter os custos de agentes de IA sob controlo num VPS aplicam-se diretamente aqui, e com maior importância, porque os subagentes paralelos multiplicam a taxa de consumo.
Qual é a velocidade de atualização deste repositório?
Os dados por trás deste gráfico
[
{
"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 página de releases do próprio projeto, consultadas em 3 de agosto de 2026. 7 releases com tag foram disponibilizadas entre 2026-06-19 e 2026-07-27, e o maior intervalo entre duas quaisquer foi de 11 dias. A versão v0.5.1 foi lançada no mesmo dia que a anterior. As duas primeiras releases no PyPI, 0.1.0 em 13 de junho de 2026 e 0.1.1 em 16 de junho de 2026, não possuem entrada na página de releases do GitHub e foram excluídas do gráfico; os três dias apresentados para a v0.2.0 são contados a partir da 0.1.1.
Duas dessas releases alteraram comandos que os guias já tinham documentado. A v0.7.0 removeu o omni server start em favor do omni server --background. A v0.6.0 renomeou o extra omnigent[memory] para omnigent[hindsight], mas manteve o memory como um alias de compatibilidade que continuou a funcionar até à 0.10.0. A partir da 0.11.0, lançada a 25 de agosto de 2026, o alias foi removido, pelo que uma linha de instalação copiada de um artigo de junho já não instala o cliente Hindsight. Este é o argumento a favor do uso de --version no seu comando de instalação e de uma tag no seu git clone, não se trata de uma preferência de estilo.
O ritmo não abrandou desde essa consulta. Até 29 de outubro de 2026, o PyPI lista a 0.20.0, lançada a 28 de outubro, treze releases menores após a 0.7.0, e as notas de lançamento do projeto indicam alterações disruptivas em várias delas. Duas são relevantes para qualquer conteúdo copiado desta página: a v0.12.0 fez com que um omni isolado iniciasse o host em background em vez do agente Polly (o omni run agora inicia o agente padrão), e a v0.13.0 requer o tmux 3.3 ou superior para terminais geridos.
O que eu ainda não confiaria a ele
Em 27 de outubro de 2026, o repositório tinha cerca de 11k stars, 1.8k forks e aproximadamente 910 issues abertas, com uma primeira versão pública lançada há pouco mais de quatro meses. As stars medem 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 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 cobrar em paralelo; com uma listaexpensive_modelsnão vazia, os gastos podem continuar em modelos mais baratos. - Eu não exporia o servidor num endereço IP público sem definir
OMNIGENT_AUTH_ENABLEDe colocar TLS à frente dele. - Eu ainda não trataria o YAML do agente como estável entre versões minor, por isso fixaria a versão e leria as notas de 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, o README indica que a recolha está ativa por predefinição e o projeto documenta essa funcionalidade, incluindo como desativá-la, 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 é genuinamente 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 única 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: ele inicia as CLIs de fornecedores que você já instalou, como Claude Code, Codex ou OpenCode, atribui trabalho a cada uma e supervisiona os resultados em uma única sessão. Ele não traz nenhum modelo próprio. É por isso que ele difere de um framework, onde você escreve Python contra uma biblioteca e seu próprio programa se torna o agente.
Preciso ter o Claude Code e o Codex instalados para o Omnigent ser útil?
Você precisa de pelo menos uma CLI de fornecedor instalada e autenticada, pois o Omnigent controla esses programas em vez de substituí-los. Para o exemplo Polly fornecido, você precisará de dois ou mais de fornecedores diferentes. A regra do Polly é que a revisão seja sempre feita por um fornecedor diferente do implementador, portanto, com apenas uma CLI presente, não há 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 através do script de instalação com sh -s --, como em sh -s -- --version 0.7.0. Sem -s --, o sh interpreta --version como sua própria opção e o instalador nunca é executado: o Bash, por exemplo, imprime sua própria versão e encerra. Com o uv já presente, uv tool install --force --python 3.12 "omnigent==0.7.0" realiza a mesma tarefa. A tag do 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?
Ele é robusto para o que cobre e claro sobre o que não cobre. No Linux, ele utiliza bubblewrap com seccomp, de modo que o kernel impõe limites de arquivo e rede, e o agente não pode desativá-los. A documentação afirma que isso se aplica a chamadas de ferramentas sys_os_* e terminais, e que não cobre servidores MCP ou o processo supervisor do Omnigent. Portanto, um servidor MCP é executado com suas permissões normais, razão pela qual uma máquina virtual descartável por agente permanece o isolamento mais forte para trabalho sem supervisão.
Quanta memória um servidor Omnigent precisa em uma VPS?
As notas de deploy do projeto relatam cerca de 275 MB de RSS em repouso, e sua configuração no Fly.io aloca uma máquina de 1 GB. A medição em repouso cobre apenas o servidor, não seus subagentes. Os subagentes podem compartilhar o diretório de trabalho e o ambiente do pai, incluindo seu sandbox através de os_env: inherit; cópias de trabalho separadas não são garantidas. Execuções no estilo Polly usam worktrees do git em paralelo, portanto, dimensione a RAM e o disco de acordo com o número de agentes que você planeja executar simultaneamente, e não apenas para o servidor.