Upgrading to 0.4

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 needs Python 3.12, 3.13 or 3.14. On 3.10 or 3.11, pip install -U omnicoreagent does not fail: it quietly stays on 0.3.9. 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.

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

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

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.

Get Started

Core Concepts

How-To Guides

Reference

HTTP API (OmniServe)

Releases

Upgrading to 0.4

Upgrading to 0.4

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

​Upgrading to 0.4

​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

Upgrading to 0.4

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