[FEATURE] Native citations for RAG / Knowledge Base tool results

[rahulrsingh09]

[FEATURE] Native citations for RAG / Knowledge Base tool results

Problem

Bedrock Converse API supports native citations when it sees DocumentBlock in conversation context. PR #576 added support for tools to return DocumentBlock. However, there's no documented pattern for the most common use case: Bedrock Knowledge Base retrieval → native citations.

The KB RetrieveCommand API returns plain text chunks (strings), not DocumentBlock objects. To get native citations, a tool would need to:

1. Call KB Retrieve to get text chunks + source S3 URIs
2. Fetch the original source documents from S3 as bytes
3. Construct DocumentBlock objects with those bytes
4. Return them from the tool

This is inefficient (fetching full PDFs for each query) and loses chunk-level granularity — Bedrock would cite the whole document, not the specific retrieved passage.

Proposed Solution

One or more of:

• SDK-level RAG helper that wraps KB Retrieve and automatically constructs citation-ready content blocks from the results
• Document fragment support — allow DocumentBlock to carry a text excerpt with source metadata, so Bedrock can generate citations from retrieved chunks without needing the full document bytes
• Integration example — at minimum, a documented pattern for how to bridge KB Retrieve → DocumentBlock → native citations, even if it requires full doc fetch

Context

• PR feat: support documentblock, imageblock, videoblock in model providers that support it #576 enabled DocumentBlock in tool results (v0.7.0+)
• PR fix: use correct 'citation' delta key for streaming citations in Bedrock provider #1058 fixed streaming citation delta handling
• Bedrock KB Retrieve API: @aws-sdk/client-bedrock-agent-runtime RetrieveCommand
• Current workaround: prompt-based citations (LLM formats [1] DocName — "excerpt", parsed client-side)

Impact

This is the missing link between Bedrock's two flagship features (Knowledge Bases and native citations). Any agent using KB retrieval tools today cannot leverage native citations without fetching full source documents on every query, which is impractical at scale.