Python: Normalize chat finish reasons

[eavanvalkenburg]

Motivation & Context

Responses-based clients and several other Python integrations either dropped terminal finish metadata or exposed incompatible provider-native values. This restores consistent finish-reason propagation and avoids incorrectly reporting generic AG-UI errors as content filtering.

Description & Review Guide

• What are the major changes? Normalize documented provider finish reasons, preserve unknown provider strings, populate the OpenAI Responses API terminal reason, and guard OTel output serialization against non-canonical values.
• What is the impact of these changes? Consumers can distinguish normal stops, length limits, tool calls, and content filtering across supported clients without losing provider-specific terminal information.
• What do you want reviewers to focus on? @moonbox3, please double-check the AG-UI RUN_ERROR change: generic run errors now leave finish_reason unset rather than being labeled content_filter.

Related Issue

Fixes #7025
Fixes #7051
Fixes #4622

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.

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/ag-ui/agent_framework_ag_ui
_event_converters.py	110	1	99%	169
packages/bedrock/agent_framework_bedrock
_chat_client.py	449	96	78%	305–306, 322–331, 337, 405, 414, 425, 427, 429, 434, 453–454, 478, 491, 503, 506, 514–515, 518–519, 521–522, 527–529, 531, 541–542, 564, 571, 580–581, 583–584, 586–588, 590, 592–593, 599–601, 604–605, 611–614, 620–630, 633, 652, 657, 723, 749, 761, 766, 794, 798–799, 802, 820, 844, 856, 860, 874, 882–883, 887, 889–896
packages/claude/agent_framework_claude
_agent.py	328	28	91%	417–418, 422, 434, 442–444, 446–447, 477–479, 498, 502, 504, 508, 517, 563, 566, 606, 611–612, 686, 772, 798–801
packages/core/agent_framework
observability.py	1012	80	92%	421, 423–424, 427, 430, 433–434, 439–440, 446–447, 453–454, 461, 463–464, 467, 470, 473–474, 479–480, 486–487, 493–494, 501, 678–679, 889, 893–895, 897, 905–906, 910, 954, 956, 967–969, 971–973, 977, 985, 1109–1110, 1345, 1628–1629, 1740, 1890, 1933–1934, 2123, 2351–2352, 2356, 2396–2397, 2401, 2443–2446, 2487–2488, 2639, 2642, 2654, 2671, 2675–2676, 2679, 2685, 2805, 3022, 3024
packages/github_copilot/agent_framework_github_copilot
_agent.py	420	21	95%	61–62, 104, 113–115, 119, 538, 553–554, 633, 646, 780, 784, 936–937, 976, 979, 1102, 1125, 1170
packages/ollama/agent_framework_ollama
_chat_client.py	227	9	96%	399, 401, 412, 416–417, 432, 443, 522, 548
packages/openai/agent_framework_openai
_chat_client.py	1292	127	90%	308, 321, 671–675, 683–686, 692–696, 746–753, 755–757, 764–766, 824, 832, 855, 973, 1072, 1131, 1133, 1135, 1137, 1203, 1217, 1297, 1307, 1312, 1355, 1466–1467, 1482, 1706, 1711, 1715–1717, 1721–1722, 1805, 1815, 1842, 1848, 1858, 1864, 1869, 1875, 1880–1881, 1961, 2005, 2008–2011, 2025, 2027, 2035–2036, 2048, 2090, 2155, 2172, 2175, 2202–2204, 2243, 2260, 2263, 2325, 2332, 2369–2370, 2405, 2443–2444, 2462–2463, 2506, 2633–2634, 2652, 2738–2746, 2776, 2922, 2937, 2986–2989, 2999–3001, 3028–3030, 3040–3041, 3047, 3062, 3184–3185
_chat_completion_client.py	373	18	95%	440, 536–537, 541, 782, 784, 789, 792, 883, 885, 902, 923, 931, 955, 968, 992, 1012, 1327
TOTAL	44478	5237	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
8997	33 💤	0 ❌	0 🔥	2m 26s ⏱️

[github-actions]

Automated Code Review

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

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

---

Automated review by eavanvalkenburg's agents

[Copilot]

Pull request overview

This PR standardizes how Python integrations populate and propagate terminal finish_reason values across providers/clients, ensuring consumers can reliably distinguish normal stops, length truncation, tool calls, and content filtering while avoiding telemetry serialization issues for non-canonical values.

Changes:

• Adds Responses-API finish-reason mapping for OpenAIChatClient (non-streaming + streaming) and corresponding unit tests.
• Normalizes and/or preserves provider finish reason strings across several clients (Chat Completions function-call mapping; Ollama/Claude/Bedrock/Copilot adjustments).
• Updates OTel message capture to only emit canonical finish reasons, and updates AG-UI RUN_ERROR handling to leave finish_reason unset.

Reviewed changes

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

Show a summary per file

File	Description
python/packages/openai/tests/openai/test_openai_chat_client.py	Adds unit tests covering Responses API status/incomplete-details → finish_reason mapping (streaming + non-streaming).
python/packages/openai/agent_framework_openai/_chat_completion_client.py	Normalizes Chat Completions finish_reason "function_call" → "tool_calls".
python/packages/openai/agent_framework_openai/_chat_client.py	Implements finish-reason mapping for Responses API terminal states and wires it into parsing.
python/packages/ollama/tests/test_ollama_chat_client.py	Updates test to expect unknown provider finish reasons to be preserved.
python/packages/ollama/agent_framework_ollama/_chat_client.py	Preserves unknown done_reason values (and maps tool-call presence to "tool_calls").
python/packages/github_copilot/tests/test_github_copilot_agent.py	Updates expectations for content-filter-triggered usage and preservation of provider-specific finish reasons.
python/packages/github_copilot/agent_framework_github_copilot/_agent.py	Adjusts how Copilot usage events map content_filter_triggered and finish_reason.
python/packages/core/agent_framework/observability.py	Guards OTel output-message finish-reason mapping to avoid non-canonical values causing issues.
python/packages/claude/tests/test_claude_agent.py	Updates tests to expect normalized Claude stop reasons (stop/length).
python/packages/claude/agent_framework_claude/_agent.py	Introduces a Claude stop-reason → framework finish-reason normalization map (while preserving unknowns).
python/packages/bedrock/tests/test_bedrock_settings.py	Adds coverage for Bedrock guardrail intervention mapping to content_filter.
python/packages/bedrock/agent_framework_bedrock/_chat_client.py	Maps guardrail_intervened → content_filter and preserves unknown finish-reason strings.
python/packages/ag-ui/tests/ag_ui/test_event_converters.py	Updates RUN_ERROR test expectation to leave finish_reason unset.
python/packages/ag-ui/agent_framework_ag_ui/_event_converters.py	Stops labeling generic RUN_ERROR events as content_filter.