Migrate to Agentium 4

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:

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. 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:

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 and Socket.IO.

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 for verification and rollback. Retries can repeat external effects. Use application idempotency or a replay-aware durable driver; 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.

See voice sessions, streaming voice, and 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.

Review new opt-in systems

Durable tasks, persistent event/artifact records, A2A 1.0, MCP v2, and outbound telephony introduce explicit host responsibilities. They do not silently replace local APIs or guarantee exactly-once external effects.

Reference

Package APIs

Type guides

Upgrades

Architecture and tooling

Migrate to Agentium 4

What changed

Replace Agent.deep

Make hosting mode explicit

Migrate queues before upgrading BullMQ

Update voice clients

Update observability

Review new opt-in systems

​What changed

​Replace Agent.deep

​Make hosting mode explicit

​Migrate queues before upgrading BullMQ

​Update voice clients

​Update observability

​Review new opt-in systems

What changed

Replace Agent.deep

Make hosting mode explicit

Migrate queues before upgrading BullMQ

Update voice clients

Update observability

Review new opt-in systems