[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

[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.