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.
How a turn looks on the log
Section titled “How a turn looks on the log”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.
- 1Busy
session.status_runningcontinuation: false. The agent starts on your message - 2Generating
job.startedOne per image or video. The agent can keep talking while they run - 3Resumes
session.status_runningcontinuation: true, once the generations finish - 4Results
job.completedEach carries its outputs - 5Idle
session.status_idlestop_reason says what to do next
session.status_idle is the event that means the agent has stopped. Its stop_reason.type tells you what to do next:
stop_reason.type | Means |
|---|---|
end_turn | The turn finished. Send the next message when you have one. |
requires_action | The 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_reached | A spending cap stopped the turn. See Budgets and usage. |
interrupted | A user.interrupt or a cancel stopped the turn. |
error | The 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.
Interrupt a turn
Section titled “Interrupt a turn”Send user.interrupt to stop the current turn. The session stays open for the next message.
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" } ] }'import jsonimport urllib.request
request = urllib.request.Request( f"https://agents.lumalabs.ai/v1/sessions/{session_id}/events", method="POST", data=json.dumps({"events": [{"type": "user.interrupt", "idempotency_key": "stop-42-1"}]}).encode(), headers={"Authorization": f"Bearer {session_token}", "Content-Type": "application/json"},)with urllib.request.urlopen(request) as response: print(json.load(response)["data"][0])const response = await fetch( `https://agents.lumalabs.ai/v1/sessions/${sessionId}/events`, { method: "POST", headers: { Authorization: `Bearer ${sessionToken}`, "Content-Type": "application/json", }, body: JSON.stringify({ events: [{ type: "user.interrupt", idempotency_key: "stop-42-1" }], }), },);console.log((await response.json()).data[0]);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.
Closing and expiry
Section titled “Closing and expiry”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.
- Streaming: follow the log live.
- Approvals and review: answer a session that is waiting on your user.
- Budgets and usage: cap what a session can spend.