Omnigent: Como Construir Workflows Multi-Agente com Governança em YAML

O que é o Omnigent

O Omnigent é um framework open-source para construir sistemas multi-agente com IA que combina agentes, ferramentas, delegação hierárquica, acesso a dados em tempo real e políticas de governança — tudo em um único sistema configurável. A grande sacada é que toda a arquitetura do agente é definida em YAML declarativo, sem precisar escrever lógica de orquestração em código.

No tutorial publicado pelo MarkTechPost, o autor Sana Hassan mostra como construir um fluxo de trabalho completo de pesquisa financeira usando o Omnigent. O agente líder consulta uma taxa de câmbio em tempo real via API, prepara um resumo para cliente, e depois delega o rascunho a um sub-agente auditor que verifica clareza e tamanho do texto — tudo isso com limites rígidos de custo e uso de ferramentas.

Como funciona na prática

O Omnigent usa o Claude Agent SDK como motor de execução e organiza os agentes em uma hierarquia clara:

• Agente líder (fx_research_lead): recebe a pergunta do usuário, chama a ferramenta de taxa de câmbio (API Frankfurter), redige um resumo e delega a revisão ao sub-agente.
• Sub-agente auditor (text_auditor): recebe o rascunho, conta palavras, sinaliza jargões não explicados e sugere melhorias de clareza.
• Ferramentas Python: funções comuns do Python (get_exchange_rate, word_count) são expostas como ferramentas que os agentes podem chamar.
• Políticas de governança: limites de chamadas de ferramenta (máximo 20 por sessão) e orçamento (US$ 1,00 por sessão) aplicados automaticamente.

Por que isso importa agora

Em julho de 2026, frameworks multi-agente estão se tornando o padrão para aplicações de IA que vão além do chat simples. O Omnigent se destaca por três razões:

1. Configuração declarativa: você define agentes, ferramentas e políticas em YAML — sem código de orquestração. Isso reduz drasticamente o tempo de desenvolvimento.
2. Execução isolada: usa uv para criar ambientes Python 3.12 isolados, funcionando perfeitamente no Google Colab sem conflitos com o interpretador do sistema.
3. Governança integrada: políticas de limite de custo e de chamadas de ferramenta são aplicadas automaticamente — essencial para uso em produção.

Código: configuração do ambiente

import os, sys, subprocess, textwrap, pathlib, getpass

def sh(cmd, **kw):
    """Executa um comando e mostra o erro real em caso de falha."""
    print("$", " ".join(map(str, cmd)))
    p = subprocess.run(cmd, text=True, capture_output=True, **kw)
    if p.returncode != 0:
        print(p.stdout or "", p.stderr or "", sep="\n")
        raise RuntimeError(f"Command failed ({p.returncode})")
    return p

# Criar diretório e venv isolado com uv
WORKDIR = pathlib.Path("/content/omnigent_tutorial")
WORKDIR.mkdir(parents=True, exist_ok=True)
VENV = WORKDIR / ".venv"
subprocess.run([sys.executable, "-m", "pip", "install", "-q", "uv"], check=True)

if not (VENV / "bin" / "python").exists():
    sh(["uv", "venv", "--python", "3.12", str(VENV)])

PY = str(VENV / "bin" / "python")
sh(["uv", "pip", "install", "--python", PY, "-q", "omnigent", "requests"])
OMNI = str(VENV / "bin" / "omnigent")
print("\n✅", subprocess.run([OMNI, "--version"], capture_output=True, text=True).stdout.strip())

Código: ferramentas Python como funções dos agentes

(WORKDIR / "agent_tools.py").write_text(textwrap.dedent('''
    """Ferramentas locais expostas aos agentes Omnigent."""
    import requests

    def get_exchange_rate(base_currency: str, target_currency: str) -> dict:
        """Busca a taxa de câmbio mais recente entre duas moedas."""
        r = requests.get(
            "https://api.frankfurter.app/latest",
            params={"from": base_currency.upper(), "to": target_currency.upper()},
            timeout=10,
        )
        r.raise_for_status()
        data = r.json()
        return {
            "base": base_currency.upper(),
            "target": target_currency.upper(),
            "rate": data["rates"][target_currency.upper()],
            "date": data["date"],
        }

    def word_count(text: str) -> int:
        """Conta palavras em um texto."""
        return len(text.split())
'''))

Código: arquitetura multi-agente em YAML

(WORKDIR / "fx_research_lead.yaml").write_text(textwrap.dedent('''
    name: fx_research_lead
    prompt: |
      You are a financial research lead. For any question about currency
      movements: call get_exchange_rate to fetch the live rate, then hand
      your draft summary to the text_auditor sub-agent for a clarity and
      length check before giving your final answer to the user.
    executor:
      harness: claude-sdk
    tools:
      get_exchange_rate:
        type: function
        callable: agent_tools.get_exchange_rate
      text_auditor:
        type: agent
        prompt: |
          You audit short pieces of financial writing. Call word_count to
          report its length, flag any unexplained jargon, and suggest one
          concrete clarity improvement.
        tools:
          word_count:
            type: function
            callable: agent_tools.word_count
    policies:
      cap_calls:
        type: function
        handler: omnigent.policies.builtins.safety.max_tool_calls_per_session
        factory_params:
          limit: 20
      budget:
        type: function
        handler: omnigent.policies.builtins.cost.cost_budget
        factory_params:
          max_cost_usd: 1.00
'''))

Código: execução do fluxo

env["PYTHONPATH"] = str(WORKDIR)
question = (
    "What is the current USD to EUR exchange rate? Give me a two-sentence "
    "summary I could paste into a client note."
)
result = subprocess.run(
    [OMNI, "run", str(WORKDIR / "fx_research_lead.yaml"), "-p", question, "--no-session"],
    cwd=WORKDIR, env=env, stdin=subprocess.DEVNULL,
    capture_output=True, text=True, timeout=300,
)

print("\n" + "=" * 70)
print(result.stdout.strip() or "(no stdout)")
if result.returncode != 0 or "error" in result.stdout.lower():
    print("-" * 70)
    print("stderr:", result.stderr[-2000:])
print("=" * 70)

O que você ganha com essa abordagem

✅ Desenvolvimento rápido: YAML declarativo elimina código de orquestração — você descreve o que o agente faz, não como.
✅ Delegação hierárquica: agentes podem delegar tarefas a sub-agentes especializados, como um time real.
✅ Governança automática: limite de custo e de uso de ferramentas aplicados sem código extra.
✅ Execução em Colab: funciona sem Node.js, tmux ou terminal interativo — ideal para prototipagem rápida.
✅ Ferramentas em Python puro: qualquer função Python vira uma ferramenta para o agente.

Limitações a considerar

⚠️ O Omnigent depende do Claude Agent SDK como motor de execução — atualmente vinculado à API da Anthropic.
⚠️ O framework é novo (julho/2026) e a documentação ainda está evoluindo.
⚠️ Para casos de uso com dezenas de agentes simultâneos, o overhead de orquestração pode ser significativo.