docs: add citation guides for OpenAI and Anthropic by GregHolmes · Pull Request #3146 · ably/docs

GregHolmes · 2026-01-22T15:27:28Z

Add two new AI Transport guides demonstrating how to attach source citations to AI responses using Ably message annotations:

openai-citations.mdx: Attach citations from OpenAI web search
anthropic-citations.mdx: Attach citations from Anthropic documents

Both guides cover:

Enabling message annotations via channel rules
Publishing responses and citations to Ably
Subscribing to citation summaries and individual citations
Combining citations with streaming responses

coderabbitai · 2026-01-22T15:27:39Z

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.

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
Post copyable unit tests in a comment
Commit unit tests in branch AIT-140-Guide-documentation-citations-and-source-annotations

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 and usage tips.}

zknill · 2026-02-17T16:32:13Z

src/pages/docs/guides/ai-transport/anthropic/anthropic-citations.mdx

+  }
+
+  // Publish the AI response message
+  const { serials: [msgSerial] } = await channel.publish('response', fullText);


where does fullText come from? we never actually call processResponse?

1cb5e6b

fullText is further up.
I've removed the initiation of processResponse, console logged and then call processResponse when it's created in a later step.

zknill · 2026-02-17T16:34:49Z

src/pages/docs/guides/ai-transport/anthropic/anthropic-citations.mdx

+await channel.subscribe((message) => {
+  switch (message.action) {
+    case 'message.create':
+      console.log('\n[New response]');
+      console.log('Serial:', message.serial);
+      console.log('Content:', message.data);
+      responses.set(message.serial, { content: message.data, citations: [] });
+      break;
+
+    case 'message.update':
+      // Handle streamed content updates
+      const response = responses.get(message.serial);
+      if (response) {
+        response.content = message.data;
+        console.log('\n[Response updated]');
+        console.log('Content:', message.data);
+      }
+      break;
+  }
+});
+
+// Subscribe to individual citation annotations
+await channel.annotations.subscribe((annotation) => {


channel.subscribe(...) isn't processing message.summary action, and channel.annotations.subscribe(...) is for raw annotations.

So this doesn't match the header: "Step 4: Subscribe to citation summaries " which references summaries

The openapi guide has a different set of headers here that works better to fix this problem

I've aligned anthropic with the openai guide: 4dd9be4

zknill · 2026-02-17T16:37:09Z

src/pages/docs/guides/ai-transport/openai/openai-citations.mdx

+// Create response with web search enabled
+async function getOpenAIResponseWithCitations(question) {
+  const response = await openai.responses.create({
+    model: "gpt-4.1",


we're using gpt-5 in the openai-message-per-response doc, lets just be consistent

Updated in this fixup: 7c06253

zknill · 2026-02-23T18:32:28Z

src/pages/docs/guides/ai-transport/anthropic/anthropic-citations.mdx

+---
+
+This guide shows you how to attach source citations to AI responses from Anthropic's [Messages API](https://docs.anthropic.com/en/api/messages) using Ably [message annotations](/docs/messages/annotations). When Anthropic provides citations from documents or search results, you can publish them as annotations on Ably messages, enabling clients to display source references alongside AI responses in realtime.
+
+Using Ably to distribute citations enables you to separate citation metadata from response content, display citation summaries updated in realtime, and retrieve detailed citation data on demand.
+
+<Aside data-type="further-reading">
+To learn more about the citations pattern and how message annotations work, see the [citations](/docs/ai-transport/messaging/citations) documentation.
+</Aside>
+


Do we know / have an idea on why you would want to include citations? Like.. why would I care about adding annotations to a message?

You're right, missing a key bit here. Why use citations. I've updated the intro text: adbef67

zknill · 2026-02-24T10:36:25Z

src/pages/docs/guides/ai-transport/anthropic/anthropic-citations.mdx

+
+This guide shows you how to attach source citations to AI responses from Anthropic's [Messages API](https://docs.anthropic.com/en/api/messages) using Ably [message annotations](/docs/messages/annotations). When Anthropic provides citations from documents or search results, you can publish them as annotations on Ably messages, enabling clients to display source references alongside AI responses in realtime.
+
+Attaching citations to AI responses enables your users to verify claims against original sources, explore topics in depth, and properly attribute content creators. For enterprises, citations provide explicit traceability between LLM responses and the information sources that were consulted when generating them.


what's "enterprises" got to do with it?

This reads a bit janky, around "verify claims against original sources", etc.

zknill

+1 shippo 🚢

Add two new AI Transport guides demonstrating how to attach source citations to AI responses using Ably message annotations: - openai-citations.mdx: Attach citations from OpenAI web search - anthropic-citations.mdx: Attach citations from Anthropic documents Both guides cover: - Enabling message annotations via channel rules - Publishing responses and citations to Ably - Subscribing to citation summaries and individual citations - Combining citations with streaming responses

GregHolmes requested review from mschristensen and rainbowFi January 22, 2026 15:27

GregHolmes self-assigned this Jan 22, 2026

GregHolmes added the review-app Create a Heroku review app label Jan 22, 2026

ably-ci temporarily deployed to ably-docs-ait-140-guide-aj312o January 22, 2026 15:28 Inactive

zknill self-requested a review February 12, 2026 16:11

GregHolmes requested a review from JoaoDiasAbly February 17, 2026 15:15

zknill reviewed Feb 17, 2026

View reviewed changes

GregHolmes removed request for JoaoDiasAbly, mschristensen and rainbowFi February 20, 2026 12:23

GregHolmes force-pushed the AIT-140-Guide-documentation-citations-and-source-annotations branch from 854d3df to f555560 Compare February 23, 2026 16:20

zknill approved these changes Feb 23, 2026

View reviewed changes

GregHolmes force-pushed the AIT-140-Guide-documentation-citations-and-source-annotations branch from 7c06253 to 91b3c04 Compare February 24, 2026 10:32

zknill reviewed Feb 24, 2026

View reviewed changes

zknill approved these changes Feb 24, 2026

View reviewed changes

GregHolmes added review-app Create a Heroku review app and removed review-app Create a Heroku review app labels Feb 24, 2026

ably-ci temporarily deployed to ably-docs-ait-140-guide-ixhqtq February 24, 2026 10:57 Inactive

GregHolmes force-pushed the AIT-140-Guide-documentation-citations-and-source-annotations branch from 3033daf to 340e08f Compare February 24, 2026 10:57

GregHolmes temporarily deployed to ably-docs-ait-140-guide-ixhqtq February 24, 2026 10:58 Inactive

GregHolmes merged commit 4be74ac into main Feb 24, 2026
7 checks passed

GregHolmes deleted the AIT-140-Guide-documentation-citations-and-source-annotations branch February 24, 2026 11:14

claude bot added the claude-code-assisted label Feb 25, 2026


		This guide shows you how to attach source citations to AI responses from Anthropic's [Messages API](https://docs.anthropic.com/en/api/messages) using Ably [message annotations](/docs/messages/annotations). When Anthropic provides citations from documents or search results, you can publish them as annotations on Ably messages, enabling clients to display source references alongside AI responses in realtime.

		Attaching citations to AI responses enables your users to verify claims against original sources, explore topics in depth, and properly attribute content creators. For enterprises, citations provide explicit traceability between LLM responses and the information sources that were consulted when generating them.

Comments

Conversation

GregHolmes commented Jan 22, 2026

Uh oh!

coderabbitai bot commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zknill left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

coderabbitai bot commented Jan 22, 2026 •

edited

Loading