docs(ai-transport): add token streaming example, reframe append example by rainbowFi · Pull Request #3448 · ably/docs

rainbowFi · 2026-06-26T12:05:06Z

Refreshes the out-of-date AI Transport streaming examples (AIT-1030): adds a runnable token streaming example built on the AI Transport SDK, reframes the old append example under Pub/Sub, and fixes two example-gallery gaps found along the way.

How to review

The branch is five single-purpose commits, best read in order:

fix(examples): product badge fix. Example product keys (ai_transport, liveobjects) did not match @ably/ui's ProductTile keys, so those gallery cards rendered without a badge. ExamplesGrid now maps them.
feat(examples): redirects for renamed example pages. Gallery pages are generated at /examples/<id> from src/data/examples, and redirects were previously only sourced from MDX frontmatter, so renaming an example left a 404. Adds an optional redirectFrom field to Example, mirroring the MDX flow.
docs(pub-sub): reframe ai-transport-message-per-response as pub-sub-message-append. The example always used raw Pub/Sub appendMessage + rewind rather than the SDK, so the READMEs, UI copy, and gallery entry now describe it accurately and point to AI Transport as the recommended approach for AI streaming. The code now models a generic text stream rather than an LLM response: MockLLM becomes MockTextStream, Agent becomes Publisher, and prompt-and-response naming becomes stream naming throughout. The channel stays in the ai: namespace because that namespace has mutable messages enabled, which appendMessage() requires; a code comment records that constraint. Also includes review fixes: a working appendMessage() doc link (/docs/messages#append; the API-reference anchor targets an H4 that gets no anchor generated), dead markup removed, API key placeholder aligned. The old URL redirects to the new one.
docs(ai-transport): the token streaming example (React + JavaScript), on @ably/ai-transport 0.4. Mirrors the Core SDK getting started: the agent flow (createAgentSession → createRun → start → drain run.view → pipe → end) and the client hooks (ClientSessionProvider, useView, useClientSession). The model is mocked so it runs without an API key, but the fake LLM emits the exact UIMessageChunk stream that streamText(...).toUIMessageStream() produces, so the agent code matches a production integration; the two necessary deviations (agent runs in-browser, token source mocked) are commented in the code. Both variants re-render on run lifecycle events (session.tree.on('run')) and gate streaming on status === 'active', because useView alone would leave the UI stuck in the streaming state when a run reaches a terminal status (related SDK gap: AIT-1128). A Refresh button demonstrates recovery from channel history. Includes Sandpack deps, the root workspace dependency (@ably/ai-transport ~0.4.0, ai ^6, ably ~2.23.0) with the regenerated yarn.lock, gallery entry and image, and docs cross-links.
docs(ai-transport): remove ai-transport-message-per-token, superseded by the token streaming example. Pure deletion plus a redirect for its URL.

Verification

Every @ably/ai-transport 0.4 call and every mocked UIMessageChunk shape was checked against the package's type definitions; both variants mirror the Core SDK getting started guide.
All four changed example workspaces typecheck against the pinned 0.4.0 and build with vite; yarn install leaves the committed yarn.lock unchanged.
Examples component and data tests pass (12), ETL tests pass (302), eslint clean on changed files.

Known simplifications (intentional)

There is a brief window after send, before the run is observed, where the prompt button re-enables; guarding it needs extra state that adds noise to a teaching example, and the in-browser agent responds within milliseconds.
The React variant reloads history with a single useView({ limit: 30 }) page while the JavaScript variant drains history via hasOlder()/loadOlder(); the JavaScript variant deliberately demonstrates the paging API.
The append example keeps its pre-existing StrictMode quirk (a state update nested in an updater); its code is intentionally unchanged in this PR beyond the reframing copy.

coderabbitai · 2026-06-26T12:05:16Z

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: f535b604-3562-4ff0-aa79-7ff3ce32d1e7

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch AIT-1030-ai-transport-token-streaming-example

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

VeskeR

LGTM, couple of minor edits:

We also need to update ai-transport-token-streaming example to 0.5.0 ait sdk. The only breaking change is that AgentSession.close() is gone, and in non-durable execution examples we should call AgentSession.end(). I'm okay with this being changed in the follow-up PR, or here.
my Claude flagged a bunch of pre-existing broken anchor links, like /docs/channels#create → /docs/channels#use. Could you please double check in the affected files?

VeskeR · 2026-07-16T12:32:51Z

 import { Example } from '../../data/examples/types';

+// Example product keys don't all match @ably/ui's ProductTile keys.
+const PRODUCT_KEY_MAP: Record<string, ProductName> = {


don't know about the @ably/ui, but shouldn't we fix example product keys instead? so they use correct ones from 'src/components/ui/ProductTile/data'?

VeskeR · 2026-07-16T12:34:14Z

      },
    });
+
+    exampleDatum.redirectFrom?.forEach((redirectFrom) => {


can't comment on this, worth checking with someone from docs team

Example product keys (ai_transport, liveobjects) do not match @ably/ui's ProductTile keys (aiTransport, liveObjects), so gallery cards for those products rendered without a product badge. Map the keys in ExamplesGrid.

Example gallery pages are generated from src/data/examples at /examples/<id>, and redirects were previously only sourced from MDX redirect_from frontmatter, so renaming or removing an example left its old URL as a 404. Add an optional redirectFrom field to Example and write nginx and client-side redirects for it, mirroring the MDX flow.

coderabbitai · 2026-07-17T16:09:51Z

Caution

Review failed

An error occurred during the review process. Please try again later.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch AIT-1030-ai-transport-token-streaming-example

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

…e-append The example always used raw Pub/Sub appendMessage and rewind rather than the AI Transport SDK, so present it as a Pub/Sub message append example. The READMEs, UI text, and gallery entry now describe Pub/Sub append, and point to AI Transport as the recommended approach for streaming AI responses. The old example URL redirects to the new one. Rework the code to model a generic text stream rather than an LLM response: MockLLM becomes MockTextStream, Agent becomes Publisher, and prompt-and-response naming becomes stream naming throughout. The channel stays in the ai namespace, which has mutable messages enabled, as appendMessage() requires; a comment now records that constraint. Also fix issues found in review: link appendMessage() to /docs/messages#append (the previous API reference anchor targets an H4, which gets no anchor generated), remove dead prompt-display and cursor spans from the JavaScript variant, and align its fallback API key placeholder with the other examples.

…port SDK Add a runnable token streaming example (React and JavaScript) on @ably/ai-transport 0.5, mirroring the Core SDK getting started guide: the agent flow (createAgentSession, createRun, start, drain run.view, pipe, end) and the client hooks (ClientSessionProvider, useView, useClientSession). The non-durable agent tears down with AgentSession.end(); 0.5 removed AgentSession.close(). The model is mocked so the example runs without an API key, but the fake LLM emits the exact UIMessageChunk stream that streamText(...).toUIMessageStream() produces, so the agent code matches a production integration. The two necessary deviations (agent runs in-browser, token source mocked) are commented in the code. Both variants re-render on run lifecycle events (session.tree.on('run')) and gate streaming on status === 'active', because useView alone only re-renders on visible message-content changes and would leave the UI stuck in the streaming state when a run reaches a terminal status (related SDK gap: AIT-1128). A Refresh button demonstrates recovery: the full response is served from channel history on rejoin. Wire up the gallery entry, Sandpack dependencies (including zod, an ai peer dependency the vercel codec pulls in at runtime), and docs cross-links, and reuse the message-per-response gallery image for the new example.

Superseded by the ai-transport-token-streaming example, which shows the same token-by-token streaming through the AI Transport SDK rather than raw Pub/Sub. Remove the example, its gallery entry, its workspace entries, and its gallery image, and redirect its URL to the new example.

rainbowFi added the review-app Create a Heroku review app label Jun 26, 2026

rainbowFi force-pushed the AIT-1030-ai-transport-token-streaming-example branch 2 times, most recently from fd3ecc2 to 00cbf76 Compare June 26, 2026 13:41

ably-ci temporarily deployed to ably-docs-ait-1030-ai-t-xxqlrp June 26, 2026 13:42 Inactive

rainbowFi force-pushed the AIT-1030-ai-transport-token-streaming-example branch from 00cbf76 to d2f09c4 Compare July 8, 2026 15:35

rainbowFi added review-app Create a Heroku review app and removed review-app Create a Heroku review app labels Jul 9, 2026

ably-ci temporarily deployed to ably-docs-ait-1030-ai-t-hibixo July 9, 2026 11:36 Inactive

rainbowFi force-pushed the AIT-1030-ai-transport-token-streaming-example branch from d2f09c4 to f27495c Compare July 9, 2026 11:36

ably-ci temporarily deployed to ably-docs-ait-1030-ai-t-hibixo July 9, 2026 11:36 Inactive

ably-ci temporarily deployed to ably-docs-ait-1030-ai-t-hibixo July 9, 2026 12:10 Inactive

ably-ci temporarily deployed to ably-docs-ait-1030-ai-t-hibixo July 9, 2026 12:31 Inactive

ably-ci temporarily deployed to ably-docs-ait-1030-ai-t-hibixo July 9, 2026 13:41 Inactive

ably-ci temporarily deployed to ably-docs-ait-1030-ai-t-hibixo July 9, 2026 16:27 Inactive

ably-ci temporarily deployed to ably-docs-ait-1030-ai-t-hibixo July 9, 2026 17:06 Inactive

ably-ci temporarily deployed to ably-docs-ait-1030-ai-t-hibixo July 9, 2026 20:37 Inactive

rainbowFi force-pushed the AIT-1030-ai-transport-token-streaming-example branch from f4de9f1 to f078c15 Compare July 9, 2026 21:24

ably-ci temporarily deployed to ably-docs-ait-1030-ai-t-hibixo July 9, 2026 21:24 Inactive

rainbowFi force-pushed the AIT-1030-ai-transport-token-streaming-example branch from f078c15 to ba5edcf Compare July 9, 2026 21:37

ably-ci temporarily deployed to ably-docs-ait-1030-ai-t-hibixo July 9, 2026 21:37 Inactive

rainbowFi force-pushed the AIT-1030-ai-transport-token-streaming-example branch from ba5edcf to 13ebbad Compare July 9, 2026 21:38

ably-ci temporarily deployed to ably-docs-ait-1030-ai-t-hibixo July 9, 2026 21:38 Inactive

rainbowFi force-pushed the AIT-1030-ai-transport-token-streaming-example branch from 13ebbad to d3e619b Compare July 9, 2026 21:52

ably-ci temporarily deployed to ably-docs-ait-1030-ai-t-hibixo July 9, 2026 21:52 Inactive

rainbowFi force-pushed the AIT-1030-ai-transport-token-streaming-example branch from d3e619b to ce029a2 Compare July 9, 2026 21:54

ably-ci temporarily deployed to ably-docs-ait-1030-ai-t-hibixo July 9, 2026 21:54 Inactive

rainbowFi marked this pull request as ready for review July 9, 2026 21:56

rainbowFi requested a review from VeskeR July 9, 2026 21:56

VeskeR removed the review-app Create a Heroku review app label Jul 16, 2026

VeskeR added the review-app Create a Heroku review app label Jul 16, 2026

ably-ci temporarily deployed to ably-docs-ait-1030-ai-t-dqaiip July 16, 2026 12:46 Inactive

VeskeR requested changes Jul 16, 2026

View reviewed changes

rainbowFi added 2 commits July 17, 2026 16:01

rainbowFi force-pushed the AIT-1030-ai-transport-token-streaming-example branch from ce029a2 to 6854d82 Compare July 17, 2026 15:02

ably-ci temporarily deployed to ably-docs-ait-1030-ai-t-dqaiip July 17, 2026 15:02 Inactive

rainbowFi force-pushed the AIT-1030-ai-transport-token-streaming-example branch from 6854d82 to 297070f Compare July 17, 2026 15:31

ably-ci temporarily deployed to ably-docs-ait-1030-ai-t-dqaiip July 17, 2026 15:31 Inactive

rainbowFi force-pushed the AIT-1030-ai-transport-token-streaming-example branch from 297070f to 9efaa4e Compare July 17, 2026 16:04

ably-ci temporarily deployed to ably-docs-ait-1030-ai-t-dqaiip July 17, 2026 16:04 Inactive

rainbowFi added 3 commits July 17, 2026 17:10

rainbowFi force-pushed the AIT-1030-ai-transport-token-streaming-example branch from 9efaa4e to b6ad953 Compare July 17, 2026 16:10

ably-ci deployed to ably-docs-ait-1030-ai-t-dqaiip July 17, 2026 16:10 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(ai-transport): add token streaming example, reframe append example#3448

docs(ai-transport): add token streaming example, reframe append example#3448
rainbowFi wants to merge 5 commits into
mainfrom
AIT-1030-ai-transport-token-streaming-example

rainbowFi commented Jun 26, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jun 26, 2026 •

edited

Loading

Review skipped

Uh oh!

VeskeR left a comment •

edited

Loading

Uh oh!

VeskeR Jul 16, 2026

Uh oh!

VeskeR Jul 16, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot commented Jul 17, 2026

Review failed

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

rainbowFi commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

How to review

Verification

Known simplifications (intentional)

Uh oh!

coderabbitai Bot commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

VeskeR left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

VeskeR Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

VeskeR Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot commented Jul 17, 2026

Review failed

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

rainbowFi commented Jun 26, 2026 •

edited

Loading

coderabbitai Bot commented Jun 26, 2026 •

edited

Loading

VeskeR left a comment •

edited

Loading