Upgrading

Coming from 0.3, start here: sections 1 to 5 cover 0.3 to 0.4. Each later release has its own section below them, ending with From 0.4 to 0.5.0. Most 0.3 code runs on 0.4 unchanged: an agent built from a name, an instruction, a model, local tools and MCP servers, run() and its result, sessions, memory, and the OmniServe routes. What changed is listed below, all of it measured: the public surface of 0.3.8 was installed next to 0.4 and compared name by name, setting by setting and route by route.

On 0.3.9? That release cannot build an agent: it was published without one of its own modules, and OmniCoreAgent(...) raises ModuleNotFoundError: No module named 'omnicoreagent.core.workspace'. If you are pinned to it, you are effectively upgrading from 0.3.8 — this page is for you.

1. Python 3.12 or later

0.4 and later need Python 3.12, 3.13 or 3.14. On 3.10 or 3.11, pip install -U omnicoreagent now stops with a message saying so. Before the guard release (0.3.10, published with 0.4.3) it did not fail: it quietly stayed on 0.3.9 (Installation). Check what you got:

python --version
pip show omnicoreagent | head -2

The omnicoreagent command is new in 0.4; if omnicoreagent --version is not found, the upgrade did not happen.

2. What runs unchanged


`OmniCoreAgent(name, system_instruction, model_config, mcp_tools, local_tools, sub_agents, agent_config, memory_router)`	Same arguments, by keyword. Pass the rest by keyword too: the ninth position, `event_router` in 0.3, is `telemetry_store` now.
`await agent.run(query, session_id)`	Same call. The result keeps `response`, `session_id`, `agent_name` and `metric`, and adds `status`, `termination_reason`, `run_id` and `trace_id`.
`model_config`	Every 0.3.8 key: `provider`, `model`, `temperature`, `max_tokens`, `max_context_length`, `top_p`, `top_k`.
`mcp_tools`	`stdio`, `sse` and `streamable_http` servers, `headers`, `timeout`, `sse_read_timeout`, `auth`.
`agent_config`	Every 0.3.8 key but `memory_tool_backend` (see below).
`ToolRegistry`, `@tools.register_tool(...)`	Unchanged; `idempotent=True` is new.
`MemoryRouter` and its stores	Unchanged.
Session methods	`get_session_history`, `clear_session_history`, `generate_session_id`, `get_memory_store_type`, `switch_memory_store`, `get_metrics`.
OmniServe	Every 0.3.8 route. `/run/sync` returns what it did plus `status`, `run_id` and `trace_id`; `response` is `null` while a run waits for an approval.

3. What was removed, and what took its place

SequentialAgent, ParallelAgent, RouterAgent

The workflow classes are gone; ordinary Python composes runs, and each run keeps its own trace.

import asyncio

from omnicoreagent import OmniCoreAgent

model = {"provider": "openai", "model": "gpt-5.4-mini"}
researcher = OmniCoreAgent(name="researcher", system_instruction="Research.", model_config=model)
writer = OmniCoreAgent(name="writer", system_instruction="Write.", model_config=model)


async def main():
    # In sequence (was SequentialAgent): one run's answer is the next one's input.
    notes = await researcher.run("What changed in Python 3.14?")
    article = await writer.run(f"Write a short post from these notes:\n{notes['response']}")

    # In parallel (was ParallelAgent).
    a, b = await asyncio.gather(
        researcher.run("Summarize PEP 649."), researcher.run("Summarize PEP 750.")
    )


asyncio.run(main())

For routing (was RouterAgent), give one agent the others as sub_agents=[billing, support]: the model gets a delegate_billing and a delegate_support tool and chooses. See Subagents.

DeepAgent

Its parts are settings on any agent now: enable_subagents=True lets the model spawn focused workers with spawn_subagents, and workspace files (on by default) give it the files it plans and works in. See Subagents and Workspace files.

agent_config['memory_tool_backend']

The memory_* tools are gone. The agent’s files live in its workspace, on by default (enable_workspace_files), with ls, read_file, write_file, edit_file, glob, grep and the rest; local disk, S3 or R2 through workspace_config. A 0.3 config that still sets the key fails when the agent is built and names this replacement. See Workspace files.

EventRouter, event_router=, and the event-store methods

0.3’s event store is replaced by telemetry: every run is recorded as a trace, one readable record from the question to the answer, with every model call, tool call, approval and budget decision.

0.3	0.4
`event_router=EventRouter(...)`	nothing to pass: runs are recorded by default (see Defaults)
`await agent.get_events(session_id)`	`await agent.get_trajectory(result["trace_id"])`
`agent.stream_events(session_id)`	`agent.run(query, on_event=callback)` or `async for event in agent.stream(query)`
`get_event_store_type`, `get_event_store_info`, `is_event_store_available`, `switch_event_store`	`telemetry_config` chooses where traces are kept
`await agent.get_trace(session_id)`	still works, and also takes `trace_id=` or `run_id=`

See Telemetry events and Observability.

BackgroundOmniCoreAgent, BackgroundTaskScheduler, APSchedulerBackend, TaskRegistry

BackgroundAgentManager remains, rebuilt around tasks and runs kept in a task store (memory, SQL, Redis or MongoDB), with leases, retries and cron. It no longer needs APScheduler; the background extra is gone.

0.3	0.4
`create_agent({"agent_id": ..., "model_config": ..., "task_config": {...}})`	`register_agent("id", agent)`, then `register_task(task_id=..., agent_id="id", query=..., schedule=...)`
`task_config["interval"]` (seconds)	`schedule={"type": "interval", "seconds": 3600}`; also `once` and `cron`
`task_config["max_retries"]`, `["retry_delay"]`	`retry_policy={"max_retries": 2, "initial_delay_seconds": 5}`
`task_config["timeout"]`	`timeout_seconds=`
`task_config["session_id"]`	`session_policy={"mode": "fixed", "session_id": ...}`
`start_agent`, the scheduler	`await manager.start()`
`run_task_now`	`run_now(task_id)`
`pause_agent`, `resume_agent`	`pause_task`, `resume_task`
`stop_agent`	`cancel_run(run_id)`
`remove_task`, `delete_agent`	`delete_task`, `unregister_agent`
`get_agent_status`, `get_task_config`	`get_task_status`, `get_task`, `get_run`
`update_task_config`	`update_task`

See Background agents.

OmniAgent, and the retry and circuit-breaker helpers

OmniAgent was another name for OmniCoreAgent; use OmniCoreAgent. with_retry, retry_async, RetryConfig, RetryStrategy, CircuitBreaker, CircuitBreakerConfig, Configuration and get_metrics were OmniServe internals exported at the top level; they are not public in 0.4. Model calls retry with backoff on their own.

omniserve run --reload

Removed. Every other omniserve option is unchanged.

4. Defaults that changed

An agent built the 0.3 way behaves differently in these ways:

Setting	0.3.8	0.4	Why
`max_steps`	15	50	Real tasks took more than 15 steps.
`tool_call_timeout`	30 s	180 s	Commands and builds take longer than 30 s.
`context_management`	off	on (100,000-token budget)	A long run stays under the model’s window.
`tool_offload`	off	on	A large tool result is saved as a file; the model gets a preview.
`guardrail_mode`	off unless `guardrail_config` was set	`full`	Inputs and tool results are screened for prompt injection. `"off"` restores 0.3.
`enable_workspace_files`	—	on, in `./workspace`	The agent has files to work in.
Telemetry	—	on, in `./workspace/telemetry/`	Every run is recorded, prompts included, kept 7 days.
Privacy	—	the record is redacted	Emails, phone numbers, SSNs and card numbers are replaced in telemetry; the model, memory, files, stream and answer see the real data.
`run_retention_days`	—	30 (from 0.4.1)	A finished run’s record is removed 30 days after it started; a run waiting for a person never is. `None` keeps every record.

To keep 0.3’s step limit and timeout, and every run record, set them:

agent_config = {"max_steps": 15, "tool_call_timeout": 30, "run_retention_days": None}

Telemetry writes to your disk from the first run. To leave model prompts and responses out of it, keep it in memory only, or move it:

telemetry_config = {"capture": "default"}            # without model prompts
telemetry_config = {"storage": "memory"}             # this process only
telemetry_config = {"storage_path": "/var/log/agent/traces.jsonl"}

See the TelemetryConfig reference and Guardrails and privacy.

5. What is new

Nothing here needs to change for the upgrade; it is what 0.4 adds. A tour shows most of it in fifteen minutes.

Policies and approvals

Allow, deny or ask a person, per capability; budgets the agent cannot overspend.

Sandboxes

Commands in Docker, E2B, Daytona, Modal or Vercel, with a network policy.

Durable runs

resume, interrupt, steer: a run survives a crash and a person’s pause.

Headless runs and Harbor

omnicoreagent run for CI and evaluations; omnicoreagent harbor for Terminal-Bench.

Every setting, method and command is in the reference.

From 0.4.0 or 0.4.1 to 0.4.2

Code that runs on 0.4.1 runs on 0.4.2, with these exceptions, each a setting that now does what its name says:

If you	0.4.1	0.4.2	Do
Build `MemoryRouter("sql")`, `"redis"` or `"mongodb"` without its URL	Fell back to memory, silently	`ValueError` naming the variable	Set `DATABASE_URL`, `REDIS_URL` or `MONGODB_URI`, or use `MemoryRouter("in_memory")`
Set `denied_hosts`, `environment.secret_refs`, or `allowed_hosts` on Daytona	Accepted, not enforced	Refused when the agent is built	Remove them; see sandbox providers for what each provider enforces
Use `overlap_policy="cancel_previous"`	The earlier run finished, then was marked cancelled	The earlier run is interrupted	Nothing, unless you relied on it finishing
Use `misfire_policy="skip_missed"`	Ran once for missed time	Skips it	Use `run_once`, now the default, to keep the old behaviour
Read OmniServe’s `504` `detail` as a string	A string	An object with `message` and `run_id`	Read `detail["message"]`

Finished run records and traces are kept as before; traces whose process died are now removed by trace retention as well. The changelog lists every fix.

From 0.4.2 to 0.4.3

Code that runs on 0.4.2 runs on 0.4.3. One behaviour changed, and only after a crash:

If	0.4.2	0.4.3	Do
A run is recovered after its process died while a turn’s calls were still running, and one of them had already finished	That call ran again, even if its tool was not idempotent	It runs again only if its tool is idempotent; otherwise the model is told it finished and its result was lost	Nothing; mark tools that are safe to repeat `idempotent=True` so they are re-run instead

See what is guaranteed for the whole contract.

From 0.4.3 to 0.4.4

Code that runs on 0.4.3 runs on 0.4.4. A policy without command rules decides exactly as before, with the same policy hash.

If	0.4.3	0.4.4	Do
A run is paused on an approval for a shell command when you upgrade	Its approval was not bound to the command text	Bound to it, so the pending approval no longer matches and is asked again	Decide it again; approvals of tools and everything else keep their digest
A policy rule has a key it does not know (a typo)	A bare `TypeError`, or on load from a file an “Invalid policy file” error	`PolicyLoadError: rule <id>: unknown key(s) <key>`	Fix the key
You read `budget_status` or call `abandon_run` from a process that never ran a query	`[]`, and holds left on the budget	The run’s budgets, and holds released	Nothing

From 0.4 to 0.5.0

One change you will notice: an agent is governed unless it says otherwise. Code that runs on 0.4 runs on 0.5.0 unless it does one of the things the default profile, permissive-dev, refuses or asks about:

If your agent	0.4 (governance off unless enabled)	0.5.0 (on by default)	Do
Uses its own tools, memory, workspace, sub-agents, background runs	Ran	Runs, unchanged	Nothing
Runs a shell command on the host (the `local` provider)	Ran	Refused by `deny_unrestricted_process_exec`	Use a sandbox provider, or start from `interactive-dev` as the local provider recipe shows. An allow rule added to `permissive-dev` does not help: its deny rule wins over any allow
Is given a sandbox with network	Ran	Asks a person first (`ask_sandbox_network`)	Decide it, or allow `sandbox.network.configure` in your policy
Reads a raw secret, installs a package, reaches the network or host files without a rule	Ran	Refused	Add the rule for what it needs (Policies)
Relied on tool argument values in its traces under `capture="default"`	Recorded	Recorded by name, not value	`telemetry_config={"capture": "full"}` (the capture you get without setting one)
Set `"enabled": True` without a profile	`interactive-dev`	`interactive-dev`	Nothing
Sets `sandbox_manifest.filesystem_policy`	Approved, applied by no provider	Refused: removed	Remove it; choose which files go in with the workspace bridge’s `include` and `exclude`
Asks a sandbox provider for a setting it does not apply (a workspace mount on e2b, `resources.timeout_seconds`)	Approved, then ignored	Refused when the agent is built, naming the setting	Remove it, or use a provider that applies it (What stops harm)
Serves with OmniServe behind a proxy	`X-Forwarded-For` trusted from anyone	Read only from `OMNICOREAGENT_SERVE_TRUSTED_PROXIES`	List your proxy’s address
Relies on CORS credentials	Sent by default, to any origin	Off by default, never with `*`	List your front end in `OMNICOREAGENT_SERVE_CORS_ORIGINS` and set `OMNICOREAGENT_SERVE_CORS_CREDENTIALS=true`

To keep 0.4’s behaviour exactly: agent_config={"governance_config": {"enabled": False}}.

Get Started

Make It Safe

Run It

See and Improve

Build

How It Works

Reference

HTTP API (OmniServe)

Releases

Upgrading

Upgrading

1. Python 3.12 or later

2. What runs unchanged

3. What was removed, and what took its place

4. Defaults that changed

5. What is new

Policies and approvals

Sandboxes

Durable runs

Headless runs and Harbor

From 0.4.0 or 0.4.1 to 0.4.2

From 0.4.2 to 0.4.3

From 0.4.3 to 0.4.4

From 0.4 to 0.5.0

​Upgrading

​1. Python 3.12 or later

​2. What runs unchanged

​3. What was removed, and what took its place

​4. Defaults that changed

​5. What is new

Policies and approvals

Sandboxes

Durable runs

Headless runs and Harbor

​From 0.4.0 or 0.4.1 to 0.4.2

​From 0.4.2 to 0.4.3

​From 0.4.3 to 0.4.4

​From 0.4 to 0.5.0

Upgrading

1. Python 3.12 or later

2. What runs unchanged

3. What was removed, and what took its place

4. Defaults that changed

5. What is new

From 0.4.0 or 0.4.1 to 0.4.2

From 0.4.2 to 0.4.3

From 0.4.3 to 0.4.4

From 0.4 to 0.5.0