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 | createClientSession, createAgentSession, Invocation, Codec interface, defineCodec |
| 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-baked 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 worker | @ably/ai-transport/temporal | createAblyTransportPlugin, stepIdFor |
| Temporal workflow | @ably/ai-transport/temporal/workflow | openRun, withRun, RunHandle |
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
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
Bridge any AI framework to 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 framing 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.