Skip to content

Add docs for AIT presence #3401

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
owenpearson wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add docs for AIT presence #3401

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions src/pages/docs/ai-transport/api/javascript/core/agent-session.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,16 @@ await run.start();
```
</Code>

## Properties <a id="properties"/>

<Table id='AgentSessionProperties'>

| Property | Description | Type |
| --- | --- | --- |
| presence | The Ably presence object for the session's channel. Use it to see which clients are connected — for example, to detect whether the requesting user is still online (`enter`, `leave`, `get`, `subscribe`). The session adds no semantics — it is the same instance the channel exposes — and presence operations implicitly attach, so they work without first awaiting [`connect()`](#connect). | `Ably.RealtimePresence` |

</Table>

## Create an agent session <a id="constructor"/>

<MethodSignature>{`function createAgentSession<TInput, TOutput, TProjection, TMessage>(options: AgentSessionOptions<TInput, TOutput, TProjection, TMessage>): AgentSession<TOutput, TProjection, TMessage>`}</MethodSignature>
Expand Down
6 changes: 2 additions & 4 deletions src/pages/docs/ai-transport/api/javascript/core/client-session.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ await session.connect();
| --- | --- | --- |
| tree | The complete conversation tree. Holds every known Run node and emits events on any change. Use `view` in most cases; reach for `tree` for low-level inspection. | <Table id='Tree'/> |
| view | The default paginated, branch-aware view for rendering. Events scope to the visible messages. | <Table id='View'/> |
| presence | The Ably presence object for the session's channel. Use it to see which clients are connected (`enter`, `leave`, `get`, `subscribe`). The session adds no semantics — it is the same instance the channel exposes — and presence operations implicitly attach, so they work without first awaiting [`connect()`](#connect). | `Ably.RealtimePresence` |

</Table>

Expand Down Expand Up @@ -89,7 +90,6 @@ const session = createClientSession({
client: ably,
channelName: 'conversation-42',
codec: UIMessageCodec,
clientId: 'user-abc',
});
```
</Code>
Expand All @@ -100,10 +100,9 @@ const session = createClientSession({

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| client | required | The Ably Realtime client. The caller owns its lifecycle; `session.close()` does not close the client. | `Ably.Realtime` |
| client | required | The Ably Realtime client. The caller owns its lifecycle; `session.close()` does not close the client. The session's identity is read from this client's `auth.clientId` at publish time, stamped on the wire as the run-owner / input-owner id so other clients can attribute messages. A connection with no concrete clientId (anonymous, or a wildcard `*` token) publishes without one. | `Ably.Realtime` |
| channelName | required | The channel to subscribe to and publish cancel signals on. The session owns this channel; do not also resolve it elsewhere with conflicting options. | String |
| codec | required | The codec used to encode and decode events and messages. | `Codec<TInput, TOutput, TProjection, TMessage>` |
| clientId | optional | The client's identity, used as the Ably publisher `clientId` on everything this session publishes. Surfaces on the wire as the run-owner / input-owner id so other clients can attribute messages. | String |
| messages | optional | Initial messages to seed the conversation tree with. Forms a linear chain. | `TMessage[]` |
| logger | optional | Logger instance for diagnostic output. | `Logger` |

Expand Down Expand Up @@ -266,7 +265,6 @@ const session = createClientSession({
client: ably,
channelName: 'conversation-42',
codec: UIMessageCodec,
clientId: 'user-abc',
});

await session.connect();
Expand Down
6 changes: 2 additions & 4 deletions src/pages/docs/ai-transport/api/javascript/core/codec.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,15 +92,14 @@ Build a stateful encoder bound to a channel. The encoder owns the message-append
| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| channel | required | The channel writer to publish through. An `Ably.RealtimeChannel` satisfies this directly. | `ChannelWriter` |
| options | optional | Per-encoder defaults (clientId, extras, messageId, onMessage hook). | <Table id='EncoderOptions'/> |
| options | optional | Per-encoder defaults (extras, messageId, onMessage hook). | <Table id='EncoderOptions'/> |

</Table>

<Table id='EncoderOptions' hidden>

| Property | Description | Type |
| --- | --- | --- |
| clientId | Default clientId for all writes. | String |
| extras | Default extras merged into every Ably message. | <Table id='Extras'/> |
| onMessage | Hook called before each Ably message is published. Mutate the message in place to add transport-level headers under `extras.ai`. | `(message: Ably.Message) => void` |
| messageId | Default `codec-message-id` for messages where the event payload doesn't supply one. | String |
Expand Down Expand Up @@ -150,7 +149,6 @@ A stateful encoder for a single channel. Two publish methods enforce direction a

| Property | Description | Type |
| --- | --- | --- |
| clientId | Override the default clientId for this write. | String |
| extras | Override the default extras for this write. | <Table id='Extras'/> |
| messageId | Message identity for projection routing. Stamped as `codec-message-id`. | String |

Expand All @@ -169,7 +167,7 @@ Encode and publish a single client input on the `ai-input` wire. Per-write overr
| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| input | required | The input event to encode and publish. | `TInput` |
| options | optional | Per-write overrides (clientId, extras, messageId). | <Table id='WriteOptions'/> |
| options | optional | Per-write overrides (extras, messageId). | <Table id='WriteOptions'/> |

</Table>

Expand Down
4 changes: 1 addition & 3 deletions src/pages/docs/ai-transport/api/javascript/vercel/chat-transport.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,6 @@ const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });
const session = createClientSession({
client: ably,
channelName: 'conversation-42',
clientId: 'user-abc',
});
```
</Code>
Expand All @@ -56,9 +55,8 @@ const session = createClientSession({

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| client | required | The Ably Realtime client. The caller owns its lifecycle. | `Ably.Realtime` |
| client | required | The Ably Realtime client. The caller owns its lifecycle. The session's identity is read from this client's `auth.clientId` at publish time and stamped on everything it publishes. | `Ably.Realtime` |
| channelName | required | The channel to subscribe to and publish cancel signals on. | String |
| clientId | optional | The client's identity, used as the Ably publisher `clientId` on everything this session publishes. | String |
| messages | optional | Initial messages to seed the conversation tree with. | `UIMessage[]` |
| logger | optional | Logger instance for diagnostic output. | `Logger` |

Expand Down
5 changes: 3 additions & 2 deletions src/pages/docs/ai-transport/api/react/core/providers.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,17 +38,18 @@ The provider reads the Ably Realtime client from the surrounding `<AblyProvider>

If `createClientSession` throws, the error is stored on the slot alongside an undefined session. `useClientSession` surfaces it as [`sessionError`](/docs/ai-transport/api/react/core/use-client-session#returns) so the component tree does not crash.

The provider also renders an ably-js `<ChannelProvider>` for the session's channel, so ably-js's channel hooks — `usePresence`, `usePresenceListener`, `useChannel` — work for any descendant without wrapping the subtree in your own `<ChannelProvider>`. Pass the same `channelName` you gave the provider. See [Agent presence](/docs/ai-transport/features/agent-presence#react).

### Props <a id="client-session-provider-props"/>

`ClientSessionProviderProps` extends all [`ClientSessionOptions`](/docs/ai-transport/api/javascript/core/client-session#constructor-params) except `client` (which is read from `<AblyProvider>`).
`ClientSessionProviderProps` extends all [`ClientSessionOptions`](/docs/ai-transport/api/javascript/core/client-session#constructor-params) except `client` (which is read from `<AblyProvider>`). The session's identity is taken from that client's `auth.clientId` (set via the Ably token or `ClientOptions.clientId`) and stamped on everything it publishes.

<Table id='ClientSessionProviderProps'>

| Property | Description | Type |
| --- | --- | --- |
| channelName | The channel the session subscribes to. Used as the registry key for nested providers. | String |
| codec | The codec used to encode and decode events and messages. | `Codec<TInput, TOutput, TProjection, TMessage>` |
| clientId | The client's identity, used as the Ably publisher `clientId` for everything the session publishes. | String |
| messages | Initial messages to seed the conversation tree with. | `TMessage[]` |
| logger | Logger instance for diagnostic output. | `Logger` |
| children | Descendant components that consume the session via hooks. | `ReactNode` |
Expand Down
5 changes: 3 additions & 2 deletions src/pages/docs/ai-transport/api/react/vercel/chat-transport-provider.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ function App() {

## Props <a id="props"/>

`ChatTransportProviderProps` extends [`ClientSessionProviderProps`](/docs/ai-transport/api/react/core/providers#client-session-provider-props) with the `codec` field omitted (always `UIMessageCodec`) and adds four transport-owned options for the agent-invocation POST.
`ChatTransportProviderProps` extends [`ClientSessionProviderProps`](/docs/ai-transport/api/react/core/providers#client-session-provider-props) with the `codec` field omitted (always `UIMessageCodec`) and adds four transport-owned options for the agent-invocation POST. As with `ClientSessionProvider`, the session's identity is taken from the `<AblyProvider>` client's `auth.clientId` (set via the Ably token or `ClientOptions.clientId`).

<Table id='ChatTransportProviderProps'>

Expand All @@ -46,7 +46,6 @@ function App() {
| credentials | Fetch credentials mode for the invocation POST. Set to `'include'` for cookie-based cross-origin auth. | `RequestCredentials` |
| fetch | Custom fetch implementation for the invocation POST. Defaults to `globalThis.fetch`. | `typeof globalThis.fetch` |
| chatOptions | Hooks for customising chat request construction (for example `prepareSendMessagesRequest`). Must be stable across renders; wrap in `useMemo` or define outside the component. A new object reference recreates the `ChatTransport`. | <Table id='ChatTransportOptions'/> |
| clientId | The client's identity, used as the Ably publisher `clientId` on everything the session publishes. | String |
| messages | Initial messages to seed the conversation tree with. | `UIMessage[]` |
| logger | Logger instance for diagnostic output. | `Logger` |
| children | Descendant components that consume the chat transport via [`useChatTransport`](/docs/ai-transport/api/react/vercel/use-chat-transport). | `ReactNode` |
Expand All @@ -67,6 +66,8 @@ function App() {

The underlying `ClientSession` is created once on first render via `useRef`, and `connect()` runs from a `useEffect`. The session is closed when the provider truly unmounts.

Because it wraps [`ClientSessionProvider`](/docs/ai-transport/api/react/core/providers#client-session-provider), it also renders an ably-js `<ChannelProvider>` for the channel, so ably-js's `usePresence`, `usePresenceListener`, and `useChannel` hooks work in the subtree. See [Agent presence](/docs/ai-transport/features/agent-presence#react).

The `ChatTransport` itself is not closed on unmount: its `close()` delegates to `ClientSession.close()`, which the inner `ClientSessionProvider` already calls. Auto-closing here would double-close in React Strict Mode.

If `createClientSession` throws, the error surfaces via [`useClientSession.sessionError`](/docs/ai-transport/api/react/core/use-client-session#returns) and [`useChatTransport.chatTransportError`](/docs/ai-transport/api/react/vercel/use-chat-transport). The component tree does not crash.
Expand Down
2 changes: 2 additions & 0 deletions src/pages/docs/ai-transport/concepts/sessions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,8 @@ Clients are resilient to disconnection. A client that drops its connection loses

New participants join at any time. A second client attaching to the channel hydrates the full session from history and receives live updates going forward. No handshake or coordination is required between participants.

To see which participants are currently connected, use presence: the session channel carries Ably Presence, exposed directly as `session.presence`. See [Agent presence](/docs/ai-transport/features/agent-presence).

## Support persistence models <a id="persistence"/>

The channel serves two distinct roles: live delivery and historical persistence. It always serves as the live delivery layer. Whether it also serves as the historical persistence layer depends on the configuration.
Expand Down
Loading