Turns

A turn is a logical unit of agent work, initiated in response to user intent. It encompasses everything that happens in service of that intent: the user's input, the agent's response, any tool calls the agent makes, any intermediate messages required to resolve those tool calls (approvals, tool outputs), the agent's continued work after resolution, and the final completion. A turn involves one or more participants and one or more exchanges before it finishes.

Understand turn lifecycle

A turn has a unique identifier and is bracketed by lifecycle events on the channel. The client initiates a turn and passes the prompt for that turn to the server to query the AI model. The user's input messages are part of the turn. The turn is visible on the session from the moment the user expresses intent, not from the moment the agent begins processing. The agent publishes turn-end when the task completes, is cancelled, or fails. The turn ID correlates all activity that belongs to the same task.

A turn progresses through a defined set of states:

Multiple turns are active simultaneously on the same session. See concurrent turns for details.

Cancel a turn

The turn is the unit of cancellation. When a user stops a response, they are cancelling the turn: all work associated with the current task, across all execution attempts. There is no user-facing cancel operation below the turn.

Internal execution failures (a stream dying, a model call erroring, a serverless timeout) fail the execution attempt, not the turn. The turn remains active and is retried. See cancellation for details on cancel filters and authorization.

Trigger a turn

When the client sends a message, the client transport sends an HTTP POST to your server endpoint. This request carries the user's messages, the conversation history, the turn ID, the channel name, and branching context (parent and fork-of pointers). The server uses this to create a turn, publish the user's messages to the channel, invoke the AI model, and stream the response back through the channel.

The HTTP response returns immediately. The response stream is decoupled from the HTTP request: tokens flow through the Ably channel, not through the HTTP response. This is what allows the stream to survive independently of the client's connection.

The server receives the turn ID and channel name from the client. Any server process that can reach the channel handles the request. The agent does not need to maintain state between turns. It creates a server transport, processes the turn, and tears down.

A turn is initiated by calling send on a view:

const turn = await transport.view.send([
  {
    id: crypto.randomUUID(),
    role: 'user',
    parts: [{ type: 'text', text: 'What is in this contract?' }],
  },
]);

for await (const chunk of turn.stream) {
  // chunk is one decoded event from the agent for this turn
}

The returned ActiveTurn carries the decoded event stream, the turnId, and a cancel() method, so you observe streamed output or stop the turn without holding the underlying connection.

Read next

• Sessions: the persistent, shared conversation state that turns operate within.
• Transport: how clients and agents connect to sessions and publish turns.
• Cancellation: control who cancels turns and how cancel signals are routed.
• Concurrent turns: handle multiple active turns on the same session.
• Human-in-the-loop: use approval gates that suspend and resume turns.