Sessions

The lifecycle of an agent run — how sessions are created, replayed, and audited.

Every conversation with a deployed agent — whether you started it from the dashboard, a Slack thread, a schedule, or an inbound webhook — runs inside a session. agntdata keeps a thin pointer row in 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.

Status is set by the API as turns flow through Anthropic’s runtime. The dashboard shows it in the session list and uses it to gate the input box.

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.

For chat-platform sessions (Slack, iMessage), the thread→session binding lives in chat_platform_conversation_state, which maps a conversation key ({channelId}:{threadTs} for Slack, the phone number for iMessage) to its agent_session_id so the router resolves the right session on subsequent messages — “one thread, one session”.

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.

The session detail view at /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.

These run inside the Builder context and never modify state — they’re the meta-agent’s lens onto deployed-agent behavior.

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 — every escalate_to_human call 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.

Combined, this is your full record of what the agent did, what it spent, and what it asked a human for.

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.