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