Runtime v1 agents

Apollo agents run on one of two runtime generations. Runtime v2 is the current one — every other page in these docs describes it. Agents created before the runtime v2 rollout run on runtime v1, and a handful of things work differently for them. This page collects all of those differences so the main pages don’t have to.

Which runtime is my agent on?

As a rule of thumb, agents created before August 1 2026 run on runtime v1, and agents created on or after that date run on runtime v2. When you’d rather not rely on a date, two things tell you for sure:

Tell	Runtime v1	Runtime v2
Thread ids the agent produces	24-character hex — `68e78d0dc5a4b19a030d03d6`	UUID — `3f9c2a1e-7b0d-4c52-9e1a-6d2f8b4c0a17`
`runtime_version` on the agent’s live version	A `1.x` value, or none	A runtime build such as `0.8.0`

The thread id is the quickest check — send one message and look at the thread_id that comes back.

What’s different

Sending is identical on both runtimes: sendMessage, streamMessage, rerun, and the channel openers route automatically based on the agent behind your key, and you never pick a runtime when sending. The differences surface in a few places only:

Capability	Runtime v1	Runtime v2
Send / stream / rerun / channels	✅ Same calls	✅ Same calls
Reading threads back	No selector needed	Pass `runtime_version` (e.g. `'0.8.0'`) — see below
Live streaming	`streamMessage` (SSE) or a WebSocket session	`streamMessage` (SSE)
`suggestions` stream frame	Not emitted — `followup_suggestions` ride on the message	Emitted after the terminal `message`
Traces (`threadTrace`, `interactionTrace`)	✅	Not yet available
`runtime_version` build pin on sends	Ignored	Honored (advanced; normally omit)
Thread id format	24-character hex	UUID

Reading runtime v1 threads

A thread lives on the runtime that created it, and thread reads name that runtime with runtime_version. Runtime v1 is the default — so reads of runtime v1 threads take no selector at all, while reads of runtime v2 threads must carry one:

// Runtime v1 thread — the default target, nothing to pass
const v1Messages = await client.messaging.listMessages(v1ThreadId);

// Runtime v2 thread — name the runtime the agent runs on
const v2Messages = await client.messaging.listMessages(threadId, {
  runtime_version: '0.8.0',
});

The rule is on the major version: a 1.x value (or none) selects runtime v1; any value outside the 1.x family selects runtime v2, and it doesn’t have to match the thread’s exact build. Asking the wrong runtime returns 404 — the most common symptom is a UUID thread that “disappears” when read without runtime_version. The same applies on the management client and the REST API:

Read	Runtime v1 thread	Runtime v2 thread
`messaging.listMessages(threadId)` · `GET /messaging/v1/threads/{threadId}/messages`	As is	`runtime_version`
`threads.getThread` · `getThreadMessages` · `updateThread` · `GET`/`PATCH /management/v1/threads/{threadId}`	As is	`runtime_version`
`threads.listThreads` · `GET /management/v1/threads`	All filters (`project_id`, `tool`, `rule`, `param`, …)	`runtime_version` plus `agent_id` or `user_id` — only `agent_id`, `user_id`, and `created` (with `agent_id`) apply; runtime v1–only filters return a clear 400

Traces

Runtime v1 agents expose the reasoning trace behind every interaction — what the agent understood, which rules fired, what it decided:

// Messaging client (publishable key)
const traces = await client.messaging.threadTrace(threadId);          // one per interaction, paginated
const trace = await client.messaging.interactionTrace(interactionId);

// Management client (organization API key)
await management.threads.getThreadTrace(threadId);
await management.threads.getInteractionTrace(interactionId);

threadTrace is paginated — pass page[size], page[after] / page[before], and sort_by / sort_order in an optional second argument. On a runtime v1 WebSocket session opened with include_trace=true, the final message envelope also embeds the trace as data.trace_info. Trace support for runtime v2 is coming; until then these calls apply to runtime v1 agents only.

WebSocket sessions

Runtime v1 agents accept a bidirectional WebSocket session through client.connect() — typed envelopes, automatic reconnection, and seq-based resume. The full protocol is on the WebSocket page (SDK) and API → WebSocket (wire format). Runtime v2 agents don’t open sessions: connect() answers with an error envelope explaining the session is SSE-only. They stream over HTTP with streamMessage instead — one call per turn, the same token-by-token reply, resumable with Last-Event-ID, and nothing to keep alive. The frames map almost one to one:

WebSocket session (runtime v1)	`streamMessage` (runtime v2)
`const socket = await client.connect(); socket.sendMessage({ type: 'message', agent_id, user_id, text })`	`const stream = await client.messaging.streamMessage({ body: { user_id, text } })`
`socket.on('message', (envelope) => …)` and switch on `envelope.type`	`for await (const event of stream)` and switch on `event.type`
`thread` · `event` · `message` · `error` envelopes	The same four types, plus `suggestions` after the terminal `message`
Token text at `envelope.data.data.text` (event `thread-message-text-content-updated`)	Token text at `event.data.text`
`agent_id` required on every frame	Not needed — the agent comes from your key
Reconnect, then `socket.sendResume({ type: 'resume', resume_after: lastSeq })`	Call again with `'Last-Event-ID': String(lastSeq)` in the request
`socket.close()`	Nothing to close — the stream ends with the turn

Moving an integration to runtime v2

When the agent behind your key moves to runtime v2, sends keep working untouched. Work through this list for everything else:

Thread reads — add runtime_version (the build your agent runs on, e.g. '0.8.0') to listMessages, threads.getThread, getThreadMessages, and updateThread; scope listThreads with runtime_version plus agent_id or user_id.
Thread ids — stop validating them as 24-character hex ids; runtime v2 ids are UUIDs.
Streaming — replace connect() + sendMessage frames with streamMessage, drop agent_id from the request, and resume with Last-Event-ID instead of a resume frame.
Follow-up suggestions — handle the new suggestions frame (data.followup_suggestions, with the thread_id and interaction_id it belongs to) instead of reading them off the message.
Traces — guard threadTrace / interactionTrace / getThreadTrace / getInteractionTrace calls until runtime v2 trace support lands.

Still importing ApolloClient from @aui.io/aui-client 1.x (the ia-controller client)? Upgrade to v3 first — the SDK upgrade guide maps every call — then come back to this page for the runtime differences.

​Which runtime is my agent on?

​What’s different

​Reading runtime v1 threads

​Traces

​WebSocket sessions

​Moving an integration to runtime v2

Which runtime is my agent on?

What’s different

Reading runtime v1 threads

Traces

WebSocket sessions

Moving an integration to runtime v2