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 callloadUntil
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 s 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
– learn more about database hydration and the rest of the AI Transport SDK.Read the docs– the product overview and the problems it solves.** See what AI Transport is**– including the demos showing the AI Transport SDK in action.** Read the source**– you need an Ably account and an** Sign up free**API keyto run a session, and the free tier covers everything you need to start.