Skip to content
AIPDocs
AIP 1.055 pagesConcept
Release status
DocumentationAIP 1.0ConceptCore Concepts

Actions and Sessions

An action is one requested unit of work. A session is an optional durable relationship that groups related work between two principals.

The distinction matters because clients disconnect, workers restart, and external providers may take longer than one request. AIP does not use the transport connection as the source of truth for work state.

Action Identity

Each action has a stable act_... id and names one capability. The action also contains structured input and may include:

  • mode: sync, async, or streaming;
  • an idempotency key and timeout;
  • conversation or memory context;
  • identity, compliance, and observability context;
  • a callback target;
  • a delegation chain;
  • an approval decision;
  • transaction context.

An action id identifies one operation. A retry with the same business intent should use the capability’s idempotency contract rather than reuse an unrelated action id.

Lifecycle

The durable action read model uses these states:

accepted -> queued -> running -> streaming -> completed
                      |           |
                      |           +---------> failed
                      +-----> pending_approval -> running
                      +-----> cancelling -> cancelled
                      +-----> dead_lettered

Not every action visits every state. completed, failed, cancelled, expired, and dead_lettered are terminal operational states.

The read model also has unknown for an action id that is not visible or not known to the current runtime. It is a query sentinel, not a persisted execution stage.

pending_approval is durable, not an error. The same action resumes after an authorized decision.

Results and Chunks

A final ActionResult reports completed, failed, cancelled, pending_approval, or requires_human. Failed results include a structured protocol error.

Streaming actions emit monotonically sequenced chunks. Chunk kinds distinguish data, progress, tool events, previews, pending approval, errors, and the terminal marker. Consumers should order by sequence, tolerate duplicate delivery after reconnect, and use the final action result as terminal authority.

Cancellation

Cancellation is a request, not proof that the external side effect stopped. A runtime transitions through cancellation state and asks the handler or provider to cancel. The final action status records whether cancellation was confirmed, the operation completed first, or the outcome needs reconciliation.

Do not retry a mutating action merely because cancellation timed out.

Operational Queries

Authorized clients can:

  • list actions using lifecycle, capability, session, principal, approval, transaction, and tenant filters;
  • read one status with optional result, chunks, and receipts;
  • read the terminal result with a bounded wait;
  • read or follow action-scoped events;
  • issue cancellation.

Query limits are bounded to 1-1000 records. Bounded waits cannot exceed 30 seconds in the native validation contract. Long-running clients should use events or repeat status reads with backoff.

Sessions

A session records an initiator, responder, creation time, and lifecycle state. It is useful for:

  • a durable agent conversation;
  • a sequence of related workflow actions;
  • reconnect and event replay;
  • a channel handoff that outlives one request.

Session states are new, active, queued, processing, streaming, waiting_for_human, completed, cancelled, failed, and settled. Transitions are validated; a terminal session cannot silently become active again.

Resume Tokens

A successful handshake may return a single-use opaque resume token. On resume, the runtime verifies the token, returns the current session view, replays events after the supplied cursor, and rotates the token. The previous token becomes invalid.

Treat resume tokens as credentials. Do not log them or place them in URLs.

Choosing Sync, Async, or Streaming

Mode Use when Caller behavior
sync Work is short and predictably bounded Wait for the final result
async Work may queue, wait for approval, or survive disconnects Store action_id and query or receive callbacks
streaming Incremental output is useful Consume chunks and still verify the final result

The capability contract is authoritative. A caller must not request a mode the capability does not advertise.