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

# Getting Started Cookbook

> 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