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: 'glm-5.3', 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.' },
    ] }],
  }],
});

When the previous Turn has ended, new input starts another Turn. Input received during an active or waiting Turn steers that same Turn. It does not create a separate parallel task.

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.