Agent Harness

An LLM is not an agent by itself. A useful agent needs runtime behavior around the model: tools, memory, context control, a workspace, guardrails, events, delegation, and a serving boundary. That runtime is the agent harness. OmniCoreAgent is built as an open Python agent harness. You still choose the model and the tools, but the execution system around them is already assembled.

model
  + prompt contract
  + ReAct loop
  + local tools
  + MCP tools
  + parallel tool batches
  + structured observations
  + loop detection
  + memory
  + context management
  + workspace files
  + tool artifacts
  + guardrails
  + events
  + subagents
  + serving through OmniServe

Why This Matters

A basic tool-calling agent is easy to build. The hard part starts when the agent needs to work for more than one or two steps:

tool calls become sequential bottlenecks
large tool outputs fill the prompt
old context pushes the model toward provider limits
external tool output carries prompt-injection risk
the agent repeats the same failing action
workers need to split independent work and report back
intermediate files, notes, logs, and artifacts need a durable place to live
the app eventually needs a stable HTTP/SSE serving boundary

OmniCoreAgent exists because these are runtime problems, not prompt-only problems.

Implementation-Backed Capability Map

Every capability below maps to code in the repository.

Capability	What The User Gets	Main Implementation
Native tool-call contract	Provider-native function calls retain IDs and typed JSON arguments; text remains task content. Configured children use native delegate tools.	`src/omnicoreagent/core/model_protocol.py`
Parallel batch tool execution	Independent tools from one model step are resolved and executed together with timeout handling.	`src/omnicoreagent/core/agents/native_tools.py`
Tool runtime registry	Local tools, MCP tools, workspace tools, artifact tools, skills, subagent tools, and BM25 retrieval are prepared through one runtime surface.	`src/omnicoreagent/core/tools/tool_runtime_registry.py`
Structured observations	Tool outputs are normalized, guarded, formatted, and returned to the model as structured observations.	`src/omnicoreagent/core/tools/tool_result_offloader.py`
Tool output offloading	Large tool responses are written to workspace artifacts and replaced with a compact preview/reference.	`src/omnicoreagent/core/workspace/artifacts.py`
Artifact readback tools	Agents read, tail, search, and list offloaded tool responses when full content is needed.	`src/omnicoreagent/core/workspace/artifact_tools.py`
Automatic context control	Before each model call, active messages are checked and reduced when the configured context threshold is crossed.	`src/omnicoreagent/core/agents/llm_step.py`, `src/omnicoreagent/core/context_manager.py`
Loop detection	Complete native tool rounds are compared using provider/server identity, arguments and results; repeated rounds/cycles disable tools.	`src/omnicoreagent/core/agents/loop_detection.py`
Workspace files	Agents get file tools for notes, scratchpads, todos, task progress, generated work, and subagent output.	`src/omnicoreagent/core/workspace/tools.py`
Local/S3/R2 workspace storage	The same workspace interface runs on local disk, S3, or R2.	`src/omnicoreagent/core/workspace/config.py`, `src/omnicoreagent/core/workspace/storage.py`
Dynamic subagents	The lead agent spawns one or many focused workers; workers inherit model/tools/config and write output to workspace files.	`src/omnicoreagent/core/subagents.py`
MCP tools	MCP servers are loaded as external tool providers over supported transports.	`src/omnicoreagent/mcp_clients_connection/client.py`
Guardrails	User input and tool output are screened according to guardrail mode; full mode passes guardrails into the ReAct agent for output scrubbing.	`src/omnicoreagent/core/guardrails/`, `src/omnicoreagent/core/tools/tool_observation_guardrail.py`
Telemetry and metrics	Runs and tool actions emit typed telemetry events and return request metrics.	`src/omnicoreagent/core/telemetry/`, `src/omnicoreagent/core/agents/llm_step.py`
OmniServe	The same agent is exposed through REST/SSE with shared server state and lifecycle handling.	`src/omnicoreagent/serve/`

The Harness Loop

The core loop is a controlled runtime cycle:

Load session memory
Assemble prompt and tool registry
Check context before model call
Call LiteLLM
Normalize the provider turn, retaining text, calls, finish reason and usage
Resolve tool or agent calls
Execute tool batch in parallel
Normalize, guard, and offload observations
Detect repeated tool-call loops
Continue or return final answer

This loop is why OmniCoreAgent supports simple assistants and deeper long-running agents through the same entry point.

Defaults Versus Harness Features

The default agent includes the protections needed for reliable multi-step execution. Capabilities that change the tool surface or require external services remain opt-in.

Capability	Default	Reason
ReAct loop	On	This is the core agent runtime.
Session memory	On	Agents need conversation continuity.
Workspace files	On	Agents need a filesystem surface for notes and outputs.
Guardrails	On in `full` mode	Input and tool-output safety should be available without extra wiring.
Context management	On	Keeps active messages within the configured budget before each model call.
Tool offload	On	Keeps large tool payloads in workspace artifacts and sends a preview to the model.
BM25 tool retrieval	Off until enabled	Only needed when the tool list is too large for the prompt.
Dynamic subagents	Off until enabled	Only needed for delegated work.
Agent skills	Off until enabled	Only needed when packaged capabilities are installed.
Redis/Postgres/MongoDB/S3/R2	Optional extras	Install only the production backends you use.

OmniCoreAgent, OmniServe, And OmniDaemon

These are separate layers:

Layer	Purpose
OmniCoreAgent	In-process agent harness: model loop, tools, memory, context, workspace, guardrails, events, subagents.
OmniServe	HTTP/SSE serving layer for exposing an OmniCoreAgent instance as an API.
OmniDaemon	Event-driven runtime for supervised, process-isolated agents running as autonomous services.

Keeping these boundaries clear matters. OmniCoreAgent should stay focused on the agent harness. Serving and event-driven infrastructure should live outside the core loop.

Boundaries

OmniCoreAgent stays focused on the in-process agent harness. That boundary keeps the core runtime clean:

MCP brings external MCP server tools into the same runtime surface as local tools, workspace tools, skills, and harness tools.
Context management works by acting before the model call against the configured budget.
Cloud workspace storage is used when the S3 or R2 backend is installed and configured.
Distributed process supervision belongs in OmniDaemon, while HTTP/SSE serving belongs in OmniServe.

The result is a complete, open agent harness whose production pieces are already integrated and testable.

Normal, deep and background execution

OmniCoreAgent is the public agent for both normal and deep runs. Enable agent_config={"enable_subagents": True} to register the native spawn_subagents tool and let the parent create focused workers with a shared workspace. Both run() and stream() support this mode. There is no separate DeepAgent class. Configured children can also be supplied through sub_agents. The facade builds this capability through core/runtime/builder.py and core/runtime/harness_tools.py; worker creation lives in core/subagents.py. Background execution is a separate scheduling and persistence layer around the same agent runtime, exposed through BackgroundAgentManager. It provides durable job lifecycle and retry handling. Retired router/sequential/parallel workflow classes are not required for native parallel tool calls or child batches.

Get Started

Make It Safe

Run It

See and Improve

Build

How It Works

Reference

HTTP API (OmniServe)

Releases

Agent Harness

Agent Harness

Why This Matters

Implementation-Backed Capability Map

The Harness Loop

Defaults Versus Harness Features

OmniCoreAgent, OmniServe, And OmniDaemon

Boundaries

Normal, deep and background execution

​Agent Harness

​Why This Matters

​Implementation-Backed Capability Map

​The Harness Loop

​Defaults Versus Harness Features

​OmniCoreAgent, OmniServe, And OmniDaemon

​Boundaries

​Normal, deep and background execution

Agent Harness

Why This Matters

Implementation-Backed Capability Map

The Harness Loop

Defaults Versus Harness Features

OmniCoreAgent, OmniServe, And OmniDaemon

Boundaries

Normal, deep and background execution