Events and items
Use events for live progress and items for persistent conversation and execution output.
An Event communicates an input or a change while a Session runs. An Item records a message or an execution result that your application can retrieve afterward.
Open a live stream
Subscribe before submitting input. Using an existing sessionId and configured client:
const stream = await client.beta.agents.sessions.events.stream(sessionId);
try {
for await (const event of stream) {
if (event.type === 'agent.session.turn.output_text.delta') {
process.stdout.write(event.delta);
}
if (event.type === 'agent.session.requires_action') {
console.log('Return the requested function results:', event);
break;
}
if (event.type === 'agent.session.idle' || event.type === 'agent.session.failed') {
console.log(event);
break;
}
}
} finally {
stream.controller.abort();
}
Send input from another request handler while this subscription is active. For a single-script first run, use stream: true during Session creation as shown in the quickstart.
Event families
| Family | What your application does |
|---|---|
| Session lifecycle | Track creation, active work, required actions, idle, and failure. |
| Turn lifecycle | Associate progress and outcomes with a Turn ID. |
| Output text deltas | Append text to the current output message. |
| Output items | Retain complete messages and tool output. |
| Input events | Submit user input, function results, or cancellation. |
Reasoning summaries and function calls are currently emitted as completed items. Incremental reasoning and function-argument deltas are not forwarded.
Retrieve Items
const items = await client.beta.agents.sessions.items.list(sessionId, {
order: 'asc', limit: 100,
});
for (const item of items.data) console.log(item);
Use the SDK's pagination helpers for larger histories. MCP execution appears as mcp_call output; it does not create an application-side function handoff.
Reconnect
A new GET stream starts at the current cursor. It does not replay past events. After a disconnect, resubscribe and reconcile your display against the persisted Session, Items, and Turns using their IDs. Do not assume that reconnecting restores missing text deltas.
Stream disconnection leaves execution running. Use an explicit cancellation event to stop a Turn.