.NET: Preserve streamed annotations in Foundry hosted responses

[Roger Barreto (rogerbarreto)]

Motivation & Context

Foundry hosted agents can receive citation annotations separately from streamed text updates. The OpenAI Responses adapter surfaces the completed annotation set in an annotation-only AIContent, but OutputConverter only collected annotations attached directly to TextContent. Hosted clients therefore received citation markers without response.output_text.annotation.added events or annotation metadata in completed payloads.

Description & Review Guide

• What are the major changes? Collect annotations from matching annotation-only content, preserve annotations attached directly to text, suppress duplicates, and map URL, file, file path, and container file citations to AgentServer response annotations. Add converter, handler, HTTP endpoint, and live Foundry integration coverage for streaming and non-streaming responses.
• What is the impact of these changes? Azure AI Search and hosted web search citations now reach hosted Responses API clients as annotation events and remain present in completed content and response payloads.
• What do you want reviewers to focus on? Please review message correlation for late annotation updates, citation mapping and duplicate suppression, plus the live Hosted Web Search and Azure AI Search integration scenarios.

Related Issue

Fixes #6926

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]

Pull request overview

Preserves Foundry citation annotations across streaming and completed Responses payloads.

Changes:

• Correlates annotation-only updates and deduplicates citations.
• Maps URL, file, path, and container citations.
• Adds unit, HTTP, and hosted integration coverage.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
OutputConverter.cs	Preserves and maps annotations.
OutputConverterTests.cs	Tests conversion and deduplication.
AgentFrameworkResponseHandlerTests.cs	Tests handler propagation.
HostedAnnotationsTests.cs	Tests HTTP response serialization.
Microsoft.Agents.AI.Foundry.Hosting.UnitTests.csproj	Adds SSE parser dependency.
WebSearchAnnotationsHostedAgentTests.cs	Tests hosted web citations.
AzureSearchToolAnnotationsHostedAgentTests.cs	Tests Search citations.
WebSearchAnnotationsHostedAgentFixture.cs	Configures web-search scenario.
AzureSearchToolAnnotationsHostedAgentFixture.cs	Configures Search scenario.
Program.cs	Adds annotation test agents.
TestSettings.cs	Adds Search connection settings.
it-bootstrap-agents.ps1	Bootstraps new scenarios.
README.md	Documents setup and RBAC.

---

💡 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)): 8690a70c5e0d
Model: gpt-5.6-sol

Overview

The change correlates late annotation-only content with an open streamed message, maps the supported citation shapes, suppresses exact duplicates, and emits annotations in the required completion order. Unit, handler, HTTP, and live integration coverage exercise the principal Foundry paths and reject mismatched IDs. One provider-compatibility gap remains for valid streams where message IDs are absent throughout.

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

Affected areas: dotnet/src/Microsoft.Agents.AI.Foundry.Hosting/OutputConverter.cs

[github-actions]

MAF Automated Review — Iteration 2

Result: No findings
Scope: 1 net-new commit(s): ea91a4e61a86
Model: gpt-5.6-sol

Overview

This incremental update strengthens late-annotation correlation by resolving message IDs from the underlying OpenAI streaming events while retaining guards against attaching unknown annotations to a known open message. Focused converter, handler, HTTP, and live integration coverage exercises missing IDs, mismatched IDs, duplicate citations, supported citation shapes, event ordering, and final payload preservation. No publishable Critical, High, or Medium defect is established on a changed line in the authoritative incremental range.

Reviewed the supplied incremental change set across correctness, security/reliability, architecture, and failure behavior.
No publishable findings remained after source verification for this scope.