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

# Sessions and turns

> How agent work is submitted, streamed, approved, cancelled, and retained

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/akua-1dce587a/KB6u5PJRNHAXrgro/images/heros/agents-sessions-and-turns-light.svg?fit=max&auto=format&n=KB6u5PJRNHAXrgro&q=85&s=cc1d82fc2ed96b17cdcee263da3a1c25" alt="A durable session timeline with turns along a rail, a rising event stream per turn, pinned diff and summary artifacts, and a streaming playhead on a turn waiting for permission" width="1536" height="864" data-path="images/heros/agents-sessions-and-turns-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/akua-1dce587a/KB6u5PJRNHAXrgro/images/heros/agents-sessions-and-turns-dark.svg?fit=max&auto=format&n=KB6u5PJRNHAXrgro&q=85&s=0c70d7ed9d2e6d44651c5880c7cebf14" alt="A durable session timeline with turns along a rail, a rising event stream per turn, pinned diff and summary artifacts, and a streaming playhead on a turn waiting for permission" width="1536" height="864" data-path="images/heros/agents-sessions-and-turns-dark.svg" />
</Frame>

A session is a durable thread for one agent. A turn is one piece of submitted work inside that session.

This model keeps long-running work understandable: users can reopen a session, inspect previous turns, stream current events, and see what the agent is waiting for.

## Lifecycle

<Steps>
  <Step title="Create or reuse a session">
    A dashboard chat, API client, or ambient trigger creates a session for an agent. Existing sessions can be reused when the work is a continuation.
  </Step>

  <Step title="Submit a turn">
    A user or system signal sends an instruction. The turn starts in a queued or running state.
  </Step>

  <Step title="Stream events">
    The agent emits messages, tool calls, interactive UI outputs, approval requests, artifacts, and status updates.
  </Step>

  <Step title="Resolve approvals">
    If the agent requests a gated action, a user approves or rejects the approval request.
  </Step>

  <Step title="Review the result">
    The turn completes, fails, or is cancelled. Results stay visible according to workspace retention policy.
  </Step>
</Steps>

## Session states

| State                    | Meaning                                                                   |
| ------------------------ | ------------------------------------------------------------------------- |
| `ACTIVE`                 | The session can accept turns.                                             |
| `WAITING_FOR_INPUT`      | The agent is done for now and waiting for the next instruction.           |
| `WAITING_FOR_PERMISSION` | The agent needs a human decision before continuing.                       |
| `COMPLETED`              | The session reached a terminal outcome.                                   |
| `FAILED`                 | The session failed and may need review.                                   |
| `CANCELLED`              | Work was cancelled.                                                       |
| `ARCHIVED`               | The session is hidden from active views but retained according to policy. |

## Event stream

Events are normalized across agent runners, so UI and API clients do not need to understand each internal tool.

| Event                                                                                              | What users see                                                                                            |
| -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `message.created`                                                                                  | A user, assistant, or system message.                                                                     |
| `widget.created`                                                                                   | A typed approval card, choice card, form, status card, documentation card, diagram, or navigation helper. |
| `progress.updated`                                                                                 | The agent reports progress for a task, investigation, or prepared action.                                 |
| `execution_environment.started` / `execution_environment.resumed`                                  | A retained runtime started or resumed.                                                                    |
| `execution_environment.stopped` / `execution_environment.deleted` / `execution_environment.failed` | A retained runtime stopped, was deleted, or failed.                                                       |
| `artifact.created`                                                                                 | A repository change request, diff, summary, log bundle, or file was produced.                             |
| `handoff_summary.created`                                                                          | The agent produced a compact summary for a continuation or handoff.                                       |
| `turn.cancelled`                                                                                   | The turn was cancelled.                                                                                   |

Widget events can include prepared actions and reactive bindings. That lets a dashboard approval card, repository change card, multi-option reply card, or status card update as the underlying resource changes, while API clients can still use the underlying approval request, repository change request, artifact, or turn state directly.

Ambient turns that appear in a user-visible session should also include a compact summary message or card before they wait or finish. The summary should make the run understandable later without replaying every event.

Turns may include a runtime hint, but Akua records the runtime decision and resolved execution mode separately. That lets a client ask for a retained runtime while policy still chooses Code Mode, denies the request, or asks for approval.

Before starting resource-scoped work, API clients can check for conflicting active sessions on the same repository, install, cluster, or repository change request. This helps avoid duplicate investigations and competing fixes.

## Retention

Session history, artifacts, and filesystems have different retention policies. Text summaries and repository change requests are cheap to keep. Retained filesystems cost more and should expire unless pinned.

Pinned sessions are useful for long investigations, customer escalations, or repository change work that should remain resumable.

## Related topics

<CardGroup cols={2}>
  <Card title="Permissions and security" icon="shield-check" href="/agents/permissions-and-security">
    Learn how approvals work.
  </Card>

  <Card title="Agents API" icon="code" href="/agents/api">
    Create sessions, submit turns, and stream events programmatically.
  </Card>
</CardGroup>