[BUG] Bedrock Runtime API CitationLocation Tagged Union Structure Error

[Tarun02]

Checks

• I have updated to the lastest minor and patch version of Strands
• I have checked the documentation and this is not expected behavior
• I have searched ./issues and there are no duplicates of my issue

Strands Version

1.19.0

Python Version

3.14.2

Operating System

N/A

Installation Method

pip

Steps to Reproduce

Minimum Reproducible code

from strands.models.bedrock import BedrockModel
import asyncio

async def processing_streaming_response():
    model = BedrockModel(
        model_id="us.anthropic.claude-3-7-sonnet-20250219-v1:0"
    )

    messages = [
        {
            "role": "user",
            "content": [
                {
                    "text": "Use this media in your response."
                }
            ]
        },
        # Assistant response with citations
        {
            "role": "assistant",
            "content": [
                {
                    "text": "I've analyzed the document. Here's what I found:"
                },
                {
                    "citationsContent": {
                        "citations": [
                            {
                                "location": {
                                    "documentChar": {
                                        "documentIndex": 0,
                                        "start": 150,
                                        "end": 300
                                    }
                                },
                                "sourceContent": [
                                    {
                                        "text": "Employee benefits include health insurance and retirement plans"
                                    }
                                ],
                                "title": "Benefits Section"
                            },
                            {
                                "location": {
                                    "documentPage": {
                                        "documentIndex": 0,
                                        "start": 2,
                                        "end": 3
                                    }
                                },
                                "sourceContent": [
                                    {
                                        "text": "Vacation policy allows 15 days per year"
                                    }
                                ],
                                "title": "Vacation Policy"
                            }
                        ],
                        "content": [
                            {
                                "text": "Based on the document, employees receive comprehensive benefits including health insurance, retirement plans, and 15 days of vacation per year."
                            }
                        ]
                    }
                }
            ]
        }
    ]

    #model._format_bedrock_messages(messages=messages)
    response_text = ""
    async for chunk in model.stream(
        messages=messages
    ):
        #response_text += chunk
        print(chunk, end="", flush=True)

    return response_text

asyncio.run(processing_streaming_response())

• Install strands through this command: pip install strands-agents strands-tools
• Run the code, and you will observe the following error:

botocore.exceptions.ParamValidationError: Parameter validation failed:
Must set one of the following keys for tagged unionstructure messages[1].content[1].citationsContent.citations[0].location: web, documentChar, documentPage, documentChunk, searchResultLocation.
Must set one of the following keys for tagged unionstructure messages[1].content[1].citationsContent.citations[1].location: web, documentChar, documentPage, documentChunk, searchResultLocation.

Expected Behavior

• CitationLocation objects should preserve the tagged union structure required by AWS Bedrock Runtime API: https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_CitationLocation.html

Actual Behavior

• It is not doing that but expecting all the keys should be present in the API.

Additional Context

No response

Possible Solution

• Preserve the union structure when processing CitationLocation objects.
• Sample code below(need to test it out):

def _format_citation_location(location: dict) -> dict:
    """Preserve tagged union structure for AWS Bedrock API compatibility"""
    
    # Check which union type is present and preserve wrapper
    if "documentChar" in location:
        inner = location["documentChar"]
        filtered_inner = {}
        if "documentIndex" in inner:
            filtered_inner["documentIndex"] = inner["documentIndex"]
        if "start" in inner:
            filtered_inner["start"] = inner["start"]
        if "end" in inner:
            filtered_inner["end"] = inner["end"]
        return {"documentChar": filtered_inner}
    
    elif "documentPage" in location:
        # Similar processing for documentPage union type
        return {"documentPage": filtered_inner}
    
    # Handle other union types: documentChunk, searchResultLocation, web
    # ...
    
    else:
        # Fallback: infer union type from available fields
        if "url" in location:
            return {"web": {"url": location["url"]}}
        # Default to documentChar for document locations
        return {"documentChar": location}

Related Issues

No response

[dbschmigelski]

Hi,

Confirming that I can reproduce this. If we add the last line to our existing integration test, to trigger a multi-turn conversation, we get the failure.

def test_document_citations_streaming(streaming_agent, letter_pdf):
    content: list[ContentBlock] = [
        {
            "document": {
                "name": "letter to shareholders",
                "source": {"bytes": letter_pdf},
                "citations": {"enabled": True},
                "context": "This is a letter to shareholders",
                "format": "pdf",
            },
        },
        {"text": "What does the document say about artificial intelligence? Use citations to back up your answer."},
    ]
    streaming_agent(content)

    assert any("citationsContent" in content for content in streaming_agent.messages[-1]["content"])

    # Validate message structure is valid in multi-turn
    streaming_agent("What is your favorite part?")

hatch test tests_integ/models/test_model_bedrock.py::test_document_citations_streaming

Citations were introduced in #631

What we need to explore now is if this is possible to fix in a backwards compatible manner. We also need to consider, what I suspect is true, which is if this feature is unusable meaning it is acceptable to break compatibility.

[ericfzhu]

Citations are just for traceability purposes, so why not just filter them out in the input from _format_bedrock_messages?
It works when I added this line to line 333, which will still keep the citations in the message history:

if "citationsContent" in content_block:
    continue

Alternatively, the proper fix would be to include the correct structure for citations inside of _format_request_message_content:

if "location" in citation:
    location = citation["location"]
    # Filter location fields to only include Bedrock-supported ones
    allowed = {
        "documentChar": {"documentIndex", "start", "end"},
        "documentPage": {"documentIndex", "start", "end"},
        "documentChunk": {"documentIndex", "start", "end"},
        "searchResultLocation": {"searchResultIndex", "start", "end"},
        "web": {"url", "domain"},
    }
    for union_type, fields in allowed.items():
        if union_type in location:
            inner = location[union_type]
            filtered_citation["location"] = {
                union_type: {k: v for k, v in inner.items() if k in fields}
            }
            break

You'll end up with an error below, because streamed responses return ContentBlockDelta and not CitationsContentBlock, and handle_content_block_stop from streaming.py is not formatting these correctly:

ValidationException: An error occurred (ValidationException) when calling the ConverseStream operation: The model returned the following errors: messages.1.content.2.text.text: Field required

https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlockDelta.html

You can fix this by changing the elif text section of the handle_content_block_stop function inside of streaming.py to this:

elif text:
    if citations_content:
        citations_block: CitationsContentBlock = {
            "citations": citations_content,
            "content": [{"text": text}]
        }
        content.append({"citationsContent": citations_block})
        state["citationsContent"] = []
    else:
        content.append({"text": text})
    state["text"] = ""

I have a proposed fix PR for this bug: #1341

[dbschmigelski]

Thank you for raising this. Internally I am probing Bedrock as well.

There are definitely ways to get this to work. I want to make sure we are acting on documented behavior. Presently, the Bedrock docs are overwhelmingly marked with Required: No, so I want to reference complementary docs so it is obvious what the "correct" use should be, both now and in the future. What I want to avoid is Bedrock making a change which breaks us because we were acting on non-documented behavior.

---

There are several people attempting to contribute. @ericfzhu, your PR is closest to what I have locally. There are some minor details that I believe will make the approach more consistent with other content blocks. For speed of review, I am going to raise a new PR as we are working on this internally with high priority. Both @danilop and @ericfzhu will be given co-authorship, of course.

Regarding "Citations are just for traceability purposes" I agree but non-filtering is what the current behavior is attempting to do.

---

Like @danilop proposed, we are going to support web and search results in a separate PR. The main goal here is to ensure our shapes are correct to allow that.