MCP Connect Client CLI

<p align="center">

</p>

<h1 align="center">OmniCoreAgent</h1>

<p align="center">
<strong>The Open Production Agent Harness for Python</strong><br />
<em>Parallel tool batches, structured observations, signature loop detection, MCP tools, memory, workspace files, subagents, background tasks, and REST/SSE serving.</em>
</p>

<p align="center">
<a href="https://pepy.tech/projects/omnicoreagent"></a>
<a href="https://badge.fury.io/py/omnicoreagent"></a>
<a href="https://www.python.org/downloads/"></a>
<a href="LICENSE"></a>
</p>

<p align="center">
<a href="#what-it-is">What It Is</a> -
<a href="#quick-start">Quick Start</a> -
<a href="#choose-your-path">Choose Your Path</a> -
<a href="#what-you-can-build">Use Cases</a> -
<a href="#why-it-matters">Why It Matters</a> -
<a href="#install-only-what-you-need">Install</a> -
<a href="./cookbook">Cookbook</a> -
<a href="#features">Features</a> -
<a href="https://docs-omnicoreagent.omnirexfloralabs.com/docs">Docs</a> -
<a href="https://docs-omnicoreagent.omnirexfloralabs.com/docs/getting-started/use-docs-with-ai-tools">Ask AI</a>
</p>

---

What It Is

An LLM is not an agent by itself. The model provides intelligence; the harness
gives that intelligence a working environment.

OmniCoreAgent is the application-facing harness layer around a model:

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

That is the difference between an agent harness and a generic agent library.
A library gives you pieces to assemble. A harness gives you the runtime boundary
that makes a model usable inside an application.

OmniCoreAgent keeps that boundary explicit:

| Layer | What It Owns |
|-------|--------------|
| Agent harness | Model loop, prompt contract, tools, observations, memory, context, workspace, guardrails, events, subagents |
| Serving boundary | OmniServe REST/SSE APIs, request lifecycle, readiness, auth, rate limits, metrics |
| Background boundary | Durable scheduled/manual task execution with task state, run history, leases, retries, and workspace output |
| External tool boundary | MCP server tools and local Python tools exposed through one runtime surface |

Start with the core harness. Turn on heavier production pieces only when the
workload needs them.

If you prefer guided docs, start with the
Quick Start.
If you use AI coding tools, use the
AI tools guide
for Ask AI, /llms.txt, hosted docs MCP, Cursor, VS Code, ChatGPT, Claude, and
Perplexity.

---

Quick Start

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())

That is the smallest path: one agent, one model, one stable session, the harness
loop, session memory, guardrails, workspace files, error handling, and metrics
around each run.

Context management, tool output offloading, BM25 tool retrieval, subagents, skills,
cloud workspace storage, and production backends are opt-in so a small agent stays
small.

> Ready to go deeper? The Cookbook has progressive examples from
> hello world to production deployments.

---

Choose Your Path

| Goal | Start Here |
|------|------------|
| Build your first agent | Quick Start |
| Add Python tools | Local tools cookbook |
| Connect MCP server tools | MCP tools cookbook |
| Manage memory and context | Getting started cookbook |
| Save files, artifacts, and large tool results | Tool offload cookbook |
| Build a production-shaped app harness | Real applications cookbook |
| Build multi-step workflows | Workflows cookbook |
| Serve an agent over HTTP/SSE | OmniServe cookbook |
| Use the docs inside AI tools | AI tools guide |
| Debug setup or configuration | Configuration guide |
| Understand the runtime internals | Implementation Map |

---

What You Can Build

OmniCoreAgent is for application builders who need the agent runtime to hold
together after the prototype works.

| Build | Harness Pieces You Use |
|-------|------------------------|
| MCP-connected product agents | MCP tools, local tools, structured observations, guardrails, session memory |
| Research and analysis agents | Parallel tool batches, workspace files, tool offloading, context management, artifact readback |
| Long-running worker agents | Background tasks, durable task stores, run history, workspace output, retries, cancellation |
| Multi-agent task systems | Dynamic subagents, shared workspace output, workflow orchestration, telemetry events |
| Agent APIs | OmniServe REST/SSE, readiness, auth, request timeout, rate limits, metrics |
| Production app integrations | Optional Redis, MongoDB, SQL, S3, and R2 backends without making the core install heavy |

The core idea is simple: one harness entry point, many application membranes.
You bring the domain instructions, tools, and business logic. OmniCoreAgent
provides the execution boundary around them.

---

Why It Matters

Most demos stop at "LLM plus tool loop." Production agents fail in the layer
around that loop: slow sequential tool calls, noisy observations, repeated
actions, context exhaustion, unsafe tool output, missing workspace state,
uninspectable background work, and weak serving boundaries.

OmniCoreAgent exists for that layer.

1. Agents call tools in batches instead of forced sequences

The usual tool loop looks like this:

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

OmniCoreAgent lets the model request independent tools together:

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

The model gets one complete view of the batch before it reasons again. A failed
tool is represented beside the successful tools instead of silently collapsing the
whole step.

Native function calling alone is not the runtime. OmniCoreAgent uses its own
tool-call contract, parser, resolver, parallel runner, and result formatter so
the harness controls the full execution path.

2. Tool results become structured observations

Raw tool output is often too noisy for the next reasoning step. Large payloads,
errors, irrelevant fields, and prompt-injection content can all distort the loop.

…