MCPOmni Connect

Um gateway universal de interface de linha de comando (CLI) para o ecossistema MCP, integrando múltiplos servidores MCP, modelos de IA e protocolos de transporte.

GitHub

245

Experimente este MCPPatrocinado

Documentação

OmniCoreAgent Logo

OmniCoreAgent

O Harness de Agente de Produção Aberto para Python
Lotes paralelos de ferramentas, observações estruturadas, detecção de loops por assinatura, ferramentas MCP, memória, arquivos de workspace, subagentes, tarefas em segundo plano e serviço REST/SSE.

O Que É - Início Rápido - Escolha Seu Caminho - Casos de Uso - Por Que Isso Importa - Instalação - Livro de Receitas - Recursos - Documentação - Pergunte à IA

O Que É

Um LLM não é um agente por si só. O modelo fornece inteligência; o harness dá a essa inteligência um ambiente de trabalho.

OmniCoreAgent é a camada de harness voltada para aplicações em torno de um modelo:

model
  + prompt contract
  + reasoning loop
  + local tools
  + MCP tools
  + parallel tool batches
  + structured observations
  + memory
  + context control
  + workspace files
  + tool-output offloading
  + guardrails
  + events
  + subagents
  + background tasks
  + REST/SSE serving

Essa é a diferença entre um harness de agente e uma biblioteca genérica de agente. Uma biblioteca fornece peças para você montar. Um harness fornece o limite de tempo de execução que torna um modelo utilizável dentro de uma aplicação.

OmniCoreAgent mantém esse limite explícito:

Camada	O Que Ela Controla
Harness de agente	Loop do modelo, contrato de prompt, ferramentas, observações, memória, contexto, workspace, guardrails, eventos, subagentes
Limite de serviço	APIs REST/SSE do OmniServe, ciclo de vida de requisições, prontidão, autenticação, limites de taxa, métricas
Limite de segundo plano	Execução durável de tarefas agendadas/manuais com estado de tarefa, histórico de execuções, leases, novas tentativas e saída de workspace
Limite de ferramentas externas	Ferramentas de servidores MCP e ferramentas Python locais expostas por uma única superfície de tempo de execução

Comece com o harness principal. Ative as peças de produção mais pesadas somente quando a carga de trabalho precisar delas.

Se você prefere documentação guiada, comece com o Início Rápido. Se você usa ferramentas de codificação com IA, use o guia de ferramentas de IA para Pergunte à IA, /llms.txt, documentação hospedada via MCP, Cursor, VS Code, ChatGPT, Claude e Perplexity.

Início Rápido

pip install omnicoreagent

export LLM_API_KEY=your_api_key

import asyncio
from omnicoreagent import OmniCoreAgent

agent = OmniCoreAgent(
    name="assistant",
    system_instruction="You are a helpful assistant.",
    model_config={"provider": "openai", "model": "gpt-4o"},
)

async def main():
    result = await agent.run(
        "Research the top 3 open-source agent runtimes and summarize them.",
        session_id="quickstart",
    )
    print(result["response"])
    await agent.cleanup()

asyncio.run(main())

Esse é o caminho mais curto: um agente, um modelo, uma sessão estável, o loop do harness, memória de sessão, guardrails, arquivos de workspace, tratamento de erros e métricas em torno de cada execução.

Gerenciamento de contexto, descarregamento de saída de ferramentas, recuperação de ferramentas BM25, subagentes, habilidades, armazenamento de workspace em nuvem e backends de produção são opcionais para que um agente pequeno permaneça pequeno.

Pronto para se aprofundar? O Livro de Receitas tem exemplos progressivos desde hello world até implantações de produção.

Escolha Seu Caminho

Objetivo	Comece Aqui
Construa seu primeiro agente	Início Rápido
Adicione ferramentas Python	Livro de receitas de ferramentas locais
Conecte ferramentas de servidores MCP	Livro de receitas de ferramentas MCP
Gerencie memória e contexto	Livro de receitas de introdução
Salve arquivos, artefatos e grandes resultados de ferramentas	Livro de receitas de descarregamento de ferramentas
Construa um harness de aplicação com formato de produção	Livro de receitas de aplicações reais
Construa fluxos de trabalho de múltiplas etapas	Livro de receitas de fluxos de trabalho
Sirva um agente via HTTP/SSE	Livro de receitas do OmniServe
Use a documentação dentro de ferramentas de IA	Guia de ferramentas de IA
Depure configuração ou instalação	Guia de configuração
Entenda os detalhes internos do tempo de execução	Mapa de Implementação

O Que Você Pode Construir

OmniCoreAgent é para construtores de aplicações que precisam que o tempo de execução do agente se mantenha firme depois que o protótipo funciona.

Construção	Peças do Harness Que Você Usa
Agentes de produto conectados via MCP	Ferramentas MCP, ferramentas locais, observações estruturadas, guardrails, memória de sessão
Agentes de pesquisa e análise	Lotes paralelos de ferramentas, arquivos de workspace, descarregamento de ferramentas, gerenciamento de contexto, leitura de artefatos
Agentes de trabalho de longa duração	Tarefas em segundo plano, armazenamentos de tarefas duráveis, histórico de execuções, saída de workspace, novas tentativas, cancelamento
Sistemas de tarefas multiagente	Subagentes dinâmicos, saída de workspace compartilhada, orquestração de fluxos de trabalho, eventos de telemetria
APIs de agente	OmniServe REST/SSE, prontidão, autenticação, tempo limite de requisição, limites de taxa, métricas
Integrações de aplicações de produção	Backends opcionais Redis, MongoDB, SQL, S3 e R2 sem tornar a instalação principal pesada

A ideia central é simples: um ponto de entrada de harness, muitas membranas de aplicação. Você traz as instruções de domínio, ferramentas e lógica de negócio. OmniCoreAgent fornece o limite de execução em torno delas.

Por Que Isso Importa

A maioria das demonstrações para em "LLM mais loop de ferramentas." Agentes de produção falham na camada em torno desse loop: chamadas de ferramentas sequenciais lentas, observações ruidosas, ações repetidas, exaustão de contexto, saída insegura de ferramentas, estado de workspace ausente, trabalho em segundo plano não inspecionável e limites de serviço fracos.

OmniCoreAgent existe para essa camada.

1. Agentes chamam ferramentas em lotes em vez de sequências forçadas

O loop de ferramentas usual se parece com isto:

LLM -> call tool A -> wait -> result -> LLM -> call tool B -> wait -> result

OmniCoreAgent permite que o modelo solicite ferramentas independentes juntas:

LLM -> [tool A + tool B + tool C in parallel] -> one structured observation -> LLM

O modelo obtém uma visão completa do lote antes de raciocinar novamente. Uma ferramenta com falha é representada ao lado das ferramentas bem-sucedidas em vez de colapsar silenciosamente a etapa inteira.

Chamada de função nativa sozinha não é o tempo de execução. OmniCoreAgent usa seu próprio contrato de chamada de ferramenta, parser, resolvedor, executor paralelo e formatador de resultados para que o harness controle o caminho completo de execução.

2. Resultados de ferramentas se tornam observações estruturadas

A saída bruta de ferramentas é frequentemente ruidosa demais para a próxima etapa de raciocínio. Grandes cargas, erros, campos irrelevantes e conteúdo de injeção de prompt podem distorcer o loop.

OmniCoreAgent roteia os resultados das ferramentas por um pipeline de observação:

tool output -> parse -> format -> guardrail check -> offload when configured -> observation -> model

O modelo recebe o sinal de que precisa para continuar a tarefa, não um despejo ilimitado de cada byte retornado por uma ferramenta. Quando o descarregamento de ferramentas está habilitado, grandes saídas são gravadas no workspace ativo e o modelo recebe uma prévia legível mais um caminho que pode usar depois.

3. Detecção de loops usa assinaturas além de contagens de etapas

max_steps ainda é útil, mas é um instrumento bruto. Ele interrompe um agente que está fazendo progresso tão rapidamente quanto um que está travado.

OmniCoreAgent rastreia assinaturas de chamadas de ferramenta com hash SHA256 ao longo do loop. Cada assinatura é baseada no nome da ferramenta, entrada e saída da chamada. O tempo de execução detecta:

Loops consecutivos: a mesma chamada de ferramenta retorna o mesmo resultado repetidamente.
Loops de padrão: a mesma ferramenta repete um pequeno padrão de interação.

Quando o harness interrompe um loop, o agente recebe um motivo. Isso torna a depuração do comportamento do agente muito mais fácil do que "máximo de iterações atingido."

4. O harness já está montado

OmniCoreAgent é entregue como um harness funcional, não um saco de peças desconectadas:

model + prompt + loop + tools + memory + context + workspace + guardrails + telemetry

Mantenha-o pequeno para agentes simples e depois ative as peças mais pesadas do harness quando a carga de trabalho precisar delas: ferramentas MCP, recuperação de ferramentas BM25, subagentes dinâmicos, habilidades, armazenamento de workspace em nuvem, memória Redis/Postgres/MongoDB, eventos de telemetria e OmniServe.

5. O contexto é gerenciado antes da chamada do modelo

Quando o gerenciamento de contexto está habilitado, OmniCoreAgent verifica o histórico ativo de mensagens antes de cada requisição ao LLM. Se o limite configurado for ultrapassado, o harness aplica automaticamente a estratégia selecionada antes de chamar o modelo:

messages -> threshold check -> truncate or summarize+truncate -> LLM

O prompt do sistema é preservado, mensagens recentes são preservadas e o histórico intermediário mais antigo é resumido ou removido dependendo da configuração. Se você definir o orçamento abaixo da janela de contexto real do seu modelo, o harness age antes que o provedor rejeite a requisição.

Veja Em Ação

import asyncio
from omnicoreagent import MemoryRouter, OmniCoreAgent, ToolRegistry

tools = ToolRegistry()

@tools.register_tool("search_web")
def search_web(query: str) -> dict:
    """Search the web for information."""
    return {"results": [f"Result for: {query}"]}

@tools.register_tool("fetch_document")
def fetch_document(path: str) -> dict:
    """Fetch a domain document from an application-owned source."""
    return {"path": path, "content": f"Contents of {path}"}

agent = OmniCoreAgent(
    name="research-agent",
    system_instruction=(
        "You are a research assistant. Use tools in parallel when the calls are "
        "independent and you can reason over the results together."
    ),
    model_config={"provider": "openai", "model": "gpt-4o"},
    local_tools=tools,
    memory_router=MemoryRouter("in_memory"),
    agent_config={
        "max_steps": 20,
        "context_management": {"enabled": True},
        "tool_offload": {"enabled": True},
        "enable_subagents": True,
        "enable_advanced_tool_use": True,
    },
)

async def main():
    result = await agent.run(
        "Search for recent AI agent papers and fetch notes.md. Do both at once "
        "if neither depends on the other."
    )
    print(result["response"])
    await agent.cleanup()

asyncio.run(main())

O tempo de execução aceita search_web e fetch_document no mesmo lote, retorna ambos os resultados juntos e continua a partir de uma observação estruturada.

Instale Apenas o Que Você Precisa

pip install omnicoreagent                    # Core runtime
pip install "omnicoreagent[redis]"           # Redis memory backend
pip install "omnicoreagent[postgres]"        # PostgreSQL / SQL memory
pip install "omnicoreagent[mongodb]"         # MongoDB memory
pip install "omnicoreagent[s3]"              # S3 / R2 workspace storage
pip install "omnicoreagent[serve]"           # OmniServe REST/SSE API
pip install "omnicoreagent[tokenizer]"       # Token-aware context budgeting
pip install "omnicoreagent[otel]"            # OTLP trace export
pip install "omnicoreagent[langsmith]"       # LangSmith trace export
pip install "omnicoreagent[opik]"            # Comet Opik trace export
pip install "omnicoreagent[all]"             # Everything

Backends de produção são extras instaláveis. Instale apenas o que o agente realmente usa.

Recursos

Núcleo do Tempo de Execução

Recurso	O Que Ele Faz
Execução Paralela de Lotes de Ferramentas	Executa chamadas de ferramentas independentes simultaneamente e retorna uma observação combinada ao modelo.
Pipeline de Observações Estruturadas	Analisa, formata, verifica guardrails e descarrega resultados de ferramentas quando configurado antes de o modelo vê-los.
Detecção de Loops por Assinatura	Detecta assinaturas repetidas de chamadas de ferramentas com hash SHA256 e padrões repetidos de interação de ferramentas além da exaustão por contagem de etapas.
Registro Local de Ferramentas	Registra funções Python como ferramentas com esquemas inferidos e suporte a execução assíncrona/síncrona.
Memória em Múltiplos Níveis	Usa histórico de sessão em memória, Redis, MongoDB ou SQL por meio do roteador de memória.
Engenharia de Contexto	Verifica o contexto antes de cada chamada de modelo e trunca ou resume automaticamente quando o limite de orçamento configurado é ultrapassado.
Arquivos de Workspace	Dá aos agentes um workspace de arquivos local, S3 ou R2 para notas, rascunhos, artefatos e descarregamentos de ferramentas.
Descarregamento de Saída de Ferramentas	Grava grandes resultados de ferramentas em arquivos de workspace e dá ao modelo uma prévia mais uma referência de arquivo.
Guardrails	Adiciona triagem de injeção de prompt dentro do caminho de observação com comportamento configurável.

Harness de Produção

Recurso	O Que Ele Faz
Subagentes Dinâmicos	Permite que o agente principal crie trabalhadores focados com contexto isolado e saída de workspace compartilhada.
Tarefas Duráveis em Segundo Plano	Executa trabalho de agente manual ou agendado com estado de tarefa, histórico de execuções, novas tentativas, cancelamento e saída de workspace.
Orquestração de Fluxos de Trabalho	Fornece agentes sequenciais, paralelos e roteadores para fluxos de trabalho de aplicações de múltiplas etapas.
Telemetria e Rastreamentos	Emite eventos de telemetria tipados, recupera rastreamentos por `trace_id` exato, sessão mais recente ou correlação `run_id`, e exporta rastreamentos para OTLP, LangSmith, Opik ou JSONL.
OmniServe	Transforma um agente em um serviço REST/SSE com gerenciamento de ciclo de vida, autenticação, limites de taxa, APIs de telemetria, APIs de segundo plano e métricas.

Integrações

Recurso	O Que Ele Faz
Ferramentas Nativas MCP	Conecta servidores MCP via stdio, SSE e Streamable HTTP, incluindo servidores remotos com capacidade OAuth.
Habilidades de Agente	Carrega capacidades empacotadas implementadas com Python, Bash ou Node.js.
Recuperação de Ferramentas BM25	Seleciona ferramentas relevantes de grandes conjuntos de ferramentas para que o prompt permaneça focado.
Troca de Backend em Tempo de Execução	Troca backends de memória em tempo de execução quando configurado.
Modelos Universais	Suporta OpenAI, Anthropic, Gemini, Groq, Ollama, DeepSeek, Mistral, OpenRouter, Azure e Cencori por meio da camada de modelos do tempo de execução.

Mapa de Implementação

As capacidades do OmniCoreAgent são suportadas por módulos concretos de tempo de execução:

Recurso	Onde Está
Lotes paralelos de ferramentas	`core/tools/tool_batch_runner.py`
Contrato de chamada de ferramentas XML	`core/agents/xml_parser.py`
Observações estruturadas	`core/tools/tool_observation.py`
Descarregamento de saída de ferramentas	`core/workspace/artifacts.py`
Controle automático de contexto	`core/agents/llm_step.py`, `core/context_manager.py`
Arquivos do workspace	`core/workspace/tools.py`, `core/workspace/storage.py`
Subagentes dinâmicos	`core/subagents.py`
Detecção de loops	`core/agents/loop_detection.py`
Ferramentas do servidor MCP	`mcp_clients_connection/client.py`
OmniServe	`serve/`

Consulte a documentação do Agent Harness para o mapa completo de implementação.

Cookbook

Todos os exemplos estão no Cookbook e são organizados por caso de uso.

Categoria	O que você vai construir
Primeiros passos	Primeiro agente, ferramentas, memória, eventos de telemetria e rastreamentos
Aplicações reais	Due diligence, operações de suporte e harnesses de revisão de código do workspace
Fluxos de trabalho	Agentes sequenciais, paralelos e roteadores
Agentes em segundo plano	Tarefas autônomas agendadas
Produção	Guardrails, serving e padrões de produção

Configuração

Variáveis de ambiente

Para a primeira execução, a maioria dos provedores de modelos hospedados só precisa de LLM_API_KEY. O OmniCoreAgent define memória e eventos como armazenamento em memória, arquivos do workspace em disco local, e integrações opcionais de produção permanecem desativadas até que você as configure.

export LLM_API_KEY=your_api_key

Adicione variáveis específicas de backend somente quando você optar por Redis, MongoDB, armazenamento de banco de dados SQL, S3, R2 ou configurações de implantação do OmniServe.

Exemplo completo de configuração do Harness

Os padrões mantêm o primeiro agente enxuto: arquivos do workspace e guardrails estão ativos, a memória de conversa é em memória, e componentes avançados do harness permanecem desativados até que você os habilite. Este exemplo mostra as opções de estilo de produção juntas.

agent_config = {
    "max_steps": 15,
    "tool_call_timeout": 30,
    "request_limit": 0,                  # 0 = unlimited
    "total_tokens_limit": 0,             # 0 = unlimited
    "memory_config": {
        "mode": "sliding_window",
        "value": 10000,
        "summary": {"enabled": False},
    },
    "enable_workspace_files": True,      # Default on
    "guardrail_mode": "full",            # Default
    "context_management": {"enabled": True},  # Default off
    "tool_offload": {"enabled": True},        # Default off
    "enable_advanced_tool_use": True,         # Default off
    "enable_subagents": True,                 # Default off
    "enable_agent_skills": True,              # Default off
}

Quando enable_subagents é verdadeiro, os arquivos do workspace são habilitados automaticamente para que subagentes gravem saídas, notas, tarefas e artefatos no workspace ativo.

Referência completa: Guia de Configuração

Desenvolvimento

git clone https://github.com/omnirexflora-labs/omnicoreagent.git
cd omnicoreagent

uv venv && source .venv/bin/activate
uv sync --dev

pytest tests/ -v
pytest tests/ --cov=src --cov-report=term-missing

Solução de problemas

Erro	Correção
`Invalid API key`	Exporte `LLM_API_KEY` com a chave do provedor selecionado em `model_config`.
`ModuleNotFoundError` para Redis / Postgres / MongoDB / S3	Instale o extra correspondente, por exemplo `pip install "omnicoreagent[redis]"`.
`Redis connection failed`	Inicie o Redis ou use `MemoryRouter("in_memory")`.
`MCP connection refused`	Garanta que o servidor MCP esteja em execução antes de iniciar o agente.

Mais ajuda: Guia de Uso Básico

Contribuindo

git clone https://github.com/omnirexflora-labs/omnicoreagent.git
cd omnicoreagent

uv venv && source .venv/bin/activate
uv sync --dev
pre-commit install

Consulte CONTRIBUTING.md para diretrizes. PRs são bem-vindos.

Licença

MIT - consulte LICENSE.

Autor

Construído por Abiola Adeshina.

GitHub: @Abiorh001
X (Twitter): @abiorhmangana
Email: abiolaadedayo1993@gmail.com

O Ecossistema OmniRexFlora

Projeto	Descrição
OmniMemory	Memória auto-evolutiva para agentes autônomos
OmniCoreAgent	Harness de agente de produção (este projeto)
OmniDaemon	Runtime orientado a eventos para executar agentes como serviços de infraestrutura autônomos e supervisionados

Construído com

LiteLLM - FastAPI - Redis - Pydantic

Dê uma estrela no GitHub - Reportar Bug - Solicitar Recurso - Documentação