Python: Fix AG-UI conversation correlation across runs

[moonbox3]

Motivation & Context

AG-UI clients use one stable thread identifier for a conversation and a new run identifier for each interaction. The Python agent adapter could replace those request identifiers with conversation or response identifiers returned by the chat provider. With FoundryChatClient, this split turns from one AG-UI thread across separate Foundry trace conversations and could key thread snapshots by a provider identifier instead of the AG-UI thread.

This change keeps protocol lifecycle identity separate from provider-side continuation identity and adds a complete single-agent sample that demonstrates multi-turn FoundryChatClient usage with trace correlation.

Description & Review Guide

• What are the major changes? Preserve request threadId and runId as the authoritative AG-UI lifecycle identifiers, while retaining provider identifiers as fallbacks and for provider-side continuation. Propagate the stable AG-UI thread through agent and workflow telemetry, including async stream pulls, and add regression coverage for snapshots and spans. Add a FoundryChatClient FastAPI and React sample with stable thread IDs, per-turn run IDs, snapshot storage, and optional Azure Monitor setup.
• What is the impact of these changes? Multi-turn interactions remain grouped under one gen_ai.conversation.id in traces, while each run keeps its own trace. Existing callers that omit AG-UI identifiers retain provider-ID fallback behavior. This is not a breaking API or protocol change.
• What do you want reviewers to focus on? The separation between AG-UI lifecycle identifiers and provider continuation identifiers, cleanup of the scoped telemetry context across normal and exceptional stream completion, and the sample's stable-thread/new-run behavior.

Related Issue

Fixes #7429

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 the title prefix in sync automatically.

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/ag-ui/agent_framework_ag_ui
_agent_run.py	1156	118	89%	189–196, 243–244, 251, 360, 364, 366, 383, 410–411, 524, 538, 542, 546, 549, 554, 559, 568, 571, 578–584, 617, 629, 640, 643, 678, 732–736, 801, 816, 819, 821, 847, 873–875, 933, 935, 937, 940–944, 958, 966–971, 980–981, 1030–1033, 1044, 1052, 1084, 1099, 1113, 1125, 1155, 1159, 1162, 1164, 1204–1206, 1270, 1276–1277, 1282, 1286–1287, 1485, 1493, 1523, 1527, 1572, 1631, 1661–1662, 1784, 1932, 1991, 2008, 2028–2029, 2036, 2157, 2185, 2193, 2195, 2198, 2204, 2259, 2262, 2272–2273, 2280, 2326
_run_common.py	578	47	91%	100, 163–164, 166, 168, 171, 177, 179, 193, 200, 224–225, 238, 257, 259, 293, 337, 349, 351, 353, 356–360, 769–770, 776–781, 1089–1090, 1095, 1097–1099, 1108, 1116, 1128, 1130–1133, 1196
_workflow_run.py	691	73	89%	83, 97, 99, 101, 104, 231–234, 283, 294, 299, 324, 360–363, 391, 396, 424, 434, 445, 450, 453, 466, 476, 479, 484, 487, 502–504, 509, 511–512, 516, 518, 535, 541–542, 552–553, 557–558, 582–583, 616, 624, 693, 713, 729, 744, 846–860, 892–893, 917–918, 993, 1055
packages/core/agent_framework
observability.py	1027	80	92%	448, 450–451, 454, 457, 460–461, 466–467, 473–474, 480–481, 488, 490–491, 494, 497, 500–501, 506–507, 513–514, 520–521, 528, 705–706, 916, 920–922, 924, 932–933, 937, 981, 983, 994–996, 998–1000, 1004, 1012, 1136–1137, 1372, 1655–1656, 1767, 1919, 1962–1963, 2152, 2380–2381, 2385, 2425–2426, 2430, 2471–2474, 2515–2516, 2667, 2670, 2682, 2699, 2703–2704, 2707, 2713, 2833, 3054, 3056
TOTAL	46149	4479	90%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
9550	34 💤	0 ❌	0 🔥	2m 31s ⏱️

[Copilot]

Pull request overview

This PR fixes AG-UI trace/snapshot correlation in the Python adapter by keeping client-supplied threadId/runId as the authoritative lifecycle identifiers, while introducing a scoped OpenTelemetry conversation override so spans can still correlate across runs. It also adds an end-to-end single-agent AG-UI sample (FastAPI backend + React frontend) demonstrating stable thread IDs and per-turn run IDs.

Changes:

• Add a scoped, application-managed OTel conversation-id override and apply it from AG-UI agent/workflow streaming paths so gen_ai.conversation.id can remain stable across runs.
• Update AG-UI adapter logic so provider conversation_id / response_id only become fallbacks when the request omitted threadId / runId.
• Add a complete single-agent sample app (backend + frontend) plus regression tests validating snapshot keying and span correlation.

Reviewed changes

Copilot reviewed 18 out of 20 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
python/packages/core/agent_framework/observability.py	Introduces scoped conversation-id override and applies it to agent/workflow span attributes.
python/packages/core/tests/core/test_observability.py	Adds unit tests validating override scoping and workflow span behavior.
python/packages/ag-ui/agent_framework_ag_ui/_run_common.py	Adds helper to iterate async streams while re-establishing execution context per pull.
python/packages/ag-ui/agent_framework_ag_ui/_agent_run.py	Preserves supplied AG-UI IDs, scopes telemetry override across stream construction and pulls, and keeps provider IDs as fallbacks.
python/packages/ag-ui/agent_framework_ag_ui/_workflow_run.py	Applies telemetry override and iterates workflow stream with per-pull context.
python/packages/ag-ui/tests/ag_ui/test_endpoint.py	Adds regression tests ensuring snapshots and spans correlate to supplied thread_id.
python/packages/ag-ui/tests/ag_ui/test_workflow_run.py	Adds regression test ensuring workflow + nested agent spans use supplied thread_id.
python/samples/05-end-to-end/ag_ui_single_agent/README.md	Documents the new single-agent demo, expected flow, and trace correlation behavior.
python/samples/05-end-to-end/ag_ui_single_agent/backend/server.py	Adds FastAPI backend hosting a Foundry-backed Agent via the AG-UI endpoint with snapshot storage.
python/samples/05-end-to-end/ag_ui_single_agent/frontend/package.json	Adds React/Vite frontend package definition for the demo.
python/samples/05-end-to-end/ag_ui_single_agent/frontend/package-lock.json	Locks frontend dependencies for the demo.
python/samples/05-end-to-end/ag_ui_single_agent/frontend/vite.config.ts	Vite dev server config for the demo frontend.
python/samples/05-end-to-end/ag_ui_single_agent/frontend/tsconfig.json	Frontend TS config for app sources.
python/samples/05-end-to-end/ag_ui_single_agent/frontend/tsconfig.node.json	Frontend TS config for Vite/node-side config compilation.
python/samples/05-end-to-end/ag_ui_single_agent/frontend/index.html	Frontend HTML entrypoint.
python/samples/05-end-to-end/ag_ui_single_agent/frontend/.gitignore	Ignores node_modules and build artifacts for the demo frontend.
python/samples/05-end-to-end/ag_ui_single_agent/frontend/src/vite-env.d.ts	Vite client type reference for TS.
python/samples/05-end-to-end/ag_ui_single_agent/frontend/src/main.tsx	React entrypoint wiring the App and CSS.
python/samples/05-end-to-end/ag_ui_single_agent/frontend/src/styles.css	Styling for the demo chat UI.
python/samples/05-end-to-end/ag_ui_single_agent/frontend/src/App.tsx	Implements AG-UI SSE streaming client with stable thread IDs and per-run IDs.

Files not reviewed (1)

• python/samples/05-end-to-end/ag_ui_single_agent/frontend/package-lock.json: Generated file

[github-actions]

Automated Code Review

Reviewers: 4 | Confidence: 31% | Result: All clear

Reviewed: Security Reliability, Test Coverage, Failure Modes, Design Approach

---

Automated review by moonbox3's agents

[github-actions]

Automated Code Review

Reviewers: 5 | Confidence: 48% | Result: All clear

Reviewed: Correctness, Security Reliability, Test Coverage, Failure Modes, Design Approach

---

Automated review by moonbox3's agents

[moonbox3]

/review

[github-actions]

Automated Code Review

Reviewers: 4 | Confidence: 39% | Result: All clear

Reviewed: Security Reliability, Test Coverage, Failure Modes, Design Approach

---

Automated review by moonbox3's agents