# Sessions

A session is the durable, shared state of a conversation. It outlives any single connection so a user can close their laptop, switch to a phone, or refresh the page without losing the stream.

A session is the complete, persistent state of a conversation, and it exists independently of anything that connects to it. A client closes its tab, an agent process terminates, and the session is unchanged. Your application addresses it by name.

The session holds the branching tree of messages, the state of any agent work in progress, and any partially streamed output. Two clients that build the same session from the same data arrive at the same state.

![Diagram showing the channel as an append-only log and the session as the materialised state above it](https://raw.githubusercontent.com/ably/docs/main/src/images/content/diagrams/ait-concepts-sessions.png)

## Materialise a session 

Underneath the session is an Ably channel, which carries the ordered, durable log of everything published to the conversation. [Streaming](https://ably.com/docs/ai-transport/streaming.md) covers what the channel supplies on its own. The session is the structured conversation that log produces once it has been materialised into the [conversation tree](https://ably.com/docs/ai-transport/durable-sessions/conversation-tree.md).

A session materialises from one of two sources.

By default it materialises from the channel, which serves as both the live delivery layer and the stored history of the conversation. When your channel's history retention window covers the session's lifetime, the channel alone holds the whole conversation, so it is your only storage.

Alternatively you supply historical messages from your own database, and the channel provides only live and in-progress activity. Use this when your channel's retention window is shorter than the conversation, or when you need to index conversation data in your own systems. Your code joins the two into one list of messages, and [database hydration](https://ably.com/docs/ai-transport/durable-sessions/database-hydration.md) covers how to wire it up.

Materialisation is more than a replay of the log. Some events change how earlier events are interpreted. A cancel signal changes how a run is represented, and an edit forks a sibling prompt that the view selects in place of the original, even though the original messages are still on the channel. The channel keeps the full unedited log, and materialisation applies these events as instructions that reshape what the session contains.

## Connect to a session 

Your code reaches a session through a session object, either `ClientSession` or `AgentSession`.

- `ClientSession` runs in the browser for as long as the user's tab is open. It subscribes to the conversation and publishes user input and cancel signals.
- `AgentSession` usually runs for one HTTP handler invocation, and it publishes the run lifecycle events and the streamed response.

Neither object owns the conversation. Each one is a connection to a session that lives on the channel, so several agents or clients can attach to and detach from the same session at once and independently.

Both are constructed and then connected, as this client-side example shows:

<Code>

### Javascript

```
// Client-side. The browser fetches a token; never put an API key here.
import * as Ably from 'ably';
import { createClientSession } from '@ably/ai-transport';
import { createUIMessageSessionCodec } from '@ably/ai-transport/vercel';

const ably = new Ably.Realtime({ authUrl: '/auth' });

const session = createClientSession({
  client: ably,
  channelName: 'conversation-42',
  codec: createUIMessageSessionCodec(),
});

await session.connect();
// session.view, session.tree, and session.cancel(...) are now safe to use.
```
</Code>

Every operation that touches the conversation waits for the connect promise, and throws `InvalidArgument` when `connect()` has never been called, which stops a `view.send` publishing before the subscription is in place. `connect()` is idempotent, so a component that mounts twice gets the same promise back. Tear a client down with `close()` and an agent with `end()`. An agent that passes an in-flight run to another process uses `detach()` instead, which [durable execution](https://ably.com/docs/ai-transport/durable-execution.md#close-once) covers.

The `codec` argument is the translation layer between your framework's events and Ably messages. The Vercel codec is bundled, and `createClientSession` imported from `@ably/ai-transport/vercel` comes pre-bound with it, so you can leave the argument out. Writing your own is covered in [codec architecture](https://ably.com/docs/ai-transport/internals/codec-architecture.md).

## Share a session across participants 

The session is the unit of sharing. A second client joins the session, an agent hydrates the session to build context for a model call, and every published message goes to the session. Every client works whether or not the others are connected, and the state survives each arrival and departure.

Agent lifecycle does not affect the session. An agent hydrates the session, works through a [run](https://ably.com/docs/ai-transport/streaming/runs-and-steps.md), and terminates. The session survives because it lives on the channel rather than in the agent's memory, so a different agent instance handles the next run with the same state.

A new client can join at any time. A second client attaching to the conversation hydrates the full session from history and receives live updates from then on.

The session carries two Ably channel features directly. [Presence](https://ably.com/docs/ai-transport/channel/agent-presence.md) is exposed as `session.presence` and tells you which participants are currently connected. [LiveObjects](https://ably.com/docs/ai-transport/channel/liveobjects.md) is exposed as `session.object` and holds shared mutable state that the user and the agent both read and write, such as the record the user has selected. Your agent can react to each change as it is published, and the user sees the agent's changes in realtime.

## Read next 

- [Conversation tree](https://ably.com/docs/ai-transport/durable-sessions/conversation-tree.md): how the session's messages form a branching history.
- [Runs and steps](https://ably.com/docs/ai-transport/streaming/runs-and-steps.md): the unit of agent work inside a session.
- [Multi-device and fan-out](https://ably.com/docs/ai-transport/streaming/multi-device.md): one conversation across a laptop, a phone, and a second tab.
- [ClientSession reference](https://ably.com/docs/ai-transport/api/javascript/core/client-session.md): every client-side method and property.
- [AgentSession reference](https://ably.com/docs/ai-transport/api/javascript/core/agent-session.md): every agent-side method and property.

## Related Topics

- [Overview](https://ably.com/docs/ai-transport/durable-sessions.md): A drop-in durable session layer for AI applications. AI Transport holds the conversation and the message state your UI renders, including branching, and you render from its React hooks.
- [Conversation tree](https://ably.com/docs/ai-transport/durable-sessions/conversation-tree.md): Understand how AI Transport organises messages into a branching conversation tree, and how views give each client its own linear path through it.
- [Optimistic updates](https://ably.com/docs/ai-transport/durable-sessions/optimistic-updates.md): User messages appear instantly in Ably AI Transport. Optimistic insertion with automatic reconciliation when the server confirms.
- [Branching, edit, and regenerate](https://ably.com/docs/ai-transport/durable-sessions/branching.md): Edit user messages, regenerate AI responses, and navigate branches with Ably AI Transport. The full history is preserved in the conversation tree.
- [Tool calling](https://ably.com/docs/ai-transport/durable-sessions/tool-calling.md): Stream tool invocations and results through Ably AI Transport. Server-executed and client-executed tools with persistent state.
- [Human-in-the-loop](https://ably.com/docs/ai-transport/durable-sessions/human-in-the-loop.md): Add human approval gates to AI agent workflows with Ably AI Transport. Approve tool executions and provide input across devices.
- [Database hydration](https://ably.com/docs/ai-transport/durable-sessions/database-hydration.md): Hydrate an AI conversation from your own database with AI Transport and reconcile it with the live Ably channel, with no gaps and no duplicate messages.
- [Migrate from Streaming](https://ably.com/docs/ai-transport/durable-sessions/move-up-from-streaming.md): What changes in an application already streaming with Ably AI Transport when it moves the conversation into a durable session, and what stays exactly as it is.

## Documentation Index

To discover additional Ably documentation:

1. Fetch [llms.txt](https://ably.com/llms.txt) for the canonical list of available pages.
2. Identify relevant URLs from that index.
3. Fetch target pages as needed.

Avoid using assumed or outdated documentation paths.