Events and conversation history

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

Session and Turn lifecycle events include scenario_id: string | null on their embedded session or turn resources. The current SDK extension's rebyte.sessions.events.stream and streaming rebyte.sessions.create preserve these types. See Scenarios. These Scenario fields support Rebyte Loop (Preview).

An event submission body may include optional nullable scenario_id alongside events. This asserts the Session's immutable binding and must match it. Omit the assertion to inherit the existing binding; it cannot assign a new Scenario.

An assistant message Item's phase is final_answer or commentary (interim text written before tool calls). When the model names the phase as the message starts (OpenAI models), agent.session.turn.item.added already carries it, so a client can stream only the answer's output_text.delta events. With phase: null on the added Item, the phase is known only from agent.session.turn.item.done.

Reasoning summaries are saved as Items. When the selected model adapter emits incremental reasoning, Rebyte forwards agent.session.turn.reasoning_summary_text.delta and related part/done events. Function calls are emitted as complete items; incremental function-argument deltas are not forwarded.

Tool call titles

With the Agent option tool_calls: { title: 'auto' }, every call Item (function_call, mcp_call, command_execution and web_search_call) carries title: the model's own short description of the call for your users, or null. Show it in place of the tool name and arguments while the call runs and in the saved history.

When the title arrives:

• A function_call for your application is complete as soon as the model finishes writing it: its agent.session.turn.item.done event and the Session's required_actions entry both carry the title before your application runs the function.
• A server-executed call (command_execution, mcp_call, web_search_call) is added to the stream when the model starts it, before its arguments are known, and done when it finishes. In between, Rebyte publishes agent.session.turn.item.updated once, with the same output_index and the complete in-progress Item, including its arguments and title. This event is a Rebyte extension and is sent only when the option is on; treat it as a replacement of the Item with that id. Its added and done events are unchanged, so applications that ignore the event see exactly the previous stream.

Items saved before the option existed have no title field.

Retrieve Items

Rebyte stores conversation history on the server. Retrieve it through GET /v1/agents/sessions/{session_id}/items; this does not start another run. For complete client setup, a curl example, and restoring a page after reload, see Retrieve conversation history.

for await (const item of client.beta.agents.sessions.items.list(sessionId, {
  order: 'asc', limit: 100,
})) {
  console.log(item);
}

This loop automatically fetches every page. 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 end of the stream. Every event carries an SSE id. To resume after a disconnect, reconnect with that id in the Last-Event-ID header (rebyte.sessions.events.stream(sessionId, { lastEventId }) in the SDK extensions): Rebyte sends every later event, text deltas included, with no gap or duplicate.

Rebyte retains a Session's live events for about ten minutes after the last one. If the cursor is older than that, the stream sends an error event with code replay_unavailable and ends; reload the Session, Turns and Items, then subscribe again without a cursor. Saved Items always hold the complete content.

Stream disconnection leaves execution running. Use an explicit cancellation event to stop a Turn.

Stream one Turn

To show a Turn that is already running, for example after a page reload, stream that Turn instead of the Session. As with OpenAI's GET /v1/responses/{response_id}?stream=true, GET /v1/agents/sessions/{session_id}/turns/{turn_id}?stream=true replays the Turn's events from its start, text deltas included, then sends new ones live. The stream ends after the Turn's completed, failed or cancelled event.

const stream = await rebyte.sessions.turns.retrieve(turnId, { session_id: sessionId, stream: true });
let answer = '';
for await (const event of stream) {
  if (event.type === 'agent.session.turn.output_text.delta') answer += event.delta;
}

The stream carries only the Turn's events; Session status events are not included. Each event carries sequence_number: 0 for agent.session.turn.created, then one more for each later event of the Turn. To resume after a disconnect, pass the last number you received as starting_after. Turn events are retained like Session events, for about ten minutes after the last one. When the Turn's first event is no longer retained, the stream sends an error event with code replay_unavailable and ends; read the Turn and its Items instead.