[sophia-ramsey]

Motivation & Context

An internal bug reported that citations were not correctly being propagated with hosted agents. The citation would include the correct filename or source, but would not link to the annotation properly, instead registering as plain text.

Description & Review Guide

• What are the major changes? Updated ResponsesHostServer to serialize URL and file citation annotations into Responses payloads for both streaming and non-streaming responses, with regression coverage for supported annotation types and edge cases.
• What is the impact of these changes? Hosted agents now preserve citation metadata through the Python hosting boundary, allowing Teams and Copilot to render clickable citations instead of displaying unsupported raw citation markers.
• What do you want reviewers to focus on? Edge cases or potential issues with any other wrappers or downstream agent services.

Related Issue

Fixes #9434

AI Assistance

• No material AI assistance was used.
• This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance details: Used GPT-5.6 Sol for planning, implementation, and testing

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[Copilot]

🟡 Changes recommended

Citation offsets can be shifted incorrectly, and ordinary streaming introduces quadratic text copying.

2 open findings

• Avoid quadratic copying for citation-free append streaming · New
• Preserve occurrence-relative annotation indices in streamed chunks · New

What changed in this PR

Preserves citation metadata across the Python hosting boundary so downstream clients can render clickable citations, addressing #9434.

Changes:

• Converts framework citations into Responses annotations.
• Includes annotations in streaming and non-streaming output.
• Adds conversion and response regression tests.

File	Description
python/​packages/​foundry_hosting/​tests/​test_responses.py	Tests citation conversion, edge cases, and response consistency.
python/​packages/​foundry_hosting/​agent_framework_foundry_hosting/​_responses.py	Converts and propagates citation annotations.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[github-code-quality]

Code coverage overview

Languages: Python

Python / code-coverage/python

main 1168c00	sramsey/python-citat... 01261ad	+/-
92%	92%	0%

View coverage of the 6 most impacted files.

File	main 1168c00	sramsey/python-citat... 01261ad	+/-
packages/openai..._chat_client.py	94%	94%	0%
packages/core/a...ework/_types.py	96%	96%	0%
packages/ag-ui/.../_run_common.py	95%	95%	0%
packages/anthro..._chat_client.py	96%	96%	0%
packages/foundr...g/_responses.py	88%	89%	+1%
packages/foundr...ow_responses.py	81%	82%	+1%

ℹ️ Calculations represent line coverage. Results may change as calculations are updated.

---

_{Updated October 27, 2026 02:50 UTC}

[github-actions]

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (1 commit(s)): 0da89b5958e8
Model: gpt-5.6-sol

Overview

The review found 3 verified inline finding(s).

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
3 verified findings remained after source verification (3 medium) across 1 file. Details are attached to the affected lines below.

Affected areas: python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses.py

[westey (westey-m)]

Just for my own ignorance, why aren't we mapping annotated_regions anymore here?

[sophia-ramsey]

In the current code, annotated_regions refers to the information location in the source document, but downstream was being interpreted as the positions in the generated response, so I took it out so it would not be forwarded to the citation. The source locations are still in raw_representation.

[Eduard van Valkenburg (eavanvalkenburg)]

This seems strange to me as well, annotations should be about locations in source documents IIRC, and relying on raw_representation is also not ideal, since those do not survive (de)ser. I also don't know why this change is related to the Foundry Hosting, was the original issue about using Anthropic within FHA?

[sophia-ramsey]

I updated the PR to preserve the original Anthropic behavior, but I added a check for "annotated_regions_coordinate_space": "source" to indicate that the annotated_regions refer to the location in the source document instead of locations for the generated response. Does this seem like an appropriate way to handle the citations?

[Jose Alvarez (jpalvarezl)]

Approve with a small nit

[Eduard van Valkenburg (eavanvalkenburg)]

sophia-ramsey Please take a look at the inline workflow citation-offset finding.

[Eduard van Valkenburg (eavanvalkenburg)]

sophia-ramsey Completed workflow projection still calls handle_update() without completed-message handling. Adjacent independent text parts are merged while their citation offsets remain part-relative, so a citation on the second part points into the first after projection. Please enable completed-message handling for completed workflow Message, AgentResponse, ChatResponse, and message-list payloads while preserving the existing streaming path, and add workflow regressions for adjacent cited text parts.