> ## Documentation Index
> Fetch the complete documentation index at: https://agnt.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```mermaid theme={null}
stateDiagram-v2
    [*] --> idle: create
    idle --> running: first message
    running --> idle: model returns final
    running --> archived: archive
    idle --> archived: archive
```

| 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:

<CardGroup cols={2}>
  <Card title="Dashboard chat">
    Opening **Agents → \<your agent> → Chat** and typing creates a fresh session bound to the current workspace member.
  </Card>

  <Card title="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.
  </Card>

  <Card title="Schedule fire">
    Each scheduled fire creates a fresh session and sends the schedule's `input_text` as the first user message.
  </Card>

  <Card title="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.
  </Card>
</CardGroup>

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

<CardGroup cols={2}>
  <Card title="Triggers" icon="bolt" href="/agents/triggers">
    How sessions get created without a human.
  </Card>

  <Card title="Permissions" icon="shield" href="/agents/permissions">
    Approval-mode tools and the escalation inbox.
  </Card>

  <Card title="Slack connector" icon="slack" href="/agents/slack">
    Sessions backed by Slack threads.
  </Card>

  <Card title="Credits" icon="coins" href="/billing/credits">
    How data and AI credits are debited per session.
  </Card>
</CardGroup>