🚀 OmniCoreAgent

The AI Agent Framework Built for Production
Switch memory backends at runtime. Manage context automatically. Deploy with confidence.

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("redis"),  # Start with Redis
    agent_config={
        "context_management": {"enabled": True},  # Auto-manage long conversations
        "guardrail_config": {"strict_mode": True},  # Block prompt injections
    }
)

async def main():
    # Run the agent
    result = await agent.run("What's the weather in Tokyo?")
    print(result["response"])
    
    # Switch to MongoDB at runtime — no restart needed
    await agent.switch_memory_store("mongodb")
    
    # Keep running with a different backend
    result = await agent.run("How about Paris?")
    print(result["response"])

asyncio.run(main())

What just happened?

• ✅ Registered a custom tool with type hints
• ✅ Built an agent with memory persistence
• ✅ Enabled automatic context management
• ✅ Switched from Redis to MongoDB while running

---

⚡ Quick Start

pip install omnicoreagent

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
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
Production Observability	Metrics, tracing, and event streaming built in

---

🎯 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 Client	Connect to any MCP server (stdio, streamable_http, SSE) with OAuth	MCP →
6	DeepAgent	Multi-agent orchestration with automatic task decomposition	DeepAgent →
7	Local Tools	Register any Python function as an AI tool via ToolRegistry	Local Tools →
8	Community Tools	100+ pre-built tools (search, AI, comms, databases, DevOps, finance)	Community Tools →
9	Agent Skills	Polyglot packaged capabilities (Python, Bash, Node.js)	Skills →
10	Workspace Memory	Persistent file storage with S3/R2/Local backends	Workspace →
11	Sub-Agents	Delegate tasks to specialized agents	Sub-Agents →
12	Background Agents	Schedule autonomous tasks on intervals	Background →
13	Workflows	Sequential, Parallel, and Router agent orchestration	Workflows →
14	BM25 Tool Retrieval	Auto-discover relevant tools from 1000+ using BM25 search	Advanced Tools →
15	Guardrails	Prompt injection protection with configurable sensitivity	Guardrails →
16	Observability	Per-request metrics + Opik distributed tracing	Observability →
17	Universal Models	9 providers via LiteLLM (OpenAI, Anthropic, Gemini, Groq, Ollama, etc.)	Models →
18	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, guardrails, observability	cookbook/production
🏆 Showcase	Full production applications	cookbook/showcase

🏆 Showcase: Full Production Applications

Application	Description	Features
OmniAudit	Healthcare Claims Audit System	Multi-agent pipeline, ERISA compliance
DevOps Copilot	AI-Powered DevOps Automation	Docker, Prometheus, Grafana
Deep Code Agent	Code Analysis with Sandbox	Sandbox execution, session management

---

⚙️ Configuration

Environment Variables

# Required
LLM_API_KEY=your_api_key

# Optional: Memory backends
REDIS_URL=redis://localhost:6379/0
DATABASE_URL=postgresql://user:pass@localhost:5432/db
MONGODB_URI=mongodb://localhost:27017/omnicoreagent

# Optional: Observability
OPIK_API_KEY=your_opik_key
OPIK_WORKSPACE=your_workspace

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_agent_skills": True,        # Specialized packaged skills
    "memory_tool_backend": "local"      # Persistent working memory
}

📖 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	pip install omnicoreagent
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: [email protected]

🌟 The OmniRexFlora Ecosystem

Project	Description
🧠 OmniMemory	Self-evolving memory for autonomous agents
🤖 OmniCoreAgent	Production-ready AI agent framework (this project)
⚡ OmniDaemon	Event-driven runtime engine for AI agents

🙏 Acknowledgments

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

---

Building the future of production-ready AI agent frameworks

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