Bugfix/ait 133 citations #3100
Open
Bugfix/ait 133 citations #3100
+260
−340
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the 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. Comment |
paddybyers
reviewed
Jan 14, 2026
| meta_keywords: "citations, references, source attribution, message annotations, AI transparency, source tracking, annotation summaries" | ||
| --- | ||
|
|
||
| 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](/docs/messages/annotations) provide a model-agnostic, structured way to attach source citations to AI responses without modifying the response content. It enable clients to append information to existing messages on a channel. |
Member
There was a problem hiding this comment.
Suggested change
| 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](/docs/messages/annotations) provide a model-agnostic, structured way to attach source citations to AI responses without modifying the response content. It enable clients to append information to existing messages on a channel. | |
| 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](/docs/messages/annotations) 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. |
| - 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 an audit trail showing which information sources were consulted during AI interactions. |
Member
There was a problem hiding this comment.
Suggested change
| - Audit trails: For enterprise applications, citations provide an audit trail showing which information sources were consulted during AI interactions. | |
| - Audit trails: For enterprise applications, citations provide explicit traceability between LLM responses and the information sources that were consulted when generating them. |
|
|
||
| 1. The agent publishes an AI response as a single message, or builds it incrementally using [message appends](/docs/ai-transport/message-per-response). | ||
| 2. The agent publishes one or more annotations to attach citations to the response message, each referencing the response message [`serial`](/docs/messages#properties). | ||
| 3. Ably automatically aggregates annotations and generates summaries showing total counts and groupings (for example, by domain name). |
Member
There was a problem hiding this comment.
Suggested change
| 3. Ably automatically aggregates annotations and generates summaries showing total counts and groupings (for example, by domain name). | |
| 3. Ably automatically aggregates annotations and generates summaries showing total counts and groupings (for example, by source domain name). |
| 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 (e.g. `ai:*` for all channels starting with `ai:`). |
Member
There was a problem hiding this comment.
Suggested change
| 4. Enter a channel name or namespace pattern (e.g. `ai:*` for all channels starting with `ai:`). | |
| 4. Enter a channel name or namespace pattern (e.g. `ai` for all channels starting with `ai:`). |
Do we need to check for other occurrences of this?
| 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:*`. |
Member
There was a problem hiding this comment.
Suggested change
| The examples in this guide use the `ai:` namespace prefix, which assumes you have configured the rule for `ai:*`. | |
| The examples in this guide use the `ai:` namespace prefix, which assumes you have configured the rule for `ai`. |
|
|
||
| ## Citation data model <a id="data-model"/> | ||
|
|
||
| Citations are implemented using [message annotations](/docs/messages/annotations). Each citation consists of an annotation type that determines how citations are aggregated into summaries, and a data payload containing the citation details. |
Member
There was a problem hiding this comment.
Suggested change
| Citations are implemented using [message annotations](/docs/messages/annotations). Each citation consists of an annotation type that determines how citations are aggregated into summaries, and a data payload containing the citation details. | |
| Citations are implemented using [message annotations](/docs/messages/annotations). Each citation includes an annotation `type` that determines how citations are aggregated into summaries, and a `data` payload containing the citation details. |
| </Aside> | ||
|
|
||
| <Aside data-type="note"> | ||
| Identify the agent with a [`clientId`](/docs/messages#properties) in order to attribute citations to a specific agent. This is useful in multi-agent architectures where multiple agents may contribute citations to the same response. For more information, see [Agent identity](/docs/ai-transport/features/sessions-identity/identifying-users-and-agents#agent-identity). |
Member
There was a problem hiding this comment.
Suggested change
| Identify the agent with a [`clientId`](/docs/messages#properties) in order to attribute citations to a specific agent. This is useful in multi-agent architectures where multiple agents may contribute citations to the same response. For more information, see [Agent identity](/docs/ai-transport/features/sessions-identity/identifying-users-and-agents#agent-identity). | |
| Identify the agent with a [`clientId`](/docs/messages#properties) in order to attribute a citation to a specific agent. This is useful in multi-agent architectures where multiple agents may contribute citations to the same response. For more information, see [Agent identity](/docs/ai-transport/features/sessions-identity/identifying-users-and-agents#agent-identity). |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
Misc. fixes and improvements to the citations docs page.
Checklist