# Cookbook Source: https://docs-omnicoreagent.omnirexfloralabs.com/cookbook/README Runnable OmniCoreAgent examples for first agents, tools, memory, workspace files, background tasks, OmniServe, and real applications # OmniCoreAgent Cookbook Copy, paste, run. These examples show how to build with OmniCoreAgent from the first local agent through production-shaped application harnesses. ## ๐Ÿš€ Where to Start **New to OmniCoreAgent?** Start with [getting\_started](./getting_started) โ€” progressive examples from "Hello World" to production deployments. **Know what you're building?** Find your use case below. **Just want to see it work?** ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} 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"]) ``` *** ## ๐Ÿ“š Build by Use Case ### ๐Ÿค– I want to build my first agent โ†’ **[getting\_started](./getting_started)** โ€” Basic agents, tools, memory, events, and configuration. ### ๐Ÿ› ๏ธ I want to use custom tools โ†’ **[getting\_started/agent\_with\_local\_tools.py](./getting_started/agent_with_local_tools.py)** โ€” Register Python functions as tools. ### ๐Ÿ”Œ I want to connect MCP servers โ†’ **[getting\_started/agent\_with\_mcp\_tools.py](./getting_started/agent_with_mcp_tools.py)** โ€” Connect to external MCP servers. ### ๐Ÿ‘ฅ I want agents working together โ†’ **[workflows](./workflows)** โ€” Sequential, Parallel, and Router agents. ### ๐Ÿš I want agents running autonomously โ†’ **[background\_agents](./background_agents)** โ€” Scheduled tasks and queue-based execution. ### ๐Ÿง  I want complex multi-step workflows โ†’ **[getting\_started/agent\_with\_sub\_agents.py](./getting_started/agent_with_sub_agents.py)** โ€” OmniCoreAgent dynamic subagents, workspace files, and orchestration. ### ๐Ÿญ I want to build a real application โ†’ **[real\_applications](./real_applications)** โ€” Production-shaped app harness examples that show domain tools, workspace files, offloading, telemetry, guardrails, and workspace command tools across different apps. ### ๐Ÿงช I want more domain demos โ†’ **[advanced\_agent](./advanced_agent)** โ€” E-commerce, flight booking, customer support, due diligence. ### ๐ŸŒ I want to deploy as an API โ†’ **[omniserve](./omniserve)** โ€” Deploy agents as REST/SSE APIs with one command. ### ๐Ÿš€ I want to run in production โ†’ **[production](./production)** โ€” Metrics and guardrails. *** ## ๐Ÿ“‚ Directory Structure ``` cookbook/ โ”œโ”€โ”€ getting_started/ # Start here! Progressive learning path โ”œโ”€โ”€ workflows/ # Multi-agent orchestration patterns โ”œโ”€โ”€ background_agents/ # Scheduled and autonomous agents โ”œโ”€โ”€ omniserve/ # ๐Ÿ†• Deploy agents as REST/SSE APIs โ”œโ”€โ”€ real_applications/ # End-to-end application harness examples โ”œโ”€โ”€ advanced_agent/ # Real-world application examples โ””โ”€โ”€ production/ # Production-ready configurations ``` *** ## ๐ŸŽฏ Featured Examples | Example | What You'll Build | | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | [Research Due Diligence](./real_applications/research_due_diligence_agent.py) | Research agent with parallel tools, workspace reports, artifact readback, telemetry | | [Support Operations](./real_applications/support_operations_agent.py) | Support agent with customer/order tools, guardrails, escalation, workspace notes | | [Workspace Code Review](./real_applications/workspace_code_review_agent.py) | Code review agent using built-in workspace file commands instead of unrestricted shell | | [Support Background Task](./background_agents/real_application_background_task.py) | Real support operations app running through durable background task state, events, attempts, and workspace output | | [E-commerce Shopper](./advanced_agent/e_commerce_personal_shopper_agent.py) | Personal shopping assistant with cart, preferences, recommendations | | [Flight Booking](./advanced_agent/flightBooking_agent.py) | Travel agent with search, booking, and itinerary management | | [Customer Support](./advanced_agent/real_time_customer_support_agent.py) | Support agent with ticket handling and escalation | | [Due Diligence](./advanced_agent/ai_due_diligence_agent/) | Investment research with web search, analysis, and reporting | *** ## ๐Ÿค Contributing Want to add a cookbook example? See [CONTRIBUTING.mdx](./CONTRIBUTING.mdx) for guidelines. # Advanced Agent Examples Source: https://docs-omnicoreagent.omnirexfloralabs.com/cookbook/advanced_agent/README Larger OmniCoreAgent application examples for shopping, travel, customer support, and due diligence workflows # Advanced Agent Examples > Real-world applications that demonstrate the full power of OmniCoreAgent. These are not simple demos โ€” they're **production-ready patterns** you can adapt for your own projects. *** ## ๐ŸŽฏ Examples | Application | Description | Lines of Code | | --------------------------------------------------------------------- | -------------------------------------------------------------- | ------------- | | [E-commerce Personal Shopper](./e_commerce_personal_shopper_agent.py) | Shopping assistant with cart, preferences, and recommendations | \~700 | | [Flight Booking Agent](./flightBooking_agent.py) | Travel agent with search, booking, and itinerary management | \~300 | | [Customer Support Agent](./real_time_customer_support_agent.py) | Support agent with ticket handling and escalation | \~600 | | [AI Due Diligence](./ai_due_diligence_agent/) | Investment research with web search, analysis, and reporting | \~1000+ | *** ## ๐Ÿ›๏ธ E-commerce Personal Shopper A full-featured shopping assistant with: * Product search across catalogs * Shopping cart management * User preference learning * Personalized recommendations * Price comparison * Shipping calculations **Key Patterns**: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} @tools.register_tool("search_products") def search_products(query: str, category: str = "all") -> str: """Search products with filters.""" ... @tools.register_tool("add_to_cart") def add_to_cart(session_id: str, product_id: str, quantity: int = 1) -> str: """Add items to shopping cart.""" ... ``` *** ## โœˆ๏ธ Flight Booking Agent A conversational travel agent with: * Flight search * Booking management * Itinerary creation * Price alerts *** ## ๐Ÿ“ž Customer Support Agent A support agent that handles: * Ticket creation and tracking * Knowledge base queries * Escalation to human agents * Sentiment analysis *** ## ๐Ÿ“Š AI Due Diligence Agent A complete investment research pipeline: * Web research with search tools * Company analysis * Report generation * Multi-agent workflow See the [full documentation](./ai_due_diligence_agent/README.mdx) for details. *** ## ๐Ÿ”ง Common Patterns in These Examples ### 1. Tool Registration ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} tools = ToolRegistry() @tools.register_tool("tool_name") def my_tool(param: str) -> dict: """Description for the LLM.""" return {"status": "success", "data": ...} ``` ### 2. Session Management ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def handle_request(user_id: str, message: str): result = await agent.run(message, session_id=user_id) return result["response"] ``` ### 3. Production Configuration ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} agent = OmniCoreAgent( name="production_agent", agent_config={ "max_steps": 15, "context_management": {"enabled": True}, "guardrail_config": { "strict_mode": True, "sensitivity": 1.2, }, "memory_config": { "summary": {"enabled": True} }, }, ) ``` *** **Previous**: [Workflows](../workflows) โ€” Multi-agent orchestration # Background Agents Cookbook Source: https://docs-omnicoreagent.omnirexfloralabs.com/cookbook/background_agents/README Runnable examples for durable scheduled and manual background agent tasks, run state, events, retries, and workspace output # Background Agents: Durable Agent Tasks Background Agents run OmniCoreAgent work outside the foreground request path. They are durable tracked tasks with schedules, retries, cancellation, leases, workspace output, and inspectable lifecycle events. Use the default in-memory store for local development, or `sql`, `redis`, or `mongodb` when runs must survive restarts. ## Key Concepts * **BackgroundAgentManager**: Registers agents, tasks, runs, and lifecycle operations. * **Task store**: Operational state for agents, tasks, schedule state, runs, attempts, leases, retries, and cancellation flags. It defaults to in-memory and is separate from conversation memory. * **Run**: One concrete execution of a task. Runs have stable IDs, statuses, attempts, workspace paths, and event history. * **Worker lifecycle**: A worker claims queued runs with leases, heartbeats while work is active, and recovers expired leases. * **Workspace output**: Every background run gets a workspace namespace for lifecycle files and agent output. You can run the background manager without storage configuration. Use `BackgroundAgentManager()` for the default zero-config in-memory task store. Use `task_store="sql"`, `task_store="redis"`, or `task_store="mongodb"` when task state must survive process restarts. The task store is not conversation memory; it is the control plane for background work. Redis and MongoDB task stores use optional backend drivers: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} pip install "omnicoreagent[redis]" pip install "omnicoreagent[mongodb]" ``` ## Quick Start ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} import asyncio from omnicoreagent import BackgroundAgentManager, OmniCoreAgent async def main(): agent = OmniCoreAgent( name="system_monitor", system_instruction="Check system health and write concise reports.", model_config={"provider": "openai", "model": "gpt-5.4-mini"}, ) manager = BackgroundAgentManager() try: await manager.register_agent(agent_id="system_monitor", agent=agent) await manager.register_task( task_id="health_report", agent_id="system_monitor", query="Check system health and summarize anything that needs attention.", schedule={"type": "manual"}, timeout_seconds=60, retry_policy={"max_retries": 1, "initial_delay_seconds": 0}, ) run = await manager.run_now("health_report", wait=True) print(run.status) print(run.result_preview) finally: await manager.shutdown() asyncio.run(main()) ``` ## Durable Task Stores The default task store is in-memory. It needs no database and is right for local development, tests, and single-process experiments: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} manager = BackgroundAgentManager() ``` Use a durable task store when background runs must survive process restarts: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} manager = BackgroundAgentManager(task_store="sql") manager = BackgroundAgentManager( task_store={"backend": "redis", "url": "redis://localhost:6379/0"} ) manager = BackgroundAgentManager( task_store={ "backend": "mongodb", "uri": "mongodb://localhost:27017", "database": "omnicoreagent", } ) ``` Redis durable deployments need persistence enabled and a no-eviction policy for task-store keys. MongoDB task-store writes use majority write concern. Choose one durable backend per deployment. Use SQL/SQLite for local durability or simple single-node services. Use Redis when your deployment already operates Redis with persistence and no eviction for task-store keys. Use MongoDB when MongoDB is your durable operational store. Durable stores preserve queued runs across manager restarts. You can queue a manual run, stop the process, construct a new manager with the same task store, and complete the queued run from that new manager. The in-memory store does not provide that guarantee. OmniServe uses the same task-store settings through environment variables. Pick one backend: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} export OMNICOREAGENT_BACKGROUND_TASK_STORE=sql export OMNICOREAGENT_BACKGROUND_TASK_STORE_URL=sqlite:///.omnicoreagent/background.db ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} export OMNICOREAGENT_BACKGROUND_TASK_STORE=redis export OMNICOREAGENT_BACKGROUND_TASK_STORE_URL=redis://localhost:6379/0 ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} export OMNICOREAGENT_BACKGROUND_TASK_STORE=mongodb export OMNICOREAGENT_BACKGROUND_TASK_STORE_URI=mongodb://localhost:27017 export OMNICOREAGENT_BACKGROUND_TASK_STORE_DATABASE=omnicoreagent ``` ## Scheduled Runs Manual tasks run only when you call `run_now`. Scheduled tasks are dispatched by the manager worker after `start()` is called: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} await manager.register_task( task_id="hourly_report", agent_id="system_monitor", query="Write the hourly operational report.", schedule={"type": "interval", "seconds": 3600}, overlap_policy="queue_next", ) await manager.start() ``` `start()` creates the manager worker and returns immediately. Keep the process alive while scheduled work should continue, and use `shutdown()` when the process exits so worker loops and active background resources close cleanly: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} try: await manager.start() await asyncio.Event().wait() finally: await manager.shutdown() if hasattr(agent, "cleanup"): await agent.cleanup() ``` The runnable scheduled example uses the same worker path without requiring an LLM API key: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} python3 cookbook/background_agents/scheduled_task_example.py ``` It creates a due `once` task, starts the background worker, waits for the run to complete, then prints task status, manager status, lifecycle events, and the workspace files created for the run. By default it writes the demo workspace under your system temp directory. Set `OMNICOREAGENT_COOKBOOK_WORKSPACE_DIR` to choose a different location: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} OMNICOREAGENT_COOKBOOK_WORKSPACE_DIR=/tmp/omnicoreagent-background-demo \ python3 cookbook/background_agents/scheduled_task_example.py ``` ## Real Application Background Task The real application example runs the support operations app shape through the background manager. It uses the same support domain tools as `cookbook/real_applications/support_operations_agent.py`, registers a manual task, waits for the run to finish, then prints the run id, status, attempts, lifecycle events, and workspace files. It is deterministic and does not require `LLM_API_KEY`, so it is safe to run in CI or locally when you only want to inspect the background execution boundary: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} uv run python cookbook/background_agents/real_application_background_task.py ``` By default, the workspace root is under your system temp directory at `omnicoreagent_real_app_background_workspace`. The script prints both `workspace_root` and the run-local `workspace` path. Pass `workspace_dir` when calling `run_real_application_background_example(...)` from Python if you want a specific local root. The run workspace contains: * `output.md` with the durable support note * `tickets/tck-1042.md` with the ticket-specific record * `run.json` with the latest run snapshot * `events.jsonl` with ordered lifecycle events ## Runtime Controls ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} run = await manager.run_now("health_report", wait=True) status = await manager.get_run(run.run_id) task_status = await manager.get_task_status("health_report") manager_status = await manager.get_manager_status() attempts = await manager.list_attempts(run.run_id) events = await manager.get_run_events(run.run_id) workspace = await manager.get_run_workspace(run.run_id) await manager.cancel_run(run.run_id) await manager.pause_task("health_report") await manager.resume_task("health_report") ``` `get_run_events(run_id)` returns ordered lifecycle events for that run. These events use run-local names such as `background_task_scheduled`, `background_run_queued`, `background_run_claimed`, `background_run_started`, `background_run_heartbeat`, `background_run_retrying`, `background_run_recovered`, `background_run_completed`, `background_run_failed`, `background_run_timeout`, `background_run_cancelled`, and `background_run_skipped`. When workspace event mirroring is enabled, lifecycle events are also written to the run workspace `events.jsonl` file for durable replay and debugging. ## OmniServe Endpoints OmniServe exposes the same background run lifecycle over HTTP: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -X POST http://localhost:8000/background/tasks \ -H "Content-Type: application/json" \ -d '{ "task_id": "health_report", "query": "Check system health and write the report.", "schedule": {"type": "manual"}, "timeout_seconds": 60 }' curl -X POST http://localhost:8000/background/tasks/health_report/run \ -H "Content-Type: application/json" \ -d '{"wait": true}' ``` The background API includes manager status, task creation, task status, task listing, pause, resume, delete, manual run, cancellation, run status, attempt history, event replay, and workspace inspection. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl http://localhost:8000/background/status curl http://localhost:8000/background/tasks/health_report/status curl http://localhost:8000/background/runs/$RUN_ID curl http://localhost:8000/background/runs/$RUN_ID/events curl http://localhost:8000/background/runs/$RUN_ID/workspace ``` ## Task Configuration | Field | Purpose | | ----------------- | ------------------------------------------------------------------------ | | `task_id` | Stable task identifier. | | `agent_id` | Registered agent that executes the task. | | `query` | Instruction passed to the agent for each run. | | `schedule` | `manual`, `interval`, `cron`, or `once`. | | `timeout_seconds` | Optional per-run timeout. | | `retry_policy` | Retry count, delay, backoff, and retryable error types. | | `overlap_policy` | `skip_if_running`, `queue_next`, `cancel_previous`, or `allow_parallel`. | | `session_policy` | `task`, `run`, or `fixed` memory-session behavior. | State is restart-persistent when the task store is SQL, Redis, or MongoDB. # Getting Started Cookbook Source: https://docs-omnicoreagent.omnirexfloralabs.com/cookbook/getting_started/README Progressive runnable examples for your first OmniCoreAgent, local tools, MCP tools, memory, events, context management, guardrails, and OmniServe # Getting Started with OmniCoreAgent Welcome to the **OmniCoreAgent** learning path. This guide takes you from writing your first line of code to building production-ready, autonomous agents with persistent memory, context management, and guardrails. **Follow the examples in order** โ€” each one builds on the concepts from the previous. *** ## ๐Ÿ“š The Learning Path | # | File | Key Concepts | | -- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | 1 | [first\_agent.py](./first_agent.py) | **The Basics**: Initialize `OmniCoreAgent` and run a simple query | | 2 | [agent\_with\_models.py](./agent_with_models.py) | **Models**: Switch providers (OpenAI, Anthropic, Gemini, Groq, Ollama) | | 3 | [agent\_with\_local\_tools.py](./agent_with_local_tools.py) | **Local Tools**: Register Python functions as agent tools | | 4 | [agent\_with\_mcp\_tools.py](./agent_with_mcp_tools.py) | **MCP Integration**: Connect to external MCP servers | | 5 | [agent\_with\_all\_tools.py](./agent_with_all_tools.py) | **Hybrid Architecture**: Combine local + MCP tools | | 6 | [agent\_with\_memory.py](./agent_with_memory.py) | **Persistence**: Store conversations in Redis, Postgres, MongoDB | | 7 | [agent\_with\_memory\_switching.py](./agent_with_memory_switching.py) | **Runtime Switching**: Change memory backends on the fly | | 8 | [agent\_with\_events.py](./agent_with_events.py) | **Telemetry**: Replay run events, stream progress, and retrieve traces | | 9 | [agent\_with\_context\_management.py](./agent_with_context_management.py) | **๐Ÿ†• Context Management**: Keep long conversations within a configured context budget | | 10 | [agent\_with\_guardrails.py](./agent_with_guardrails.py) | **๐Ÿ†• Guardrails**: Protect against prompt injection | | 11 | [agent\_with\_metrics.py](./agent_with_metrics.py) | **๐Ÿ†• Metrics**: Track tokens, requests, and latency | | 12 | [agent\_with\_sub\_agents.py](./agent_with_sub_agents.py) | **๐Ÿ†• Sub-Agents**: Build multi-agent systems | | 13 | [agent\_configuration.py](./agent_configuration.py) | **Advanced Config**: All settings in one place | *** ## ๐ŸŽฏ "I just want to..." | Goal | Example | | ------------------------------------------ | ------------------------------------------------------------------------- | | Build my first agent | [first\_agent.py](./first_agent.py) | | Use a different LLM (Claude, Gemini, etc.) | [agent\_with\_models.py](./agent_with_models.py) | | Give my agent tools | [agent\_with\_local\_tools.py](./agent_with_local_tools.py) | | Connect to MCP servers | [agent\_with\_mcp\_tools.py](./agent_with_mcp_tools.py) | | Save conversation history | [agent\_with\_memory.py](./agent_with_memory.py) | | Handle long conversations | [agent\_with\_context\_management.py](./agent_with_context_management.py) | | Protect against attacks | [agent\_with\_guardrails.py](./agent_with_guardrails.py) | | Track usage for cost estimation | [agent\_with\_metrics.py](./agent_with_metrics.py) | | Build multi-agent systems | [agent\_with\_sub\_agents.py](./agent_with_sub_agents.py) | *** ## ๐Ÿ› ๏ธ Prerequisites ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} pip install omnicoreagent # Most hosted model providers need only this key. The cookbook loader reads .env. echo "LLM_API_KEY=your_key_here" > .env ``` The examples start with in-memory defaults. Add `REDIS_URL`, `DATABASE_URL`, or `MONGODB_URI` only when you intentionally run the persistence examples. *** ## ๐Ÿ“– Key Concepts ### Memory with Summarization ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} "memory_config": { "mode": "sliding_window", "value": 50, "summary": { "enabled": True, "retention_policy": "keep" } } ``` Old messages are summarized, not lost. ### Context Management ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} "context_management": { "enabled": True, "mode": "token_budget", # or "sliding_window" "value": 100000, "threshold_percent": 75, "strategy": "summarize_and_truncate", "preserve_recent": 6 } ``` Long conversations stay within the context budget you configure. #### Choosing the Right Mode | Mode | Triggers When | Best For | | ---------------- | ---------------------------------------- | ----------------------------------------- | | `sliding_window` | Message count exceeds `value` | Conversational agents with short messages | | `token_budget` | Token count exceeds `value ร— threshold%` | Tool-heavy agents with large responses | **Trade-offs:** | | `sliding_window` | `token_budget` | | -------------------- | --------------------------- | --------------------------- | | **Token efficiency** | โœ… Better (smaller contexts) | โš ๏ธ Larger contexts per call | | **Predictability** | โœ… Consistent behavior | Depends on message size | | **Large messages** | โš ๏ธ Can exceed limits | โœ… Handles safely | | **Cost** | โœ… Lower cumulative | Higher cumulative | **Recommendations:** * **Chatbots / Q\&A agents**: Use `sliding_window` with `value: 10-20` * **Tool-heavy agents** (APIs, web scraping): Use `token_budget` with `value: 8000-16000` * **Mixed workloads**: Use `token_budget` with lower threshold (50-60%) ### Tool Response Offloading ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} "tool_offload": { "enabled": True, "threshold_tokens": 500, # Offload if response > 500 tokens "max_preview_tokens": 150 # Show first 150 tokens in context } ``` Large tool responses are automatically saved into the active workspace `artifacts/` area, with only a preview in context. **How it works:** 1. Tool returns large response (e.g., web search with 50 results) 2. Response saved to `workspace/artifacts/` 3. Agent sees preview + file reference in context 4. Agent uses `read_artifact()` tool to get full content when needed **Token savings example:** | Tool Response | Without Offloading | With Offloading | | ----------------------- | ------------------ | --------------- | | Web search (50 results) | \~10,000 tokens | \~200 tokens | | Large API response | \~5,000 tokens | \~150 tokens | | File read (1000 lines) | \~8,000 tokens | \~200 tokens | **Tool offloading adds 4 artifact tools:** * `read_artifact(artifact_id)` - Read full content * `tail_artifact(artifact_id, lines)` - Read last N lines * `search_artifact(artifact_id, query)` - Search within artifact * `list_artifacts()` - List all offloaded artifacts Workspace files are separate and enabled by default with workspace-scoped command tools such as `ls`, `read_file`, `write_file`, `glob`, and `grep`. > ๐Ÿ’ก *Inspired by Cursor's "dynamic context discovery" and Anthropic's context engineering patterns* ### Guardrails ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} "guardrail_config": { "strict_mode": True } ``` Built-in protection against prompt injection attacks. ### Metrics ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} metrics = await agent.get_metrics() # Returns: total_requests, total_tokens, total_request_tokens, total_response_tokens ``` Track usage for cost control and monitoring. *** ## ๐Ÿš€ Next Steps * **[Workflows](../workflows)**: Chain agents together (Sequential, Parallel, Router) * **[Background Agents](../background_agents)**: Scheduled autonomous tasks * **[Production](../production)**: Metrics and guardrails # OmniServe Cookbook Source: https://docs-omnicoreagent.omnirexfloralabs.com/cookbook/omniserve/README Runnable examples for serving OmniCoreAgent over REST and SSE with CLI and Python API patterns # OmniServe Cookbook Production-ready API server examples for OmniCoreAgent. *** ## ๐Ÿ“ฆ Agent File Requirements Your agent file must define **one of the following**: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} # Option 1: `agent` variable agent = OmniCoreAgent(...) # Option 2: `create_agent()` function def create_agent(): return OmniCoreAgent(...) ``` *** ## Examples | Example | Description | How to Run | | ---------------------------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------- | | [cli\_agent.py](./cli_agent.py) | Agent file for CLI deployment | `omniserve run --agent cookbook/omniserve/cli_agent.py` | | [python\_api.py](./python_api.py) | Full Python API with all config options | `python cookbook/omniserve/python_api.py` | | [real\_application\_agent.py](./real_application_agent.py) | Serve the support operations real application harness | `uv run omniserve run --agent cookbook/omniserve/real_application_agent.py` | *** ## Quick Start ### Option 1: CLI (Zero-code deployment) ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} # Quickstart with defaults (no agent file needed) omniserve quickstart --provider openai --model gpt-4o-mini # Run with your agent file omniserve run --agent cookbook/omniserve/cli_agent.py --port 8000 # Run a real application harness uv run omniserve run --agent cookbook/omniserve/real_application_agent.py --port 8000 # With authentication and rate limiting omniserve run --agent cookbook/omniserve/cli_agent.py \ --port 8000 \ --auth-token secret \ --rate-limit 100 ``` Use the provider that matches your `LLM_API_KEY`. For an OpenAI key, run `omniserve quickstart --provider openai --model gpt-4o-mini`. ### Option 2: Python API (Programmatic control) ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} # Run Python script directly python cookbook/omniserve/python_api.py ``` > \[!WARNING] > **Environment Variable Precedence:** > Environment variables **ALWAYS override** values set in `OmniServeConfig`. > > ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} > # In code: port=8000 > # In environment: OMNICOREAGENT_SERVE_PORT=9000 > # Result: Server runs on port 9000 (env wins!) > ``` *** ## Environment Variables Server settings use the `OMNICOREAGENT_SERVE_*` prefix. Background task settings use the `OMNICOREAGENT_BACKGROUND_*` prefix. You can start without either prefix; defaults use port `8000`, in-memory background task state, and no auth/rate limiting until you opt in. | Variable | Default | Description | | ------------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------- | | `OMNICOREAGENT_SERVE_HOST` | `0.0.0.0` | Server host. Must not be empty | | `OMNICOREAGENT_SERVE_PORT` | `8000` | Server port. Must be `1`-`65535` | | `OMNICOREAGENT_SERVE_WORKERS` | `1` | Direct OmniServe worker count. Must be `1`; scale by running multiple processes | | `OMNICOREAGENT_SERVE_API_PREFIX` | `""` | API path prefix. Normalized to a leading slash with no trailing slash; whitespace is invalid | | `OMNICOREAGENT_SERVE_ENABLE_DOCS` | `true` | Swagger UI at `/docs` | | `OMNICOREAGENT_SERVE_ENABLE_REDOC` | `true` | ReDoc at `/redoc` | | `OMNICOREAGENT_SERVE_CORS_ENABLED` | `true` | Enable CORS | | `OMNICOREAGENT_SERVE_CORS_ORIGINS` | `*` | Allowed origins | | `OMNICOREAGENT_SERVE_CORS_METHODS` | `*` | Allowed methods | | `OMNICOREAGENT_SERVE_CORS_HEADERS` | `*` | Allowed headers | | `OMNICOREAGENT_SERVE_CORS_CREDENTIALS` | `true` | Allow credentials | | `OMNICOREAGENT_SERVE_AUTH_ENABLED` | `false` | Enable Bearer auth. Requires a non-empty auth token | | `OMNICOREAGENT_SERVE_AUTH_TOKEN` | โ€” | Bearer token value used when auth is enabled | | `OMNICOREAGENT_SERVE_RATE_LIMIT_ENABLED` | `false` | Rate limiting | | `OMNICOREAGENT_SERVE_RATE_LIMIT_REQUESTS` | `100` | Requests/window. Must be at least `1` when enabled | | `OMNICOREAGENT_SERVE_RATE_LIMIT_WINDOW` | `60` | Window seconds. Must be at least `1` when enabled | | `OMNICOREAGENT_SERVE_REQUEST_LOGGING` | `true` | Log requests | | `OMNICOREAGENT_SERVE_LOG_LEVEL` | `INFO` | Log level: `CRITICAL`, `ERROR`, `WARNING`, `INFO`, `DEBUG`, or `TRACE` | | `OMNICOREAGENT_SERVE_REQUEST_TIMEOUT` | `300` | Timeout seconds | | `OMNICOREAGENT_BACKGROUND_ENABLED` | `true` | Expose background task endpoints | | `OMNICOREAGENT_BACKGROUND_AGENT_ID` | `default` | Agent id for the served agent in background tasks | | `OMNICOREAGENT_BACKGROUND_TASK_STORE` | `in_memory` | Background task store backend: `in_memory`, `sql`, `redis`, or `mongodb` | | `OMNICOREAGENT_BACKGROUND_TASK_STORE_URL` | โ€” | SQL or Redis task store URL. Use `OMNICOREAGENT_BACKGROUND_TASK_STORE=redis` for Redis URLs | | `OMNICOREAGENT_BACKGROUND_TASK_STORE_URI` | โ€” | MongoDB task store URI | | `OMNICOREAGENT_BACKGROUND_TASK_STORE_DATABASE` | `omnicoreagent` | MongoDB database name | | `OMNICOREAGENT_BACKGROUND_TASK_STORE_PREFIX` | โ€” | Redis key prefix | | `OMNICOREAGENT_BACKGROUND_TASK_STORE_COLLECTION_PREFIX` | โ€” | MongoDB collection prefix | | `OMNICOREAGENT_BACKGROUND_TASK_STORE_CONNECT_TIMEOUT` | โ€” | Backend connect timeout in seconds | | `OMNICOREAGENT_BACKGROUND_START_WORKER` | `true` | Start scheduler and worker loop | *** ## API Endpoints ### Core Endpoints | Method | Endpoint | Auth | Description | | ------ | ---------------------------------------- | ----- | ------------------------------------------------------------------------------------------------ | | POST | `/run` | Yes\* | SSE streaming response | | POST | `/run/sync` | Yes\* | JSON response | | GET | `/health` | No | Health check | | GET | `/ready` | No | Readiness check | | GET | `/prometheus` | No | Prometheus metrics | | GET | `/tools` | Yes\* | List available tools | | GET | `/metrics` | Yes\* | Agent usage metrics | | GET | `/events/{session_id}` | Yes\* | Replay and follow telemetry events over SSE | | GET | `/events/{session_id}/list` | Yes\* | Return stored telemetry events as JSON | | GET | `/events/{session_id}/trace` | Yes\* | Return the latest telemetry trace summary | | GET | `/telemetry/events` | Yes\* | Return stored telemetry events by trace, run, session, task, or event type; default `limit=200` | | GET | `/telemetry/events/stream` | Yes\* | Replay and follow telemetry over SSE for a session | | GET | `/telemetry/traces` | Yes\* | List traces by trace, run, session, task, agent, workflow, model, or status; default `limit=100` | | GET | `/telemetry/traces/{trace_id}` | Yes\* | Return one exact trace | | GET | `/telemetry/runs/{run_id}/trace` | Yes\* | Return the latest trace for one run | | GET | `/telemetry/sessions/{session_id}/trace` | Yes\* | Return the latest trace for one session | | GET | `/sessions/{session_id}/history` | Yes\* | Return conversation history | | GET | `/docs` | No | Swagger UI | | GET | `/redoc` | No | ReDoc UI | `/ready` becomes true after server startup finishes, the agent is initialized, and configured MCP servers are connected. Local-only agents with no MCP servers do not need an MCP client for readiness. ### Background Task Endpoints These routes are mounted when background execution is enabled. It is enabled by default and can be turned off with `OMNICOREAGENT_BACKGROUND_ENABLED=false` or `OmniServeConfig(background_enabled=False)`. | Method | Endpoint | Auth | Description | | ------ | ------------------------------------- | ----- | ------------------------------------------- | | POST | `/background/agents` | Yes\* | Register a background agent | | GET | `/background/agents` | Yes\* | List background agents | | GET | `/background/agents/{agent_id}` | Yes\* | Inspect a background agent | | DELETE | `/background/agents/{agent_id}` | Yes\* | Delete a background agent | | POST | `/background/tasks` | Yes\* | Create a background task | | GET | `/background/tasks` | Yes\* | List background tasks | | GET | `/background/tasks/{task_id}` | Yes\* | Inspect a task | | PATCH | `/background/tasks/{task_id}` | Yes\* | Patch a task | | POST | `/background/tasks/{task_id}/run` | Yes\* | Queue or synchronously execute a manual run | | POST | `/background/tasks/{task_id}/pause` | Yes\* | Pause scheduled dispatch | | POST | `/background/tasks/{task_id}/resume` | Yes\* | Resume scheduled dispatch | | DELETE | `/background/tasks/{task_id}` | Yes\* | Delete a task | | POST | `/background/runs/{run_id}/cancel` | Yes\* | Cancel a queued or running run | | GET | `/background/runs` | Yes\* | List runs | | GET | `/background/runs/{run_id}` | Yes\* | Inspect run state | | GET | `/background/runs/{run_id}/attempts` | Yes\* | List run attempts | | GET | `/background/runs/{run_id}/events` | Yes\* | Replay lifecycle events | | GET | `/background/runs/{run_id}/workspace` | Yes\* | Inspect run workspace files | \*Auth required only if `OMNICOREAGENT_SERVE_AUTH_ENABLED=true` or `--auth-token` is set. `POST /background/tasks/{task_id}/run` accepts `{"wait": true}` when the client needs terminal run state in the response. With the worker enabled, OmniServe waits on the durable run record. With the worker disabled, OmniServe executes the run inline through the background manager execution path. If the run does not finish before the background wait budget, the response is `504`. The wait budget is derived from the configured request timeout and leaves a small margin for OmniServe to return the structured response before the outer HTTP timeout. The `detail` payload includes the `run_id`, latest `status`, `wait_timeout_seconds`, and `request_timeout_seconds` so the run can still be inspected through `/background/runs/{run_id}`. *** ## Docker Deployment ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} # Generate Dockerfile omniserve generate-dockerfile --file cookbook/omniserve/cli_agent.py # Build and run docker build -t omnicoreagent-serve . docker run -p 8000:8000 -e LLM_API_KEY=$LLM_API_KEY omnicoreagent-serve ``` ### Cloud Deployment (Cloud Run, AWS Fargate, Railway) The generated Dockerfile is deterministic. It does not import or execute the agent file. It sets: * `AGENT_PATH` to the in-container agent path * `OMNICOREAGENT_WORKSPACE_BACKEND=local` * `OMNICOREAGENT_WORKSPACE_DIR=/tmp/workspace` The agent file must be inside the current Docker build context. For S3/R2 workspace persistence, pass backend and credentials at runtime: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} docker run -p 8000:8000 \ -e LLM_API_KEY=$LLM_API_KEY \ -e OMNICOREAGENT_WORKSPACE_BACKEND=s3 \ -e AWS_S3_BUCKET=my-bucket \ -e AWS_ACCESS_KEY_ID=... \ -e AWS_SECRET_ACCESS_KEY=... \ omnicoreagent-serve ``` # Production Cookbook Source: https://docs-omnicoreagent.omnirexfloralabs.com/cookbook/production/README Production-oriented OmniCoreAgent examples for metrics, telemetry, guardrails, and operational configuration # Production > Deploy OmniCoreAgent with confidence. Runtime usage metrics and guardrails. ## Examples | File | What You'll Learn | | ------------------------------------------------------- | --------------------------------------------------------------------- | | [metrics\_observability.py](./metrics_observability.py) | Track tokens, requests, response times, and usage for cost estimation | | [guardrails.py](./guardrails.py) | Protect agents from prompt injection attacks | *** ## ๐Ÿ“Š Metrics & Observability Track everything your agent does: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from omnicoreagent import OmniCoreAgent agent = OmniCoreAgent( name="monitored_agent", system_instruction="You are a helpful assistant.", model_config={"provider": "openai", "model": "gpt-4o"}, agent_config={ "request_limit": 100, "total_tokens_limit": 50000, }, ) # After running queries... metrics = await agent.get_metrics() print(f"Total requests: {metrics['total_requests']}") print(f"Total tokens: {metrics['total_tokens']}") print(f"Request tokens: {metrics['total_request_tokens']}") print(f"Response tokens: {metrics['total_response_tokens']}") ``` **Available Metrics**: * `total_requests` โ€” Number of `agent.run()` calls * `total_tokens` โ€” Total tokens used (input + output) * `total_request_tokens` โ€” Tokens sent to LLM * `total_response_tokens` โ€” Tokens received from LLM *** ## ๐Ÿ›ก๏ธ Guardrails Protect against prompt injection attacks: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} agent = OmniCoreAgent( name="protected_agent", system_instruction="You are a customer service agent.", model_config={"provider": "openai", "model": "gpt-4o"}, agent_config={ "guardrail_config": { "strict_mode": True, # Block suspicious inputs }, }, ) ``` **Guardrails Detect**: * Prompt injection attempts * Jailbreak attempts * System prompt extraction attempts * Role manipulation attacks *** ## ๐Ÿ”ง Usage Limits Set limits to prevent runaway request or token usage: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} agent_config={ "request_limit": 100, # Max requests per session "total_tokens_limit": 50000, # Max tokens before stopping "max_steps": 10, # Max reasoning loops } ``` *** **Previous**: [Background Agents](../background_agents) โ€” Scheduled autonomous tasks # Real Application Harness Examples Source: https://docs-omnicoreagent.omnirexfloralabs.com/cookbook/real_applications/README Production-shaped OmniCoreAgent examples for research, support operations, personal operations, workspace code review, and background tasks # Real Application Harness Examples These examples show OmniCoreAgent as an application-facing agent harness, not a toy loop. Each app combines domain behavior with the built-in runtime pieces it needs: local tools, workspace files, tool offloading, guardrails, telemetry identifiers, and file commands. ## Examples | Example | Run command | What it demonstrates | | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | | [Research due diligence](./research_due_diligence_agent.py) | `uv run python cookbook/real_applications/research_due_diligence_agent.py` | Parallel research tools, context management, large evidence offload, artifact readback, workspace report output, telemetry identifiers | | [Support operations](./support_operations_agent.py) | `uv run python cookbook/real_applications/support_operations_agent.py` | Customer/order tools, support knowledge retrieval, guardrails, workspace ticket notes, telemetry | | [Personal operations assistant](./personal_operations_assistant.py) | `uv run python cookbook/real_applications/personal_operations_assistant.py` | Calendar/task/preferences tools, selectable memory backend, private workspace brief, guardrails, telemetry identifiers | | [Workspace code review](./workspace_code_review_agent.py) | `uv run python cookbook/real_applications/workspace_code_review_agent.py` | Built-in workspace command tools for file discovery, grep-style search, reading, editing, and writing review output | | [Support background task](../background_agents/real_application_background_task.py) | `uv run python cookbook/background_agents/real_application_background_task.py` | The support operations app shape running through durable task state, attempts, lifecycle events, and workspace output | ## Run an Example ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} export LLM_API_KEY=your_key uv run python cookbook/real_applications/research_due_diligence_agent.py ``` Expected output includes the agent response plus runtime identifiers such as `trace_id` and `run_id`. Workspace examples also print or create files under the configured workspace. The examples default to the provider/model from `cookbook/shared.py`. Override them with: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} export OMNICOREAGENT_PROVIDER=openai export OMNICOREAGENT_MODEL=gpt-5.4-mini ``` The personal assistant example defaults to in-memory history. To prove durable local memory without any external service, run it with SQLite: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} export OMNICOREAGENT_COOKBOOK_MEMORY_BACKEND=sql uv run python cookbook/real_applications/personal_operations_assistant.py ``` ## Why these examples exist Application builders need to see where OmniCoreAgent owns the base harness and where their application code plugs in. * App code provides domain tools, instructions, data sources, and business rules. * OmniCoreAgent provides the model loop, tool execution, workspace files, structured observations, offloading, telemetry, memory, and guardrails. * The same application pattern can be served through OmniServe with `cookbook/omniserve/real_application_agent.py`. * The same application pattern can run as a background task with `cookbook/background_agents/real_application_background_task.py`. Use these examples as starting points for your own application harness. # Workflow Agents Cookbook Source: https://docs-omnicoreagent.omnirexfloralabs.com/cookbook/workflows/README Sequential, parallel, and router workflow examples for coordinating multiple OmniCoreAgent instances # Workflow Agents > Orchestrate multiple agents for complex tasks using Sequential, Parallel, and Router patterns. ## Examples | File | Pattern | Key Concepts | | --------------------------------------------------- | -------------- | ----------------------------------------------- | | [sequential\_workflow.py](./sequential_workflow.py) | **Sequential** | Chain agents to pass results step-by-step | | [parallel\_agent.py](./parallel_agent.py) | **Parallel** | Run agents concurrently for speed | | [router\_agent.py](./router_agent.py) | **Router** | Intelligently route tasks to specialized agents | ## When to Use Each Pattern | Pattern | Use When | Example | | -------------- | ---------------------------- | --------------------------- | | **Sequential** | Tasks depend on each other | Research โ†’ Analyze โ†’ Report | | **Parallel** | Tasks are independent | Check 3 APIs simultaneously | | **Router** | Task type determines handler | Customer โ†’ Support vs Sales | ## Quick Start ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from omnicoreagent import SequentialAgent workflow = SequentialAgent( name="research_pipeline", agents=[researcher, analyst, writer], ) result = await workflow.run("Analyze AI trends in healthcare") ``` *** **Next**: Check out [Background Agents](../background_agents) for scheduled autonomous tasks. # Changelog Source: https://docs-omnicoreagent.omnirexfloralabs.com/docs/changelog Release history and version notes for OmniCoreAgent # Changelog OmniCoreAgent is being rebuilt around the production agent harness direction: runtime, tools, MCP, memory, workspace, guardrails, background tasks, telemetry, and OmniServe as one application-facing base layer. Detailed version history is published with GitHub releases: Review tagged releases, release notes, and package versions. ## Current Package Direction * Agent harness positioning instead of generic framework positioning. * Single `LLM_API_KEY` public API-key variable for hosted model providers. * Optional extras for heavier production integrations. * Workspace files on local disk, S3, or Cloudflare R2. * Memory backends: `in_memory`, `sql`, `redis`, and `mongodb`. * Background task stores: `in_memory`, `sql`, `redis`, and `mongodb`. * Telemetry stores: in-memory and JSONL, with OTLP-compatible exporters for OpenTelemetry, LangSmith, and Opik. * OmniServe configuration through `OMNICOREAGENT_SERVE_*`. * Background serving configuration through `OMNICOREAGENT_BACKGROUND_*`. ## Configuration Source Of Truth Use the configuration guide for current environment variables and runtime settings: Current model, memory, workspace, background, telemetry, and OmniServe settings. # Agent Harness Source: https://docs-omnicoreagent.omnirexfloralabs.com/docs/core-concepts/agent-harness What OmniCoreAgent adds around a model to make it useful for long-running autonomous work # Agent Harness An LLM is not an agent by itself. A useful agent needs runtime behavior around the model: tools, memory, context control, a workspace, guardrails, events, delegation, and a serving boundary. That runtime is the agent harness. OmniCoreAgent is built as an open Python agent harness. You still choose the model and the tools, but the execution system around them is already assembled. ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} model + prompt contract + ReAct loop + local tools + MCP tools + parallel tool batches + structured observations + loop detection + memory + context management + workspace files + tool artifacts + guardrails + events + subagents + serving through OmniServe ``` *** ## Why This Matters A basic tool-calling agent is easy to build. The hard part starts when the agent needs to work for more than one or two steps: * tool calls become sequential bottlenecks * large tool outputs fill the prompt * old context pushes the model toward provider limits * external tool output carries prompt-injection risk * the agent repeats the same failing action * workers need to split independent work and report back * intermediate files, notes, logs, and artifacts need a durable place to live * the app eventually needs a stable HTTP/SSE serving boundary OmniCoreAgent exists because these are runtime problems, not prompt-only problems. *** ## Implementation-Backed Capability Map Every capability below maps to code in the repository. | Capability | What The User Gets | Main Implementation | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | **Custom tool-call contract** | XML tool calls, final answers, single tool calls, multi-tool calls, and agent calls are parsed consistently. | `src/omnicoreagent/core/agents/xml_parser.py` | | **Parallel batch tool execution** | Independent tools from one model step are resolved and executed together with timeout handling. | `src/omnicoreagent/core/tools/tool_batch_runner.py` | | **Tool runtime registry** | Local tools, MCP tools, workspace tools, artifact tools, skills, subagent tools, and BM25 retrieval are prepared through one runtime surface. | `src/omnicoreagent/core/tools/tool_runtime_registry.py` | | **Structured observations** | Tool outputs are normalized, guarded, formatted, and returned to the model as structured observations. | `src/omnicoreagent/core/tools/tool_observation.py` | | **Tool output offloading** | Large tool responses are written to workspace artifacts and replaced with a compact preview/reference. | `src/omnicoreagent/core/workspace/artifacts.py` | | **Artifact readback tools** | Agents read, tail, search, and list offloaded tool responses when full content is needed. | `src/omnicoreagent/core/workspace/artifact_tools.py` | | **Automatic context control** | Before each model call, active messages are checked and reduced when the configured context threshold is crossed. | `src/omnicoreagent/core/agents/llm_step.py`, `src/omnicoreagent/core/context_manager.py` | | **Loop detection** | Repeated SHA256-backed tool-call signatures and repeated interaction patterns are detected. | `src/omnicoreagent/core/agents/loop_detection.py` | | **Workspace files** | Agents get file tools for notes, scratchpads, todos, task progress, generated work, and subagent output. | `src/omnicoreagent/core/workspace/tools.py` | | **Local/S3/R2 workspace storage** | The same workspace interface runs on local disk, S3, or R2. | `src/omnicoreagent/core/workspace/config.py`, `src/omnicoreagent/core/workspace/storage.py` | | **Dynamic subagents** | The lead agent spawns one or many focused workers; workers inherit model/tools/config and write output to workspace files. | `src/omnicoreagent/core/subagents.py` | | **MCP tools** | MCP servers are loaded as external tool providers over supported transports. | `src/omnicoreagent/mcp_clients_connection/client.py` | | **Guardrails** | User input and tool output are screened according to guardrail mode; full mode passes guardrails into the ReAct agent for output scrubbing. | `src/omnicoreagent/core/guardrails/`, `src/omnicoreagent/core/tools/tool_observation_guardrail.py` | | **Telemetry and metrics** | Runs and tool actions emit typed telemetry events and return request metrics. | `src/omnicoreagent/core/telemetry/`, `src/omnicoreagent/core/agents/llm_step.py` | | **OmniServe** | The same agent is exposed through REST/SSE with shared server state and lifecycle handling. | `src/omnicoreagent/serve/` | *** ## The Harness Loop The core loop is a controlled runtime cycle: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} 1. Load session memory 2. Assemble prompt and tool registry 3. Check context before model call 4. Call model through LiteLLM 5. Parse XML response 6. Resolve tool or agent calls 7. Execute tool batch in parallel 8. Normalize, guard, and offload observations 9. Detect repeated tool-call loops 10. Continue or return final answer ``` This loop is why OmniCoreAgent supports simple assistants and deeper long-running agents through the same entry point. *** ## Defaults Versus Harness Features The default agent stays light. Heavier harness behavior is enabled when the workload needs it. | Capability | Default | Reason | | ---------------------------- | ----------------- | ---------------------------------------------------------------------- | | ReAct loop | On | This is the core agent runtime. | | Session memory | On | Agents need conversation continuity. | | Workspace files | On | Agents need a filesystem surface for notes and outputs. | | Guardrails | On in `full` mode | Input and tool-output safety should be available without extra wiring. | | Context management | Off until enabled | Small agents should not pay summarization/truncation overhead. | | Tool offload | Off until enabled | Only needed when tools produce large payloads. | | BM25 tool retrieval | Off until enabled | Only needed when the tool list is too large for the prompt. | | Dynamic subagents | Off until enabled | Only needed for delegated work. | | Agent skills | Off until enabled | Only needed when packaged capabilities are installed. | | Redis/Postgres/MongoDB/S3/R2 | Optional extras | Install only the production backends you use. | *** ## OmniCoreAgent, OmniServe, And OmniDaemon These are separate layers: | Layer | Purpose | | ----------------- | ------------------------------------------------------------------------------------------------------- | | **OmniCoreAgent** | In-process agent harness: model loop, tools, memory, context, workspace, guardrails, events, subagents. | | **OmniServe** | HTTP/SSE serving layer for exposing an OmniCoreAgent instance as an API. | | **OmniDaemon** | Event-driven runtime for supervised, process-isolated agents running as autonomous services. | Keeping these boundaries clear matters. OmniCoreAgent should stay focused on the agent harness. Serving and event-driven infrastructure should live outside the core loop. *** ## Boundaries OmniCoreAgent stays focused on the in-process agent harness. That boundary keeps the core runtime clean: * MCP brings external MCP server tools into the same runtime surface as local tools, workspace tools, skills, and harness tools. * Context management works by acting before the model call against the configured budget. * Cloud workspace storage is used when the S3 or R2 backend is installed and configured. * Distributed process supervision belongs in OmniDaemon, while HTTP/SSE serving belongs in OmniServe. The result is a complete, open agent harness whose production pieces are already integrated and testable. # Architecture Source: https://docs-omnicoreagent.omnirexfloralabs.com/docs/core-concepts/architecture How OmniCoreAgent is built: runtime, loop, tools, observations, memory, workspace, events, and serving # Architecture OmniCoreAgent is an agent harness: everything added around a model to make it usable for real autonomous work. The model is only one part of the system. The harness owns prompt assembly, the reasoning loop, tool resolution, parallel tool execution, observation formatting, loop detection, memory, workspace files, events, and serving integration. The architecture is intentionally modular so each layer can be tested and changed without turning the root agent class into a dump of unrelated behavior. *** ## High-Level Runtime ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} graph TD App["User application"] --> Agent["OmniCoreAgent facade"] Agent --> Runtime["Agent runtime construction"] Runtime --> Loop["ReAct loop"] Runtime --> Tools["Tool runtime"] Runtime --> State["State services"] Runtime --> Harness["Harness capabilities"] Loop --> Model["LiteLLM model call"] Loop --> Parser["Custom tool-call parser"] Parser --> Batch["Parallel tool batch runner"] Batch --> Observation["Observation pipeline"] Observation --> Loop Tools --> Local["Local ToolRegistry"] Tools --> MCP["MCP tools"] Tools --> WorkspaceTools["Workspace command tools"] Tools --> SkillTools["Skill tools"] Tools --> SubagentTools["Subagent tools"] Tools --> Retrieval["BM25 tool retrieval"] State --> Memory["Memory router"] State --> Telemetry["Telemetry stream"] State --> Workspace["Workspace storage"] Harness --> Context["Context management"] Harness --> Offload["Tool output offload"] Harness --> Guardrails["Guardrails"] Harness --> Serve["OmniServe"] ``` *** ## Request Flow The user application calls `agent.run(query, session_id=...)`. The runtime loads session state and prepares the prompt for the current request. OmniCoreAgent builds the system prompt from the base instruction, harness rules, available tools, workspace guidance, memory policy, subagent policy, and BM25 tool retrieval results when enabled. Before every LLM call, the runtime checks whether context management should trigger. If enabled and the configured threshold is crossed, it truncates or summarizes the message history before LiteLLM sends the prompt to the provider. The model returns either a final answer or one or more tool calls using OmniCoreAgent's tool-call contract. The parser extracts tool calls. The resolver maps each call to the right executor: local Python tool, MCP tool, skill, workspace tool, or harness tool. The batch runner executes the resolved tools concurrently with a per-tool timeout. Successes and failures are collected together. The observation pipeline normalizes the batch result, applies guardrails, offloads large payloads to the active workspace when configured, and creates the observation text that returns to the model. Tool-call signatures are recorded so the runtime can detect repeated calls or repeated tool interaction patterns beyond max step limits. The model receives the structured observation and either continues with more tool work or returns the final response. *** ## Core Layers ### 1. Public Facade `OmniCoreAgent` is the API application builders use. It owns the user-facing constructor, `run()`, MCP connection helpers, history helpers, runtime switching, metrics, and cleanup. The facade should stay thin. Construction and runtime behavior live in dedicated modules so the agent entry point remains easy to read. ### 2. Runtime Construction The runtime construction layer normalizes: * model configuration * MCP tool configuration * agent configuration * memory routers and telemetry streams * workspace configuration * harness capability setup This is where defaults are resolved. For example, workspace files are enabled by default, context management and tool offload are disabled by default, and enabling subagents forces workspace files on. ### 3. ReAct Loop The loop controls the actual agent execution: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} messages -> model -> tool calls -> batch execution -> observation -> model ``` The loop is also where max steps, request limits, token limits, context management, memory updates, and final response handling are enforced. Context management runs before the model call, so a configured token budget reduces the prompt before the provider context window is hit. ### 4. Tool Runtime Tools come from several sources but are exposed to the model through one runtime view: | Source | Purpose | | ----------------------- | --------------------------------------------------------------------------- | | Local tools | Application-owned Python functions registered with `ToolRegistry`. | | MCP tools | External tool servers over stdio, SSE, or Streamable HTTP. | | Workspace command tools | File operations for notes, scratchpads, task progress, and generated files. | | Artifact tools | Read, tail, search, and list offloaded tool-result artifacts. | | Skills | Packaged capabilities implemented in Python, Bash, or Node.js. | | Subagent tools | Harness tools that let the lead agent spawn focused workers. | | BM25 retrieval | Optional tool filtering when the full tool set is too large for the prompt. | The model should not need to know where a tool came from. The resolver maps tool names to the right executor. ### 5. Parallel Batch Runner The batch runner is responsible for executing all tool calls from a model step together: * assigns stable tool call IDs * emits start/result/error events * runs calls concurrently * applies the configured timeout * preserves individual success and failure results * passes the combined result into the observation pipeline This layer is one of the core differences between OmniCoreAgent and a basic sequential tool loop. ### 6. Observation Pipeline The observation pipeline protects the next reasoning step from raw, noisy tool output. ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} raw tool results -> normalized tool result objects -> guardrail screening -> workspace offload when configured -> compact observation text ``` The model gets enough information to continue the task and a workspace reference when a large payload was offloaded. ### 7. State Services State is split by responsibility: | Service | Responsibility | | ----------------- | --------------------------------------------------------------------------------------- | | Memory router | Conversation/session history. | | Telemetry stream | Typed run, tool, background, and service events for live streaming and replay. | | Workspace storage | Files used by agents, subagents, tools, artifacts, scratchpads, and offloaded payloads. | Workspace storage is separate from memory storage. Memory stores conversation state. Workspace stores files. A project can use Redis for memory and local disk, S3, or R2 for workspace files. ### 8. Serving Layer OmniServe wraps an OmniCoreAgent instance with production HTTP/SSE boundaries: * app lifecycle * request serialization * streaming route helpers * health and metrics routes * CORS and error middleware * shared server state The dependency points one way: OmniServe wraps the agent runtime, while the agent runtime stays independent of the serving package. *** ## Design Invariants These rules keep the architecture clean: * MCP connects external MCP server tools into OmniCoreAgent's tool runtime. Those MCP tools are resolved and executed beside local tools, workspace tools, skills, and harness tools. * Workspace storage is the only filesystem surface for harness files: notes, scratchpads, artifacts, subagent output, and tool offloads. * Memory storage and workspace storage are different concepts and should not share naming that makes users confuse them. * Tool output should not go straight to the model. It must pass through the observation pipeline. * Subagents must write useful output into the workspace so the lead agent can inspect it later. * Optional production backends belong behind routers or storage interfaces, not inside the root agent class. * Public docs should separate default behavior from opt-in capability. *** ## Runtime Boundaries OmniCoreAgent is the in-process agent harness. The surrounding production boundaries are handled by the layer designed for that job: * Use **OmniServe** when you need REST/SSE access to an agent. * Use **OmniDaemon** when you need event-driven, supervised, process-isolated agents running as autonomous infrastructure services. * Use your own application infrastructure when you only need a direct script or a direct function call around one model request. This separation keeps OmniCoreAgent focused: it builds the agent harness cleanly, then integrates with the right outer runtime when the deployment needs it. # Background Agents Source: https://docs-omnicoreagent.omnirexfloralabs.com/docs/core-concepts/background-agents Run tracked OmniCoreAgent tasks outside the foreground request path # Background Agents Background agents run tracked OmniCoreAgent tasks outside the foreground request path. Use the default in-memory store for local development, or choose `sql`, `redis`, or `mongodb` when tasks, runs, attempts, leases, retries, and cancellation state must survive process restarts. A task can run manually, once at a fixed time, on an interval, or from a five-field cron expression. Each run is tracked through queued, claimed, running, retrying, and terminal states. Background execution is part of the core package: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} pip install omnicoreagent ``` Redis and MongoDB task stores use optional backend drivers: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} pip install "omnicoreagent[redis]" pip install "omnicoreagent[mongodb]" ``` No storage configuration is required to start. `BackgroundAgentManager()` uses an in-memory task store by default so the first run has no database requirement. Use `task_store="sql"`, `task_store="redis"`, or `task_store="mongodb"` when tasks, runs, attempts, leases, retries, and cancellation state must survive process restarts. The task store is separate from agent memory. `MemoryRouter` stores conversation/session history. The task store stores operational background state and owns the atomic claim, lease, retry, and schedule-cursor guarantees. ## Quick Start Set `LLM_API_KEY` first, then run the example; no task-store configuration is required. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} import asyncio from omnicoreagent import BackgroundAgentManager, OmniCoreAgent async def main(): agent = OmniCoreAgent( name="system_monitor", system_instruction="Check system health and write concise reports.", model_config={"provider": "openai", "model": "gpt-5.4-mini"}, ) manager = BackgroundAgentManager() await manager.register_agent("system_monitor", agent) await manager.register_task( task_id="health_report", agent_id="system_monitor", query="Check system health and summarize anything that needs attention.", schedule={"type": "manual"}, timeout_seconds=60, retry_policy={"max_retries": 1, "initial_delay_seconds": 0}, ) run = await manager.run_now("health_report", wait=True) print(run.status) print(run.result_preview) asyncio.run(main()) ``` ## Scheduled Runs Start the manager when you want it to dispatch due schedules: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} await manager.register_task( task_id="hourly_report", agent_id="system_monitor", query="Write the hourly operational report.", schedule={"type": "interval", "seconds": 3600}, overlap_policy="queue_next", ) await manager.start() ``` The worker loop reads due schedules from the task store, creates a run exactly once for each occurrence, advances the schedule state, claims queued runs, and executes them with lease fencing. ## Runtime Controls ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} run = await manager.run_now("health_report") latest = await manager.get_run(run.run_id) attempts = await manager.list_attempts(run.run_id) events = await manager.get_run_events(run.run_id) await manager.cancel_run(run.run_id) await manager.pause_task("hourly_report") await manager.resume_task("hourly_report") await manager.delete_task("hourly_report", delete_runs=True) ``` ## Run Event Replay Each run emits ordered lifecycle events with a run-local `sequence` number. `get_run_events(run_id)` returns the most complete trace it can read from: * the current process cache * the run workspace `events.jsonl` mirror, when workspace event mirroring is enabled If more than one source is available, OmniCoreAgent returns a complete terminal trace first. If no source has reached a terminal event yet, it prefers the process cache, then the workspace mirror. Sources with malformed or duplicate run-local sequence numbers are ignored during replay selection. A valid source uses contiguous integer sequence numbers starting at `1`. Run-scoped lifecycle events include schedule dispatch, queueing, claiming, start, heartbeat, retry, terminal status, and recovery transitions when those transitions occur. Durable restart replay needs workspace event mirroring enabled. If a process exits with only in-memory events and no workspace mirror, the task store still preserves run status, attempts, leases, and results, but old event history may not be replayable. ## OmniServe API When an agent is served through OmniServe, the server registers that agent with the background manager during startup and exposes task control over HTTP: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -X POST http://localhost:8000/background/tasks \ -H "Content-Type: application/json" \ -d '{ "task_id": "health_report", "query": "Check system health and write the report.", "schedule": {"type": "manual"}, "timeout_seconds": 60 }' curl -X POST http://localhost:8000/background/tasks/health_report/run \ -H "Content-Type: application/json" \ -d '{"wait": false}' ``` Use `{"wait": true}` when the HTTP request should wait for terminal run state. If the OmniServe worker is running, the API waits for that worker-owned run. If the worker is disabled, the API queues the run through the background manager and drives that run inline through the same execution contract. If the run does not finish before the background wait budget, OmniServe returns `504` and the run remains inspectable through the background run endpoints. The wait budget is derived from the configured request timeout and leaves a small margin for OmniServe to return the structured response before the outer HTTP timeout. The `504` response includes the `run_id`, `task_id`, latest `status`, `wait_timeout_seconds`, and `request_timeout_seconds` in `detail`. The background API includes manager status, task creation, task status, task listing, pause, resume, delete, manual run, cancellation, run status, attempt history, event replay, and workspace inspection. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl http://localhost:8000/background/status curl http://localhost:8000/background/tasks/health_report/status curl http://localhost:8000/background/runs/$RUN_ID curl http://localhost:8000/background/runs/$RUN_ID/events curl http://localhost:8000/background/runs/$RUN_ID/workspace ``` ## Task Configuration | Field | Purpose | | ------------------ | ------------------------------------------------------------------------ | | `task_id` | Stable task identifier. | | `agent_id` | Registered agent that executes the task. | | `query` | Instruction passed to the agent for each run. | | `schedule` | `manual`, `interval`, `cron`, or `once`. | | `timeout_seconds` | Optional per-run timeout. | | `retry_policy` | Retry count, delay, backoff, and retryable error types. | | `overlap_policy` | `skip_if_running`, `queue_next`, `cancel_previous`, or `allow_parallel`. | | `session_policy` | `task`, `run`, or `fixed` memory-session behavior. | | `workspace_policy` | Workspace namespace used for run output. | ## Persistent State The task store is the source of truth for: * registered agent specs * task definitions * schedule state and occurrence IDs * runs and attempts * leases, heartbeats, and cancellation flags The current runtime includes the tracked run model, in-memory, SQL, Redis, and MongoDB task stores, schedule dispatch, manual runs, retries with delay/backoff, lease fencing, expired-lease recovery, cancellation, workspace lifecycle files, and run event replay. Task, schedule, run, attempt, lease, retry, and cancellation state is restart-persistent when the task store is SQL, Redis, or MongoDB. Event history follows the replay rules above through the manager process cache and workspace `events.jsonl` mirror. Durable stores are tested at the manager boundary. A queued run can be created, the manager can shut down, and a new manager over the same SQL, Redis, or MongoDB task store can claim and complete that run. The in-memory store is only for local development, tests, and single-process experiments. Choose one durable backend per deployment. Use SQL/SQLite for local durability or simple single-node services. Use Redis when your deployment already operates Redis with persistence and no eviction for task-store keys. Use MongoDB when MongoDB is your durable operational store. Redis durable deployments need persistence enabled and a no-eviction policy for task-store keys. MongoDB task-store writes use majority write concern. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} BackgroundAgentManager(task_store="sql") BackgroundAgentManager(task_store={"backend": "redis", "url": "redis://localhost:6379/0"}) BackgroundAgentManager( task_store={ "backend": "mongodb", "uri": "mongodb://localhost:27017", "database": "omnicoreagent", } ) ``` # Context Engineering Source: https://docs-omnicoreagent.omnirexfloralabs.com/docs/core-concepts/context-engineering Automatic context control and workspace-backed tool output offloading # Context Engineering OmniCoreAgent has three context-control layers that work together: | Layer | Scope | Purpose | Default | | --------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------- | | **Session memory** | Across `agent.run()` calls | Controls how much conversation history is loaded for a session. | On through the memory router | | **Agent loop context management** | Inside one `agent.run()` loop | Checks active messages before every model call and reduces them before the configured budget is exceeded. | Off until enabled | | **Tool output offloading** | Individual tool responses | Moves large tool outputs into workspace artifacts and keeps only a preview in the prompt. | Off until enabled | When agent loop context management is enabled and configured with a budget below your model's real context window, OmniCoreAgent acts before the provider context limit is hit. The runtime checks context before the LLM call, not after an error. ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} active messages -> context threshold check -> truncate or summarize+truncate when needed -> model call ``` This is why long tasks can keep moving without waiting for the provider to reject an oversized prompt. *** ## Layer 1: Session Memory Session memory decides what historical messages are loaded when a new `agent.run()` starts. This is the cross-request layer. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} agent = OmniCoreAgent( name="assistant", system_instruction="You are helpful.", model_config={"provider": "openai", "model": "gpt-4o"}, agent_config={ "memory_config": { "mode": "sliding_window", "value": 10000, "summary": {"enabled": False}, } }, ) ``` Use persistent memory backends such as Redis, MongoDB, or SQL database storage when session history must survive process restarts. *** ## Layer 2: Agent Loop Context Management Agent loop context management runs inside the ReAct loop. Before each model call, `OmniCoreAgent` asks the context manager whether the current messages crossed the configured threshold. If yes, it reduces the message list before the LLM request is sent. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} agent_config = { "context_management": { "enabled": True, "mode": "token_budget", # or "sliding_window" "value": 100000, # token budget or message count "threshold_percent": 75, "strategy": "summarize_and_truncate", # or "truncate" "preserve_recent": 6, } } ``` With the config above, management triggers around 75,000 tokens. If the selected model has a larger context window, the harness reduces context before the model request reaches the provider limit. ### What Is Preserved | Part | Behavior | | ---------------- | --------------------------------------------------------------- | | System prompt | Always preserved. | | Recent messages | Preserved according to `preserve_recent`. | | Middle history | Truncated, or summarized then truncated, depending on strategy. | | Summary metadata | Added when `summarize_and_truncate` creates a context summary. | ### Modes | Mode | Description | Best For | | ---------------- | ---------------------------------------- | ----------------------------------------- | | `token_budget` | Manage context by estimated token count. | Provider context limits and cost control. | | `sliding_window` | Manage context by message count. | Predictable, low-latency history windows. | ### Strategies | Strategy | Behavior | Trade-Off | | ------------------------ | ---------------------------------------------------------------------------------------- | ------------------------------------------------ | | `truncate` | Drop older middle messages while preserving system and recent messages. | Fast and deterministic. | | `summarize_and_truncate` | Summarize older middle history, insert a summary message, then preserve recent messages. | Keeps more intent, adds an LLM call and latency. | *** ## Layer 3: Tool Output Offloading Tool offloading handles large individual tool responses. It keeps the agent from burning context on a full payload when a preview and a file reference are enough for the next reasoning step. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} agent_config = { "tool_offload": { "enabled": True, "threshold_tokens": 500, "threshold_bytes": 2000, "max_preview_tokens": 150, "max_preview_lines": 10, } } ``` When a tool result crosses the configured threshold, OmniCoreAgent writes the full payload to the active workspace `artifacts/` area. The observation sent to the model contains the preview and the artifact reference. ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} large tool result -> workspace artifact -> preview + artifact reference in the observation ``` The artifact uses the same workspace backend as the rest of the agent: local, S3, or R2. ### Built-In Artifact Tools Artifact tools are available when offloading is enabled: | Tool | Purpose | | ----------------- | ---------------------------------------------------------------- | | `read_artifact` | Read the full offloaded payload. | | `tail_artifact` | Read the last lines of an artifact, useful for logs. | | `search_artifact` | Search inside an offloaded payload. | | `list_artifacts` | List artifacts available in the current workspace/session scope. | *** ## Full Context Configuration Use all layers together for long-running research, coding, data, and operational agents: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} agent = OmniCoreAgent( name="research_agent", system_instruction=( "Use workspace files and artifact references for long tasks. " "Read artifacts only when the full payload is needed." ), model_config={"provider": "openai", "model": "gpt-4o"}, agent_config={ "memory_config": { "mode": "sliding_window", "value": 10000, }, "context_management": { "enabled": True, "mode": "token_budget", "value": 100000, "threshold_percent": 75, "strategy": "summarize_and_truncate", "preserve_recent": 6, }, "tool_offload": { "enabled": True, "threshold_tokens": 500, "threshold_bytes": 2000, }, }, ) ``` Set `context_management.value` to a budget below your model's real context window. OmniCoreAgent checks the budget before each model call and reduces the prompt when the threshold is crossed. # Telemetry Events Source: https://docs-omnicoreagent.omnirexfloralabs.com/docs/core-concepts/events Real-time telemetry events for streaming, debugging, and future trace surfaces # Telemetry Events OmniCoreAgent records typed telemetry events for user messages, model calls, tool batches, tool calls, observation handling, subagents, final answers, and background run lifecycle changes. Telemetry is available by default. Simple apps use the in-memory telemetry store automatically. Serving integrations can replay stored telemetry and follow new events through Server-Sent Events. *** ## Quick Start ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} result = await agent.run("Research three AI agent runtimes.", session_id="user_1") events = await agent.get_telemetry_events_after( cursor=None, session_id=result["session_id"], run_id=result["run_id"], ) for event in events: print(event.event_type, event.model_dump()) exact_trace = await agent.get_trace(result["trace_id"]) latest_session_trace = await agent.get_latest_trace(result["session_id"]) run_correlated_trace = await agent.get_trace(run_id=result["run_id"]) normalized_trace = await agent.get_trace(result["trace_id"], normalize=True) ``` *** ## Common Event Types | Event | Description | | -------------------------- | ---------------------------------------------- | | `user_message` | User input received | | `model_call` | Model request started | | `model_response` | Model returned content and usage | | `model_error` | Model call failed | | `agent_step` | ReAct loop step started | | `tool_batch_start` | Parallel tool batch started | | `tool_call` | Individual tool execution started | | `tool_result` | Individual tool returned successfully | | `tool_error` | Tool validation or execution failed | | `observation_pipeline_end` | Tool output was parsed, cleaned, and formatted | | `subagent_spawn` | One or more subagents were delegated work | | `subagent_result` | Subagent returned output | | `subagent_error` | Subagent execution failed | | `guardrail_violation` | Guardrail blocked unsafe input | | `final_answer` | Agent produced final response | | `runtime_error` | Runtime failed | *** ## Streaming ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} session_id = "user_1" run_id = "run_ui_1" cursor = await agent.get_telemetry_stream_cursor(session_id=session_id) task = asyncio.create_task( agent.run("Use tools if needed.", session_id=session_id, run_id=run_id) ) async for event in agent.stream_telemetry_after( cursor=cursor, session_id=session_id, run_id=run_id, ): print(event.event_type) if event.event_type == "final_answer": break await task ``` OmniServe uses the same telemetry stream: * `POST /run` streams telemetry for the run it starts and finishes with `complete`. * `GET /telemetry/events` returns stored telemetry events as JSON. Filter by `trace_id`, `run_id`, `session_id`, `task_id`, or `event_type`. The default event limit is `200`. * `GET /telemetry/events/stream?session_id=...` replays stored telemetry for a session and follows new telemetry. Add `run_id` to isolate one run. * `GET /telemetry/traces/{trace_id}` returns one exact trace. * `GET /telemetry/runs/{run_id}/trace` returns the latest trace correlated to one run. * `GET /telemetry/sessions/{session_id}/trace` returns the latest trace for a session. The older `/events/{session_id}`, `/events/{session_id}/list`, and `/events/{session_id}/trace` routes remain as compact session-oriented aliases. Use `?run_id=...` on those aliases to isolate one run inside a shared session. Trace detail routes return `404` when the requested exact trace, run trace, or session trace does not exist. The trace list route defaults to `limit=100`. Every telemetry event includes its `trace_id`. Runtime-created events also carry correlation metadata such as `run_id`, `session_id`, and `agent_id` when that context exists. Use `trace_id` for exact trace lookup. Use `run_id` to filter or correlate one runtime execution inside a session. If several traces share one `run_id`, the run lookup returns the latest matching trace. Telemetry traces can also be exported. The exporter layer maps normalized OmniCoreAgent traces to OpenTelemetry span records, then sends them through OTLP/HTTP or vendor presets such as LangSmith and Opik. *** ## Background Run Events Background agents expose run-local lifecycle events through `get_run_events(run_id)` and OmniServe's `/background/runs/{run_id}/events`. These events are emitted into telemetry, stored in the manager cache, and mirrored to workspace `events.jsonl` when the task workspace policy allows it. Common background lifecycle names include: | Lifecycle Event | Meaning | | --------------------------- | ----------------------------------------- | | `background_task_scheduled` | A scheduled occurrence created a run. | | `background_run_queued` | A run was created and queued. | | `background_run_claimed` | A worker claimed the run with a lease. | | `background_run_started` | Agent execution started. | | `background_run_heartbeat` | Active worker refreshed the run lease. | | `background_run_retrying` | Failed attempt entered retry state. | | `background_run_recovered` | Expired lease was recovered and requeued. | | `background_run_completed` | Run completed successfully. | | `background_run_failed` | Run failed terminally. | | `background_run_timeout` | Run exceeded its timeout. | | `background_run_cancelled` | Run was cancelled. | | `background_run_skipped` | Overlap policy skipped a scheduled run. | # Guardrails Source: https://docs-omnicoreagent.omnirexfloralabs.com/docs/core-concepts/guardrails Built-in prompt injection protection and safety guardrails # Prompt Injection Guardrails Protect your agents against malicious inputs, jailbreaks, and instruction overrides before they reach the LLM. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} agent_config = { "guardrail_config": { "strict_mode": True, # Block all suspicious inputs "sensitivity": 1.2, # 1.0 default; higher = more sensitive "enable_heuristic_analysis": True } } agent = OmniCoreAgent(..., agent_config=agent_config) # If a threat is detected: # result['response'] -> "I'm sorry, but I cannot process this request..." # result['guardrail_result'] -> Full metadata about the detected threat ``` *** ## Key Protections * **Instruction Overrides**: "Ignore previous instructions..." * **Jailbreaks**: DAN mode, roleplay escapes, etc. * **Toxicity & Abuse**: Built-in pattern recognition. * **Payload Splitting**: Detects fragmented attack attempts. *** ## Configuration Options | Parameter | Type | Default | Description | | ---------------------------- | ------- | ------- | ------------------------------------------------------------------------------------------ | | `strict_mode` | `bool` | `False` | When `True`, any detection (even low confidence) blocks the request. | | `sensitivity` | `float` | `1.0` | Scaling factor for threat scores. Lower reduces sensitivity; higher increases sensitivity. | | `max_input_length` | `int` | `10000` | Maximum allowed query length before blocking. | | `enable_encoding_detection` | `bool` | `True` | Detects base64, hex, and other obfuscation attempts. | | `enable_heuristic_analysis` | `bool` | `True` | Analyzes prompt structure for typical attack patterns. | | `enable_sequential_analysis` | `bool` | `True` | Checks for phased attacks across multiple tokens. | | `enable_entropy_analysis` | `bool` | `True` | Detects high-entropy payloads common in injections. | | `allowlist_patterns` | `list` | `[]` | List of regex patterns that bypass safety checks. | | `blocklist_patterns` | `list` | `[]` | Custom regex patterns to always block. | Always enable guardrails in user-facing applications to prevent prompt injection attacks and ensure agent reliability. # Local Tools Source: https://docs-omnicoreagent.omnirexfloralabs.com/docs/core-concepts/local-tools Register Python functions as AI-callable tools with ToolRegistry # Local Tools System Register any Python function as an AI tool using the `ToolRegistry`. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} import asyncio from omnicoreagent import OmniCoreAgent, ToolRegistry tools = ToolRegistry() @tools.register_tool("get_weather") def get_weather(city: str) -> dict: """Get weather for a city.""" return {"city": city, "temperature": "25C", "condition": "Sunny"} @tools.register_tool("calculate_area") def calculate_area(length: float, width: float) -> dict: """Calculate rectangle area.""" return {"area": length * width, "unit": "square units"} async def main(): agent = OmniCoreAgent( name="tool_agent", system_instruction="Use local tools when they help answer the user.", model_config={"provider": "openai", "model": "gpt-4o"}, local_tools=tools, ) result = await agent.run( "What is the weather in Lagos, and what is the area of a 12 by 8 room?" ) print(result["response"]) await agent.cleanup() asyncio.run(main()) ``` *** ## How It Works 1. **Decorate** any Python function with `@tools.register_tool("tool_name")` 2. **Type hints** are automatically converted into JSON Schema for the LLM 3. **Docstrings** become tool descriptions the LLM uses to decide when to call the tool 4. **Pass** the `ToolRegistry` to your agent via `local_tools=` Workspace files are enabled by default and reserve these built-in tool names: `ls`, `read_file`, `write_file`, `edit_file`, `insert_file`, `delete_file`, `move_file`, `clear_files`, `glob`, and `grep`. Use domain-specific names for application tools, such as `fetch_invoice` or `query_knowledge_base`. *** ## Async Tools Async functions work seamlessly: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} @tools.register_tool("fetch_data") async def fetch_data(url: str) -> dict: """Fetch data from a URL.""" async with httpx.AsyncClient() as client: response = await client.get(url) return response.json() ``` *** ## Class-Based Tools For more complex tools, use a class with a `get_tool()` method: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from omnicoreagent import Tool class DatabaseTool: def __init__(self, connection_string: str): self.conn = connection_string def get_tool(self) -> Tool: return Tool( name="query_db", description="Run a SQL query against the database.", inputSchema={ "type": "object", "properties": { "query": {"type": "string", "description": "SQL query to execute"} }, "required": ["query"] }, function=self._query, ) async def _query(self, query: str) -> dict: # Your database logic return {"status": "success", "data": [...], "message": "Query executed"} ``` Register class-based tools: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} registry = ToolRegistry() registry.register(DatabaseTool(connection_string="postgresql://...")) ``` *** ## Composing Local Tools ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from omnicoreagent import OmniCoreAgent, ToolRegistry tools = ToolRegistry() @tools.register_tool("greet") def greet(name: str) -> str: """Greet someone.""" return f"Hello, {name}!" @tools.register_tool("calculate_total") def calculate_total(price: float, quantity: int) -> float: """Calculate an order total.""" return price * quantity agent = OmniCoreAgent( name="local_tools_agent", system_instruction="Use local tools when they help answer the user.", model_config={"provider": "openai", "model": "gpt-4o"}, local_tools=tools, ) ``` Use Local Tools for custom business logic, internal APIs, or Python functionality that belongs to your application. Use MCP for shared external services. # MCP Tools Source: https://docs-omnicoreagent.omnirexfloralabs.com/docs/core-concepts/mcp Connect MCP server tools over stdio, SSE, and Streamable HTTP # MCP Tools MCP connects external MCP server tools into OmniCoreAgent's tool runtime. Those tools run beside local Python tools, workspace tools, artifact tools, skills, subagent tools, and other harness tools. The agent sees one available tool surface; the runtime handles where each tool came from. *** ## Transport Types ### 1. stdio โ€” Local MCP servers Process communication with local CLI tools: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} { "name": "filesystem", "transport_type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home"] } ``` ### 2. streamable\_http โ€” Remote servers with HTTP streaming ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} # With Bearer Token { "name": "github", "transport_type": "streamable_http", "url": "http://localhost:8080/mcp", "headers": { "Authorization": "Bearer your-token" }, "timeout": 60 } # With OAuth 2.0 (auto-starts callback server on localhost:3000) { "name": "oauth_server", "transport_type": "streamable_http", "auth": { "method": "oauth" }, "url": "http://localhost:8000/mcp" } ``` ### 3. sse โ€” Server-Sent Events ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} { "name": "sse_server", "transport_type": "sse", "url": "http://localhost:3000/sse", "headers": { "Authorization": "Bearer token" }, "timeout": 60, "sse_read_timeout": 120 } ``` *** ## Complete Example with All 3 Transport Types ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} agent = OmniCoreAgent( name="multi_mcp_agent", system_instruction="You have access to filesystem, GitHub, and live data.", model_config={"provider": "openai", "model": "gpt-4o"}, mcp_tools=[ # 1. stdio - Local filesystem { "name": "filesystem", "transport_type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home"] }, # 2. streamable_http - Remote API (supports Bearer token or OAuth) { "name": "github", "transport_type": "streamable_http", "url": "http://localhost:8080/mcp", "headers": {"Authorization": "Bearer github-token"}, "timeout": 60 }, # 3. sse - Real-time streaming { "name": "live_data", "transport_type": "sse", "url": "http://localhost:3000/sse", "headers": {"Authorization": "Bearer token"}, "sse_read_timeout": 120 } ] ) await agent.connect_mcp_servers() tools = await agent.list_all_available_tools() # All MCP + local tools result = await agent.run("List all Python files and get latest commits") ``` *** ## Transport Comparison | Transport | Use Case | Auth Methods | | ----------------- | ---------------------------- | ---------------------------- | | `stdio` | Local MCP servers, CLI tools | None (local process) | | `streamable_http` | Remote APIs, cloud services | Bearer token, OAuth 2.0 | | `sse` | Real-time data, streaming | Bearer token, custom headers | Use MCP when the agent needs tools hosted by an MCP server. Choose `stdio` for local CLI servers, `streamable_http` for HTTP MCP servers, and `sse` for Server-Sent Events transports. # Multi-Tier Memory Source: https://docs-omnicoreagent.omnirexfloralabs.com/docs/core-concepts/memory MemoryRouter backends with runtime switching โ€” in-memory, Redis, MongoDB, and SQL database storage # Multi-Tier Memory System **Runtime-switchable memory backends** โ€” start in memory, switch to Redis, MongoDB, or SQL database storage when the application needs persistence. *** ## Quick Start The default `in_memory` backend is enough for local development and tests: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} import asyncio from omnicoreagent import OmniCoreAgent, MemoryRouter async def main(): agent = OmniCoreAgent( name="memory_agent", system_instruction="Remember useful details inside the active session.", model_config={"provider": "openai", "model": "gpt-4o"}, memory_router=MemoryRouter("in_memory"), ) await agent.run("My project is called Atlas.", session_id="user_123") result = await agent.run("What is my project called?", session_id="user_123") print(result["response"]) await agent.cleanup() asyncio.run(main()) ``` Install the backend extra before using a durable store: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} pip install "omnicoreagent[redis]" pip install "omnicoreagent[mongodb]" pip install "omnicoreagent[postgres]" ``` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from omnicoreagent import OmniCoreAgent, MemoryRouter # Start with Redis agent = OmniCoreAgent( name="my_agent", system_instruction="Remember useful details inside the active session.", memory_router=MemoryRouter("redis"), model_config={"provider": "openai", "model": "gpt-4o"} ) # Switch at runtime โ€” no restart needed! await agent.switch_memory_store("mongodb") # Switch to MongoDB await agent.switch_memory_store("sql") # Switch to SQL database storage await agent.switch_memory_store("in_memory") # Switch to in-memory await agent.switch_memory_store("redis") # Back to Redis ``` *** ## Available Backends | Backend | Use Case | Environment Variable | | ----------- | --------------------------- | -------------------- | | `in_memory` | Fast development | โ€” | | `redis` | Production persistence | `REDIS_URL` | | `sql` | SQLAlchemy database storage | `DATABASE_URL` | | `mongodb` | Document storage | `MONGODB_URI` | *** ## Conversation Summarization OmniCoreAgent includes **automatic conversation summarization** to manage long conversation histories efficiently. When enabled, older messages are condensed into summaries, keeping context while reducing token usage. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from omnicoreagent import OmniCoreAgent, MemoryRouter memory_router = MemoryRouter("redis") memory_config = { "mode": "sliding_window", # or "token_budget" "value": 10, # Keep last 10 messages, or max tokens in token_budget mode "summary": { "enabled": True, "retention_policy": "keep" # Options: "keep" or "delete" } } agent = OmniCoreAgent( name="summarizing_agent", memory_router=memory_router, model_config={"provider": "openai", "model": "gpt-4o"}, agent_config={"memory_config": memory_config}, ) ``` ### Summarization Modes | Mode | Description | Best For | | ---------------- | ------------------------------------------ | ----------------------- | | `sliding_window` | Keep last N messages, summarize older ones | Predictable memory size | | `token_budget` | Keep messages within token limit | Cost optimization | ### Retention Policies | Policy | Behavior | | -------- | -------------------------------------------------- | | `keep` | Mark summarized messages as inactive (recoverable) | | `delete` | Permanently remove summarized messages | ### How It Works 1. When conversation exceeds configured limit โ†’ summarization triggers 2. Older messages are sent to LLM for summary generation 3. Summary replaces older messages in active context 4. Original messages are retained (with `"keep"`) or deleted per policy Enable summarization for long-running conversations (support bots, research assistants) to maintain context while controlling costs. Use `sliding_window` for predictable behavior, `token_budget` for strict cost control. # OmniCoreAgent Source: https://docs-omnicoreagent.omnirexfloralabs.com/docs/core-concepts/overview The primary agent harness API: model, loop, tools, memory, workspace, guardrails, events, and runtime options # OmniCoreAgent `OmniCoreAgent` is the main entry point for the harness. It wraps a model with the runtime pieces needed to execute real tasks: a reasoning loop, tool routing, parallel tool batches, structured observations, memory, workspace files, guardrails, events, and production harness extensions. Use it when you want one agent object that starts small and grows into a production runtime without rebuilding the application around a different API. For the full implementation-backed map of what OmniCoreAgent adds around the model, read [Agent Harness](/docs/core-concepts/agent-harness). *** ## Minimal Agent ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} import asyncio from omnicoreagent import OmniCoreAgent async def main(): agent = OmniCoreAgent( name="my_assistant", system_instruction="You are a helpful assistant.", model_config={"provider": "openai", "model": "gpt-4o"}, ) result = await agent.run("Hello!") print(result["response"]) await agent.cleanup() asyncio.run(main()) ``` This gives you the core harness loop, session memory, workspace files, guardrails, events, metrics, and cleanup lifecycle. Heavier capabilities are enabled explicitly through `agent_config` or installable extras. *** ## What The Harness Owns | Area | Responsibility | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | **Reasoning loop** | Builds the prompt, calls the model, parses tool calls, observes results, and stops with a final response. | | **Tool runtime** | Combines local tools, MCP tools, skills, workspace tools, subagent tools, and BM25 retrieval when enabled. | | **Parallel execution** | Runs independent tool calls in one batch and returns a single structured observation. | | **Observation pipeline** | Normalizes tool outputs, applies guardrails, and offloads large results to workspace files when configured. | | **Context management** | Checks message history before each model call and automatically truncates or summarizes when the configured budget threshold is crossed. | | **Memory** | Stores and retrieves session history through the configured memory router. | | **Workspace** | Provides agent-accessible files for notes, scratchpads, artifacts, subagent output, and tool offloads. | | **Telemetry and Traces** | Emits typed events, stores traces, streams progress, and exports traces through OTLP-compatible adapters. | | **Serving** | Runs the agent through OmniServe when you need REST/SSE endpoints. | *** ## Defaults And Opt-In Capabilities OmniCoreAgent keeps the default path light. Production features are enabled by configuration or installed as extras when the workload needs them. | Capability | Default | How To Enable | | ---------------------------- | ------------------ | ------------------------------------------------------------- | | Harness loop | On | Always part of `OmniCoreAgent`. | | Session memory | On | Uses the default memory router unless you pass another one. | | Workspace files | On | `enable_workspace_files=True` by default. | | Guardrails | On | `guardrail_mode="full"` by default. | | Context management | Off | `agent_config={"context_management": {"enabled": True}}` | | Tool output offload | Off | `agent_config={"tool_offload": {"enabled": True}}` | | BM25 tool retrieval | Off | `agent_config={"enable_advanced_tool_use": True}` | | Dynamic subagents | Off | `agent_config={"enable_subagents": True}` | | Agent skills | Off | `agent_config={"enable_agent_skills": True}` | | Redis/Postgres/MongoDB/S3/R2 | Installable extras | Install the matching package extra and configure the backend. | When dynamic subagents are enabled, workspace files are enabled automatically. Subagents need a shared file surface for outputs, todos, notes, and task artifacts that the lead agent reads back. *** ## Parameters | Parameter | Type | Description | | -------------------- | ------------------------ | ----------------------------------------------------------------------------------- | | `name` | `str` | Agent name used for session tracking, telemetry, metrics, and logs. | | `system_instruction` | `str` | The high-level role, objective, or policy for the agent. | | `model_config` | `dict` or `ModelConfig` | LLM provider and model configuration. | | `mcp_tools` | `list` | Optional MCP tool server definitions. OmniCoreAgent loads tools from these servers. | | `local_tools` | `ToolRegistry` or `list` | Optional Python/application-owned tools. | | `sub_agents` | `list` | Optional predefined agents available for delegation. | | `agent_config` | `dict` or `AgentConfig` | Runtime behavior: steps, timeouts, context, offload, subagents, skills, workspace. | | `memory_router` | `MemoryRouter` | Optional conversation memory backend. Defaults to in-memory. | *** ## Full Harness Configuration ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from omnicoreagent import MemoryRouter, OmniCoreAgent, ToolRegistry tools = ToolRegistry() agent = OmniCoreAgent( name="production_agent", system_instruction="You are a production research agent.", model_config={"provider": "openai", "model": "gpt-4o"}, local_tools=tools, mcp_tools=[...], memory_router=MemoryRouter("redis"), agent_config={ "max_steps": 20, "tool_call_timeout": 30, "enable_advanced_tool_use": True, "enable_subagents": True, "enable_agent_skills": True, "enable_workspace_files": True, "memory_config": { "mode": "sliding_window", "value": 10000, "summary": { "enabled": True, "retention_policy": "keep", }, }, "context_management": { "enabled": True, "mode": "token_budget", "value": 100000, "threshold_percent": 75, "strategy": "summarize_and_truncate", "preserve_recent": 6, }, "tool_offload": { "enabled": True, "threshold_tokens": 500, "threshold_bytes": 2000, }, "guardrail_config": {"strict_mode": True}, }, ) ``` *** ## Core Methods ### `run()` Execute a task with the agent. Pass a `session_id` when you want continuity across calls. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} result = await agent.run("What is the weather today?", session_id="user_1") print(result["response"]) ``` `run()` returns a dictionary with the response, session ID, agent name, and request metrics. ### `connect_mcp_servers()` Connect all configured MCP tool servers. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} await agent.connect_mcp_servers() ``` ### `list_all_available_tools()` Return all currently available tools from MCP, local tools, skills, workspace tools, and harness tools. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} tools = await agent.list_all_available_tools() ``` ### `cleanup()` Close MCP connections and release runtime state. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} await agent.cleanup() ``` *** ## Session Management ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} history = await agent.get_session_history("user_1") await agent.clear_session_history("user_1") await agent.clear_session_history() # clear all sessions for this agent ``` *** ## Runtime Switching Switch configured memory backends without rebuilding the agent object: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} await agent.switch_memory_store("mongodb") await agent.switch_memory_store("sql") await agent.switch_memory_store("redis") await agent.get_memory_store_type() ``` *** ## Best Practices * Use `await agent.cleanup()` when the application shuts down, especially if MCP tools are connected. * Use stable `session_id` values, such as your user or task IDs, when you need continuity. * Enable context management and tool offloading for long tasks, research agents, coding agents, and agents that call large-output tools. * Enable BM25 retrieval when your tool list is too large to place fully in the prompt. * Enable subagents when a task naturally splits into focused work units whose outputs belong in the workspace for lead-agent synthesis. # Agent Skills Source: https://docs-omnicoreagent.omnirexfloralabs.com/docs/core-concepts/skills Self-contained capability packages for specialized agent tasks # Agent Skills System OmniCoreAgent supports the **Agent Skills** specification โ€” self-contained capability packages that provide specialized knowledge, executable scripts, and comprehensive documentation for agents. ## What is an Agent Skill? An agent skill is a directory following a specific structure that packages everything an agent needs to perform specialized tasks. Skills allow you to build portable, reusable capabilities that can be shared across agents and projects. ### Directory Structure ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} .agents/skills/my-skill-name/ โ”œโ”€โ”€ SKILL.md # The "Activation" document (instructions + metadata) โ”œโ”€โ”€ scripts/ # Multi-language executable scripts (Python, JS, etc.) โ”œโ”€โ”€ references/ # Deep-dive documentation and research โ””โ”€โ”€ assets/ # Templates, examples, and other resources ``` *** ## Configuration Enable skill discovery in the agent configuration: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} agent_config = { "enable_agent_skills": True # Enable discovery and tools for skills } agent = OmniCoreAgent( ... agent_config=agent_config ) ``` *** ## How It Works 1. **Discovery**: The agent automatically scans the `.agents/skills/` directory at startup. 2. **Activation**: The agent is instructed to read the `SKILL.md` file first to understand the skill's capabilities and how to use them. 3. **Execution**: The agent uses specialized tools to interact with skill files and run scripts. ### Skill-Specific Tools | Tool | Description | | ------------------ | ------------------------------------------------------------- | | `read_skill_file` | Access any file within a skill (docs, references, etc.). | | `run_skill_script` | Execute bundled scripts with automatic interpreter detection. | *** ## Polyglot Script Execution The `run_skill_script` tool supports multiple languages, allowing you to bridge different ecosystems: * **Python** (.py) * **JavaScript / Node.js** (.js) * **TypeScript** (.ts) * **Ruby** (.rb) * **Bash / Shell** (.sh) The runtime automatically detects the correct interpreter and passes arguments from the agent to your script. *** ## Creating Your Own Skills To learn how to create your own agent skills and follow the official specification, visit [agentskills.io](https://agentskills.io/). ### Tips for Skill Authors * **Clear Metadata**: Ensure your `SKILL.md` has a clear "Purpose" and "Usage" section. * **Example Driven**: Include examples of successful tool calls or script executions. * **Portable Scripts**: Avoid hardcoded paths in your scripts; use the environment and arguments provided by the agent. # Subagents Source: https://docs-omnicoreagent.omnirexfloralabs.com/docs/core-concepts/sub-agents Dynamic and explicit task delegation inside OmniCoreAgent # Subagents OmniCoreAgent supports subagents as part of the core harness. A lead agent can spawn focused workers dynamically with `spawn_subagents`, or you can attach explicit subagents when you want a fixed team. Workers can execute any assigned task their tools support: research, coding, review, data work, writing, verification, or operational actions. ## Why Use Sub-Agents? * **Modular Design**: Build and test small, expert agents individually before integrating them. * **Improved Accuracy**: Specialized agents (e.g., a "Math Expert" or "Code Auditor") are less likely to hallucinate in their specific domain. * **Tool Management**: Avoid cluttering a single agent's prompt with hundreds of tools. Instead, give each sub-agent only the tools it needs. * **Parallel Work**: Use one `spawn_subagents` call with multiple specs when independent tasks can run at the same time. * **Workspace Continuity**: Dynamic subagents write output to workspace files, so outputs survive context compression and tool offloading. *** ## Dynamic Subagents Enable dynamic subagents directly on OmniCoreAgent: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from omnicoreagent import OmniCoreAgent agent = OmniCoreAgent( name="task_manager", system_instruction="You coordinate complex work and synthesize outputs.", model_config={"provider": "openai", "model": "gpt-4o"}, agent_config={ "enable_subagents": True, "context_management": {"enabled": True}, "tool_offload": {"enabled": True}, }, ) ``` Workspace files are available by default, and `enable_subagents` also keeps them enabled for worker output. Dynamic workers are expected to save output with `write_file`, and the lead agent reads those paths with `read_file` before synthesizing. ### `spawn_subagents` `spawn_subagents` accepts one JSON array. Use one item for one worker, or many items for parallel workers. ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} [ { "name": "api", "role": "API reviewer", "task": "Review API error handling and write concrete risks.", "output_path": "/workspace/product_audit/subagent_api/output.md" }, { "name": "tests", "role": "Test reviewer", "task": "Review coverage gaps and write recommended test cases.", "output_path": "/workspace/product_audit/subagent_tests/output.md" } ] ``` Spawned workers inherit the parent's model, MCP tools, user local tools, workspace files, context management, and tool offloading. They do not inherit the lead agent's `spawn_subagents` tool, which keeps delegation controlled by the lead agent. *** ## Explicit Subagents Use explicit subagents when the team is known upfront and each child agent has a stable role or custom tool set. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} research_agent = OmniCoreAgent( name="researcher", system_instruction="You specialize in web research and summarization.", model_config={"provider": "openai", "model": "gpt-4o"}, ) code_agent = OmniCoreAgent( name="coder", system_instruction="You are an expert Python developer.", model_config={"provider": "openai", "model": "gpt-4o"}, ) parent_agent = OmniCoreAgent( name="manager", system_instruction="You manage a team of specialists.", model_config={"provider": "openai", "model": "gpt-4o"}, sub_agents=[research_agent, code_agent], ) ``` When a parent agent has explicit subagents, it is given tools to communicate with them: | Tool | Action | | ---------------- | -------------------------------------------------------------- | | `call_sub_agent` | Send a specific task to a child agent and wait for the result. | *** ## Example Workflow 1. **User Query**: "Research the latest AI news and write a Python script for a news aggregator." 2. **Manager (Parent)**: Recognizes this requires research and coding. 3. **Manager**: Calls `spawn_subagents` with research and coding workers, or calls explicit child agents. 4. **Researcher (Sub)**: Performs web search, returns summaries. 5. **Manager**: Receives summaries, then calls `code_agent` with "Write a Python aggregator using this data: \[summaries]". 6. **Coder (Sub)**: Writes the code, returns it. 7. **Manager**: Synthesizes the final response to the user. *** ## Best Practices * **Use One Spawn Call**: When tasks are independent, put every worker spec in one `spawn_subagents` array so they run in parallel. * **Write to Workspace Files**: Give each worker a clear `output_path` under `/workspace/{task_name}/...`. * **Read Before Synthesis**: After workers finish, read every output path before producing the final answer. * **Explicit Instructions**: For fixed subagents, briefly describe each subagent's expertise in the parent instruction. * **Limit Depth**: While hierarchical agents are powerful, avoid nesting agents too deep (e.g., Parent -> Child -> Grandchild) to prevent excessive latency and token usage. * **Keep Workers Focused**: Do not give one worker the whole task. Give it a bounded role and output contract. # Workflow Agents Source: https://docs-omnicoreagent.omnirexfloralabs.com/docs/core-concepts/workflows Sequential, parallel, and router workflows for multi-agent orchestration # Workflow Agents Multi-agent orchestration patterns for complex task pipelines: **Sequential**, **Parallel**, and **Router** agents. *** ## Sequential Agent Run agents in order where each agent's output feeds into the next: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from omnicoreagent import OmniCoreAgent, SequentialAgent # Define specialized agents researcher = OmniCoreAgent( name="researcher", system_instruction="Research the given topic thoroughly.", model_config={"provider": "openai", "model": "gpt-4o"} ) writer = OmniCoreAgent( name="writer", system_instruction="Write a report based on research findings.", model_config={"provider": "openai", "model": "gpt-4o"} ) reviewer = OmniCoreAgent( name="reviewer", system_instruction="Review and improve the report.", model_config={"provider": "openai", "model": "gpt-4o"} ) # Chain them together pipeline = SequentialAgent( sub_agents=[researcher, writer, reviewer], model_config={"provider": "openai", "model": "gpt-4o"} ) result = await pipeline.run(task="Write a report on quantum computing") ``` *** ## Parallel Agent Run multiple agents simultaneously for independent tasks: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from omnicoreagent import OmniCoreAgent, ParallelAgent code_agent = OmniCoreAgent( name="code_reviewer", system_instruction="Review code for bugs.", model_config={"provider": "openai", "model": "gpt-4o"} ) security_agent = OmniCoreAgent( name="security_reviewer", system_instruction="Check for security vulnerabilities.", model_config={"provider": "openai", "model": "gpt-4o"} ) perf_agent = OmniCoreAgent( name="performance_reviewer", system_instruction="Identify performance issues.", model_config={"provider": "openai", "model": "gpt-4o"} ) # Run all three simultaneously parallel = ParallelAgent( sub_agents=[code_agent, security_agent, perf_agent], model_config={"provider": "openai", "model": "gpt-4o"} ) result = await parallel.run(task="Review this codebase") ``` *** ## Router Agent Intelligently route tasks to the best-suited specialist: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from omnicoreagent import OmniCoreAgent, RouterAgent code_agent = OmniCoreAgent( name="code_expert", system_instruction="You handle coding tasks.", model_config={"provider": "openai", "model": "gpt-4o"} ) data_agent = OmniCoreAgent( name="data_expert", system_instruction="You handle data analysis.", model_config={"provider": "openai", "model": "gpt-4o"} ) research_agent = OmniCoreAgent( name="research_expert", system_instruction="You handle research tasks.", model_config={"provider": "openai", "model": "gpt-4o"} ) # Router: Intelligent task routing router = RouterAgent( sub_agents=[code_agent, data_agent, research_agent], model_config={"provider": "openai", "model": "gpt-4o"} ) result = await router.run(task="Find and summarize AI research") ``` *** ## When to Use Each Pattern | Pattern | Best For | Example | | ------------------- | --------------------------------------------------------------- | ------------------------------------ | | **SequentialAgent** | Tasks that depend on each other (output of one โ†’ input of next) | Research โ†’ Write โ†’ Review | | **ParallelAgent** | Independent tasks that can run simultaneously for speed | Code + Security + Performance review | | **RouterAgent** | Intelligent task routing to specialized agents | Route "analyze sales" to data agent | Combine patterns for complex workflows. For example, use a Router to select a pipeline, which then runs a Sequential or Parallel agent. # Workspace Files Source: https://docs-omnicoreagent.omnirexfloralabs.com/docs/core-concepts/workspace-files Persistent workspace files inside the active local, S3, or R2 workspace # Workspace Files > Workspace files give agents durable file-style storage for notes, scratchpads, logs, todos, task progress, generated code, and research files. The workspace has two clear areas: * `files/` โ€” agent-managed files for scratchpads, todos, progress, preferences, notes, subagent outputs, and generated work. * `artifacts/` โ€” runtime-managed tool output artifacts created by tool offloading and read back with artifact tools. There is no separate workspace-files backend: choose the workspace backend once, and both areas use that same local, S3, or R2 workspace. *** ## Workspace Backends | Backend | Use Case | Benefits | | ------- | ------------------------------ | -------------------------------------- | | `local` | Development, single-server | Zero config, instant setup | | `s3` | Production, AWS infrastructure | Scalable, durable, global access | | `r2` | Production, edge computing | Zero egress fees, Cloudflare ecosystem | *** ## Quick Setup Workspace files default to local disk. Choose S3 or R2 only when the whole workspace should live in cloud storage. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} export OMNICOREAGENT_WORKSPACE_BACKEND=local export OMNICOREAGENT_WORKSPACE_DIR=./workspace ``` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} import asyncio from omnicoreagent import OmniCoreAgent async def main(): agent = OmniCoreAgent( name="workspace_agent", system_instruction=( "Use workspace files for notes, progress, and final artifacts." ), model_config={"provider": "openai", "model": "gpt-4o"}, agent_config={"enable_workspace_files": True}, ) result = await agent.run( "Create a project note at notes/plan.md with three checklist items, " "then read it back." ) print(result["response"]) await agent.cleanup() asyncio.run(main()) ``` With the local backend, workspace command tools write under: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} ./workspace/files/ ``` For example, the prompt above creates `./workspace/files/notes/plan.md`. Cloud workspace storage uses the S3/R2 extra: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} pip install "omnicoreagent[s3]" ``` *** ## Environment Variables ### Local ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} OMNICOREAGENT_WORKSPACE_BACKEND=local OMNICOREAGENT_WORKSPACE_DIR=./workspace ``` ### S3 ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} OMNICOREAGENT_WORKSPACE_BACKEND=s3 OMNICOREAGENT_WORKSPACE_PREFIX=workspace AWS_S3_BUCKET=my-agent-workspace AWS_ACCESS_KEY_ID=AKIA... AWS_SECRET_ACCESS_KEY=your-secret AWS_REGION=us-east-1 # optional ``` ### R2 ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} OMNICOREAGENT_WORKSPACE_BACKEND=r2 OMNICOREAGENT_WORKSPACE_PREFIX=workspace R2_BUCKET_NAME=my-agent-workspace R2_ACCOUNT_ID=your-cloudflare-account-id R2_ACCESS_KEY_ID=your-r2-key R2_SECRET_ACCESS_KEY=your-r2-secret ``` *** ## Workspace Command Tools OmniCoreAgent exposes these tools for the `files/` area: | Tool | Purpose | | ------------- | ----------------------------------------------- | | `ls` | List files and directories | | `read_file` | Read file contents, like workspace-scoped `cat` | | `write_file` | Create, append, or overwrite files | | `edit_file` | Find and replace text within files | | `insert_file` | Insert text at specific line numbers | | `delete_file` | Delete files or directories | | `move_file` | Rename or move files | | `clear_files` | Clear the workspace files area | | `glob` | Find files by glob pattern | | `grep` | Search text inside workspace files | These are workspace tools, not host shell tools. They operate through the active workspace backend, so the same tool calls work on local disk, S3, and R2. When workspace files are enabled, these tool names are reserved for the harness. Use distinct names for application-owned local tools. *** ## Backend Behavior | Feature | Local | S3 | R2 | | -------------------------------- | ------- | --- | --- | | Persists across process restarts | Yes | Yes | Yes | | Works without cloud credentials | Yes | No | No | | Shared across multiple machines | No | Yes | Yes | | Fits single-server development | Yes | Yes | Yes | | Fits distributed deployments | Limited | Yes | Yes | | Uses the same workspace tools | Yes | Yes | Yes | *** ## Use Cases | Use Case | Recommended Backend | | ------------------------- | ------------------- | | Local development | `local` | | Single-server production | `local` or `s3` | | Multi-server / Kubernetes | `s3` or `r2` | | Edge computing / Workers | `r2` | | Cost-sensitive workloads | `r2` (zero egress) | *** ## Example: Research Agent with Cloud Workspace ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} import os # Set environment for S3 os.environ["OMNICOREAGENT_WORKSPACE_BACKEND"] = "s3" os.environ["AWS_S3_BUCKET"] = "research-agent-workspace" os.environ["AWS_ACCESS_KEY_ID"] = "AKIA..." os.environ["AWS_SECRET_ACCESS_KEY"] = "..." os.environ["AWS_REGION"] = "us-east-1" os.environ["AWS_ENDPOINT_URL"] = "https://s3.amazonaws.com" # Optional agent = OmniCoreAgent( name="workspace_agent", system_instruction="Save durable notes, logs, task progress, and final output to workspace files.", model_config={"provider": "openai", "model": "gpt-4o"}, agent_config={ "max_steps": 50, } ) # Agent can now save research notes that persist across: # - Server restarts # - Multiple instances # - Different geographic locations result = await agent.run( "Research recent AI developments and save a summary to /notes/ai_trends.md" ) ``` Use `local` for development. Use `s3` or `r2` when the whole workspace should persist across server restarts, multiple agent instances, or production deployments. # Installation Source: https://docs-omnicoreagent.omnirexfloralabs.com/docs/getting-started/installation Install OmniCoreAgent and get set up in minutes # Installation ## Prerequisites Before installing OmniCoreAgent, ensure you have the following: **System Requirements:** * **Python 3.10+** (Python 3.11+ recommended) * **LLM API key** from any supported provider (OpenAI, Anthropic, Google, etc.) * **UV package manager** (recommended) or pip ### Check Python Version ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} python --version # Should show Python 3.10.0 or higher ``` ### Install UV (Recommended) UV is faster than pip and handles dependencies more reliably: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -LsSf https://astral.sh/uv/install.sh | sh ``` ```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}} powershell -c "irm https://astral.sh/uv/install.ps1 | iex" ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} pip install uv ``` *** ## Installation Methods ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} uv add omnicoreagent ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} pip install omnicoreagent ``` For development or latest features: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} git clone https://github.com/omnirexflora-labs/omnicoreagent.git cd omnicoreagent uv sync ``` *** ## Optional Production Extras The base install stays focused on the core agent harness. Add heavier production integrations only when your agent uses them: | Extra | Installs | | ----------- | --------------------------------------------------- | | `redis` | Redis memory and Redis-backed background task state | | `postgres` | SQLAlchemy and PostgreSQL driver | | `mongodb` | MongoDB async and sync drivers | | `s3` | AWS S3 and Cloudflare R2 workspace storage | | `serve` | OmniServe REST/SSE API server | | `tokenizer` | tiktoken token counting | | `otel` | OpenTelemetry OTLP/HTTP trace export | | `langsmith` | LangSmith trace export through OTLP | | `opik` | Comet Opik trace export through OTLP | | `all` | Every optional integration | ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} pip install "omnicoreagent[redis]" pip install "omnicoreagent[serve]" pip install "omnicoreagent[otel]" pip install "omnicoreagent[all]" ``` With UV: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} uv add "omnicoreagent[redis]" ``` *** ## Verify Installation After installation, verify that you can import the package: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} python -c "import omnicoreagent; print(omnicoreagent.__version__)" ``` *** ## Troubleshooting **Error**: `OmniCoreAgent requires Python 3.10+` **Solution**: Upgrade your Python version: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} # Check available Python versions python3.11 --version # Use specific Python version with UV uv python install 3.11 uv add omnicoreagent ``` **Error**: Permission denied during installation **Solution**: Use user installation: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} pip install --user omnicoreagent ``` **Error**: `ImportError: Redis memory requires optional dependency 'redis'` **Solution**: Install the matching extra: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} pip install "omnicoreagent[redis]" ``` Use `postgres`, `mongodb`, `s3`, `serve`, `tokenizer`, `otel`, `langsmith`, `opik`, or `all` for other optional integrations. If you encounter issues: 1. Search [existing issues](https://github.com/omnirexflora-labs/omnicoreagent/issues) 2. Create a [new issue](https://github.com/omnirexflora-labs/omnicoreagent/issues/new) with: * Your operating system * Python version * Installation method used * Complete error message *** ## Next Steps Build your first agent in under 30 seconds Learn about memory, events, and tools Environment variables and agent settings # Quick Start Source: https://docs-omnicoreagent.omnirexfloralabs.com/docs/getting-started/quickstart Build your first OmniCoreAgent and understand what the harness gives you # Quick Start This guide creates the smallest useful OmniCoreAgent: one model, one harness runtime, one task, one local tool, and one stable session. The core install stays light. Redis, PostgreSQL, MongoDB, S3/R2, OmniServe, and background scheduling install as extras when the agent needs them. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} pip install omnicoreagent ``` Export the model key for the provider you choose: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} export LLM_API_KEY=your_api_key_here ``` OmniCoreAgent uses `LLM_API_KEY` as the single public API-key variable. Choose the provider with `model_config["provider"]`. See [Model Support](/docs/how-to-guides/models) for supported provider names. Create `hello_agent.py`: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} import asyncio from omnicoreagent import OmniCoreAgent async def main(): agent = OmniCoreAgent( name="my_agent", system_instruction="You are a helpful assistant.", model_config={"provider": "openai", "model": "gpt-4o"}, ) result = await agent.run("Hello, what can you do?") print(result["response"]) await agent.cleanup() if __name__ == "__main__": asyncio.run(main()) ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} python hello_agent.py ``` You now have an agent with the core harness loop, session memory, workspace files, guardrails, events, metrics, and cleanup lifecycle. *** ## Add Local Tools Local tools are normal Python functions registered through `ToolRegistry`. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} import asyncio from omnicoreagent import OmniCoreAgent, ToolRegistry tools = ToolRegistry() @tools.register_tool("get_weather") def get_weather(city: str) -> dict: """Get current weather for a city.""" return {"city": city, "temp": "22C", "condition": "Sunny"} async def main(): agent = OmniCoreAgent( name="weather_agent", system_instruction="Use tools when they help answer the user.", model_config={"provider": "openai", "model": "gpt-4o"}, local_tools=tools, ) result = await agent.run("What's the weather in Tokyo?") print(result["response"]) await agent.cleanup() asyncio.run(main()) ``` *** ## Keep Continuity With Session IDs Agents keep continuity when you provide a stable `session_id`: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} await agent.run("My name is Abiola.", session_id="user_123") result = await agent.run("What is my name?", session_id="user_123") print(result["response"]) ``` The default memory backend is in-memory and works for local development. Use Redis, MongoDB, or SQL database storage when conversation history must survive process restarts. *** ## Common First-Run Errors Export the model key before running your script: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} export LLM_API_KEY=your_api_key_here ``` OmniCoreAgent examples use `LLM_API_KEY` as the single public model API-key variable. Set both fields: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} model_config={"provider": "openai", "model": "gpt-4o"} ``` See [Models](/docs/how-to-guides/models) for supported provider names. Install the extra for the backend you are using: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} pip install "omnicoreagent[redis]" pip install "omnicoreagent[mongodb]" pip install "omnicoreagent[serve]" ``` The base quickstart does not require these extras. *** ## Next: Add MCP Tools MCP servers are external tool providers. OmniCoreAgent connects to them and loads their tools into the same runtime view as local tools. This optional example uses Node.js and `npx` because the filesystem MCP server is published as an npm package: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} import asyncio from omnicoreagent import OmniCoreAgent async def main(): agent = OmniCoreAgent( name="fs_agent", system_instruction="Inspect files when the task needs filesystem context.", model_config={"provider": "openai", "model": "gpt-4o"}, mcp_tools=[ { "name": "filesystem", "transport_type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"], } ], ) await agent.connect_mcp_servers() result = await agent.run("List files in /tmp") print(result["response"]) await agent.cleanup() asyncio.run(main()) ``` MCP connects external MCP server tools into OmniCoreAgent's tool runtime. Those tools run beside local tools, workspace tools, artifact tools, skills, and harness tools. *** ## Next: Turn On Heavier Harness Features For longer tasks, enable the heavier harness features explicitly: automatic context control before each model call, tool output offloading into the workspace, BM25 tool retrieval, subagents, and skills. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} agent = OmniCoreAgent( name="research_agent", system_instruction=( "Use tools in parallel when the calls are independent. Write useful " "notes and outputs to the workspace when the task is long." ), model_config={"provider": "openai", "model": "gpt-4o"}, local_tools=tools, agent_config={ "max_steps": 20, "context_management": {"enabled": True}, "tool_offload": {"enabled": True}, "enable_advanced_tool_use": True, "enable_subagents": True, "enable_agent_skills": True, }, ) ``` When `enable_subagents` is true, workspace files are enabled automatically so workers write outputs that the lead agent reads back. *** ## Next Steps Register Python functions as tools. Store notes, artifacts, scratchpads, and tool offloads. Serve this agent through REST and SSE. Configure context, tool offload, memory, events, and workspace storage. Ask questions against the official docs from your editor or AI tool. Understand the runtime layers and request flow. # Use Docs With AI Tools Source: https://docs-omnicoreagent.omnirexfloralabs.com/docs/getting-started/use-docs-with-ai-tools Use OmniCoreAgent docs with Ask AI, llms.txt, hosted MCP, Cursor, VS Code, ChatGPT, Claude, and Perplexity # Use Docs With AI Tools OmniCoreAgent docs are written for people and AI coding tools. Use this page when you want the docs inside your editor, chat session, or agent workflow. AI tools are a faster way to navigate the docs. They do not replace source-code verification for production changes. *** ## Ask AI In The Docs Use the Ask AI action in the docs header to ask questions against the official OmniCoreAgent documentation. Good prompts: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} Show me the smallest OmniCoreAgent with one local tool. ``` ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} Explain memory vs workspace vs task store. ``` ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} Build an OmniServe API with auth and rate limiting. ``` ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} Which config enables context management and tool offload? ``` Ask AI should answer with the docs as source context. If a feature is not documented, verify in the source code or open an issue. *** ## Copy Or View A Page As Markdown Use the contextual menu on any docs page to copy the page as Markdown or view the raw Markdown source. This is useful when you want to paste one exact docs page into ChatGPT, Claude, Perplexity, Cursor, or another coding agent. Best use cases: * explain one API surface * convert one example to your app * compare memory, workspace, and task-store behavior * ask for a migration checklist from a specific docs page *** ## Use `/llms.txt` Mintlify publishes an AI-readable docs index at: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} https://docs-omnicoreagent.omnirexfloralabs.com/llms.txt ``` Use this when an AI tool asks for a documentation index or when you want to give a coding agent the full docs map before it starts changing code. Example prompt: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} Read the OmniCoreAgent llms.txt index, then show me the pages I need to build an agent with local tools, workspace files, and OmniServe. ``` *** ## Use The Hosted Docs MCP Mintlify exposes the docs as an MCP server at: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} https://docs-omnicoreagent.omnirexfloralabs.com/mcp ``` Use this with an MCP-capable editor or agent when you want documentation search available as a tool instead of pasting pages manually. Ask your tool to search the docs MCP for exact topics: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} Search the OmniCoreAgent docs MCP for task store configuration and summarize the Redis, MongoDB, and SQL options. ``` *** ## Use Cursor Or VS Code Use the contextual menu actions for Cursor or VS Code when you want the current docs page opened inside your editor context. Useful workflow: 1. Open the docs page that matches your task. 2. Send it to Cursor or VS Code from the contextual menu. 3. Ask the editor agent to update your app using only that docs page and your local source files. Example prompt: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} Using this OmniCoreAgent page, add a local tool registry to my existing agent without changing memory or workspace configuration. ``` *** ## Use ChatGPT, Claude, Or Perplexity The contextual menu can open the current docs page in ChatGPT, Claude, or Perplexity. Use this when you want explanation, comparison, or planning around one specific docs page. Good prompts: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} Turn this OmniServe docs page into a deployment checklist for my FastAPI app. ``` ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} Explain the difference between MemoryRouter, workspace storage, and background task store using only this OmniCoreAgent page. ``` ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} Create a minimal support-agent example from this local tools guide. ``` *** ## Where To Start Run the smallest useful OmniCoreAgent. Find environment variables and runtime config. Understand what OmniCoreAgent adds around the model. Serve an agent through REST and SSE. # Advanced Tool Use Source: https://docs-omnicoreagent.omnirexfloralabs.com/docs/how-to-guides/advanced-tools Scale to 1000+ tools with BM25 lexical retrieval # Advanced Tool Use (BM25 Tool Retrieval) Automatically discover relevant tools at runtime using BM25 lexical search. When you have many tools, this feature keeps the model prompt small: the model sees `tools_retriever`, searches the runtime tool catalog, then calls the matching tool returned by the search. *** ## Quick Setup ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} agent_config = { "enable_advanced_tool_use": True # Enable BM25 retrieval } ``` *** ## How It Works 1. Local tools, MCP tools, workspace/artifact tools, skills, and other registered runtime tools are indexed in memory. 2. Always-visible harness tools such as `tools_retriever`, workspace tools, artifact tools, and subagent tools stay directly visible. 3. The model calls `tools_retriever` with a semantic query for the capability it needs. 4. The retriever returns the top matching tools with names, descriptions, and parameters. 5. The model calls the selected tool normally. *** ## Benefits * **Scales to 1000+ tools** โ€” searchable tools do not all need to be stuffed into the prompt * **Zero network I/O** โ€” index lives in memory * **Deterministic** โ€” same query always selects same tools * **Container-friendly** โ€” no external dependencies Enable when you have many local or MCP tools and want the agent to discover the right capability through the runtime tool catalog. # Basic Usage Source: https://docs-omnicoreagent.omnirexfloralabs.com/docs/how-to-guides/basic-usage Common patterns for using OmniCoreAgent in your projects # Basic Usage This guide covers the most common patterns you'll need when working with OmniCoreAgent โ€” from running your first query to handling errors in production. *** ## Running an Agent Every interaction starts with `agent.run()`. It returns a dictionary with the agent's response and metadata. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} import asyncio from omnicoreagent import OmniCoreAgent async def main(): agent = OmniCoreAgent( name="my_agent", system_instruction="You are a helpful assistant.", model_config={"provider": "openai", "model": "gpt-4o"} ) result = await agent.run("What is the capital of France?") print(result["response"]) # The agent's text reply print(result["session_id"]) # Session used for this run print(result.get("metric")) # Token/timing metric when provider usage is available await agent.cleanup() asyncio.run(main()) ``` *** ## Session Management Use `session_id` to give your agent persistent memory across multiple calls. Without it, each call is stateless. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} # First interaction โ€” agent learns the user's name await agent.run("My name is Abiola.", session_id="user_42") # Later interaction โ€” agent remembers result = await agent.run("What's my name?", session_id="user_42") # โ†’ "Your name is Abiola." ``` ### Retrieving History ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} history = await agent.get_history(session_id="user_42") for message in history: print(f"{message['role']}: {message['content'][:80]}") ``` ### Clearing History ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} await agent.clear_session_history(session_id="user_42") ``` *** ## Adding Memory Persistence By default, history is stored in-memory (lost on restart). Add a `MemoryRouter` to persist across restarts. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from omnicoreagent import OmniCoreAgent, MemoryRouter agent = OmniCoreAgent( name="persistent_agent", system_instruction="You are a helpful assistant.", model_config={"provider": "openai", "model": "gpt-4o"}, memory_router=MemoryRouter("redis") # or "sql", "mongodb", "in_memory" ) ``` You can switch backends at runtime without restarting: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} await agent.switch_memory_store("mongodb") ``` *** ## Using Tools ### MCP Tools (External Servers) Connect to any MCP-compatible tool server: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} agent = OmniCoreAgent( name="tool_agent", system_instruction="You can manage files and search the web.", model_config={"provider": "openai", "model": "gpt-4o"}, mcp_tools=[ { "name": "filesystem", "transport_type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] } ] ) await agent.connect_mcp_servers() result = await agent.run("List all files in /tmp") ``` ### Local Tools (Custom Python Functions) Register any Python function as a tool the agent can call: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from omnicoreagent import OmniCoreAgent, ToolRegistry 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"} agent = OmniCoreAgent( name="weather_agent", system_instruction="You help with weather queries.", model_config={"provider": "openai", "model": "gpt-4o"}, local_tools=tools ) ``` ### External Tools Keep external integrations outside the core package. Use MCP servers for shared capabilities, or wrap project-owned APIs with `ToolRegistry` when the tool is specific to your application. *** ## Event Streaming Read telemetry events for UIs, logging, and debugging. Use `run_id` when multiple runs can share the same `session_id`. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} agent = OmniCoreAgent( name="streaming_agent", system_instruction="You are a helpful assistant.", model_config={"provider": "openai", "model": "gpt-4o"} ) result = await agent.run("What can you do?") session_id = result["session_id"] run_id = result["run_id"] trace_id = result["trace_id"] events = await agent.get_telemetry_events_after( cursor=None, session_id=session_id, run_id=run_id, ) for event in events: print(event.event_type, event.model_dump()) exact_trace = await agent.get_trace(trace_id) latest_session_trace = await agent.get_latest_trace(session_id) normalized_trace = await agent.get_trace(trace_id, normalize=True) ``` *** ## Error Handling Wrap agent calls with try/except for production use: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from omnicoreagent.exceptions import OmniCoreAgentError try: result = await agent.run("Analyze this dataset", session_id="user_1") except OmniCoreAgentError as e: print(f"Agent runtime error: {e.message}") except Exception as e: print(f"Unexpected failure: {e}") ``` *** ## Common Troubleshooting | Error | Fix | | --------------------------------------------- | ------------------------------------------------------------------------------ | | `Invalid API key` | Export `LLM_API_KEY` with the key for the provider selected in `model_config`. | | `ModuleNotFoundError` for an optional backend | 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 and path is correct | | `Token limit exceeded` | Increase `total_tokens_limit` or enable context management | *** ## Next Steps Full reference for env vars, agent settings, and models 5 backends with runtime switching and summarization Dynamic subagents and workspace-backed coordination for complex tasks # Configuration Source: https://docs-omnicoreagent.omnirexfloralabs.com/docs/how-to-guides/configuration Environment variables, agent settings, and model configuration # Configuration Guide OmniCoreAgent supports configuration through environment variables, Python dictionaries, and specialized configuration objects. *** ## 1. Environment Variables Environment variables are the best way to manage sensitive data like API keys and connection strings. For the first working agent, set only `LLM_API_KEY`. Memory and events default to in-memory storage, workspace files default to local disk, and OmniServe settings have server-side defaults. Add backend variables only when you are intentionally moving from local defaults to persistent or cloud infrastructure. ### LLM API Key OmniCoreAgent uses one public environment variable for hosted model credentials: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} export LLM_API_KEY=your_provider_key ``` Set `model_config["provider"]` to choose the provider. The runtime reads `LLM_API_KEY` and internally passes it to LiteLLM for the selected provider. Do not configure provider-specific key names in OmniCoreAgent examples. ### Optional Memory Backends The default memory backend is in-memory and needs no environment variables. Set these only when conversation history must live outside the current process. | Backend | Variable | Example | | ---------------- | -------------- | ------------------------------------------ | | **Redis** | `REDIS_URL` | `redis://localhost:6379/0` | | **SQL Database** | `DATABASE_URL` | `postgresql://user:pass@localhost:5432/db` | | **MongoDB** | `MONGODB_URI` | `mongodb://localhost:27017` | Optional MongoDB memory variables: | Variable | Purpose | | -------------------- | ---------------------------------------------------------- | | `MONGODB_DB_NAME` | MongoDB memory database name. Defaults to `omnicoreagent`. | | `MONGODB_COLLECTION` | MongoDB memory collection name. Defaults to `messages`. | ### Workspace Storage Workspace storage is separate from memory storage. Memory stores conversation history. Workspace storage stores files, scratchpads, artifacts, subagent outputs, and tool offloads. | Backend | Variables | | --------- | ------------------------------------------------------------------------------------------------------------------- | | **Local** | `OMNICOREAGENT_WORKSPACE_BACKEND=local`, `OMNICOREAGENT_WORKSPACE_DIR=./workspace` | | **S3** | `OMNICOREAGENT_WORKSPACE_BACKEND=s3`, `AWS_S3_BUCKET`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` | | **R2** | `OMNICOREAGENT_WORKSPACE_BACKEND=r2`, `R2_BUCKET_NAME`, `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY` | Optional workspace variables: | Variable | Purpose | | -------------------------------- | --------------------------------------- | | `OMNICOREAGENT_WORKSPACE_PREFIX` | Key prefix for S3/R2 workspace objects. | | `AWS_REGION` | AWS region for S3 workspaces. | | `AWS_ENDPOINT_URL` | Custom S3-compatible endpoint. | ### Optional Telemetry Export Telemetry events and traces work in-process by default. Set exporter variables only when traces should leave the process for an OTLP-compatible backend. | Exporter | Variables | | ------------- | --------------------------------------------------------------------------------------------- | | **OTLP/HTTP** | `OTEL_EXPORTER_OTLP_ENDPOINT` or explicit exporter `endpoint` | | **LangSmith** | `LANGSMITH_API_KEY`, optional `LANGSMITH_PROJECT`, optional `LANGSMITH_OTEL_ENDPOINT` | | **Opik** | `OPIK_API_KEY`, `OPIK_WORKSPACE`, optional `OPIK_PROJECT_NAME`, optional `OPIK_OTEL_ENDPOINT` | Install the matching extra before exporting: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} pip install "omnicoreagent[otel]" pip install "omnicoreagent[langsmith]" pip install "omnicoreagent[opik]" ``` Python configuration can pass exporters directly: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from omnicoreagent import OmniCoreAgent agent = OmniCoreAgent( name="research-agent", system_instruction="You are a research assistant.", model_config={"provider": "openai", "model": "gpt-5.4-mini"}, telemetry_exporters=[ { "destination": "otlp", "endpoint": "http://localhost:4318/v1/traces", "service_name": "research-agent", } ], ) ``` ### OmniServe OmniServe reads these variables through `OmniServeConfig`. Environment variables override values passed in code. You do not need any OmniServe environment variables to start. Defaults bind the server to port `8000`, enable the background API, start the background worker, and use an in-memory task store. Set only the values you want to override. | Variable | Default | Purpose | | ------------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------- | | `OMNICOREAGENT_SERVE_HOST` | `0.0.0.0` | Server bind host. Must not be empty. | | `OMNICOREAGENT_SERVE_PORT` | `8000` | Server port. Must be `1`-`65535`. | | `OMNICOREAGENT_SERVE_WORKERS` | `1` | Direct OmniServe worker count. Must be `1`; run multiple processes behind a process manager for horizontal scaling. | | `OMNICOREAGENT_SERVE_API_PREFIX` | `""` | API route prefix, such as `/api/v1`. Normalized to a leading slash with no trailing slash; whitespace is invalid. | | `OMNICOREAGENT_SERVE_ENABLE_DOCS` | `true` | Enable Swagger UI. | | `OMNICOREAGENT_SERVE_ENABLE_REDOC` | `true` | Enable ReDoc. | | `OMNICOREAGENT_SERVE_CORS_ENABLED` | `true` | Enable CORS middleware. | | `OMNICOREAGENT_SERVE_CORS_ORIGINS` | `*` | Comma-separated allowed origins. | | `OMNICOREAGENT_SERVE_CORS_METHODS` | `*` | Comma-separated allowed methods. | | `OMNICOREAGENT_SERVE_CORS_HEADERS` | `*` | Comma-separated allowed headers. | | `OMNICOREAGENT_SERVE_CORS_CREDENTIALS` | `true` | Allow CORS credentials. | | `OMNICOREAGENT_SERVE_AUTH_ENABLED` | `false` | Enable Bearer token auth. Requires a non-empty `OMNICOREAGENT_SERVE_AUTH_TOKEN` value. | | `OMNICOREAGENT_SERVE_AUTH_TOKEN` | unset | Bearer token value used when auth is enabled. | | `OMNICOREAGENT_SERVE_REQUEST_LOGGING` | `true` | Log incoming requests. | | `OMNICOREAGENT_SERVE_LOG_LEVEL` | `INFO` | Server log level: `CRITICAL`, `ERROR`, `WARNING`, `INFO`, `DEBUG`, or `TRACE`. | | `OMNICOREAGENT_SERVE_REQUEST_TIMEOUT` | `300` | Request timeout in seconds. Set `0` to disable timeout middleware. | | `OMNICOREAGENT_SERVE_RATE_LIMIT_ENABLED` | `false` | Enable in-process rate limiting. | | `OMNICOREAGENT_SERVE_RATE_LIMIT_REQUESTS` | `100` | Requests per rate-limit window. Must be at least `1` when rate limiting is enabled. | | `OMNICOREAGENT_SERVE_RATE_LIMIT_WINDOW` | `60` | Rate-limit window in seconds. Must be at least `1` when rate limiting is enabled. | | `OMNICOREAGENT_BACKGROUND_ENABLED` | `true` | Expose background task endpoints. | | `OMNICOREAGENT_BACKGROUND_AGENT_ID` | `default` | Agent id used when OmniServe registers the served agent for background work. | | `OMNICOREAGENT_BACKGROUND_TASK_STORE` | `in_memory` | Background control-plane store: `in_memory`, `sql`, `redis`, or `mongodb`. | | `OMNICOREAGENT_BACKGROUND_TASK_STORE_URL` | unset | SQL or Redis URL. A URL with no backend selects SQL; use `OMNICOREAGENT_BACKGROUND_TASK_STORE=redis` for Redis URLs. | | `OMNICOREAGENT_BACKGROUND_TASK_STORE_URI` | unset | MongoDB URI. Setting this selects the MongoDB task store. | | `OMNICOREAGENT_BACKGROUND_TASK_STORE_DATABASE` | `omnicoreagent` | MongoDB database name. | | `OMNICOREAGENT_BACKGROUND_TASK_STORE_PREFIX` | unset | Redis key prefix. | | `OMNICOREAGENT_BACKGROUND_TASK_STORE_COLLECTION_PREFIX` | unset | MongoDB collection prefix. | | `OMNICOREAGENT_BACKGROUND_TASK_STORE_CONNECT_TIMEOUT` | unset | Optional backend connect timeout in seconds. | | `OMNICOREAGENT_BACKGROUND_START_WORKER` | `true` | Start the scheduler and worker loop during server lifespan. | The background task store is separate from `MemoryRouter`. `MemoryRouter` stores conversation/session history. The task store stores scheduler/runtime state: tasks, schedule cursors, runs, attempts, leases, heartbeats, retries, and cancellation flags. Defaults are intentionally light. Use `sql`, `redis`, or `mongodb` when background tasks must survive process restarts. Choose one durable backend per deployment. Use SQL/SQLite for local durability or simple single-node services. Use Redis when your deployment already operates Redis with persistence and no eviction for task-store keys. Use MongoDB when MongoDB is your durable operational store. For Redis durability, enable Redis persistence and keep task-store keys out of eviction. MongoDB task-store writes use majority write concern. Durable background examples. Pick one backend: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} # Local SQLite durability export OMNICOREAGENT_BACKGROUND_TASK_STORE=sql export OMNICOREAGENT_BACKGROUND_TASK_STORE_URL=sqlite:///.omnicoreagent/background.db ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} # Redis durability export OMNICOREAGENT_BACKGROUND_TASK_STORE=redis export OMNICOREAGENT_BACKGROUND_TASK_STORE_URL=redis://localhost:6379/0 ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} # MongoDB durability export OMNICOREAGENT_BACKGROUND_TASK_STORE=mongodb export OMNICOREAGENT_BACKGROUND_TASK_STORE_URI=mongodb://localhost:27017 export OMNICOREAGENT_BACKGROUND_TASK_STORE_DATABASE=omnicoreagent ``` ## 2. Agent Configuration The `AgentConfig` handles the runtime behavior of the agent, such as reasoning steps and resource limits. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} agent_config = { "tool_call_timeout": 30, # Max seconds per tool execution "max_steps": 15, # Max reasoning loops per run() "request_limit": 0, # 0 = unlimited "total_tokens_limit": 0, # 0 = unlimited "enable_subagents": True, # Dynamic focused workers "enable_workspace_files": True, # Default: workspace files for notes/logs/scratchpads "enable_agent_skills": True, # Enable local skill discovery "enable_advanced_tool_use": True, # Enable BM25 tool retrieval "context_management": {"enabled": True}, "tool_offload": {"enabled": True}, "governance_config": { "enabled": True, "profile": "interactive-dev", "sandbox_config": {"provider": "none"} } } agent = OmniCoreAgent( ... agent_config=agent_config ) ``` When `enable_subagents` is true, OmniCoreAgent automatically enables workspace files because spawned workers write output, todos, logs, and scratchpads into the active workspace. For full harness-style workloads, pair dynamic subagents with context management and tool offloading. Context management checks the prompt before each model call; tool offloading keeps large tool payloads in workspace artifacts instead of feeding the full payload back into the loop. `governance_config.sandbox_config` selects the sandbox runtime boundary used by governed execution. Supported built-in providers are: | Provider | Use | | ------------ | ---------------------------------------------------------------------------------------------- | | `none` | Policy-only mode. Does not satisfy `sandbox_required`. | | `local_test` | Development/test adapter that runs registered handlers only. No shell or production isolation. | Use `local_test` only for tests and local harness wiring: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} agent_config = { "governance_config": { "enabled": True, "sandbox_config": {"provider": "local_test"}, "allow_test_sandbox_runtime": True, } } ``` *** ## 3. Model Configuration The `model_config` defines which LLM to use and its sampling parameters. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} model_config = { "provider": "openai", "model": "gpt-4o", "temperature": 0.5, "max_tokens": 4000, "top_p": 0.9, } ``` Supported provider values are: `openai`, `anthropic`, `groq`, `ollama`, `azure`, `gemini`, `deepseek`, `mistral`, `openrouter`, and `cencori`. Provider-specific runtime options currently supported by OmniCoreAgent are: * Azure: `azure_endpoint`, `azure_api_version`, `azure_deployment` * Ollama: `ollama_host` *** ## 4. MCP Tool Configuration MCP tool servers are configured as a list of dictionaries. OmniCoreAgent only loads tools from MCP servers. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} mcp_tools = [ { "name": "explorer", "transport_type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] }, { "name": "remote_service", "transport_type": "streamable_http", "url": "https://api.myapp.com/mcp", "headers": {"Authorization": "Bearer token"} } ] ``` *** ## 5. Persistence Configuration Pass a `MemoryRouter` to customize conversation memory. Runtime evidence is recorded through telemetry, which defaults to in-memory storage. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from omnicoreagent import MemoryRouter agent = OmniCoreAgent( ... memory_router=MemoryRouter("redis") ) ``` *** ## Best Practices * **Use `.env`**: Use a library like `python-dotenv` to load your environment variables during development. * **Model Selection**: Use smaller models (`gpt-4o-mini`) while building and testing your agent logic to save costs. * **Limit Steps**: Always set a reasonable `max_steps` to prevent the agent from entering infinite reasoning loops in case of tool failures. # Model Support Source: https://docs-omnicoreagent.omnirexfloralabs.com/docs/how-to-guides/models Supported LLM providers โ€” OpenAI, Anthropic, Gemini, Groq, DeepSeek, and more # Universal Model Support Model-agnostic through LiteLLM with the provider values supported by the OmniCoreAgent runtime: *** ## Supported Providers ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} # OpenAI model_config = {"provider": "openai", "model": "gpt-4o"} # Anthropic model_config = {"provider": "anthropic", "model": "claude-3-5-sonnet-20241022"} # Google Gemini model_config = {"provider": "gemini", "model": "gemini-2.0-flash-exp"} # Groq (Ultra-fast) model_config = {"provider": "groq", "model": "llama-3.1-8b-instant"} # DeepSeek model_config = {"provider": "deepseek", "model": "deepseek-chat"} # Mistral AI model_config = {"provider": "mistral", "model": "mistral-7b-instruct"} # Azure OpenAI model_config = {"provider": "azure", "model": "gpt-4o"} # OpenRouter (200+ models) model_config = {"provider": "openrouter", "model": "anthropic/claude-3.5-sonnet"} # Ollama (Local) model_config = {"provider": "ollama", "model": "llama3.1:8b", "ollama_host": "http://localhost:11434"} ``` *** ## Model Configuration Options ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} model_config = { "provider": "openai", "model": "gpt-4o", "temperature": 0.7, "max_tokens": 2000, "top_p": 0.95 } ``` *** ## Azure OpenAI Configuration ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} model_config = { "provider": "azure", "model": "gpt-4", "azure_endpoint": "https://your-resource.openai.azure.com", "azure_api_version": "2024-02-01" } ``` *** ## Ollama Configuration (Local Models) ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} model_config = { "provider": "ollama", "model": "llama3.1:8b", "ollama_host": "http://localhost:11434" } ``` *** ## Environment Variables ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} # Hosted providers use this single OmniCoreAgent key export LLM_API_KEY=your_api_key ``` OmniCoreAgent reads `LLM_API_KEY`. Select the provider through `model_config["provider"]`; do not set provider-specific API-key variables in OmniCoreAgent configuration. *** ## Provider Selection Guide | Use Case | Recommended Provider | | ------------------ | ------------------------------------------- | | Complex reasoning | OpenAI (`gpt-4o`), Anthropic (`claude-3.5`) | | Fast inference | Groq (`llama-3.1-8b-instant`) | | Cost-effective | DeepSeek (`deepseek-chat`) | | Privacy-sensitive | Ollama (runs locally) | | Multi-model access | OpenRouter (200+ models) | | Enterprise / Azure | Azure OpenAI | Switch providers based on your needs โ€” use cheaper models (Groq, DeepSeek) for simple tasks, powerful models (GPT-4o, Claude) for complex reasoning, and local models (Ollama) for privacy-sensitive applications. # Runtime Visibility Source: https://docs-omnicoreagent.omnirexfloralabs.com/docs/how-to-guides/observability Production metrics and per-request performance monitoring # Runtime Visibility & Metrics Monitor your agents with built-in metrics, telemetry streams, and in-house trace summaries. *** ## Real-time Usage Metrics OmniCoreAgent tracks request counts, runtime, and provider-reported token usage when available. Each `run()` returns a `metric` object, and you can get cumulative stats anytime. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} result = await agent.run("Analyze this data") print(f"Request Tokens: {result['metric'].request_tokens}") print(f"Time Taken: {result['metric'].total_time:.2f}s") # Get aggregated metrics for the agent's lifecycle stats = await agent.get_metrics() print(f"Avg Response Time: {stats['average_time']:.2f}s") ``` *** ## Runtime Metrics OmniCoreAgent exposes lightweight runtime metrics without requiring an external tracing service. ### What's Available * Request count * Request, response, and total tokens * Total runtime * Average response time *** ## Telemetry Events OmniCoreAgent emits typed telemetry events for user messages, tool calls, tool results, final answers, subagent calls, and background run lifecycle changes. Use events when you need a live UI, session debugging, or a lightweight execution record. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} result = await agent.run("Research this topic", session_id="research_1") events = await agent.get_telemetry_events_after( cursor=None, session_id="research_1", run_id=result["run_id"], ) for event in events: print(event.event_type, event.model_dump()) ``` When serving through OmniServe, `POST /run` streams the live run over SSE. For application UIs and APIs, use the `/telemetry` routes to replay, inspect, and stream stored telemetry. Filter by `run_id` when a UI needs to isolate one execution inside a shared session. The compact `/events/{session_id}` aliases are still available and accept `?run_id=...` for the same run-scoped isolation. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -N -X POST http://localhost:8000/run \ -H "Content-Type: application/json" \ -d '{"query": "Research this topic", "session_id": "research_1"}' curl "http://localhost:8000/telemetry/events?session_id=research_1&run_id=RUN_ID" curl "http://localhost:8000/telemetry/events?run_id=RUN_ID&event_type=tool_result&limit=100" curl "http://localhost:8000/telemetry/traces?session_id=research_1&limit=20" curl "http://localhost:8000/telemetry/traces/TRACE_ID" curl "http://localhost:8000/telemetry/runs/RUN_ID/trace" curl "http://localhost:8000/telemetry/sessions/research_1/trace" curl -N "http://localhost:8000/telemetry/events/stream?session_id=research_1&run_id=RUN_ID" ``` *** ## Agent Trace Every run emits typed telemetry. Retrieve the trace by the `trace_id` returned from `agent.run(...)`. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} trace = await agent.get_trace(result["trace_id"]) print(trace["status"]) print(len(trace["events"])) print(len(trace["spans"])) for event in trace["events"]: print(event["event_type"], event.get("input"), event.get("output")) ``` You can also retrieve the latest trace for a session or a trace correlated to a run: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} latest_session_trace = await agent.get_latest_trace("research_1") run_correlated_trace = await agent.get_trace(run_id=result["run_id"]) normalized = await agent.get_trace(result["trace_id"], normalize=True) ``` `trace_id` is the exact trace handle. `run_id` is a correlation and filtering handle; when more than one trace is correlated to the same run, `get_trace( run_id=...)` returns the latest matching trace. The trace is intentionally dependency-free inside the runtime. Exporters are optional adapters layered on top of this internal trace model. *** ## Export Traces Install the OpenTelemetry extra when you want to send traces to an OTLP collector or an OTLP-compatible tracing backend: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} pip install "omnicoreagent[otel]" ``` Export a specific trace manually: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from omnicoreagent import build_telemetry_exporter result = await agent.run("Research this topic", session_id="research_1") otel = build_telemetry_exporter( "otlp", endpoint="http://localhost:4318/v1/traces", service_name="research-agent", ) exported = await agent.export_trace( result["trace_id"], exporters=[otel], ) print(exported) ``` Configure exporters on the agent to export automatically when traces end: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from omnicoreagent import OmniCoreAgent agent = OmniCoreAgent( name="research-agent", system_instruction="You are a research assistant.", model_config={"provider": "openai", "model": "gpt-5.4-mini"}, telemetry_exporters=[ { "destination": "otlp", "endpoint": "http://localhost:4318/v1/traces", "service_name": "research-agent", } ], ) ``` Vendor presets use the same OTLP exporter path: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} langsmith = build_telemetry_exporter( "langsmith", api_key="...", project_name="production-agents", ) opik = build_telemetry_exporter( "opik", api_key="...", workspace="your-workspace", project_name="production-agents", ) ``` The presets also read common environment variables: | Exporter | Environment variables | | --------- | ------------------------------------------------------------------------------------ | | OTLP | `OTEL_EXPORTER_OTLP_ENDPOINT` or explicit `endpoint` | | LangSmith | `LANGSMITH_API_KEY`, `LANGSMITH_PROJECT`, optional `LANGSMITH_OTEL_ENDPOINT` | | Opik | `OPIK_API_KEY`, `OPIK_WORKSPACE`, `OPIK_PROJECT_NAME`, optional `OPIK_OTEL_ENDPOINT` | | JSONL | explicit local `path` | `trace_id` remains the exact lookup and export handle. `run_id` can be used for correlated export, but when a serving trace and an agent trace share the same `run_id`, the latest matching trace is exported. Use metrics for cost and performance monitoring, events for live UI streaming, traces for debugging, and exporters when traces need to leave the process. # OmniServe Source: https://docs-omnicoreagent.omnirexfloralabs.com/docs/how-to-guides/omniserve Production REST and SSE API server for OmniCoreAgent # OmniServe โ€” Production API Server **Turn any agent into a production-ready REST/SSE API with a single command.** OmniServe is an optional production extra: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} pip install "omnicoreagent[serve]" ``` *** ## Agent File Requirements Your Python file must define **one of the following**: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} # Option 1: Define an `agent` variable from omnicoreagent import OmniCoreAgent agent = OmniCoreAgent( name="MyAgent", system_instruction="You are a helpful assistant.", model_config={"provider": "openai", "model": "gpt-4o-mini"}, ) ``` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} # Option 2: Define a `create_agent()` function from omnicoreagent import OmniCoreAgent def create_agent(): """Factory function that returns an agent instance.""" return OmniCoreAgent( name="MyAgent", system_instruction="You are a helpful assistant.", model_config={"provider": "openai", "model": "gpt-4o-mini"}, ) ``` OmniServe looks for `agent` variable first, then `create_agent()` function. Your file must export one of these. *** ## Quick Start ### Step 1: Create your agent file (`my_agent.py`) ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from omnicoreagent import OmniCoreAgent, ToolRegistry tools = ToolRegistry() @tools.register_tool("greet") def greet(name: str) -> str: """Greet someone by name.""" return f"Hello, {name}!" @tools.register_tool("calculate") def calculate(expression: str) -> dict: """Evaluate a math expression.""" import math result = eval(expression, {"__builtins__": {}}, {"sqrt": math.sqrt, "pi": math.pi}) return {"expression": expression, "result": result} agent = OmniCoreAgent( name="MyAgent", system_instruction="You are a helpful assistant with access to greeting and calculation tools.", model_config={"provider": "openai", "model": "gpt-4o-mini"}, local_tools=tools, ) ``` ### Step 2: Set environment variables ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} export LLM_API_KEY=your_api_key_here ``` ### Step 3: Run the server ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} omniserve run --agent my_agent.py ``` ### Step 4: Test the API ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} # Health check curl http://localhost:8000/health # Run a query (sync) curl -X POST http://localhost:8000/run/sync \ -H "Content-Type: application/json" \ -d '{"query": "Greet Alice and calculate 2+2"}' # Run a query (streaming SSE) curl -X POST http://localhost:8000/run \ -H "Content-Type: application/json" \ -d '{"query": "What is sqrt(144)?"}' # Open interactive docs open http://localhost:8000/docs ``` *** ## CLI Commands | Command | Description | | ------------------------------- | --------------------------------- | | `omniserve run` | Run your agent file as API server | | `omniserve quickstart` | Zero-code server with defaults | | `omniserve config` | View or generate configuration | | `omniserve generate-dockerfile` | Generate production Dockerfile | *** ## CLI Options: `omniserve run` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} omniserve run \ --agent my_agent.py \ --host 0.0.0.0 \ --port 8000 \ --workers 1 \ --auth-token YOUR_TOKEN \ --rate-limit 100 \ --cors-origins "*" \ --no-docs ``` **Examples:** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} # Basic run omniserve run --agent my_agent.py # With authentication omniserve run --agent my_agent.py --auth-token secret123 # With rate limiting omniserve run --agent my_agent.py --rate-limit 100 # Production settings omniserve run --agent my_agent.py \ --port 8000 \ --auth-token $AUTH_TOKEN \ --rate-limit 100 \ --cors-origins "https://myapp.com,https://api.myapp.com" ``` *** ## CLI Options: `omniserve quickstart` Start a server instantly without writing any code: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} omniserve quickstart \ --provider openai \ --model gpt-4o \ --name QuickAgent \ --instruction "You are..." \ --port 8000 ``` Use the provider that matches your `LLM_API_KEY`. For an OpenAI key, run `omniserve quickstart --provider openai --model gpt-4o-mini`. **Examples:** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} # OpenAI omniserve quickstart --provider openai --model gpt-4o # Google Gemini omniserve quickstart --provider gemini --model gemini-2.0-flash # Anthropic Claude omniserve quickstart --provider anthropic --model claude-3-5-sonnet-20241022 ``` *** ## API Endpoints ### Core Endpoints | Method | Endpoint | Auth | Description | | ------ | ---------------------------------------- | ----- | ---------------------------------------------------------------------------------------------------------------- | | `POST` | `/run` | Yes\* | SSE streaming response | | `POST` | `/run/sync` | Yes\* | JSON response (blocking) | | `GET` | `/health` | No | Health check | | `GET` | `/ready` | No | Readiness check | | `GET` | `/prometheus` | No | Prometheus metrics | | `GET` | `/tools` | Yes\* | List available tools | | `GET` | `/metrics` | Yes\* | Agent usage metrics | | `GET` | `/events/{session_id}` | Yes\* | Replay stored telemetry events, then follow live telemetry events over SSE; add `?run_id=...` to isolate one run | | `GET` | `/events/{session_id}/list` | Yes\* | Return stored telemetry events as JSON; add `?run_id=...` to isolate one run | | `GET` | `/events/{session_id}/trace` | Yes\* | Compact telemetry trace summary for the latest session trace, or `?run_id=...` for one run | | `GET` | `/telemetry/events` | Yes\* | Return stored telemetry events filtered by `trace_id`, `run_id`, `session_id`, `task_id`, or `event_type` | | `GET` | `/telemetry/events/stream` | Yes\* | Replay and follow telemetry events over SSE for `session_id`; add `run_id` to isolate one run | | `GET` | `/telemetry/traces` | Yes\* | List traces filtered by trace, run, session, task, agent, workflow, model, or status | | `GET` | `/telemetry/traces/{trace_id}` | Yes\* | Return one exact trace | | `GET` | `/telemetry/runs/{run_id}/trace` | Yes\* | Return the latest trace correlated to one run | | `GET` | `/telemetry/sessions/{session_id}/trace` | Yes\* | Return the latest trace for one session | | `GET` | `/docs` | No | Swagger UI | | `GET` | `/redoc` | No | ReDoc UI | `/ready` returns `ready: true` only after the FastAPI lifespan has completed startup, the served agent is initialized, and any configured MCP servers are connected. Agents without MCP servers do not need an MCP client to pass readiness. ### Background Task Endpoints These routes are mounted when background execution is enabled. It is enabled by default and can be turned off with `OMNICOREAGENT_BACKGROUND_ENABLED=false` or `OmniServeConfig(background_enabled=False)`. | Method | Endpoint | Auth | Description | | -------- | ------------------------------------- | ----- | -------------------------------------------------------------------- | | `GET` | `/background/status` | Yes\* | Inspect background manager counts and run status totals | | `POST` | `/background/agents` | Yes\* | Register the served agent or an agent spec for background execution | | `GET` | `/background/agents` | Yes\* | List registered background agents | | `GET` | `/background/agents/{agent_id}` | Yes\* | Inspect a background agent spec | | `DELETE` | `/background/agents/{agent_id}` | Yes\* | Delete a background agent spec | | `POST` | `/background/tasks` | Yes\* | Create a background task | | `GET` | `/background/tasks` | Yes\* | List background tasks | | `GET` | `/background/tasks/{task_id}` | Yes\* | Inspect a background task | | `GET` | `/background/tasks/{task_id}/status` | Yes\* | Inspect schedule state, run counts, and latest run | | `PATCH` | `/background/tasks/{task_id}` | Yes\* | Patch a background task | | `POST` | `/background/tasks/{task_id}/run` | Yes\* | Queue a manual background run, optionally waiting for terminal state | | `POST` | `/background/tasks/{task_id}/pause` | Yes\* | Pause scheduled dispatch | | `POST` | `/background/tasks/{task_id}/resume` | Yes\* | Resume scheduled dispatch | | `DELETE` | `/background/tasks/{task_id}` | Yes\* | Delete a background task | | `POST` | `/background/runs/{run_id}/cancel` | Yes\* | Cancel a queued or running run | | `GET` | `/background/runs` | Yes\* | List background runs | | `GET` | `/background/runs/{run_id}` | Yes\* | Inspect run status | | `GET` | `/background/runs/{run_id}/attempts` | Yes\* | List run attempts | | `GET` | `/background/runs/{run_id}/events` | Yes\* | Replay lifecycle events | | `GET` | `/background/runs/{run_id}/workspace` | Yes\* | Inspect run workspace files | \*Auth required only if `--auth-token` is set or `OMNICOREAGENT_SERVE_AUTH_ENABLED=true` with `OMNICOREAGENT_SERVE_AUTH_TOKEN`. ### Request/Response Examples ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} # Sync request (with auth) curl -X POST http://localhost:8000/run/sync \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_TOKEN" \ -d '{"query": "What is 2+2?", "session_id": "user123"}' # Response: # {"response": "2+2 equals 4", "session_id": "user123", ...} # Streaming SSE request curl -X POST http://localhost:8000/run \ -H "Content-Type: application/json" \ -d '{"query": "Explain quantum computing"}' # Replay and follow one session's events curl -N http://localhost:8000/events/user123 # Replay one run inside a shared session curl -N "http://localhost:8000/events/user123?run_id=RUN_ID" curl "http://localhost:8000/events/user123/list?run_id=RUN_ID" curl "http://localhost:8000/events/user123/trace?run_id=RUN_ID" # Production telemetry API curl "http://localhost:8000/telemetry/events?session_id=user123&run_id=RUN_ID" curl "http://localhost:8000/telemetry/events?run_id=RUN_ID&event_type=tool_result&limit=100" curl "http://localhost:8000/telemetry/traces?session_id=user123&limit=20" curl "http://localhost:8000/telemetry/traces/TRACE_ID" curl "http://localhost:8000/telemetry/runs/RUN_ID/trace" curl "http://localhost:8000/telemetry/sessions/user123/trace" curl -N "http://localhost:8000/telemetry/events/stream?session_id=user123&run_id=RUN_ID" # List tools curl http://localhost:8000/tools \ -H "Authorization: Bearer YOUR_TOKEN" ``` For telemetry traces, `trace_id` is the exact lookup handle returned by the agent runtime. `run_id` is the serving/runtime correlation handle returned from `/run/sync` and SSE completion payloads. Use `trace_id` when you need one exact trace. Use `run_id` when your UI or application needs all telemetry for one execution inside a shared session. `/telemetry/events` defaults to `limit=200`; `/telemetry/traces` defaults to `limit=100`. Both accept lower limits per request. Exact trace, run trace, and session trace detail endpoints return `404` when no matching trace exists or an accessor returns a trace that does not match the requested selector. ### Background Task Example OmniServe registers the served agent as a background-capable agent during server startup. The default background agent id is `default`; override it with `OMNICOREAGENT_BACKGROUND_AGENT_ID` or `OmniServeConfig(background_agent_id="...")`. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -X POST http://localhost:8000/background/tasks \ -H "Content-Type: application/json" \ -d '{ "task_id": "daily_report", "query": "Write today'\''s operations report and save the output.", "schedule": {"type": "manual"}, "timeout_seconds": 120, "retry_policy": {"max_retries": 1, "initial_delay_seconds": 30} }' curl -X POST http://localhost:8000/background/tasks/daily_report/run \ -H "Content-Type: application/json" \ -d '{"wait": false}' ``` Set `{"wait": true}` when the response should wait for terminal run state. If the run does not finish before the background wait budget, OmniServe returns `504` with the `run_id`, latest `status`, `wait_timeout_seconds`, and `request_timeout_seconds` in `detail`; use the `run_id` with `/background/runs/{run_id}` to inspect the run later. If auth is enabled with `--auth-token` or `OMNICOREAGENT_SERVE_AUTH_ENABLED=true`, add `-H "Authorization: Bearer YOUR_TOKEN"` to protected requests. Each run stores operational state in the task store and writes lifecycle files into the configured workspace namespace. Use the default in-memory task store for local development, or choose `sql`, `redis`, or `mongodb` when runs must survive restarts. Durable stores preserve queued runs across server restarts: OmniServe can queue a run, stop, start again with the same task store, and the new manager can claim and complete that run. Choose one durable backend per deployment. Use SQL/SQLite for local durability or simple single-node services. Use Redis when your deployment already operates Redis with persistence and no eviction for task-store keys. Use MongoDB when MongoDB is your durable operational store. Common inspection endpoints: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl http://localhost:8000/background/status curl http://localhost:8000/background/tasks/daily_report/status curl http://localhost:8000/background/runs/$RUN_ID curl http://localhost:8000/background/runs/$RUN_ID/events curl http://localhost:8000/background/runs/$RUN_ID/workspace ``` *** ## Environment Variables Server settings use the `OMNICOREAGENT_SERVE_*` prefix. Background task settings use the `OMNICOREAGENT_BACKGROUND_*` prefix. **Environment variables always override code values.** You can run OmniServe without adding any `OMNICOREAGENT_SERVE_*` variables. The defaults enable the background API, start the worker, and use in-memory background task state. Add variables only when you want to change server behavior, authentication, rate limits, or background storage. | Variable | Default | Description | | ------------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------- | | `OMNICOREAGENT_SERVE_HOST` | `0.0.0.0` | Server host. Must not be empty | | `OMNICOREAGENT_SERVE_PORT` | `8000` | Server port. Must be `1`-`65535` | | `OMNICOREAGENT_SERVE_WORKERS` | `1` | Direct OmniServe worker count. Must be `1`; scale by running multiple processes | | `OMNICOREAGENT_SERVE_API_PREFIX` | `""` | API path prefix (e.g., `/api/v1`). Normalized to a leading slash with no trailing slash; whitespace is invalid | | `OMNICOREAGENT_SERVE_ENABLE_DOCS` | `true` | Swagger UI at `/docs` | | `OMNICOREAGENT_SERVE_ENABLE_REDOC` | `true` | ReDoc at `/redoc` | | `OMNICOREAGENT_SERVE_CORS_ENABLED` | `true` | Enable CORS | | `OMNICOREAGENT_SERVE_CORS_ORIGINS` | `*` | Allowed origins (comma-separated) | | `OMNICOREAGENT_SERVE_CORS_METHODS` | `*` | Allowed methods (comma-separated) | | `OMNICOREAGENT_SERVE_CORS_HEADERS` | `*` | Allowed headers (comma-separated) | | `OMNICOREAGENT_SERVE_CORS_CREDENTIALS` | `true` | Allow credentials | | `OMNICOREAGENT_SERVE_AUTH_ENABLED` | `false` | Enable Bearer token auth. Requires a non-empty auth token | | `OMNICOREAGENT_SERVE_AUTH_TOKEN` | โ€” | Bearer token value used when auth is enabled | | `OMNICOREAGENT_SERVE_RATE_LIMIT_ENABLED` | `false` | Enable rate limiting | | `OMNICOREAGENT_SERVE_RATE_LIMIT_REQUESTS` | `100` | Requests per window. Must be at least `1` when enabled | | `OMNICOREAGENT_SERVE_RATE_LIMIT_WINDOW` | `60` | Window in seconds. Must be at least `1` when enabled | | `OMNICOREAGENT_SERVE_REQUEST_LOGGING` | `true` | Log requests | | `OMNICOREAGENT_SERVE_LOG_LEVEL` | `INFO` | Log level: `CRITICAL`, `ERROR`, `WARNING`, `INFO`, `DEBUG`, or `TRACE` | | `OMNICOREAGENT_SERVE_REQUEST_TIMEOUT` | `300` | Request timeout in seconds | | `OMNICOREAGENT_BACKGROUND_ENABLED` | `true` | Expose background task endpoints | | `OMNICOREAGENT_BACKGROUND_AGENT_ID` | `default` | Agent id for the served agent in background tasks | | `OMNICOREAGENT_BACKGROUND_TASK_STORE` | `in_memory` | Background control-plane store: `in_memory`, `sql`, `redis`, or `mongodb` | | `OMNICOREAGENT_BACKGROUND_TASK_STORE_URL` | โ€” | SQL or Redis URL. Use `OMNICOREAGENT_BACKGROUND_TASK_STORE=redis` for Redis URLs | | `OMNICOREAGENT_BACKGROUND_TASK_STORE_URI` | โ€” | MongoDB URI | | `OMNICOREAGENT_BACKGROUND_TASK_STORE_DATABASE` | `omnicoreagent` | MongoDB database name | | `OMNICOREAGENT_BACKGROUND_TASK_STORE_PREFIX` | โ€” | Redis key prefix | | `OMNICOREAGENT_BACKGROUND_TASK_STORE_COLLECTION_PREFIX` | โ€” | MongoDB collection prefix | | `OMNICOREAGENT_BACKGROUND_TASK_STORE_CONNECT_TIMEOUT` | โ€” | Backend connect timeout in seconds | | `OMNICOREAGENT_BACKGROUND_START_WORKER` | `true` | Start scheduler and worker loop during server lifespan | The background task store is not conversation memory. Memory stays in `MemoryRouter`. The task store is the control plane for schedules, runs, attempts, leases, retries, and cancellation. Leave it at the in-memory default to start; choose `sql`, `redis`, or `mongodb` when that state must survive restarts. Redis durable deployments need persistence enabled and a no-eviction policy for task-store keys. MongoDB durable deployments use majority writes. **Example shell environment:** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} # Model credential export LLM_API_KEY=your_api_key_here # Optional OmniServe overrides export OMNICOREAGENT_SERVE_PORT=8000 export OMNICOREAGENT_SERVE_AUTH_ENABLED=true export OMNICOREAGENT_SERVE_AUTH_TOKEN=my-secret-token export OMNICOREAGENT_SERVE_RATE_LIMIT_ENABLED=true export OMNICOREAGENT_SERVE_RATE_LIMIT_REQUESTS=100 export OMNICOREAGENT_SERVE_CORS_ORIGINS=https://myapp.com,https://api.myapp.com export OMNICOREAGENT_SERVE_CORS_METHODS=GET,POST,OPTIONS export OMNICOREAGENT_SERVE_CORS_HEADERS=Authorization,Content-Type # Optional durable background task store. Pick one backend. export OMNICOREAGENT_BACKGROUND_TASK_STORE=sql export OMNICOREAGENT_BACKGROUND_TASK_STORE_URL=sqlite:///.omnicoreagent/background.db ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} export OMNICOREAGENT_BACKGROUND_TASK_STORE=redis export OMNICOREAGENT_BACKGROUND_TASK_STORE_URL=redis://localhost:6379/0 ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} export OMNICOREAGENT_BACKGROUND_TASK_STORE=mongodb export OMNICOREAGENT_BACKGROUND_TASK_STORE_URI=mongodb://localhost:27017 export OMNICOREAGENT_BACKGROUND_TASK_STORE_DATABASE=omnicoreagent ``` *** ## Docker Deployment ### Generate a Dockerfile ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} omniserve generate-dockerfile --file my_agent.py ``` ### Build and run ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} docker build -t omnicoreagent-serve . docker run -p 8000:8000 -e LLM_API_KEY=$LLM_API_KEY omnicoreagent-serve ``` The generator creates a Dockerfile for the current project directory and stores only non-sensitive defaults in the image: | Setting | Value | | --------------------------------- | -------------------------------------------- | | `AGENT_PATH` | In-container path to the selected agent file | | `OMNICOREAGENT_WORKSPACE_BACKEND` | `local` | | `OMNICOREAGENT_WORKSPACE_DIR` | `/tmp/workspace` | The agent file must be inside the current Docker build context. The generator does not import or execute the agent file. S3/R2 workspace credentials are passed at runtime with `-e`, never baked into the image. ### Cloud deployment examples ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} # Local workspace (ephemeral) docker run -p 8000:8000 -e LLM_API_KEY=$LLM_API_KEY omnicoreagent-serve # AWS S3 workspace (persistent) docker run -p 8000:8000 \ -e LLM_API_KEY=$LLM_API_KEY \ -e OMNICOREAGENT_WORKSPACE_BACKEND=s3 \ -e AWS_S3_BUCKET=my-bucket \ -e AWS_ACCESS_KEY_ID=... \ -e AWS_SECRET_ACCESS_KEY=... \ -e AWS_REGION=us-east-1 \ omnicoreagent-serve # Cloudflare R2 workspace (persistent) docker run -p 8000:8000 \ -e LLM_API_KEY=$LLM_API_KEY \ -e OMNICOREAGENT_WORKSPACE_BACKEND=r2 \ -e R2_BUCKET_NAME=my-bucket \ -e R2_ACCOUNT_ID=... \ -e R2_ACCESS_KEY_ID=... \ -e R2_SECRET_ACCESS_KEY=... \ omnicoreagent-serve ``` *** ## Python API (Programmatic Control) For full programmatic control, use `OmniServe` directly in your Python script: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from omnicoreagent import OmniCoreAgent, OmniServe, OmniServeConfig, ToolRegistry tools = ToolRegistry() @tools.register_tool("get_time") def get_time() -> dict: from datetime import datetime return {"time": datetime.now().isoformat()} agent = OmniCoreAgent( name="MyAgent", system_instruction="You are a helpful assistant.", model_config={"provider": "openai", "model": "gpt-4o-mini"}, local_tools=tools, ) config = OmniServeConfig( host="0.0.0.0", port=8000, auth_enabled=True, auth_token="my-secret-token", rate_limit_enabled=True, rate_limit_requests=100, rate_limit_window=60, cors_origins=["*"], enable_docs=True, ) if __name__ == "__main__": server = OmniServe(agent, config=config) server.start() ``` Run with Python directly: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} export LLM_API_KEY=your_api_key python server.py ``` **CLI vs Python API:** * `omniserve run --agent my_agent.py` โ€” CLI loads your agent file and applies CLI flags * `python server.py` โ€” You control everything programmatically via `OmniServeConfig` **Environment Variable Precedence:** environment variables **always override** values set in `OmniServeConfig`. *** OmniServe is perfect for deploying agents as microservices, webhooks, chatbots, or any HTTP-accessible AI capability. *** **Learn More**: See [OmniServe Cookbook](https://github.com/omnirexflora-labs/omnicoreagent/tree/main/cookbook/omniserve) for more examples. # OmniCoreAgent Source: https://docs-omnicoreagent.omnirexfloralabs.com/docs/index Open Python agent harness and runtime for production AI agents OmniCoreAgent Light OmniCoreAgent Dark ## Open Python Agent Harness For Production AI Applications **OmniCoreAgent** is the harness around the model: the loop, tools, memory, context control, workspace files, MCP tools, subagents, background tasks, and REST/SSE serving boundary that make an agent usable beyond a demo. Start small with one agent and one model. Add tools, memory, workspace files, background tasks, telemetry, and OmniServe only when the application needs them. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} pip install omnicoreagent ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} export LLM_API_KEY=your_api_key_here ``` Install OmniCoreAgent, create your first agent, add one tool, and learn the next paths. Use Ask AI, Markdown export, `llms.txt`, hosted docs MCP, Cursor, VS Code, ChatGPT, Claude, and Perplexity. Add only the production extras you need later: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} pip install "omnicoreagent[redis]" pip install "omnicoreagent[serve]" pip install "omnicoreagent[all]" ``` *** ## Choose Your Path One model, one agent, one task. Register application-owned functions with `ToolRegistry`. Load tools from external MCP servers. Store conversation history in memory, Redis, MongoDB, or SQL. Give agents a file surface for notes, artifacts, and offloads. Run the same agent behind REST and SSE endpoints. Schedule durable agent work with run history, retries, and workspace output. Start from production-shaped examples. *** ## Why It Exists OmniCoreAgent is built around real agent runtime problems: The runtime supports independent tool calls in one batch, executes them concurrently, and returns one structured observation. Tool results are parsed, formatted, guardrail-checked, and offloaded when they cross the configured threshold before the model sees them. The harness detects repeated tool signatures and repeated tool interaction patterns beyond max-step exhaustion. Agents, subagents, tool offloads, notes, scratchpads, and artifacts share one local, S3, or R2-backed workspace. When enabled, the runtime checks context before each model call and acts before the configured budget is exceeded. *** ## Start Building Build your first OmniCoreAgent and run a task. Understand what OmniCoreAgent adds around the model. Install the core package or the extras your agent uses. Register application-owned Python functions as tools. Connect external MCP servers over stdio, SSE, or Streamable HTTP. Environment variables, memory, workspace, task stores, telemetry, and OmniServe settings. Production REST/SSE serving, auth, rate limits, events, and background APIs. *** ## See It In Action ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} import asyncio from omnicoreagent import 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}"} async def main(): agent = OmniCoreAgent( name="research_agent", system_instruction=( "Use tools in parallel when the calls are independent." ), model_config={"provider": "openai", "model": "gpt-4o"}, local_tools=tools, agent_config={ "context_management": {"enabled": True}, "tool_offload": {"enabled": True}, }, ) result = await agent.run( "Search for current agent papers and read notes.md. Do both at once " "if neither depends on the other." ) print(result["response"]) await agent.cleanup() asyncio.run(main()) ``` *** ## Core Documentation The main agent harness API and runtime capabilities. The implementation-backed map of the runtime pieces around the model. How the loop, tools, observations, memory, workspace, and serving layers fit. Session history across in-memory, Redis, MongoDB, and SQL database storage. Context strategies plus tool-output offloading for long-running tasks. Local, S3, or R2 files for notes, scratchpads, artifacts, and offloads. Dynamic focused workers that write outputs back into the workspace. Prompt-injection screening inside the observation pipeline. Runtime events for runs, tool calls, and streaming integrations. Run an OmniCoreAgent behind REST and SSE endpoints.