Skip to main content
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
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

​
Event stream

Events are normalized across agent runners, so UI and API clients do not need to understand each internal tool. 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.

Permissions and security

Learn how approvals work.

Agents API

Create sessions, submit turns, and stream events programmatically.