agent_sessions; the canonical event history (every tool call, every model response) lives in Anthropic’s managed runtime, addressed by anthropic_session_id.
This gives you two views of the same conversation: the dashboard UI for humans, and the event stream for programmatic replay.
Lifecycle
| Status | Meaning |
|---|---|
idle | Created but no model turn in flight. New messages are accepted. |
running | A model turn is in flight. New messages queue behind the current one. |
archived | Read-only. Useful for closing out completed work without deleting the transcript. |
How sessions are created
Sessions can be created in four ways:Dashboard chat
Opening Agents → <your agent> → Chat and typing creates a fresh session bound to the current workspace member.
Slack thread
A Slack DM or
@mention that the router maps to a deployed agent creates one session per thread. The same agent_sessions row is reused for every reply in that thread.Schedule fire
Each scheduled fire creates a fresh session and sends the schedule’s
input_text as the first user message.Webhook delivery
An inbound delivery to an endpoint bound to an agent creates a session and sends the delivery JSON as the first user message.
slack_team_id, slack_channel_id, slack_thread_ts, slack_conversation_key) let the router resolve the right session on subsequent messages. A partial unique index on (deployed_agent_id, slack_conversation_key) enforces “one session per Slack thread”.
REST surface
Sessions are scoped to a single deployed agent. All routes live under/dashboard/agents/:id/sessions and require a Supabase session.
| Route | What it does |
|---|---|
POST /dashboard/agents/:id/sessions | Create a fresh session. |
GET /dashboard/agents/:id/sessions | List sessions for the agent. |
GET /dashboard/agents/:id/sessions/:sid | Read one session row. |
GET /dashboard/agents/:id/sessions/:sid/events | Paginated event history (tool calls, model outputs, escalations). |
GET /dashboard/agents/:id/sessions/:sid/stream | Server-sent events for live tail. |
POST /dashboard/agents/:id/sessions/:sid/messages | Send a new user message. |
POST /dashboard/agents/:id/sessions/:sid/interrupt | Cancel the in-flight turn. |
POST /dashboard/agents/:id/sessions/:sid/archive | Mark the session archived. |
/dashboard/sub-agents/:id/chat/:sid renders the same data with a transcript timeline, per-turn token cost (from agent_compute_usage), and inline approval cards for human-in-the-loop tool calls.
From the Builder
When you’re inspecting how a deployed agent has been running — debugging a flaky tool, validating a schedule, looking for stuck escalations — open the Build with AI chat for that agent and ask. The Builder has read-only tools that mirror this surface:list_live_agent_sessions— list the agent’s recent sessions.read_live_agent_session— read the full event history.search_live_agent_sessions— keyword search across recent turns.get_agent_session_usage— per-session token and runtime cost.list_agent_trigger_runs— pair sessions with the schedule or webhook that fired them.
Audit and billing
Each session links to the rest of the audit graph:agent_trigger_runs— if the session was created by a schedule or webhook, the trigger run row points back at this session id.agent_escalations— everyescalate_to_humancall writes a row referencing the session.agent_compute_usage— per-turn token, cache, and runtime cost, debited from the AI wallet.usage_logs— per-tool-call cost for data APIs and connections, debited from the data wallet.
Next steps
Triggers
How sessions get created without a human.
Permissions
Approval-mode tools and the escalation inbox.
Slack connector
Sessions backed by Slack threads.
Credits
How data and AI credits are debited per session.