> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate to Agentium 4

> Upgrade from Agentium 3.x to 4.0.0 with explicit package, execution, and integration boundaries.

Agentium **4.0.0** introduces the separate `@agentium/harness` package and removes several deprecated or ambiguous APIs. Upgrade related Agentium packages together, then apply the changes below. Keep state migrations separate from dependency installation.

## What changed

| Area | Previous API or behavior | Agentium 4.0.0 |
| - | - | - |
| Harness | `Agent.deep()`, Agent `harness` / `harnessOptions` / `replaceTools` | Explicit definitions and `HarnessRuntime` from `@agentium/harness` |
| Workspace | `workspace: "./project"` | `workspace: { path: "./project", mode: "read" }` or explicit `"write"` |
| HTTP and text Socket.IO | Security could be omitted | Required `security: { mode: "local" }` or authenticated identity and ownership hooks |
| Local reranking | `ColbertReranker`, `ColbertRerankerConfig` | `CrossEncoderReranker`, `CrossEncoderRerankerConfig`; provider ID `cross-encoder-local` |
| Protocol aliases | `LegacyMCPToolProvider`, `A2ALegacyRemoteAgent`, `createA2ALegacyServer` | Removed aliases; original `MCPToolProvider`, `A2ARemoteAgent`, and `createA2AServer` remain |
| Worker retries | `WorkerConfig.attempts` / `backoffDelay` | Producer `defaultJobOptions` or per-enqueue retry options |
| Queue name | `agentium:jobs` | `agentium-jobs`; producer and worker must use the same valid name |
| Native voice | Remote `prompt` / `realtimePrompt` configuration | Removed; use application-owned instructions and transcription context |
| Sandbox | `backend: "docker"` advertised | Rejected before host I/O; choose trusted `unix-local` or an explicit remote adapter |
| Telemetry | Automatic content capture | Metadata by default; explicit bounded content capture at tracer and destination |
| Runtime | Older Node versions | Node `^22.18.0` or `^24.11.0` |

Public Zod 3 support, legacy session snapshot readers, and buffered `VoicePipeline` remain. An upgrade does not automatically convert existing session or protocol storage into durable execution.

## Replace Agent.deep

For a small Agent, configure only the capabilities you need:

```typescript theme={null}
import { Agent, openai } from "@agentium/core";

const agent = new Agent({
  name: "project-reader",
  model: openai("gpt-4o"),
  workspace: { path: "./project", mode: "read" },
  contextFiles: { cwd: "./project" },
  skillDirs: ["./project/.agents/skills"],
});
```

For composable abilities and aggregate controls, follow the [harness guide](/harness/overview). Definitions select capabilities; host grants and execution policy authorize them. Harness canonical history is separate from Agent backing storage. Scope shared note storage to the authenticated tenant/user and keep it host-owned.

## Make hosting mode explicit

A trusted local router now needs:

```typescript theme={null}
import { createAgentRouter } from "@agentium/transport";

// Integration fragment: app is Express; assistant is an existing Agent.
app.use("/api", createAgentRouter({
  registry: false,
  agents: { assistant },
  security: { mode: "local" },
}));
```

Hosted HTTP and Socket.IO applications must resolve identity from verified credentials and authorize each resource. New session IDs require an atomic owner binding; existing IDs require an ownership check. JWT scopes alone are insufficient. See [Express](/transport/express) and [Socket.IO](/transport/socketio).

## Migrate queues before upgrading BullMQ

The adapter supports BullMQ **5.81.5+ in v5** and **6.3.11+ in v6**. Migrate persisted legacy repeat records while still on v5; v6 cannot perform that maintenance. Stop old writers, pause and drain the queue, back up state, remove legacy records, and create stable scheduler IDs. Follow [schedule migration](/queue/migration) for verification and rollback.

Retries can repeat external effects. Use application idempotency or a replay-aware [durable driver](/durable/overview); registering an ordinary Agent as a worker does not establish that contract.

## Update voice clients

* Import voice adapters from `@agentium/core/voice`.
* Native OpenAI input transcription defaults to `gpt-transcribe`; Gemini Live defaults to `gemini-3.8-live` in this implementation. Validate your own audio corpus when changing models.
* Socket.IO clients acknowledge audio sequence numbers and actual playback completion. Discard queued playback on `voice.clear`.
* Reconnection is opt-in. OpenAI fresh recovery loses provider history; Gemini recovery requires a safe resumable checkpoint. Uncertain tool effects require host reconciliation.
* `createRealtimeCall()` accepts WebRTC SDP. It does not place outbound SIP calls; use the separate [telephony layer](/voice/telephony).

See [voice sessions](/voice/overview), [streaming voice](/voice/streaming), and [voice gateway](/voice/gateway).

## Update observability

Use `LangfuseOTLPExporter` or `"langfuse-otlp"` for the OTLP integration. The old `LangfuseExporter` remains an explicit compatibility path. `OTelExporter` sends HTTP JSON; use a host SDK bridge for protobuf. Close observers with `shutdown()` to detach and drain owned exports. See [observability](/observability/overview).

## Review new opt-in systems

[Durable tasks](/durable/overview), [persistent event/artifact records](/durable/records), [A2A 1.0](/a2a/v1), [MCP v2](/mcp/v2), and [outbound telephony](/voice/telephony) introduce explicit host responsibilities. They do not silently replace local APIs or guarantee exactly-once external effects.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.