Python: [BREAKING] Standardize orchestration terminal outputs as AgentResponse (#5301)

* Fix orchestration outputs so as_agent() returns the final answer only. Align other orchestration outputs

* Fix orchestration output issues from review comments

1. Sample cleanup: Remove commented-out FoundryChatClient block and update
   prerequisites to reference OPENAI_CHAT_MODEL_ID instead of FOUNDRY_* vars.

2. Sequential approval output: Change _EndWithConversation.end_with_agent_executor_response
   from a no-op sink to yield response.agent_response. When the last participant is
   AgentApprovalExecutor (via with_request_info), _EndWithConversation is the output
   executor so the yield produces the terminal answer. When the last participant is a
   regular AgentExecutor, _EndWithConversation is not in output_executors so the yield
   is silently filtered out.

3. Forward data events through WorkflowExecutor: _process_workflow_result now also
   forwards 'data' events from sub-workflows so that emit_intermediate_data=True on
   AgentExecutor works correctly when wrapped in AgentApprovalExecutor.

4. Concurrent docstring: Update _AggregateAgentConversations docstring to say
   'deterministic participant order' instead of 'completion order'.

5. Add test_concurrent_intermediate_outputs_emits_data_events verifying that
   ConcurrentBuilder(intermediate_outputs=True) emits per-participant data events
   alongside the single aggregated output event.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Add tests for sequential workflow with_request_info and intermediate_outputs (#5301)

Address PR review comments 2, 3, and 5:

- Add test_sequential_request_info_last_participant_emits_output:
  Verifies that when the last participant is wrapped via with_request_info()
  (AgentApprovalExecutor), the workflow still emits a terminal output after
  approval, exercising the _EndWithConversation.end_with_agent_executor_response
  fallback path.

- Add test_sequential_request_info_with_intermediate_outputs_emits_data_events:
  Verifies that emit_intermediate_data=True works correctly through
  AgentApprovalExecutor wrapping—WorkflowExecutor._process_result already
  forwards data events from sub-workflows, so intermediate agent responses
  surface as data events in the parent workflow.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix pyright type errors from AgentResponse output refactor (#5301)

Update cast() calls in _group_chat.py and _magentic.py to use
WorkflowContext[Never, AgentResponse] instead of the old
WorkflowContext[Never, list[Message]], matching the updated method
signatures in _base_group_chat_orchestrator.py.

Fix _sequential.py _EndWithConversation.end_with_agent_executor_response
to declare WorkflowContext[Any, AgentResponse] so yield_output accepts
AgentResponse[None].

Fix _workflow_executor.py data event forwarding to handle nullable
executor_id.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix pyright reportUnknownVariableType in _agent.py (#5301)

Extract event.data into a typed local variable before the isinstance
check to avoid pyright narrowing it to AgentResponse[Unknown].

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix pyright reportMissingImports for orjson in file history samples (#5301)

Add pyright: ignore[reportMissingImports] to orjson imports that are
already guarded by try/except ImportError, matching the existing pattern
used elsewhere in the samples.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Address review feedback for #5301: review comment fixes

* Address review feedback for #5301: review comment fixes

* Revert sequential_workflow_as_agent sample to FoundryChatClient

Reverts the mistaken switch from FoundryChatClient to OpenAIChatClient
in the sequential workflow as agent sample.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Address ultrareview feedback: emit_data_events rename + WorkflowAgent reasoning conversion

Layered on top of the prior review-feedback work in this branch.

Renames:
- AgentExecutor.emit_intermediate_data -> emit_data_events (mechanical
  rename; orchestration semantics live at the orchestration layer, not
  the general-purpose executor). Forwarded through MagenticAgentExecutor,
  AgentApprovalExecutor, and all orchestration call sites.
- HandoffAgentExecutor._check_terminate_and_yield -> _should_terminate
  (pure predicate; no longer yields anything). HandoffBuilder docstring
  rewritten to describe the new per-agent AgentResponse output contract.

WorkflowAgent reasoning-content conversion:
- Add _rewrite_text_to_reasoning(contents) and _msg_as_reasoning(msg)
  helpers; the as_agent() path now reframes text content from data events
  as text_reasoning Content blocks before merging into the AgentResponse.
- Consumers iterate msg.contents and branch on content.type — same path
  they already use for Claude thinking and OpenAI reasoning. No new
  field on Message/AgentResponse/WorkflowEvent.
- Streaming branch constructs fresh AgentResponseUpdate instances instead
  of mutating shared payloads (regression test added).
- Helper _msg_maybe_reasoning consolidates the conditional rewrite at
  three call sites in the non-streaming conversion.

Tests:
- TestWorkflowAgentReasoningHelpers + TestWorkflowAgentDataEventReasoningConversion
  add 9 new tests covering helpers, non-streaming, streaming, mixed content,
  already-reasoning passthrough, and mutation-safety regression.
- Updated test_sequential_as_agent_with_intermediate_outputs_includes_chain
  to assert text_reasoning content for intermediate agents.

* Fix pyright: widen event.data to Any to avoid partial-unknown narrowing

The streaming conversion path narrowed event.data via isinstance against
generic AgentResponse, producing AgentResponse[Unknown] and tripping
reportUnknownVariableType/reportUnknownMemberType. Binding data: Any
before the check keeps runtime behavior identical while restoring a fully
known type for downstream access.

* Clean up design

* Scope to agent output semantics only

* yield AgentResponseUpdate streaming, AgentResponse non-streaming

* Fix mypy/pyright: widen cast types at GroupChat callsites

Eight callsites in _group_chat.py still cast to WorkflowContext[Never,
AgentResponse] but the base orchestrator methods now accept the wider
WorkflowContext[Never, AgentResponse | AgentResponseUpdate] (mode-aware
yields). W_OutT is invariant, so the narrower cast is not assignable.
Magentic was widened in the same commit; this catches the GroupChat
callsites that were missed.

* Python: skip flaky Foundry / Foundry Hosting integration tests (#5553)

These two integration tests have been failing in the merge queue across
multiple unrelated PRs (5301, 5531). Both are marked `@pytest.mark.flaky`
with 3 retries, but all attempts fail back-to-back. Skipping both with a
reason pointing to #5553 so they can be fixed properly without continuing
to block unrelated merges.

- packages/foundry_hosting/tests/test_responses_int.py::TestOptions::test_temperature_and_max_tokens
- packages/foundry/tests/foundry/test_foundry_embedding_client.py::TestFoundryEmbeddingIntegration::test_text_embedding_live

Also includes a one-line uv.lock specifier-ordering normalization
auto-applied by the poe-check pre-commit hook.

---------

Co-authored-by: Copilot <copilot@github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

python/packages/orchestrations/tests/test_magentic.py

@@ -190,24 +190,82 @@ async def test_magentic_builder_returns_workflow_and_runs() -> None:
 
     assert isinstance(workflow, Workflow)
 
-    outputs: list[Message] = []
+    updates: list[AgentResponseUpdate] = []
     orchestrator_event_count = 0
     async for event in workflow.run("compose summary", stream=True):
-        if event.type == "output":
-            msg = event.data
-            if isinstance(msg, list):
-                outputs.extend(cast(list[Message], msg))
+        if event.type == "output" and isinstance(event.data, AgentResponseUpdate):
+            updates.append(event.data)
         elif event.type == "magentic_orchestrator":
             orchestrator_event_count += 1
 
-    assert outputs, "Expected a final output message"
-    assert len(outputs) >= 1
-    final = outputs[-1]
+    assert updates, "Expected a final output update"
+    final = updates[-1]
     assert final.text == manager.FINAL_ANSWER
     assert final.author_name == manager.name
     assert orchestrator_event_count > 0, "Expected orchestrator events to be emitted"
 
 
+async def test_magentic_final_answer_yields_update_in_streaming() -> None:
+    """In streaming mode, Magentic's manager final-answer surfaces as `AgentResponseUpdate`.
+
+    Mirrors AgentExecutor's mode-aware behavior: streaming workflows produce per-chunk
+    `AgentResponseUpdate` events; the synthesized final answer is logically a single chunk,
+    so it surfaces as a single `AgentResponseUpdate`.
+    """
+    manager = FakeManager()
+    workflow = MagenticBuilder(
+        participants=[StubAgent(manager.next_speaker_name, "first draft")],
+        manager=manager,
+    ).build()
+
+    terminal: AgentResponseUpdate | None = None
+    async for event in workflow.run("compose summary", stream=True):
+        if event.type == "output":
+            terminal = event.data
+
+    assert isinstance(terminal, AgentResponseUpdate), (
+        f"Expected AgentResponseUpdate in streaming mode, got {type(terminal).__name__}"
+    )
+    assert terminal.text == manager.FINAL_ANSWER
+    assert terminal.author_name == manager.name
+
+
+async def test_magentic_final_answer_yields_response_in_non_streaming() -> None:
+    """In non-streaming mode, Magentic's manager final-answer surfaces as `AgentResponse`."""
+    manager = FakeManager()
+    workflow = MagenticBuilder(
+        participants=[StubAgent(manager.next_speaker_name, "first draft")],
+        manager=manager,
+    ).build()
+
+    events = await workflow.run("compose summary")
+    outputs = [ev for ev in events if ev.type == "output"]
+    assert len(outputs) == 1
+    assert isinstance(outputs[0].data, AgentResponse)
+    assert outputs[0].data.messages[-1].text == manager.FINAL_ANSWER
+
+
+async def test_magentic_limit_termination_yields_update_in_streaming() -> None:
+    """In streaming mode, Magentic's round-limit termination surfaces as `AgentResponseUpdate`."""
+    manager = FakeManager(max_round_count=1)
+    workflow = MagenticBuilder(
+        participants=[DummyExec(name=manager.next_speaker_name)],
+        manager=manager,
+    ).build()
+
+    terminal: AgentResponseUpdate | None = None
+    async for event in workflow.run("round limit test", stream=True):
+        if event.type == "output":
+            terminal = event.data
+
+    assert isinstance(terminal, AgentResponseUpdate), (
+        f"Expected AgentResponseUpdate in streaming mode, got {type(terminal).__name__}"
+    )
+    # Either the final answer OR the round-limit termination message — both are valid terminal states
+    # for max_round_count=1; the precise one depends on FakeManager's progression.
+    assert terminal.text
+
+
 async def test_magentic_as_agent_does_not_accept_conversation() -> None:
     manager = FakeManager()
     writer = StubAgent(manager.next_speaker_name, "summary response")
@@ -250,7 +308,7 @@ async def test_magentic_workflow_plan_review_approval_to_completion():
     assert isinstance(req_event.data, MagenticPlanReviewRequest)
 
     completed = False
-    output: list[Message] | None = None
+    output: AgentResponseUpdate | None = None
     async for ev in wf.run(stream=True, responses={req_event.request_id: req_event.data.approve()}):
         if ev.type == "status" and ev.state == WorkflowRunState.IDLE:
             completed = True
@@ -261,8 +319,8 @@ async def test_magentic_workflow_plan_review_approval_to_completion():
 
     assert completed
     assert output is not None
-    assert isinstance(output, list)
-    assert all(isinstance(msg, Message) for msg in output)
+    # Streaming mode: terminal output is AgentResponseUpdate.
+    assert isinstance(output, AgentResponseUpdate)
 
 
 async def test_magentic_plan_review_with_revise():
@@ -333,14 +391,12 @@ async def test_magentic_orchestrator_round_limit_produces_partial_result():
         None,
     )
     assert idle_status is not None
-    # Check that we got workflow output via WorkflowEvent with type "output"
+    # Streaming mode: terminal output is AgentResponseUpdate.
     output_event = next((e for e in events if e.type == "output"), None)
     assert output_event is not None
     data = output_event.data
-    assert isinstance(data, list)
-    assert len(data) > 0  # type: ignore
-    assert data[-1].role == "assistant"  # type: ignore
-    assert all(isinstance(msg, Message) for msg in data)  # type: ignore
+    assert isinstance(data, AgentResponseUpdate)
+    assert data.role == "assistant"
 
 
 async def test_magentic_checkpoint_resume_round_trip():
@@ -578,7 +634,7 @@ async def _collect_agent_responses_setup(participant: SupportsAgentRun) -> list[
 
     # Run a bounded stream to allow one invoke and then completion
     events: list[WorkflowEvent] = []
-    async for ev in wf.run("task", stream=True):  # plan review disabled
+    async for ev in wf.run("task", stream=True):
         events.append(ev)
         # Capture streaming updates (type="output" with AgentResponseUpdate data)
         if ev.type == "output" and isinstance(ev.data, AgentResponseUpdate):
@@ -753,11 +809,9 @@ async def test_magentic_stall_and_reset_reach_limits():
     assert idle_status is not None
     output_event = next((e for e in events if e.type == "output"), None)
     assert output_event is not None
-    assert isinstance(output_event.data, list)
-    assert all(isinstance(msg, Message) for msg in output_event.data)  # type: ignore
-    assert len(output_event.data) > 0  # type: ignore
-    assert output_event.data[-1].text is not None  # type: ignore
-    assert output_event.data[-1].text == "Workflow terminated due to reaching maximum reset count."  # type: ignore
+    # Streaming mode: terminal output is AgentResponseUpdate.
+    assert isinstance(output_event.data, AgentResponseUpdate)
+    assert output_event.data.text == "Workflow terminated due to reaching maximum reset count."
 
 
 async def test_magentic_checkpoint_runtime_only() -> None: