[Eduard van Valkenburg (eavanvalkenburg)]

Motivation & Context

The Responses API can deliver grounding citations only on completed content-part or output-item events. The OpenAI integration previously discarded those annotations, leaving AG-UI applications without a supported way to render sources and forcing them to inspect log messages.

This change preserves those citations through the existing provider-neutral annotation model and transports them to AG-UI clients without replaying completed response text.

Description & Review Guide

• What are the major changes? Responses URL, file, file-path, and container-file citations are parsed into Content.annotations; AG-UI emits message-linked CUSTOM events named annotations and restores them on inbound updates; tests and package documentation cover the event contract.
• What is the impact of these changes? Applications can consume SharePoint and other Responses API citations through supported framework APIs. Existing text streaming, approval suppression, and snapshot behavior remain unchanged.
• What do you want reviewers to focus on? The request-local positional deduplication across annotation-added and completion events, and the occurrence-aware AG-UI replay handling that preserves distinct references to the same source.

Related Issue

Fixes #7460

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 is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• 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]

Copilot review overview

🟢 Approval recommended

The implementation is request-isolated, preserves existing signatures, and has strong unit and end-to-end coverage.

Review effort: Balanced
Findings: None

What changed in this PR

Preserves Responses API citations through OpenAI parsing and AG-UI transport.

Changes:

• Parses and deduplicates streaming citation annotations.
• Emits/restores message-linked AG-UI annotation events.
• Adds documentation and comprehensive replay, concurrency, and integration tests.

File	Description
python/​packages/​openai/​tests/​openai/​test_openai_chat_client.py	Tests citation parsing and deduplication.
python/​packages/​openai/​README.md	Documents citation behavior.
python/​packages/​openai/​AGENTS.md	Records parser invariants.
python/​packages/​openai/​agent_framework_openai/​_chat_client.py	Parses completed-response annotations.
python/​packages/​ag-ui/​tests/​ag_ui/​test_run.py	Tests outbound annotation events.
python/​packages/​ag-ui/​tests/​ag_ui/​test_event_converters.py	Tests inbound annotation restoration.
python/​packages/​ag-ui/​README.md	Documents the transport contract.
python/​packages/​ag-ui/​AGENTS.md	Records AG-UI annotation conventions.
python/​packages/​ag-ui/​agent_framework_ag_ui/​_run_common.py	Emits message-linked annotations.
python/​packages/​ag-ui/​agent_framework_ag_ui/​_event_converters.py	Restores inbound annotations.

---

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

[github-actions]

MAF Automated Review — Iteration 1

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

Overview

The PR adds request-local positional deduplication for Responses API citations and carries them through message-linked AG-UI custom events, with strong coverage for completion-event replay, identical occurrences, suppression, and JSON-safe transport. Two Medium contract gaps remain: annotations attached to later text chunks retain chunk-relative spans after AG-UI has concatenated earlier text, and inbound annotations targeting a non-current message do not attach to that existing message in aggregated responses.

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

Affected areas: python/packages/ag-ui/agent_framework_ag_ui/_event_converters.py, python/packages/ag-ui/agent_framework_ag_ui/_run_common.py