🚀 OmniCoreAgent

The Open Agent Harness Built for Production
Run autonomous agents with tools, memory, context management, guardrails, and deployment paths.

Quick Start • See It In Action • 📚 Cookbook • Features • Docs

---

🎬 See It In Action

import asyncio
from omnicoreagent import OmniCoreAgent, MemoryRouter, ToolRegistry

# Create tools in seconds
tools = ToolRegistry()

@tools.register_tool("get_weather")
def get_weather(city: str) -> dict:
    """Get current weather for a city."""
    return {"city": city, "temp": "22°C", "condition": "Sunny"}

# Build a production-ready agent
agent = OmniCoreAgent(
    name="assistant",
    system_instruction="You are a helpful assistant with access to weather data.",
    model_config={"provider": "openai", "model": "gpt-4o"},
    local_tools=tools,
    memory_router=MemoryRouter("in_memory"),
    agent_config={
        "context_management": {"enabled": True},  # Auto-manage long conversations
        "guardrail_config": {"strict_mode": True},  # Block prompt injections
        "enable_subagents": True,  # Optional dynamic worker spawning
    }
)

async def main():
    # Run the agent
    result = await agent.run("What's the weather in Tokyo?")
    print(result["response"])
    
    # Production memory stores such as Redis, MongoDB, and Postgres are optional extras.
    # Install only the memory store you use, then switch at runtime when configured.

asyncio.run(main())

What just happened?

• ✅ Registered a custom tool with type hints
• ✅ Built an agent with memory
• ✅ Enabled automatic context management
• ✅ Kept production backends optional until you need them

---

⚡ Quick Start

pip install omnicoreagent

Install production extras only when you need them:

pip install "omnicoreagent[redis]"       # Redis memory and event streams
pip install "omnicoreagent[postgres]"    # PostgreSQL / SQL memory
pip install "omnicoreagent[mongodb]"     # MongoDB memory
pip install "omnicoreagent[s3]"          # S3 / R2 workspace files
pip install "omnicoreagent[serve]"       # OmniServe REST/SSE API server
pip install "omnicoreagent[all]"         # Everything

echo "LLM_API_KEY=your_api_key" > .env

from omnicoreagent import OmniCoreAgent

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

result = await agent.run("Hello!")
print(result["response"])

That's it. You have an AI agent with session management, memory, and error handling.

📚 Want to learn more? Check out the Cookbook — progressive examples from "Hello World" to production deployments.

---

🎯 What Makes OmniCoreAgent Different?

Feature	What It Means For You
Agent Harness Runtime	Tool loop, memory, context management, guardrails, skills, sub-agents, and serving in one open package
Runtime Backend Switching	Switch Redis ↔ MongoDB ↔ PostgreSQL without restarting
Cloud Workspace Storage	Agent files persist in AWS S3 or Cloudflare R2 ⚡ NEW
Context Engineering	Session memory + agent loop context + tool offloading = no token exhaustion
Tool Response Offloading	Large tool outputs saved to files, 98% token savings
Built-in Guardrails	Prompt injection protection out of the box
MCP Native	Connect to any MCP server (stdio, SSE, HTTP with OAuth)
Background Agents	Schedule autonomous tasks that run on intervals
Workflow Orchestration	Sequential, Parallel, and Router agents for complex tasks
Runtime Visibility	Metrics, event streams, and compact in-house trace summaries

---

🎯 Core Features

📖 Full documentation: docs-omnicoreagent.omnirexfloralabs.com/docs

#	Feature	Description	Docs
1	OmniCoreAgent	The heart of the framework — production agent with all features	Overview →
2	Multi-Tier Memory	5 backends (Redis, MongoDB, PostgreSQL, SQLite, in-memory) with runtime switching	Memory →
3	Context Engineering	Dual-layer system: agent loop context management + tool response offloading	Context →
4	Event System	Real-time event streaming with runtime switching	Events →
5	MCP Tools	Connect external MCP tool servers (stdio, streamable_http, SSE) with OAuth	MCP →
6	Dynamic Subagents	Spawn one or many focused workers from OmniCoreAgent with workspace files	Sub-Agents →
7	Local Tools	Register any Python function as an AI tool via ToolRegistry	Local Tools →
8	Agent Skills	Polyglot packaged capabilities (Python, Bash, Node.js)	Skills →
9	Workspace Files	Agent-managed files and tool artifacts on local, S3, or R2 workspaces	Workspace →
10	Harness Defaults	Subagents, workspace files, context management, and tool offloading inside OmniCoreAgent	Sub-Agents →
11	Background Agents	Schedule autonomous tasks on intervals	Background →
12	Workflows	Sequential, Parallel, and Router agent orchestration	Workflows →
13	BM25 Tool Retrieval	Auto-discover relevant tools from 1000+ using BM25 search	Advanced Tools →
14	Guardrails	Prompt injection protection with configurable sensitivity	Guardrails →
15	Runtime Visibility	Per-request metrics, event streams, and compact in-house trace summaries	Observability →
16	Universal Models	9 providers via LiteLLM (OpenAI, Anthropic, Gemini, Groq, Ollama, etc.)	Models →
17	OmniServe	Turn any agent into a production REST/SSE API with one command	OmniServe →

---

📚 Examples & Cookbook

All examples are in the Cookbook — organized by use case with progressive learning paths.

Category	What You'll Build	Location
Getting Started	Your first agent, tools, memory, events	cookbook/getting_started
Workflows	Sequential, Parallel, Router agents	cookbook/workflows
Background Agents	Scheduled autonomous tasks	cookbook/background_agents
Production	Metrics and guardrails	cookbook/production

---

⚙️ Configuration

Environment Variables

# Required
LLM_API_KEY=your_api_key

# Optional: workspace backend for artifacts and workspace files
OMNICOREAGENT_WORKSPACE_BACKEND=local  # local, s3, or r2
OMNICOREAGENT_WORKSPACE_DIR=.omnicoreagent/workspace
AWS_S3_BUCKET=your-s3-bucket           # when workspace backend=s3
R2_BUCKET_NAME=your-r2-bucket          # when workspace backend=r2

Agent Configuration

agent_config = {
    "max_steps": 15,                    # Max reasoning steps
    "tool_call_timeout": 30,            # Tool timeout (seconds)
    "request_limit": 0,                 # 0 = unlimited
    "total_tokens_limit": 0,            # 0 = unlimited
    "memory_config": {"mode": "sliding_window", "value": 10000},
    "enable_advanced_tool_use": True,   # BM25 tool retrieval
    "enable_subagents": True,           # Dynamic focused workers
    "enable_agent_skills": True,        # Specialized packaged skills
    "enable_workspace_files": True,    # Default: workspace files for notes/logs/scratchpads
    "context_management": {"enabled": True},
    "tool_offload": {"enabled": True}
}

📖 Full configuration reference: Configuration Guide →

---

🧪 Testing & Development

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

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

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

---

🔍 Troubleshooting

Error	Fix
Invalid API key	Check .env: LLM_API_KEY=your_key
ModuleNotFoundError for Redis/Postgres/Mongo/S3/OmniServe	Install the matching extra, e.g. pip install "omnicoreagent[redis]"
Redis connection failed	Start Redis or use MemoryRouter("in_memory")
MCP connection refused	Ensure MCP server is running

📖 More troubleshooting: Basic Usage Guide →

---

📝 Changelog

See the full Changelog → for version history.

---

🤝 Contributing

# Fork & clone
git clone https://github.com/omnirexflora-labs/omnicoreagent.git

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

# Submit PR

See CONTRIBUTING.md for guidelines.

---

📄 License

MIT License — see LICENSE

---

👨‍💻 Author & Credits

Created by Abiola Adeshina

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

🌟 The OmniRexFlora Ecosystem

Project	Description
🧠 OmniMemory	Self-evolving memory for autonomous agents
🤖 OmniCoreAgent	Production-ready AI agent framework (this project)

🙏 Acknowledgments

Built on: LiteLLM, FastAPI, Redis, Pydantic, APScheduler

---

Building the future of production-ready AI agent frameworks

⭐ Star us on GitHub • 🐛 Report Bug • 💡 Request Feature • 📖 Documentation