API reference
Reference for every public API in the @ably/ai-transport package. The SDK is organised into seven entry points so you only import what you need.
This reference covers every public API in the @ably/ai-transport package. The SDK is organised into seven entry points so you only import what you need.
Quick example
A minimal client session setup using the Vercel-pre-bound factory:
1
2
3
4
5
6
7
8
9
10
11
import * as Ably from 'ably';
import { createClientSession } from '@ably/ai-transport/vercel';
const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });
const session = createClientSession({
client: ably,
channelName: 'conversation-42',
});
await session.connect();Entry points
| Entry point | Import path | Contents |
|---|---|---|
| Core | @ably/ai-transport | createClientTransport, createAgentTransport, createClientSession, createAgentSession, defineCodec, Invocation, the WireCodec interface |
| React | @ably/ai-transport/react | ClientSessionProvider, useClientSession, useView, useTree, useCreateView, useMessagesWithSeed, useAblyMessages, createSessionHooks |
| Vercel | @ably/ai-transport/vercel | createUIMessageCodec, Vercel-bound createClientSession and createAgentSession, createChatTransport, vercelRunOutcome, createToolResultFork |
| Vercel React | @ably/ai-transport/vercel/react | ChatTransportProvider, useChatTransport, useMessageSync, useMessagesWithSeed, plus the Vercel pre-typed re-exports of ClientSessionProvider, useClientSession, useView, useCreateView, useTree, and useAblyMessages |
| OpenAI | @ably/ai-transport/openai | ResponsesCodec, toResponsesInput, and the loop-correlation helpers resolvedCallIds, unansweredCalls, and approvedUnexecutedCalls |
| Temporal | @ably/ai-transport/temporal | createAblyTransportPlugin and stepIdFor, both worker-side |
| Temporal workflow | @ably/ai-transport/temporal/workflow | withRun, openRun, and RunHandle, for code inside the workflow sandbox |
Peer dependencies
ably is required. The rest are optional, and you only need the ones matching the entry points you import:
| Package | Needed for |
|---|---|
ably | Every entry point. |
ai | The Vercel entry points. |
openai | The OpenAI entry point. |
react | The React entry points. |
@temporalio/activity | The Temporal worker entry point. |
@temporalio/worker | The Temporal worker entry point. |
@temporalio/workflow | The Temporal workflow entry point. |
JavaScript
Transport
You can publish and subscribe to codec events alongside run and step lifecycle events, and build your own application state from them. Your own code holds the conversation state, so you decide which events to keep and how to shape them for your UI.
ClientTransport
Publish client inputs, read classified events, cancel and steer runs, and page channel history.
AgentTransport
Open runs, locate the input that woke an invocation, and publish output through steps.
WireCodec
The encode and decode contract the transports require, and how defineCodec builds one.
Core
ClientSession
Subscribe to a session, build a conversation tree, send messages, and cancel runs from the client.
AgentSession
Manage run lifecycles, publish lifecycle events, and pipe streamed assistant output from the server.
Codec
Encode and decode any AI framework's events as Ably channel messages by implementing the codec contract.
Vercel
ChatTransport
The Vercel-bound session factories and the ChatTransport adapter for useChat.
createUIMessageCodec
The factory for the pre-built Vercel AI SDK codec, and its type parameters.
vercelRunOutcome
Map a Vercel streamText finishReason and pipe result to a VercelRunOutcome for run.suspend / run.end.
Temporal
Worker
Register the run and step lifecycle activities on a Temporal worker with createAblyTransportPlugin, and derive step ids with stepIdFor.
Workflow
Open a run from inside a workflow with openRun or withRun, then end it, suspend it, or clean it up.
React
Core
Providers
ClientSessionProvider and the createSessionHooks factory for baking codec types into the hooks.
useClientSession
Read a ClientSession from the nearest provider.
useView
Subscribe to the session's default view: visible messages, branch navigation, send and regenerate.
useCreateView
Create an independent view with its own branch selection and pagination state.
useMessagesWithSeed
Reconcile a persisted conversation seed with the live session and render the composed conversation.
useTree
Stable structural query callbacks for inspecting runs outside the visible branch.
useAblyMessages
Accumulate the raw Ably InboundMessages observed on the session's channel.
Vercel
useChatTransport
Read a ChatTransport and its underlying ClientSession from the nearest ChatTransportProvider.
useMessageSync
Sync view updates into useChat's setMessages so observer tabs see new messages live.