Skip to content
Core concepts

Sessions

A session is one conversation with the agent, recorded on one ordered event log.

A session keeps one numbered event log. Everything you send and everything the agent does is an event on it, in order, starting at seq 1. You write to the log through one route. You read it live on the stream, page through it afterwards, or receive it on a webhook, and all three carry the same events with the same ids.

When you send a message, the agent works on it in a turn. If it starts generations, the session stays busy after its text ends, and picks up again on its own when they finish. The Quickstart shows every event of a real turn; this is the busy, resume and idle cycle within it.

  1. 1Busysession.status_runningcontinuation: false. The agent starts on your message
  2. 2Generatingjob.startedOne per image or video. The agent can keep talking while they run
  3. 3Resumessession.status_runningcontinuation: true, once the generations finish
  4. 4Resultsjob.completedEach carries its outputs
  5. 5Idlesession.status_idlestop_reason says what to do next
The continuation's session.status_running arrives just before the job.completed events that woke it (seq 13 and 14 in the Quickstart run).

session.status_idle is the event that means the agent has stopped. Its stop_reason.type tells you what to do next:

stop_reason.typeMeans
end_turnThe turn finished. Send the next message when you have one.
requires_actionThe session is waiting on you, for example a client tool or an app’s review step. stop_reason.pending lists each item. See Approvals and review.
budget_reachedA spending cap stopped the turn. See Budgets and usage.
interruptedA user.interrupt or a cancel stopped the turn.
errorThe turn failed. The session.error before it says how.

A session pauses for a person only when you set it up to: a client tool your UI answers, or a workflow app with a review step. While it waits, the turn is suspended, not finished, and it continues when you answer. Approvals and review shows how to answer.

GET /v1/sessions/$SESSION_ID returns the same state as a snapshot: status (running, idle or terminated) and what the session is waiting on in pending. A client that has just connected reads where things stand from there.

To read the log live or page through it, see Streaming. The rules for everything you send are in the Reference. Every event type is listed in the Reference.

Send user.interrupt to stop the current turn. The session stays open for the next message.

Terminal window
curl -s -X POST https://agents.lumalabs.ai/v1/sessions/$SESSION_ID/events \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "events": [ { "type": "user.interrupt", "idempotency_key": "stop-42-1" } ] }'

The acknowledgement lists cancelled_run_ids. Add target_run_id to stop one run instead of the whole turn. If it is refused with SESSION.ORCHESTRATION_UNAVAILABLE, retry with the same key.

DELETE /v1/sessions/$SESSION_ID closes a session. It refuses new work and ends with session.status_terminated and reason: "closed".

A session lives for expires_in_seconds, 24 hours by default and up to 7 days. At expiry it emits session.status_terminated with reason: "expired", and later calls answer 410 SESSION.EXPIRED.