​

🌐 OmniDaemon

​

Universal Event-Driven Runtime Engine for AI Agents

​

🌊 Why OmniDaemon Exists: The “Single Process” Trap

Most AI frameworks run everything in a single Python process. One crash kills your entire system.

​

The Problem

• ❌ One agent crashes? The entire process dies.
• ❌ Memory leak? Affects all agents in the process.
• ❌ No fault isolation Each agent shares the same memory space.

​

The OmniDaemon Solution: Process Isolation

• ✅ Fault Isolation: If Agent A crashes, Agent B keeps running.
• ✅ Auto-Recovery: Supervisors automatically restart crashed agents.
• ✅ Resource Safety: Clean memory/CPU boundaries per agent.
• ✅ Production-Ready: Run Python agents (LangGraph, CrewAI, AutoGen, custom) with process isolation.

👉 See the deep dive: OmniDaemon vs Other Frameworks

​

📚 Event-Driven Architectures: A Primer

​

⚠️ The Rise and Fall of Early Social Giants

​

🚀 The Future is Event-Driven Agents

​

🤝 Agents as Microservices with Informational Dependencies

​

🔓 Decoupling While Keeping Context Intact

​

⚡ Scaling Agents with Event-Driven Architecture

• Horizontal Scalability: Distributed design supports the addition of new agents or consumers without bottlenecks, ensuring the system grows effortlessly.
• Low Latency: Real-time event processing enables agents to respond instantly to changes, ensuring fast and reliable workflows.
• Loose Coupling: By communicating through topics rather than direct dependencies, agents remain independent and scalable.
• Event Persistence: Durable message storage guarantees that no data is lost in transit, which is critical for high-reliability workflows.

​

🎯 Event-Driven Agents Will Define the Future of AI

​

🎯 What is OmniDaemon?

“Kubernetes for AI Agents” - A universal runtime that makes AI agents autonomous, observable, and scalable.

​

In 5 Seconds

• 🤖 Run AI agents in the background (not chatbots, not APIs)
• 📨 Event-driven (agents react to events, not HTTP requests)
• 🔌 Use any AI framework (OmniCore Agent, Google ADK, LangChain, or custom)
• 🚀 Production-ready (retries, DLQ, metrics, scaling built-in)

​

🌊 Why Event-Driven AI? The Evolution Story

​

The AI Evolution: Three Waves

​

Wave 1: Predictive Models (Traditional ML)

Training Data → ML Model → Predictions for Specific Use Case

• ❌ Domain-specific and rigid
• ❌ Required ML expertise for each use case
• ❌ Difficult to repurpose
• ❌ Lacked scalability

​

Wave 2: Generative Models (LLMs)

Massive Dataset → LLM → Generate Text, Images, Code

• ❌ Fixed in time (no dynamic information)
• ❌ Expensive to fine-tune
• ❌ No access to private/domain data
• ❌ Generic responses without context

“Recommend an insurance policy tailored to my health history, location, and financial goals.”

1. Retrieve user’s health and financial data from database
2. Add data to context during prompt assembly
3. LLM generates accurate, personalized response

Database → Retrieve Context → LLM + Context → Accurate Response

​

Wave 3: Agentic AI (Current)

Event → Agent Reasons → Uses Tools → Adapts Workflow → Takes Action

• ✅ Dynamic workflows (figure out next steps on the fly)
• ✅ Context-driven (adapt to the situation)
• ✅ Autonomous (no pre-defined paths needed)
• ✅ Tool use (access external systems)
• ✅ Memory (learn from past interactions)

“Agents are the new apps.” — Dharmesh Shah, HubSpot CTO

“We’ve reached the upper limits of what LLMs can do. The future lies with autonomous agents.” — Marc Benioff, Salesforce CEO (The Wall Street Journal, “Future of Everything” podcast)

​

🏗️ Why Agents Need Event-Driven Architecture

​

The Infrastructure Problem

• 📊 Access to data from multiple sources
• 🔧 Ability to use tools and external systems
• 🤝 Communication with other agents
• 🌐 Outputs available to multiple services
• ⚡ Real-time responsiveness
• 📈 Horizontal scalability

​

The Tight Coupling Problem

❌ Tightly Coupled Architecture
┌─────────┐     ┌─────────┐     ┌─────────┐
│ Agent 1 │────▶│ Agent 2 │────▶│ Agent 3 │
└─────────┘     └─────────┘     └─────────┘
     │               │               │
     ▼               ▼               ▼
  [Fails] ───────▶ [Fails] ─────▶ [Fails]

Problems:
• If one agent fails, entire chain breaks
• Hard to scale individual agents
• Changes ripple through system
• Difficult to add new agents
• Can't support multiple consumers

​

The Event-Driven Solution

✅ Event-Driven Architecture
        ┌──────────────────┐
        │   Event Bus      │
        │ (Redis Streams)  │
        └──────────────────┘
         ↑      ↑      ↑
         │      │      │
    ┌────┴──┐ ┌┴────┐ ┌┴────┐
    │Agent 1│ │Agent│ │Agent│
    │       │ │  2  │ │  3  │
    └───────┘ └─────┘ └─────┘

Benefits:
✅ Agents don't depend on each other
✅ Scale agents independently
✅ Add/remove agents dynamically
✅ Multiple consumers per event
✅ Automatic retries & DLQ
✅ Message persistence

​

Agents as Microservices

• Autonomous - Operate independently
• Decoupled - Don’t depend on each other
• Scalable - Add more instances for load

• Context-rich - Need shared information to reason
• Tool-enabled - Interact with external systems
• Collaborative - Share insights with other agents
• Adaptive - Modify behavior based on events

​

🚀 What OmniDaemon Provides

​

Traditional AI (Request-Driven)

User asks → AI responds → Done ❌

​

OmniDaemon (Event-Driven)

Event happens → AI agent reacts → Result stored ✅
              → Multiple agents listen
              → Automatic retries
              → DLQ for failures

​

Core Features

​

Pluggable Architecture

# Event Bus - Switch backends with NO code changes
EVENT_BUS_TYPE=redis_stream + REDIS_URL=...         # Current
EVENT_BUS_TYPE=rabbitmq + RABBITMQ_URL=...          # Coming soon
EVENT_BUS_TYPE=kafka + KAFKA_SERVERS=...            # Coming soon

# Storage - Switch backends with NO code changes
STORAGE_BACKEND=json + JSON_STORAGE_DIR=...         # Development
STORAGE_BACKEND=redis + REDIS_URL=...               # Production
STORAGE_BACKEND=postgresql + POSTGRES_URL=...       # Coming soon
STORAGE_BACKEND=mongodb + MONGODB_URI=...           # Coming soon

​

🎯 When to Use OmniDaemon

​

✅ Perfect For

• Background AI Agents Autonomous agents reacting to events, triggers, or system signals.
• Event-Driven Workflows Multi-step pipelines coordinated through events.
• Distributed Multi-Agent Systems Sub-agents running across different servers, runtimes, or toolsets.
• Async & Long-Running AI Tasks Workloads that shouldn’t block a client request (analysis, ingestion, evaluation).
• Enterprise AI Ops Durable, observable, scalable systems with retries, logs, and monitoring baked in.
• Hybrid Real-Time + Background Work Use SSE/WebSockets for live streaming, while OmniDaemon handles internal agent events and orchestration.

​

❌ Overkill For (Simpler Alternatives Exist)

• Simple HTTP APIs — FastAPI/Flask are more straightforward.
• Pure Real-Time Chat Only — WebSockets/SSE alone give lower direct latency.
• Strict Synchronous Request→Response — REST/RPC is simpler when no async logic is involved.
• Single-Shot Scripts — A basic Python script is sufficient.

​

🆚 Compared to Alternatives

​

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         OmniDaemon                              │
│                   Universal Runtime Engine                       │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
        ▼                     ▼                     ▼
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│  Event Bus   │    │   Storage    │    │ Agent Runner │
│ (Pluggable!) │    │ (Pluggable!) │    │  (Your Code) │
├──────────────┤    ├──────────────┤    ├──────────────┤
│ • Streams    │    │ • Agents     │    │ • Register   │
│ • Pub/Sub    │    │ • Results    │    │ • Subscribe  │
│ • DLQ        │    │ • Metrics    │    │ • Process    │
│ • Groups     │    │ • Config     │    │ • Respond    │
│              │    │              │    │              │
│ Redis ✅     │    │ Redis ✅     │    │              │
│ Kafka 🚧     │    │ JSON ✅      │    │              │
│ RabbitMQ 🚧  │    │ Postgres 🚧  │    │              │
│ NATS 🚧      │    │ MongoDB 🚧   │    │              │
└──────────────┘    └──────────────┘    └──────────────┘
        │                     │                     │
        │                     │                     │
        └─────────────────────┴─────────────────────┘
                              │
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
        ▼                     ▼                     ▼
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│     CLI      │    │     API      │    │     SDK      │
│   (Typer)    │    │  (FastAPI)   │    │  (Python)    │
├──────────────┤    ├──────────────┤    ├──────────────┤
│ • Commands   │    │ • REST       │    │ • Register   │
│ • Rich UI    │    │ • Endpoints  │    │ • Publish    │
│ • Monitoring │    │ • Webhooks   │    │ • Query      │
└──────────────┘    └──────────────┘    └──────────────┘

​

Key Components

1. Event Bus (Pluggable) - Message broker for event distribution
   • Currently: Redis Streams
   • Coming: Kafka, RabbitMQ, NATS
2. Storage (Pluggable) - Persistent layer for agents, results, metrics
   • Currently: Redis, JSON
   • Coming: PostgreSQL, MongoDB, S3
3. Agent Runner - Orchestrates agent execution and lifecycle
4. CLI - Beautiful command-line interface (powered by Rich)
5. API - RESTful HTTP API (powered by FastAPI)
6. SDK - Python SDK for agent integration

​

🏭 Production Mode: Agent Supervisors

Refactoring from “Simple Mode” to “Production Mode” is easy.

​

When to use Supervisors?

• Simple Mode (sdk.register_agent): Great for lightweight tasks, development, and simple logic. Runs in the main process.
• Supervisor Mode (create_supervisor_from_directory): REQUIRED for production AI agents. Runs in a separate process with auto-restart, crash protection, and full isolation.

​

How to implement

1. Structure your agent:
   my_agent/
   ├── __init__.py
   ├── agent.py       # Your AI agent class/logic
   └── requirements.txt
   
2. Use the Supervisor in agent_runner.py:
   from omnidaemon.supervisor import create_supervisor_from_directory
   
   # Create a supervisor that manages the agent process
   supervisor = await create_supervisor_from_directory(
       agent_name="my_robust_agent",
       agent_dir="./my_agent",                 # Directory containing code
       callback_function="my_agent.callback",  # Function to call inside that dir
       watch_paths=["./my_agent"]              # Auto-reload on code change!
   )
   
   # Register the supervisor to handle events
   await sdk.register_agent(
       agent_config=AgentConfig(topic="my.topic"),
       callback=supervisor.handle_event        # Supervisor handles the event!
   )
   

📚 See full examples:

• examples/agents_with_supervisors
• examples/google_adk_with_supervisor

​

🚀 Quick Start

# 1. Install Redis (event bus backend)
docker run -d -p 6379:6379 --name redis redis:latest

# 2. Install OmniDaemon
uv add omnidaemon
# Or: pip install omnidaemon

# 3. Create agent directory
mkdir my_first_agent

# my_first_agent/agent.py
def greeter_callback(message: dict):
    """Your agent runs here - in an isolated process!"""
    name = message.get("content", {}).get("name", "stranger")
    return {"reply": f"Hello, {name}! 👋"}

touch my_first_agent/__init__.py

# agent_runner.py - Production-ready with Supervisor
import asyncio
from omnidaemon import OmniDaemonSDK, AgentConfig
from omnidaemon.supervisor import create_supervisor_from_directory

sdk = OmniDaemonSDK()

async def main():
    # Create supervisor (runs agent in separate process)
    supervisor = await create_supervisor_from_directory(
        agent_name="greeter",
        agent_dir="./my_first_agent",
        callback_function="agent.greeter_callback"
    )
    
    await sdk.register_agent(
        agent_config=AgentConfig(topic="greet.user"),
        callback=supervisor.handle_event
    )
    
    await sdk.start()
    print("🎧 Agent running. Press Ctrl+C to stop.")
    
    try:
        while True:
            await asyncio.sleep(1)
    except KeyboardInterrupt:
        await sdk.shutdown()

if __name__ == "__main__":
    asyncio.run(main())

python agent_runner.py

​

📚 What’s Next?

​

For New Users

1. Getting Started - Understand core concepts
2. Quick Start Tutorial - Build your first agent in 10 minutes
3. Complete Examples - Real-world agent implementations

​

For Developers

4. How-To Guides - Solve specific problems
5. Common Patterns - Production-ready recipes
6. API Reference - Complete SDK documentation

​

For Architects

7. Architecture & Design - Deep dive into system design
8. Enterprise - Use cases and deployment guide

​

🌟 Learn More

• Read the README - Comprehensive overview
• Explore Examples - Working code
• Join Community - Get help and contribute

​

📖 References

​

👨‍💻 About