> ## Documentation Index
> Fetch the complete documentation index at: https://docs-omnicoreagent.omnirexfloralabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> 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.

<Steps>
  <Step title="Install">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    pip install omnicoreagent
    ```
  </Step>

  <Step title="Set API Key">
    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
    ```

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="Create Your First Agent">
    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())
    ```
  </Step>

  <Step title="Run It">
    ```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.
  </Step>
</Steps>

***

## 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

<AccordionGroup>
  <Accordion title="LLM_API_KEY not found">
    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.
  </Accordion>

  <Accordion title="model_config requires provider and model">
    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.
  </Accordion>

  <Accordion title="Missing optional backend package">
    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.
  </Accordion>
</AccordionGroup>

***

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

<Note>
  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.
</Note>

***

## 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

<CardGroup cols={3}>
  <Card title="Local Tools" icon="toolbox" href="/docs/core-concepts/local-tools">
    Register Python functions as tools.
  </Card>

  <Card title="Workspace Files" icon="folder-tree" href="/docs/core-concepts/workspace-files">
    Store notes, artifacts, scratchpads, and tool offloads.
  </Card>

  <Card title="OmniServe" icon="server" href="/docs/how-to-guides/omniserve">
    Serve this agent through REST and SSE.
  </Card>

  <Card title="Configuration" icon="gear" href="/docs/how-to-guides/configuration">
    Configure context, tool offload, memory, events, and workspace storage.
  </Card>

  <Card title="Use Docs With AI Tools" icon="sparkles" href="/docs/getting-started/use-docs-with-ai-tools">
    Ask questions against the official docs from your editor or AI tool.
  </Card>

  <Card title="Architecture" icon="sitemap" href="/docs/core-concepts/architecture">
    Understand the runtime layers and request flow.
  </Card>
</CardGroup>