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.

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.

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 10-minute deadline for client results. Expired results are rejected; an abandoned wait fails with request_timeout. The interaction workflow uses a durable Temporal timer while waiting and ends when the Turn settles. Applications should still expose explicit cancellation and their own user-facing response deadline. See Functions.