Run and continue sessions

A Session holds its Agent configuration, conversation history, Turns, and optional Environment. Keep the Session ID in your application to continue work later.

Rebyte supports retrieving saved conversation history through the Agents API. Use Retrieve conversation history below to restore messages after a page reload. You do not need the separate Conversations API.

Create a Session

const session = await client.beta.agents.sessions.create({
  agent: { model: 'gpt-5.6-luna', instructions: 'Answer concisely.' },
  environment: { type: 'none' },
  input: 'Explain what an agent session stores.',
});

A Session without an Environment requires initial input. A managed Session can be created before input is available. See the quickstart for client setup and a complete streaming example.

Submit input

await client.beta.agents.sessions.events.create(session.id, {
  'Idempotency-Key': 'followup-1',
  events: [{
    type: 'agent.session.input.message',
    input: [{ role: 'user', content: [
      { type: 'input_text', text: 'Give a concrete example.' },
    ] }],
  }],
});

Each input submission containing a message creates a new Turn. If another Turn is active or waiting for client functions, the new Turn queues behind it. Turns execute sequentially within the Session; a new message does not automatically resolve or steer the waiting Turn. Return its function results or cancel it to allow queued work to continue. This queuing policy differs from OpenAI's active-Turn steering behavior.

Follow progress

Subscribe to live events before submitting input. A subscription opened afterward starts at the current cursor and may miss earlier events. Retrieve Items and Turns to read persisted results.

A Session can be in_progress, requires_action, idle, or failed. requires_action means your application needs to return a function result. An idle Session may contain a completed, failed, or cancelled Turn; inspect that Turn to determine the outcome.

Retrieve conversation history

Use GET https://api.rebyte.ai/v1/agents/sessions/{session_id}/items to read saved messages and execution output. Your Rebyte organization key needs tasks:read and must belong to the Session's organization. Keep the key on your server.

Install the official client with pnpm add openai@7.15.0, then save this as history.mjs. Set REBYTE_API_KEY and REBYTE_SESSION_ID to your existing key and Session ID; this script only reads history and does not start another run.

import OpenAI from 'openai';

const sessionId = process.env.REBYTE_SESSION_ID;
if (!sessionId) throw new Error('Set REBYTE_SESSION_ID');

const client = new OpenAI({
  apiKey: process.env.REBYTE_API_KEY,
  baseURL: 'https://api.rebyte.ai/v1',
  maxRetries: 0,
});

// Automatically fetch every page, oldest first.
for await (const item of client.beta.agents.sessions.items.list(sessionId, {
  order: 'asc', limit: 100,
})) {
  console.log(JSON.stringify(item));
}

Run node history.mjs. To request one page directly over HTTP:

curl --fail-with-body \
  "https://api.rebyte.ai/v1/agents/sessions/${REBYTE_SESSION_ID}/items?order=asc&limit=100" \
  -H "Authorization: Bearer ${REBYTE_API_KEY}" \
  -H "OpenAI-Beta: agents=v1"

The HTTP response contains data, has_more, first_id, and last_id. When has_more is true, pass after=<last_id> with the same order to fetch the next page. limit accepts 1–100 and defaults to 20; order defaults to desc. The SDK loop above handles pagination for you; reading one page's data alone does not retrieve a longer history.

Items include user and assistant messages, tool calls, and saved tool results. Use each Item's type to render it, its id to avoid duplicates, and turn_id to associate it with an execution Turn. Retrieve Turns for completion, failure, or cancellation status. Files are retrieved separately through Artifacts.

Restore a conversation after a reload

1. Save the Session ID with your application's user/conversation record.
2. Authorize that user's access to the Session on your server.
3. Retrieve its Items and Turns, and render the saved history.
4. Send follow-up input to the same Session ID to continue with its context.

If execution is still active, subscribe to live events and reconcile the saved Items and Turns by ID. A new stream does not replay missed text deltas; use the reconnection flow. Saved Items restore conversation content, not the original timing of every streamed token.

Rebyte Agent SDK already loads this history when you initialize it with an existing Session ID. Deleting a Session makes its history unavailable through the API, so retain the Session while your application needs to display or continue it.

Cancel a Turn

await client.beta.agents.sessions.events.create(session.id, {
  'Idempotency-Key': 'cancel-1',
  events: [{ type: 'agent.session.input.cancel' }],
});

Cancellation stops the active work and retains the Session for later input. Closing a stream does not cancel execution. Cancellation cannot undo side effects that a tool has already performed.

Client function deadline

A waiting round has a 24-hour deadline for client results. Expired results are rejected; an abandoned direct function wait fails the Turn with request_timeout. Waiting survives service restarts. A nested function inside Dynamic Workflow instead fails its program on expiry and returns that error to the Agent. The Agent can then continue its Turn. Ordinary Turns have no fixed overall deadline; a Schedule also imposes its own total timeout. Applications should still expose explicit cancellation and their own user-facing response deadline. See Functions.

Compact conversation context

Rebyte keeps the original Session Items when compacting. Compaction changes the history supplied to subsequent model calls; it does not delete your conversation or create a new Session or environment.

Before the first model call of a new Turn, Rebyte automatically summarizes older history when estimated input reaches 80% of the model's usable input budget: floor((context_size - reserved_output_tokens - 1024) * 0.8). The current Turn's new input is excluded from the summary. The pending request then continues using the summary and newer messages. UI Agents and API Agents share the tokenizer, threshold policy and summary generator.

Automatic compaction runs at most once per Turn, before generation. It does not interrupt a running tool-call sequence. Input that still exceeds the budget fails with context_length_exceeded; shorten the new input or compact between Turns.

Compact from a client

Send /compact as a standalone message while the Session is idle. Rebyte recognizes it as a control command and runs the shared summarizer; it is not sent to the Agent as an ordinary prompt. This also works in the SDK's React chat composer. Quoted mentions, mixed message batches and messages containing attachments are ordinary input, not commands.

await client.beta.agents.sessions.events.create(session.id, {
  events: [{
    type: 'agent.session.input.message',
    input: [{ role: 'user', content: [{ type: 'input_text', text: '/compact' }] }],
  }],
}, { headers: { 'Idempotency-Key': crypto.randomUUID() } });

For an explicit HTTP operation, Rebyte also provides an extension endpoint:

curl -X POST "https://api.rebyte.ai/v1/agents/sessions/$SESSION_ID/compact" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $REBYTE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $REQUEST_ID" \
  -d '{}'

This returns 202 and a Session snapshot after command admission. It requires tasks:write. The endpoint is a Rebyte extension, not an extra method added to the official OpenAI client. Both entry points use the same durable Turn and idempotency path. Reuse a request key only when retrying the same command.

Subscribe to Session events before submission. The summary appears as an assistant commentary Item prefixed Context compacted.; manual compaction finishes with the normal Turn completion event. Automatic compaction publishes the summary before the answer to the current request. Rebyte also emits agent.session.compaction.started with the Turn, trigger and model-attempt identity; clients can ignore this extension event. Original messages, tool output and completed summaries remain available through Items after reload. Summary usage is included in Session and Turn usage and billed using the actual summary model.

Manual compaction returns 409 if a Turn or client function is still active, or there is no new history since the previous summary. Finish or cancel active work first. Failed or cancelled summary attempts preserve the previously effective history. Cancelling after a summary has committed preserves that successful summary.