11 Commits

• Python: Improve the handling of intermediate outputs for workflows and orchestrations (#5623)

  * Improve the handling of intermediate outputs for workflows and orchestrations
  
  * Address PR review feedback on intermediate output forwarding
  
  - Switch workflow.as_agent() forwarding to an explicit allowlist of {output,
    intermediate, data, request_info} so orchestration-internal events
    (group_chat, handoff_sent, magentic_orchestrator) stay inside the workflow
    instead of leaking into agent responses via str(data) coercion.
  - Stop raising on intermediate AgentResponseUpdate in non-streaming run();
    surface the partial as a Message with text_reasoning content. The defensive
    raise still applies to terminal output events, where Update payloads would
    corrupt message ordering.
  - Extend the DevUI workflow-event mapper so intermediate yields wrapping
    plain strings, Messages, and list[Message] render as visible output items
    instead of generic completed-trace events.
  - Add orchestration coverage for GroupChat, Handoff, and Magentic builders
    (default vs intermediate_outputs=True; structural where end-to-end is heavy).
  
  * Lift output-designation policy into a value type
  
  Replace the ``Workflow._output_executors`` list and the
  ``RunnerContext.should_label_as_intermediate`` Protocol method with a single
  immutable ``OutputDesignation`` value type owned by ``Workflow``. Thread the
  designation as a parameter through the existing call chain (Runner ->
  EdgeRunner -> Executor -> WorkflowContext) so ``yield_output`` consults the
  threaded snapshot directly rather than calling back into the runner context.
  
  Removes the ``InProcRunnerContext._workflow`` back-reference and the
  ``WorkflowBuilder.build()`` assignment that wired it up. Adds the public
  predicate ``Workflow.is_terminal_executor(executor_id)`` for external
  observers; ``OutputDesignation`` itself stays package-internal.
  
  Key decisions
  - ``OutputDesignation.designated`` is ``frozenset[str] | None`` -- ``None``
    preserves legacy "every yield is type='output'" behavior, any frozenset
    (including empty) opts into strict mode. The ``DeprecationWarning`` for
    legacy mode at build time is unchanged.
  - ``output_designation`` is an optional parameter on ``Runner``,
    ``EdgeRunner.send_message``, ``EdgeRunner._execute_on_target``,
    ``Executor.execute``, ``Executor._create_context_for_handler``, and
    ``WorkflowContext.__init__``. Each defaults to legacy ``OutputDesignation()``
    so direct callers (Azure Functions ``CapturingRunnerContext``,
    ``test_runner`` recording fixtures) keep working without ceremony.
  - The workflow-level filter in ``_run_core`` reads ``self._output_designation``
    live, preserving today's semantics where mutating the designation after
    build still affects subsequent runs (used by two existing tests).
  - ``Workflow.to_dict()`` continues to emit ``"output_executors":
    list[str] | None`` (sorted from the frozenset). Checkpoint format unchanged.
  
  Files changed
  - _workflow.py: add ``OutputDesignation`` dataclass; replace
    ``_output_executors`` with ``_output_designation``; add
    ``is_terminal_executor``; delete ``_should_yield_output_event``.
  - _runner_context.py: drop ``should_label_as_intermediate`` Protocol method
    and ``InProcRunnerContext`` impl; drop ``_workflow`` back-reference.
  - _workflow_builder.py: remove ``context._workflow = workflow`` assignment.
  - _runner.py, _edge_runner.py, _executor.py, _workflow_context.py: thread
    ``output_designation`` parameter through the call chain.
  - tests/workflow/test_output_designation.py (new): three-state coverage of
    the value type plus the public predicate delegation.
  - tests/workflow/test_workflow_builder.py, test_validation.py,
    test_workflow.py, test_runner.py and
    orchestrations/tests/test_orchestration_intermediate_vs_terminal.py:
    switch probes from ``_output_executors`` set checks to
    ``get_output_executors`` / ``is_terminal_executor``; update two
    post-build mutation tests to set ``_output_designation`` instead.
  
  Verification
  - core/tests/workflow/, orchestrations/tests/, azurefunctions/tests/:
    1119 passed, 42 skipped, 2 xfailed.
  - ``uv run poe lint``: clean.
  - ``uv run poe typing``: only the pre-existing
    ``_AGENT_FORWARDED_EVENT_TYPES`` pyright warning from 394bcd607 remains.
  
  Notes for next iteration
  - The builder's own ``_output_executors`` attribute (``list[Executor |
    SupportsAgentRun]``) is intentionally untouched; the issue scoped the
    rename to the workflow attribute.
  - Adjacent review candidates (twin ``WorkflowAgent`` translators,
    ``_AGENT_FORWARDED_EVENT_TYPES`` kind classifier,
    ``_event_origin_context`` ContextVar removal, ``WorkflowEvent`` ADT
    split, legacy-mode removal) remain out of scope.
  
  * Add explicit workflow output designation
  
  Key decisions
  
  - Extend the internal OutputDesignation value type from terminal-only membership to output/intermediate/hidden classification. Legacy mode remains outputs=None, so workflows built without output_executors or intermediate_executors still label every yield_output as type='output'.
  
  - WorkflowBuilder now accepts intermediate_executors. Providing either designation enters explicit mode; output executors emit output, intermediate executors emit intermediate, and unlisted yield_output payloads are hidden from caller-facing events while remaining in executor_completed data.
  
  - Empty explicit designation, duplicate entries, overlaps, unknown executors, and designated executors without workflow output annotations fail build validation. Existing orchestration builders pass intermediate-capable participants through intermediate_executors to preserve current intermediate_outputs behavior until participant-oriented designation lands.
  
  Files changed
  
  - packages/core/agent_framework/_workflows/_workflow.py, _workflow_builder.py, _workflow_context.py, _validation.py, _events.py
  
  - packages/core/tests/workflow/test_output_designation.py, test_output_executors_contract.py, test_strict_mode_event_labeling.py, test_validation.py, test_workflow.py, test_workflow_agent_intermediate.py
  
  - packages/orchestrations/agent_framework_orchestrations/_sequential.py, _concurrent.py, _group_chat.py, _magentic.py
  
  - packages/core/AGENTS.md
  
  Verification
  
  - uv run pytest packages/core/tests/workflow packages/orchestrations/tests packages/devui/tests/devui/test_mapper.py -q
  
  - uv run pytest packages/azurefunctions/tests -q
  
  - uv run poe lint
  
  - uv run poe typing fails only on pre-existing packages/core/agent_framework/_workflows/_agent.py _AGENT_FORWARDED_EVENT_TYPES private-use pyright error.
  
  Notes for next iteration
  
  - issues/03-core-workflow-explicit-designation.md was moved to issues/done but issues/ remains untracked and intentionally excluded from this commit.
  
  - Slice 4 should tighten workflow.as_agent() mapping for hidden emissions and streaming-only update payloads; Slice 5 should replace orchestration intermediate_outputs with participant-oriented designation.
  
  * Tighten workflow-as-agent output mapping
  
  Key decisions
  
  - Treat AgentResponseUpdate as a streaming-only payload across the workflow.as_agent() adapter, so non-streaming agent runs now reject both terminal output and intermediate workflow events carrying updates.
  - Keep streaming classification behavior explicit: terminal update payloads remain normal text content, while intermediate update payloads are rewritten to text_reasoning content.
  - Add explicit-mode coverage proving hidden yield_output emissions do not appear in non-streaming AgentResponse messages or streaming AgentResponseUpdate chunks.
  
  Files changed
  
  - packages/core/agent_framework/_workflows/_agent.py
  - packages/core/tests/workflow/test_workflow_agent_intermediate.py
  
  Verification
  
  - uv run pytest packages/core/tests/workflow/test_workflow_agent_intermediate.py -q
  - uv run pytest packages/core/tests/workflow/test_workflow_agent.py packages/core/tests/workflow/test_workflow_agent_intermediate.py -q
  - uv run pytest packages/core/tests/workflow packages/orchestrations/tests packages/devui/tests/devui/test_mapper.py -q
  - uv run poe lint
  - uv run poe typing fails only on the pre-existing packages/core/agent_framework/_workflows/_agent.py _AGENT_FORWARDED_EVENT_TYPES private-use pyright error.
  
  Blockers or notes for next iteration
  
  - issues/04-workflow-as-agent-output-mapping.md was moved to issues/done/ but issues/ remains untracked and intentionally excluded from this commit.
  - Slice 5 should replace orchestration intermediate_outputs with participant-oriented designation.
  
  * Add orchestration participant output designation
  
  Key decisions
  
  - Replace orchestration intermediate_outputs with participant-oriented output_participants and intermediate_participants across Sequential, Concurrent, GroupChat, Magentic, and Handoff builders.
  - Keep synthetic final executors terminal by default for Concurrent, GroupChat, and Magentic; keep Sequential's final participant terminal by default; keep Handoff participants terminal by default.
  - Centralize participant designation validation for empty explicit designation, duplicates, overlaps, and unknown participants, then map validated participants to workflow output/intermediate executors.
  
  Files changed
  
  - packages/orchestrations/agent_framework_orchestrations/_participant_designation.py
  - packages/orchestrations/agent_framework_orchestrations/_sequential.py
  - packages/orchestrations/agent_framework_orchestrations/_concurrent.py
  - packages/orchestrations/agent_framework_orchestrations/_group_chat.py
  - packages/orchestrations/agent_framework_orchestrations/_magentic.py
  - packages/orchestrations/agent_framework_orchestrations/_handoff.py
  - packages/orchestrations/tests/test_orchestration_intermediate_vs_terminal.py
  - packages/orchestrations/tests/test_magentic.py
  
  Blockers or notes for next iteration
  
  - issues/05-orchestration-participant-designation.md was moved to issues/done/ but issues/ remains untracked and intentionally excluded from this commit.
  - Slice 7 should migrate samples and docs away from intermediate_outputs to the new participant designation API.
  - uv run poe typing still fails only on the pre-existing packages/core/agent_framework/_workflows/_agent.py _AGENT_FORWARDED_EVENT_TYPES private-use pyright error.
  
  * Migrate samples to explicit output designation
  
  Key decisions
  
  - Replace sample usage of the removed orchestration intermediate_outputs boolean with participant-oriented intermediate_participants designation.
  - Update raw workflow guidance to show output_executors together with intermediate_executors, and document that unlisted yields are hidden in explicit designation mode.
  - Keep orchestration final outputs terminal while streaming designated participant responses as intermediate progress, including workflow.as_agent() samples where intermediates map to text_reasoning content.
  - Refresh workflow and orchestration README guidance plus the changelog reference so public docs no longer point users at intermediate_outputs.
  
  Files changed
  
  - CHANGELOG.md
  - packages/orchestrations/README.md
  - samples/README.md
  - samples/03-workflows/README.md
  - samples/03-workflows/control-flow/intermediate_vs_terminal_outputs.py
  - samples/03-workflows/orchestrations/README.md
  - samples/03-workflows/orchestrations/group_chat_agent_manager.py
  - samples/03-workflows/orchestrations/group_chat_philosophical_debate.py
  - samples/03-workflows/orchestrations/group_chat_simple_selector.py
  - samples/03-workflows/orchestrations/magentic.py
  - samples/03-workflows/orchestrations/magentic_human_plan_review.py
  - samples/03-workflows/orchestrations/sequential_chain_only_agent_responses.py
  - samples/03-workflows/agents/group_chat_workflow_as_agent.py
  - samples/03-workflows/agents/magentic_workflow_as_agent.py
  - samples/03-workflows/agents/sequential_workflow_as_agent.py
  - samples/semantic-kernel-migration/orchestrations/group_chat.py
  - samples/semantic-kernel-migration/orchestrations/magentic.py
  
  Blockers or notes for next iteration
  
  - issues/07-samples-and-docs-explicit-output-designation.md was moved to issues/done/ but issues/ remains untracked and intentionally excluded from this commit.
  - issues/06-devui-intermediate-event-rendering.md remains present and appears already satisfied by existing DevUI mapper/tests from the prior implementation slice.
  - PRD-explicit-workflow-output-designation.md remains untracked and intentionally excluded from this commit.
  
  * Render DevUI intermediate workflow outputs
  
  Key decisions
  
  - Preserve workflow output designation metadata on visible DevUI output messages and text deltas so intermediate/data emissions remain distinguishable from terminal output.
  - Render intermediate workflow message items in the execution timeline using executor metadata, while excluding them from the final workflow result aggregation.
  - Keep terminal output message rendering unchanged and retain legacy data events on the intermediate compatibility path.
  
  Files changed
  
  - packages/devui/agent_framework_devui/_mapper.py
  - packages/devui/frontend/src/components/features/workflow/execution-timeline.tsx
  - packages/devui/frontend/src/components/features/workflow/workflow-view.tsx
  - packages/devui/frontend/src/types/openai.ts
  - packages/devui/tests/devui/test_mapper.py
  
  Blockers or notes for next iteration
  
  - issues/06-devui-intermediate-event-rendering.md was moved to issues/done/ but issues/ remains untracked and intentionally excluded from this commit.
  - PRD-explicit-workflow-output-designation.md remains untracked and intentionally excluded from this commit.
  - uv run poe typing still fails only on the pre-existing packages/core/agent_framework/_workflows/_agent.py _AGENT_FORWARDED_EVENT_TYPES private-use pyright error.
  
  * Fix mypy
  
  * Clarify orchestration participant output config
  
  * Rename participant output kwargs for clarity
  
  output_participants -> final_output_from, intermediate_participants ->
  intermediate_output_from. The old names read like categories of
  participant; the new names make it clear the kwarg designates which
  participants' outputs surface as final vs. intermediate events.
  
  * Rename core workflow output kwargs with deprecation shim
  
  Adds final_output_from / intermediate_output_from as canonical kwargs on
  Workflow and WorkflowBuilder. Old output_executors / intermediate_executors
  kwargs continue to work but emit DeprecationWarning via a shared coalesce
  helper that also rejects supplying both. Wire-format keys in to_dict()
  stay as output_executors / intermediate_executors so checkpoint
  compatibility is preserved.
  
  Internal call sites in orchestrations and samples updated to the new
  names so users following sample code learn the canonical vocabulary;
  legacy callers still work with a one-shot warning.
  
  * Suppress pyright reportPrivateUsage on cross-module sentinel import
  
  * Update docstrings
  
  * Propagate sub-workflow intermediate outputs, fix handoff/sequential intermediate-only designation, and shore up tests, sample, and docstrings around the intermediate output contract.
  
  * Add canonical workflow output_from selection
  
  Key decisions:\n- Make output_from the canonical workflow-output allow-list and keep output_executors/final_output_from as deprecated compatibility aliases.\n- Treat empty output_from/intermediate_output_from lists as explicit selections and keep validation responsible for empty, duplicate, overlap, and unknown selections.\n- Remove the branch-only public intermediate_executors WorkflowBuilder kwarg while preserving legacy wire keys in to_dict().\n\nFiles changed:\n- packages/core/agent_framework/_workflows/_workflow.py\n- packages/core/agent_framework/_workflows/_workflow_builder.py\n- packages/core/agent_framework/_workflows/_workflow_context.py\n- packages/core/agent_framework/_workflows/_agent.py\n- packages/core/agent_framework/_workflows/_agent_executor.py\n- packages/core/tests/workflow/* output-selection coverage updates\n- packages/core/AGENTS.md\n- issues/done/001-canonical-list-based-output-selection.md\n\nBlockers/notes:\n- Orchestration builders still pass final_output_from internally; follow-up issue 004 should migrate them to output_from.\n- Legacy omitted-selection behavior and explicit all/all_other literals are left for issues 002 and 003.
  
  * Add explicit all workflow output selection
  
  Key decisions:
  - Treat output_from='all' as an explicit workflow-output selection sentinel and expand it at build time to executors with declared workflow output types.
  - Keep omitted output selections in legacy all-output mode with a deprecation warning that names output_from and intermediate_output_from and points to output_from='all'.
  - Reject intermediate_output_from='all' at construction because the all-output literal is output-only for this issue.
  
  Files changed:
  - packages/core/agent_framework/_workflows/_workflow_builder.py
  - packages/core/tests/workflow/test_output_executors_contract.py
  - issues/done/002-explicit-all-output-and-legacy-migration.md
  
  Blockers/notes:
  - all_other intermediate-output selection remains for issue 003.
  - Workflow-as-agent/orchestration parity remains for issue 004.
  
  * Add all-other intermediate output selection
  
  Key decisions:
  - Treat intermediate_output_from='all_other' as an explicit intermediate-output selection sentinel and expand it at build time after the workflow graph is complete.
  - Expand all_other to output-capable executors not selected by output_from; omitted or empty output_from selects no workflow outputs, while output_from='all' leaves an empty intermediate selection.
  - Keep output_from='all_other' invalid so all_other remains intermediate-output-only and runtime classification still receives concrete executor-id sets.
  
  Files changed:
  - packages/core/agent_framework/_workflows/_workflow_builder.py
  - packages/core/tests/workflow/test_output_executors_contract.py
  - issues/done/003-all-other-intermediate-output-selection.md
  
  Blockers/notes:
  - Workflow-as-agent and orchestration parity remains for issue 004.
  - Full documentation updates remain for issue 005.
  
  * Add orchestration output selection parity
  
  Key decisions:
  - Expose output_from on sequential, concurrent, group chat, handoff, and magentic builders while keeping final_output_from as a deprecated compatibility alias.
  - Resolve orchestration participant selections through the same explicit rules as workflows: output_from='all', intermediate_output_from='all_other', hidden unselected participant payloads, and overlap/duplicate/unknown/invalid-literal validation.
  - Continue preserving documented orchestration defaults by always designating each pattern's terminal internal executor where applicable.
  
  Files changed:
  - packages/orchestrations/agent_framework_orchestrations/_participant_output_config.py
  - packages/orchestrations/agent_framework_orchestrations/_sequential.py
  - packages/orchestrations/agent_framework_orchestrations/_concurrent.py
  - packages/orchestrations/agent_framework_orchestrations/_group_chat.py
  - packages/orchestrations/agent_framework_orchestrations/_handoff.py
  - packages/orchestrations/agent_framework_orchestrations/_magentic.py
  - packages/orchestrations/agent_framework_orchestrations/_orchestration_request_info.py
  - packages/orchestrations/tests/test_orchestration_intermediate_vs_terminal.py
  - issues/done/004-workflow-as-agent-and-orchestration-parity.md
  
  Blockers/notes:
  - Full documentation and sample migration wording remains for issue 005.
  - Existing tests that intentionally use final_output_from now emit the new deprecation warning.
  
  * Document workflow output selection contract
  
  Key decisions:
  - Use Workflow Output and Intermediate Output as the developer-facing terms for selected caller-facing emissions.
  - Document output_from and intermediate_output_from as the canonical API, with output_from as an allow-list and unselected payloads hidden unless explicitly selected as intermediate.
  - Add scenario and invalid-selection tables for workflow and orchestration docs, including legacy omission warnings, output_from='all', intermediate_output_from='all_other', list selections, invalid literals, overlap, duplicates, unknown selections, and empty explicit selections.
  - Migrate samples away from final_output_from and output_executors except where compatibility aliases are explicitly documented.
  
  Files changed:
  - packages/core/AGENTS.md
  - packages/orchestrations/README.md
  - packages/orchestrations/agent_framework_orchestrations/_handoff.py
  - packages/orchestrations/agent_framework_orchestrations/_sequential.py
  - samples/03-workflows/README.md
  - samples/03-workflows/control-flow/intermediate_vs_terminal_outputs.py
  - samples/03-workflows/human-in-the-loop/agents_with_approval_requests.py
  - samples/03-workflows/orchestrations/README.md
  - samples/04-hosting/foundry-hosted-agents/responses/05_workflows/main.py
  - scripts/sample_validation/create_dynamic_workflow_executor.py
  - issues/done/005-document-output-selection-contract.md
  
  Blockers/notes:
  - Direct full Ruff on scripts/sample_validation/create_dynamic_workflow_executor.py still reports pre-existing docstring/print/line-length issues outside this docs migration; syntax-focused checks for changed files pass.
  - No remaining AFK issue files are present under issues/.
  
  * Latest updates
  
  * Typing fixes
  
  * Cleanup

  Evan Mattson · 2026-05-19 00:15:25 +00:00
  3bbc81554b
• docs: fix outdated @ai_function reference to @tool in workflows README (#5622)

  The @ai_function decorator was renamed to @tool in release 
  python-1.0.0b260128 (PR #3413) as a breaking change.
  
  Line 58 of python/samples/03-workflows/README.md still referenced 
  the old @ai_function name, causing users to hit:
  ImportError: cannot import name 'AIFunction'
  
  Changes made:
  - Fixed @ai_function to @tool on line 58 only
  - No formatting or whitespace changes

  Aishwarya Sawant · 2026-05-04 10:59:09 +00:00
  e558d36ff6
• Python: (core): Add functional workflow API (#4238)

  * Add functional workflow api
  
  * cleanup
  
  * More cleanup
  
  * address copilot feedback
  
  * Address PR feedbacK
  
  * updates
  
  * PR feedback
  
  * Address review comments on functional workflow samples
  
  - Swap 05/06 get-started samples: agent workflow first (motivates
    why workflows exist), simple text workflow second
  - Rename text_pipeline → text_workflow, poem_pipeline → poem_workflow
  - Add @step to agent workflow sample (05) to demonstrate caching
  - Switch agent samples to AzureOpenAIResponsesClient with Foundry
  - Remove .as_agent() from agent_integration.py to focus on the key
    difference between inline agent calls vs @step-cached calls
  - Add commented-out Agent.run example in hitl_review.py
  - Add clarifying comment in _functional.py that event streaming is
    buffered (not true per-token streaming)
  - Add naive_group_chat.py functional sample: round-robin group chat
    as a plain Python loop
  - Update READMEs to reflect new file names and group chat sample
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Fix pyright type errors
  
  * Address PR review comments on functional workflow API
  
  1. Allow request_info inside @step: Auto-inject RunContext into step
     functions that declare a RunContext parameter (by type or name 'ctx'),
     and expose get_run_context() for programmatic access.
  
  2. Handle None responses: Log a warning when a response value is None,
     and document the behavior in request_info docstring.
  
  3. Add executor_bypassed event type: Replace executor_invoked +
     executor_completed with a single executor_bypassed event when a step
     replays from cache, making cached vs live execution explicit.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Add regression tests for PR review comments on functional workflow API
  
  The three review comments (request_info in @step, None response handling,
  executor_bypassed event type) were already addressed in 7da7db4e. This
  commit adds cross-cutting regression tests that exercise the interactions
  between these features:
  
  - HITL in step with caching: preceding step bypassed on resume
  - Full checkpoint lifecycle with HITL step (interrupt -> resume -> restore)
  - None response inside step-level request_info logs warning
  - WorkflowInterrupted from step does not emit executor_failed
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Address PR #4238 review comments on functional workflow API
  
  Comment 1 (request_info in @step): Already supported. Added comment in
  StepWrapper.__call__ explaining why WorkflowInterrupted (BaseException)
  safely bypasses the except Exception handler.
  
  Comment 2 (None response): Added docstring to _get_response clarifying
  the (found, value) return tuple semantics and None handling.
  
  Comment 3 (bypass event type): executor_bypassed is already a dedicated
  event type in WorkflowEventType. Updated comment at the bypass site to
  make the deliberate event type choice explicit.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Add experimental API warnings to functional workflow module
  
  Mark all public classes and decorators (workflow, step, RunContext,
  FunctionalWorkflow, StepWrapper, FunctionalWorkflowAgent) as
  experimental and subject to change or removal.
  
  * Address PR #4238 review comments from @eavanvalkenburg
  
  - RunContext docstring leads with purpose (opt-in handle for HITL,
    custom events, state) so readers importing it from the public surface
    understand its role before the mechanics (#2993513452).
  - Rename `06_first_functional_workflow.py` to
    `06_functional_workflow_basics.py`; the previous filename was
    confusing since it followed `05_functional_workflow_with_agents.py`
    (#2993531979).
  - Simplify `05_functional_workflow_with_agents.py` to call agents
    directly without a @step wrapper; the step-vs-no-step contrast lives
    in `03-workflows/functional/agent_integration.py`, keeping the
    get-started sample minimal (#2993525532).
  - Switch functional samples to `FoundryChatClient` for consistency with
    the rest of 01-get-started and 03-workflows (follow-up on #2876988570).
  - Use walrus in `hitl_review.py` final-state assertion (#2993572182).
  - Add expected-output block to `basic_streaming_pipeline.py` (#2993557609).
  - Clarify in `parallel_pipeline.py` that `@step` composes with
    `asyncio.gather` (#2993597282).
  - `naive_group_chat.py` threads `list[Message]` between turns instead
    of stringifying the transcript, preserving role/authorship (#2993583231).
  
  Drive-by: pre-commit hook sorts an unrelated import block in
  `samples/04-hosting/foundry-hosted-agents/responses/02_local_tools/main.py`.
  
  * Fix 10 functional-workflow API bugs from /ultrareview pass
  
  - bug_001: `ctx.request_info()` without an explicit `request_id` now derives
    a deterministic `auto::<index>` id from the call-counter, so HITL resume
    works correctly on the documented default path.  A uuid was regenerated on
    every replay, making resume impossible.
  
  - bug_002: `StepWrapper.__call__` no longer deepcopies arguments on the
    cache-hit replay branch.  The copy is only performed on the live-execution
    path (for the event log) and falls back to the original mapping if deepcopy
    fails, so steps whose args aren't deepcopyable (locks, sockets, sessions)
    can still resume from checkpoint.
  
  - bug_007: `_set_responses` now prunes each resolved `request_id` from
    `_pending_requests`, and the cache-hit branch in `request_info` does the
    same.  Previously, answered requests were re-serialized into every
    subsequent checkpoint and the final checkpoint falsely claimed pending
    requests even after the workflow completed.
  
  - bug_008: `_compute_signature_hash` now mixes the function's `co_code` and
    `co_names` into the checkpoint signature, so changes to the workflow body
    invalidate older checkpoints even when steps are accessed via module /
    class attributes (which `_discover_step_names` can't see statically).
    `RunContext._record_observed_step` records observed step names for
    diagnostics.
  
  - bug_010: `FunctionalWorkflow.run()` docstring corrected — says "at least
    one of message/responses/checkpoint_id" and explicitly notes `responses`
    may be combined with `checkpoint_id` (the validator already allowed this).
  
  - bug_013: `FunctionalWorkflowAgent` now surfaces `request_info` events as
    `FunctionApprovalRequestContent` items (mirroring graph `WorkflowAgent`),
    threads `responses=` and `checkpoint_id=` through to the underlying
    workflow, and exposes `pending_requests`.  Previously `.as_agent()`
    returned empty `AgentResponse` for HITL workflows — effectively unusable.
  
  - bug_014: `FunctionalWorkflow` now clears `_last_message`,
    `_last_step_cache`, and `_last_pending_request_ids` on clean completion.
    `run()` validates that `responses=` keys intersect the currently-pending
    request set (or raises with a clear error) instead of silently replaying
    against stale singleton state from a prior run.
  
  - bug_015: `FunctionalWorkflow.as_agent` signature now matches graph
    `Workflow.as_agent`: accepts `name`, `description`, `context_providers`,
    and `**kwargs`.  `FunctionalWorkflowAgent` stores the overrides.
  
  - bug_017: `RunContext.set_state` raises `ValueError` for underscore-
    prefixed keys (the framework's `_step_cache` / `_original_message` keys
    would silently clobber user state on checkpoint save and user
    underscore-prefixed state was dropped on restore).  Docstring documents
    the reserved prefix.
  
  - merged_bug_003: Workflow function arity is validated at decoration time.
    Multiple non-ctx parameters raise `ValueError` immediately (previously
    every arg past the first was silently dropped at call time).  Passing a
    non-None `message` to a ctx-only workflow raises `ValueError` instead of
    silently discarding the message.
  
  Test coverage: +18 regression tests covering every fix.  Full workflow
  suite now 766 passed, 1 skipped, 2 xfailed; full core suite 2338 passed.
  
  * Deslop functional.py fix commit
  
  - Remove dead instrumentation added in the prior commit that was never
    consumed: `RunContext._observed_step_names`,
    `RunContext._record_observed_step`, `FunctionalWorkflow._runtime_step_names`,
    and `FunctionalWorkflowAgent._extra_kwargs`.  The signature hash relies on
    `co_code` alone, which covers the attribute-access case without the
    collection-scaffolding.
  - Trim over-explanatory comments that restated what the code does or what
    it no longer does.  Keep only the comments that answer "why" for the
    non-obvious bits (deterministic id contract, defensive deepcopy, stale
    replay guard).
  - Compress the `_compute_signature_hash` and FunctionalWorkflow `__init__`
    block docstrings without losing the user-facing reasoning.
  
  Net -49 lines.  Regression lock preserved (766 passed, 1 skipped, 2 xfailed).
  
  * Fix functional workflow review feedback
  
  ---------
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  Co-authored-by: Copilot <copilot@github.com>

  Evan Mattson · 2026-04-24 09:41:20 +00:00
  da32e8cf80
• Python: Add Cosmos DB NoSQL Checkpoint Storage for Python Workflows (#4916)

  * Add CosmosCheckpointStorage for Python workflow checkpointing
  
  Add native Cosmos DB NoSQL support for workflow checkpoint storage in the
  Python agent-framework-azure-cosmos package, achieving parity with the
  existing .NET CosmosCheckpointStore.
  
  New files:
  - _checkpoint_storage.py: CosmosCheckpointStorage implementing the
    CheckpointStorage protocol with 6 methods (save, load, list_checkpoints,
    delete, get_latest, list_checkpoint_ids)
  - test_cosmos_checkpoint_storage.py: Unit and integration tests
  - workflow_checkpointing.py: Sample demonstrating Cosmos DB-backed
    workflow checkpoint/resume
  
  Auth support:
  - Managed identity / RBAC via Azure credential objects
    (DefaultAzureCredential, ManagedIdentityCredential, etc.)
  - Key-based auth via account key string or AZURE_COSMOS_KEY env var
  - Pre-created CosmosClient or ContainerProxy
  
  Key design decisions:
  - Partition key: /workflow_name for efficient per-workflow queries
  - Serialization: Reuses encode/decode_checkpoint_value for full Python
    object fidelity (hybrid JSON + pickle approach)
  - Container auto-creation via create_container_if_not_exists
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Adding cosmos checkpointer
  
  * Resolving comments
  
  * Fixing builds
  
  * Adding sample for history provider and checkpoint storage
  
  * Resolving comments
  
  * fixing builds
  
  * Resolving comments
  
  ---------
  
  Co-authored-by: Aayush Kataria <aayushkataria@Aayushs-MacBook-Pro-2.local>
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>

  Aayush Kataria · 2026-04-09 05:01:41 +00:00
  30a2bc3dcb
• Python: [BREAKING] Python: move Azure AI embeddings to Foundry (#5056)

  * renamed AzureAIINferenceEmbeddings and lazy load azure-cosmos and env var rename
  
  * updated coverage
  
  * fix readme

  Eduard van Valkenburg · 2026-04-02 11:26:35 +00:00
  95fd5ec658
• Python: [BREAKING] Remove deprecated Python OpenAI/Azure AI surfaces (#4990)

  * [BREAKING] Remove deprecated Python OpenAI/Azure AI surfaces
  
  Also clean up follow-on docs, environment guidance, package metadata, and lab test stability.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Fix deleted semantic-kernel sample links
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Address PR review feedback
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * improve foundry language
  
  * Fix A2A Foundry sample regression
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  ---------
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

  Eduard van Valkenburg · 2026-03-31 20:36:21 +00:00
  3a49b1d6dd
• Python: Fix samples (#4980)

  * First samples 1st batch
  
  * Fix sample paths
  
  * Fix workflow samples
  
  * Fix workflow dependency
  
  * Correct env vars
  
  * Increase idle timeout
  
  * Fix workflows HIL sample
  
  * Fix more workflow samples

  Tao Chen · 2026-03-31 15:20:35 +00:00
  016daf3b98
• Python: Update workflow orchestration samples to use AzureOpenAIResponsesClient (#4285)

  * Update workflow orchestration samples to use AzureOpenAIResponsesClient
  
  * Fix broken link

  Evan Mattson · 2026-02-26 07:51:25 +00:00
  8e2cc4bedc
• [BREAKING] Python: Add InvokeFunctionTool action for declarative workflows (#3716)

  * add(declarative): Declarative workflow InvokeFunctionTool feature
  
  * Cleanup
  
  * Address PR feedback
  
  * Remove InvokeTool kind, consolidate to InvokeFunctionTool
  
  * Fix sample locations
  
  * pin azure-ai-projects to 2.0.0b3 due to breaking changes

  Evan Mattson · 2026-02-24 22:54:35 +00:00
  40d2fac29c
• Python: [BREAKING] PR2 — Wire context provider pipeline, remove old types, update all consumers (#3850)

  * PR2: Wire context provider pipeline and update all internal consumers
  
  - Replace AgentThread with AgentSession across all packages
  - Replace ContextProvider with BaseContextProvider across all packages
  - Replace context_provider param with context_providers (Sequence)
  - Replace thread= with session= in run() signatures
  - Replace get_new_thread() with create_session()
  - Add get_session(service_session_id) to agent interface
  - DurableAgentThread -> DurableAgentSession
  - Remove _notify_thread_of_new_messages from WorkflowAgent
  - Wire before_run/after_run context provider pipeline in RawAgent
  - Auto-inject InMemoryHistoryProvider when no providers configured
  
  * fix: update all tests for context provider pipeline, fix lazy-loaders, remove old test files
  
  * refactor: update all sample files for context provider pipeline (AgentThread→AgentSession, ContextProvider→BaseContextProvider)
  
  * fix: update remaining ag-ui references (client docstring, getting_started sample)
  
  * fix: make get_session service_session_id keyword-only to avoid confusion with session_id
  
  * refactor: rename _RunContext.thread_messages to session_messages
  
  * refactor: remove _threads.py, _memory.py, and old provider files; migrate devui to use plain message lists
  
  * rename: remove _new_ prefix from test files
  
  * refactor: rewrite SlidingWindowChatMessageStore as SlidingWindowHistoryProvider(InMemoryHistoryProvider)
  
  * fix: read full history from session state directly instead of reaching into provider internals
  
  * fix: update stale .pyi stubs, sample imports, and README references for new provider types
  
  * fix: remove stale message_store, _notify_thread_of_new_messages, and session_id.key references in samples
  
  * refactor: merge context_providers and sessions sample folders into sessions, remove aggregate_context_provider
  
  * refactor: UserInfoMemory stores state in session.state instead of instance attributes
  
  * feat: add Pydantic BaseModel support to session state serialization
  
  Pydantic models stored in session.state are now automatically serialized
  via model_dump() and restored via model_validate() during to_dict()/from_dict()
  round-trips. Models are auto-registered on first serialization; use
  register_state_type() for cold-start deserialization.
  
  Also export register_state_type as a public API.
  
  * fix mem0
  
  * Update sample README links and descriptions for session terminology
  
  - Replace 'thread' with 'session' in sample descriptions across all READMEs
  - Update file links for renamed samples (mem0_sessions, redis_sessions, etc.)
  - Fix Threads section → Sessions section in main samples/README.md
  - Update tools, middleware, workflows, durabletask, azure_functions READMEs
  - Update architecture diagrams in concepts/tools/README.md
  - Update migration guides (autogen, semantic-kernel)
  
  * Fix broken Redis README link to renamed sample
  
  * Fix Mem0 OSS client search: pass scoping params as direct kwargs
  
  AsyncMemory (OSS) expects user_id/agent_id/run_id as direct kwargs,
  while AsyncMemoryClient (Platform) expects them in a filters dict.
  Adds tests for both client types.
  
  Port of fix from #3844 to new Mem0ContextProvider.
  
  * Fix rebase issues: restore missing _conversation_state.py and checkpoint decode logic
  
  - Add back _conversation_state.py (encode/decode_chat_messages) lost in rebase
  - Fix on_checkpoint_restore to decode cache/conversation with decode_chat_messages
  - Fix on_checkpoint_restore to use decode_checkpoint_value for pending requests
  - Add tests/workflow/__init__.py for relative import support
  - Fix test_agent_executor checkpoint selection (checkpoints[1] not superstep)
  
  * Add STORES_BY_DEFAULT ClassVar to skip redundant InMemoryHistoryProvider injection
  
  Chat clients that store history server-side by default (OpenAI Responses API,
  Azure AI Agent) now declare STORES_BY_DEFAULT = True. The agent checks this
  during auto-injection and skips InMemoryHistoryProvider unless the user
  explicitly sets store=False.
  
  * Fix broken markdown links in azure_ai and redis READMEs
  
  * Fix getting-started samples to use session API instead of removed thread/ContextProvider API
  
  * updates to workflow as agent
  
  * fix group chat import
  
  * Rename Thread→Session throughout, fix service_session_id propagation, remove stale AGUIThread
  
  - Fix: Propagate conversation_id from ChatResponse back to session.service_session_id
    in both streaming and non-streaming paths in _agents.py
  - Rename AgentThreadException → AgentSessionException
  - Remove stale AGUIThread from ag_ui lazy-loader
  - Rename use_service_thread → use_service_session in ag-ui package
  - Rename test functions from *_thread_* to *_session_*
  - Rename sample files from *_thread* to *_session*
  - Update docstrings and comments: thread → session
  - Update _mcp.py kwargs filter: add 'session' alongside 'thread'
  - Fix ContinuationToken docstring example: thread=thread → session=session
  - Fix _clients.py docstring: 'Agent threads' → 'Agent sessions'
  
  * Fix broken markdown links after thread→session file renames
  
  * fix azure ai test

  Eduard van Valkenburg · 2026-02-12 21:00:32 +00:00
  1e350ea22f
• Python: restructure: Python samples into progressive 01-05 layout (#3862)

  * restructure: Python samples into progressive 01-05 layout
  
  - 01-get-started/: 6 numbered steps (hello agent → hosting)
  - 02-agents/: all agent concept samples (tools, middleware, providers, etc.)
  - 03-workflows/: ALL existing workflow samples preserved as-is
  - 04-hosting/: azure-functions, durabletask, a2a
  - 05-end-to-end/: demos, evaluation, hosted agents
  - Old files moved to _to_delete/ for review
  - Added AGENTS.md with structure documentation
  - autogen-migration/ and semantic-kernel-migration/ preserved at root
  
  * fix: switch to AzureOpenAI Foundry, fix CI failures
  
  - Switch all 01-get-started samples to AzureOpenAIResponsesClient with
    Azure AI Foundry project endpoint (AZURE_AI_PROJECT_ENDPOINT +
    AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME + AzureCliCredential)
  - Add _to_delete/ and 05-end-to-end/ to pyrightconfig.samples.json excludes
  - Fix test paths in packages/ that referenced old getting_started/ dirs:
    durabletask conftest + streaming test, azurefunctions conftest,
    devui conftest + capture_messages + openai_sdk_integration
  - Fix workflow_as_agent_human_in_the_loop.py import (sibling import)
  - Update hosting READMEs and tool comment paths
  - Replace root README.md with new structure overview
  - Update AGENTS.md to document Azure OpenAI Foundry as default provider
  
  * cleanup: remove _to_delete folder, copy resource files to active dirs
  
  All files in _to_delete/ were either:
  - Exact duplicates of files in the new structure (240 files)
  - Same file with only comment path updates (100 files)
  - One import-fix diff (workflow_as_agent_human_in_the_loop.py)
  - One superseded minimal_sample.py
  
  Resource files (sample.pdf, countries.json, employees.pdf, weather.json)
  copied to 02-agents/sample_assets/ and 02-agents/resources/ since active
  samples reference them.
  
  * fix: address PR review comments, centralize resources, remove root duplicates
  
  - Fix type annotation in 04_memory.py (string union -> proper types)
  - Fix old sample paths in observability files
  - Fix grammar/spelling in observability samples
  - Move sample_assets/ and resources/ to shared/ folder
  - Remove 8 duplicate observability files from 02-agents root
  - Update resource path references in multimodal_input and provider samples
  
  * fix: update broken links from old getting_started paths to new structure
  
  - Update relative paths in READMEs: getting_started/ → 01-get-started/,
    02-agents/, 03-workflows/, 04-hosting/, 05-end-to-end/
  - Fix absolute GitHub URLs in package READMEs
  - Fix broken link in ollama package README
  
  * fix: convert absolute GitHub URLs to relative paths for link checker
  
  Absolute URLs to python/samples/ on main branch 404 until PR merges.
  Converted to relative paths that linkspector can verify locally.
  
  * fix: update link for handoff sample moved to orchestrations/
  
  * fix: update chatkit-integration README path from demos/ to 05-end-to-end/
  
  * fix: update broken links in orchestrations README to match flat directory structure

  Eduard van Valkenburg · 2026-02-12 17:36:36 +00:00
  a2856d3b92