> ## 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.
# Upgrading to 0.4
> From 0.3: what runs unchanged, what was removed and what took its place, and the defaults that changed
# 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:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
The workflow classes are gone; ordinary Python composes runs, and each run
keeps its own trace.
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/docs/core-concepts/sub-agents).
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](/docs/core-concepts/sub-agents) and
[Workspace files](/docs/core-concepts/workspace-files).
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](/docs/core-concepts/workspace-files).
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](#4-defaults-that-changed)) |
| `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](/docs/core-concepts/events) and
[Observability](/docs/how-to-guides/observability).
`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](/docs/core-concepts/background-agents).
`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.
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:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/docs/reference/telemetry-config) and
[Guardrails and privacy](/docs/core-concepts/guardrails).
## 5. What is new
Nothing here needs to change for the upgrade; it is what 0.4 adds.
[A tour](/docs/getting-started/tour) shows most of it in fifteen minutes.
Allow, deny or ask a person, per capability; budgets the agent cannot overspend.
Commands in Docker, E2B, Daytona, Modal or Vercel, with a network policy.
`resume`, `interrupt`, `steer`: a run survives a crash and a person's pause.
`omnicoreagent run` for CI and evaluations; `omnicoreagent harbor` for Terminal-Bench.
Every setting, method and command is in the [reference](/docs/reference/omnicoreagent).