# Citations
AI agents often draw information from external sources such as documents, web pages, or databases. Citations to those sources enable users to verify information, explore sources in detail, and understand where responses came from. Ably's [message annotations](https://ably.com/docs/messages/annotations.md) provide a model-agnostic, structured way to attach source citations to AI responses without modifying the response content. It enables clients to append information to existing messages on a channel.
This pattern works when publishing complete responses as messages on a channel or when streaming responses using the [message-per-response](https://ably.com/docs/ai-transport/message-per-response.md) pattern.
## Why citations matter
Including citations on AI responses provides:
- Transparency: Users can verify claims and understand the basis for AI responses. This builds trust and allows users to fact-check information independently.
- Source exploration: Citations enable users to dive deeper into topics by accessing original sources. This is particularly valuable for research, learning, and decision-making workflows.
- Attribution: Proper attribution respects content creators and helps users understand which sources informed the AI's response.
- Audit trails: For enterprise applications, citations provide explicit traceability between LLM responses and the information sources that were consulted when generating them.
## How it works
Use [message annotations](https://ably.com/docs/messages/annotations.md) to attach source metadata to AI response messages without modifying the response content:
1. The agent publishes an AI response as a single message, or builds it incrementally using [message appends](https://ably.com/docs/ai-transport/message-per-response.md).
2. The agent publishes one or more annotations to attach citations to the response message, each referencing the response message [`serial`](https://ably.com/docs/messages.md#properties).
3. Ably automatically aggregates annotations and generates summaries showing total counts and groupings (for example, by source domain name).
4. Clients receive citation summaries automatically and can optionally subscribe to individual annotation events for detailed citation data as part of the realtime stream. Alternatively, clients can obtain annotations for a given message via the REST API.
## Enable message annotations
Message append functionality requires "Message annotations, updates, deletes and appends" to be enabled in a [channel rule](https://ably.com/docs/channels.md#rules) associated with the channel.
To enable the channel rule:
1. Go to the [Ably dashboard](https://www.ably.com/dashboard) and select your app.
2. Navigate to the "Configuration" > "Rules" section from the left-hand navigation bar.
3. Choose "Add new rule".
4. Enter a channel name or namespace pattern (for example, `ai` for all channels starting with `ai:`).
5. Select the "Message annotations, updates, deletes and appends" option from the list.
6. Click "Create channel rule".
The examples in this guide use the `ai:` namespace prefix, which assumes you have configured the rule for `ai`.
## Citation data model
Citations are implemented using [message annotations](https://ably.com/docs/messages/annotations.md). Each citation includes an annotation `type` that determines how citations are aggregated into summaries, and a `data` payload containing the citation details.
### Annotation type
[Annotation types](https://ably.com/docs/messages/annotations.md#annotation-types) determine how annotations are processed and aggregated into summaries. The type is a string of the format `namespace:summarization_method`:
- `namespace` is a string that logically groups related annotations. For example, use `citations` for AI response citations.
- `summarization_method` specifies how annotations are aggregated to produce summaries.
Use the [`multiple.v1`](https://ably.com/docs/messages/annotations.md#multiple) summarization method for AI response citations. This is well suited for citations because:
- AI responses often reference the same source multiple times, and `multiple.v1` counts each citation separately.
- Citations can be grouped by source using the `name` field (for example, by domain name), so clients can display "3 citations from wikipedia.org, 2 from nasa.gov".
The examples below use the annotation type `citations:multiple.v1`.
### Annotation data
The annotation `data` field can contain any structured data relevant to your citation use case. For example, a citation for a web search result might include:
```json
{
"url": "https://example.com/article",
"title": "Example Article Title",
"startOffset": 120,
"endOffset": 180,
"snippet": "Short excerpt from source"
}
```
In this example:
- `url` is the source URL.
- `title` is the title of the web page.
- `startOffset` is the character position in the response where this citation begins.
- `endOffset` is the character position in the response where the citation ends.
- `snippet` is a short excerpt from the source content for preview displays.
Including character offsets in annotation data allow UIs to attach inline citation markers to specific portions of the response text.
## Publish citations
Agents create citations by publishing [message annotations](https://ably.com/docs/messages/annotations.md) that reference the [`serial`](https://ably.com/docs/messages.md#properties) of the response message:
```javascript
const channel = realtime.channels.get('ai:your-channel-name');
// Publish the AI response message
const response = 'The James Webb Space Telescope launched in December 2021 and its first images were released in July 2022.';
const { serials: [msgSerial] } = await channel.publish('response', response);
// Add citations by annotating the response message
await channel.annotations.publish(msgSerial, {
type: 'citations:multiple.v1',
name: 'science.nasa.gov',
data: {
url: 'https://science.nasa.gov/mission/webb/',
title: 'James Webb Space Telescope - NASA Science',
startOffset: 43,
endOffset: 56,
snippet: 'Webb launched on Dec. 25th 2021'
}
});
await channel.annotations.publish(msgSerial, {
type: 'citations:multiple.v1',
name: 'en.wikipedia.org',
data: {
url: 'https://en.wikipedia.org/wiki/James_Webb_Space_Telescope',
title: 'James Webb Space Telescope - Wikipedia',
startOffset: 95,
endOffset: 104,
snippet: 'The telescope\'s first image was released to the public on 11 July 2022.'
}
});
```
```java
Channel channel = realtime.channels.get("ai:your-channel-name");
// Publish the AI response message
String response = "The James Webb Space Telescope launched in December 2021 and its first images were released in July 2022.";
CompletableFuture publishFuture = new CompletableFuture<>()
channel.publish("response", response, new Callback() {
@Override
public void onSuccess(PublishResult result) {
publishFuture.complete(result);
}
@Override
public void onError(ErrorInfo reason) {
publishFuture.completeExceptionally(AblyException.fromErrorInfo(reason));
}
});
String msgSerial = publishFuture.get().serials[0];
// Add citations by annotating the response message
JsonObject citation1Data = new JsonObject();
citation1Data.addProperty("url", "https://science.nasa.gov/mission/webb/");
citation1Data.addProperty("title", "James Webb Space Telescope - NASA Science");
citation1Data.addProperty("startOffset", 43);
citation1Data.addProperty("endOffset", 56);
citation1Data.addProperty("snippet", "Webb launched on Dec. 25th 2021");
Annotation citation1 = new Annotation();
citation1.name = "science.nasa.gov";
citation1.type = "citations:multiple.v1";
citation1.data = citation1Data;
channel.annotations.publish(msgSerial, citation1);
JsonObject citation2Data = new JsonObject();
citation2Data.addProperty("url", "https://en.wikipedia.org/wiki/James_Webb_Space_Telescope");
citation2Data.addProperty("title", "James Webb Space Telescope - Wikipedia");
citation2Data.addProperty("startOffset", 95);
citation2Data.addProperty("endOffset", 104);
citation2Data.addProperty("snippet", "The telescope's first image was released to the public on 11 July 2022.");
Annotation citation2 = new Annotation();
citation2.name = "en.wikipedia.org";
citation2.type = "citations:multiple.v1";
citation2.data = citation2Data;
channel.annotations.publish(msgSerial, citation2);
```
## Subscribe to summaries
Clients can display a summary of the citations attached to a response by using [annotation summaries](https://ably.com/docs/messages/annotations.md#annotation-summaries). Clients receive realtime updates to annotation summaries automatically when subscribing to a channel, which are [delivered as messages](https://ably.com/docs/messages/annotations.md#subscribe) with an `action` of `message.summary`. When using [`multiple.v1`](https://ably.com/docs/messages/annotations.md#multiple) summarization, counts are grouped by the annotation `name`.
In the example below, the `name` is set to the domain name of the citation source, so summaries show counts per domain:
```javascript
const channel = realtime.channels.get('ai:your-channel-name');
await channel.subscribe((message) => {
if (message.action === 'message.summary') {
const citations = message.annotations.summary['citations:multiple.v1'];
if (citations) {
console.log('Citation summary:', citations);
}
}
});
```
```java
Channel channel = realtime.channels.get("ai:your-channel-name");
channel.subscribe(message -> {
if (message.action == MessageAction.MESSAGE_SUMMARY) {
JsonObject citations = message.annotations.summary.get("citations:multiple.v1");
if (citations != null) {
System.out.println("Citation summary: " + citations);
}
}
});
```
The `multiple.v1` summary groups counts by the annotation `name`, with totals and per-client breakdowns for each group:
```json
{
"citations:multiple.v1": {
"science.nasa.gov": {
"total": 1,
"clientIds": {
"research-agent": 1
},
"totalUnidentified": 0,
"totalClientIds": 1,
"clipped": false
},
"en.wikipedia.org": {
"total": 1,
"clientIds": {
"research-agent": 1
},
"totalUnidentified": 0,
"totalClientIds": 1,
"clipped": false
}
}
}
```
When agents publish citations with a [`clientId`](https://ably.com/docs/auth/identified-clients.md), summaries include a per-client count showing how many citations each agent contributed. Citations published by [unidentified](https://ably.com/docs/auth/identified-clients.md#unidentified) clients are counted in the `totalUnidentified` field.
## Subscribe to individual citations
To access the full citation data, subscribe to [individual annotation events](https://ably.com/docs/messages/annotations.md#individual-annotations):
```javascript
const channel = realtime.channels.get('ai:your-channel-name', {
modes: ['ANNOTATION_SUBSCRIBE']
});
await channel.annotations.subscribe((annotation) => {
if (annotation.action === 'annotation.create' &&
annotation.type === 'citations:multiple.v1') {
const { url, title } = annotation.data;
console.log(`Citation: ${title} (${url})`);
// Output: Citation: James Webb Space Telescope - Wikipedia (https://en.wikipedia.org/wiki/James_Webb_Space_Telescope)
}
});
```
```java
ChannelOptions options = new ChannelOptions();
options.modes = new ChannelMode[]{ChannelMode.ANNOTATION_SUBSCRIBE};
Channel channel = realtime.channels.get("ai:your-channel-name", options);
channel.annotations.subscribe(annotation -> {
if (annotation.action == AnnotationAction.ANNOTATION_CREATE &&
annotation.type.equals("citations:multiple.v1")) {
JsonObject data = annotation.data;
String url = data.get("url").getAsString();
String title = data.get("title").getAsString();
System.out.println("Citation: " + title + " (" + url + ")");
// Output: Citation: James Webb Space Telescope - Wikipedia (https://en.wikipedia.org/wiki/James_Webb_Space_Telescope)
}
});
```
Each annotation event includes the `messageSerial` of the response message it is attached to, the `name` used for grouping in summaries, and the full citation `data` payload. This data can be used to render clickable source links or attach inline citation markers to specific portions of the response text:
```json
{
"action": "annotation.create",
"clientId": "research-agent",
"type": "citations:multiple.v1",
"messageSerial": "01767638186693-000@108SP4XcgBxfMO07491612:000",
"name": "en.wikipedia.org",
"data": {
"url": "https://en.wikipedia.org/wiki/James_Webb_Space_Telescope",
"title": "James Webb Space Telescope - Wikipedia",
"startOffset": 95,
"endOffset": 104,
"snippet": "The telescope's first image was released to the public on 11 July 2022."
}
}
```
## Retrieve citations on demand
Annotations can also be retrieved via the [REST API](https://ably.com/docs/api/rest-api.md#annotations-list) without maintaining a realtime subscription.