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.

Minimal Agent

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

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.

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.

await agent.connect_mcp_servers()

`list_all_available_tools()`

Return all currently available tools from MCP, local tools, skills, workspace tools, and harness tools.

tools = await agent.list_all_available_tools()

`cleanup()`

Close MCP connections and release runtime state.

await agent.cleanup()

Session Management

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:

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.

Get Started

Core Concepts

How-To Guides

Changelog

OmniCoreAgent

OmniCoreAgent

Minimal Agent

What The Harness Owns

Defaults And Opt-In Capabilities

Parameters

Full Harness Configuration

Core Methods

`run()`

`connect_mcp_servers()`

`list_all_available_tools()`

`cleanup()`

Session Management

Runtime Switching

Best Practices

​OmniCoreAgent

​Minimal Agent

​What The Harness Owns

​Defaults And Opt-In Capabilities

​Parameters

​Full Harness Configuration

​Core Methods

​run()

​connect_mcp_servers()

​list_all_available_tools()

​cleanup()

​Session Management

​Runtime Switching

​Best Practices

OmniCoreAgent

Minimal Agent

What The Harness Owns

Defaults And Opt-In Capabilities

Parameters

Full Harness Configuration

Core Methods

`run()`

`connect_mcp_servers()`

`list_all_available_tools()`

`cleanup()`

Session Management

Runtime Switching

Best Practices