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.

Install

pip install omnicoreagent

Set API Key

Export the model key for the provider you choose:

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 for supported provider names.

Create Your First Agent

Create hello_agent.py:

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

Run It

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.

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:

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

LLM_API_KEY not found

Export the model key before running your script:

export LLM_API_KEY=your_api_key_here

OmniCoreAgent examples use LLM_API_KEY as the single public model API-key variable.

model_config requires provider and model

Set both fields:

model_config={"provider": "openai", "model": "gpt-4o"}

See Models for supported provider names.

Missing optional backend package

Install the extra for the backend you are using:

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:

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.

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

Local Tools

Workspace Files

Store notes, artifacts, scratchpads, and tool offloads.

OmniServe

Serve this agent through REST and SSE.

Configuration

Configure context, tool offload, memory, events, and workspace storage.

Use Docs With AI Tools

Ask questions against the official docs from your editor or AI tool.

Architecture

Understand the runtime layers and request flow.

Get Started

Core Concepts

How-To Guides

Changelog

Quick Start

Quick Start

Add Local Tools

Keep Continuity With Session IDs

Common First-Run Errors

Next: Add MCP Tools

Next: Turn On Heavier Harness Features

Next Steps

Local Tools

Workspace Files

OmniServe

Configuration

Use Docs With AI Tools

Architecture

​Quick Start

​Add Local Tools

​Keep Continuity With Session IDs

​Common First-Run Errors

​Next: Add MCP Tools

​Next: Turn On Heavier Harness Features

​Next Steps

Local Tools

Workspace Files

OmniServe

Configuration

Use Docs With AI Tools

Architecture

Quick Start

Add Local Tools

Keep Continuity With Session IDs

Common First-Run Errors

Next: Add MCP Tools

Next: Turn On Heavier Harness Features

Next Steps