Sessions and turns

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

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

1. 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.

2. Submit a turn

   A user or system signal sends an instruction. The turn starts in a queued or running state.

3. Stream events

   The agent emits messages, tool calls, interactive UI outputs, approval requests, artifacts, and status updates.

4. Resolve approvals

   If the agent requests a gated action, a user approves or rejects the approval request.

5. Review the result

   The turn completes, fails, or is cancelled. Results stay visible according to workspace retention policy.

Session states

State	Meaning
CREATED	The session exists but has not started work.
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.
tool_call.started / tool_call.completed	A platform, git, shell, browser, or repository action.
widget.created	A typed approval card, choice card, form, status card, documentation card, diagram, or navigation helper.
approval_request.created	The agent needs approval.
execution_environment.started	A retained runtime started or resumed.
artifact.created	A repository change request, diff, summary, log bundle, or file was produced.
turn.completed	The turn finished successfully.

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.

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

Permissions and security

Learn how approvals work.

Agents API

Create sessions, submit turns, and stream events programmatically.