Runtime Sessions

A Runtime Session represents one controlled clinical workflow — a long-lived container you poll and act on while an agent's output is being evaluated and (if needed) reviewed.

States

created → queued → running → (waiting_for_evidence | waiting_for_human_review | paused | blocked) → completed | cancelled | failed

resumed is a transient state a paused session passes through on its way back to running — you'll see it in the timeline, never as a resting state from a GET.

The retry model

A retry creates a new Agent Run, never mutating the previous one.

• For an internal-origin session, POST /runtime/sessions/{id}/retry immediately re-invokes the engine's reference adapter and creates Agent Run #2 (or #3, ...) in the same call.
• For an external-origin session, retry only reopens the session (back to running) — there's no internal adapter to re-invoke. Your integration must resubmit via POST /runtime/agent-runs with the same session_id to actually create the next Agent Run.

run_count on the session tells you how many Agent Runs it has owned so far.

Actions

Endpoint	Effect
POST /sessions/{id}/pause	Pauses a running session
POST /sessions/{id}/resume	Resumes a paused session
POST /sessions/{id}/cancel	Cancels the session (terminal)
POST /sessions/{id}/approve	Approves output awaiting review; finalizes the decision
POST /sessions/{id}/reject	Rejects output awaiting review; moves to blocked
POST /sessions/{id}/retry	Reopens for retry — see above

Each requires a reviewer_id where a human action is being recorded (approve/reject; retry accepts an optional one).

API

POST  /runtime/sessions
GET   /runtime/sessions
GET   /runtime/sessions/{id}
GET   /runtime/sessions/{id}/timeline
GET   /runtime/sessions/{id}/replay
POST  /runtime/sessions/{id}/pause
POST  /runtime/sessions/{id}/resume
POST  /runtime/sessions/{id}/cancel
POST  /runtime/sessions/{id}/approve
POST  /runtime/sessions/{id}/reject
POST  /runtime/sessions/{id}/retry

SDK usage

const session = await runtime.createSession({
  caseId: "case-0001",
  agentId: "discharge-summary-agent",
  taskType: "discharge_summary",
  userRole: "clinician",
});

if (session.current_state === "waiting_for_human_review") {
  await runtime.approveSession(session.session_id, { reviewerId: "dr.reviewer" });
}