How it fits together
OmniCoreAgent is an agent runtime for Python. This page is the map: the four layers it is made of, one run traced through all of them, and which setting turns what on. Every other page goes deeper into one piece.Four layers
The harness is what makes a model an agent. The other three are what let you
give that agent real work: you know what it may do before it does it, a crash
does not make it do something twice, and afterwards you can see exactly what
happened.
You reach all four the same way, with the same agent object: in your Python
code, from the
omnicoreagent run command for scripts and CI
(Headless runs), served over HTTP by
OmniServe (omniserve run, part of this package; OmniServe),
or on a schedule as a background run
(Background agents).
One run, through every layer
What happens when your code callsawait agent.run("Refund order 1042"):
1
Set-up (first run only)
The model client loads and the tools are assembled: yours, your MCP
servers’, the workspace file tools, and, when switched on,
execute, code
mode, skills and spawn_subagents. There is an execute tool only when a
sandbox is configured: a fresh agent has none. The policy is loaded and
hashed.2
The run starts its record and its trace
Durability: a run record is saved in the memory store with status
running, and a heartbeat keeps it marked alive. The record: a trace
starts with the request and a header (model, tools, policy hash,
settings). In a fresh process, loading the model client can take seconds;
the trace shows it as a model.client.load span. Control: the
guardrail screens the request for prompt injection (guardrail_mode:
full, the default, also screens every tool result; input_only; off).3
The harness takes a step
The context is built from the system instruction, the session’s history
and the run so far, kept under a token budget. Control: if budgets are
set, the call is checked before the model is called (its cost held when its
price is known, otherwise the call counted); a run
that cannot afford it pauses for a person or ends, as the budget says.
Then the model answers, or asks for tools.
4
Each tool call is decided before it runs
Control: the call becomes a capability (for example
workspace.files.delete on prod/db.txt, or process.exec for a shell
command), and the policy decides. Allowed, it runs. Refused, the model is
told why. Asked, the run pauses (awaiting_approval) until a person
decides. Durability: a call is recorded as started before it runs and
as finished after. A command runs in the sandbox, with the workspace files
copied in before it and its new files copied back after, each copy decided
by the same file rules as read_file and write_file. A file an ask rule
covers, a hidden, binary or oversized file, and anything past the file
limit is skipped, and the model is told.5
Steps repeat until the answer
Results go back to the model, the guardrail screens them, large ones are
saved to the workspace with a preview. Steps repeat until the model
answers, or a limit (steps, the deadline, a budget) stops the run.
6
The run ends
The record is finished, the trace ends, and budgets are settled. You get
the answer with the run’s
status, run_id and trace_id.When it pauses
A run waiting for a person (an approval or a budget top-up) keeps everything it has done. The decision can come from your code, over HTTP, or from another process; thenresume(run_id) continues from where it stopped. A worker’s
question pauses its lead too, and the lead’s decision reaches the worker.
When the process dies
With a store that keeps run state (all the built-in ones: SQLite, PostgreSQL, Redis, MongoDB), another process callsresume(run_id) once the dead
process’s heartbeat has lapsed. What happens to the call that was running:
Where each feature sits
Settings are keys ofagent_config unless written with = (a constructor argument).
Every setting is in the agent settings reference.
What runs where
Next
- Quickstart: a first agent in minutes.
- Security model: control, in depth.
- Durable runs: durability, in depth.
- Read a run: the record, in depth.