Introducing AI Transport v0.4.0

AI Transport v0.4.0 includes changes to optionally support database hydration.

Some applications may wish to store AI conversation history in an external store, such as a database. AI Transport's support for database hydration allows applications to reconcile that stored history with the live activity in the AI session.

When using database hydration, your application persists messages for completed runs to the database. This allows developers to build additional functionality, such as search or analytics, on top of the persisted state.

The AI Transport session provides realtime visibility over live activity, including support for multi-device continuity, resumable streaming and bidirectional control between clients and agents.

How database hydration works

Hydration is symmetric: the agent rebuilds the model context and the client rebuilds the UI, both from the same two sources. The flow has two parts:

• Persist completed runs. As each run completes, your agent writes its messages to your database. Once a run completes, its messages are immutable, so it is the natural atomic unit to store.
• Hydrate the conversation state. On load, both agents and client reads the conversation history from your database, then call loadUntil to fetch only the messages newer than the latest one that was stored.

Persist the completed run

Persist a run once it completes, because a completed run is immutable: while it is in flight messages can be mutated as tokens are appended and tool calls are resolved. run.messages returns the run's whole contribution, its triggering input plus all of its streamed output across any suspend and resume, so a turn that pauses for a client-side tool result and resumes under the same run still persists as one unit.

const runMessages = run.messages;
await run.end(outcome);
if (outcome.reason === 'complete') await appendMessagesInDB(invocation.sessionName, runMessages);

Hydrate the agent

The agent seeds the prior conversation from your store, takes the newest stored id as the seam, and lets run.view.loadUntil page back to it and return the not-yet-stored tail:

const session = createAgentSession({ client: ably, channelName: invocation.sessionName });
await session.connect();
const run = session.createRun(invocation, { signal: req.signal });

const seed = loadMessages(invocation.sessionName);
const seamId = seed.at(-1)?.id;

// loadUntil pages run.view back to the seam and returns only the messages newer than it.
const tail = await run.view.loadUntil((m) => m.message.id === seamId);
await run.start();

const conversation = [...seed, ...tail.map((m) => m.message)];
// ...stream the model response with `conversation` as the message history...

Hydrate the client

The client reconciles the same way, over its own session view.

const seed = loadStoredMessages(conversationId);
const seamId = seed.at(-1)?.id;

const tail = await session.view.loadUntil((m) => m.message.id === seamId);
const conversation = [...seed, ...tail.map((m) => m.message)];

In React, useMessagesWithSeed wraps that walk. Give it your session view and the stored seed, and it returns the composed conversation, kept current as new messages stream in.

const messages = useMessagesWithSeed({ view: session.view, seed, getMessageId: (m) => m.id });

If you use the Vercel AI SDK's useChat, useMessageSync runs the same reconciliation from a messages seed, so you keep hydration without leaving useChat. The use-chat-db demo in the repository is the reference implementation of the pattern.

Get started

@ably/ai-transport v0.4.0 is available now:

npm install @ably/ai-transport

• Read the docs – learn more about database hydration and the rest of the AI Transport SDK.
• See what AI Transport is – the product overview and the problems it solves.
• Read the source – including the demos showing the AI Transport SDK in action.
• Sign up free – you need an Ably account and an API key to run a session, and the free tier covers everything you need to start.