Python: (samples): adopt AzureOpenAIResponsesClient, reorganize orchestration examples, and fix workflow/orchestration bugs

[Evan Mattson (moonbox3)]

Motivation and Context

This PR standardizes getting-started samples on AzureOpenAIResponsesClient, restructures orchestration samples by subject, and fixes several runtime issues discovered while validating sample execution.

What changed

1) Client standardization in samples

• Updated orchestration/workflow samples to use:
  • agent_framework.azure.AzureOpenAIResponsesClient
  • azure.identity.AzureCliCredential
• Standardized deployment env var usage to:
  • AZURE_AI_MODEL_DEPLOYMENT_NAME
• Clarified sample prerequisites to explicitly call out:
  • AZURE_AI_PROJECT_ENDPOINT as an Azure AI Foundry Agent Service (V2) project endpoint

2) Sample reorganization

• Moved builder-centric workflow.as_agent(...) examples from workflows/agents into orchestrations
• Moved builder-oriented tool-approval and request-info samples into orchestration subject folders
• Reorganized orchestration samples into:
  • concurrent/
  • sequential/
  • group-chat/
  • handoff/
  • magentic/
• Updated samples/getting_started/orchestrations/README.md and samples/getting_started/workflows/README.md accordingly
• Removed workflows README links to orchestration sample paths and fixed broken README links

3) Framework/runtime fixes

• Workflow kwargs propagation
  • Fixed _agent_executor.py to correctly flatten/merge additional_function_arguments into options.additional_function_arguments (instead of nesting)
  • Preserved coexistence with workflow.run(options=...)
• Full-conversation handling
  • Fixed conversation snapshot behavior in AgentExecutor to avoid duplicate history growth
• Checkpoint reliability
  • Updated _runner.py to commit state before checkpoint creation so executor snapshots are captured
• Responses payload compatibility
  • Updated _responses_client.py assistant text formatting to satisfy Azure Responses validation requirements (output_text with annotations)
• Group chat orchestration robustness
  • Updated _group_chat.py parsing to handle structured output and concatenated JSON responses reliably

4) Sample output/UX fixes

• Reduced noisy/garbled streaming output in multiple workflow samples (simple_loop, multi_selection_edge_group, fan_out_fan_in_edges)
• Fixed invalid source_executor_id access on non-request_info events in declarative customer support sample
• Adjusted a content-filter-prone prompt pattern in agents_with_approval_requests.py
• Removed emoji-based console output from composition samples for cleaner logs

Tests / validation

• Added/updated targeted tests in:
  • packages/core/tests/workflow/test_workflow_kwargs.py
  • packages/core/tests/workflow/test_full_conversation.py
  • packages/core/tests/openai/test_openai_responses_client.py
  • packages/orchestrations/tests/test_group_chat.py
  • packages/orchestrations/tests/test_magentic.py

Notes

• Sample paths changed under samples/getting_started/orchestrations/** due to folder-based reorganization.

• FixesPython: [Bug]: Handoff_with_tool_approval_checkpoint_resume sample is failing #3859

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[Mark Wallace (markwallace-microsoft)]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework/_workflows
_agent_executor.py	172	18	89%	97, 145, 163–164, 218–219, 221–222, 260–262, 264, 268, 272, 276–277, 404, 422
_runner.py	171	2	98%	276–277
packages/core/agent_framework/openai
_responses_client.py	613	80	86%	292–295, 299–300, 303–304, 310–311, 316, 329–335, 356, 364, 387, 550, 553, 608, 612, 614, 616, 618, 694, 704, 709, 752, 811, 825, 842, 855, 911, 1004, 1009, 1013–1015, 1019–1020, 1043, 1112, 1134–1135, 1150–1151, 1169–1170, 1301–1302, 1318, 1320, 1399–1407, 1502, 1557, 1572, 1608–1609, 1611–1613, 1627–1629, 1639–1640, 1646, 1661
packages/orchestrations/agent_framework_orchestrations
_group_chat.py	328	70	78%	173, 336, 343, 372, 383–384, 390, 395, 416, 420, 433–434, 447, 462–463, 465, 481, 508–513, 515, 548–551, 553, 558–562, 650, 653, 692, 695, 698, 701, 709, 721–722, 724–725, 727–728, 730, 735, 738, 747, 753, 797–798, 802–803, 817–818, 820–821, 852–853, 919, 938, 946, 951–953, 960, 970
TOTAL	21191	3265	84%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
4079	225 💤	0 ❌	0 🔥	1m 13s ⏱️

[Copilot]

Pull request overview

This PR updates the Python getting-started experience by standardizing samples on AzureOpenAIResponsesClient (Azure AI Foundry Agent Service V2), reorganizing orchestration samples by pattern, and addressing several workflow/orchestration runtime correctness issues (kwargs propagation, full-conversation handling, checkpoint capture, Responses payload formatting, and group-chat parsing robustness).

Changes:

• Standardize workflow/orchestration samples on AzureOpenAIResponsesClient + AzureCliCredential, and align env var usage (AZURE_AI_PROJECT_ENDPOINT, AZURE_AI_MODEL_DEPLOYMENT_NAME).
• Reorganize orchestration samples into pattern-based directories and update READMEs/links accordingly.
• Fix core runtime issues (kwargs propagation/merging, full conversation snapshot duplication, checkpoint state commit timing, Responses assistant history formatting, group chat JSON parsing), with targeted regression tests.

Reviewed changes

Copilot reviewed 73 out of 73 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
python/samples/getting_started/workflows/visualization/concurrent_with_visualization.py	Switch sample client to AzureOpenAIResponsesClient and use standardized env vars.
python/samples/getting_started/workflows/state-management/workflow_kwargs.py	Update sample to Azure Responses client and add Azure CLI auth + env vars.
python/samples/getting_started/workflows/state-management/state_with_agents.py	Update agents to Azure Responses client and standard env vars.
python/samples/getting_started/workflows/parallelism/fan_out_fan_in_edges.py	Update to Azure Responses client; improve streaming output handling.
python/samples/getting_started/workflows/human-in-the-loop/guessing_game_with_human_input.py	Update to Azure Responses client and standard env vars.
python/samples/getting_started/workflows/human-in-the-loop/agents_with_declaration_only_tools.py	Update to Azure Responses client and standard env vars.
python/samples/getting_started/workflows/human-in-the-loop/agents_with_approval_requests.py	Update to Azure Responses client; adjust prompt/payload formatting.
python/samples/getting_started/workflows/human-in-the-loop/agents_with_HITL.py	Update to Azure Responses client and standard env vars.
python/samples/getting_started/workflows/declarative/student_teacher/main.py	Update declarative workflow sample to Azure Responses client + env vars.
python/samples/getting_started/workflows/declarative/marketing/main.py	Update declarative workflow sample to Azure Responses client + env vars.
python/samples/getting_started/workflows/declarative/function_tools/main.py	Update declarative function-tools sample to Azure Responses client + env vars.
python/samples/getting_started/workflows/declarative/deep_research/main.py	Update declarative deep-research sample to Azure Responses client + env vars.
python/samples/getting_started/workflows/declarative/customer_support/main.py	Update to Azure Responses client; fix source_executor_id usage for output events.
python/samples/getting_started/workflows/control-flow/switch_case_edge_group.py	Update to Azure Responses client + env vars.
python/samples/getting_started/workflows/control-flow/simple_loop.py	Update to Azure Responses client; reduce noisy streaming output.
python/samples/getting_started/workflows/control-flow/multi_selection_edge_group.py	Update to Azure Responses client; reduce streaming noise; adjust custom event emission.
python/samples/getting_started/workflows/control-flow/edge_condition.py	Update to Azure Responses client + env vars; keep file-path lint suppression.
python/samples/getting_started/workflows/composition/sub_workflow_request_interception.py	Remove emoji console output for cleaner logs.
python/samples/getting_started/workflows/composition/sub_workflow_parallel_requests.py	Remove emoji console output for cleaner logs.
python/samples/getting_started/workflows/composition/sub_workflow_kwargs.py	Update to Azure Responses client + env vars.
python/samples/getting_started/workflows/composition/sub_workflow_basics.py	Remove emoji console output for cleaner logs.
python/samples/getting_started/workflows/checkpoint/workflow_as_agent_checkpoint.py	Update to Azure Responses client + env vars.
python/samples/getting_started/workflows/checkpoint/checkpoint_with_human_in_the_loop.py	Update to Azure Responses client + env vars; simplify credential import.
python/samples/getting_started/workflows/agents/workflow_as_agent_with_thread.py	Update to Azure Responses client + env vars.
python/samples/getting_started/workflows/agents/workflow_as_agent_reflection_pattern.py	Update worker/reviewer clients to Azure Responses client + env vars.
python/samples/getting_started/workflows/agents/workflow_as_agent_kwargs.py	Update to Azure Responses client + env vars.
python/samples/getting_started/workflows/agents/workflow_as_agent_human_in_the_loop.py	Update to Azure Responses client + env vars.
python/samples/getting_started/workflows/agents/custom_agent_executors.py	Update to Azure Responses client + env vars; adjust docs accordingly.
python/samples/getting_started/workflows/agents/azure_chat_agents_tool_calls_with_feedback.py	Update to Azure Responses client + env vars.
python/samples/getting_started/workflows/agents/azure_chat_agents_streaming.py	Update to Azure Responses client + env vars.
python/samples/getting_started/workflows/agents/azure_chat_agents_and_executor.py	Update to Azure Responses client + env vars.
python/samples/getting_started/workflows/agents/azure_ai_agents_with_shared_thread.py	Replace V2 provider flow with Azure Responses client; keep shared thread example.
python/samples/getting_started/workflows/agents/azure_ai_agents_streaming.py	Replace async agent client flow with Azure Responses client + env vars.
python/samples/getting_started/workflows/_start-here/step3_streaming.py	Update start-here streaming sample to Azure Responses client + env vars.
python/samples/getting_started/workflows/_start-here/step2_agents_in_a_workflow.py	Update start-here workflow sample to Azure Responses client + env vars.
python/samples/getting_started/workflows/README.md	Update/trim links and redirect orchestration/builder-oriented samples to orchestrations set.
python/samples/getting_started/orchestrations/sequential/sequential_workflow_as_agent.py	Update to Azure Responses client + env vars.
python/samples/getting_started/orchestrations/sequential/sequential_request_info.py	Update to Azure Responses client + env vars.
python/samples/getting_started/orchestrations/sequential/sequential_custom_executors.py	Update to Azure Responses client + env vars.
python/samples/getting_started/orchestrations/sequential/sequential_builder_tool_approval.py	Update to Azure Responses client + env vars.
python/samples/getting_started/orchestrations/sequential/sequential_agents.py	Update to Azure Responses client + env vars.
python/samples/getting_started/orchestrations/magentic/magentic_workflow_as_agent.py	Update Magentic sample clients to Azure Responses client + env vars.
python/samples/getting_started/orchestrations/magentic/magentic_human_plan_review.py	Update Magentic plan review sample to Azure Responses client + env vars.
python/samples/getting_started/orchestrations/magentic/magentic_checkpoint.py	Update Magentic checkpoint sample to Azure Responses client + env vars; fix credential import.
python/samples/getting_started/orchestrations/magentic/magentic.py	Update Magentic sample to Azure Responses client + env vars.
python/samples/getting_started/orchestrations/handoff_with_code_interpreter_file.py	Remove old top-level handoff CI sample (moved under handoff/).
python/samples/getting_started/orchestrations/handoff/handoff_workflow_as_agent.py	Update to Azure Responses client + env vars.
python/samples/getting_started/orchestrations/handoff/handoff_with_tool_approval_checkpoint_resume.py	Update to Azure Responses client + env vars.
python/samples/getting_started/orchestrations/handoff/handoff_with_code_interpreter_file.py	Add/move CI file-ID retrieval handoff sample under handoff/ and update to Azure Responses client.
python/samples/getting_started/orchestrations/handoff/handoff_simple.py	Update to Azure Responses client + env vars.
python/samples/getting_started/orchestrations/handoff/handoff_autonomous.py	Update to Azure Responses client + env vars.
python/samples/getting_started/orchestrations/group-chat/group_chat_workflow_as_agent.py	Update group chat orchestration-as-agent to Azure Responses client + env vars.
python/samples/getting_started/orchestrations/group-chat/group_chat_simple_selector.py	Update to Azure Responses client + env vars.
python/samples/getting_started/orchestrations/group-chat/group_chat_request_info.py	Update to Azure Responses client + env vars.
python/samples/getting_started/orchestrations/group-chat/group_chat_philosophical_debate.py	Update to Azure Responses client + env vars; improve streaming speaker formatting.
python/samples/getting_started/orchestrations/group-chat/group_chat_builder_tool_approval.py	Update tool-approval sample to Azure Responses client + env vars.
python/samples/getting_started/orchestrations/group-chat/group_chat_agent_manager.py	Update to Azure Responses client + env vars; improve streaming speaker formatting.
python/samples/getting_started/orchestrations/concurrent/concurrent_workflow_as_agent.py	Update to Azure Responses client + env vars.
python/samples/getting_started/orchestrations/concurrent/concurrent_request_info.py	Update to Azure Responses client + env vars.
python/samples/getting_started/orchestrations/concurrent/concurrent_custom_aggregator.py	Update to Azure Responses client + env vars; formatting cleanup.
python/samples/getting_started/orchestrations/concurrent/concurrent_custom_agent_executors.py	Update to Azure Responses client + env vars.
python/samples/getting_started/orchestrations/concurrent/concurrent_builder_tool_approval.py	Update tool-approval sample to Azure Responses client + env vars.
python/samples/getting_started/orchestrations/concurrent/concurrent_agents.py	Update to Azure Responses client + env vars.
python/samples/getting_started/orchestrations/README.md	Restructure orchestration README by directory and update paths.
python/packages/orchestrations/tests/test_magentic.py	Add regression coverage for checkpoint state capture; fix run() checkpoint_id usage.
python/packages/orchestrations/tests/test_group_chat.py	Add regression test for concatenated JSON manager outputs.
python/packages/orchestrations/agent_framework_orchestrations/_group_chat.py	Improve manager output parsing (structured value, JSON text, concatenated JSON).
python/packages/core/tests/workflow/test_workflow_kwargs.py	Add tests ensuring options/kwargs merging and flattening behavior is correct.
python/packages/core/tests/workflow/test_full_conversation.py	Add round-trip regression test preventing full-conversation duplication.
python/packages/core/tests/openai/test_openai_responses_client.py	Add tests enforcing role-specific text content item types and required annotations.
python/packages/core/agent_framework/openai/_responses_client.py	Ensure assistant history uses output_text with annotations to satisfy Azure validation.
python/packages/core/agent_framework/_workflows/_runner.py	Commit staged state before checkpoint creation to capture executor snapshots reliably.
python/packages/core/agent_framework/_workflows/_agent_executor.py	Fix conversation snapshot behavior and correctly merge workflow kwargs into agent options.