Fix AGUI overload tests after rebase

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

.github/CODEOWNERS

@@ -1,5 +1,130 @@
 # Code ownership assignments
 # https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+#
+# Policy: a PR needs one approval, and it must come from a code owner of the changed
+# files ("Require review from Code Owners" + "Required approvals: 1" on `main`).
+# A PR touching several CODEOWNERS patterns will request review from the applicable
+# code owners, but an approval from any applicable code owner is sufficient to satisfy
+# GitHub's required-code-owner review.
+#
+# Order matters: the LAST matching pattern wins, so a module rule fully replaces the
+# catch-all rather than adding to it. @chetantoshniwal is included on every line as a
+# repository-wide fallback owner. All owners on a line have equal approval authority.
+#
+# CONVENTION: owners are written in the order
+#   @chetantoshniwal <owner A> <owner B> [...]
+# @chetantoshniwal is at the beginning for aesthetics. The owners share equal approval
+# power and responsibility.
+#
+# RULE: every path must list at least two owners besides @chetantoshniwal. An author
+# cannot approve their own PR, so a path with a single module owner leaves only Chetan
+# to review whenever that owner is the author, which defeats the point of naming a
+# module owner.
+#
+# Samples: owned by all core developers of that language, not by the module a sample
+# demonstrates. Any core Python developer can approve any Python sample, and any core
+# .NET developer can approve any .NET sample. No dedicated rule is needed -- samples
+# fall through to the /python and /dotnet rules, which already list those developers.
+#
+# Tests: same as samples. Tests that live inside a package (python/packages/<pkg>/tests)
+# are covered by that package's rule instead, since they sit under its path.
+
+# Default owners for everything not matched by a module rule below.
+*                                                               @chetantoshniwal @westey-m
+
+# Repository-level paths: every core Agent Framework developer is a code owner, so any
+# one of them can approve. Be explicit now and we can use the AgentFramework team in the future.
+/docs/                                                          @chetantoshniwal @westey-m @eavanvalkenburg @giles17 @moonbox3 @TaoChenOSU @peibekwe @rogerbarreto @SergeyMenshykh
+/*.md                                                           @chetantoshniwal @westey-m @eavanvalkenburg @giles17 @moonbox3 @TaoChenOSU @peibekwe @rogerbarreto @SergeyMenshykh
+/LICENSE                                                        @chetantoshniwal @westey-m @eavanvalkenburg @giles17 @moonbox3 @TaoChenOSU @peibekwe @rogerbarreto @SergeyMenshykh
+/.gitattributes                                                 @chetantoshniwal @westey-m @eavanvalkenburg @giles17 @moonbox3 @TaoChenOSU @peibekwe @rogerbarreto @SergeyMenshykh
+/.gitignore                                                     @chetantoshniwal @westey-m @eavanvalkenburg @giles17 @moonbox3 @TaoChenOSU @peibekwe @rogerbarreto @SergeyMenshykh
+/.github                                                        @chetantoshniwal @westey-m @eavanvalkenburg @giles17 @moonbox3 @TaoChenOSU @peibekwe @rogerbarreto @SergeyMenshykh
+
+# Repository-level paths that require specific owners
+/.devcontainer                                                  @chetantoshniwal @westey-m @rogerbarreto @SergeyMenshykh
+/declarative-agents                                             @chetantoshniwal @moonbox3 @peibekwe
+
+# Core Python developers: @eavanvalkenburg @giles17 @moonbox3 @TaoChenOSU
+/python                                                         @chetantoshniwal @eavanvalkenburg @giles17 @moonbox3 @TaoChenOSU
+
+# Python packages
+/python/packages/a2a/                                           @chetantoshniwal @giles17 @eavanvalkenburg
+/python/packages/ag-ui/                                         @chetantoshniwal @moonbox3 @giles17
+/python/packages/anthropic/                                     @chetantoshniwal @eavanvalkenburg @giles17
+/python/packages/azure-ai-search/                               @chetantoshniwal @eavanvalkenburg @giles17
+/python/packages/azure-contentunderstanding/                    @chetantoshniwal @giles17 @eavanvalkenburg
+/python/packages/azure-cosmos/                                  @chetantoshniwal @eavanvalkenburg @giles17
+/python/packages/azure-cosmos-memory/                           @chetantoshniwal @eavanvalkenburg @giles17
+/python/packages/bedrock/                                       @chetantoshniwal @eavanvalkenburg @giles17
+/python/packages/chatkit/                                       @chetantoshniwal @moonbox3 @giles17
+/python/packages/claude/                                        @chetantoshniwal @eavanvalkenburg @giles17
+/python/packages/copilotstudio/                                 @chetantoshniwal @eavanvalkenburg @giles17
+/python/packages/core/                                          @chetantoshniwal @eavanvalkenburg @moonbox3 @TaoChenOSU @giles17
+/python/packages/core/agent_framework/_workflows/               @chetantoshniwal @moonbox3 @TaoChenOSU
+/python/packages/core/agent_framework/_harness/                 @chetantoshniwal @westey-m @eavanvalkenburg
+/python/packages/declarative/                                   @chetantoshniwal @moonbox3 @peibekwe
+/python/packages/devui/                                         @chetantoshniwal @eavanvalkenburg @moonbox3
+/python/packages/foundry/                                       @chetantoshniwal @eavanvalkenburg @TaoChenOSU @moonbox3 @giles17
+/python/packages/foundry_hosting/                               @chetantoshniwal @TaoChenOSU @eavanvalkenburg
+/python/packages/foundry_local/                                 @chetantoshniwal @eavanvalkenburg @giles17
+/python/packages/gemini/                                        @chetantoshniwal @giles17 @eavanvalkenburg
+/python/packages/github_copilot/                                @chetantoshniwal @giles17 @eavanvalkenburg
+/python/packages/hosting/                                       @chetantoshniwal @eavanvalkenburg @TaoChenOSU
+/python/packages/hosting-a2a/                                   @chetantoshniwal @eavanvalkenburg @TaoChenOSU
+/python/packages/hosting-mcp/                                   @chetantoshniwal @eavanvalkenburg @TaoChenOSU
+/python/packages/hosting-responses/                             @chetantoshniwal @eavanvalkenburg @TaoChenOSU
+/python/packages/hosting-telegram/                              @chetantoshniwal @eavanvalkenburg @TaoChenOSU
+/python/packages/hyperlight/                                    @chetantoshniwal @eavanvalkenburg @giles17
+/python/packages/lab/                                           @chetantoshniwal @eavanvalkenburg @giles17 @moonbox3 @TaoChenOSU
+/python/packages/mem0/                                          @chetantoshniwal @eavanvalkenburg @giles17
+/python/packages/mistral/                                       @chetantoshniwal @eavanvalkenburg @giles17
+/python/packages/monty/                                         @chetantoshniwal @eavanvalkenburg @giles17
+/python/packages/ollama/                                        @chetantoshniwal @eavanvalkenburg @giles17
+/python/packages/openai/                                        @chetantoshniwal @eavanvalkenburg @moonbox3 @TaoChenOSU @giles17
+/python/packages/orchestrations/                                @chetantoshniwal @moonbox3 @TaoChenOSU
+/python/packages/purview/                                       @chetantoshniwal @eavanvalkenburg @giles17
+/python/packages/redis/                                         @chetantoshniwal @eavanvalkenburg @giles17
+/python/packages/tools/                                         @chetantoshniwal @eavanvalkenburg @giles17
+
+# Core .NET developers: @peibekwe @rogerbarreto @SergeyMenshykh @westey-m
+/dotnet                                                         @chetantoshniwal @peibekwe @rogerbarreto @SergeyMenshykh @westey-m
+
+# .NET projects
+/dotnet/src/Aspire.Hosting.AgentFramework.DevUI/                @chetantoshniwal @peibekwe @rogerbarreto @SergeyMenshykh @westey-m
+/dotnet/src/LegacySupport/                                      @chetantoshniwal @peibekwe @rogerbarreto @SergeyMenshykh @westey-m
+/dotnet/src/Shared/                                             @chetantoshniwal @peibekwe @rogerbarreto @SergeyMenshykh @westey-m
+/dotnet/src/Microsoft.Agents.AI/                                @chetantoshniwal @rogerbarreto @SergeyMenshykh @westey-m
+/dotnet/src/Microsoft.Agents.AI.A2A/                            @chetantoshniwal @rogerbarreto @SergeyMenshykh @westey-m
+/dotnet/src/Microsoft.Agents.AI.Abstractions/                   @chetantoshniwal @rogerbarreto @SergeyMenshykh @westey-m
+/dotnet/src/Microsoft.Agents.AI.AGUI/                           @chetantoshniwal @peibekwe @rogerbarreto @SergeyMenshykh @westey-m
+/dotnet/src/Microsoft.Agents.AI.Anthropic/                      @chetantoshniwal @rogerbarreto @westey-m
+/dotnet/src/Microsoft.Agents.AI.AzureAI.Persistent/             @chetantoshniwal @rogerbarreto @westey-m
+/dotnet/src/Microsoft.Agents.AI.CopilotStudio/                  @chetantoshniwal @rogerbarreto @westey-m
+/dotnet/src/Microsoft.Agents.AI.CosmosNoSql/                    @chetantoshniwal @rogerbarreto @westey-m
+/dotnet/src/Microsoft.Agents.AI.Declarative/                    @chetantoshniwal @peibekwe @westey-m
+/dotnet/src/Microsoft.Agents.AI.DevUI/                          @chetantoshniwal @peibekwe @rogerbarreto @SergeyMenshykh @westey-m
+/dotnet/src/Microsoft.Agents.AI.Foundry/                        @chetantoshniwal @rogerbarreto @westey-m
+/dotnet/src/Microsoft.Agents.AI.Foundry.Hosting/                @chetantoshniwal @rogerbarreto @westey-m
+/dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/                 @chetantoshniwal @rogerbarreto @westey-m
+/dotnet/src/Microsoft.Agents.AI.Harness/                        @chetantoshniwal @westey-m @SergeyMenshykh
+/dotnet/src/Microsoft.Agents.AI.Hosting/                        @chetantoshniwal @rogerbarreto @SergeyMenshykh @westey-m
+/dotnet/src/Microsoft.Agents.AI.Hosting.A2A/                    @chetantoshniwal @rogerbarreto @SergeyMenshykh @westey-m
+/dotnet/src/Microsoft.Agents.AI.Hosting.A2A.AspNetCore/         @chetantoshniwal @rogerbarreto @SergeyMenshykh @westey-m
+/dotnet/src/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore/        @chetantoshniwal @rogerbarreto @SergeyMenshykh @westey-m
+/dotnet/src/Microsoft.Agents.AI.Hosting.AspNetCore/             @chetantoshniwal @rogerbarreto @SergeyMenshykh @westey-m
+/dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/                 @chetantoshniwal @rogerbarreto @SergeyMenshykh @westey-m
+/dotnet/src/Microsoft.Agents.AI.Hyperlight/                     @chetantoshniwal @westey-m @SergeyMenshykh
+/dotnet/src/Microsoft.Agents.AI.LocalCodeAct/                   @chetantoshniwal @westey-m @SergeyMenshykh
+/dotnet/src/Microsoft.Agents.AI.Mcp/                            @chetantoshniwal @westey-m @peibekwe
+/dotnet/src/Microsoft.Agents.AI.Mem0/                           @chetantoshniwal @westey-m @SergeyMenshykh
+/dotnet/src/Microsoft.Agents.AI.OpenAI/                         @chetantoshniwal @westey-m @rogerbarreto
+/dotnet/src/Microsoft.Agents.AI.Purview/                        @chetantoshniwal @westey-m @SergeyMenshykh
+/dotnet/src/Microsoft.Agents.AI.Tools.Shell/                    @chetantoshniwal @westey-m @SergeyMenshykh
+/dotnet/src/Microsoft.Agents.AI.Valkey/                         @chetantoshniwal @westey-m @SergeyMenshykh
+/dotnet/src/Microsoft.Agents.AI.Workflows/                      @chetantoshniwal @peibekwe @rogerbarreto
+/dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/          @chetantoshniwal @peibekwe @rogerbarreto
+/dotnet/src/Microsoft.Agents.AI.Workflows.Declarative.Foundry/  @chetantoshniwal @peibekwe @rogerbarreto
+/dotnet/src/Microsoft.Agents.AI.Workflows.Declarative.Mcp/      @chetantoshniwal @peibekwe @rogerbarreto
+/dotnet/src/Microsoft.Agents.AI.Workflows.Generators/           @chetantoshniwal @peibekwe @rogerbarreto
 
-python/samples/getting_started/azure_functions/ @microsoft/agentframework-durabletask-developers
-python/samples/getting_started/durabletask/ @microsoft/agentframework-durabletask-developers

declarative-agents/workflow-samples/DeepResearch.yaml

@@ -14,6 +14,9 @@
 # - Knowledge Agent: Performs generic web searches.
 # - Coder Agent: Able to write and execute code.
 # - Weather Agent: Provides weather information.
+#  
+# Example input: 
+# Find the current temperatures in Seattle and San Francisco, calculate the difference in Celsius and Fahrenheit, and recommend what clothing to pack for each city.  
 # 
 kind: Workflow
 maxTurns: 500
@@ -264,14 +267,14 @@ trigger:
                       output:
                         messages: Local.Plan
                       input:
+                        arguments:
+                          team: =Local.TeamDescription
                         messages: |-
                           =UserMessage(
                              "Please briefly explain what went wrong on this last run (the root cause of the failure),
                               and then come up with a new plan that takes steps and/or includes hints to overcome prior challenges and especially avoids repeating the same mistakes.
-                              As before, the new plan should be concise, be expressed in bullet-point form, and consider the following team composition
-                              (do not involve any other outside people since we cannot contact anyone else):
-
-                              {Local.TeamDescription}")
+                              As before, the new plan should be concise, be expressed in bullet-point form, and only involve the team members already described
+                              (do not involve any other outside people since we cannot contact anyone else).")
 
                     - kind: SetTextVariable
                       id: setVariable_jW7tmM

docs/specs/004-python-function-calling-loop.md

@@ -342,6 +342,21 @@ that manually replay messages own the equivalent rule: do not resend an approval
 ### Approval request and resume
 
 - A tool that requires approval does not execute before an approved response.
+- With an `AgentSession`, every surfaced local or hosted approval request is stored as an immutable snapshot in one
+  active model batch. A new surfaced batch replaces an abandoned batch instead of accumulating session state.
+- Approval request IDs use the provider function `call_id`, whose conversation-level uniqueness is required for
+  function-call/result correlation. Duplicate request IDs within one batch are rejected as malformed.
+- An inbound response is honored only when its request id matches the pending server-held snapshot.
+- Approval requests replayed in inbound message history do not create, replace, or resurrect approval authority.
+- The executable call id, tool name, arguments, and local or hosted tool metadata are sourced from the recorded
+  request, never from the response payload.
+- A matched approval response consumes its pending entry once. Unmatched, duplicate, and replayed responses do not
+  reach local execution.
+- Tool lookup uses the recorded name against the current registry. A same-name implementation upgrade is allowed;
+  removing the name prevents local execution.
+- Only the strict boolean `True` grants approval. Missing decisions and non-boolean values are rejection, not consent.
+- Direct chat-client invocation without an `AgentSession` preserves pass-through compatibility, matching .NET;
+  authorization sinks still require strict `True`.
 - An approved tool executes exactly once.
 - A rejected tool executes zero times and produces one synthetic rejection `function_result` using the original
   function `call_id`.
@@ -365,6 +380,14 @@ that manually replay messages own the equivalent rule: do not resend an approval
   response for local execution, and leaves hosted approval responses as provider protocol data.
 - Hosted AG-UI approval interrupts expose an accept/reject decision only; argument edits are rejected because the
   hosted provider executes the server-owned request rather than client-edited arguments.
+- AG-UI tool approval resumes accept the standard `approved` decision and full-replacement `editedArgs` payload.
+  Existing MAF clients remain compatible through the `accepted` decision alias and direct partial argument edits.
+- An AG-UI `cancelled` resume is a valid terminal decision, not a run error. In a resume covering parallel open
+  interrupts, resolved siblings still execute and cancelled calls do not. An identical cancellation retry during
+  the retained terminal window also completes normally without restoring authority.
+- AG-UI Approval State capacity is enforced independently for each trusted application scope. Abandoned pending
+  authority expires after its configured window, and indeterminate execution records remain non-retryable until
+  their separate safety window permits reclamation. Reclamation never recreates approval authority.
 - A server-issued approval request must not be replayed inline during service-side continuation.
 - History providers may retain approval control contents in their backing store for audit, but base history replay
   filters them before later model calls.
@@ -413,12 +436,17 @@ that manually replay messages own the equivalent rule: do not resend an approval
 | Rejected streaming resume | Rejection result update precedes final text and tool executes zero times. | `test_approval_resume_returns_result_without_mutating_inputs[streaming-rejected]`, `test_streaming_approval_resume_yields_terminal_result_before_model_text[rejected]` |
 | Mixed approved/rejected batch | Every call gets one correctly correlated terminal result. | `packages/core/tests/core/test_function_invocation_logic.py::test_rejected_approval` |
 | Persisted approval replay | Resume executes with the prior call available. | `test_persisted_approval_messages_replay_correctly` |
-| Hosted approval pass-through | Hosted requests/responses are not processed as local calls. | `test_hosted_tool_approval_response`, `test_hosted_mcp_approval_response_passthrough`, `test_mixed_local_and_hosted_approval_flow` |
+| Hosted approval pass-through | Hosted requests/responses are bound to the recorded provider request and are not processed as local calls. | `test_hosted_tool_approval_response`, `test_hosted_mcp_approval_response_passthrough`, `test_session_approval_binding_reconstructs_hosted_response`, `test_mixed_local_and_hosted_approval_flow` |
 | Approval-time user input | Every user-input request from one approved execution returns in order with assistant role and no extra model call; the execution consumes one call-budget unit. | `packages/core/tests/core/test_harness_tool_approval.py::test_approval_resume_returns_all_user_input_requests_without_another_model_call`, `packages/core/tests/core/test_function_invocation_logic.py::test_approval_resume_user_input_counts_toward_function_call_budget` |
 | Mixed terminal result and follow-up input | Completed siblings remain tool-role while only follow-up input requests use assistant-role messages/updates. | `packages/core/tests/core/test_function_invocation_logic.py::test_approval_resume_separates_terminal_results_from_follow_up_requests`, `packages/openai/tests/openai/test_openai_chat_completion_client.py::test_mixed_approval_resume_roles_serialize_function_result_as_tool` |
 | Approval-time middleware termination | Terminal result returns with no extra model call in either response mode. | `packages/core/tests/core/test_function_invocation_logic.py::test_approval_resume_honors_middleware_termination` |
 | Approval re-entry after iteration budget | Pending approved calls resolve once even when prior model calls consumed `max_iterations`. | `packages/core/tests/core/test_harness_tool_approval.py::test_auto_approval_resolves_after_iteration_budget_is_exhausted` |
 | Approval resume with reasoning | Model-bound resume history retains reasoning before the call and terminal result in both modes. | `packages/core/tests/core/test_harness_tool_approval.py::test_approval_resume_replays_reasoning_with_function_call_group` |
+| Session-bound substituted response | A response is rebound to the immutable recorded call and cannot replace its call id, tool name, or arguments. | `packages/core/tests/core/test_function_invocation_logic.py::test_session_approval_binding_rebinds_consumes_and_rejects_duplicates` |
+| Truthy non-boolean decision | Strings, integers, null, and other non-booleans do not authorize execution. | `packages/core/tests/core/test_function_invocation_logic.py::test_session_approval_binding_treats_truthy_non_boolean_as_rejection`, `packages/core/tests/core/test_types.py::test_function_approval_response_deserialization_rejects_non_boolean_decisions`, `packages/ag-ui/tests/ag_ui/test_message_adapters.py::test_function_approval_requires_real_boolean`, `packages/ag-ui/tests/ag_ui/test_approval_result_event.py::test_resolve_approval_responses_treats_non_boolean_decision_as_rejection` |
+| Active batch replacement | A newly surfaced model batch replaces abandoned approval authority instead of growing session state. | `packages/core/tests/core/test_function_invocation_logic.py::test_session_approval_binding_replaces_abandoned_batch` |
+| Duplicate request id | Ambiguous request IDs within one active batch fail explicitly. | `packages/core/tests/core/test_function_invocation_logic.py::test_session_approval_batch_rejects_duplicate_request_ids` |
+| Tool registry changes | Same-name upgrades may execute the recorded operation; removing the recorded name executes nothing. | `packages/core/tests/core/test_harness_tool_approval.py::test_approval_resume_allows_same_name_tool_upgrade`, `test_approval_resume_does_not_execute_when_recorded_tool_disappears` |
 
 ### Approval correlation and replay
 
@@ -437,6 +465,8 @@ that manually replay messages own the equivalent rule: do not resend an approval
 | Missing result call id | A malformed result does not steal another approval's result. | `test_replace_approval_contents_with_results_skips_results_without_call_id` |
 | Empty approval message cleanup | Fully consumed approval messages are removed from normalized model input. | `test_replace_approval_contents_with_results_prunes_emptied_messages` |
 | Later stateless turn | A prior terminal approval response cannot execute again. | `test_resolved_approval_response_is_inert_on_later_stateless_turn` |
+| Unbound or duplicate response | A response with no pending session request is removed; one request authorizes at most one response. | `test_session_approval_binding_rebinds_consumes_and_rejects_duplicates` |
+| Forged inbound request history | A caller-supplied request wrapper cannot replace the server snapshot or resurrect consumed authority. | `test_session_approval_binding_does_not_trust_inbound_request_history` |
 | Pending history turn | An unresolved approval batch is omitted atomically from unrelated model input while a later decision can still resume it once. | `packages/core/tests/core/test_harness_tool_approval.py::test_pending_approval_from_file_history_stays_resumable_without_model_orphan` |
 | Duplicate function-call prevention | Approval normalization does not create a second call for one round. | `test_no_duplicate_function_calls_after_approval_processing` |
 | Rejection call id | Rejection result uses the function call id, not only the approval id. | `test_rejection_result_uses_function_call_id` |
@@ -454,10 +484,16 @@ that manually replay messages own the equivalent rule: do not resend an approval
 | Auto-approval callback | Callback receives the original function call and executes the approved set once. | `test_tool_approval_middleware_auto_approval_rule_receives_function_call` |
 | Shared call budget | Auto-approved re-entry does not reset `max_function_calls`, and every executed approval group counts even when it pauses for input. | `test_tool_approval_middleware_auto_approved_loops_share_function_call_budget`, `test_approval_resume_user_input_counts_toward_function_call_budget` |
 | Standing tool rule | Tool-level approval applies only to later matching tools. | `test_tool_approval_middleware_always_approve_tool_rule` |
+| Forged standing rule | An unbound or substituted hosted response cannot create a standing middleware approval rule for caller-selected metadata. | `test_tool_approval_middleware_drops_forged_standing_approval`, `test_tool_approval_middleware_rebinds_hosted_standing_approval` |
 | Hosted server boundary | Standing approval does not cross `server_label`. | `test_tool_approval_middleware_standing_rules_include_hosted_server_boundary` |
 | Argument-scoped rule | Exact arguments are required; empty arguments are not tool-wide. | `test_tool_approval_middleware_always_approve_tool_with_arguments_rule`, `test_tool_approval_middleware_empty_arguments_rule_is_not_tool_wide` |
 | Provider-injected approval tool | A tool added during `before_run` defers to in-run resolution, executes once, and emits one result. | `packages/ag-ui/tests/ag_ui/test_endpoint.py::test_endpoint_agent_approval_deferred_provider_tool_executes` |
 | AG-UI provider boundary | Completed local approval controls from AG-UI request and snapshot replay are absent from raw chat-client input while deferred and hosted approvals keep their respective in-run/provider paths. | `packages/ag-ui/tests/ag_ui/test_endpoint.py::test_endpoint_does_not_forward_resolved_local_approval_control_to_chat_client`, `packages/ag-ui/tests/ag_ui/test_endpoint.py::test_endpoint_agent_approval_deferred_provider_tool_executes`, `packages/ag-ui/tests/ag_ui/test_endpoint.py::test_endpoint_canonical_resume_preserves_hosted_approval_for_provider`, `packages/ag-ui/tests/ag_ui/test_run.py::test_filter_local_approval_responses_for_provider_removes_duplicate_completed_controls`, `packages/ag-ui/tests/ag_ui/test_run.py::test_filter_local_approval_responses_for_provider_pairs_reused_call_ids_by_occurrence`, `packages/ag-ui/tests/ag_ui/test_run.py::test_canonical_hosted_approval_resume_rejects_edited_arguments_without_mutating_pending` |
+| AG-UI standard approval payload | Agent and workflow tool approvals emit canonical `tool_call` interrupts. `approved` plus full-replacement `editedArgs` executes once and replays idempotently, while legacy `accepted` plus direct partial edits remains supported. Hosted approvals remain decision-only. | `packages/ag-ui/tests/ag_ui/test_endpoint.py::test_endpoint_agent_approval_resume_entry_applies_standard_full_replacement_edited_args`, `test_endpoint_agent_approval_replayed_standard_edited_resume_is_idempotent`, `test_endpoint_agent_approval_resume_entry_applies_edited_arguments`, `test_workflow_endpoint_emits_canonical_tool_approval_interrupt`, `test_workflow_endpoint_accepts_canonical_tool_approval_resume`, `test_workflow_endpoint_applies_canonical_approval_edited_args`, `test_workflow_endpoint_accepts_legacy_partial_approval_edits`, `test_workflow_endpoint_hosted_approval_rejects_argument_edits` |
+| AG-UI cancellation | A cancelled interrupt executes zero times and completes normally, including an identical retry during retained cancellation state; resolved siblings in the same complete resume still execute once. Workflow cancellation clears both runner correlation and the owning agent executor's pending request so later approvals remain resumable. | `packages/ag-ui/tests/ag_ui/test_endpoint.py::test_endpoint_agent_approval_cancelled_resume_entry_completes_without_execution`, `test_endpoint_agent_approval_replayed_cancellation_completes_idempotently`, `test_endpoint_agent_approval_mixed_cancelled_and_resolved_resume_executes_resolved_tool`, `test_endpoint_workflow_request_info_cancelled_resume_completes_normally`, `test_workflow_endpoint_cancelled_agent_approval_does_not_block_next_approval` |
+| AG-UI approval retention and capacity | Pending authority expires automatically, indeterminate outcomes remain non-retryable until their safety window permits reclamation, and one trusted scope cannot consume another scope's occurrence quota. | `packages/ag-ui/tests/ag_ui/test_approval_lifecycle.py::test_abandoned_pending_occurrence_expires_and_releases_capacity`, `test_indeterminate_occurrence_is_reclaimed_after_its_safety_window`, `test_capacity_is_enforced_per_trusted_scope` |
+| AG-UI local executor unavailable on resume | A claimed local occurrence whose executor disappeared releases its unstarted claim, reports temporary unavailability, and remains safely retryable. | `packages/ag-ui/tests/ag_ui/test_endpoint.py::test_endpoint_agent_approval_resume_remains_retryable_when_local_tool_is_temporarily_unavailable` |
+| AG-UI forwarded execution interruption | A provider failure, cancellation, or stream close after forwarding an approval recovers the open occurrence as indeterminate when no idempotency key proves retry safety. | `packages/ag-ui/tests/ag_ui/test_endpoint.py::test_endpoint_hosted_approval_becomes_indeterminate_when_provider_stream_fails` |
 
 ### Errors, control flow, and limits
 
@@ -493,11 +529,11 @@ that manually replay messages own the equivalent rule: do not resend an approval
 | Foundry encrypted reasoning opt-in | Foundry clients omit `reasoning.encrypted_content` by default and preserve an explicit caller opt-in. | `packages/foundry/tests/foundry/test_foundry_chat_client.py::test_get_response_does_not_request_encrypted_reasoning_by_default`, `test_get_response_preserves_explicit_encrypted_reasoning_opt_in`, `packages/foundry/tests/foundry/test_foundry_agent.py::test_foundry_agent_basic_call_does_not_request_unsupported_encrypted_reasoning`, `test_foundry_agent_preserves_caller_requested_encrypted_reasoning`, `packages/foundry_hosting/tests/test_responses_int.py::TestReasoningHostedMcpReplay::test_second_turn_replays_mcp_call_with_encrypted_reasoning` |
 | Opaque reasoning signature replay | Provider-specific opaque reasoning metadata is captured and restored on reconstructed calls. | `packages/gemini/tests/test_gemini_client.py::test_function_call_part_captures_thought_signature_as_reasoning_content`, `test_reconstructed_function_call_replays_thought_signature_from_reasoning_content` |
 | Chat Completions approval wrappers | Framework approval wrappers are not sent as chat messages. | `packages/openai/tests/openai/test_openai_chat_completion_client.py` approval serialization tests |
-| AG-UI approval result event | Approved result emits once with content and persists in snapshot. | `packages/ag-ui/tests/ag_ui/test_approval_result_event.py::test_approval_resume_emits_tool_call_result`, `test_approval_resume_result_has_content`, `test_approval_resume_snapshot_replaces_approval_payload_with_tool_result`, `test_approval_resume_zero_updates_emits_tool_result` |
-| AG-UI rejection/mixed decision | Transport emits only the events defined for approved and rejected calls without duplicates. | `test_rejection_does_not_emit_tool_call_result`, `test_mixed_approve_reject_emits_only_approved_tool_result`, `test_resolve_approval_responses_returns_only_approved` |
-| AG-UI approval-time follow-up | The full grouped user-input pause remains in message history and emits no synthetic `TOOL_CALL_RESULT`. | `test_resolve_approval_responses_preserves_follow_up_user_input_group` |
-| AG-UI approval execution failure | A grouped executor failure becomes one deterministic terminal error result for the approved call. | `test_resolve_approval_responses_returns_failure_when_grouped_execution_raises` |
-| AG-UI no-approval path | Ordinary tool results do not gain an extra approval result event. | `test_no_approval_no_extra_tool_result` |
+| AG-UI approval result event | Approved result emits once with content and persists in snapshot. | `packages/ag-ui/tests/ag_ui/test_approval_result_event.py::test_approved_call_emits_one_live_result_under_original_identity`, `packages/ag-ui/tests/ag_ui/test_endpoint.py::test_endpoint_agent_approval_resume_persists_replayable_tool_results`, `test_endpoint_agent_approval_replayed_resume_entry_reprojects_retained_result` |
+| AG-UI rejection/mixed decision | Transport emits only the events defined for approved and rejected calls without duplicates. | `packages/ag-ui/tests/ag_ui/test_approval_result_event.py::test_rejected_call_does_not_execute_or_emit_live_result`, `test_mixed_batch_preserves_approved_result_identity_and_order`, `packages/ag-ui/tests/ag_ui/test_endpoint.py::test_endpoint_agent_approval_rejection_releases_already_approved_sibling` |
+| AG-UI approval-time follow-up | The full grouped user-input pause remains in message history and emits no synthetic `TOOL_CALL_RESULT`. | `packages/ag-ui/tests/ag_ui/test_approval_result_event.py::test_approval_follow_up_group_remains_in_history_without_live_tool_result` |
+| AG-UI approval execution failure | A grouped executor failure becomes one deterministic terminal error result for the approved call. | `packages/ag-ui/tests/ag_ui/test_approval_result_event.py::test_approval_execution_failure_emits_one_terminal_error_result` |
+| AG-UI no-approval path | Ordinary tool results do not gain an extra approval result event. | `packages/ag-ui/tests/ag_ui/test_approval_result_event.py::test_no_approval_path_emits_no_approval_specific_duplicate_result` |
 | AG-UI `confirm_changes` snapshot | An accepted synthetic confirmation is replaced only when its original function call has a real result; rejection is cleaned explicitly, and missing accepted results remain inert. | `packages/ag-ui/tests/ag_ui/test_confirm_changes_snapshot.py` |
 | AG-UI malformed `confirm_changes` metadata | Non-list tool-call metadata and malformed argument JSON are ignored without guessing a target call. | `test_confirm_changes_target_ignores_non_list_tool_calls`, `test_confirm_changes_target_rejects_malformed_arguments_json` |
 | Compaction pair integrity | Adjacent and non-adjacent pairs, including assistant-embedded results and completed reused-id occurrences, remain atomic without pairing ambiguous or out-of-order ids. | `packages/core/tests/core/test_compaction.py::test_group_annotations_keep_tool_call_and_tool_result_atomic`, `test_group_annotations_include_reasoning_in_tool_call_group`, `test_group_annotations_pair_nonadjacent_function_result_by_call_id`, `test_group_annotations_pair_multiple_nonadjacent_results_with_declaration`, `test_group_annotations_pair_completed_reused_call_id_occurrences`, `test_group_annotations_close_assistant_embedded_result_before_reused_call_id`, `test_sliding_window_does_not_retain_orphan_result_after_assistant_embedded_result`, `test_sliding_window_keeps_reused_call_id_occurrences_atomic`, `test_group_annotations_do_not_pair_ambiguous_duplicate_call_ids` |
@@ -531,6 +567,7 @@ uv run poe syntax -P openai
 uv run poe pyright -P openai
 uv run poe test-typing -P openai
 uv run poe test -P ag-ui
+uv run poe test -P declarative
 uv run --directory packages/foundry_hosting poe test
 ```
 

docs/specs/feature-usage-bit-registry.md

@@ -136,7 +136,8 @@ only to approved first-party endpoints.
 | 15 | `core.in_memory_skills_source` | In-memory / programmatic skills | `agent_framework.InMemorySkillsSource` |
 | 16 | `core.mcp_skills_source` | MCP-backed skills | `agent_framework.MCPSkillsSource` |
 | 17 | `core.session_store` | Agent session store | `agent_framework.SessionStore` / `FileSessionStore` |
-| 18–31 | _reserved_ | core growth | — |
+| 18 | `core.agent_hooks` | Agent Hooks middleware | `agent_framework.create_agent_hooks_middleware` |
+| 19–31 | _reserved_ | core growth | — |
 | 32 | `orchestration.sequential` | Sequential orchestration | `agent_framework_orchestrations.SequentialBuilder` |
 | 33 | `orchestration.concurrent` | Concurrent orchestration | `agent_framework_orchestrations.ConcurrentBuilder` |
 | 34 | `orchestration.group_chat` | Group-chat orchestration | `agent_framework_orchestrations.GroupChatBuilder` |

dotnet/global.json

@@ -1,6 +1,6 @@
 {
     "sdk": {
-        "version": "10.0.302",
+        "version": "10.0.303",
         "rollForward": "minor",
         "allowPrerelease": false
     },

dotnet/nuget/nuget-package.props

@@ -1,14 +1,14 @@
 <Project>
   <PropertyGroup>
     <!-- Central version prefix - applies to all nuget packages. -->
-    <VersionPrefix>1.17.0</VersionPrefix>
+    <VersionPrefix>1.18.0</VersionPrefix>
     <RCNumber>1</RCNumber>
-    <DateSuffix>260804</DateSuffix>
+    <DateSuffix>260818</DateSuffix>
     <PackageVersion Condition="'$(IsReleaseCandidate)' == 'true'">$(VersionPrefix)-rc$(RCNumber)</PackageVersion>
     <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).$(DateSuffix).1</PackageVersion>
     <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' == ''">$(VersionPrefix)-preview.$(DateSuffix).1</PackageVersion>
     <PackageVersion Condition="'$(IsReleased)' == 'true'">$(VersionPrefix)</PackageVersion>
-    <GitTag>1.17.0</GitTag>
+    <GitTag>1.18.0</GitTag>
 
     <Configurations>Debug;Release;Publish</Configurations>
     <IsPackable>true</IsPackable>

dotnet/samples/02-agents/AgentWithRAG/AgentWithRAG_Step01_BasicTextRAG/Program.cs

@@ -37,7 +37,7 @@ TextSearchStore textSearchStore = new(vectorStore, "product-and-policy-info", 30
 await textSearchStore.UpsertDocumentsAsync(GetSampleDocuments());
 
 // Create an adapter function that the TextSearchProvider can use to run searches against the TextSearchStore.
-Func<string, CancellationToken, Task<IEnumerable<TextSearchProvider.TextSearchResult>>> SearchAdapter = async (text, ct) =>
+async Task<IEnumerable<TextSearchProvider.TextSearchResult>> SearchAdapterAsync(string text, CancellationToken ct)
 {
     // Here we are limiting the search results to the single top result to demonstrate that we are accurately matching
     // specific search results for each question, but in a real world case, more results should be used.
@@ -49,7 +49,7 @@ Func<string, CancellationToken, Task<IEnumerable<TextSearchProvider.TextSearchRe
         Text = r.Text ?? string.Empty,
         RawRepresentation = r
     });
-};
+}
 
 // Configure the options for the TextSearchProvider.
 TextSearchProviderOptions textSearchOptions = new()
@@ -63,7 +63,7 @@ AIAgent agent = aiProjectClient
     .AsAIAgent(new ChatClientAgentOptions
     {
         ChatOptions = new() { ModelId = deploymentName, Instructions = "You are a helpful support specialist for Contoso Outdoors. Answer questions using the provided context and cite the source document when available." },
-        AIContextProviders = [new TextSearchProvider(SearchAdapter, textSearchOptions)],
+        AIContextProviders = [new TextSearchProvider(SearchAdapterAsync, textSearchOptions)],
         // Since we are using ChatCompletion which stores chat history locally, we can also add a message filter
         // that removes messages produced by the TextSearchProvider before they are added to the chat history, so that
         // we don't bloat chat history with all the search result messages.

dotnet/samples/02-agents/AgentWithRAG/AgentWithRAG_Step02_CustomVectorStoreRAG/Program.cs

@@ -40,7 +40,7 @@ await UploadDataFromMarkdown(afOverviewUrl, "Microsoft Agent Framework Overview"
 await UploadDataFromMarkdown(afMigrationUrl, "Semantic Kernel to Microsoft Agent Framework Migration Guide", documentationCollection, 2000, 200);
 
 // Create an adapter function that the TextSearchProvider can use to run searches against the collection.
-Func<string, CancellationToken, Task<IEnumerable<TextSearchProvider.TextSearchResult>>> SearchAdapter = async (text, ct) =>
+async Task<IEnumerable<TextSearchProvider.TextSearchResult>> SearchAdapterAsync(string text, CancellationToken ct)
 {
     List<TextSearchProvider.TextSearchResult> results = [];
     await foreach (var result in documentationCollection.SearchAsync(text, 5, cancellationToken: ct))
@@ -54,7 +54,7 @@ Func<string, CancellationToken, Task<IEnumerable<TextSearchProvider.TextSearchRe
         });
     }
     return results;
-};
+}
 
 // Configure the options for the TextSearchProvider.
 TextSearchProviderOptions textSearchOptions = new()
@@ -72,7 +72,7 @@ AIAgent agent = aiProjectClient
     .AsAIAgent(new ChatClientAgentOptions
     {
         ChatOptions = new() { ModelId = deploymentName, Instructions = "You are a helpful support specialist for the Microsoft Agent Framework. Answer questions using the provided context and cite the source document when available. Keep responses brief." },
-        AIContextProviders = [new TextSearchProvider(SearchAdapter, textSearchOptions)],
+        AIContextProviders = [new TextSearchProvider(SearchAdapterAsync, textSearchOptions)],
         // Configure a filter on the InMemoryChatHistoryProvider so that we don't persist the messages produced by the TextSearchProvider in chat history.
         // The default is to persist all messages except those that came from chat history in the first place.
         // You may choose to persist the TextSearchProvider messages, if you want the search output to be provided to the model in future interactions as well.

dotnet/samples/02-agents/Agents/Agent_Step17_AdditionalAIContext/Program.cs

@@ -23,7 +23,7 @@ var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ??
 var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
 
 // A sample function to load the next three calendar events for the user.
-Func<Task<string[]>> loadNextThreeCalendarEvents = async () =>
+async Task<string[]> LoadNextThreeCalendarEventsAsync()
 {
     // In a real implementation, this method would connect to a calendar service
     return
@@ -32,7 +32,7 @@ Func<Task<string[]>> loadNextThreeCalendarEvents = async () =>
         "Team meeting today at 17:00",
         "Birthday party today at 20:00"
     ];
-};
+}
 
 // Create an agent with an AI context provider attached that aggregates two other providers.
 // You must dissable client side conversation storage for clients that support it:
@@ -64,7 +64,7 @@ AIAgent agent = new AIProjectClient(
         // The agent will call each provider in sequence, accumulating context from each.
         AIContextProviders = [
             new TodoListAIContextProvider(),
-            new CalendarSearchAIContextProvider(loadNextThreeCalendarEvents)
+            new CalendarSearchAIContextProvider(LoadNextThreeCalendarEventsAsync)
         ],
     });
 

dotnet/samples/03-workflows/Declarative/DeepResearch/Program.cs

@@ -123,20 +123,27 @@ internal sealed class Program
     private static DeclarativeAgentDefinition DefinePlannerAgent(IConfiguration configuration) =>
         new(configuration.GetValue(Application.Settings.FoundryModel))
         {
-            Instructions = // TODO: Use Structured Inputs / Prompt Template
+            Instructions =
                 """
                 Your only job is to devise an efficient plan that identifies (by name) how a team member may contribute to addressing the user request.
 
                 Only select the following team which is listed as "- [Name]: [Description]"
 
-                - WeatherAgent: Able to retrieve weather information
-                - CoderAgent: Able to write and execute Python code
-                - KnowledgeAgent: Able to perform generic websearches
+                {{team}}
 
                 The plan must be a bullet point list must be in the form "- [AgentName]: [Specific action or task for that agent to perform]"
   
                 Remember, there is no requirement to involve the entire team -- only select team member's whose particular expertise is required for this task.
-                """
+                """,
+            StructuredInputs =
+            {
+                ["team"] =
+                    new StructuredInputDefinition
+                    {
+                        IsRequired = true,
+                        Description = "The available team members and their capabilities.",
+                    }
+            }
         };
 
     private static DeclarativeAgentDefinition DefineManagerAgent(IConfiguration configuration) =>
@@ -151,7 +158,7 @@ internal sealed class Program
                 - WeatherAgent: Able to retrieve weather information
                                 
                 To make progress on the request, please answer the following questions, including necessary reasoning:
-                - Is the request fully satisfied? (True if complete, or False if the original request has yet to be SUCCESSFULLY and FULLY addressed)
+                - Is the request fully satisfied? (True if the requested work is complete and enough information is available to provide the final answer. A verified negative or empty result, such as confirming that a requested resource does not exist, can fully satisfy the request. False if work remains or if a negative or empty result may be caused by an execution, authorization, connectivity, or investigation failure.)
                 - Are we in a loop where we are repeating the same requests and / or getting the same responses from an agent multiple times? Loops can span multiple turns, and can include repeated actions like scrolling up or down more than a handful of times.
                 - Are we making forward progress? (True if just starting, or recent messages are adding value. False if recent messages show evidence of being stuck in a loop or if there is evidence of significant barriers to success such as the inability to read from a required file)
                 - Who should speak next? (select from: KnowledgeAgent, CoderAgent, WeatherAgent) 

dotnet/src/Microsoft.Agents.AI.CosmosNoSql/CosmosChatHistoryProvider.cs

@@ -215,7 +215,26 @@ public sealed class CosmosChatHistoryProvider : ChatHistoryProvider, IDisposable
     }
 
     /// <inheritdoc />
-    protected override async ValueTask<IEnumerable<ChatMessage>> ProvideChatHistoryAsync(InvokingContext context, CancellationToken cancellationToken = default)
+    protected override ValueTask<IEnumerable<ChatMessage>> ProvideChatHistoryAsync(InvokingContext context, CancellationToken cancellationToken = default) =>
+        new(this.GetMessagesAsync(context.Session, cancellationToken));
+
+    /// <summary>
+    /// Gets the messages stored for the specified session.
+    /// </summary>
+    /// <param name="session">The agent session to get state from.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>
+    /// The messages in the timestamp-based order used by the agent invocation pipeline. Messages with equal stored
+    /// timestamps have no guaranteed relative order. When <see cref="MaxMessagesToRetrieve"/> is set, messages with
+    /// the latest timestamps are selected; if the limit intersects a timestamp tie, which tied messages are included
+    /// is unspecified.
+    /// </returns>
+    /// <remarks>
+    /// This method returns messages as stored and does not apply the output filter or chat-history source attribution
+    /// used by the agent invocation pipeline. Use <see cref="ChatHistoryProvider.InvokingAsync"/> when that processing
+    /// is required. <see cref="MaxItemCount"/> controls the query page size.
+    /// </remarks>
+    public async Task<IEnumerable<ChatMessage>> GetMessagesAsync(AgentSession? session, CancellationToken cancellationToken = default)
     {
 #pragma warning disable CA1513 // Use ObjectDisposedException.ThrowIf - not available on all target frameworks
         if (this._disposed)
@@ -224,7 +243,7 @@ public sealed class CosmosChatHistoryProvider : ChatHistoryProvider, IDisposable
         }
 #pragma warning restore CA1513
 
-        var state = this._sessionState.GetOrInitializeState(context.Session);
+        var state = this._sessionState.GetOrInitializeState(session);
         var partitionKey = BuildPartitionKey(state);
 
         // Fetch most recent messages in descending order when limit is set, then reverse to ascending
@@ -233,7 +252,7 @@ public sealed class CosmosChatHistoryProvider : ChatHistoryProvider, IDisposable
             .WithParameter("@conversationId", state.ConversationId)
             .WithParameter("@type", "ChatMessage");
 
-        var iterator = this._container.GetItemQueryIterator<CosmosMessageDocument>(query, requestOptions: new QueryRequestOptions
+        using var iterator = this._container.GetItemQueryIterator<CosmosMessageDocument>(query, requestOptions: new QueryRequestOptions
         {
             PartitionKey = partitionKey,
             MaxItemCount = this.MaxItemCount // Configurable query performance

dotnet/src/Microsoft.Agents.AI.Foundry.Hosting/AgentFrameworkResponseHandler.cs

@@ -514,9 +514,12 @@ public class AgentFrameworkResponseHandler : ResponseHandler
 
         if (notAllowedStoreUsageDetected)
         {
-            this._logger.LogError(
-                "Agent '{AgentName}' should not have server side storage enabled. This produced a new untracked conversation/response in the server while the hosted agent also generated a conversation for the request of the agent.",
-                agent.Name);
+            if (this._logger.IsEnabled(LogLevel.Error))
+            {
+                this._logger.LogError(
+                    "Agent '{AgentName}' should not have server side storage enabled. This produced a new untracked conversation/response in the server while the hosted agent also generated a conversation for the request of the agent.",
+                    agent.Name);
+            }
 
             throw HostedStoredOutputCompatibility.CreateMisconfiguredAgentError();
         }

dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgent.cs

@@ -135,7 +135,7 @@ public sealed class FoundryAgent : DelegatingAIAgent
     /// <see cref="AIProjectClient"/> reference here.
     /// </summary>
     internal FoundryAgent(ChatClientAgent innerAgent)
-        : base(WireClientHeaders(Throw.IfNull(innerAgent)))
+        : base(WireFoundryRequestContext(Throw.IfNull(innerAgent)))
     {
     }
 
@@ -162,6 +162,59 @@ public sealed class FoundryAgent : DelegatingAIAgent
     public ValueTask<AgentSession> CreateSessionAsync(string conversationId, CancellationToken cancellationToken = default)
         => this.GetInnerChatClientAgent().CreateSessionAsync(conversationId, cancellationToken);
 
+    /// <summary>
+    /// Creates a local <see cref="ChatClientAgentSession"/> optionally pinned to a Foundry hosted-agent
+    /// session id (sandbox) and/or a server conversation id.
+    /// </summary>
+    /// <param name="hostedSessionId">
+    /// Optional existing hosted-agent session id to pin on the session. The id identifies a Foundry
+    /// infrastructure managed sandbox (compute and persistent <c>$HOME</c>), not Agent Framework local
+    /// state. See
+    /// <see href="https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/hosted-agents#sessions-and-conversations">Sessions and conversations</see>.
+    /// When set, it is stored in <see cref="AgentSession.StateBag"/> under
+    /// <see cref="FoundryAgentSessionExtensions.FoundryHostedAgentSessionIdKey"/> and subsequent runs that
+    /// reuse this session send <c>agent_session_id</c> automatically. When omitted, Foundry may create
+    /// a session on the first run and the returned id becomes sticky on this session.
+    /// </param>
+    /// <param name="conversationId">
+    /// Optional existing conversation id for server-side message history continuity. Conversation
+    /// history and hosted-agent session (sandbox) are separate Foundry concepts; see
+    /// <see href="https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/hosted-agents#sessions-and-conversations">Sessions and conversations</see>.
+    /// </param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests.</param>
+    /// <returns>A <see cref="ChatClientAgentSession"/> with the optional pins applied.</returns>
+    /// <remarks>
+    /// <para>
+    /// The hosted-agent session itself is owned and lifecycle managed by Foundry Agent Service
+    /// (provisioning, idle suspend, TTL). This method only builds a local Agent Framework session
+    /// object and optionally attaches an existing platform session id. It does not call the Foundry
+    /// admin API to provision a sandbox. To create a platform session first, use the agent
+    /// administration client and pass the resulting id as <paramref name="hostedSessionId"/>.
+    /// </para>
+    /// <para>
+    /// For the platform model of sessions versus conversations, see
+    /// <see href="https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/hosted-agents#sessions-and-conversations">Hosted agents: sessions and conversations</see>.
+    /// </para>
+    /// </remarks>
+    public async Task<ChatClientAgentSession> CreateFoundryHostedAgentSessionAsync(
+        string? hostedSessionId = null,
+        string? conversationId = null,
+        CancellationToken cancellationToken = default)
+    {
+        AgentSession session = conversationId is null
+            ? await this.CreateSessionAsync(cancellationToken).ConfigureAwait(false)
+            : await this.CreateSessionAsync(conversationId, cancellationToken).ConfigureAwait(false);
+
+        var typed = (ChatClientAgentSession)session;
+        if (hostedSessionId is not null)
+        {
+            // Non-null values are treated as an explicit pin attempt; whitespace is rejected by Set.
+            typed.FoundryHostedAgentSessionId = hostedSessionId;
+        }
+
+        return typed;
+    }
+
     /// <summary>
     /// Creates a server-side conversation session that appears in the Foundry Project UI.
     /// </summary>
@@ -240,23 +293,21 @@ public sealed class FoundryAgent : DelegatingAIAgent
             chatClient = clientFactory(chatClient);
         }
 
-        return WireClientHeaders(new ChatClientAgent(chatClient, agentOptions, loggerFactory, services));
+        return WireFoundryRequestContext(new ChatClientAgent(chatClient, agentOptions, loggerFactory, services));
     }
 
     /// <summary>
-    /// Registers <see cref="ClientHeadersPolicy"/> on the agent's underlying chat client (if it
-    /// exposes <see cref="OpenAIRequestPolicies"/>) and wraps the agent in a
-    /// <see cref="ClientHeadersAgent"/> so per-call <c>x-client-*</c> headers stamped via
-    /// <see cref="ClientHeadersExtensions.WithClientHeader(ChatOptions, string, string)"/> reach
-    /// the wire. Idempotent: if the chain already contains a <see cref="ClientHeadersAgent"/>,
-    /// the original instance is returned unchanged.
+    /// Registers Foundry per-call pipeline policies and wraps the agent so request-scoped
+    /// headers/body fields reach the wire:
+    /// <list type="bullet">
+    /// <item><description><c>x-client-*</c> via <see cref="ClientHeadersAgent"/> / <see cref="ClientHeadersPolicy"/></description></item>
+    /// <item><description><c>x-ms-user-identity</c> and sticky <c>agent_session_id</c> via <see cref="FoundryHostedRequestAgent"/></description></item>
+    /// </list>
+    /// Idempotent per decorator type.
     /// </summary>
-    private static AIAgent WireClientHeaders(ChatClientAgent innerAgent)
+    private static AIAgent WireFoundryRequestContext(ChatClientAgent innerAgent)
     {
-        if (innerAgent.GetService<ClientHeadersAgent>() is not null)
-        {
-            return innerAgent;
-        }
+        AIAgent agent = innerAgent;
 
 #pragma warning disable MEAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
         if (innerAgent.ChatClient.GetService<OpenAIRequestPolicies>() is { } policies)
@@ -265,10 +316,28 @@ public sealed class FoundryAgent : DelegatingAIAgent
                 policies,
                 ClientHeadersPolicy.Instance,
                 PipelinePosition.PerCall);
+            OpenAIRequestPoliciesReflection.AddPolicyIfMissing(
+                policies,
+                UserIdentityPolicy.Instance,
+                PipelinePosition.PerCall);
+            OpenAIRequestPoliciesReflection.AddPolicyIfMissing(
+                policies,
+                HostedSessionIdCapturePolicy.Instance,
+                PipelinePosition.PerCall);
         }
 #pragma warning restore MEAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
 
-        return new ClientHeadersAgent(innerAgent);
+        if (agent.GetService<ClientHeadersAgent>() is null)
+        {
+            agent = new ClientHeadersAgent(agent);
+        }
+
+        if (agent.GetService<FoundryHostedRequestAgent>() is null)
+        {
+            agent = new FoundryHostedRequestAgent(agent);
+        }
+
+        return agent;
     }
 
     /// <summary>
@@ -303,7 +372,7 @@ public sealed class FoundryAgent : DelegatingAIAgent
             ChatOptions = new() { Tools = tools },
         };
 
-        return WireClientHeaders(new ChatClientAgent(chatClient, agentOptions, services: services));
+        return WireFoundryRequestContext(new ChatClientAgent(chatClient, agentOptions, services: services));
     }
 
     /// <summary>
@@ -336,7 +405,7 @@ public sealed class FoundryAgent : DelegatingAIAgent
             ChatOptions = new() { Tools = tools },
         };
 
-        return WireClientHeaders(new ChatClientAgent(chatClient, agentOptions, services: services));
+        return WireFoundryRequestContext(new ChatClientAgent(chatClient, agentOptions, services: services));
     }
 
     /// <summary>

dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgentSessionExtensions.cs

@@ -0,0 +1,77 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Agents.AI.Foundry;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Foundry-specific extension methods for <see cref="AgentSession"/>.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The hosted-agent session id (sandbox / <c>agent_session_id</c>) is stored in
+/// <see cref="AgentSession.StateBag"/> under <see cref="FoundryHostedAgentSessionIdKey"/>. That keeps
+/// Foundry-specific state off the sealed <see cref="ChatClientAgentSession"/> type while still
+/// serializing with the session.
+/// </para>
+/// <para>
+/// This is not <see cref="Extensions.AI.ChatOptions.AdditionalProperties"/>. Per-call
+/// overrides use
+/// <see cref="Extensions.AI.FoundryChatOptionsExtensions.WithFoundryHostedAgentSessionId(Extensions.AI.ChatOptions, string)"/>.
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AIOpenAIRequestPolicies)]
+public static class FoundryAgentSessionExtensions
+{
+    /// <summary>
+    /// Well-known <see cref="AgentSessionStateBag"/> key for the sticky hosted-agent session id.
+    /// </summary>
+    public const string FoundryHostedAgentSessionIdKey = "Microsoft.Agents.AI.Foundry.HostedAgentSessionId";
+
+    extension(AgentSession session)
+    {
+        /// <summary>
+        /// Gets the sticky Microsoft Foundry hosted-agent session id associated with this
+        /// Agent Framework session.
+        /// </summary>
+        /// <value>
+        /// The Foundry <c>agent_session_id</c>, or <see langword="null"/> when no hosted sandbox
+        /// has been pinned or captured yet.
+        /// </value>
+        /// <remarks>
+        /// <para>
+        /// This id identifies the Foundry-managed hosted-agent sandbox: its compute, persisted
+        /// <c>$HOME</c>, and files. It is separate from
+        /// <see cref="ChatClientAgentSession.ConversationId"/>, which identifies conversation
+        /// history.
+        /// </para>
+        /// <para>
+        /// Prefer creating or pinning through
+        /// <see cref="FoundryAgent.CreateFoundryHostedAgentSessionAsync(string?, string?, System.Threading.CancellationToken)"/>.
+        /// The property is populated automatically when Foundry creates a sandbox on first use.
+        /// See
+        /// <see href="https://learn.microsoft.com/azure/foundry/agents/how-to/manage-hosted-sessions#sessions-versus-conversations">Manage hosted agent sessions</see>.
+        /// </para>
+        /// </remarks>
+        public string? FoundryHostedAgentSessionId
+        {
+            get
+            {
+                _ = Throw.IfNull(session);
+                return session.StateBag.TryGetValue<string>(FoundryHostedAgentSessionIdKey, out var value)
+                    ? value
+                    : null;
+            }
+
+            internal set
+            {
+                _ = Throw.IfNull(session);
+                _ = Throw.IfNullOrWhitespace(value);
+                session.StateBag.SetValue(FoundryHostedAgentSessionIdKey, value);
+            }
+        }
+    }
+}

dotnet/src/Microsoft.Agents.AI.Foundry/FoundryChatOptionsExtensions.cs

@@ -0,0 +1,143 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Foundry-specific extension methods for <see cref="ChatOptions"/>.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Use these helpers to attach per-call Foundry request fields:
+/// <list type="bullet">
+/// <item><description><see cref="WithFoundryHostedAgentSessionId"/> sends <c>agent_session_id</c> on the Responses body.</description></item>
+/// <item><description><see cref="WithFoundryHostedAgentUserIdentity"/> sends <c>x-ms-user-identity</c> on the request.</description></item>
+/// </list>
+/// </para>
+/// <para>
+/// Hosted-agent session ids supplied via <see cref="WithFoundryHostedAgentSessionId"/> participate in the same
+/// conflict rule as <see cref="ChatOptions.ConversationId"/>: if the <see cref="AgentSession"/> already
+/// holds a different hosted id in its <see cref="AgentSession.StateBag"/>, the run throws
+/// <see cref="System.InvalidOperationException"/>. Prefer pinning at session creation via
+/// <see cref="FoundryAgent.CreateFoundryHostedAgentSessionAsync(string?, string?, System.Threading.CancellationToken)"/>.
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AIOpenAIRequestPolicies)]
+public static class FoundryChatOptionsExtensions
+{
+    /// <summary>HTTP header name for delegated application user identity.</summary>
+    public const string FoundryHostedAgentUserIdentityHeaderName = "x-ms-user-identity";
+
+    /// <summary>
+    /// Well-known <see cref="ChatOptions.AdditionalProperties"/> key used to carry a per-call
+    /// hosted-agent session id.
+    /// </summary>
+    internal const string FoundryHostedAgentSessionIdKey = "Microsoft.Agents.AI.Foundry.HostedAgentSessionId";
+
+    /// <summary>
+    /// Well-known <see cref="ChatOptions.AdditionalProperties"/> key used to carry the per-call
+    /// user identity value.
+    /// </summary>
+    internal const string FoundryHostedAgentUserIdentityKey = "Microsoft.Agents.AI.Foundry.UserIdentity";
+
+    /// <summary>
+    /// Attaches a hosted-agent session id to the per-call <paramref name="options"/> carrier.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Only valid when the run's session has no hosted id yet, or already has this same id.
+    /// Prefer
+    /// <see cref="FoundryAgent.CreateFoundryHostedAgentSessionAsync(string?, string?, System.Threading.CancellationToken)"/>
+    /// to pin at session creation.
+    /// </para>
+    /// <para>
+    /// The value is stored in <see cref="ChatOptions.AdditionalProperties"/>. Replacing that
+    /// dictionary after calling this method removes the value; populate or replace the dictionary
+    /// first, then call this method.
+    /// </para>
+    /// </remarks>
+    public static ChatOptions WithFoundryHostedAgentSessionId(this ChatOptions options, string hostedSessionId)
+    {
+        _ = Throw.IfNull(options);
+        _ = Throw.IfNullOrWhitespace(hostedSessionId);
+
+        options.AdditionalProperties ??= new AdditionalPropertiesDictionary();
+        options.AdditionalProperties[FoundryHostedAgentSessionIdKey] = hostedSessionId;
+        return options;
+    }
+
+    /// <summary>
+    /// Attaches a delegated user identity value that will be sent as the
+    /// <c>x-ms-user-identity</c> request header.
+    /// </summary>
+    /// <param name="options">The per-call chat options to mutate.</param>
+    /// <param name="userIdentity">Opaque application user identifier. Must be non-empty.</param>
+    /// <returns><paramref name="options"/> for fluent chaining.</returns>
+    /// <remarks>
+    /// <para>
+    /// User identity is always request-scoped. It is never stored on <see cref="AgentSession"/>.
+    /// </para>
+    /// <para>
+    /// Per Foundry hosted-agent isolation, a Responses chain created under one user cannot be
+    /// continued by another user via <c>previous_response_id</c>, even when both calls share the
+    /// same hosted sandbox (<c>agent_session_id</c>). See
+    /// <see href="https://learn.microsoft.com/azure/foundry/agents/how-to/multiplex-session-users">Multiplex multiple users in one hosted agent session</see>.
+    /// Reusing one <see cref="AgentSession"/> across identities typically reuses that chain, so the
+    /// second identity's run fails at the platform (observed as a response not-found error). Prefer
+    /// a distinct <see cref="AgentSession"/> per identity; those sessions may still share one hosted
+    /// sandbox pin via <see cref="WithFoundryHostedAgentSessionId"/> or
+    /// <see cref="FoundryAgent.CreateFoundryHostedAgentSessionAsync(string?, string?, System.Threading.CancellationToken)"/>.
+    /// </para>
+    /// <para>
+    /// The value is stored in <see cref="ChatOptions.AdditionalProperties"/>. Replacing that
+    /// dictionary after calling this method removes the value; populate or replace the dictionary
+    /// first, then call this method.
+    /// </para>
+    /// </remarks>
+    public static ChatOptions WithFoundryHostedAgentUserIdentity(this ChatOptions options, string userIdentity)
+    {
+        _ = Throw.IfNull(options);
+        _ = Throw.IfNullOrWhitespace(userIdentity);
+
+        options.AdditionalProperties ??= new AdditionalPropertiesDictionary();
+        options.AdditionalProperties[FoundryHostedAgentUserIdentityKey] = userIdentity;
+        return options;
+    }
+
+    /// <summary>Reads the per-call hosted-agent session id stamped by <see cref="WithFoundryHostedAgentSessionId"/>.</summary>
+    internal static string? GetFoundryHostedAgentSessionId(this ChatOptions options)
+    {
+        if (options.AdditionalProperties is null)
+        {
+            return null;
+        }
+
+        if (!options.AdditionalProperties.TryGetValue(FoundryHostedAgentSessionIdKey, out var raw))
+        {
+            return null;
+        }
+
+        return raw as string;
+    }
+
+    /// <summary>Reads the per-call user identity stamped by <see cref="WithFoundryHostedAgentUserIdentity"/>.</summary>
+    internal static string? GetFoundryHostedAgentUserIdentity(this ChatOptions options)
+    {
+        if (options.AdditionalProperties is null)
+        {
+            return null;
+        }
+
+        if (!options.AdditionalProperties.TryGetValue(FoundryHostedAgentUserIdentityKey, out var raw))
+        {
+            return null;
+        }
+
+        return raw as string;
+    }
+}

dotnet/src/Microsoft.Agents.AI.Foundry/FoundryHostedRequestAgent.cs

@@ -0,0 +1,175 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Runtime.CompilerServices;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using OpenAI.Responses;
+
+#pragma warning disable OPENAI001
+#pragma warning disable SCME0001
+#pragma warning disable MEAI001
+
+namespace Microsoft.Agents.AI.Foundry;
+
+/// <summary>
+/// Delegating agent that applies Foundry hosted-agent request context per run:
+/// resolves the sticky hosted-agent session id, injects <c>agent_session_id</c> into the
+/// Responses body, stamps <c>x-ms-user-identity</c>, and writes the platform-returned session
+/// id back onto the <see cref="AgentSession"/>.
+/// </summary>
+internal sealed class FoundryHostedRequestAgent : DelegatingAIAgent
+{
+    public FoundryHostedRequestAgent(AIAgent innerAgent)
+        : base(innerAgent)
+    {
+    }
+
+    /// <inheritdoc/>
+    protected override async Task<AgentResponse> RunCoreAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        var prepared = Prepare(session, options);
+        try
+        {
+            return await this.InnerAgent.RunAsync(messages, session, prepared.Options, cancellationToken).ConfigureAwait(false);
+        }
+        finally
+        {
+            // Persist any platform-captured hosted session id even when later agent processing fails.
+            ApplySessionSticky(session, prepared.SessionIdBox);
+        }
+    }
+
+    /// <inheritdoc/>
+    protected override async IAsyncEnumerable<AgentResponseUpdate> RunCoreStreamingAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        AgentRunOptions? options = null,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        var prepared = Prepare(session, options);
+        try
+        {
+            await foreach (var update in this.InnerAgent.RunStreamingAsync(messages, session, prepared.Options, cancellationToken).ConfigureAwait(false))
+            {
+                yield return update;
+            }
+        }
+        finally
+        {
+            // finally also runs when the consumer disposes the enumerator early.
+            ApplySessionSticky(session, prepared.SessionIdBox);
+        }
+    }
+
+    private static PreparedRun Prepare(AgentSession? session, AgentRunOptions? options)
+    {
+        ChatOptions? chatOptions = options is ChatClientAgentRunOptions cro ? cro.ChatOptions : null;
+
+        string? sessionHostedId = session?.FoundryHostedAgentSessionId;
+        string? optionsHostedId = chatOptions?.GetFoundryHostedAgentSessionId();
+
+        if (!string.IsNullOrWhiteSpace(sessionHostedId)
+            && !string.IsNullOrWhiteSpace(optionsHostedId)
+            && !string.Equals(sessionHostedId, optionsHostedId, StringComparison.Ordinal))
+        {
+            throw new InvalidOperationException(
+                """
+                The hosted-agent session id provided via ChatOptions is different from the id stored on the provided AgentSession.
+                Only one hosted-agent session id can be used for a run.
+                """);
+        }
+
+        string? resolvedHostedId = !string.IsNullOrWhiteSpace(optionsHostedId) ? optionsHostedId : sessionHostedId;
+        var sessionIdBox = new StrongBox<string?>(resolvedHostedId);
+        HostedSessionIdCaptureScope.Current = sessionIdBox;
+
+        // Always ensure ChatOptions + factory so (a) an existing id is sent on every service call
+        // and (b) a platform-created id captured mid-run is sent on later function-loop calls.
+        var effectiveOptions = EnsureChatOptions(options, out chatOptions);
+        AttachHostedSessionIdFactory(chatOptions, sessionIdBox);
+
+        // Always assign (including null) so a nested Foundry run that omits the per-call Foundry
+        // user identity does not inherit a parent AsyncLocal value and stamp the wrong header.
+        UserIdentityScope.Current = chatOptions.GetFoundryHostedAgentUserIdentity();
+
+        return new PreparedRun(effectiveOptions, sessionIdBox);
+    }
+
+    private static ChatClientAgentRunOptions EnsureChatOptions(AgentRunOptions? options, out ChatOptions chatOptions)
+    {
+        if (options is ChatClientAgentRunOptions existing)
+        {
+            // Clone so per-run RawRepresentationFactory wrapping does not mutate caller-owned options
+            // or stack factories when the same instance is reused across runs.
+            var clone = (ChatClientAgentRunOptions)existing.Clone();
+            clone.ChatOptions ??= new ChatOptions();
+            chatOptions = clone.ChatOptions;
+            return clone;
+        }
+
+        chatOptions = new ChatOptions();
+        var specialized = new ChatClientAgentRunOptions(chatOptions);
+        if (options is not null)
+        {
+            // Preserve base AgentRunOptions fields when upgrading a plain options instance.
+#pragma warning disable MEAI001 // ResponseContinuationToken is experimental
+            specialized.ContinuationToken = options.ContinuationToken;
+#pragma warning restore MEAI001
+            specialized.AllowBackgroundResponses = options.AllowBackgroundResponses;
+            specialized.ResponseFormat = options.ResponseFormat;
+            specialized.AdditionalProperties = options.AdditionalProperties?.Clone();
+        }
+
+        return specialized;
+    }
+
+    private static void AttachHostedSessionIdFactory(ChatOptions chatOptions, StrongBox<string?> sessionIdBox)
+    {
+        var previousFactory = chatOptions.RawRepresentationFactory;
+        chatOptions.RawRepresentationFactory = client =>
+        {
+            object? previous = previousFactory?.Invoke(client);
+            if (previous is not null and not CreateResponseOptions)
+            {
+                return previous;
+            }
+
+            var responseOptions = previous as CreateResponseOptions ?? new CreateResponseOptions();
+            if (!string.IsNullOrWhiteSpace(sessionIdBox.Value))
+            {
+                responseOptions.Patch.Set("$.agent_session_id"u8, sessionIdBox.Value);
+            }
+
+            return responseOptions;
+        };
+    }
+
+    private static void ApplySessionSticky(AgentSession? session, StrongBox<string?> sessionIdBox)
+    {
+        if (session is null || string.IsNullOrWhiteSpace(sessionIdBox.Value))
+        {
+            return;
+        }
+
+        session.FoundryHostedAgentSessionId = sessionIdBox.Value!;
+    }
+
+    private sealed class PreparedRun
+    {
+        public PreparedRun(ChatClientAgentRunOptions options, StrongBox<string?> sessionIdBox)
+        {
+            this.Options = options;
+            this.SessionIdBox = sessionIdBox;
+        }
+
+        public ChatClientAgentRunOptions Options { get; }
+        public StrongBox<string?> SessionIdBox { get; }
+    }
+}

dotnet/src/Microsoft.Agents.AI.Foundry/HostedSessionIdCapturePolicy.cs

@@ -0,0 +1,68 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.ClientModel.Primitives;
+using System.Collections.Generic;
+using System.Threading.Tasks;
+
+namespace Microsoft.Agents.AI.Foundry;
+
+/// <summary>
+/// Pipeline policy that captures the <c>x-agent-session-id</c> response header into
+/// <see cref="HostedSessionIdCaptureScope"/> so subsequent service calls in the same run (and the
+/// session sticky update after the run) see the platform-assigned hosted-agent session id.
+/// </summary>
+/// <remarks>
+/// When the scope already holds a pinned id, a different response id is rejected as an unexpected
+/// Foundry hosted session switch rather than silently overwriting the sticky value.
+/// </remarks>
+internal sealed class HostedSessionIdCapturePolicy : PipelinePolicy
+{
+    internal const string SessionIdHeader = "x-agent-session-id";
+
+    public static HostedSessionIdCapturePolicy Instance { get; } = new HostedSessionIdCapturePolicy();
+
+    private HostedSessionIdCapturePolicy()
+    {
+    }
+
+    public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+    {
+        ProcessNext(message, pipeline, currentIndex);
+        Capture(message);
+    }
+
+    public override async ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+    {
+        await ProcessNextAsync(message, pipeline, currentIndex).ConfigureAwait(false);
+        Capture(message);
+    }
+
+    private static void Capture(PipelineMessage message)
+    {
+        if (message.Response is null)
+        {
+            return;
+        }
+
+        if (HostedSessionIdCaptureScope.Current is not { } box)
+        {
+            return;
+        }
+
+        if (message.Response.Headers.TryGetValue(SessionIdHeader, out string? sessionId)
+            && !string.IsNullOrWhiteSpace(sessionId))
+        {
+            sessionId = sessionId.Trim();
+            if (!string.IsNullOrWhiteSpace(box.Value)
+                && !string.Equals(box.Value, sessionId, StringComparison.Ordinal))
+            {
+                throw new InvalidOperationException(
+                    $"Unexpected Foundry hosted session switch. The run is pinned to hosted session '{box.Value}' " +
+                    $"but the response returned '{sessionId}'.");
+            }
+
+            box.Value = sessionId;
+        }
+    }
+}

dotnet/src/Microsoft.Agents.AI.Foundry/HostedSessionIdCaptureScope.cs

@@ -0,0 +1,27 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Runtime.CompilerServices;
+using System.Threading;
+
+namespace Microsoft.Agents.AI.Foundry;
+
+/// <summary>
+/// AsyncLocal carrier for the mutable hosted-agent session id box shared by
+/// <see cref="FoundryHostedRequestAgent"/> (request body injection) and
+/// <see cref="HostedSessionIdCapturePolicy"/> (response header capture).
+/// </summary>
+/// <remarks>
+/// Uses <see cref="StrongBox{T}"/> so writes inside the transport pipeline remain visible to the
+/// agent decorator after the inner call returns (and on later service calls in a function loop).
+/// </remarks>
+internal static class HostedSessionIdCaptureScope
+{
+    private static readonly AsyncLocal<StrongBox<string?>?> s_current = new();
+
+    /// <summary>Gets or sets the per-async-flow hosted session id box.</summary>
+    public static StrongBox<string?>? Current
+    {
+        get => s_current.Value;
+        set => s_current.Value = value;
+    }
+}

dotnet/src/Microsoft.Agents.AI.Foundry/UserIdentityPolicy.cs

@@ -0,0 +1,43 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ClientModel.Primitives;
+using System.Collections.Generic;
+using System.Threading.Tasks;
+
+namespace Microsoft.Agents.AI.Foundry;
+
+/// <summary>
+/// Pipeline policy that stamps <c>x-ms-user-identity</c> from <see cref="UserIdentityScope"/>
+/// onto outbound OpenAI Responses requests.
+/// </summary>
+internal sealed class UserIdentityPolicy : PipelinePolicy
+{
+    public static UserIdentityPolicy Instance { get; } = new UserIdentityPolicy();
+
+    private UserIdentityPolicy()
+    {
+    }
+
+    public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+    {
+        Stamp(message);
+        ProcessNext(message, pipeline, currentIndex);
+    }
+
+    public override ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+    {
+        Stamp(message);
+        return ProcessNextAsync(message, pipeline, currentIndex);
+    }
+
+    private static void Stamp(PipelineMessage message)
+    {
+        var identity = UserIdentityScope.Current;
+        if (string.IsNullOrWhiteSpace(identity))
+        {
+            return;
+        }
+
+        message.Request.Headers.Set("x-ms-user-identity", identity);
+    }
+}

dotnet/src/Microsoft.Agents.AI.Foundry/UserIdentityScope.cs

@@ -0,0 +1,21 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Threading;
+
+namespace Microsoft.Agents.AI.Foundry;
+
+/// <summary>
+/// AsyncLocal carrier for the per-call <c>x-ms-user-identity</c> value from
+/// <see cref="FoundryHostedRequestAgent"/> to <see cref="UserIdentityPolicy"/>.
+/// </summary>
+internal static class UserIdentityScope
+{
+    private static readonly AsyncLocal<string?> s_current = new();
+
+    /// <summary>Gets or sets the per-async-flow user identity value.</summary>
+    public static string? Current
+    {
+        get => s_current.Value;
+        set => s_current.Value = value;
+    }
+}

dotnet/src/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore/AGUIEndpointRouteBuilderExtensions.cs

@@ -32,6 +32,21 @@ namespace Microsoft.Agents.AI.Hosting.AGUI.AspNetCore;
 /// </remarks>
 public static class AGUIEndpointRouteBuilderExtensions
 {
+    /// <summary>
+    /// Maps an AG-UI agent endpoint using an agent registered in dependency injection via <see cref="IHostedAgentBuilder"/>.
+    /// </summary>
+    /// <param name="endpoints">The endpoint route builder.</param>
+    /// <param name="agentBuilder">The hosted agent builder that identifies the agent registration.</param>
+    /// <returns>An <see cref="IEndpointConventionBuilder"/> for the mapped endpoint.</returns>
+    public static IEndpointConventionBuilder MapAGUIServer(
+        this IEndpointRouteBuilder endpoints,
+        IHostedAgentBuilder agentBuilder)
+    {
+        ArgumentNullException.ThrowIfNull(endpoints);
+        ArgumentNullException.ThrowIfNull(agentBuilder);
+        return endpoints.MapAGUIServer(agentBuilder.Name);
+    }
+
     /// <summary>
     /// Maps an AG-UI agent endpoint using an agent registered in dependency injection via <see cref="IHostedAgentBuilder"/>.
     /// </summary>
@@ -49,6 +64,23 @@ public static class AGUIEndpointRouteBuilderExtensions
         return endpoints.MapAGUIServer(agentBuilder.Name, pattern);
     }
 
+    /// <summary>
+    /// Maps an AG-UI agent endpoint using a named agent registered in dependency injection.
+    /// </summary>
+    /// <param name="endpoints">The endpoint route builder.</param>
+    /// <param name="agentName">The name of the keyed agent registration to resolve from dependency injection.</param>
+    /// <returns>An <see cref="IEndpointConventionBuilder"/> for the mapped endpoint.</returns>
+    public static IEndpointConventionBuilder MapAGUIServer(
+        this IEndpointRouteBuilder endpoints,
+        string agentName)
+    {
+        ArgumentNullException.ThrowIfNull(endpoints);
+        ArgumentException.ThrowIfNullOrWhiteSpace(agentName);
+
+        var agent = endpoints.ServiceProvider.GetRequiredKeyedService<AIAgent>(agentName);
+        return endpoints.MapAGUIServer(agent);
+    }
+
     /// <summary>
     /// Maps an AG-UI agent endpoint using a named agent registered in dependency injection.
     /// </summary>
@@ -68,6 +100,24 @@ public static class AGUIEndpointRouteBuilderExtensions
         return endpoints.MapAGUIServer(pattern, agent);
     }
 
+    /// <summary>
+    /// Maps an AG-UI agent endpoint using a route derived from the agent name.
+    /// </summary>
+    /// <param name="endpoints">The endpoint route builder.</param>
+    /// <param name="aiAgent">The agent instance.</param>
+    /// <returns>An <see cref="IEndpointConventionBuilder"/> for the mapped endpoint.</returns>
+    public static IEndpointConventionBuilder MapAGUIServer(
+        this IEndpointRouteBuilder endpoints,
+        AIAgent aiAgent)
+    {
+        ArgumentNullException.ThrowIfNull(endpoints);
+        ArgumentNullException.ThrowIfNull(aiAgent);
+        ArgumentException.ThrowIfNullOrWhiteSpace(aiAgent.Name, nameof(aiAgent.Name));
+        ValidateAgentName(aiAgent.Name);
+
+        return endpoints.MapAGUIServer($"/{aiAgent.Name}/agui", aiAgent);
+    }
+
     /// <summary>
     /// Maps an AG-UI agent endpoint.
     /// </summary>
@@ -186,4 +236,13 @@ public static class AGUIEndpointRouteBuilderExtensions
 
         await hostAgent.SaveSessionAsync(threadId, session, cancellationToken).ConfigureAwait(false);
     }
+
+    private static void ValidateAgentName([NotNull] string agentName)
+    {
+        var escaped = Uri.EscapeDataString(agentName);
+        if (!string.Equals(escaped, agentName, StringComparison.OrdinalIgnoreCase))
+        {
+            throw new ArgumentException($"Agent name '{agentName}' contains characters invalid for URL routes.", nameof(agentName));
+        }
+    }
 }

dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgentOptions.cs

@@ -61,6 +61,19 @@ public sealed class ChatClientAgentOptions
     /// </remarks>
     public bool UseProvidedChatClientAsIs { get; set; }
 
+    /// <summary>
+    /// Gets or sets a value indicating whether functions may be invoked concurrently when a model response
+    /// contains multiple function calls.
+    /// </summary>
+    /// <remarks>
+    /// This setting is independent of <see cref="ChatOptions.AllowMultipleToolCalls"/>, which controls whether
+    /// a model may return multiple tool calls in a single response. The default is <see langword="false"/>.
+    /// This option has no effect when <see cref="UseProvidedChatClientAsIs"/> is <see langword="true"/>.
+    /// When using a custom chat client stack, configure <see cref="FunctionInvokingChatClient.AllowConcurrentInvocation"/>
+    /// directly on its <see cref="FunctionInvokingChatClient"/> instance.
+    /// </remarks>
+    public bool AllowConcurrentInvocation { get; set; }
+
     /// <summary>
     /// Gets or sets a value indicating whether to set the <see cref="ChatClientAgent.ChatHistoryProvider"/> to <see langword="null"/>
     /// if the underlying AI service indicates that it manages chat history (for example, by returning a conversation id in the response), but a <see cref="ChatHistoryProvider"/> is configured for the agent.
@@ -288,6 +301,7 @@ public sealed class ChatClientAgentOptions
             ChatHistoryProvider = this.ChatHistoryProvider,
             AIContextProviders = this.AIContextProviders is null ? null : new List<AIContextProvider>(this.AIContextProviders),
             UseProvidedChatClientAsIs = this.UseProvidedChatClientAsIs,
+            AllowConcurrentInvocation = this.AllowConcurrentInvocation,
             ClearOnChatHistoryProviderConflict = this.ClearOnChatHistoryProviderConflict,
             WarnOnChatHistoryProviderConflict = this.WarnOnChatHistoryProviderConflict,
             ThrowOnChatHistoryProviderConflict = this.ThrowOnChatHistoryProviderConflict,

dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientExtensions.cs

@@ -90,15 +90,23 @@ public static class ChatClientExtensions
                 new InvocableFunctionBypassingChatClient(innerClient, services.GetService<ILoggerFactory>()));
         }
 
-        if (chatClient.GetService<FunctionInvokingChatClient>() is null)
+        var functionInvokingChatClient = chatClient.GetService<FunctionInvokingChatClient>();
+        if (functionInvokingChatClient is null)
         {
             chatBuilder.Use((innerClient, services) =>
             {
                 var loggerFactory = services.GetService<ILoggerFactory>();
 
-                return new FunctionInvokingChatClient(innerClient, loggerFactory, services);
+                return new FunctionInvokingChatClient(innerClient, loggerFactory, services)
+                {
+                    AllowConcurrentInvocation = options?.AllowConcurrentInvocation is true,
+                };
             });
         }
+        else if (options?.AllowConcurrentInvocation is true)
+        {
+            functionInvokingChatClient.AllowConcurrentInvocation = true;
+        }
 
         // MessageInjectingChatClient is injected when EnableMessageInjection is enabled.
         // It is registered after FunctionInvokingChatClient so that it sits between FIC and the inner client.

dotnet/tests/Foundry.Hosting.IntegrationTests.TestContainer/Program.cs

@@ -45,6 +45,7 @@ AIAgent agent = scenario switch
     "azure-search-rag" => CreateAzureSearchRagAgent(projectClient, deployment),
     "session-files" => CreateSessionFilesAgent(projectClient, deployment),
     "agent-skills" => CreateAgentSkillsAgent(projectClient, deployment),
+    "user-identity" => CreateUserIdentityAgent(projectClient, deployment),
     _ => throw new InvalidOperationException($"Unknown IT_SCENARIO '{scenario}'.")
 };
 
@@ -210,6 +211,12 @@ static Func<string, CancellationToken, Task<IEnumerable<TextSearchProvider.TextS
 
         return results;
     };
+// user-identity scenario: returns USER-ID:<platform-user-key> without calling a model so the
+// assertion works even when the subscription has no OpenAI chat deployment. The hosting layer
+// writes HostedSessionContext from x-agent-user-id before RunCoreAsync.
+static AIAgent CreateUserIdentityAgent(AIProjectClient _, string __) =>
+    new UserIdentityEchoAgent();
+
 // session-files scenario: agent reads files from $HOME inside the per-session sandbox volume.
 // Mirrors the dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files sample.
 static AIAgent CreateSessionFilesAgent(AIProjectClient client, string deployment) =>

dotnet/tests/Foundry.Hosting.IntegrationTests.TestContainer/UserIdentityEchoAgent.cs

@@ -0,0 +1,73 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Runtime.CompilerServices;
+using System.Text.Json;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry.Hosting;
+using Microsoft.Extensions.AI;
+
+namespace Foundry.Hosting.IntegrationTests.TestContainer;
+
+/// <summary>
+/// Minimal agent that echoes the platform user isolation key as <c>USER-ID:&lt;key&gt;</c>.
+/// Does not call a model, so identity ITs do not depend on OpenAI quota or catalog access.
+/// </summary>
+#pragma warning disable MAAI001 // HostedSessionContext / experimental surface
+internal sealed class UserIdentityEchoAgent : AIAgent
+{
+    public override string Name => "user-identity-agent";
+
+    public override string Description =>
+        "Echoes the platform user isolation key for user-identity IT assertions.";
+
+    protected override Task<AgentResponse> RunCoreAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        var text = BuildReply(session);
+        return Task.FromResult(new AgentResponse(new ChatMessage(ChatRole.Assistant, text)));
+    }
+
+    protected override async IAsyncEnumerable<AgentResponseUpdate> RunCoreStreamingAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        AgentRunOptions? options = null,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        var text = BuildReply(session);
+        yield return new AgentResponseUpdate
+        {
+            Role = ChatRole.Assistant,
+            Contents = [new TextContent(text)],
+        };
+
+        await Task.CompletedTask.ConfigureAwait(false);
+    }
+
+    protected override ValueTask<AgentSession> CreateSessionCoreAsync(CancellationToken cancellationToken = default)
+        => new(new InMemorySession());
+
+    protected override ValueTask<JsonElement> SerializeSessionCoreAsync(
+        AgentSession session,
+        JsonSerializerOptions? jsonSerializerOptions = null,
+        CancellationToken cancellationToken = default)
+        => new(JsonSerializer.SerializeToElement(new { }, jsonSerializerOptions));
+
+    protected override ValueTask<AgentSession> DeserializeSessionCoreAsync(
+        JsonElement serializedState,
+        JsonSerializerOptions? jsonSerializerOptions = null,
+        CancellationToken cancellationToken = default)
+        => new(new InMemorySession());
+
+    private static string BuildReply(AgentSession? session)
+    {
+        var userId = session?.GetHostedContext()?.UserId;
+        var token = string.IsNullOrWhiteSpace(userId) ? "USER-ID:missing" : $"USER-ID:{userId}";
+        return $"ready\n{token}";
+    }
+
+    private sealed class InMemorySession : AgentSession;
+}
+#pragma warning restore MAAI001

dotnet/tests/Foundry.Hosting.IntegrationTests/Fixtures/UserIdentityHostedAgentFixture.cs

@@ -0,0 +1,13 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Foundry.Hosting.IntegrationTests.Fixtures;
+
+/// <summary>
+/// Provisions a hosted agent that runs the test container in <c>IT_SCENARIO=user-identity</c> mode.
+/// The container echoes the platform user isolation key so client tests can assert that
+/// <c>x-ms-user-identity</c> produces distinct effective users on the same hosted session.
+/// </summary>
+public sealed class UserIdentityHostedAgentFixture : HostedAgentFixture
+{
+    protected override string ScenarioName => "user-identity";
+}

dotnet/tests/Foundry.Hosting.IntegrationTests/HostedSessionAndUserIdentityTests.cs

@@ -0,0 +1,297 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+#pragma warning disable AAIP001 // Agent session admin APIs are experimental
+#pragma warning disable MEAI001 // FoundryChatOptionsExtensions / OpenAIRequestPolicies are experimental
+
+using System;
+using System.ClientModel.Primitives;
+using System.Collections.Generic;
+using System.Text.RegularExpressions;
+using System.Threading;
+using System.Threading.Tasks;
+using AgentConformance.IntegrationTests.Support;
+using Azure.AI.Extensions.OpenAI;
+using Azure.AI.Projects.Agents;
+using Foundry.Hosting.IntegrationTests.Fixtures;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry;
+using Microsoft.Extensions.AI;
+using Shared.IntegrationTests;
+
+namespace Foundry.Hosting.IntegrationTests;
+
+/// <summary>
+/// Live tests for client-side Foundry hosted session sticky behavior and per-call
+/// <c>x-ms-user-identity</c> pass-through against a real hosted agent.
+/// </summary>
+/// <remarks>
+/// <para>
+/// These tests build a <see cref="FoundryAgent"/> against the fixture's agent endpoint so the
+/// production request pipeline (<c>FoundryHostedRequestAgent</c>, session sticky, user-identity
+/// header) is exercised. The fixture's default <see cref="HostedAgentFixture.Agent"/> is a plain
+/// chat-client agent and is intentionally not used here.
+/// </para>
+/// <para>
+/// Requires the caller credential to be allowed to send <c>x-ms-user-identity</c> (delegation).
+/// Without that permission the user-identity tests fail at the platform with 403 rather than an
+/// assertion mismatch.
+/// </para>
+/// </remarks>
+[Trait("Category", "FoundryHostedAgents")]
+public sealed class HostedSessionAndUserIdentityTests(UserIdentityHostedAgentFixture fixture)
+    : IClassFixture<UserIdentityHostedAgentFixture>
+{
+    private const string FoundryFeaturesHeader = "Foundry-Features";
+    private const string HostedAgentsFeatureValue = "HostedAgents=V1Preview,AgentEndpoints=V1Preview";
+    private static readonly Regex s_userIdToken = new(@"USER-ID:(\S+)", RegexOptions.CultureInvariant | RegexOptions.Compiled);
+
+    private readonly UserIdentityHostedAgentFixture _fixture = fixture;
+
+    [Fact(Skip = "Requires live Foundry hosted agent image, bootstrap it-user-identity, and delegation permission for x-ms-user-identity.")]
+    public async Task ServiceManagedSession_BecomesStickyAndIsReusedAsync()
+    {
+        // Arrange
+        FoundryAgent agent = this.CreateFoundryAgent();
+        ChatClientAgentSession session = await agent.CreateFoundryHostedAgentSessionAsync();
+        Assert.Null(session.FoundryHostedAgentSessionId);
+
+        string? hostedSessionId = null;
+        try
+        {
+            // Act: first run lets Foundry create the sandbox; sticky id is written from the response.
+            var first = await agent.RunAsync("Reply with the single word ready.", session);
+            Assert.False(string.IsNullOrWhiteSpace(first.Text));
+
+            hostedSessionId = session.FoundryHostedAgentSessionId;
+            Assert.False(string.IsNullOrWhiteSpace(hostedSessionId));
+
+            // Act: second run reuses the same AgentSession and must keep the same sticky id.
+            var second = await agent.RunAsync("Reply with the single word again.", session);
+            Assert.False(string.IsNullOrWhiteSpace(second.Text));
+
+            // Assert
+            Assert.Equal(hostedSessionId, session.FoundryHostedAgentSessionId);
+        }
+        finally
+        {
+            await this.TryDeleteSessionAsync(hostedSessionId);
+        }
+    }
+
+    [Fact(Skip = "Requires live Foundry hosted agent image, bootstrap it-user-identity, and AgentAdministration CreateSession.")]
+    public async Task UserManagedSession_PinIsStickyAndMatchesAdminSessionAsync()
+    {
+        // Arrange: provision sandbox via admin API (Python using_deployed_agent path).
+        AgentAdministrationClient admin = this.CreateAdminClient();
+        ProjectAgentSession platformSession = await admin.CreateSessionAsync(
+            this._fixture.AgentName,
+            new VersionRefIndicator(this._fixture.AgentVersion));
+
+        string hostedSessionId = platformSession.AgentSessionId;
+        await WaitForSessionActiveAsync(admin, this._fixture.AgentName, hostedSessionId);
+
+        FoundryAgent agent = this.CreateFoundryAgent();
+        ChatClientAgentSession session = await agent.CreateFoundryHostedAgentSessionAsync(hostedSessionId: hostedSessionId);
+        Assert.Equal(hostedSessionId, session.FoundryHostedAgentSessionId);
+
+        try
+        {
+            // Act
+            var response = await agent.RunAsync("Reply with the single word pinned.", session);
+
+            // Assert
+            Assert.False(string.IsNullOrWhiteSpace(response.Text));
+            Assert.Equal(hostedSessionId, session.FoundryHostedAgentSessionId);
+        }
+        finally
+        {
+            await this.TryDeleteSessionAsync(hostedSessionId);
+        }
+    }
+
+    [Fact(Skip = "Requires live Foundry hosted agent image, bootstrap it-user-identity, and delegation permission for x-ms-user-identity.")]
+    public async Task SameHostedSandbox_DifferentAgentSessionsAndUserIdentities_YieldsDistinctUsersAsync()
+    {
+        // Arrange: two different AgentSession instances share one Foundry hosted sandbox id.
+        // ConversationId is per AgentSession (chat trail). HostedAgentSessionId is the sandbox.
+        // Reusing one AgentSession across identities reuses previous_response_id and 404s under
+        // per-user response partitioning; separate AgentSessions avoid that while keeping the sandbox.
+        FoundryAgent agent = this.CreateFoundryAgent();
+        string? hostedSessionId = null;
+
+        try
+        {
+            // Act: alice creates the sandbox via service-managed sticky capture.
+            ChatClientAgentSession aliceSession = await agent.CreateFoundryHostedAgentSessionAsync();
+            string aliceUserId = await this.RunAndReadUserIdAsync(agent, aliceSession, "alice-it");
+            hostedSessionId = aliceSession.FoundryHostedAgentSessionId;
+            Assert.False(string.IsNullOrWhiteSpace(hostedSessionId));
+            string? aliceConversationId = aliceSession.ConversationId;
+
+            // Act: bob gets a fresh AgentSession pinned to the same hosted sandbox.
+            ChatClientAgentSession bobSession = await agent.CreateFoundryHostedAgentSessionAsync(hostedSessionId: hostedSessionId);
+            Assert.NotSame(aliceSession, bobSession);
+            Assert.Equal(hostedSessionId, bobSession.FoundryHostedAgentSessionId);
+
+            string bobUserId = await this.RunAndReadUserIdAsync(agent, bobSession, "bob-it");
+
+            // Assert: hosted sandbox stays the same on both sessions after bob's response.
+            Assert.Equal(hostedSessionId, aliceSession.FoundryHostedAgentSessionId);
+            Assert.Equal(hostedSessionId, bobSession.FoundryHostedAgentSessionId);
+
+            // Assert: conversation trails stay independent (must not share ConversationId).
+            string? bobConversationId = bobSession.ConversationId;
+            Assert.False(
+                aliceConversationId is not null
+                && bobConversationId is not null
+                && string.Equals(aliceConversationId, bobConversationId, StringComparison.Ordinal),
+                $"ConversationId must differ across AgentSessions. alice='{aliceConversationId}', bob='{bobConversationId}'.");
+            if (aliceConversationId is not null || bobConversationId is not null)
+            {
+                Assert.NotEqual(aliceConversationId, bobConversationId);
+            }
+
+            // Assert: platform user keys differ for alice vs bob.
+            Assert.NotEqual("missing", aliceUserId);
+            Assert.NotEqual("missing", bobUserId);
+            Assert.NotEqual(aliceUserId, bobUserId);
+        }
+        finally
+        {
+            await this.TryDeleteSessionAsync(hostedSessionId);
+        }
+    }
+
+    [Fact(Skip = "Requires live Foundry hosted agent image, bootstrap it-user-identity, and delegation permission for x-ms-user-identity.")]
+    public async Task SameSession_SameUserIdentity_YieldsStablePlatformUserIdAsync()
+    {
+        // Arrange
+        FoundryAgent agent = this.CreateFoundryAgent();
+        ChatClientAgentSession session = await agent.CreateFoundryHostedAgentSessionAsync();
+        string? hostedSessionId = null;
+
+        try
+        {
+            // Act
+            string first = await this.RunAndReadUserIdAsync(agent, session, "stable-user-it");
+            hostedSessionId = session.FoundryHostedAgentSessionId;
+            string second = await this.RunAndReadUserIdAsync(agent, session, "stable-user-it");
+
+            // Assert
+            Assert.False(string.IsNullOrWhiteSpace(hostedSessionId));
+            Assert.Equal(hostedSessionId, session.FoundryHostedAgentSessionId);
+            Assert.NotEqual("missing", first);
+            Assert.Equal(first, second);
+        }
+        finally
+        {
+            await this.TryDeleteSessionAsync(hostedSessionId);
+        }
+    }
+
+    private async Task<string> RunAndReadUserIdAsync(FoundryAgent agent, AgentSession session, string userIdentity)
+    {
+        var options = new ChatClientAgentRunOptions(
+            new ChatOptions().WithFoundryHostedAgentUserIdentity(userIdentity));
+
+        var response = await agent.RunAsync(
+            "Acknowledge the request briefly.",
+            session,
+            options);
+
+        Assert.False(string.IsNullOrWhiteSpace(response.Text));
+        Match match = s_userIdToken.Match(response.Text);
+        Assert.True(match.Success, $"Expected USER-ID:<value> token in response text. Actual: {response.Text}");
+        return match.Groups[1].Value;
+    }
+
+    /// <summary>
+    /// Builds a <see cref="FoundryAgent"/> against this fixture's hosted agent endpoint with the
+    /// preview feature headers required for hosted agent traffic.
+    /// </summary>
+    private FoundryAgent CreateFoundryAgent()
+    {
+        var endpoint = new Uri(TestConfiguration.GetRequiredValue(TestSettings.AzureAIProjectEndpoint));
+        var credential = TestAzureCliCredentials.CreateAzureCliCredential();
+        Uri agentEndpoint = new($"{endpoint.ToString().TrimEnd('/')}/agents/{this._fixture.AgentName}/endpoint/protocols/openai");
+
+        var options = new ProjectOpenAIClientOptions
+        {
+            AgentName = this._fixture.AgentName,
+        };
+        options.AddPolicy(new FoundryFeaturesPolicy(HostedAgentsFeatureValue), PipelinePosition.PerCall);
+
+        return new FoundryAgent(agentEndpoint, credential, options);
+    }
+
+    private AgentAdministrationClient CreateAdminClient()
+    {
+        var endpoint = new Uri(TestConfiguration.GetRequiredValue(TestSettings.AzureAIProjectEndpoint));
+        var credential = TestAzureCliCredentials.CreateAzureCliCredential();
+        var adminOptions = new AgentAdministrationClientOptions();
+        adminOptions.AddPolicy(new FoundryFeaturesPolicy(HostedAgentsFeatureValue), PipelinePosition.PerCall);
+        return new AgentAdministrationClient(endpoint, credential, adminOptions);
+    }
+
+    private async Task TryDeleteSessionAsync(string? hostedSessionId)
+    {
+        if (string.IsNullOrWhiteSpace(hostedSessionId))
+        {
+            return;
+        }
+
+        try
+        {
+            AgentAdministrationClient admin = this.CreateAdminClient();
+            await admin.DeleteSessionAsync(this._fixture.AgentName, hostedSessionId);
+        }
+        catch
+        {
+            // Best-effort cleanup; platform TTL reclaims orphaned sessions.
+        }
+    }
+
+    private static async Task WaitForSessionActiveAsync(
+        AgentAdministrationClient admin,
+        string agentName,
+        string sessionId,
+        TimeSpan? timeout = null)
+    {
+        TimeSpan limit = timeout ?? TimeSpan.FromMinutes(3);
+        DateTimeOffset deadline = DateTimeOffset.UtcNow + limit;
+        ProjectAgentSession session = await admin.GetSessionAsync(agentName, sessionId);
+
+        while (session.Status != AgentSessionStatus.Active
+            && session.Status != AgentSessionStatus.Failed
+            && session.Status != AgentSessionStatus.Deleted
+            && session.Status != AgentSessionStatus.Expired)
+        {
+            if (DateTimeOffset.UtcNow > deadline)
+            {
+                throw new TimeoutException(
+                    $"Hosted session '{sessionId}' for agent '{agentName}' did not become Active within {limit.TotalSeconds:F0}s. Last status: {session.Status}.");
+            }
+
+            await Task.Delay(TimeSpan.FromMilliseconds(500), CancellationToken.None);
+            session = await admin.GetSessionAsync(agentName, sessionId);
+        }
+
+        Assert.Equal(AgentSessionStatus.Active, session.Status);
+    }
+
+    /// <summary>Pipeline policy that stamps the Foundry preview feature header.</summary>
+    private sealed class FoundryFeaturesPolicy(string features) : PipelinePolicy
+    {
+        public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+        {
+            message.Request.Headers.Set(FoundryFeaturesHeader, features);
+            ProcessNext(message, pipeline, currentIndex);
+        }
+
+        public override ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+        {
+            message.Request.Headers.Set(FoundryFeaturesHeader, features);
+            return ProcessNextAsync(message, pipeline, currentIndex);
+        }
+    }
+}

dotnet/tests/Foundry.Hosting.IntegrationTests/README.md

@@ -31,6 +31,21 @@ the agent definition by each fixture, drives a `switch` in the test container's
 `Program.cs` to wire up the scenario specific behavior (tools, toolbox, custom storage,
 etc.).
 
+### Session sticky and user-identity scenario
+
+`HostedSessionAndUserIdentityTests` (fixture `UserIdentityHostedAgentFixture`, agent
+`it-user-identity`) exercises the client-side `FoundryAgent` APIs:
+
+- `CreateFoundryHostedAgentSessionAsync` sticky hosted `agent_session_id` (service-managed and
+  admin `CreateSession` / `DeleteSession` pin)
+- per-call `ChatOptions.WithFoundryHostedAgentUserIdentity` (`x-ms-user-identity`) producing distinct
+  platform user keys inside the container
+
+The container scenario injects `USER-ID:<platform-user-key>` via
+`EchoPlatformUserIdContextProvider`, reading `HostedSessionContext.UserId` (from
+`x-agent-user-id`). The caller credential must be allowed to delegate via
+`x-ms-user-identity` or those tests fail with HTTP 403.
+
 ## Required environment variables
 
 | Variable | Source | Purpose |
@@ -222,4 +237,3 @@ human-only operation; CI only adds and deletes versions under existing agents.
 The scenarios marked (placeholder) are already wired into the test container `Program.cs`,
 but their assertions stay skipped pending live validation and stabilization of the relevant
 `Microsoft.Agents.AI.Foundry.Hosting` API surfaces.
-

dotnet/tests/Foundry.Hosting.IntegrationTests/scripts/it-bootstrap-agents.ps1

@@ -52,6 +52,7 @@ $Scenarios = @(
     'azure-search-rag',
     'session-files',
     'agent-skills',
+    'user-identity',
     'unsupported-protocol'
 )
 

dotnet/tests/Microsoft.Agents.AI.CosmosNoSql.UnitTests/CosmosChatHistoryProviderTests.cs

@@ -3,6 +3,7 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
+using System.Threading;
 using System.Threading.Tasks;
 using Azure.Core;
 using Azure.Identity;
@@ -807,6 +808,137 @@ public sealed class CosmosChatHistoryProviderTests : IAsyncLifetime, IDisposable
         Assert.Equal("Hierarchical partitioning message", hierarchicalMessageList[0].Text);
     }
 
+    [Fact]
+    [Trait("Category", "CosmosDB")]
+    public async Task GetMessagesAsync_WithMessages_ShouldReturnAllMessagesAcrossPagesAsync()
+    {
+        // Arrange
+        this.SkipIfEmulatorNotAvailable();
+        var session = CreateMockSession();
+        const string ConversationId = "get-messages-test";
+
+        using var provider = new CosmosChatHistoryProvider(this._connectionString, s_testDatabaseId, TestContainerId,
+            _ => new CosmosChatHistoryProvider.State(ConversationId))
+        {
+            MaxItemCount = 2,
+        };
+
+        List<ChatMessage> messages =
+        [
+            new(ChatRole.User, "Message 1"),
+            new(ChatRole.Assistant, "Message 2"),
+            new(ChatRole.User, "Message 3"),
+            new(ChatRole.Assistant, "Message 4"),
+            new(ChatRole.User, "Message 5"),
+        ];
+
+        var context = new ChatHistoryProvider.InvokedContext(s_mockAgent, session, messages, []);
+        await provider.InvokedAsync(context);
+
+        // Wait a moment for eventual consistency
+        await Task.Delay(100);
+
+        // Act
+        var retrievedMessages = (await provider.GetMessagesAsync(session)).ToList();
+
+        // Assert
+        Assert.Equal(messages.Count, retrievedMessages.Count);
+        // Batch writes share a Unix-seconds timestamp, so this test intentionally verifies page completeness
+        // without asserting relative order among tied messages.
+        Assert.Equal(
+            messages.Select(message => message.Text).Order(),
+            retrievedMessages.Select(message => message.Text).Order());
+    }
+
+    [Fact]
+    [Trait("Category", "CosmosDB")]
+    public async Task GetMessagesAsync_WithNoMessages_ShouldReturnEmptyAsync()
+    {
+        // Arrange
+        this.SkipIfEmulatorNotAvailable();
+        var session = CreateMockSession();
+
+        using var provider = new CosmosChatHistoryProvider(this._connectionString, s_testDatabaseId, TestContainerId,
+            _ => new CosmosChatHistoryProvider.State("get-messages-empty-test"));
+
+        // Act
+        var messages = await provider.GetMessagesAsync(session);
+
+        // Assert
+        Assert.Empty(messages);
+    }
+
+    [Fact]
+    [Trait("Category", "CosmosDB")]
+    public async Task GetMessagesAsync_DoesNotApplyInvocationFilterOrSourceAttributionAsync()
+    {
+        // Arrange
+        this.SkipIfEmulatorNotAvailable();
+        var session = CreateMockSession();
+
+        using var provider = new CosmosChatHistoryProvider(
+            this._connectionString,
+            s_testDatabaseId,
+            TestContainerId,
+            _ => new CosmosChatHistoryProvider.State("get-messages-filter-test"),
+            provideOutputMessageFilter: messages => messages.Where(message => message.Text != "Hidden"));
+
+        List<ChatMessage> messages =
+        [
+            new(ChatRole.User, "Visible"),
+            new(ChatRole.Assistant, "Hidden"),
+        ];
+
+        var invokedContext = new ChatHistoryProvider.InvokedContext(s_mockAgent, session, messages, []);
+        await provider.InvokedAsync(invokedContext);
+
+        // Act
+        var directMessages = (await provider.GetMessagesAsync(session)).ToList();
+        var invokingContext = new ChatHistoryProvider.InvokingContext(s_mockAgent, session, []);
+        var invocationMessages = (await provider.InvokingAsync(invokingContext)).ToList();
+
+        // Assert
+        Assert.Equal(2, directMessages.Count);
+        Assert.All(directMessages, message => Assert.Equal(AgentRequestMessageSourceType.External, message.GetAgentRequestMessageSourceType()));
+        Assert.Single(invocationMessages);
+        Assert.Equal("Visible", invocationMessages[0].Text);
+        Assert.Equal(AgentRequestMessageSourceType.ChatHistory, invocationMessages[0].GetAgentRequestMessageSourceType());
+    }
+
+    [Fact]
+    [Trait("Category", "CosmosDB")]
+    public async Task GetMessagesAsync_AfterDispose_ShouldThrowObjectDisposedExceptionAsync()
+    {
+        // Arrange
+        this.SkipIfEmulatorNotAvailable();
+        var session = CreateMockSession();
+        var provider = new CosmosChatHistoryProvider(this._connectionString, s_testDatabaseId, TestContainerId,
+            _ => new CosmosChatHistoryProvider.State("get-messages-disposed-test"));
+        provider.Dispose();
+
+        // Act & Assert
+        await Assert.ThrowsAsync<ObjectDisposedException>(() => provider.GetMessagesAsync(session));
+    }
+
+    [Fact]
+    [Trait("Category", "CosmosDB")]
+    public async Task GetMessagesAsync_WithCanceledToken_ShouldThrowOperationCanceledExceptionAsync()
+    {
+        // Arrange
+        this.SkipIfEmulatorNotAvailable();
+        var session = CreateMockSession();
+
+        using var provider = new CosmosChatHistoryProvider(this._connectionString, s_testDatabaseId, TestContainerId,
+            _ => new CosmosChatHistoryProvider.State("get-messages-cancellation-test"));
+
+        using var cancellationTokenSource = new CancellationTokenSource();
+        cancellationTokenSource.Cancel();
+
+        // Act & Assert
+        await Assert.ThrowsAnyAsync<OperationCanceledException>(
+            () => provider.GetMessagesAsync(session, cancellationTokenSource.Token));
+    }
+
     [Fact]
     [Trait("Category", "CosmosDB")]
     public async Task MaxMessagesToRetrieve_ShouldLimitAndReturnMostRecentAsync()

dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/FoundryAgentTests.cs

@@ -168,6 +168,7 @@ public class FoundryAgentTests
 
         // Assert: ClientHeadersAgent decorator is present in the delegating chain.
         Assert.NotNull(agent.GetService<ClientHeadersAgent>());
+        Assert.NotNull(agent.GetService<FoundryHostedRequestAgent>());
     }
 
     [Fact]

dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/FoundryHostedRequestTests.cs

@@ -0,0 +1,481 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.ClientModel;
+using System.ClientModel.Primitives;
+using System.Collections.Generic;
+using System.Net;
+using System.Net.Http;
+using System.Text;
+using System.Text.Json;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using OpenAI;
+using OpenAI.Responses;
+
+#pragma warning disable OPENAI001, MEAI001, MAAI001, SCME0001
+
+namespace Microsoft.Agents.AI.Foundry.UnitTests;
+
+/// <summary>
+/// Tests for hosted-agent session sticky behavior and per-call user identity.
+/// </summary>
+public sealed class FoundryHostedRequestTests
+{
+    [Fact]
+    public void WithFoundryHostedAgentSessionId_WritesOptionsCarrier()
+    {
+        var options = new ChatOptions();
+        options.WithFoundryHostedAgentSessionId("sess-1");
+        Assert.Equal("sess-1", options.GetFoundryHostedAgentSessionId());
+    }
+
+    [Fact]
+    public void WithFoundryHostedAgentUserIdentity_WritesOptionsCarrier()
+    {
+        var options = new ChatOptions();
+        options.WithFoundryHostedAgentUserIdentity("alice");
+        Assert.Equal("alice", options.GetFoundryHostedAgentUserIdentity());
+    }
+
+    [Fact]
+    public async Task CreateFoundryHostedAgentSessionAsync_PinsHostedAndConversationIdsAsync()
+    {
+        FoundryAgent agent = CreateFoundryAgent();
+        ChatClientAgentSession session = await agent.CreateFoundryHostedAgentSessionAsync(
+            hostedSessionId: "sess-1",
+            conversationId: "conv-1");
+
+        Assert.Equal("sess-1", session.FoundryHostedAgentSessionId);
+        Assert.Equal("conv-1", session.ConversationId);
+        Assert.True(session.StateBag.TryGetValue<string>(FoundryAgentSessionExtensions.FoundryHostedAgentSessionIdKey, out var raw));
+        Assert.Equal("sess-1", raw);
+    }
+
+    [Fact]
+    public async Task CreateFoundryHostedAgentSessionAsync_WithoutIds_LeavesBothEmptyAsync()
+    {
+        FoundryAgent agent = CreateFoundryAgent();
+        ChatClientAgentSession session = await agent.CreateFoundryHostedAgentSessionAsync();
+
+        Assert.Null(session.FoundryHostedAgentSessionId);
+        Assert.Null(session.ConversationId);
+    }
+
+    [Fact]
+    public async Task CreateFoundryHostedAgentSessionAsync_WhitespaceHostedId_ThrowsAsync()
+    {
+        FoundryAgent agent = CreateFoundryAgent();
+
+        await Assert.ThrowsAsync<ArgumentException>(
+            () => agent.CreateFoundryHostedAgentSessionAsync(hostedSessionId: "   "));
+    }
+
+    [Fact]
+    public async Task Conflict_SessionAndOptionsHostedIdsDiffer_ThrowsAsync()
+    {
+        var inner = new ProbeAgent();
+        var agent = new FoundryHostedRequestAgent(inner);
+        var session = new TestSession();
+        session.FoundryHostedAgentSessionId = "sess-A";
+        var runOptions = new ChatClientAgentRunOptions(
+            new ChatOptions().WithFoundryHostedAgentSessionId("sess-B"));
+
+        InvalidOperationException ex = await Assert.ThrowsAsync<InvalidOperationException>(
+            () => agent.RunAsync("hi", session, runOptions));
+        Assert.Contains("hosted-agent session id", ex.Message, StringComparison.OrdinalIgnoreCase);
+    }
+
+    [Fact]
+    public async Task SameHostedId_OnSessionAndOptions_DoesNotThrowAsync()
+    {
+        var inner = new ProbeAgent();
+        var agent = new FoundryHostedRequestAgent(inner);
+        var session = new TestSession();
+        session.FoundryHostedAgentSessionId = "sess-A";
+        var runOptions = new ChatClientAgentRunOptions(
+            new ChatOptions().WithFoundryHostedAgentSessionId("sess-A"));
+
+        await agent.RunAsync("hi", session, runOptions);
+        Assert.Equal(1, inner.RunCount);
+    }
+
+    [Fact]
+    public async Task Sticky_SessionHostedId_IsInjectedIntoCreateResponseOptionsAsync()
+    {
+        CreateResponseOptions? seen = null;
+        var inner = new ProbeAgent(onRun: options =>
+        {
+            if (options is ChatClientAgentRunOptions { ChatOptions.RawRepresentationFactory: { } factory })
+            {
+                seen = factory(null!) as CreateResponseOptions;
+            }
+        });
+        var agent = new FoundryHostedRequestAgent(inner);
+        var session = new TestSession();
+        session.FoundryHostedAgentSessionId = "sess-sticky";
+
+        await agent.RunAsync("hi", session);
+
+        Assert.NotNull(seen);
+        Assert.True(seen!.Patch.Contains("$.agent_session_id"u8));
+    }
+
+    [Fact]
+    public async Task OptionsHostedId_WhenSessionEmpty_IsInjectedAndStickyAfterRunAsync()
+    {
+        var inner = new ProbeAgent();
+        var agent = new FoundryHostedRequestAgent(inner);
+        var session = new TestSession();
+        var runOptions = new ChatClientAgentRunOptions(
+            new ChatOptions().WithFoundryHostedAgentSessionId("sess-options"));
+
+        await agent.RunAsync("hi", session, runOptions);
+        Assert.Equal("sess-options", session.FoundryHostedAgentSessionId);
+    }
+
+    [Fact]
+    public async Task UserIdentity_DifferentPerCall_OnSameSession_IsAllowedAsync()
+    {
+        // Pipeline still allows different identities on one AgentSession (request-scoped header).
+        // On a live hosted agent, Foundry binds previous_response_id chains to the creating user, so
+        // prefer distinct AgentSessions per identity; sandbox id may still be shared.
+        var seen = new List<string?>();
+        var inner = new ProbeAgent(onRun: _ => seen.Add(UserIdentityScope.Current));
+        var agent = new FoundryHostedRequestAgent(inner);
+        var session = new TestSession();
+        session.FoundryHostedAgentSessionId = "sess-shared";
+
+        await agent.RunAsync(
+            "hi",
+            session,
+            new ChatClientAgentRunOptions(new ChatOptions().WithFoundryHostedAgentUserIdentity("alice")));
+        await agent.RunAsync(
+            "hi",
+            session,
+            new ChatClientAgentRunOptions(new ChatOptions().WithFoundryHostedAgentUserIdentity("bob")));
+
+        Assert.Equal(["alice", "bob"], seen);
+        Assert.Equal("sess-shared", session.FoundryHostedAgentSessionId);
+    }
+
+    [Fact]
+    public async Task UserIdentity_OmittedAfterParent_ClearsAsyncLocalScopeAsync()
+    {
+        var seen = new List<string?>();
+        var inner = new ProbeAgent(onRun: _ => seen.Add(UserIdentityScope.Current));
+        var agent = new FoundryHostedRequestAgent(inner);
+        var session = new TestSession();
+
+        await agent.RunAsync(
+            "hi",
+            session,
+            new ChatClientAgentRunOptions(new ChatOptions().WithFoundryHostedAgentUserIdentity("alice")));
+        await agent.RunAsync("hi", session, new ChatClientAgentRunOptions(new ChatOptions()));
+
+        Assert.Equal(["alice", null], seen);
+    }
+
+    [Fact]
+    public async Task PlainAgentRunOptions_PreservesBasePropertiesAsync()
+    {
+        AgentRunOptions? seen = null;
+        var inner = new ProbeAgent(onRun: o => seen = o);
+        var agent = new FoundryHostedRequestAgent(inner);
+#pragma warning disable MEAI001
+        var plain = new AgentRunOptions
+        {
+            AllowBackgroundResponses = true,
+            ResponseFormat = ChatResponseFormat.Text,
+        };
+#pragma warning restore MEAI001
+
+        await agent.RunAsync("hi", new TestSession(), plain);
+
+        var cro = Assert.IsType<ChatClientAgentRunOptions>(seen);
+        Assert.True(cro.AllowBackgroundResponses);
+        Assert.Same(ChatResponseFormat.Text, cro.ResponseFormat);
+    }
+
+    [Fact]
+    public async Task ReusedRunOptions_DoesNotStackRawRepresentationFactoriesAsync()
+    {
+        CreateResponseOptions? first = null;
+        CreateResponseOptions? second = null;
+        int run = 0;
+        var inner = new ProbeAgent(onRun: options =>
+        {
+            if (options is not ChatClientAgentRunOptions { ChatOptions.RawRepresentationFactory: { } factory })
+            {
+                return;
+            }
+
+            var created = factory(null!) as CreateResponseOptions;
+            if (run++ == 0)
+            {
+                first = created;
+            }
+            else
+            {
+                second = created;
+            }
+        });
+        var agent = new FoundryHostedRequestAgent(inner);
+        var session = new TestSession();
+        session.FoundryHostedAgentSessionId = "sess-shared";
+        var reused = new ChatClientAgentRunOptions(new ChatOptions());
+
+        await agent.RunAsync("hi", session, reused);
+        await agent.RunAsync("hi", session, reused);
+
+        Assert.NotNull(first);
+        Assert.NotNull(second);
+        Assert.NotSame(first, second);
+        Assert.Null(reused.ChatOptions!.RawRepresentationFactory);
+    }
+
+    [Fact]
+    public async Task EndToEnd_UserIdentity_AndHostedSessionId_ReachWireAsync()
+    {
+        using var handler = new RecordingHandler(
+            MinimalResponseJson(),
+            responseHeaders: new Dictionary<string, string>
+            {
+                ["x-agent-session-id"] = "sess-from-platform",
+            });
+#pragma warning disable CA5399
+        using var http = new HttpClient(handler);
+#pragma warning restore CA5399
+        var openAIOptions = new OpenAIClientOptions { Transport = new HttpClientPipelineTransport(http) };
+        var openAIClient = new OpenAIClient(new ApiKeyCredential("fake"), openAIOptions);
+        IChatClient chatClient = openAIClient.GetResponsesClient().AsIChatClient();
+
+#pragma warning disable MEAI001
+        var policies = chatClient.GetService<OpenAIRequestPolicies>();
+        Assert.NotNull(policies);
+        OpenAIRequestPoliciesReflection.AddPolicyIfMissing(policies!, ClientHeadersPolicy.Instance);
+        OpenAIRequestPoliciesReflection.AddPolicyIfMissing(policies!, UserIdentityPolicy.Instance);
+        OpenAIRequestPoliciesReflection.AddPolicyIfMissing(policies!, HostedSessionIdCapturePolicy.Instance);
+#pragma warning restore MEAI001
+
+        var chatAgent = new ChatClientAgent(chatClient);
+        AIAgent agent = new FoundryHostedRequestAgent(new ClientHeadersAgent(chatAgent));
+        AgentSession session = await chatAgent.CreateSessionAsync();
+        session.FoundryHostedAgentSessionId = "sess-pinned";
+
+        var runOptions = new ChatClientAgentRunOptions(
+            new ChatOptions()
+                .WithFoundryHostedAgentUserIdentity("alice")
+                .WithClientHeader("x-client-end-user-id", "alice-app"));
+
+        // Response returns a different hosted session id than the pin → unexpected switch.
+        InvalidOperationException ex = await Assert.ThrowsAsync<InvalidOperationException>(
+            () => agent.RunAsync("hi", session, runOptions));
+        Assert.Contains("Unexpected Foundry hosted session switch", ex.Message, StringComparison.Ordinal);
+
+        Assert.True(handler.Requests.Count > 0);
+        var req = handler.Requests[0];
+        Assert.Equal("alice", req.Headers[FoundryChatOptionsExtensions.FoundryHostedAgentUserIdentityHeaderName]);
+        Assert.Equal("alice-app", req.Headers["x-client-end-user-id"]);
+        Assert.Contains("\"agent_session_id\":\"sess-pinned\"", req.Body, StringComparison.Ordinal);
+        // Sticky pin must not be overwritten by the conflicting response id.
+        Assert.Equal("sess-pinned", session.FoundryHostedAgentSessionId);
+    }
+
+    [Fact]
+    public async Task EndToEnd_PinnedHostedSessionId_MatchingResponseKeepsStickyAsync()
+    {
+        using var handler = new RecordingHandler(
+            MinimalResponseJson(),
+            responseHeaders: new Dictionary<string, string>
+            {
+                ["x-agent-session-id"] = "sess-pinned",
+            });
+#pragma warning disable CA5399
+        using var http = new HttpClient(handler);
+#pragma warning restore CA5399
+        var openAIClient = new OpenAIClient(
+            new ApiKeyCredential("fake"),
+            new OpenAIClientOptions { Transport = new HttpClientPipelineTransport(http) });
+        IChatClient chatClient = openAIClient.GetResponsesClient().AsIChatClient();
+
+#pragma warning disable MEAI001
+        var policies = chatClient.GetService<OpenAIRequestPolicies>()!;
+        OpenAIRequestPoliciesReflection.AddPolicyIfMissing(policies, HostedSessionIdCapturePolicy.Instance);
+#pragma warning restore MEAI001
+
+        var chatAgent = new ChatClientAgent(chatClient);
+        AIAgent agent = new FoundryHostedRequestAgent(chatAgent);
+        AgentSession session = await chatAgent.CreateSessionAsync();
+        session.FoundryHostedAgentSessionId = "sess-pinned";
+
+        await agent.RunAsync("hi", session);
+
+        Assert.Equal("sess-pinned", session.FoundryHostedAgentSessionId);
+        Assert.Contains("\"agent_session_id\":\"sess-pinned\"", handler.Requests[0].Body, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public async Task EndToEnd_ServiceManaged_CapturesHostedSessionIdOntoSessionAsync()
+    {
+        using var handler = new RecordingHandler(
+            MinimalResponseJson(),
+            responseHeaders: new Dictionary<string, string>
+            {
+                ["x-agent-session-id"] = "sess-created",
+            });
+#pragma warning disable CA5399
+        using var http = new HttpClient(handler);
+#pragma warning restore CA5399
+        var openAIClient = new OpenAIClient(
+            new ApiKeyCredential("fake"),
+            new OpenAIClientOptions { Transport = new HttpClientPipelineTransport(http) });
+        IChatClient chatClient = openAIClient.GetResponsesClient().AsIChatClient();
+
+#pragma warning disable MEAI001
+        var policies = chatClient.GetService<OpenAIRequestPolicies>()!;
+        OpenAIRequestPoliciesReflection.AddPolicyIfMissing(policies, HostedSessionIdCapturePolicy.Instance);
+#pragma warning restore MEAI001
+
+        var chatAgent = new ChatClientAgent(chatClient);
+        AIAgent agent = new FoundryHostedRequestAgent(chatAgent);
+        AgentSession session = await chatAgent.CreateSessionAsync();
+
+        await agent.RunAsync("hi", session);
+
+        Assert.Equal("sess-created", session.FoundryHostedAgentSessionId);
+        Assert.DoesNotContain("agent_session_id", handler.Requests[0].Body, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public void Constructor_PreWiresFoundryHostedRequestAgent()
+    {
+        FoundryAgent agent = CreateFoundryAgent();
+        Assert.NotNull(agent.GetService<FoundryHostedRequestAgent>());
+        Assert.NotNull(agent.GetService<ClientHeadersAgent>());
+    }
+
+    private static FoundryAgent CreateFoundryAgent() =>
+        new(
+            new Uri("https://test.services.ai.azure.com/api/projects/test-project"),
+            new FakeAuthenticationTokenProvider(),
+            model: "gpt-4o-mini",
+            instructions: "Test");
+
+    private static string MinimalResponseJson() => """
+        {
+          "id":"resp_1","object":"response","created_at":1700000000,"status":"completed",
+          "model":"fake","output":[],"usage":{"input_tokens":1,"output_tokens":1,"total_tokens":2}
+        }
+        """;
+
+    private sealed class TestSession : AgentSession;
+
+    private sealed class ProbeAgent : AIAgent
+    {
+        private readonly Action<AgentRunOptions?>? _onRun;
+
+        public ProbeAgent(Action<AgentRunOptions?>? onRun = null)
+        {
+            this._onRun = onRun;
+        }
+
+        public int RunCount { get; private set; }
+
+        protected override Task<AgentResponse> RunCoreAsync(
+            IEnumerable<ChatMessage> messages,
+            AgentSession? session = null,
+            AgentRunOptions? options = null,
+            CancellationToken cancellationToken = default)
+        {
+            this.RunCount++;
+            this._onRun?.Invoke(options);
+            return Task.FromResult(new AgentResponse());
+        }
+
+        protected override async IAsyncEnumerable<AgentResponseUpdate> RunCoreStreamingAsync(
+            IEnumerable<ChatMessage> messages,
+            AgentSession? session = null,
+            AgentRunOptions? options = null,
+            [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken = default)
+        {
+            this.RunCount++;
+            this._onRun?.Invoke(options);
+            await Task.Yield();
+            yield break;
+        }
+
+        protected override ValueTask<AgentSession> CreateSessionCoreAsync(CancellationToken cancellationToken = default) =>
+            new(new TestSession());
+
+        protected override ValueTask<JsonElement> SerializeSessionCoreAsync(
+            AgentSession session,
+            JsonSerializerOptions? jsonSerializerOptions,
+            CancellationToken cancellationToken = default) =>
+            new(JsonDocument.Parse("{}").RootElement);
+
+        protected override ValueTask<AgentSession> DeserializeSessionCoreAsync(
+            JsonElement serializedState,
+            JsonSerializerOptions? jsonSerializerOptions,
+            CancellationToken cancellationToken = default) =>
+            new(new TestSession());
+    }
+
+    private sealed class RecordingHandler : HttpClientHandler
+    {
+        private readonly string _body;
+        private readonly Dictionary<string, string> _responseHeaders;
+
+        public RecordingHandler(string body, Dictionary<string, string>? responseHeaders = null)
+        {
+            this._body = body;
+            this._responseHeaders = responseHeaders ?? new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+        }
+
+        public List<RecordedRequest> Requests { get; } = [];
+
+        protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
+        {
+            var headers = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+            foreach (var h in request.Headers)
+            {
+                headers[h.Key] = string.Join(",", h.Value);
+            }
+
+            string body;
+            if (request.Content is null)
+            {
+                body = string.Empty;
+            }
+            else
+            {
+#if NET
+                body = await request.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
+#else
+                body = await request.Content.ReadAsStringAsync().ConfigureAwait(false);
+#endif
+            }
+
+            this.Requests.Add(new RecordedRequest(headers, body));
+
+            var resp = new HttpResponseMessage(HttpStatusCode.OK)
+            {
+                Content = new StringContent(this._body, Encoding.UTF8, "application/json"),
+                RequestMessage = request,
+            };
+            foreach (var kvp in this._responseHeaders)
+            {
+                resp.Headers.TryAddWithoutValidation(kvp.Key, kvp.Value);
+            }
+
+            return resp;
+        }
+    }
+
+    private sealed class RecordedRequest(Dictionary<string, string> headers, string body)
+    {
+        public Dictionary<string, string> Headers { get; } = headers;
+        public string Body { get; } = body;
+    }
+}

dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/Microsoft.Agents.AI.Foundry.UnitTests.csproj

@@ -21,6 +21,7 @@
     <Compile Remove="FoundryEvalConverterTests.cs" />
     <Compile Remove="FoundryEvalsTests.cs" />
     <Compile Remove="ClientHeadersExtensionsTests.cs" />
+    <Compile Remove="FoundryHostedRequestTests.cs" />
     <Compile Remove="ServedModelTestHelpers.cs" />
     <Compile Remove="ServedModelScopeTests.cs" />
     <Compile Remove="ServedModelPolicyTests.cs" />

dotnet/tests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests/MapAGUIServerEndpointRouteBuilderExtensionsTests.cs

@@ -0,0 +1,210 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text.Json;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Routing;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.DependencyInjection;
+using Moq;
+
+namespace Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests;
+
+/// <summary>
+/// Unit tests for the agent-name-derived <c>MapAGUIServer</c> overloads.
+/// </summary>
+public sealed class MapAGUIServerEndpointRouteBuilderExtensionsTests
+{
+    [Fact]
+    public void MapAGUIServer_WithAgentBuilder_MapsNameDerivedRoute()
+    {
+        // Arrange
+        using WebApplication app = CreateApp("test-agent");
+        Mock<IHostedAgentBuilder> agentBuilder = new();
+        agentBuilder.SetupGet(builder => builder.Name).Returns("test-agent");
+
+        // Act
+        app.MapAGUIServer(agentBuilder.Object);
+
+        // Assert
+        Assert.Contains(GetRoutePatterns(app), pattern => pattern == "/test-agent/agui");
+    }
+
+    [Fact]
+    public void MapAGUIServer_WithAgentName_MapsNameDerivedRoute()
+    {
+        // Arrange
+        using WebApplication app = CreateApp("test-agent");
+
+        // Act
+        app.MapAGUIServer("test-agent");
+
+        // Assert
+        Assert.Contains(GetRoutePatterns(app), pattern => pattern == "/test-agent/agui");
+    }
+
+    [Fact]
+    public void MapAGUIServer_WithAgent_MapsNameDerivedRoute()
+    {
+        // Arrange
+        using WebApplication app = CreateApp();
+        AIAgent agent = new TestAgent("test-agent");
+
+        // Act
+        app.MapAGUIServer(agent);
+
+        // Assert
+        Assert.Contains(GetRoutePatterns(app), pattern => pattern == "/test-agent/agui");
+    }
+
+    [Fact]
+    public void MapAGUIServer_WithNullEndpoints_ThrowsArgumentNullException()
+    {
+        // Arrange
+        IEndpointRouteBuilder endpoints = null!;
+        AIAgent agent = new TestAgent("test-agent");
+
+        // Act
+        ArgumentNullException exception = Assert.Throws<ArgumentNullException>(() => endpoints.MapAGUIServer(agent));
+
+        // Assert
+        Assert.Equal("endpoints", exception.ParamName);
+    }
+
+    [Fact]
+    public void MapAGUIServer_WithNullAgentBuilder_ThrowsArgumentNullException()
+    {
+        // Arrange
+        using WebApplication app = CreateApp();
+
+        // Act
+        ArgumentNullException exception = Assert.Throws<ArgumentNullException>(() => app.MapAGUIServer((IHostedAgentBuilder)null!));
+
+        // Assert
+        Assert.Equal("agentBuilder", exception.ParamName);
+    }
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    [InlineData("   ")]
+    public void MapAGUIServer_WithNullOrWhitespaceAgentName_ThrowsArgumentException(string? agentName)
+    {
+        // Arrange
+        using WebApplication app = CreateApp();
+
+        // Act
+        ArgumentException exception = Assert.ThrowsAny<ArgumentException>(() => app.MapAGUIServer(agentName!));
+
+        // Assert
+        Assert.Equal("agentName", exception.ParamName);
+    }
+
+    [Fact]
+    public void MapAGUIServer_WithNullAgent_ThrowsArgumentNullException()
+    {
+        // Arrange
+        using WebApplication app = CreateApp();
+
+        // Act
+        ArgumentNullException exception = Assert.Throws<ArgumentNullException>(() => app.MapAGUIServer((AIAgent)null!));
+
+        // Assert
+        Assert.Equal("aiAgent", exception.ParamName);
+    }
+
+    [Theory]
+    [InlineData("agent with spaces")]
+    [InlineData("agent<script>")]
+    [InlineData("agent?query")]
+    [InlineData("agent#fragment")]
+    public void MapAGUIServer_WithInvalidAgentName_ThrowsArgumentException(string agentName)
+    {
+        // Arrange
+        using WebApplication app = CreateApp();
+        AIAgent agent = new TestAgent(agentName);
+
+        // Act
+        ArgumentException exception = Assert.Throws<ArgumentException>(() => app.MapAGUIServer(agent));
+
+        // Assert
+        Assert.Equal("agentName", exception.ParamName);
+    }
+
+    [Theory]
+    [InlineData("agent-name")]
+    [InlineData("agent_name")]
+    [InlineData("agent.name")]
+    [InlineData("agent123")]
+    public void MapAGUIServer_WithValidAgentName_MapsNameDerivedRoute(string agentName)
+    {
+        // Arrange
+        using WebApplication app = CreateApp();
+        AIAgent agent = new TestAgent(agentName);
+
+        // Act
+        app.MapAGUIServer(agent);
+
+        // Assert
+        Assert.Contains(GetRoutePatterns(app), pattern => pattern == $"/{agentName}/agui");
+    }
+
+    private static WebApplication CreateApp(string? keyedAgentName = null)
+    {
+        WebApplicationBuilder builder = WebApplication.CreateBuilder();
+        builder.Services.AddAGUIServer();
+
+        if (keyedAgentName is not null)
+        {
+            builder.Services.AddKeyedSingleton<AIAgent>(keyedAgentName, new TestAgent(keyedAgentName));
+        }
+
+        return builder.Build();
+    }
+
+    private static IEnumerable<string?> GetRoutePatterns(WebApplication app) =>
+        ((IEndpointRouteBuilder)app).DataSources
+            .SelectMany(dataSource => dataSource.Endpoints)
+            .OfType<RouteEndpoint>()
+            .Select(endpoint => endpoint.RoutePattern.RawText);
+
+    private sealed class TestAgent(string? name) : AIAgent
+    {
+        protected override string? IdCore => name;
+
+        public override string? Name => name;
+
+        protected override Task<AgentResponse> RunCoreAsync(
+            IEnumerable<ChatMessage> messages,
+            AgentSession? session = null,
+            AgentRunOptions? options = null,
+            CancellationToken cancellationToken = default) =>
+            throw new NotImplementedException();
+
+        protected override IAsyncEnumerable<AgentResponseUpdate> RunCoreStreamingAsync(
+            IEnumerable<ChatMessage> messages,
+            AgentSession? session = null,
+            AgentRunOptions? options = null,
+            CancellationToken cancellationToken = default) =>
+            throw new NotImplementedException();
+
+        protected override ValueTask<AgentSession> CreateSessionCoreAsync(CancellationToken cancellationToken = default) =>
+            throw new NotImplementedException();
+
+        protected override ValueTask<AgentSession> DeserializeSessionCoreAsync(
+            JsonElement serializedState,
+            JsonSerializerOptions? jsonSerializerOptions = null,
+            CancellationToken cancellationToken = default) =>
+            throw new NotImplementedException();
+
+        protected override ValueTask<JsonElement> SerializeSessionCoreAsync(
+            AgentSession session,
+            JsonSerializerOptions? jsonSerializerOptions = null,
+            CancellationToken cancellationToken = default) =>
+            throw new NotImplementedException();
+    }
+}

dotnet/tests/Microsoft.Agents.AI.UnitTests/ChatClient/ChatClientAgentOptionsTests.cs

@@ -24,6 +24,7 @@ public class ChatClientAgentOptionsTests
         Assert.Null(options.ChatHistoryProvider);
         Assert.Null(options.AIContextProviders);
         Assert.False(options.UseProvidedChatClientAsIs);
+        Assert.False(options.AllowConcurrentInvocation);
         Assert.True(options.ClearOnChatHistoryProviderConflict);
         Assert.True(options.WarnOnChatHistoryProviderConflict);
         Assert.True(options.ThrowOnChatHistoryProviderConflict);
@@ -131,6 +132,7 @@ public class ChatClientAgentOptionsTests
             ChatHistoryProvider = mockChatHistoryProvider,
             AIContextProviders = [mockAIContextProvider],
             UseProvidedChatClientAsIs = true,
+            AllowConcurrentInvocation = true,
             ClearOnChatHistoryProviderConflict = false,
             WarnOnChatHistoryProviderConflict = false,
             ThrowOnChatHistoryProviderConflict = false,
@@ -149,6 +151,7 @@ public class ChatClientAgentOptionsTests
         Assert.Same(original.ChatHistoryProvider, clone.ChatHistoryProvider);
         Assert.Equal(original.AIContextProviders, clone.AIContextProviders);
         Assert.Equal(original.UseProvidedChatClientAsIs, clone.UseProvidedChatClientAsIs);
+        Assert.Equal(original.AllowConcurrentInvocation, clone.AllowConcurrentInvocation);
         Assert.Equal(original.ClearOnChatHistoryProviderConflict, clone.ClearOnChatHistoryProviderConflict);
         Assert.Equal(original.WarnOnChatHistoryProviderConflict, clone.WarnOnChatHistoryProviderConflict);
         Assert.Equal(original.ThrowOnChatHistoryProviderConflict, clone.ThrowOnChatHistoryProviderConflict);

dotnet/tests/Microsoft.Agents.AI.UnitTests/ChatClient/ChatClientExtensionsTests.cs

@@ -72,6 +72,43 @@ public sealed class ChatClientExtensionsTests
         Assert.Same(chatClientMock.Object, agent.ChatClient);
     }
 
+    [Fact]
+    public void CreateAIAgent_WithConcurrentInvocation_EnablesConcurrentFunctionInvocation()
+    {
+        // Arrange
+        var chatClientMock = new Mock<IChatClient>();
+        var options = new ChatClientAgentOptions { AllowConcurrentInvocation = true };
+
+        // Act
+        var agent = chatClientMock.Object.AsAIAgent(options);
+
+        // Assert
+        var functionInvokingClient = agent.ChatClient.GetService<FunctionInvokingChatClient>();
+        Assert.NotNull(functionInvokingClient);
+        Assert.True(functionInvokingClient.AllowConcurrentInvocation);
+    }
+
+    [Theory]
+    [InlineData(false, true)]
+    [InlineData(true, false)]
+    public void CreateAIAgent_WithExistingFunctionInvokingChatClient_ConfiguresConcurrentInvocation(bool initiallyEnabled, bool allowConcurrentInvocation)
+    {
+        // Arrange
+        var chatClientMock = new Mock<IChatClient>();
+        var chatClient = chatClientMock.Object.AsBuilder()
+            .UseFunctionInvocation(configure: client => client.AllowConcurrentInvocation = initiallyEnabled)
+            .Build();
+        var options = new ChatClientAgentOptions { AllowConcurrentInvocation = allowConcurrentInvocation };
+
+        // Act
+        var agent = chatClient.AsAIAgent(options);
+
+        // Assert
+        var functionInvokingClient = agent.ChatClient.GetService<FunctionInvokingChatClient>();
+        Assert.NotNull(functionInvokingClient);
+        Assert.True(functionInvokingClient.AllowConcurrentInvocation);
+    }
+
     [Fact]
     public void CreateAIAgent_WithNullClient_Throws()
     {

python/AGENTS.md

@@ -64,8 +64,9 @@ serialization, or transport result handling must follow
 [the function-calling loop specification](../docs/specs/004-python-function-calling-loop.md). This area requires
 extra validation because small changes can duplicate side effects, orphan call/result pairs, replay stale approval
 authority, or make streaming and non-streaming behavior diverge. Update the specification and its scenario-to-test
-mapping whenever coverage or behavior changes. External contributors must check with the Agent Framework core team
-before picking up issues in this area.
+mapping only when the documented contract, scenario inventory, or authoritative scenario-to-test mapping materially
+changes. Adding or modifying tests that preserve existing documented behavior does not require a specification update.
+External contributors must check with the Agent Framework core team before picking up issues in this area.
 
 ## Project Structure
 

python/CHANGELOG.md

@@ -7,8 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.14.0] - 2026-08-13
+
+### Added
+- **agent-framework-core**, **agent-framework-mistral**: Add a Mistral chat client with native chat, streaming, tools, structured output, and embeddings support ([#7392](https://github.com/microsoft/agent-framework/pull/7392))
+- **agent-framework-core**: Add experimental AGENT-HOOKS-0.1 enforcement middleware behind the opt-in `agent-hooks` extra ([#7515](https://github.com/microsoft/agent-framework/pull/7515))
+- **agent-framework-openai**: Add request preparation and response parsing hooks to `OpenAIChatCompletionClient` ([#7028](https://github.com/microsoft/agent-framework/pull/7028))
+- **agent-framework-ag-ui**: Add workflow checkpoint creation and resume support to `AgentFrameworkWorkflow` ([#6646](https://github.com/microsoft/agent-framework/pull/6646))
+- **agent-framework-core**: Add `BackgroundAgentsProvider.release_session()` for safely cancelling work and releasing per-session runtime state ([#7450](https://github.com/microsoft/agent-framework/pull/7450))
+- **agent-framework-foundry-hosting**: Add provider-based Foundry state stores for agent sessions, checkpoints, and function approvals ([#7533](https://github.com/microsoft/agent-framework/pull/7533))
+- **agent-framework-foundry**: Export the Foundry hosted-agent session-state key used for service session continuity ([#7608](https://github.com/microsoft/agent-framework/pull/7608))
+- **agent-framework-orchestrations**: Expose the Magentic orchestrator manager name as `MagenticOrchestrator.MANAGER_NAME` ([#7350](https://github.com/microsoft/agent-framework/pull/7350))
+- **agent-framework-gemini**: Surface Gemini thought summaries as reasoning content ([#7488](https://github.com/microsoft/agent-framework/pull/7488))
+- **samples**: Add a locally hosted Responses sample for the agent harness ([#7010](https://github.com/microsoft/agent-framework/pull/7010))
+
 ### Changed
-- **agent-framework-azurefunctions**, **agent-framework-durabletask**: The Durable Task and Azure Functions integrations (package sources and samples) have moved to the [Durable Agent Framework extension repository](https://github.com/microsoft/agent-framework-durable-extension) and are now developed and published from there. **agent-framework-core** continues to re-export their public symbols via `agent_framework.azure` and to include both packages in its `all` extra (installed from PyPI), so existing imports and `pip install agent-framework[all]` are unaffected.
+- **agent-framework**, **agent-framework-core**, **agent-framework-azurefunctions**, **agent-framework-durabletask**: Move the Durable Task and Azure Functions integrations to the [Durable Agent Framework extension repository](https://github.com/microsoft/agent-framework-durable-extension); core continues to re-export their public symbols and install their independently published packages through the `all` extra ([#7465](https://github.com/microsoft/agent-framework/pull/7465))
+- **agent-framework-core**: [BREAKING — experimental] Require functional workflow definitions to be built into stateful workflow instances before running or adapting them as agents ([#7521](https://github.com/microsoft/agent-framework/pull/7521))
+- **agent-framework-foundry-hosting**: [BREAKING — beta] Migrate Foundry Hosted Agents to the Agent Server Responses 2.x storage model ([#7533](https://github.com/microsoft/agent-framework/pull/7533))
+- **agent-framework-foundry-hosting**, **agent-framework-azure-contentunderstanding**: Update Azure Agent Server dependencies to the 2.1 beta line and adapt request and storage handling ([#7621](https://github.com/microsoft/agent-framework/pull/7621))
+- **agent-framework-foundry**: Make encrypted reasoning opt-in for Foundry chat requests ([#7536](https://github.com/microsoft/agent-framework/pull/7536))
+- **agent-framework-mem0**: Separate Mem0 storage and search scopes ([#7531](https://github.com/microsoft/agent-framework/pull/7531))
+- **agent-framework-ag-ui**: Consolidate thread-snapshot ownership and remove unused internal orchestration helpers ([#7426](https://github.com/microsoft/agent-framework/pull/7426), [#7479](https://github.com/microsoft/agent-framework/pull/7479))
+- **agent-framework-devui**: Update frontend transitive dependencies ([#7493](https://github.com/microsoft/agent-framework/pull/7493), [#7554](https://github.com/microsoft/agent-framework/pull/7554))
+- **agent-framework-mistral**, **agent-framework-ollama**: Expand the supported `uv_build` version range ([#7445](https://github.com/microsoft/agent-framework/pull/7445))
+- **tests**: Update Python development tools and improve sample validation with deterministic replay ([#7350](https://github.com/microsoft/agent-framework/pull/7350), [#7445](https://github.com/microsoft/agent-framework/pull/7445), [#7541](https://github.com/microsoft/agent-framework/pull/7541), [#7545](https://github.com/microsoft/agent-framework/pull/7545))
+- **samples**: Update frontend dependencies and add a Foundry Hosted Agents custom-storage sample ([#7529](https://github.com/microsoft/agent-framework/pull/7529), [#7621](https://github.com/microsoft/agent-framework/pull/7621))
+
+### Fixed
+- **agent-framework-core**: Ignore excluded tool results during compaction ([#7391](https://github.com/microsoft/agent-framework/pull/7391))
+- **agent-framework-core**: Bound tool-result compaction summaries before provider calls ([#7396](https://github.com/microsoft/agent-framework/pull/7396))
+- **agent-framework-core**: Report evaluator results with zero checks correctly ([#7399](https://github.com/microsoft/agent-framework/pull/7399))
+- **agent-framework-core**: Reject Windows junctions while discovering and accessing skills ([#7507](https://github.com/microsoft/agent-framework/pull/7507))
+- **agent-framework-core**: Warn when advertised MCP archives are rejected ([#7622](https://github.com/microsoft/agent-framework/pull/7622))
+- **agent-framework-core**: Prevent streaming transcript duplication with message injection and per-service-call persistence ([#7605](https://github.com/microsoft/agent-framework/pull/7605))
+- **agent-framework-ag-ui**, **agent-framework-core**: Preserve conversation correlation across AG-UI runs ([#7430](https://github.com/microsoft/agent-framework/pull/7430))
+- **agent-framework-ag-ui**: Preserve approval resume semantics at the protocol boundary ([#7480](https://github.com/microsoft/agent-framework/pull/7480))
+- **agent-framework-ag-ui**: Make approval lifecycle, interruption recovery, and replay behavior occurrence-safe ([#7594](https://github.com/microsoft/agent-framework/pull/7594))
+- **agent-framework-azure-ai-search**: Forward query-source identity to Azure AI Search ([#7278](https://github.com/microsoft/agent-framework/pull/7278))
+- **agent-framework-azure-cosmos-memory**: Call the renamed Cosmos toolkit registration API ([#7635](https://github.com/microsoft/agent-framework/pull/7635))
+- **agent-framework-claude**: Avoid reusing one Claude SDK client across distinct fresh sessions ([#7404](https://github.com/microsoft/agent-framework/pull/7404))
+- **agent-framework-copilotstudio**: Handle large activities without line-length failures, update the Copilot Studio client dependency, and declare its required HTTP and authentication runtime dependencies ([#7417](https://github.com/microsoft/agent-framework/pull/7417))
+- **agent-framework-declarative**: Preserve falsey `EditTableV2` items and robustly extract JSON from declarative workflow responses ([#7380](https://github.com/microsoft/agent-framework/pull/7380), [#7550](https://github.com/microsoft/agent-framework/pull/7550))
+- **agent-framework-foundry**: Preserve Foundry hosted-agent session IDs independently from conversation continuation IDs ([#7608](https://github.com/microsoft/agent-framework/pull/7608))
+- **agent-framework-gemini**: Restore `thought_signature` values during approval replay ([#7546](https://github.com/microsoft/agent-framework/pull/7546))
+- **agent-framework-github-copilot**: Scope under-specified approve-for-session decisions to the current tool and align package metadata with the SDK's Python 3.11 minimum ([#7607](https://github.com/microsoft/agent-framework/pull/7607))
+- **agent-framework-mistral**: Preserve prompt-cache usage details ([#7597](https://github.com/microsoft/agent-framework/pull/7597))
+- **agent-framework-openai**: Prevent orphaned local approval responses and safely ignore non-string Chat Completions content ([#7462](https://github.com/microsoft/agent-framework/pull/7462), [#7028](https://github.com/microsoft/agent-framework/pull/7028))
+- **agent-framework-redis**: Honor a `max_messages` retention limit of zero ([#7470](https://github.com/microsoft/agent-framework/pull/7470))
 
 ## [1.13.0] - 2026-07-30
 
@@ -1477,7 +1523,8 @@ Release candidate for **agent-framework-core** and **agent-framework-azure-ai**
 
 For more information, see the [announcement blog post](https://devblogs.microsoft.com/foundry/introducing-microsoft-agent-framework-the-open-source-engine-for-agentic-ai-apps/).
 
-[Unreleased]: https://github.com/microsoft/agent-framework/compare/python-1.13.0...HEAD
+[Unreleased]: https://github.com/microsoft/agent-framework/compare/python-1.14.0...HEAD
+[1.14.0]: https://github.com/microsoft/agent-framework/compare/python-1.13.0...python-1.14.0
 [1.13.0]: https://github.com/microsoft/agent-framework/compare/python-1.12.1...python-1.13.0
 [1.12.1]: https://github.com/microsoft/agent-framework/compare/python-1.12.0...python-1.12.1
 [1.12.0]: https://github.com/microsoft/agent-framework/compare/python-1.11.0...python-1.12.0

python/PACKAGE_STATUS.md

@@ -115,7 +115,8 @@ listed below.
 
 - `agent-framework-core`: functional workflow APIs from
   `agent_framework/_workflows/_functional.py`, including `RunContext`, `step`,
-  `FunctionalWorkflow`, `workflow`, and `FunctionalWorkflowAgent`
+  `FunctionalWorkflowDefinition`, `FunctionalWorkflow`, `workflow`, and
+  `FunctionalWorkflowAgent`
 
 #### `HARNESS`
 

python/packages/ag-ui/AGENTS.md

@@ -29,10 +29,17 @@ AG-UI protocol integration for building agent UIs with the AG-UI standard.
 - Multimodal user inputs support both legacy (`text`, `binary`) and draft-style (`image`, `audio`, `video`, `document`) shapes.
 - Interrupted runs complete with `RUN_FINISHED.outcome.type == "interrupt"` and canonical `outcome.interrupts`; do not document or add new flows that depend on the legacy top-level `RUN_FINISHED.interrupt` field.
 - `Interrupt` and `ResumeEntry` come from the `ag-ui-protocol` package (`ag_ui.core`), not from an Agent Framework-specific interrupt model.
+- Tool approval interrupts, including approvals surfaced through workflow `request_info`, advertise standard
+  `approved` and full-replacement `editedArgs` responses while retaining the existing `accepted` alias and direct
+  partial edits for MAF client compatibility. A `cancelled` resume completes normally without executing that call;
+  resolved siblings in the same complete resume still proceed.
 - Approval-time execution preserves each call's complete result group. Follow-up user-input requests remain in the
   resumed messages, while `TOOL_CALL_RESULT` events are emitted only for terminal `function_result` contents.
 - Approval responses for tools injected during `before_run` are deferred to the in-run approval middleware rather
   than executed or rejected by the transport before those tools exist.
+- `_approval_lifecycle.py` is the sole owner of approval occurrence registration, trusted aliases, authority
+  validation, claims, terminal outcomes, and retry deduplication. Runner code normalizes AG-UI protocol values and
+  projects lifecycle outcomes but must not maintain a parallel pending-approval registry.
 - `confirm_changes` snapshot cleanup resolves the synthetic confirmation back to its original `function_call_id`;
   it must never concatenate unrelated tool results or record accepted changes without a matching real result.
 - SSE keepalive is endpoint-owned transport behavior configured through

python/packages/ag-ui/README.md

@@ -167,10 +167,23 @@ Interrupted terminal event shape:
         "responseSchema": {
           "type": "object",
           "properties": {
+            "approved": { "type": "boolean" },
             "accepted": { "type": "boolean" },
-            "arguments": { "type": "object" }
+            "city": { "type": "string" },
+            "editedArgs": {
+              "type": "object",
+              "description": "Full replacement of the tool arguments. Not merged.",
+              "properties": {
+                "city": { "type": "string" }
+              },
+              "required": ["city"],
+              "additionalProperties": false
+            }
           },
-          "required": ["accepted"]
+          "anyOf": [
+            { "required": ["approved"] },
+            { "required": ["accepted"] }
+          ]
         },
         "metadata": {
           "agent_framework": {
@@ -192,6 +205,11 @@ Interrupted terminal event shape:
 
 Resume the paused thread with a canonical `resume` array. Each entry addresses exactly one open interrupt by
 `interruptId`; `status` is `resolved` or `cancelled`; resolved entries carry the approval or workflow response payload.
+Tool approvals use the standard `approved` field and may provide `editedArgs` as a full replacement of the tool
+arguments. For compatibility with existing MAF clients, `accepted` remains an alias for `approved`, and direct
+argument fields remain supported as partial edits. Cancellation is a normal terminal decision: cancelled calls do
+not execute, while resolved siblings in the same complete resume continue normally. The same tool-approval shape and
+resume payloads apply when an agent approval is surfaced through a workflow `request_info` event.
 
 ```json
 {

python/packages/ag-ui/agent_framework_ag_ui/_agent.py

@@ -9,7 +9,7 @@ from ag_ui.core import BaseEvent
 from agent_framework import SupportsAgentRun
 from agent_framework._telemetry import mark_feature_used
 
-from ._agent_run import PendingApprovalEntry, PendingApprovalKey, run_agent_stream
+from ._agent_run import run_agent_stream
 from ._approval_state import InMemoryAGUIApprovalStateStore
 from ._feature_usage import FeatureIndex
 from ._snapshots import AGUIThreadSnapshotStore
@@ -122,10 +122,6 @@ class AgentFrameworkAgent:
         # Server-side Approval State. Populated when approval requests are emitted
         # and consumed when resume decisions arrive.
         self._approval_state_store = InMemoryAGUIApprovalStateStore()
-        self._pending_approvals = cast(
-            dict[PendingApprovalKey, PendingApprovalEntry],
-            self._approval_state_store.pending_approvals,
-        )
 
     @property
     def snapshot_store(self) -> AGUIThreadSnapshotStore | None:
@@ -149,7 +145,6 @@ class AgentFrameworkAgent:
             input_data,
             self.agent,
             self.config,
-            pending_approvals=self._pending_approvals,
             approval_state_store=self._approval_state_store,
         ):
             yield event

python/packages/ag-ui/agent_framework_ag_ui/_approval_state.py

@@ -4,13 +4,19 @@
 
 from __future__ import annotations
 
-from collections import OrderedDict
+import copy
+from threading import RLock
 from typing import Any
 
+from ._approval_lifecycle import ApprovalCapacityError, ApprovalExecutionOwner, ApprovalLifecycle
+
 ApprovalScope = str
 """Application-defined scope for server-side AG-UI Approval State."""
 
 DEFAULT_MAX_APPROVAL_STATES = 10_000
+DEFAULT_PENDING_RETENTION_SECONDS = 86_400
+DEFAULT_INDETERMINATE_RETENTION_SECONDS = 604_800
+DEFAULT_TERMINAL_RETENTION_SECONDS = 900
 _APPROVAL_SCOPE_INPUT_KEY = "__ag_ui_approval_scope"
 _APPROVAL_THREAD_SEPARATOR = "\x1f"
 
@@ -32,15 +38,27 @@ def approval_state_thread_id(*, scope: object | None, thread_id: str) -> str:
 class InMemoryAGUIApprovalStateStore:
     """Bounded process-local server-side store for AG-UI Approval State.
 
-    The default store keeps only pending approval entries. It does not store
-    general ``AgentSession.state`` or AG-UI Thread Snapshots.
+    State is local to one process and is not durable across restarts or replicas.
+    Active and indeterminate occurrences are protected from eviction. Terminal
+    outcomes guarantee duplicate-execution protection for the configured
+    retention interval.
     """
 
-    def __init__(self, *, max_entries: int = DEFAULT_MAX_APPROVAL_STATES) -> None:
+    def __init__(
+        self,
+        *,
+        max_entries: int = DEFAULT_MAX_APPROVAL_STATES,
+        pending_retention_seconds: float = DEFAULT_PENDING_RETENTION_SECONDS,
+        indeterminate_retention_seconds: float = DEFAULT_INDETERMINATE_RETENTION_SECONDS,
+        terminal_retention_seconds: float = DEFAULT_TERMINAL_RETENTION_SECONDS,
+    ) -> None:
         """Initialize the process-local Approval State store.
 
         Keyword Args:
-            max_entries: Maximum pending approval entries to retain.
+            max_entries: Maximum approval occurrences or middleware state entries to retain.
+            pending_retention_seconds: Maximum time to retain abandoned pending approval authority.
+            indeterminate_retention_seconds: Safety window for uncertain execution records before reclamation.
+            terminal_retention_seconds: Process-local duplicate-execution protection window.
 
         Raises:
             ValueError: If ``max_entries`` is less than 1.
@@ -48,12 +66,62 @@ class InMemoryAGUIApprovalStateStore:
         if max_entries < 1:
             raise ValueError("max_entries must be greater than 0.")
         self.max_entries = max_entries
-        self.pending_approvals: OrderedDict[tuple[str, str], Any] = OrderedDict()
-        self.tool_approval_states: OrderedDict[str, dict[str, Any]] = OrderedDict()
+        self._lock = RLock()
+        self._tool_approval_states: dict[str, dict[str, Any]] = {}
+        self.lifecycle = ApprovalLifecycle(
+            max_entries=max_entries,
+            pending_retention_seconds=pending_retention_seconds,
+            indeterminate_retention_seconds=indeterminate_retention_seconds,
+            terminal_retention_seconds=terminal_retention_seconds,
+        )
 
-    def evict_oldest(self) -> None:
-        """Evict oldest pending approval entries until the store is within bounds."""
-        while len(self.pending_approvals) > self.max_entries:
-            self.pending_approvals.popitem(last=False)
-        while len(self.tool_approval_states) > self.max_entries:
-            self.tool_approval_states.popitem(last=False)
+    def register(
+        self,
+        *,
+        thread_ids: list[str],
+        name: str,
+        arguments: str,
+        request_id: str,
+        interrupt_id: str,
+        owner: ApprovalExecutionOwner,
+        scope: ApprovalScope | None = None,
+        already_approved_requests: list[dict[str, Any]] | None = None,
+        server_label: str | None = None,
+    ) -> None:
+        """Register one occurrence with its pending transition owner."""
+        unique_thread_ids = list(dict.fromkeys(thread_ids))
+        self.lifecycle.register(
+            owner=owner,
+            scope=scope,
+            thread_ids=unique_thread_ids,
+            interrupt_id=interrupt_id,
+            call_id=interrupt_id,
+            name=name,
+            arguments=arguments,
+            aliases=[request_id],
+            already_approved_requests=already_approved_requests,
+            server_label=server_label,
+        )
+
+    def set_tool_approval_state(self, thread_id: str, state: dict[str, Any]) -> None:
+        """Store approval middleware state without evicting another active thread."""
+        with self._lock:
+            if thread_id not in self._tool_approval_states and len(self._tool_approval_states) >= self.max_entries:
+                raise ApprovalCapacityError("Approval state capacity is exhausted by protected occurrences.")
+            self._tool_approval_states[thread_id] = copy.deepcopy(state)
+
+    def get_tool_approval_state(self, thread_id: str) -> dict[str, Any] | None:
+        """Return an isolated copy of server-owned middleware approval state."""
+        with self._lock:
+            state = self._tool_approval_states.get(thread_id)
+            return copy.deepcopy(state) if state is not None else None
+
+    def delete_tool_approval_state(self, thread_id: str) -> None:
+        """Delete server-owned middleware approval state for one scoped thread."""
+        with self._lock:
+            self._tool_approval_states.pop(thread_id, None)
+
+    def has_tool_approval_state(self, thread_id: str) -> bool:
+        """Return whether middleware approval state exists for one scoped thread."""
+        with self._lock:
+            return thread_id in self._tool_approval_states

python/packages/ag-ui/agent_framework_ag_ui/_message_adapters.py

@@ -152,9 +152,9 @@ def _sanitize_tool_history(
                     if content.function_call and content.function_call.call_id:
                         approval_call_ids.add(str(content.function_call.call_id))
                     if approval_accepted is None:
-                        approval_accepted = bool(content.approved)
+                        approval_accepted = content.approved is True
                     else:
-                        approval_accepted = approval_accepted and bool(content.approved)
+                        approval_accepted = approval_accepted and content.approved is True
 
             if approval_call_ids and pending_tool_call_ids:
                 pending_tool_call_ids = [
@@ -203,7 +203,7 @@ def _sanitize_tool_history(
                             contents=[
                                 Content.from_function_result(
                                     call_id=pending_confirm_changes_id,
-                                    result="Confirmed" if parsed.get("accepted") else "Rejected",
+                                    result="Confirmed" if parsed.get("accepted") is True else "Rejected",
                                 )
                             ],
                         )
@@ -360,9 +360,10 @@ def _extract_multimodal_source_fields(
 ) -> tuple[str | None, str | None, str | None, str | None]:
     """Extract ``(url, data, binary_id, mime_type)`` from an AG-UI multimodal part.
 
-    Handles both the current AG-UI spec (``source.value`` for base64 payloads) and the
-    legacy ``source.data`` field for backward compatibility. Returned values are the
-    raw extracted strings (or ``None`` when absent); callers apply their own defaults.
+    Handles both the current AG-UI spec (``source.value`` for both URL and base64
+    payloads) and the legacy ``source.url``/``source.data`` fields for backward
+    compatibility. Returned values are the raw extracted strings (or ``None`` when
+    absent); callers apply their own defaults.
     """
     mime_type = cast(str | None, part.get("mimeType") or part.get("mime_type"))
     url = cast(str | None, part.get("url") or part.get("uri"))
@@ -378,7 +379,7 @@ def _extract_multimodal_source_fields(
             mime_type = source_mime
 
         if source_type in {"url", "uri"}:
-            url = cast(str | None, source_dict.get("url") or source_dict.get("uri"))
+            url = cast(str | None, source_dict.get("value") or source_dict.get("url") or source_dict.get("uri"))
         elif source_type in {"base64", "data", "binary"}:
             data = cast(str | None, source_dict.get("value") or source_dict.get("data"))
         elif source_type in {"id", "file"}:
@@ -724,7 +725,7 @@ def agui_messages_to_agent_framework(messages: list[dict[str, Any]]) -> list[Mes
                 # Look for the matching function call in previous messages to create
                 # proper function_approval_response content. This enables the agent framework
                 # to execute the approved tool (fix for GitHub issue #3034).
-                accepted = parsed.get("accepted", False) if parsed is not None else False
+                accepted = parsed.get("accepted") is True if parsed is not None else False
                 approval_payload_text = result_content if isinstance(result_content, str) else json.dumps(parsed)
 
                 # Log the full approval payload to debug modified arguments
@@ -932,7 +933,7 @@ def agui_messages_to_agent_framework(messages: list[dict[str, Any]]) -> list[Mes
 
                 # Create the approval response
                 approval_response = Content.from_function_approval_response(
-                    approved=approval.get("approved", True),
+                    approved=approval.get("approved") is True,
                     id=approval.get("id", ""),
                     function_call=func_call,
                 )

python/packages/ag-ui/agent_framework_ag_ui/_run_common.py

@@ -374,22 +374,37 @@ def _json_schema_for_value(value: Any) -> dict[str, Any]:
 
 def _approval_response_schema(arguments: Mapping[str, Any] | None = None) -> dict[str, Any]:
     """Build the response schema generic AG-UI clients use to render approval input."""
+    reserved_properties = {"approved", "accepted", "editedArgs"}
     properties: dict[str, Any] = {
-        "accepted": {
+        "approved": {
             "type": "boolean",
             "description": "Whether the requested tool call is approved.",
-        }
+        },
+        "accepted": {
+            "type": "boolean",
+            "description": "Legacy alias for approved.",
+        },
     }
-    if arguments:
+    if arguments is not None:
+        edited_argument_properties: dict[str, Any] = {}
         for name, value in arguments.items():
             argument_schema = _json_schema_for_value(value)
             argument_schema["description"] = f"Optional edited value for the '{name}' tool argument."
-            properties[str(name)] = argument_schema
+            if str(name) not in reserved_properties:
+                properties[str(name)] = argument_schema
+            edited_argument_properties[str(name)] = _json_schema_for_value(value)
+        properties["editedArgs"] = {
+            "type": "object",
+            "description": "Full replacement of the tool arguments. Not merged.",
+            "properties": edited_argument_properties,
+            "required": list(edited_argument_properties),
+            "additionalProperties": False,
+        }
 
     return {
         "type": "object",
         "properties": properties,
-        "required": ["accepted"],
+        "anyOf": [{"required": ["approved"]}, {"required": ["accepted"]}],
         "additionalProperties": False,
     }
 

python/packages/ag-ui/agent_framework_ag_ui/_snapshot_session.py

@@ -181,6 +181,16 @@ class ThreadSnapshotSession:
         Clears all interrupts when ``interrupt_ids`` is omitted. Failures are
         logged and swallowed for the same reason as :meth:`save`.
         """
+        if self._stored is not None and self._stored.interrupt is not None:
+            if interrupt_ids is None:
+                self._stored.interrupt = None
+            else:
+                remaining_interrupts = [
+                    interrupt
+                    for interrupt in self._stored.interrupt
+                    if str(interrupt.get("id") or interrupt.get("interruptId")) not in interrupt_ids
+                ]
+                self._stored.interrupt = remaining_interrupts or None
         if self._store is None or self._scope is None:
             return
         await _clear_thread_snapshot_interrupt(

python/packages/ag-ui/agent_framework_ag_ui/_workflow_run.py

@@ -41,6 +41,8 @@ from agent_framework.observability import (
 from ._message_adapters import normalize_agui_input_messages
 from ._run_common import (
     FlowState,
+    _approval_interrupt_for_function_call,  # pyright: ignore[reportPrivateUsage]
+    _approval_response_schema,  # pyright: ignore[reportPrivateUsage]
     _build_run_finished_event,
     _close_reasoning_block,
     _emit_content,
@@ -191,6 +193,26 @@ def _interrupt_entry_for_request_event(request_event: Any) -> dict[str, Any] | N
         return None
 
     value = _workflow_interrupt_value(request_payload.get("data"))
+    request_data = getattr(request_event, "data", None)
+    if (
+        isinstance(request_data, Content)
+        and request_data.type == "function_approval_request"
+        and request_data.function_call is not None
+    ):
+        workflow_metadata = _workflow_interrupt_metadata(request_payload, value)["agent_framework"]
+        workflow_metadata.pop("type", None)
+        response_schema = (
+            _approval_response_schema()
+            if request_data.function_call.additional_properties.get("server_label")
+            else None
+        )
+        return _approval_interrupt_for_function_call(
+            interrupt_id=str(request_payload["request_id"]),
+            function_call=request_data.function_call,
+            metadata=workflow_metadata,
+            response_schema=response_schema,
+        )
+
     entry: dict[str, Any] = {
         "id": str(request_payload["request_id"]),
         "reason": "input_required",
@@ -303,16 +325,11 @@ def _pending_workflow_interrupt_ids(pending_events: dict[str, Any]) -> set[str]:
 def _resume_error_for_pending_workflow_requests(
     resume_entries: list[dict[str, Any]],
 ) -> RunErrorEvent | None:
-    """Return a workflow resume error for explicit non-resolved canonical resume entries."""
+    """Return a workflow resume error for unsupported canonical resume entries."""
     for entry in resume_entries:
         interrupt_id = str(entry["interrupt_id"])
         status = entry.get("status")
-        if status == "cancelled":
-            return RunErrorEvent(
-                message=f"Workflow resume for interruptId '{interrupt_id}' was cancelled.",
-                code="WORKFLOW_RESUME_CANCELLED",
-            )
-        if status not in {None, "resolved"}:
+        if status not in {None, "resolved", "cancelled"}:
             return RunErrorEvent(
                 message=f"Unsupported workflow resume status '{status}' for interruptId '{interrupt_id}'.",
                 code="WORKFLOW_RESUME_INVALID",
@@ -321,7 +338,7 @@ def _resume_error_for_pending_workflow_requests(
 
 
 def _consume_cancelled_workflow_requests(workflow: Workflow, resume_entries: list[dict[str, Any]]) -> None:
-    """Remove cancelled workflow request_info events from the runner context."""
+    """Remove cancelled workflow requests from runner and owning agent-executor state."""
     cancelled_ids = {str(entry["interrupt_id"]) for entry in resume_entries if entry.get("status") == "cancelled"}
     if not cancelled_ids:
         return
@@ -330,9 +347,15 @@ def _consume_cancelled_workflow_requests(workflow: Workflow, resume_entries: lis
     pending_events = getattr(runner_context, "_pending_request_info_events", None)
     if not isinstance(pending_events, dict):
         return
+    pending_events = cast(dict[str, Any], pending_events)
 
     for interrupt_id in cancelled_ids:
-        pending_events.pop(interrupt_id, None)
+        request_event = pending_events.pop(interrupt_id, None)
+        source_executor_id = getattr(request_event, "source_executor_id", None)
+        executor = workflow.executors.get(source_executor_id) if source_executor_id else None
+        pending_agent_requests = getattr(executor, "_pending_agent_requests", None)
+        if isinstance(pending_agent_requests, dict):
+            cast(dict[str, Any], pending_agent_requests).pop(interrupt_id, None)
 
 
 def _coerce_json_value(value: Any) -> Any:
@@ -439,6 +462,79 @@ def _coerce_message(value: Any) -> Message | None:
     )
 
 
+def _approval_argument_value_matches(original_value: Any, edited_value: Any) -> bool:
+    """Return whether an edited approval argument preserves its JSON value type."""
+    if isinstance(original_value, bool):
+        return isinstance(edited_value, bool)
+    if isinstance(original_value, int) and not isinstance(original_value, bool):
+        return isinstance(edited_value, int) and not isinstance(edited_value, bool)
+    if isinstance(original_value, float):
+        return isinstance(edited_value, (int, float)) and not isinstance(edited_value, bool)
+    if isinstance(original_value, str):
+        return isinstance(edited_value, str)
+    if isinstance(original_value, list):
+        return isinstance(edited_value, list)
+    if isinstance(original_value, dict):
+        return isinstance(edited_value, dict)
+    return True
+
+
+def _coerce_compact_approval_response(request_data: Content, candidate: dict[str, Any]) -> Content | None:
+    """Reconstruct a workflow approval response from client-owned decision fields."""
+    if {"type", "id", "function_call"}.intersection(candidate):
+        return None
+
+    approved = candidate.get("approved", candidate.get("accepted"))
+    if not isinstance(approved, bool):
+        return None
+
+    direct_edited_arguments = {
+        key: value for key, value in candidate.items() if key not in {"approved", "accepted", "editedArgs"}
+    }
+    standard_edited_arguments = candidate.get("editedArgs")
+    if request_data.function_call is None:
+        return None
+    if (
+        direct_edited_arguments or standard_edited_arguments is not None
+    ) and request_data.function_call.additional_properties.get("server_label"):
+        return None
+
+    original_arguments = request_data.function_call.parse_arguments() or {}
+    if standard_edited_arguments is not None:
+        if not isinstance(standard_edited_arguments, dict) or direct_edited_arguments:
+            return None
+        edited_arguments = cast(dict[str, Any], standard_edited_arguments)
+        if set(edited_arguments) != set(original_arguments):
+            return None
+        final_arguments = dict(edited_arguments)
+    else:
+        edited_arguments = direct_edited_arguments
+        if not set(edited_arguments).issubset(original_arguments):
+            return None
+        final_arguments = {**original_arguments, **edited_arguments}
+
+    if any(
+        not _approval_argument_value_matches(original_arguments[name], edited_arguments[name])
+        for name in edited_arguments
+    ):
+        return None
+    if not edited_arguments:
+        return request_data.to_function_approval_response(approved)
+
+    edited_function_call = Content.from_function_call(
+        call_id=request_data.function_call.call_id or "",
+        name=request_data.function_call.name or "",
+        arguments=final_arguments,
+        informational_only=request_data.function_call.informational_only,
+        annotations=request_data.function_call.annotations,
+        additional_properties=request_data.function_call.additional_properties,
+        raw_representation=request_data.function_call.raw_representation,
+    )
+    response = request_data.to_function_approval_response(approved)
+    response.function_call = edited_function_call
+    return response
+
+
 def _coerce_response_for_request(request_event: Any, value: Any) -> Any | None:
     """Coerce a candidate value into the request's expected response type."""
     response_type = getattr(request_event, "response_type", None)
@@ -485,6 +581,15 @@ def _coerce_response_for_request(request_event: Any, value: Any) -> Any | None:
     if target_type is Message:
         return _coerce_message(candidate)
     if target_type is Content:
+        request_data = getattr(request_event, "data", None)
+        if (
+            isinstance(request_data, Content)
+            and request_data.type == "function_approval_request"
+            and isinstance(candidate, dict)
+        ):
+            compact_response = _coerce_compact_approval_response(request_data, cast(dict[str, Any], candidate))
+            if compact_response is not None:
+                return compact_response
         return _coerce_content(candidate)
     if target_type is bool:
         return candidate if isinstance(candidate, bool) else None
@@ -499,7 +604,21 @@ def _coerce_response_for_request(request_event: Any, value: Any) -> Any | None:
     return candidate
 
 
-def _approval_response_matches_request(request_id: str, request_event: Any, response: Any) -> bool:
+def _is_compact_approval_response_payload(value: Any) -> bool:
+    """Return whether a value contains only client-owned approval decision fields."""
+    candidate = _coerce_json_value(value)
+    return isinstance(candidate, dict) and not {"type", "id", "function_call"}.intersection(
+        cast(dict[str, Any], candidate)
+    )
+
+
+def _approval_response_matches_request(
+    request_id: str,
+    request_event: Any,
+    response: Any,
+    *,
+    allow_edited_arguments: bool = False,
+) -> bool:
     """Check whether an approval response matches the pending approval request."""
     request_data = getattr(request_event, "data", None)
     if not isinstance(request_data, Content) or request_data.type != "function_approval_request":
@@ -519,6 +638,8 @@ def _approval_response_matches_request(request_id: str, request_event: Any, resp
     if getattr(response_call, "name", None) != getattr(request_call, "name", None):
         return False
 
+    if allow_edited_arguments:
+        return True
     return canonical_function_arguments(response_call) == canonical_function_arguments(request_call)
 
 
@@ -541,7 +662,12 @@ def _single_pending_response_from_value(pending_events: dict[str, Any], value: A
         )
         return {}
 
-    if not _approval_response_matches_request(str(request_id), request_event, coerced_value):
+    if not _approval_response_matches_request(
+        str(request_id),
+        request_event,
+        coerced_value,
+        allow_edited_arguments=_is_compact_approval_response_payload(value),
+    ):
         logger.info(
             "Ignoring pending request response for request_id=%s: approval response does not match pending request",
             request_id,
@@ -582,7 +708,12 @@ def _coerce_responses_for_pending_requests(
                 _response_type_name(request_event),
             )
             continue
-        if not _approval_response_matches_request(request_key, request_event, coerced_value):
+        if not _approval_response_matches_request(
+            request_key,
+            request_event,
+            coerced_value,
+            allow_edited_arguments=_is_compact_approval_response_payload(value),
+        ):
             logger.info(
                 "Ignoring resume response for request_id=%s: approval response does not match pending request",
                 request_key,
@@ -627,7 +758,12 @@ def _coerce_responses_for_pending_requests_strict(
                     code="WORKFLOW_RESUME_INVALID_RESPONSE",
                 ),
             )
-        if not _approval_response_matches_request(request_key, request_event, coerced_value):
+        if not _approval_response_matches_request(
+            request_key,
+            request_event,
+            coerced_value,
+            allow_edited_arguments=_is_compact_approval_response_payload(value),
+        ):
             return (
                 {},
                 RunErrorEvent(
@@ -864,6 +1000,7 @@ async def run_workflow_stream(
         pending_before_run = await _pending_request_events(workflow)
     pending_interrupt_ids = _pending_workflow_interrupt_ids(pending_before_run)
     resume_entries: list[dict[str, Any]] = []
+    cancelled_request_ids: set[str] = set()
     if pending_interrupt_ids:
         resume_entries, contract_error, contract_code = _resume_contract_error(
             resume_payload,
@@ -879,11 +1016,12 @@ async def run_workflow_stream(
             return
         resume_error = _resume_error_for_pending_workflow_requests(resume_entries)
         if resume_error is not None:
-            if getattr(resume_error, "code", None) == "WORKFLOW_RESUME_CANCELLED":
-                _consume_cancelled_workflow_requests(workflow, resume_entries)
             yield RunStartedEvent(run_id=run_id, thread_id=thread_id)
             yield resume_error
             return
+        cancelled_request_ids = {
+            str(entry["interrupt_id"]) for entry in resume_entries if entry.get("status") == "cancelled"
+        }
 
     resume_responses = (
         _resume_entries_to_workflow_responses(resume_entries)
@@ -901,6 +1039,13 @@ async def run_workflow_stream(
         yield RunStartedEvent(run_id=run_id, thread_id=thread_id)
         yield response_error
         return
+    if cancelled_request_ids:
+        _consume_cancelled_workflow_requests(workflow, resume_entries)
+        pending_before_run = {
+            request_id: request_event
+            for request_id, request_event in pending_before_run.items()
+            if str(getattr(request_event, "request_id", None) or request_id) not in cancelled_request_ids
+        }
     pending_interrupts = _interrupts_from_pending_requests(pending_before_run)
 
     # A checkpoint resume must always reach ``workflow.run(checkpoint_id=...)`` so the

python/packages/ag-ui/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-framework-ag-ui"
-version = "1.0.1"
+version = "1.1.0"
 description = "AG-UI protocol integration for Agent Framework"
 readme = "README.md"
 license-files = ["LICENSE"]
@@ -22,9 +22,10 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.13.0,<2",
+    "agent-framework-core>=1.14.0,<2",
     "ag-ui-protocol>=0.1.19,<0.2",
     "fastapi>=0.121.0,<0.140.0",
+    "httpx>=0.28.1,<1",
     "sse-starlette>=3.4.5,<4",
     "uvicorn[standard]>=0.30.0,<1"
 ]
@@ -32,7 +33,6 @@ dependencies = [
 [project.optional-dependencies]
 dev = [
     "pytest==9.1.1",
-    "httpx==0.28.1",
 ]
 
 [dependency-groups]

python/packages/ag-ui/tests/ag_ui/test_agent_wrapper_comprehensive.py

@@ -7,9 +7,12 @@ from collections.abc import AsyncIterator, MutableSequence
 from typing import Any
 
 import pytest
+from ag_ui.core import RunErrorEvent, ToolCallResultEvent
 from agent_framework import Agent, ChatOptions, ChatResponseUpdate, Content, Message
 from pydantic import BaseModel
 
+from agent_framework_ag_ui._approval_lifecycle import ApprovalExecutionOwner
+
 
 async def test_agent_initialization_basic(streaming_chat_client_stub):
     """Test basic agent initialization without state schema."""
@@ -819,21 +822,25 @@ async def test_function_approval_mode_executes_tool(streaming_chat_client_stub):
     assert len(run_started) == 1
     assert len(run_finished) == 1
 
-    # Verify that a FunctionResultContent was created and sent to the agent
-    tool_result_found = False
-    for msg in messages_received:
-        for content in msg.contents:
-            if content.type == "function_result":
-                tool_result_found = True
-                assert content.call_id == "call_get_datetime_123"
-                assert content.result == "2025/12/01 12:00:00"
-                break
-
-    assert tool_result_found, (
-        "FunctionResultContent should be included in messages sent to agent. "
-        "This is required for the model to see the approved tool execution result."
+    result_events = [event for event in events2 if event.type == "TOOL_CALL_RESULT"]
+    assert len(result_events) == 1
+    assert result_events[0].tool_call_id == "call_get_datetime_123"
+    assert result_events[0].content == "2025/12/01 12:00:00"
+    assert not any(
+        event.type in {"TOOL_CALL_START", "TOOL_CALL_ARGS", "TOOL_CALL_END"}
+        and getattr(event, "tool_call_id", None) == "call_get_datetime_123"
+        for event in events2
     )
 
+    replayable_results = [
+        content
+        for message in messages_received
+        for content in message.contents
+        if content.type == "function_result" and content.call_id == "call_get_datetime_123"
+    ]
+    assert len(replayable_results) == 1
+    assert replayable_results[0].result == "2025/12/01 12:00:00"
+
 
 async def test_function_approval_mode_rejection(streaming_chat_client_stub):
     """Test that function approval rejection creates a rejection response."""
@@ -868,8 +875,14 @@ async def test_function_approval_mode_rejection(streaming_chat_client_stub):
 
     thread_id = "thread-rejection-test"
 
-    # Pre-populate the pending approval as if Turn 1 had emitted the request.
-    wrapper._pending_approvals[(thread_id, "call_delete_123")] = "delete_all_data"
+    wrapper._approval_state_store.register(
+        owner=ApprovalExecutionOwner.LOCAL,
+        thread_ids=[thread_id],
+        name="delete_all_data",
+        arguments="{}",
+        request_id="call_delete_123",
+        interrupt_id="call_delete_123",
+    )
 
     input_data: dict[str, Any] = {
         "thread_id": thread_id,
@@ -1041,7 +1054,7 @@ async def test_approval_replay_is_blocked(streaming_chat_client_stub):
         if getattr(e, "type", None) == "CUSTOM" and getattr(e, "name", None) == "function_approval_request"
     ]
     assert len(approval_events) == 1, "Expected one approval request event"
-    assert any("call_sens_001" in k for k in wrapper._pending_approvals)
+    assert wrapper._approval_state_store.lifecycle.pending_occurrence(thread_id=thread_id, interrupt_id="call_sens_001")
 
     # --- Turn 2: legitimate approval ---
     async def stream_fn_post_approval(
@@ -1055,7 +1068,7 @@ async def test_approval_replay_is_blocked(streaming_chat_client_stub):
         instructions="Test",
         tools=[sensitive_action],
     )
-    # Reuse the same wrapper (same _pending_approvals) with a new agent for Turn 2
+    # Reuse the same wrapper with its server-owned Approval State for Turn 2.
     wrapper.agent = agent2
 
     turn2_input: dict[str, Any] = {
@@ -1069,7 +1082,9 @@ async def test_approval_replay_is_blocked(streaming_chat_client_stub):
         events2.append(event)
 
     assert call_count == 1, "Tool should have been executed once"
-    assert not any("call_sens_001" in k for k in wrapper._pending_approvals), "Pending approval should be consumed"
+    assert not wrapper._approval_state_store.lifecycle.pending_occurrence(
+        thread_id=thread_id, interrupt_id="call_sens_001"
+    )
 
     # --- Turn 3: replay attempt with the same approval ID ---
     call_count = 0  # reset
@@ -1140,8 +1155,12 @@ async def test_approval_resolves_with_client_or_provider_thread_id(
     async for _ in wrapper.run({"thread_id": "client-thread", "messages": [{"role": "user", "content": "do it"}]}):
         pass
 
-    assert ("client-thread", "call_sensitive") in wrapper._pending_approvals
-    assert ("provider-conversation", "call_sensitive") in wrapper._pending_approvals
+    assert wrapper._approval_state_store.lifecycle.pending_occurrence(
+        thread_id="client-thread", interrupt_id="call_sensitive"
+    )
+    assert wrapper._approval_state_store.lifecycle.pending_occurrence(
+        thread_id="provider-conversation", interrupt_id="call_sensitive"
+    )
 
     async def completion_stream(
         messages: MutableSequence[Message], options: ChatOptions, **kwargs: Any
@@ -1166,14 +1185,38 @@ async def test_approval_resolves_with_client_or_provider_thread_id(
         pass
 
     assert execution_count == 1
-    assert ("client-thread", "call_sensitive") not in wrapper._pending_approvals
-    assert ("provider-conversation", "call_sensitive") not in wrapper._pending_approvals
+    assert not wrapper._approval_state_store.lifecycle.pending_occurrence(
+        thread_id="client-thread", interrupt_id="call_sensitive"
+    )
+    assert not wrapper._approval_state_store.lifecycle.pending_occurrence(
+        thread_id="provider-conversation", interrupt_id="call_sensitive"
+    )
 
     replay_thread_id = "provider-conversation" if resume_thread_id == "client-thread" else "client-thread"
-    async for _ in wrapper.run(approval_input(replay_thread_id)):
-        pass
+    retry_events = [event async for event in wrapper.run(approval_input(replay_thread_id))]
 
     assert execution_count == 1
+    retry_results = [event for event in retry_events if isinstance(event, ToolCallResultEvent)]
+    assert len(retry_results) == 1
+    assert retry_results[0].tool_call_id == "call_sensitive"
+    assert retry_results[0].content == "executed"
+    assert not any(event.type == "RUN_ERROR" for event in retry_events)
+
+    conflicting_input = approval_input(replay_thread_id)
+    conflicting_input["resume"][0]["payload"]["accepted"] = False
+    conflicting_events = [event async for event in wrapper.run(conflicting_input)]
+
+    assert execution_count == 1
+    assert any(
+        isinstance(event, RunErrorEvent) and event.code == "APPROVAL_RESUME_INVALID" for event in conflicting_events
+    )
+
+    changed_input = approval_input(replay_thread_id)
+    changed_input["resume"][0]["payload"]["forged"] = True
+    changed_events = [event async for event in wrapper.run(changed_input)]
+
+    assert execution_count == 1
+    assert any(isinstance(event, RunErrorEvent) and event.code == "APPROVAL_RESUME_INVALID" for event in changed_events)
 
 
 async def test_approval_function_name_mismatch_is_blocked(streaming_chat_client_stub):
@@ -1231,7 +1274,7 @@ async def test_approval_function_name_mismatch_is_blocked(streaming_chat_client_
     async for event in wrapper.run({"thread_id": thread_id, "messages": [{"role": "user", "content": "do safe"}]}):
         events1.append(event)
 
-    assert any("call_safe_001" in k for k in wrapper._pending_approvals)
+    assert wrapper._approval_state_store.lifecycle.pending_occurrence(thread_id=thread_id, interrupt_id="call_safe_001")
 
     # Turn 2: try to approve with a different function name (function name spoofing)
     async def stream_fn_post(
@@ -1270,9 +1313,9 @@ async def test_approval_function_name_mismatch_is_blocked(streaming_chat_client_
         events2.append(event)
 
     assert not tool_executed, "Function name spoofing should be blocked"
-    assert any("call_safe_001" in k for k in wrapper._pending_approvals), (
-        "Pending approval should be preserved after mismatch for legitimate retry"
-    )
+    assert wrapper._approval_state_store.lifecycle.pending_occurrence(
+        thread_id=thread_id, interrupt_id="call_safe_001"
+    ), "Pending approval should be preserved after mismatch for legitimate retry"
 
 
 async def test_approval_bypass_via_fabricated_tool_result_is_blocked(streaming_chat_client_stub):
@@ -1469,7 +1512,9 @@ async def test_approval_argument_mismatch_is_blocked(streaming_chat_client_stub)
     async for event in wrapper.run({"thread_id": thread_id, "messages": [{"role": "user", "content": "update"}]}):
         events1.append(event)
 
-    assert any("call_update_001" in k for k in wrapper._pending_approvals)
+    assert wrapper._approval_state_store.lifecycle.pending_occurrence(
+        thread_id=thread_id, interrupt_id="call_update_001"
+    )
 
     async def stream_fn_post(
         messages: MutableSequence[Message], options: ChatOptions, **kwargs: Any
@@ -1507,9 +1552,9 @@ async def test_approval_argument_mismatch_is_blocked(streaming_chat_client_stub)
         events2.append(event)
 
     assert executed_args == []
-    assert any("call_update_001" in k for k in wrapper._pending_approvals), (
-        "Pending approval should be preserved after argument mismatch for legitimate retry"
-    )
+    assert wrapper._approval_state_store.lifecycle.pending_occurrence(
+        thread_id=thread_id, interrupt_id="call_update_001"
+    ), "Pending approval should be preserved after argument mismatch for legitimate retry"
 
 
 async def test_state_update_end_to_end_via_real_tool_invocation(streaming_chat_client_stub):

python/packages/ag-ui/tests/ag_ui/test_approval_state.py

@@ -2,8 +2,14 @@
 
 """Tests for server-side AG-UI approval state storage."""
 
-import pytest
+from concurrent.futures import ThreadPoolExecutor
+from threading import Barrier
+from time import sleep
 
+import pytest
+from typing_extensions import Self
+
+from agent_framework_ag_ui._approval_lifecycle import ApprovalCapacityError, ApprovalExecutionOwner
 from agent_framework_ag_ui._approval_state import InMemoryAGUIApprovalStateStore, approval_state_thread_id
 
 
@@ -30,14 +36,81 @@ def test_approval_state_store_rejects_invalid_max_entries() -> None:
         InMemoryAGUIApprovalStateStore(max_entries=0)
 
 
-def test_approval_state_store_evicts_oldest_entries() -> None:
+def test_approval_state_store_registers_explicit_execution_owner() -> None:
+    store = InMemoryAGUIApprovalStateStore()
+
+    store.register(
+        owner=ApprovalExecutionOwner.DEFERRED,
+        thread_ids=["thread-1", "provider-thread-1"],
+        name="write_record",
+        arguments="{}",
+        request_id="request-1",
+        interrupt_id="approval-1",
+        server_label=None,
+    )
+
+    occurrence = store.lifecycle.pending_occurrence(thread_id="thread-1", interrupt_id="approval-1")
+    assert occurrence is not None
+    assert occurrence.owner is ApprovalExecutionOwner.DEFERRED
+    assert store.lifecycle.pending_occurrence(thread_id="provider-thread-1", interrupt_id="request-1") is occurrence
+
+
+def test_approval_state_store_does_not_evict_active_entries() -> None:
     store = InMemoryAGUIApprovalStateStore(max_entries=1)
-    store.pending_approvals[("thread-1", "call-1")] = "first"
-    store.pending_approvals[("thread-2", "call-2")] = "second"
-    store.tool_approval_states["thread-1"] = {"call_id": "call-1"}
-    store.tool_approval_states["thread-2"] = {"call_id": "call-2"}
+    store.register(
+        owner=ApprovalExecutionOwner.LOCAL,
+        thread_ids=["thread-1"],
+        name="write_record",
+        arguments="{}",
+        request_id="request-1",
+        interrupt_id="approval-1",
+    )
 
-    store.evict_oldest()
+    with pytest.raises(ApprovalCapacityError):
+        store.register(
+            owner=ApprovalExecutionOwner.LOCAL,
+            thread_ids=["thread-2"],
+            name="write_record",
+            arguments="{}",
+            request_id="request-2",
+            interrupt_id="approval-2",
+        )
 
-    assert list(store.pending_approvals.items()) == [(("thread-2", "call-2"), "second")]
-    assert list(store.tool_approval_states.items()) == [("thread-2", {"call_id": "call-2"})]
+    assert store.lifecycle.pending_interrupt_ids(thread_id="thread-1") == {"approval-1"}
+
+
+def test_approval_state_store_does_not_evict_active_middleware_state() -> None:
+    store = InMemoryAGUIApprovalStateStore(max_entries=1)
+    store.set_tool_approval_state("thread-1", {"call_id": "call-1"})
+
+    with pytest.raises(ApprovalCapacityError):
+        store.set_tool_approval_state("thread-2", {"call_id": "call-2"})
+
+    assert store.get_tool_approval_state("thread-1") == {"call_id": "call-1"}
+    assert store.get_tool_approval_state("thread-2") is None
+
+
+def test_approval_state_store_enforces_capacity_across_concurrent_first_writes() -> None:
+    """Concurrent first writes cannot reserve more middleware slots than configured."""
+    store = InMemoryAGUIApprovalStateStore(max_entries=1)
+    start = Barrier(2)
+
+    class SlowCopy:
+        def __deepcopy__(self, memo: dict[int, object]) -> Self:
+            del memo
+            sleep(0.05)
+            return self
+
+    def write(thread_id: str) -> str:
+        start.wait(timeout=2)
+        try:
+            store.set_tool_approval_state(thread_id, {"call_id": thread_id, "slow": SlowCopy()})
+        except ApprovalCapacityError:
+            return "rejected"
+        return "stored"
+
+    with ThreadPoolExecutor(max_workers=2) as executor:
+        outcomes = list(executor.map(write, ["thread-1", "thread-2"]))
+
+    assert sorted(outcomes) == ["rejected", "stored"]
+    assert sum(store.has_tool_approval_state(thread_id) for thread_id in ["thread-1", "thread-2"]) == 1

python/packages/ag-ui/tests/ag_ui/test_message_adapters.py

@@ -100,6 +100,56 @@ def test_agui_tool_result_to_agent_framework():
     assert message.additional_properties.get("tool_call_id") == "call_123"
 
 
+@pytest.mark.parametrize("approved", [None, "true", "false", 1, 0, []])
+def test_function_approval_requires_real_boolean(approved: Any) -> None:
+    """Missing and malformed decisions are converted to explicit rejection."""
+    approval: dict[str, Any] = {
+        "id": "approval_1",
+        "call_id": "call_1",
+        "name": "sensitive_action",
+        "arguments": {},
+    }
+    if approved is not None:
+        approval["approved"] = approved
+
+    messages = agui_messages_to_agent_framework([{"role": "user", "content": "", "function_approvals": [approval]}])
+
+    response = messages[0].contents[0]
+    assert response.type == "function_approval_response"
+    assert response.approved is False
+
+
+@pytest.mark.parametrize(
+    ("accepted", "expected"),
+    [(True, True), (False, False), ("true", False), (1, False), (None, False)],
+)
+def test_tool_approval_accepted_requires_real_boolean(accepted: Any, expected: bool) -> None:
+    """Only the literal boolean true authorizes a raw tool approval payload."""
+    messages = agui_messages_to_agent_framework(
+        [
+            {
+                "role": "assistant",
+                "tool_calls": [
+                    {
+                        "id": "call_1",
+                        "type": "function",
+                        "function": {"name": "sensitive_action", "arguments": {}},
+                    }
+                ],
+            },
+            {
+                "role": "tool",
+                "toolCallId": "call_1",
+                "content": json.dumps({"accepted": accepted}),
+            },
+        ]
+    )
+
+    response = messages[1].contents[0]
+    assert response.type == "function_approval_response"
+    assert response.approved is expected
+
+
 def test_agui_tool_approval_updates_tool_call_arguments():
     """Tool approval updates matching tool call arguments for snapshots and agent context.
 
@@ -1995,3 +2045,39 @@ def test_parse_multimodal_media_part_unknown_source_value_fallback():
     )
     assert result is not None
     assert "aGVsbG8=" in result.uri  # type: ignore[operator]  # pyrefly: ignore[not-iterable]  # ty: ignore[unsupported-operator]
+
+
+def test_parse_multimodal_media_part_url_value_field():
+    """Source with type='url' reads the URL from the 'value' field per AG-UI spec."""
+    from agent_framework_ag_ui._message_adapters import _parse_multimodal_media_part
+
+    result = _parse_multimodal_media_part(
+        {
+            "type": "document",
+            "source": {
+                "type": "url",
+                "value": "https://example.com/files/document.pdf",
+                "mime_type": "application/pdf",
+            },
+        }
+    )
+    assert result is not None
+    assert result.uri == "https://example.com/files/document.pdf"
+    assert result.media_type == "application/pdf"
+
+
+def test_parse_multimodal_media_part_url_field_backward_compat():
+    """Source with type='url' still supports the non-spec 'url' and 'uri' fields."""
+    from agent_framework_ag_ui._message_adapters import _parse_multimodal_media_part
+
+    from_url = _parse_multimodal_media_part(
+        {"type": "image", "source": {"type": "url", "url": "https://example.com/a.png"}}
+    )
+    assert from_url is not None
+    assert from_url.uri == "https://example.com/a.png"
+
+    from_uri = _parse_multimodal_media_part(
+        {"type": "image", "source": {"type": "uri", "uri": "https://example.com/b.png"}}
+    )
+    assert from_uri is not None
+    assert from_uri.uri == "https://example.com/b.png"

python/packages/ag-ui/tests/ag_ui/test_run.py

@@ -24,21 +24,24 @@ from conftest import StubAgent  # pyrefly: ignore[missing-import] # pyright: ign
 
 from agent_framework_ag_ui._agent import AgentConfig
 from agent_framework_ag_ui._agent_run import (
-    PendingApprovalEntry,
-    PendingApprovalKey,
     _build_messages_snapshot,
     _build_safe_metadata,
     _canonical_approval_resume_messages,
     _create_state_context_message,
     _filter_local_approval_responses_for_provider,
     _inject_state_context,
-    _make_pending_approval_entry,
     _normalize_response_stream,
-    _pending_approval_key,
     _resume_to_tool_messages,
     _should_suppress_intermediate_snapshot,
     run_agent_stream,
 )
+from agent_framework_ag_ui._approval_lifecycle import (
+    ApprovalExecutionOwner,
+    ApprovalLifecycle,
+    ApprovalStatus,
+    ResumeDecision,
+)
+from agent_framework_ag_ui._approval_state import InMemoryAGUIApprovalStateStore
 from agent_framework_ag_ui._run_common import (
     FlowState,
     _build_run_finished_event,
@@ -926,9 +929,12 @@ def test_emit_approval_request_populates_interrupt_metadata():
     assert flow.interrupts[0]["reason"] == "tool_call"
     assert flow.interrupts[0]["toolCallId"] == "call_123"
     assert flow.interrupts[0]["message"] == "Approve running write_doc?"
-    assert flow.interrupts[0]["responseSchema"]["required"] == ["accepted"]
-    assert flow.interrupts[0]["responseSchema"]["properties"]["accepted"]["type"] == "boolean"
-    assert flow.interrupts[0]["responseSchema"]["properties"]["content"]["type"] == "string"
+    response_schema = flow.interrupts[0]["responseSchema"]
+    assert response_schema["anyOf"] == [{"required": ["approved"]}, {"required": ["accepted"]}]
+    assert response_schema["properties"]["approved"]["type"] == "boolean"
+    assert response_schema["properties"]["accepted"]["type"] == "boolean"
+    assert response_schema["properties"]["content"]["type"] == "string"
+    assert response_schema["properties"]["editedArgs"]["required"] == ["content"]
     assert flow.interrupts[0]["metadata"]["agent_framework"]["type"] == "function_approval_request"
     assert flow.interrupts[0]["metadata"]["agent_framework"]["function_call"] == {
         "call_id": "call_123",
@@ -937,6 +943,34 @@ def test_emit_approval_request_populates_interrupt_metadata():
     }
 
 
+def test_emit_approval_request_keeps_protocol_fields_when_tool_arguments_use_reserved_names() -> None:
+    """Reserved protocol fields remain controls while editedArgs carries colliding tool arguments."""
+    flow = FlowState(message_id="msg-1")
+    function_call = Content.from_function_call(
+        call_id="call_reserved",
+        name="write_doc",
+        arguments={"approved": "draft", "accepted": 1, "editedArgs": {"value": True}},
+    )
+    approval_content = Content.from_function_approval_request(id="approval_reserved", function_call=function_call)
+
+    _emit_approval_request(approval_content, flow)
+
+    properties = flow.interrupts[0]["responseSchema"]["properties"]
+    assert properties["approved"]["type"] == "boolean"
+    assert properties["accepted"]["type"] == "boolean"
+    assert properties["editedArgs"] == {
+        "type": "object",
+        "description": "Full replacement of the tool arguments. Not merged.",
+        "properties": {
+            "approved": {"type": "string"},
+            "accepted": {"type": "integer"},
+            "editedArgs": {"type": "object", "additionalProperties": True},
+        },
+        "required": ["approved", "accepted", "editedArgs"],
+        "additionalProperties": False,
+    }
+
+
 def test_emit_approval_request_accumulates_multiple_interrupts():
     """Multiple approval requests in the same turn should accumulate in flow.interrupts."""
     flow = FlowState(message_id="msg-1")
@@ -1041,29 +1075,31 @@ def test_resume_to_tool_messages_skips_cancelled_entries():
 
 def test_canonical_approval_resume_does_not_mutate_arguments_until_batch_validates():
     """Edited approval arguments are committed only after every resume entry validates."""
-    pending_entry = _make_pending_approval_entry(
-        "get_weather",
-        '{"city":"Seattle"}',
-        request_id="call_a",
+    lifecycle = ApprovalLifecycle()
+    pending_entry = lifecycle.register(
+        owner=ApprovalExecutionOwner.LOCAL,
+        thread_id="thread-weather",
         interrupt_id="call_a",
+        call_id="call_a",
+        name="get_weather",
+        arguments='{"city":"Seattle"}',
+    )
+    lifecycle.register(
+        owner=ApprovalExecutionOwner.LOCAL,
+        thread_id="thread-weather",
+        interrupt_id="call_b",
+        call_id="call_b",
+        name="get_weather",
+        arguments='{"city":"Portland"}',
     )
-    pending_approvals: dict[PendingApprovalKey, PendingApprovalEntry] = {
-        _pending_approval_key("thread-weather", "call_a"): pending_entry,
-        _pending_approval_key("thread-weather", "call_b"): _make_pending_approval_entry(
-            "get_weather",
-            '{"city":"Portland"}',
-            request_id="call_b",
-            interrupt_id="call_b",
-        ),
-    }
 
     messages, handled_ids, cancelled_ids, error = _canonical_approval_resume_messages(
         [
             {"interruptId": "call_a", "status": "resolved", "payload": {"accepted": True, "city": "Portland"}},
             {"interruptId": "call_b", "status": "resolved", "payload": "not an object"},
         ],
-        pending_approvals,
         "thread-weather",
+        lifecycle=lifecycle,
     )
 
     assert messages == []
@@ -1071,20 +1107,182 @@ def test_canonical_approval_resume_does_not_mutate_arguments_until_batch_validat
     assert cancelled_ids == set()
     assert error is not None
     assert error.code == "APPROVAL_RESUME_INVALID"
-    assert pending_entry["arguments"] == '{"city":"Seattle"}'
+    assert pending_entry.arguments == '{"city":"Seattle"}'
+
+
+def test_canonical_approval_resume_does_not_cancel_until_resolved_siblings_validate() -> None:
+    """A malformed resolved sibling leaves every approval in the batch pending."""
+    lifecycle = ApprovalLifecycle()
+    cancelled = lifecycle.register(
+        owner=ApprovalExecutionOwner.LOCAL,
+        thread_id="thread-weather",
+        interrupt_id="call_a",
+        call_id="call_a",
+        name="get_weather",
+        arguments='{"city":"Seattle"}',
+    )
+    resolved = lifecycle.register(
+        owner=ApprovalExecutionOwner.LOCAL,
+        thread_id="thread-weather",
+        interrupt_id="call_b",
+        call_id="call_b",
+        name="get_weather",
+        arguments='{"city":"Portland"}',
+    )
+
+    _, _, _, error = _canonical_approval_resume_messages(
+        [
+            {"interruptId": "call_a", "status": "cancelled"},
+            {"interruptId": "call_b", "status": "resolved", "payload": "not an object"},
+        ],
+        "thread-weather",
+        lifecycle=lifecycle,
+    )
+
+    assert error is not None
+    assert error.code == "APPROVAL_RESUME_INVALID"
+    assert lifecycle.get(cancelled.identity).status is ApprovalStatus.PENDING
+    assert lifecycle.get(resolved.identity).status is ApprovalStatus.PENDING
+
+
+def test_terminal_approval_retry_validates_standard_edited_arguments() -> None:
+    """A terminal retry cannot bypass the pending path's editedArgs contract."""
+    lifecycle = ApprovalLifecycle()
+    lifecycle.register(
+        owner=ApprovalExecutionOwner.LOCAL,
+        thread_id="thread-weather",
+        interrupt_id="call_a",
+        call_id="call_a",
+        name="get_weather",
+        arguments='{"city":"Seattle"}',
+    )
+    lifecycle.claim_batch(
+        thread_id="thread-weather",
+        decisions=[
+            ResumeDecision(
+                interrupt_id="call_a",
+                accepted=False,
+                arguments='{"city":"Seattle"}',
+                name="get_weather",
+                original_arguments='{"city":"Seattle"}',
+            )
+        ],
+    )
+    retained_results: list[Content] = []
+
+    _, handled_ids, _, error = _canonical_approval_resume_messages(
+        [
+            {
+                "interruptId": "call_a",
+                "status": "resolved",
+                "payload": {"approved": False, "editedArgs": "not an object"},
+            }
+        ],
+        "thread-weather",
+        lifecycle=lifecycle,
+        retained_results=retained_results,
+    )
+
+    assert handled_ids == set()
+    assert error is not None
+    assert error.code == "APPROVAL_RESUME_INVALID_RESPONSE"
+    assert retained_results == []
+
+
+def test_terminal_rejection_retry_does_not_project_a_live_tool_result() -> None:
+    """An identical rejected retry has the same no-result projection as the original rejection."""
+    lifecycle = ApprovalLifecycle()
+    lifecycle.register(
+        owner=ApprovalExecutionOwner.LOCAL,
+        thread_id="thread-weather",
+        interrupt_id="call_a",
+        call_id="call_a",
+        name="get_weather",
+        arguments='{"city":"Seattle"}',
+    )
+    decision = ResumeDecision(
+        interrupt_id="call_a",
+        accepted=False,
+        arguments='{"city":"Seattle"}',
+        name="get_weather",
+        original_arguments='{"city":"Seattle"}',
+    )
+    lifecycle.claim_batch(thread_id="thread-weather", decisions=[decision])
+    retained_results: list[Content] = []
+
+    _, handled_ids, _, error = _canonical_approval_resume_messages(
+        [
+            {
+                "interruptId": "call_a",
+                "status": "resolved",
+                "payload": {"approved": False},
+            }
+        ],
+        "thread-weather",
+        lifecycle=lifecycle,
+        retained_results=retained_results,
+    )
+
+    assert error is None
+    assert handled_ids == {"call_a"}
+    assert retained_results == []
+
+
+async def test_run_settles_server_collected_rejection_in_lifecycle() -> None:
+    """A rejection restored from approval middleware state no longer remains pending."""
+    function_call = Content.from_function_call(
+        call_id="call_rejected",
+        name="write_record",
+        arguments={"value": "draft"},
+    )
+    response = Content.from_function_approval_response(
+        approved=False,
+        id="approval_rejected",
+        function_call=function_call,
+    )
+    store = InMemoryAGUIApprovalStateStore()
+    store.set_tool_approval_state(
+        "thread-server-rejection",
+        {"collected_approval_responses": [response.to_dict()]},
+    )
+    agent = StubAgent(updates=[AgentResponseUpdate(contents=[Content.from_text(text="Done.")], role="assistant")])
+
+    events = [
+        event
+        async for event in run_agent_stream(
+            {
+                "runId": "run-server-rejection",
+                "threadId": "thread-server-rejection",
+                "messages": [{"role": "user", "content": "Continue"}],
+            },
+            agent,
+            AgentConfig(),
+            approval_state_store=store,
+        )
+    ]
+
+    assert not [event for event in events if event.type == "RUN_ERROR"]
+    occurrence = store.lifecycle.occurrence_for_alias(
+        thread_id="thread-server-rejection",
+        interrupt_id="approval_rejected",
+    )
+    assert occurrence is not None
+    assert occurrence.status is ApprovalStatus.REJECTED
+    assert store.lifecycle.pending_interrupt_ids(thread_id="thread-server-rejection") == set()
 
 
 def test_canonical_hosted_approval_resume_rejects_edited_arguments_without_mutating_pending() -> None:
     """Hosted approvals accept a decision only because providers ignore edited arguments."""
-    pending_entry = _make_pending_approval_entry(
-        "docs_search",
-        '{"query":"azure"}',
-        request_id="mcpr_docs",
+    lifecycle = ApprovalLifecycle()
+    pending_entry = lifecycle.register(
+        owner=ApprovalExecutionOwner.HOSTED,
+        thread_id="thread-hosted",
         interrupt_id="mcpr_docs",
+        call_id="mcpr_docs",
+        name="docs_search",
+        arguments='{"query":"azure"}',
         server_label="Microsoft_Learn_MCP",
     )
-    key = _pending_approval_key("thread-hosted", "mcpr_docs")
-    pending_approvals: dict[PendingApprovalKey, PendingApprovalEntry] = {key: pending_entry}
 
     messages, handled_ids, cancelled_ids, error = _canonical_approval_resume_messages(
         [
@@ -1094,8 +1292,8 @@ def test_canonical_hosted_approval_resume_rejects_edited_arguments_without_mutat
                 "payload": {"accepted": True, "query": "untrusted edit"},
             }
         ],
-        pending_approvals,
         "thread-hosted",
+        lifecycle=lifecycle,
     )
 
     assert messages == []
@@ -1103,23 +1301,24 @@ def test_canonical_hosted_approval_resume_rejects_edited_arguments_without_mutat
     assert cancelled_ids == set()
     assert error is not None
     assert error.code == "APPROVAL_RESUME_INVALID_RESPONSE"
-    assert pending_entry["arguments"] == '{"query":"azure"}'
-    assert pending_approvals[key] is pending_entry
+    assert pending_entry.arguments == '{"query":"azure"}'
+    assert lifecycle.pending_occurrence(thread_id="thread-hosted", interrupt_id="mcpr_docs") is pending_entry
 
 
-def test_pending_approval_registry_scans_exact_thread_keys_with_colons():
+def test_approval_lifecycle_scans_exact_thread_keys_with_colons():
     """A thread id that prefixes another thread id must not inherit its pending approval contract."""
-    pending_approvals: dict[PendingApprovalKey, PendingApprovalEntry] = {
-        _pending_approval_key("tenant:thread", "call_1"): _make_pending_approval_entry(
-            "get_weather",
-            '{"city":"Seattle"}',
-            request_id="call_1",
-            interrupt_id="call_1",
-        )
-    }
+    lifecycle = ApprovalLifecycle()
+    lifecycle.register(
+        owner=ApprovalExecutionOwner.LOCAL,
+        thread_id="tenant:thread",
+        interrupt_id="call_1",
+        call_id="call_1",
+        name="get_weather",
+        arguments='{"city":"Seattle"}',
+    )
 
-    _, _, _, unrelated_error = _canonical_approval_resume_messages(None, pending_approvals, "tenant")
-    _, _, _, owning_error = _canonical_approval_resume_messages(None, pending_approvals, "tenant:thread")
+    _, _, _, unrelated_error = _canonical_approval_resume_messages(None, "tenant", lifecycle=lifecycle)
+    _, _, _, owning_error = _canonical_approval_resume_messages(None, "tenant:thread", lifecycle=lifecycle)
 
     assert unrelated_error is None
     assert owning_error is not None

python/packages/ag-ui/tests/ag_ui/test_workflow_run.py

@@ -1033,6 +1033,65 @@ async def test_workflow_run_empty_turn_with_pending_request_emits_run_error():
     assert getattr(run_error, "code") == "WORKFLOW_RESUME_REQUIRED"
 
 
+async def test_workflow_run_does_not_cancel_until_resolved_siblings_validate() -> None:
+    """A malformed resolved workflow sibling leaves a cancelled request pending."""
+    cancelled_call = Content.from_function_call(
+        call_id="call-cancelled",
+        name="write_record",
+        arguments={"value": "cancelled"},
+    )
+    resolved_call = Content.from_function_call(
+        call_id="call-resolved",
+        name="write_record",
+        arguments={"value": "resolved"},
+    )
+    pending = {
+        "approval-cancelled": SimpleNamespace(
+            request_id="approval-cancelled",
+            data=Content.from_function_approval_request(id="approval-cancelled", function_call=cancelled_call),
+            response_type=Content,
+        ),
+        "approval-resolved": SimpleNamespace(
+            request_id="approval-resolved",
+            data=Content.from_function_approval_request(id="approval-resolved", function_call=resolved_call),
+            response_type=Content,
+        ),
+    }
+
+    async def get_pending_request_info_events() -> dict[str, Any]:
+        return dict(pending)
+
+    runner_context = SimpleNamespace(
+        get_pending_request_info_events=get_pending_request_info_events,
+        _pending_request_info_events=pending,
+    )
+    workflow = SimpleNamespace(_runner_context=runner_context)
+
+    events = [
+        event
+        async for event in run_workflow_stream(
+            {
+                "runId": "run-mixed-invalid",
+                "threadId": "thread-mixed-invalid",
+                "messages": [],
+                "resume": [
+                    {"interruptId": "approval-cancelled", "status": "cancelled"},
+                    {
+                        "interruptId": "approval-resolved",
+                        "status": "resolved",
+                        "payload": {"approved": True, "editedArgs": "not an object"},
+                    },
+                ],
+            },
+            cast(Any, workflow),
+        )
+    ]
+
+    assert [event.type for event in events] == ["RUN_STARTED", "RUN_ERROR"]
+    assert getattr(events[-1], "code") == "WORKFLOW_RESUME_INVALID_RESPONSE"
+    assert set(runner_context._pending_request_info_events) == {"approval-cancelled", "approval-resolved"}
+
+
 async def test_workflow_run_agent_response_output_uses_latest_assistant_message_only() -> None:
     """Conversation payload outputs should not flatten full history into one assistant message."""
 

python/packages/azure-ai-search/pyproject.toml

@@ -4,7 +4,7 @@ description = "Azure AI Search integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260730"
+version = "1.0.0b260813"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"

python/packages/azure-contentunderstanding/agent_framework_azure_contentunderstanding/_context_provider.py

@@ -762,7 +762,7 @@ class ContentUnderstandingContextProvider(ContextProvider):
             result,
             include_markdown="markdown" in self.output_sections,
             include_fields="fields" in self.output_sections,
-            metadata={"source": filename},
+            custom_metadata={"source": filename},
         )
 
     # ------------------------------------------------------------------

python/packages/azure-contentunderstanding/pyproject.toml

@@ -4,7 +4,7 @@ description = "Azure Content Understanding integration for Microsoft Agent Frame
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com" }]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260730"
+version = "1.0.0b260813"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"

python/packages/azure-contentunderstanding/tests/cu/test_context_provider.py

@@ -1663,13 +1663,13 @@ class TestAnalyzerAutoDetectionE2E:
 class TestWarningsExtraction:
     """Verify that CU RAI warnings are surfaced via ``to_llm_input`` rendering.
 
-    The SDK serializes ``result.warnings`` under the reserved ``rai_warnings``
+    The SDK serializes ``result.warnings`` under the reserved ``warnings``
     YAML front-matter key. Telemetry filtering of stray ``LLMStats:`` lines is
     handled by the SDK helper (azure-ai-contentunderstanding >= 1.2.0b2).
     """
 
     def test_warnings_included_when_present(self) -> None:
-        """Non-empty warnings should appear under ``rai_warnings`` front-matter key."""
+        """Non-empty warnings should appear under ``warnings`` front-matter key."""
         provider = _make_provider()
         fixture = {
             "contents": [
@@ -1694,16 +1694,16 @@ class TestWarningsExtraction:
         result_obj = AnalysisResult(fixture)
         rendered = provider._render_for_llm(result_obj, "doc.pdf")
 
-        assert "rai_warnings:" in rendered
+        assert "warnings:" in rendered
         assert "ContentFiltered" in rendered
         assert "Content was filtered due to Responsible AI policy." in rendered
         assert "Violence content detected and filtered." in rendered
 
     def test_warnings_omitted_when_empty(self, pdf_analysis_result: AnalysisResult) -> None:
-        """The PDF fixture has no warnings, so ``rai_warnings:`` should not appear."""
+        """The PDF fixture has no warnings, so ``warnings:`` should not appear."""
         provider = _make_provider()
         rendered = provider._render_for_llm(pdf_analysis_result, "report.pdf")
-        assert "rai_warnings:" not in rendered
+        assert "warnings:" not in rendered
 
 
 class TestCategoryExtraction:

python/packages/azure-cosmos-memory/agent_framework_azure_cosmos_memory/_context_provider.py

@@ -435,13 +435,17 @@ class CosmosMemoryContextProvider(ContextProvider):
         user_id = self._resolve_user_id(state, session)
         thread_id = state.get("thread_id") or session.session_id or "default"
 
+        # TODO(atty57): The toolkit renamed add_cosmos -> upsert_memory (same kwargs); accept either
+        # until the declared azure-cosmos-agent-memory floor is past the rename, then inline it.
+        write_turn = getattr(self.memory_client, "upsert_memory", None) or self.memory_client.add_cosmos
+
         try:
             # Store input messages (skip empty/whitespace-only content to avoid junk turns)
             for msg in context.input_messages:
                 if hasattr(msg, "role") and hasattr(msg, "text") and msg.text and msg.text.strip():
                     role_value = getattr(msg.role, "value", None) or str(msg.role)
                     if role_value in {"user", "assistant", "system"}:
-                        await self.memory_client.add_cosmos(
+                        await write_turn(
                             user_id=user_id,
                             thread_id=thread_id,
                             role=self._ROLE_MAP.get(role_value, role_value),
@@ -454,7 +458,7 @@ class CosmosMemoryContextProvider(ContextProvider):
                     if hasattr(msg, "role") and hasattr(msg, "text") and msg.text and msg.text.strip():
                         role_value = getattr(msg.role, "value", None) or str(msg.role)
                         if role_value in {"user", "assistant", "system"}:
-                            await self.memory_client.add_cosmos(
+                            await write_turn(
                                 user_id=user_id,
                                 thread_id=thread_id,
                                 role=self._ROLE_MAP.get(role_value, role_value),
@@ -462,7 +466,7 @@ class CosmosMemoryContextProvider(ContextProvider):
                             )
 
             # Auto-extraction and processing:
-            # When auto_extract is True (default), add_cosmos() schedules cadence-aware background
+            # When auto_extract is True (default), the turn write schedules cadence-aware background
             # processing (fact extraction, summaries, reconciliation) based on the configured
             # thresholds (FACT_EXTRACTION_EVERY_N, DEDUP_EVERY_N, etc.), so no explicit
             # process_now() call is needed. When auto_extract is False, those thresholds were

python/packages/azure-cosmos-memory/pyproject.toml

@@ -4,7 +4,7 @@ description = "Azure Cosmos DB Agent Memory Toolkit integration for Microsoft Ag
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.11"
-version = "1.0.0a260730"
+version = "1.0.0a260813"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"

python/packages/azure-cosmos-memory/tests/test_context_provider.py

@@ -52,7 +52,7 @@ def mock_memory_client() -> AsyncMock:
     mock_client = AsyncMock()
     mock_client.search_cosmos = AsyncMock(return_value=[])
     mock_client.get_user_summary = AsyncMock(return_value=None)
-    mock_client.add_cosmos = AsyncMock()
+    mock_client.upsert_memory = AsyncMock()
     mock_client.create_memory_store = AsyncMock()
     mock_client.__aenter__ = AsyncMock(return_value=mock_client)
     mock_client.__aexit__ = AsyncMock()
@@ -468,8 +468,8 @@ class TestAfterRun:
             agent=_STUB_AGENT, session=session, context=ctx, state=session.state.setdefault(provider.source_id, {})
         )
 
-        assert mock_memory_client.add_cosmos.await_count == 2
-        calls = mock_memory_client.add_cosmos.await_args_list
+        assert mock_memory_client.upsert_memory.await_count == 2
+        calls = mock_memory_client.upsert_memory.await_args_list
 
         # Check input message stored
         assert calls[0].kwargs["role"] == "user"
@@ -499,7 +499,7 @@ class TestAfterRun:
             agent=_STUB_AGENT, session=session, context=ctx, state=session.state.setdefault(provider.source_id, {})
         )
 
-        stored_roles = [c.kwargs["role"] for c in mock_memory_client.add_cosmos.await_args_list]
+        stored_roles = [c.kwargs["role"] for c in mock_memory_client.upsert_memory.await_args_list]
         assert stored_roles == ["user", "agent"]
         # No raw "assistant" role should ever be sent to the toolkit.
         assert "assistant" not in stored_roles
@@ -520,7 +520,7 @@ class TestAfterRun:
             agent=_STUB_AGENT, session=session, context=ctx, state=session.state.setdefault(provider.source_id, {})
         )
 
-        call_kwargs = mock_memory_client.add_cosmos.await_args_list[0].kwargs
+        call_kwargs = mock_memory_client.upsert_memory.await_args_list[0].kwargs
         assert call_kwargs["user_id"] == "user-456"
         assert call_kwargs["thread_id"] == "thread-789"
 
@@ -541,8 +541,8 @@ class TestAfterRun:
         )
 
         # Only one message should be stored
-        assert mock_memory_client.add_cosmos.await_count == 1
-        call_kwargs = mock_memory_client.add_cosmos.await_args_list[0].kwargs
+        assert mock_memory_client.upsert_memory.await_count == 1
+        call_kwargs = mock_memory_client.upsert_memory.await_args_list[0].kwargs
         assert call_kwargs["content"] == "Valid message"
 
     async def test_skips_whitespace_only_messages(self, mock_memory_client: AsyncMock) -> None:
@@ -563,15 +563,35 @@ class TestAfterRun:
         )
 
         # Whitespace-only input and the whitespace-only response are both skipped.
-        assert mock_memory_client.add_cosmos.await_count == 1
-        call_kwargs = mock_memory_client.add_cosmos.await_args_list[0].kwargs
+        assert mock_memory_client.upsert_memory.await_count == 1
+        call_kwargs = mock_memory_client.upsert_memory.await_args_list[0].kwargs
         assert call_kwargs["content"] == "Trimmed message"
 
+    async def test_falls_back_to_add_cosmos_on_older_toolkit(self) -> None:
+        """Toolkit versions predating the upsert_memory rename still receive turns.
+
+        The declared azure-cosmos-agent-memory range spans both names, so a resolved
+        install can expose either one; picking neither would silently drop every turn.
+        """
+        legacy_client = AsyncMock(spec=["add_cosmos", "search_cosmos", "get_user_summary"])
+        legacy_client.add_cosmos = AsyncMock()
+
+        provider = CosmosMemoryContextProvider(memory_client=legacy_client)
+        session = AgentSession(session_id="test-session")
+        ctx = SessionContext(input_messages=[Message(role="user", contents=["Hello"])], session_id="s1")
+
+        await provider.after_run(
+            agent=_STUB_AGENT, session=session, context=ctx, state=session.state.setdefault(provider.source_id, {})
+        )
+
+        assert legacy_client.add_cosmos.await_count == 1
+        assert legacy_client.add_cosmos.await_args_list[0].kwargs["content"] == "Hello"
+
     async def test_storage_failure_logs_warning(
         self, mock_memory_client: AsyncMock, caplog: pytest.LogCaptureFixture
     ) -> None:
         """Storage failures are logged but don't raise."""
-        mock_memory_client.add_cosmos.side_effect = Exception("Storage failed")
+        mock_memory_client.upsert_memory.side_effect = Exception("Storage failed")
 
         provider = CosmosMemoryContextProvider(memory_client=mock_memory_client)
         session = AgentSession(session_id="test-session")

python/packages/azure-cosmos-memory/tests/test_emulator.py

@@ -183,7 +183,8 @@ class TestEmulatorVectorSearch:
         # embeddings client). This lands in the memories container under the quantizedFlat
         # vector index, without needing LLM extraction.
         assert provider.memory_client is not None
-        await provider.memory_client.add_cosmos(
+        seed = getattr(provider.memory_client, "upsert_memory", None) or provider.memory_client.add_cosmos
+        await seed(
             user_id=user_id,
             thread_id=thread_id,
             role="user",

python/packages/azure-cosmos/agent_framework_azure_cosmos/_checkpoint_storage.py

@@ -54,8 +54,9 @@ class CosmosCheckpointStorage:
 
     By default, checkpoint deserialization is restricted to a built-in set of safe
     Python types (primitives, datetime, uuid, ...) and all ``agent_framework``
-    internal types.  To allow additional application-specific types, pass them via
-    the ``allowed_checkpoint_types`` parameter using ``"module:qualname"`` format.
+    internal types. To allow additional application-specific types, register them
+    with ``register_checkpoint_type`` or pass them via the
+    ``allowed_checkpoint_types`` parameter using ``"module:qualname"`` format.
 
     Example:
 

python/packages/azure-cosmos/tests/test_cosmos_checkpoint_storage.py

@@ -609,6 +609,13 @@ class _AppState:
     count: int
 
 
+@dataclass
+class _GloballyRegisteredAppState:
+    """Application-defined state type registered for all checkpoint backends."""
+
+    label: str
+
+
 _APP_STATE_TYPE_KEY = f"{_AppState.__module__}:{_AppState.__qualname__}"
 
 
@@ -679,6 +686,21 @@ async def test_load_allows_listed_app_type(mock_container: MagicMock) -> None:
     assert loaded.state["data"].count == 7
 
 
+async def test_load_allows_globally_registered_app_type(mock_container: MagicMock) -> None:
+    """Registered application types load without configuring the Cosmos storage instance."""
+    from agent_framework import register_checkpoint_type
+
+    checkpoint = _make_checkpoint_with_state({"data": _GloballyRegisteredAppState(label="registered")})
+    doc = _checkpoint_to_cosmos_document(checkpoint)
+    mock_container.query_items.return_value = _to_async_iter([doc])
+
+    register_checkpoint_type(_GloballyRegisteredAppState)
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+    loaded = await storage.load(checkpoint.checkpoint_id)
+
+    assert loaded.state["data"] == _GloballyRegisteredAppState(label="registered")
+
+
 async def test_list_checkpoints_blocks_unlisted_app_type(mock_container: MagicMock) -> None:
     """list_checkpoints skips documents with unlisted application types."""
     checkpoint = _make_checkpoint_with_state({"data": _AppState(label="x", count=1)})

python/packages/claude/pyproject.toml

@@ -4,7 +4,7 @@ description = "Claude Agent SDK integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260730"
+version = "1.0.0b260813"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"

python/packages/copilotstudio/pyproject.toml

@@ -4,7 +4,7 @@ description = "Copilot Studio integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260730"
+version = "1.0.0b260813"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -24,6 +24,8 @@ classifiers = [
 ]
 dependencies = [
     "agent-framework-core>=1.13.0,<2",
+    "aiohttp>=3.9,<4",
+    "msal>=1.31,<2",
     "microsoft-agents-copilotstudio-client>=1.2.0,<2",
 ]
 

python/packages/core/AGENTS.md

@@ -201,6 +201,12 @@ agent_framework/
   every output-capable executor not selected by `output_from`.
 - **`WorkflowRunResult`** - Non-streaming workflow result with Workflow Output `get_outputs()`
   and Intermediate Output `get_intermediate_outputs()` accessors
+- **Functional workflow definition/build lifecycle** - `@workflow` returns a stateless
+  `FunctionalWorkflowDefinition`. Call `build()` to create a stateful `FunctionalWorkflow` scoped to one logical
+  caller or session. The definition has no `run()` or `as_agent()` surface, so module-level decorated definitions
+  cannot accidentally retain caller state. Each built workflow and its `FunctionalWorkflowAgent` must remain scoped
+  to that caller/session. Pass a caller-scoped checkpoint storage to `build(checkpoint_storage=...)` when needed;
+  hosts remain responsible for authorizing and tenant-scoping access to any shared checkpoint adapter.
 - **Orchestrators**: `SequentialOrchestrator`, `ConcurrentOrchestrator`, `GroupChatOrchestrator`, `MagenticOrchestrator`, `HandoffOrchestrator`
 
 ## Built-in Providers

python/packages/core/agent_framework/__init__.py

@@ -293,6 +293,7 @@ _LAZY_MODULE_EXPORTS: Final[Mapping[str, tuple[str, ...]]] = {
         "InMemoryCheckpointStorage",
         "WorkflowCheckpoint",
     ),
+    "._workflows._checkpoint_encoding": ("register_checkpoint_type",),
     "._workflows._const": (
         "DEFAULT_MAX_ITERATIONS",
         "INTERNAL_SOURCE_ID",
@@ -321,6 +322,7 @@ _LAZY_MODULE_EXPORTS: Final[Mapping[str, tuple[str, ...]]] = {
     "._workflows._function_executor": ("FunctionExecutor", "executor"),
     "._workflows._functional": (
         "FunctionalWorkflow",
+        "FunctionalWorkflowDefinition",
         "FunctionalWorkflowAgent",
         "RunContext",
         "StepWrapper",
@@ -478,6 +480,7 @@ __all__ = [
     "FunctionTool",
     "FunctionalWorkflow",
     "FunctionalWorkflowAgent",
+    "FunctionalWorkflowDefinition",
     "GeneratedEmbeddings",
     "GraphConnectivityError",
     "HistoryProvider",
@@ -629,6 +632,7 @@ __all__ = [
     "normalize_tools",
     "prepend_agent_framework_to_user_agent",
     "prepend_instructions_to_messages",
+    "register_checkpoint_type",
     "register_state_type",
     "resolve_agent_id",
     "response_handler",

python/packages/core/agent_framework/__init__.pyi

@@ -259,6 +259,7 @@ from ._workflows._checkpoint import (
     InMemoryCheckpointStorage,
     WorkflowCheckpoint,
 )
+from ._workflows._checkpoint_encoding import register_checkpoint_type
 from ._workflows._const import DEFAULT_MAX_ITERATIONS, INTERNAL_SOURCE_ID
 from ._workflows._edge import (
     Case,
@@ -285,6 +286,7 @@ from ._workflows._function_executor import FunctionExecutor, executor
 from ._workflows._functional import (
     FunctionalWorkflow,
     FunctionalWorkflowAgent,
+    FunctionalWorkflowDefinition,
     RunContext,
     StepWrapper,
     get_run_context,
@@ -442,6 +444,7 @@ __all__ = [
     "FunctionTool",
     "FunctionalWorkflow",
     "FunctionalWorkflowAgent",
+    "FunctionalWorkflowDefinition",
     "GeneratedEmbeddings",
     "GraphConnectivityError",
     "HistoryProvider",
@@ -593,6 +596,7 @@ __all__ = [
     "normalize_tools",
     "prepend_agent_framework_to_user_agent",
     "prepend_instructions_to_messages",
+    "register_checkpoint_type",
     "register_state_type",
     "resolve_agent_id",
     "response_handler",

python/packages/core/agent_framework/_agent_hooks.py

@@ -120,6 +120,7 @@ from ._sessions import (
     _current_run_identity,  # pyright: ignore[reportPrivateUsage]
     _RunPersistenceGate,  # pyright: ignore[reportPrivateUsage]
 )
+from ._telemetry import FeatureIndex, mark_feature_used
 from ._types import (
     AgentResponse,
     AgentResponseUpdate,
@@ -1610,6 +1611,7 @@ def create_agent_hooks_middleware_from_emitter(
 
 
 def _build_bundle(config: _AgentHooksConfig) -> MiddlewareBundle:
+    mark_feature_used(FeatureIndex.CORE_AGENT_HOOKS)
     return MiddlewareBundle([
         _AgentHooksAgentMiddleware(config),
         _AgentHooksChatMiddleware(config),

python/packages/core/agent_framework/_harness/_background_agents.py

@@ -10,6 +10,7 @@ and retrieve results. Each background task runs in its own session concurrently.
 from __future__ import annotations
 
 import asyncio
+import logging
 from collections.abc import Awaitable, MutableMapping, Sequence
 from dataclasses import dataclass, field
 from enum import Enum
@@ -23,6 +24,8 @@ from .._telemetry import FeatureIndex, mark_feature_used
 from .._tools import tool
 from .._types import AgentResponse, Message
 
+logger = logging.getLogger(__name__)
+
 DEFAULT_BACKGROUND_AGENTS_SOURCE_ID = "background_agents"
 
 DEFAULT_BACKGROUND_AGENTS_INSTRUCTIONS = """\
@@ -114,6 +117,15 @@ class _RuntimeState:
 
     in_flight_tasks: dict[int, asyncio.Task[AgentResponse[Any]]] = field(default_factory=lambda: {})
     background_sessions: dict[int, AgentSession] = field(default_factory=lambda: {})
+    closed: bool = False
+
+    def track_task(self, task_id: int, task: asyncio.Task[AgentResponse[Any]]) -> None:
+        """Track a background task if this runtime is still open."""
+        if self.closed:
+            task.cancel()
+            raise RuntimeError("Session runtime is closed; cannot start background task.")
+
+        self.in_flight_tasks[task_id] = task
 
 
 # ---------------------------------------------------------------------------
@@ -126,6 +138,20 @@ async def _run_agent(awaitable: Awaitable[AgentResponse[Any]]) -> AgentResponse[
     return await awaitable
 
 
+def _log_abandoned_background_task(task: asyncio.Task[Any]) -> None:
+    """Retrieve exception from an abandoned task to avoid asyncio warnings."""
+    if task.cancelled():
+        return
+
+    try:
+        exception = task.exception()
+    except asyncio.CancelledError:
+        return
+
+    if exception is not None:
+        logger.debug("Abandoned background task raised: %s", exception)
+
+
 def _validate_and_build_agent_dict(agents: Sequence[SupportsAgentRun]) -> dict[str, SupportsAgentRun]:
     """Validate agents and build a case-insensitive lookup dict.
 
@@ -308,9 +334,115 @@ class BackgroundAgentsProvider(ContextProvider):
     def _get_runtime(self, session: AgentSession) -> _RuntimeState:
         """Get or create runtime state for a session."""
         session_id = session.session_id
-        if session_id not in self._runtime:
-            self._runtime[session_id] = _RuntimeState()
-        return self._runtime[session_id]
+        runtime = self._runtime.get(session_id)
+
+        if runtime is None or runtime.closed:
+            runtime = _RuntimeState()
+            self._runtime[session_id] = runtime
+
+        return runtime
+
+    async def release_session(
+        self,
+        session: AgentSession,
+        *,
+        cancel_running: bool = True,
+        timeout: float | None = 30.0,
+    ) -> None:
+        """Release all runtime state for a session to prevent runtime leaks.
+
+        Args:
+            session: The agent session whose runtime state should be released.
+            cancel_running: If True, cancel pending asyncio.Tasks safely.
+            timeout: Maximum seconds to wait for tasks to finish cancellation.
+                If None, wait indefinitely. The default is bounded so a buggy
+                task cannot wedge host eviction or shutdown.
+        """
+        session_id = session.session_id
+        runtime = self._runtime.get(session_id)
+
+        if runtime is None or runtime.closed:
+            return
+
+        pending = [task for task in list(runtime.in_flight_tasks.values()) if not task.done()]
+
+        if pending and not cancel_running:
+            raise RuntimeError(f"Cannot release session {session_id}: {len(pending)} tasks still running.")
+
+        runtime.closed = True
+
+        try:
+            if pending:
+                await self._drain_runtime(
+                    runtime,
+                    cancel_running=cancel_running,
+                    timeout=timeout,
+                )
+            else:
+                completed = list(runtime.in_flight_tasks.values())
+                if completed:
+                    await asyncio.gather(*completed, return_exceptions=True)
+        finally:
+            runtime.in_flight_tasks.clear()
+            runtime.background_sessions.clear()
+
+            if self._runtime.get(session_id) is runtime:
+                self._runtime.pop(session_id, None)
+
+    async def _drain_runtime(
+        self,
+        runtime: _RuntimeState,
+        *,
+        cancel_running: bool,
+        timeout: float | None,
+    ) -> None:
+        """Cancel and await tracked tasks, bounded by timeout."""
+        loop = asyncio.get_running_loop()
+        deadline = None if timeout is None else loop.time() + float(timeout)
+
+        while True:
+            tasks = list(runtime.in_flight_tasks.values())
+            pending = [task for task in tasks if not task.done()]
+
+            if not pending:
+                if tasks:
+                    await asyncio.gather(*tasks, return_exceptions=True)
+                return
+
+            if not cancel_running:
+                raise RuntimeError(f"Cannot release session: {len(pending)} tasks still running.")
+
+            for task in pending:
+                if not task.done():
+                    task.cancel()
+
+            remaining = None
+            if deadline is not None:
+                remaining = deadline - loop.time()
+                if remaining <= 0:
+                    logger.warning(
+                        "Session release timed out before all tasks finished. Abandoning %s task(s).",
+                        len(pending),
+                    )
+                    for task in pending:
+                        if not task.done():
+                            task.add_done_callback(_log_abandoned_background_task)
+                    return
+
+            try:
+                await asyncio.wait_for(
+                    asyncio.gather(*pending, return_exceptions=True),
+                    timeout=remaining,
+                )
+            except asyncio.TimeoutError:
+                not_done = [task for task in pending if not task.done()]
+                logger.warning(
+                    "Session release timed out waiting for %s task(s). They will be abandoned.",
+                    len(not_done),
+                )
+                for task in not_done:
+                    task.add_done_callback(_log_abandoned_background_task)
+                return
 
     async def before_run(
         self,
@@ -331,6 +463,9 @@ class BackgroundAgentsProvider(ContextProvider):
         @tool(name="background_agents_start_task", approval_mode="never_require")
         def background_agents_start_task(agent_name: str, input: str, description: str) -> str:
             """Start a background task on a named agent. Returns a confirmation with the task ID."""
+            if runtime.closed:
+                return "Error: Session is being released; cannot start a new background task."
+
             key = agent_name.lower()
             if key not in self._agents:
                 available = ", ".join(a.name or "" for a in self._agents.values())
@@ -338,6 +473,17 @@ class BackgroundAgentsProvider(ContextProvider):
 
             bg_agent = self._agents[key]
             task_id = provider_state.get("next_task_id", 1)
+
+            sub_session = bg_agent.create_session()
+
+            async_task = asyncio.create_task(_run_agent(bg_agent.run(input, session=sub_session)))
+            try:
+                runtime.track_task(task_id, async_task)
+            except RuntimeError as exc:
+                return f"Error: {exc}"
+
+            runtime.background_sessions[task_id] = sub_session
+
             provider_state["next_task_id"] = task_id + 1
 
             task_info = BackgroundTaskInfo(
@@ -349,14 +495,6 @@ class BackgroundAgentsProvider(ContextProvider):
             tasks.append(task_info)
             _save_tasks(provider_state, tasks)
 
-            # Create a dedicated session for this background task.
-            sub_session = bg_agent.create_session()
-
-            # Start the task concurrently.
-            async_task = asyncio.create_task(_run_agent(bg_agent.run(input, session=sub_session)))
-            runtime.in_flight_tasks[task_id] = async_task
-            runtime.background_sessions[task_id] = sub_session
-
             _save_provider_state(session, provider_state, source_id=source_id)
             return f"Background task {task_id} started on agent '{agent_name}'."
 
@@ -365,6 +503,9 @@ class BackgroundAgentsProvider(ContextProvider):
         @tool(name="background_agents_wait_for_first_completion", approval_mode="never_require")
         async def background_agents_wait_for_first_completion(task_ids: list[int]) -> str:
             """Block until the first of the specified background tasks completes. Returns the completed task's ID."""
+            if runtime.closed:
+                return "Error: Session is being released; cannot wait for background tasks."
+
             if not task_ids:
                 return "Error: No task IDs provided."
 
@@ -448,6 +589,9 @@ class BackgroundAgentsProvider(ContextProvider):
         @tool(name="background_agents_continue_task", approval_mode="never_require")
         def background_agents_continue_task(task_id: int, text: str) -> str:
             """Send follow-up input to a completed or failed task to resume its work."""
+            if runtime.closed:
+                return "Error: Session is being released; cannot continue a background task."
+
             tasks = _refresh_task_state(session, provider_state, runtime, source_id=source_id)
             task_info = next((t for t in tasks if t.id == task_id), None)
 
@@ -472,15 +616,16 @@ class BackgroundAgentsProvider(ContextProvider):
 
             bg_agent = self._agents[key]
 
-            # Reset task state and start a new run on the existing session.
+            async_task = asyncio.create_task(_run_agent(bg_agent.run(text, session=sub_session)))
+            try:
+                runtime.track_task(task_id, async_task)
+            except RuntimeError as exc:
+                return f"Error: {exc}"
             task_info.status = BackgroundTaskStatus.RUNNING
             task_info.result_text = None
             task_info.error_text = None
             _save_tasks(provider_state, tasks)
 
-            async_task = asyncio.create_task(_run_agent(bg_agent.run(text, session=sub_session)))
-            runtime.in_flight_tasks[task_id] = async_task
-
             _save_provider_state(session, provider_state, source_id=source_id)
             return f"Task {task_id} continued with new input."
 
@@ -489,6 +634,9 @@ class BackgroundAgentsProvider(ContextProvider):
         @tool(name="background_agents_clear_completed_task", approval_mode="never_require")
         def background_agents_clear_completed_task(task_id: int) -> str:
             """Remove a completed or failed task and release its session to free memory."""
+            if runtime.closed:
+                return "Error: Session is being released; cannot clear tasks."
+
             tasks = _refresh_task_state(session, provider_state, runtime, source_id=source_id)
             task_info = next((t for t in tasks if t.id == task_id), None)
 

python/packages/core/agent_framework/_harness/_tool_approval.py

@@ -386,7 +386,7 @@ class ToolApprovalMiddleware(AgentMiddleware):
 
         state = _get_state(context.session, source_id=self.source_id)
         context.client_kwargs.setdefault(_FUNCTION_INVOCATION_BUDGET_STATE_KEY, {})
-        context.messages = self._prepare_inbound_messages(context.messages, state)
+        context.messages = self._prepare_inbound_messages(context.messages, state, context.session)
         await self._drain_auto_approvable_queue(state)
         if next_queued := self._pop_next_queued_request(state):
             _save_state(context.session, state, source_id=self.source_id)
@@ -501,14 +501,22 @@ class ToolApprovalMiddleware(AgentMiddleware):
 
         return ResponseStream(_stream(), finalizer=AgentResponse.from_updates)
 
-    def _prepare_inbound_messages(self, messages: Sequence[Message], state: ToolApprovalState) -> list[Message]:
+    def _prepare_inbound_messages(
+        self,
+        messages: Sequence[Message],
+        state: ToolApprovalState,
+        session: AgentSession,
+    ) -> list[Message]:
         prepared: list[Message] = []
         for message in messages:
             replacement_contents: list[Content] = []
             changed = False
             for content in message.contents:
                 if content.type == "function_approval_response":
-                    replacement = self._handle_inbound_approval_response(content, state)
+                    replacement = self._handle_inbound_approval_response(content, state, session)
+                    if replacement is None:
+                        changed = True
+                        continue
                     state.collected_approval_responses.append(replacement)
                     changed = True
                     continue
@@ -523,9 +531,23 @@ class ToolApprovalMiddleware(AgentMiddleware):
                 prepared.append(cloned)
         return prepared
 
-    def _handle_inbound_approval_response(self, response: Content, state: ToolApprovalState) -> Content:
+    def _handle_inbound_approval_response(
+        self,
+        response: Content,
+        state: ToolApprovalState,
+        session: AgentSession,
+    ) -> Content | None:
+        from .._tools import (
+            _bind_approval_response_to_pending_request,  # pyright: ignore[reportPrivateUsage]
+            _is_approval_granted,  # pyright: ignore[reportPrivateUsage]
+        )
+
+        bound_response = _bind_approval_response_to_pending_request(response, session, consume=False)
+        if bound_response is None:
+            return None
+        response = bound_response
         scope = _get_always_approve_scope(response)
-        if scope is None or not response.approved:
+        if scope is None or not _is_approval_granted(response.approved):
             return response
 
         function_call = response.function_call

python/packages/core/agent_framework/_skills.py

@@ -1815,8 +1815,10 @@ RESOURCE_INSTRUCTIONS: Final[str] = (
 
 SCRIPT_RUNNER_INSTRUCTIONS: Final[str] = (
     "- Use `run_skill_script` to run referenced scripts, using the name exactly as listed.\n"
-    "- Pass script arguments inside `args` as a JSON object"
+    "- Pass named script arguments inside `args` as a JSON object, including for inline scripts"
     ' (e.g. `args: {"length": 24}`), not as top-level tool parameters.\n'
+    "- For file-based scripts that document CLI-style positional arguments, pass `args` as an array of strings"
+    ' (e.g. `args: ["input.docx", "--output", "result.idx"]`).\n'
 )
 
 # endregion

python/packages/core/agent_framework/_telemetry.py

@@ -54,6 +54,7 @@ class FeatureIndex(IntEnum):
     CORE_IN_MEMORY_SKILLS_SOURCE = 15
     CORE_MCP_SKILLS_SOURCE = 16
     CORE_SESSION_STORE = 17
+    CORE_AGENT_HOOKS = 18
 
 
 # This environment variable is reserved by the Foundry hosting environment to

python/packages/core/agent_framework/_tools.py

@@ -97,6 +97,7 @@ DEFAULT_MAX_CONSECUTIVE_ERRORS_PER_REQUEST: Final[int] = 3
 SHELL_TOOL_KIND_VALUE: Final[str] = "shell"
 _TOOL_APPROVAL_STATE_KEY: Final[str] = "tool_approval"
 _ALREADY_APPROVED_APPROVAL_REQUEST_GROUPS_KEY: Final[str] = "already_approved_approval_request_groups"
+_PENDING_APPROVAL_REQUESTS_KEY: Final[str] = "pending_approval_requests"
 _FUNCTION_INVOCATION_BUDGET_STATE_KEY: Final[str] = "_function_invocation_budget_state"
 _FUNCTION_INVOCATION_LIMIT_FALLBACK_TEXT: Final[str] = (
     "Function invocation limit reached before a final answer could be produced."
@@ -1813,6 +1814,7 @@ async def _try_execute_function_call_groups(
             visible_requests,
             already_approved_requests,
         )
+        _store_pending_approval_requests(invocation_session, visible_requests)
         return [[request] for request in visible_requests], False
     if has_declaration_only_call:
         # Declaration-only calls are returned as user input rather than executed locally.
@@ -1943,6 +1945,11 @@ def _is_hosted_tool_approval(content: Any) -> bool:
     return bool(ap and ap.get("server_label"))
 
 
+def _is_approval_granted(value: Any) -> bool:
+    """Return whether an approval decision is the strict boolean ``True``."""
+    return value is True
+
+
 def _is_unexecutable_local_tool_content(content: Content) -> bool:
     if _is_actionable_function_call(content):
         return True
@@ -2072,6 +2079,146 @@ def _content_from_state(value: Any) -> Content | None:
     return None
 
 
+def _load_pending_approval_requests(invocation_session: AgentSession | None) -> dict[str, Content]:
+    """Load immutable approval-request snapshots keyed by request ID."""
+    state = _get_tool_approval_state(invocation_session)
+    if state is None:
+        return {}
+    raw_requests = state.get(_PENDING_APPROVAL_REQUESTS_KEY, [])
+    if not isinstance(raw_requests, list):
+        return {}
+    pending: dict[str, Content] = {}
+    for raw_request in cast(list[Any], raw_requests):
+        request = _content_from_state(raw_request)
+        if request is not None and request.type == "function_approval_request" and request.id is not None:
+            if request.id in pending:
+                raise ValueError(f"Duplicate pending approval request id {request.id!r}.")
+            pending[request.id] = request
+    return pending
+
+
+def _save_pending_approval_requests(
+    invocation_session: AgentSession | None,
+    pending_requests: Mapping[str, Content],
+) -> None:
+    """Persist the active approval-request batch."""
+    state = _get_tool_approval_state(invocation_session)
+    if state is None:
+        return
+    if pending_requests:
+        state[_PENDING_APPROVAL_REQUESTS_KEY] = [request.to_dict() for request in pending_requests.values()]
+    else:
+        state.pop(_PENDING_APPROVAL_REQUESTS_KEY, None)
+
+
+def _store_pending_approval_requests(
+    invocation_session: AgentSession | None,
+    approval_requests: Sequence[Content],
+) -> None:
+    """Replace the active batch with immutable snapshots of surfaced approval requests."""
+    if invocation_session is None:
+        return
+    pending: dict[str, Content] = {}
+    for request in approval_requests:
+        if request.type != "function_approval_request" or request.id is None:
+            continue
+        if request.id in pending:
+            raise ValueError(f"Duplicate approval request id {request.id!r} in the active batch.")
+        snapshot = _content_from_state(request.to_dict())
+        if snapshot is not None:
+            pending[request.id] = snapshot
+    _save_pending_approval_requests(invocation_session, pending)
+    state = _get_tool_approval_state(invocation_session)
+    if state is None:
+        return
+    raw_groups = state.get(_ALREADY_APPROVED_APPROVAL_REQUEST_GROUPS_KEY)
+    if not isinstance(raw_groups, list):
+        return
+    active_ids = set(pending)
+    active_groups: list[Any] = []
+    for raw_group in cast(list[Any], raw_groups):
+        if not isinstance(raw_group, Mapping):
+            continue
+        group = cast(Mapping[str, Any], raw_group)
+        raw_ids = group.get("approval_request_ids")
+        if not isinstance(raw_ids, list):
+            continue
+        group_ids = {str(item) for item in cast(list[Any], raw_ids)}
+        if group_ids.issubset(active_ids):
+            active_groups.append(raw_group)
+    if active_groups:
+        state[_ALREADY_APPROVED_APPROVAL_REQUEST_GROUPS_KEY] = active_groups
+    else:
+        state.pop(_ALREADY_APPROVED_APPROVAL_REQUEST_GROUPS_KEY, None)
+
+
+def _bind_approval_response_to_pending_request(
+    response: Content,
+    invocation_session: AgentSession | None,
+    *,
+    consume: bool,
+) -> Content | None:
+    """Bind one approval response to a session-recorded request."""
+    from ._types import Content
+
+    if invocation_session is None:
+        return response
+    if response.id is None:
+        return None
+    pending = _load_pending_approval_requests(invocation_session)
+    request = pending.get(response.id)
+    if request is None or request.function_call is None:
+        return None
+    rebound_call = _content_from_state(request.function_call.to_dict())
+    if rebound_call is None:
+        return None
+    rebound = Content.from_function_approval_response(
+        approved=_is_approval_granted(response.approved),
+        id=response.id,
+        function_call=rebound_call,
+        annotations=response.annotations,
+        additional_properties=copy.deepcopy(response.additional_properties),
+        raw_representation=response.raw_representation,
+    )
+    if consume:
+        pending.pop(response.id, None)
+        _save_pending_approval_requests(invocation_session, pending)
+    return rebound
+
+
+def _bind_approval_responses_to_pending_requests(
+    messages: list[Message],
+    invocation_session: AgentSession | None,
+) -> None:
+    """Rebind approval responses and remove unissued or duplicate responses."""
+    if invocation_session is None:
+        return
+
+    filtered_messages: list[Message] = []
+    for message in messages:
+        filtered_contents: list[Content] = []
+        for content in message.contents:
+            if content.type != "function_approval_response":
+                filtered_contents.append(content)
+                continue
+            rebound = _bind_approval_response_to_pending_request(
+                content,
+                invocation_session,
+                consume=True,
+            )
+            if rebound is None:
+                logger.warning(
+                    "Ignored an approval response with request id %r because no pending approval request exists.",
+                    content.id,
+                )
+                continue
+            filtered_contents.append(rebound)
+        if filtered_contents:
+            message.contents = filtered_contents
+            filtered_messages.append(message)
+    messages[:] = filtered_messages
+
+
 def _store_already_approved_approval_requests(
     invocation_session: AgentSession | None,
     visible_approval_requests: Sequence[Content],
@@ -2419,7 +2566,7 @@ def _replace_approval_contents_with_results(
                 if occurrence is None:
                     occurrence = find_open_occurrence(call_id)
                 replacements: list[Content] | None
-                if content.approved:
+                if _is_approval_granted(content.approved):
                     call_result_groups = result_groups_by_call_id.get(call_id)
                     replacements = call_result_groups.popleft() if call_result_groups else None
                 else:
@@ -2708,6 +2855,8 @@ async def _resolve_approval_responses(
     """Resolve inbound approval responses before the next model call."""
     from ._types import Message
 
+    _bind_approval_responses_to_pending_requests(prepared_messages, invocation_session)
+
     # 1. Restore safe siblings hidden with a prior mixed approval batch when its visible decision arrives.
     explicit_approval_response_ids = {
         content.id
@@ -2728,7 +2877,9 @@ async def _resolve_approval_responses(
         return _FunctionProcessingResult(errors_in_a_row=errors_in_a_row)
 
     # 3. Execute approved decisions once. Rejected decisions are converted to results during normalization below.
-    responses_to_execute = [response for response in pending_approval_responses.values() if response.approved]
+    responses_to_execute = [
+        response for response in pending_approval_responses.values() if _is_approval_granted(response.approved)
+    ]
     execution_result_groups: list[list[Content]] = []
     should_terminate = False
     reached_error_limit = False
@@ -2782,14 +2933,23 @@ async def _process_model_function_calls(
     errors_in_a_row: int,
     max_errors: int,
     execute_function_calls: _FunctionCallExecutor,
+    invocation_session: AgentSession | None = None,
 ) -> _FunctionProcessingResult:
     """Execute function calls from a newly completed model response."""
+    approval_requests = [
+        content
+        for message in response.messages
+        for content in message.contents
+        if content.type == "function_approval_request"
+    ]
     # 1. Extract only actionable, unanswered calls from this model turn.
     tools = _extract_tools(options)
     function_calls = _extract_function_calls(response)
     if not (function_calls and tools):
         if function_call_messages is not None:
             _prepend_function_call_messages(response, function_call_messages)
+        if approval_requests:
+            _store_pending_approval_requests(invocation_session, approval_requests)
         return _FunctionProcessingResult(errors_in_a_row=errors_in_a_row, action="return")
 
     # 2. Execute the batch once while preserving each call's result group.
@@ -2810,6 +2970,15 @@ async def _process_model_function_calls(
     )
     if execution.should_terminate:
         processing_result.action = "return"
+    if processing_result.action == "return":
+        returned_approval_requests = [
+            content
+            for message in response.messages
+            for content in message.contents
+            if content.type == "function_approval_request"
+        ]
+        if returned_approval_requests:
+            _store_pending_approval_requests(invocation_session, returned_approval_requests)
     return processing_result
 
 
@@ -2967,6 +3136,7 @@ class FunctionInvocationLayer(Generic[OptionsCoT]):
                 errors_in_a_row=errors_in_a_row,
                 max_errors=max_errors,
                 execute_function_calls=execute_function_calls,
+                invocation_session=invocation_session,
             )
             total_function_calls = _record_function_calls(
                 budget_state,
@@ -3117,6 +3287,7 @@ class FunctionInvocationLayer(Generic[OptionsCoT]):
                 errors_in_a_row=errors_in_a_row,
                 max_errors=max_errors,
                 execute_function_calls=execute_function_calls,
+                invocation_session=invocation_session,
             )
             errors_in_a_row = function_processing.errors_in_a_row
             total_function_calls = _record_function_calls(

python/packages/core/agent_framework/_types.py

@@ -1304,7 +1304,7 @@ class Content:
         """Create function approval response content."""
         return cls(
             "function_approval_response",
-            approved=approved,
+            approved=approved if type(approved) is bool else False,
             id=id,
             function_call=function_call,
             annotations=annotations,
@@ -1457,6 +1457,9 @@ class Content:
         if (function_call := remaining.get("function_call")) and isinstance(function_call, dict):
             remaining["function_call"] = cls.from_dict(function_call)  # type: ignore[reportUnknownArgumentType]
 
+        if content_type == "function_approval_response" and type(remaining.get("approved")) is not bool:
+            remaining["approved"] = False
+
         # Handle list of Content objects (e.g., inputs in code_interpreter_tool_call)
         if (input_items := remaining.get("inputs")) and isinstance(input_items, list):
             remaining["inputs"] = [cls.from_dict(item) if isinstance(item, dict) else item for item in input_items]  # type: ignore[reportUnknownVariableType]

python/packages/core/agent_framework/_workflows/_agent.py

@@ -64,7 +64,18 @@ class WorkflowAgent(BaseAgent):
             return {"request_id": self.request_id, "request_event": self.request_event.to_dict()}
 
         @classmethod
-        def from_dict(cls, payload: dict[str, Any]) -> WorkflowAgent.RequestInfoFunctionArgs:
+        def from_dict(
+            cls,
+            payload: dict[str, Any],
+            *,
+            allowed_types: Mapping[str, type[Any]] | None = None,
+        ) -> WorkflowAgent.RequestInfoFunctionArgs:
+            """Create request-info function arguments from a dictionary.
+
+            Args:
+                payload: Serialized request-info function arguments.
+                allowed_types: Optional exact mapping of serialized names to trusted custom types.
+            """
             if "request_id" not in payload or "request_event" not in payload:
                 raise ValueError(
                     "Invalid payload for RequestInfoFunctionArgs. 'request_id' and 'request_event' are required."
@@ -74,7 +85,10 @@ class WorkflowAgent(BaseAgent):
 
             return cls(
                 request_id=payload.get("request_id", ""),
-                request_event=WorkflowEvent.from_dict(payload.get("request_event", {})),
+                request_event=WorkflowEvent.from_dict(
+                    payload.get("request_event", {}),
+                    allowed_types=allowed_types,
+                ),
             )
 
     def __init__(

python/packages/core/agent_framework/_workflows/_checkpoint.py

@@ -256,8 +256,9 @@ class FileCheckpointStorage:
 
     By default, checkpoint deserialization is restricted to a built-in set of safe Python types
     (primitives, datetime, uuid, ...), all ``agent_framework`` internal types, and OpenAI SDK types
-    (``openai.types``). To allow additional application-specific types, pass them via the
-    ``allowed_checkpoint_types`` parameter using ``"module:qualname"`` format.
+    (``openai.types``). To allow additional application-specific types, register them with
+    ``agent_framework.register_checkpoint_type`` or pass them via the ``allowed_checkpoint_types``
+    parameter using ``"module:qualname"`` format.
 
     Example::
 

python/packages/core/agent_framework/_workflows/_checkpoint_encoding.py

@@ -57,6 +57,28 @@ from ..exceptions import WorkflowCheckpointException
 
 logger = logging.getLogger("agent_framework")
 
+# Application-defined types registered for all restricted checkpoint decoders.
+_REGISTERED_CHECKPOINT_TYPE_KEYS: set[str] = set()
+
+
+def register_checkpoint_type(cls: type[Any]) -> None:
+    """Register an application type for restricted checkpoint deserialization.
+
+    Registration applies process-wide to all checkpoint storage backends that
+    use :func:`decode_checkpoint_value` with a restricted allowlist, including
+    instances created before this function is called.
+
+    Args:
+        cls: The application type to permit during checkpoint deserialization.
+
+    Raises:
+        TypeError: If ``cls`` is not a class.
+    """
+    if not isinstance(cls, type):
+        raise TypeError("Checkpoint types must be classes.")
+    _REGISTERED_CHECKPOINT_TYPE_KEYS.add(_type_to_key(cls))
+
+
 # Marker to identify pickled values in serialized JSON
 _PICKLE_MARKER = "__pickled__"
 _TYPE_MARKER = "__type__"
@@ -277,6 +299,8 @@ def decode_checkpoint_value(value: Any, *, allowed_types: frozenset[str] | None
             data is malformed, or if a disallowed type is encountered during
             restricted deserialization.
     """
+    if allowed_types is not None:
+        allowed_types = allowed_types | _REGISTERED_CHECKPOINT_TYPE_KEYS
     return _decode(value, allowed_types=allowed_types)
 
 

python/packages/core/agent_framework/_workflows/_edge_runner.py

@@ -353,9 +353,26 @@ class FanInEdgeRunner(EdgeRunner):
                     # Send aggregated data to target
                     aggregated_data = [msg.data for msg in messages_to_send]
 
-                    # Collect all trace contexts and source span IDs for fan-in linking
-                    trace_contexts = [msg.trace_context for msg in messages_to_send if msg.trace_context]
-                    source_span_ids = [msg.source_span_id for msg in messages_to_send if msg.source_span_id]
+                    # Collect all trace contexts and source span IDs for fan-in linking.
+                    # Iterate over the plural fields (trace_contexts / source_span_ids)
+                    # so that messages carrying multiple contexts from a previous
+                    # fan-in aggregation are fully preserved. Using the singular
+                    # backward-compat properties would silently drop all but the
+                    # first context per message.
+                    #
+                    # Pair contexts and span IDs per-message (via zip) so that a
+                    # message with mismatched counts only drops its own orphans
+                    # instead of shifting all subsequent pairs out of alignment
+                    # when the flattened lists are later zipped by
+                    # ``create_processing_span``.
+                    trace_contexts: list[dict[str, str]] = []
+                    source_span_ids: list[str] = []
+                    for msg in messages_to_send:
+                        msg_contexts = msg.trace_contexts or []
+                        msg_span_ids = msg.source_span_ids or []
+                        for trace_context, span_id in zip(msg_contexts, msg_span_ids, strict=False):
+                            trace_contexts.append(trace_context)
+                            source_span_ids.append(span_id)
 
                     # Create a new Message object for the aggregated data
                     aggregated_message = WorkflowMessage(

python/packages/core/agent_framework/_workflows/_events.py

@@ -6,7 +6,7 @@ import builtins
 import sys
 import traceback as _traceback
 import warnings
-from collections.abc import Generator
+from collections.abc import Generator, Mapping
 from contextlib import contextmanager
 from contextvars import ContextVar
 from dataclasses import dataclass
@@ -426,14 +426,24 @@ class WorkflowEvent(Generic[DataT]):
         }
 
     @classmethod
-    def from_dict(cls, data: dict[str, Any]) -> WorkflowEvent[Any]:
-        """Create a REQUEST_INFO event from a dictionary."""
+    def from_dict(
+        cls,
+        data: dict[str, Any],
+        *,
+        allowed_types: Mapping[str, builtins.type[Any]] | None = None,
+    ) -> WorkflowEvent[Any]:
+        """Create a request-info event from a dictionary.
+
+        Args:
+            data: Serialized request-info event fields.
+            allowed_types: Optional exact mapping of serialized names to trusted custom types.
+        """
         for prop in ["data", "request_id", "source_executor_id", "request_type", "response_type"]:
             if prop not in data:
                 raise KeyError(f"Missing '{prop}' field in WorkflowEvent dictionary.")
 
         request_data = data["data"]
-        request_type = deserialize_type(data["request_type"])
+        request_type = deserialize_type(data["request_type"], allowed_types=allowed_types)
 
         if request_type is not type(request_data):
             raise TypeError(
@@ -444,5 +454,5 @@ class WorkflowEvent(Generic[DataT]):
             request_id=data["request_id"],
             source_executor_id=data["source_executor_id"],
             request_data=cast(Any, request_data),  # type: ignore
-            response_type=deserialize_type(data["response_type"]),
+            response_type=deserialize_type(data["response_type"], allowed_types=allowed_types),
         )

python/packages/core/agent_framework/_workflows/_functional.py

@@ -21,7 +21,10 @@ parameter to access HITL and state APIs directly.
 
 Key public symbols:
 
-* :func:`workflow` / :class:`FunctionalWorkflow` — decorator and runtime.
+* :func:`workflow` / :class:`FunctionalWorkflowDefinition` — decorator and
+  stateless definition.
+* :class:`FunctionalWorkflow` — stateful runtime created by
+  :meth:`FunctionalWorkflowDefinition.build`.
 * :func:`step` / :class:`StepWrapper` — optional step decorator.
 * :class:`RunContext` — execution context injected into workflow and step
   functions.
@@ -628,6 +631,46 @@ def step(
     return _decorator
 
 
+# ---------------------------------------------------------------------------
+# FunctionalWorkflowDefinition
+# ---------------------------------------------------------------------------
+
+
+@experimental(feature_id=ExperimentalFeature.FUNCTIONAL_WORKFLOWS)
+class FunctionalWorkflowDefinition:
+    """Stateless definition produced by :func:`workflow`.
+
+    Call :meth:`build` to create a stateful :class:`FunctionalWorkflow`.
+    Each built workflow represents one logical caller or session.
+    """
+
+    def __init__(
+        self,
+        func: Callable[..., Awaitable[Any]],
+        *,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> None:
+        FunctionalWorkflow._classify_signature(func)
+        self._func = func
+        self.name = name or func.__name__
+        self.description = description
+        functools.update_wrapper(self, func)  # type: ignore[arg-type]
+
+    def build(
+        self,
+        *,
+        checkpoint_storage: CheckpointStorage | None = None,
+    ) -> FunctionalWorkflow:
+        """Build a stateful workflow for one logical caller or session."""
+        return FunctionalWorkflow(
+            self._func,
+            name=self.name,
+            description=self.description,
+            checkpoint_storage=checkpoint_storage,
+        )
+
+
 # ---------------------------------------------------------------------------
 # FunctionalWorkflow
 # ---------------------------------------------------------------------------
@@ -637,8 +680,8 @@ def step(
 class FunctionalWorkflow:
     """A workflow backed by a user-defined async function.
 
-    Created by the :func:`workflow` decorator.  Exposes the same ``run()``
-    interface as graph-based :class:`Workflow` objects, returning a
+    Built from a :class:`FunctionalWorkflowDefinition`. Exposes the same
+    ``run()`` interface as graph-based :class:`Workflow` objects, returning a
     :class:`WorkflowRunResult` (or a :class:`ResponseStream` in streaming
     mode).
 
@@ -646,6 +689,10 @@ class FunctionalWorkflow:
     edge wiring is involved.  Native Python control flow (``if``/``else``,
     ``for``, ``asyncio.gather``) is used for branching and parallelism.
 
+    Like graph-based :class:`Workflow`, each instance owns mutable execution
+    state across calls to :meth:`run`. Scope an instance to one logical
+    caller or session; build separate instances for independent callers.
+
     Args:
         func: The async function that implements the workflow logic.
         name: Display name for the workflow.  Defaults to ``func.__name__``.
@@ -664,7 +711,8 @@ class FunctionalWorkflow:
                 return await to_upper(data)
 
 
-            result = await my_pipeline.run("hello")
+            pipeline = my_pipeline.build()
+            result = await pipeline.run("hello")
             print(result.get_outputs())  # ['HELLO']
     """
 
@@ -933,7 +981,7 @@ class FunctionalWorkflow:
             if storage is None:
                 raise ValueError(
                     "Cannot restore from checkpoint without checkpoint_storage. "
-                    "Provide checkpoint_storage parameter or set it on the @workflow decorator."
+                    "Provide checkpoint_storage to build() or to this run."
                 )
             checkpoint = await storage.load(checkpoint_id)
             if checkpoint.graph_signature_hash != self.graph_signature_hash:
@@ -1258,7 +1306,7 @@ class FunctionalWorkflow:
 
 
 @overload
-def workflow(func: Callable[..., Awaitable[Any]]) -> FunctionalWorkflow: ...
+def workflow(func: Callable[..., Awaitable[Any]]) -> FunctionalWorkflowDefinition: ...
 
 
 @overload
@@ -1266,8 +1314,7 @@ def workflow(
     *,
     name: str | None = None,
     description: str | None = None,
-    checkpoint_storage: CheckpointStorage | None = None,
-) -> Callable[[Callable[..., Awaitable[Any]]], FunctionalWorkflow]: ...
+) -> Callable[[Callable[..., Awaitable[Any]]], FunctionalWorkflowDefinition]: ...
 
 
 @experimental(feature_id=ExperimentalFeature.FUNCTIONAL_WORKFLOWS)
@@ -1276,29 +1323,26 @@ def workflow(
     *,
     name: str | None = None,
     description: str | None = None,
-    checkpoint_storage: CheckpointStorage | None = None,
-) -> FunctionalWorkflow | Callable[[Callable[..., Awaitable[Any]]], FunctionalWorkflow]:
-    """Decorator that converts an async function into a :class:`FunctionalWorkflow`.
+) -> FunctionalWorkflowDefinition | Callable[[Callable[..., Awaitable[Any]]], FunctionalWorkflowDefinition]:
+    """Decorator that creates a stateless :class:`FunctionalWorkflowDefinition`.
 
     Supports both bare ``@workflow`` and parameterized
     ``@workflow(name="my_wf")`` forms.
 
     The decorated function receives its input as the first positional argument
     and a :class:`RunContext` instance wherever a parameter is annotated with
-    that type.  The resulting :class:`FunctionalWorkflow` object exposes the
-    same ``run()`` interface as graph-based workflows.
+    that type. Call ``build()`` on the resulting definition to create a
+    stateful :class:`FunctionalWorkflow`.
 
     Args:
         func: The async function to decorate (when using the bare
             ``@workflow`` form).
         name: Display name for the workflow.  Defaults to ``func.__name__``.
         description: Optional human-readable description.
-        checkpoint_storage: Default :class:`CheckpointStorage` for
-            persisting step results and workflow state.
 
     Returns:
-        A :class:`FunctionalWorkflow` (bare form) or a decorator that
-        produces one (parameterized form).
+        A :class:`FunctionalWorkflowDefinition` (bare form) or a decorator
+        that produces one (parameterized form).
 
     Examples:
 
@@ -1311,14 +1355,17 @@ def workflow(
 
 
             # Parameterized form
-            @workflow(name="my_pipeline", checkpoint_storage=storage)
+            @workflow(name="my_pipeline")
             async def pipeline(data: str) -> str: ...
+
+
+            instance = pipeline.build(checkpoint_storage=storage)
     """
     if func is not None:
-        return FunctionalWorkflow(func, name=name, description=description, checkpoint_storage=checkpoint_storage)
+        return FunctionalWorkflowDefinition(func, name=name, description=description)
 
-    def _decorator(fn: Callable[..., Awaitable[Any]]) -> FunctionalWorkflow:
-        return FunctionalWorkflow(fn, name=name, description=description, checkpoint_storage=checkpoint_storage)
+    def _decorator(fn: Callable[..., Awaitable[Any]]) -> FunctionalWorkflowDefinition:
+        return FunctionalWorkflowDefinition(fn, name=name, description=description)
 
     return _decorator
 
@@ -1343,6 +1390,12 @@ class FunctionalWorkflowAgent:
     :class:`WorkflowAgent`), so HITL workflows are callable via this
     adapter.  Callers resume via ``responses=`` / ``checkpoint_id=``.
 
+    The wrapped workflow owns mutable execution state. Scope the workflow and
+    this adapter to one logical caller or session; create separate workflow
+    instances for independent or mutually untrusted callers. If those
+    instances use checkpoint storage, the host must also authorize and
+    tenant-scope access to that external store.
+
     Args:
         workflow: The :class:`FunctionalWorkflow` to wrap.
         name: Display name for the agent.  Defaults to the workflow name.

python/packages/core/agent_framework/_workflows/_typing_utils.py

@@ -1,7 +1,9 @@
 # Copyright (c) Microsoft. All rights reserved.
 
+import sys
 import typing
-from types import UnionType
+from collections.abc import Mapping
+from types import ModuleType, UnionType
 from typing import Any, TypeGuard, Union, cast, get_args, get_origin
 
 import typing_extensions
@@ -14,6 +16,17 @@ from .._agents import Agent
 _TYPEVAR_TYPES: tuple[type, ...] = (type(typing.TypeVar("_T")), type(typing_extensions.TypeVar("_T")))  # pyright: ignore[reportUnknownVariableType]
 
 
+def _is_runtime_type(value: object) -> TypeGuard[type[Any]]:
+    if not isinstance(value, type):
+        return False
+    try:
+        type.__getattribute__(value, "__module__")
+        type.__getattribute__(value, "__qualname__")
+    except TypeError:
+        return False
+    return True
+
+
 def is_typevar(x: Any) -> bool:
     """Check if x is an unresolved TypeVar instance (from typing or typing_extensions).
 
@@ -274,19 +287,46 @@ def serialize_type(t: type) -> str:
     return f"{t.__module__}.{t.__qualname__}"
 
 
-def deserialize_type(serialized_type_string: str) -> type:
+def deserialize_type(
+    serialized_type_string: str,
+    *,
+    allowed_types: Mapping[str, type[Any]] | None = None,
+) -> type:
     """Deserialize a serialized type string.
 
+    Resolution is limited to exact caller-supplied types or types already present
+    in loaded module namespaces. This function never imports a module selected by
+    the serialized value.
+
+    Args:
+        serialized_type_string: Fully qualified serialized type name.
+        allowed_types: Optional exact mapping of serialized names to trusted types.
+
     For example,
 
     deserialize_type("builtins.int") => int
     """
-    import importlib
+    if allowed_types is not None and serialized_type_string in allowed_types:
+        resolved = allowed_types[serialized_type_string]
+        if not _is_runtime_type(resolved):
+            raise TypeError(f"allowed_types entry {serialized_type_string!r} must be a type.")
+        if serialize_type(resolved) != serialized_type_string:
+            raise ValueError(f"allowed_types entry {serialized_type_string!r} does not match the supplied type.")
+        return resolved
 
     module_name, _, type_name = serialized_type_string.rpartition(".")
-    module = importlib.import_module(module_name)
+    module = sys.modules.get(module_name)
+    if not isinstance(module, ModuleType):
+        raise ModuleNotFoundError(f"No module named {module_name!r}", name=module_name)
 
-    return cast(type, getattr(module, type_name))
+    namespace = ModuleType.__getattribute__(module, "__dict__")
+    if type_name not in namespace:
+        raise AttributeError(f"{module_name!r} has no attribute {type_name!r}")
+
+    resolved = namespace[type_name]
+    if not _is_runtime_type(resolved):
+        raise TypeError(f"{serialized_type_string!r} does not resolve to a type.")
+    return resolved
 
 
 def is_type_compatible(source_type: type | UnionType | Any, target_type: type | UnionType | Any) -> bool:

python/packages/core/pyproject.toml

@@ -4,7 +4,7 @@ description = "Microsoft Agent Framework for building AI Agents with Python. Thi
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.13.0"
+version = "1.14.0"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"

python/packages/core/tests/core/test_agent_hooks.py

@@ -9,6 +9,7 @@ from typing import Any, cast
 import pytest
 
 import agent_framework
+import agent_framework._telemetry as telemetry
 from agent_framework import (
     Agent,
     AgentContext,
@@ -155,6 +156,23 @@ FULL_TOOL_RUN_POINTS = [
 # region Factory validation
 
 
+@pytest.mark.parametrize("factory_kind", ["managed", "host_owned"])
+@requires_sdk
+def test_agent_hooks_factories_activate_feature_telemetry(factory_kind: str, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(telemetry, "_feature_mask", 0)
+    monkeypatch.setattr(telemetry, "IS_TELEMETRY_ENABLED", True)
+    monkeypatch.setenv(telemetry.FEATURE_MASK_DISABLED_ENV_VAR, "false")
+
+    if factory_kind == "managed":
+        create_agent_hooks_middleware([AllowGuard()])
+    else:
+        emitter = InterceptionEmitter().register(AllowGuard())
+        builder = AgentContextBuilder(agent_id="a", framework="agent-framework", session_id="s")
+        create_agent_hooks_middleware_from_emitter(emitter, builder)
+
+    assert telemetry.get_feature_token() == "v1.40000"
+
+
 @requires_sdk
 async def test_factory_requires_interceptors() -> None:
     with pytest.raises(ValueError, match="at least one interceptor"):

python/packages/core/tests/core/test_function_invocation_logic.py

@@ -8,6 +8,7 @@ import pytest
 
 from agent_framework import (
     Agent,
+    AgentSession,
     ChatOptions,
     ChatResponse,
     ChatResponseUpdate,
@@ -55,6 +56,213 @@ def _build_approved_tool_roundtrip(
     return function_call, approval_request, approval_response
 
 
+def test_session_approval_binding_rebinds_consumes_and_rejects_duplicates() -> None:
+    """Session binding must use the recorded call and honor one response once."""
+    from agent_framework._tools import (
+        _bind_approval_responses_to_pending_requests,
+        _store_pending_approval_requests,
+    )
+
+    session = AgentSession(session_id="approval-binding")
+    original_call = Content.from_function_call(
+        call_id="call_original",
+        name="guarded_write",
+        arguments={"value": "approved"},
+    )
+    request = Content.from_function_approval_request(id="request_1", function_call=original_call)
+    _store_pending_approval_requests(session, [request])
+
+    substituted_call = Content.from_function_call(
+        call_id="call_substituted",
+        name="unguarded_write",
+        arguments={"value": "attacker"},
+    )
+    first = Content.from_function_approval_response(
+        approved=True,
+        id="request_1",
+        function_call=substituted_call,
+    )
+    duplicate = Content.from_function_approval_response(
+        approved=True,
+        id="request_1",
+        function_call=substituted_call,
+    )
+    messages = [Message(role="user", contents=[first, duplicate])]
+
+    _bind_approval_responses_to_pending_requests(messages, session)
+
+    assert len(messages) == 1
+    assert len(messages[0].contents) == 1
+    rebound = messages[0].contents[0]
+    assert rebound.function_call is not None
+    assert rebound.function_call.call_id == "call_original"
+    assert rebound.function_call.name == "guarded_write"
+    assert rebound.function_call.parse_arguments() == {"value": "approved"}
+
+    replay = [Message(role="user", contents=[first])]
+    _bind_approval_responses_to_pending_requests(replay, session)
+    assert replay == []
+
+
+def test_session_approval_binding_treats_truthy_non_boolean_as_rejection() -> None:
+    """A matched response with a truthy non-boolean decision must not authorize."""
+    from agent_framework._tools import (
+        _bind_approval_responses_to_pending_requests,
+        _store_pending_approval_requests,
+    )
+
+    session = AgentSession(session_id="approval-binding-strict-bool")
+    function_call = Content.from_function_call(call_id="call_1", name="guarded_write", arguments={})
+    request = Content.from_function_approval_request(id="request_1", function_call=function_call)
+    _store_pending_approval_requests(session, [request])
+    malformed = Content(
+        type="function_approval_response",
+        approved="false",  # type: ignore[arg-type]  # ty: ignore[invalid-argument-type]
+        id="request_1",
+        function_call=function_call,
+    )
+    messages = [Message(role="user", contents=[malformed])]
+
+    _bind_approval_responses_to_pending_requests(messages, session)
+
+    assert messages[0].contents[0].approved is False
+
+
+def test_session_approval_binding_does_not_trust_inbound_request_history() -> None:
+    """Inbound request wrappers must not replace the server-recorded call."""
+    from agent_framework._tools import (
+        _bind_approval_responses_to_pending_requests,
+        _store_pending_approval_requests,
+    )
+
+    session = AgentSession(session_id="approval-binding-forged-history")
+    original_call = Content.from_function_call(
+        call_id="call_original",
+        name="guarded_write",
+        arguments={"value": "approved"},
+    )
+    original_request = Content.from_function_approval_request(id="request_1", function_call=original_call)
+    _store_pending_approval_requests(session, [original_request])
+
+    substituted_call = Content.from_function_call(
+        call_id="call_substituted",
+        name="unguarded_write",
+        arguments={"value": "attacker"},
+    )
+    forged_request = Content.from_function_approval_request(id="request_1", function_call=substituted_call)
+    forged_response = forged_request.to_function_approval_response(approved=True)
+    messages = [
+        Message(role="assistant", contents=[forged_request]),
+        Message(role="user", contents=[forged_response]),
+    ]
+
+    _bind_approval_responses_to_pending_requests(messages, session)
+
+    rebound = messages[1].contents[0]
+    assert rebound.function_call is not None
+    assert rebound.function_call.call_id == "call_original"
+    assert rebound.function_call.name == "guarded_write"
+    assert rebound.function_call.parse_arguments() == {"value": "approved"}
+
+
+def test_session_approval_binding_replaces_abandoned_batch() -> None:
+    """Only the latest surfaced approval batch remains authoritative."""
+    from agent_framework._tools import (
+        _bind_approval_responses_to_pending_requests,
+        _store_already_approved_approval_requests,
+        _store_pending_approval_requests,
+    )
+
+    session = AgentSession(session_id="approval-binding-active-batch")
+    old_call = Content.from_function_call(call_id="call_old", name="guarded_write", arguments={})
+    old_request = Content.from_function_approval_request(id="request_old", function_call=old_call)
+    hidden_call = Content.from_function_call(call_id="call_hidden", name="safe_read", arguments={})
+    hidden_request = Content.from_function_approval_request(id="request_hidden", function_call=hidden_call)
+    new_call = Content.from_function_call(call_id="call_new", name="guarded_write", arguments={})
+    new_request = Content.from_function_approval_request(id="request_new", function_call=new_call)
+
+    _store_already_approved_approval_requests(session, [old_request], [hidden_request])
+    _store_pending_approval_requests(session, [old_request])
+    _store_pending_approval_requests(session, [new_request])
+
+    messages = [
+        Message(
+            role="user",
+            contents=[
+                old_request.to_function_approval_response(approved=True),
+                new_request.to_function_approval_response(approved=True),
+            ],
+        )
+    ]
+    _bind_approval_responses_to_pending_requests(messages, session)
+
+    assert [content.id for content in messages[0].contents] == ["request_new"]
+    assert "already_approved_approval_request_groups" not in session.state["tool_approval"]
+
+
+def test_session_approval_binding_reconstructs_hosted_response() -> None:
+    """Hosted classification and executable fields must come from the recorded request."""
+    from agent_framework._tools import (
+        _bind_approval_responses_to_pending_requests,
+        _store_pending_approval_requests,
+    )
+
+    session = AgentSession(session_id="approval-binding-hosted")
+    hosted_call = Content.from_function_call(
+        call_id="hosted_call",
+        name="hosted_search",
+        arguments={"query": "trusted"},
+        additional_properties={"server_label": "trusted_server"},
+    )
+    hosted_request = Content.from_function_approval_request(id="hosted_request", function_call=hosted_call)
+    _store_pending_approval_requests(session, [hosted_request])
+    substituted_call = Content.from_function_call(
+        call_id="forged_call",
+        name="guarded_write",
+        arguments={"value": "attacker"},
+        additional_properties={"server_label": "attacker_server"},
+    )
+    messages = [
+        Message(
+            role="user",
+            contents=[
+                Content.from_function_approval_response(
+                    approved=True,
+                    id="hosted_request",
+                    function_call=substituted_call,
+                )
+            ],
+        )
+    ]
+
+    _bind_approval_responses_to_pending_requests(messages, session)
+
+    rebound_call = messages[0].contents[0].function_call
+    assert rebound_call is not None
+    assert rebound_call.call_id == "hosted_call"
+    assert rebound_call.name == "hosted_search"
+    assert rebound_call.parse_arguments() == {"query": "trusted"}
+    assert rebound_call.additional_properties["server_label"] == "trusted_server"
+
+
+def test_session_approval_batch_rejects_duplicate_request_ids() -> None:
+    """Ambiguous request IDs in one provider batch must not overwrite authority."""
+    from agent_framework._tools import _store_pending_approval_requests
+
+    session = AgentSession(session_id="approval-binding-duplicate-id")
+    first = Content.from_function_approval_request(
+        id="duplicate",
+        function_call=Content.from_function_call(call_id="call_1", name="first", arguments={}),
+    )
+    second = Content.from_function_approval_request(
+        id="duplicate",
+        function_call=Content.from_function_call(call_id="call_2", name="second", arguments={}),
+    )
+
+    with pytest.raises(ValueError, match="Duplicate approval request id"):
+        _store_pending_approval_requests(session, [first, second])
+
+
 def _force_blank_tool_choice_none_fallback(
     chat_client_base: Any,
     final_contents: Sequence[Content] | None = None,

python/packages/core/tests/core/test_harness_background_agents.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+from contextlib import suppress
 from typing import Any
 
 import pytest
@@ -542,3 +543,303 @@ def test_task_status_enum_values() -> None:
     assert BackgroundTaskStatus.COMPLETED == "completed"
     assert BackgroundTaskStatus.FAILED == "failed"
     assert BackgroundTaskStatus.LOST == "lost"
+
+
+async def test_release_session_cancels_and_clears() -> None:
+    """Should cancel pending tasks and clear runtime state."""
+    provider = _make_provider(_FakeAgent("Slow", delay=10.0))
+    session = _make_session()
+    tools = await _get_tools(provider, session)
+
+    await _invoke_tool(
+        tools["background_agents_start_task"],
+        agent_name="Slow",
+        input="task",
+        description="long running",
+    )
+
+    runtime = provider._runtime.get(session.session_id)
+    assert runtime is not None
+    assert len(runtime.in_flight_tasks) == 1
+
+    task = next(iter(runtime.in_flight_tasks.values()))
+
+    await provider.release_session(session, cancel_running=True)
+
+    assert task.done()
+    assert task.cancelled()
+    assert runtime.in_flight_tasks == {}
+    assert runtime.background_sessions == {}
+
+    assert session.session_id not in provider._runtime
+
+
+async def test_release_session_raises_if_cancel_running_false() -> None:
+    """Should raise RuntimeError if cancel_running=False and tasks are pending."""
+    provider = _make_provider(_FakeAgent("Slow", delay=10.0))
+    session = _make_session()
+    tools = await _get_tools(provider, session)
+
+    await _invoke_tool(
+        tools["background_agents_start_task"],
+        agent_name="Slow",
+        input="task",
+        description="long running",
+    )
+
+    with pytest.raises(RuntimeError, match="tasks still running"):
+        await provider.release_session(session, cancel_running=False)
+
+    assert session.session_id in provider._runtime
+    await provider.release_session(session, cancel_running=True)
+
+
+async def test_release_session_idempotent() -> None:
+    """Should not raise when releasing an unknown or already released session."""
+    provider = _make_provider(_FakeAgent("Worker"))
+    session = _make_session()
+
+    await provider.release_session(AgentSession(session_id="non_existent_session"))
+
+    await provider.release_session(session)
+    await provider.release_session(session)
+
+
+async def test_release_session_isolation() -> None:
+    """Releasing one session should not affect another."""
+    provider = _make_provider(_FakeAgent("Worker", delay=10.0))
+    session_a = AgentSession(session_id="session_a")
+    session_b = AgentSession(session_id="session_b")
+
+    tools_a = await _get_tools(provider, session_a)
+    tools_b = await _get_tools(provider, session_b)
+
+    await _invoke_tool(
+        tools_a["background_agents_start_task"],
+        agent_name="Worker",
+        input="A",
+        description="A",
+    )
+    await _invoke_tool(
+        tools_b["background_agents_start_task"],
+        agent_name="Worker",
+        input="B",
+        description="B",
+    )
+
+    await provider.release_session(session_a, cancel_running=True)
+
+    assert "session_a" not in provider._runtime
+    assert "session_b" in provider._runtime
+
+    await provider.release_session(session_b, cancel_running=True)
+
+
+async def test_get_runtime_replaces_closed_runtime() -> None:
+    """A closed runtime should be replaced by a new runtime instance."""
+    provider = _make_provider(_FakeAgent("Worker"))
+    session = _make_session()
+
+    old_runtime = provider._get_runtime(session)
+    old_runtime.closed = True
+
+    new_runtime = provider._get_runtime(session)
+
+    assert new_runtime is not old_runtime
+    assert provider._runtime.get(session.session_id) is new_runtime
+
+
+async def test_track_task_rejects_when_runtime_closed() -> None:
+    """Closed runtime should not accept new background tasks."""
+    provider = _make_provider(_FakeAgent("Worker"))
+    session = _make_session()
+
+    runtime = provider._get_runtime(session)
+    runtime.closed = True
+
+    async def _dummy() -> Any:
+        await asyncio.sleep(0)
+
+    task = asyncio.create_task(_dummy())
+
+    with pytest.raises(RuntimeError, match="closed"):
+        runtime.track_task(1, task)
+
+    with suppress(asyncio.CancelledError):
+        await task
+
+    assert task.cancelled()
+
+
+async def test_start_task_returns_error_when_runtime_closed() -> None:
+    """background_agents_start_task should refuse to run on a closed runtime."""
+    provider = _make_provider(_FakeAgent("Worker"))
+    session = _make_session()
+
+    tools = await _get_tools(provider, session)
+
+    runtime = provider._get_runtime(session)
+    runtime.closed = True
+
+    result = await _invoke_tool(
+        tools["background_agents_start_task"],
+        agent_name="Worker",
+        input="task",
+        description="should not start",
+    )
+
+    assert "being released" in result
+    assert runtime.in_flight_tasks == {}
+
+
+async def test_tools_return_error_when_runtime_closed() -> None:
+    """Mutating/background tools should refuse to run on a closed runtime."""
+    provider = _make_provider(_FakeAgent("Worker"))
+    session = _make_session()
+
+    tools = await _get_tools(provider, session)
+
+    runtime = provider._get_runtime(session)
+    runtime.closed = True
+
+    wait_result = await _invoke_tool(
+        tools["background_agents_wait_for_first_completion"],
+        task_ids=[1],
+    )
+    assert "being released" in wait_result
+
+    continue_result = await _invoke_tool(
+        tools["background_agents_continue_task"],
+        task_id=1,
+        text="continue",
+    )
+    assert "being released" in continue_result
+
+    clear_result = await _invoke_tool(
+        tools["background_agents_clear_completed_task"],
+        task_id=1,
+    )
+    assert "being released" in clear_result
+
+
+async def test_release_session_times_out_if_task_ignores_cancellation() -> None:
+    """release_session should return within bounded time even if task ignores cancel."""
+    provider = _make_provider(_FakeAgent("Worker"))
+    session = _make_session()
+
+    runtime = provider._get_runtime(session)
+    unblock = asyncio.Event()
+
+    async def _ignore_cancel() -> Any:
+        try:
+            await unblock.wait()
+        except asyncio.CancelledError:
+            await unblock.wait()
+            raise
+
+    task = asyncio.create_task(_ignore_cancel())
+    runtime.in_flight_tasks[1] = task
+
+    start = asyncio.get_running_loop().time()
+
+    await asyncio.wait_for(
+        provider.release_session(
+            session,
+            cancel_running=True,
+            timeout=0.05,
+        ),
+        timeout=1.0,
+    )
+
+    elapsed = asyncio.get_running_loop().time() - start
+
+    assert elapsed < 1.0
+    assert session.session_id not in provider._runtime
+
+    unblock.set()
+    with suppress(asyncio.CancelledError):
+        await asyncio.wait_for(task, timeout=1.0)
+
+
+async def test_release_session_does_not_pop_replacement_runtime() -> None:
+    """A release of an old runtime should not remove a replacement runtime."""
+    provider = _make_provider(_FakeAgent("Worker"))
+    session = _make_session()
+
+    old_runtime = provider._get_runtime(session)
+    unblock = asyncio.Event()
+
+    async def _blocked_task() -> Any:
+        try:
+            await unblock.wait()
+        except asyncio.CancelledError:
+            await unblock.wait()
+            raise
+
+    task = asyncio.create_task(_blocked_task())
+    old_runtime.in_flight_tasks[1] = task
+
+    release_task = asyncio.create_task(
+        provider.release_session(
+            session,
+            cancel_running=True,
+            timeout=5.0,
+        )
+    )
+
+    for _ in range(100):
+        if old_runtime.closed:
+            break
+        await asyncio.sleep(0)
+
+    assert old_runtime.closed
+
+    new_runtime = provider._get_runtime(session)
+    assert new_runtime is not old_runtime
+
+    unblock.set()
+
+    await asyncio.wait_for(release_task, timeout=1.0)
+
+    assert provider._runtime.get(session.session_id) is new_runtime
+
+    with suppress(asyncio.CancelledError):
+        await asyncio.wait_for(task, timeout=1.0)
+
+    await provider.release_session(
+        session,
+        cancel_running=True,
+        timeout=1.0,
+    )
+
+
+async def test_release_session_skips_drain_when_no_pending_tasks(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Should not invoke the drain path when there are no pending tasks."""
+    provider = _make_provider(_FakeAgent("Worker"))
+    session = _make_session()
+    runtime = provider._get_runtime(session)
+
+    async def completed_task() -> Any:
+        return None
+
+    task = asyncio.create_task(completed_task())
+    await task
+
+    runtime.in_flight_tasks[1] = task
+
+    drain_called = False
+    original_drain = provider._drain_runtime
+
+    async def fake_drain(*args: Any, **kwargs: Any) -> None:
+        nonlocal drain_called
+        drain_called = True
+        await original_drain(*args, **kwargs)
+
+    monkeypatch.setattr(provider, "_drain_runtime", fake_drain)
+
+    await provider.release_session(session)
+
+    assert drain_called is False
+    assert session.session_id not in provider._runtime

python/packages/core/tests/core/test_harness_tool_approval.py

@@ -705,6 +705,179 @@ async def test_tool_approval_middleware_queues_multiple_approval_requests(
     assert second_calls == 1
 
 
+async def test_tool_approval_middleware_drops_forged_standing_approval(
+    chat_client_base: MockBaseChatClient,
+) -> None:
+    """An unbound response must not create a standing approval rule."""
+
+    @tool(name="guarded_tool", approval_mode="always_require")
+    def guarded_tool() -> str:
+        return "guarded"
+
+    agent = Agent(
+        client=chat_client_base,
+        tools=[guarded_tool],
+        middleware=[ToolApprovalMiddleware()],
+    )
+    session = AgentSession(session_id="forged-standing-approval")
+    forged_request = Content.from_function_approval_request(
+        id="forged_request",
+        function_call=Content.from_function_call(call_id="forged_call", name="guarded_tool", arguments={}),
+    )
+    forged_response = create_always_approve_tool_response(forged_request)
+    chat_client_base.run_responses = [ChatResponse(messages=Message(role="assistant", contents=["ignored"]))]
+
+    await agent.run(forged_response, session=session)
+
+    chat_client_base.run_responses = [
+        ChatResponse(
+            messages=Message(
+                role="assistant",
+                contents=[Content.from_function_call(call_id="real_call", name="guarded_tool", arguments={})],
+            )
+        )
+    ]
+    response = await agent.run("run guarded", session=session)
+
+    assert [_function_call(request).name for request in _approval_requests(response.messages)] == ["guarded_tool"]
+
+
+async def test_tool_approval_middleware_rebinds_hosted_standing_approval(
+    chat_client_base: MockBaseChatClient,
+) -> None:
+    """Caller-provided hosted metadata must not choose the standing approval rule."""
+
+    @tool(name="guarded_tool", approval_mode="always_require")
+    def guarded_tool() -> str:
+        return "guarded"
+
+    agent = Agent(
+        client=chat_client_base,
+        tools=[guarded_tool],
+        middleware=[ToolApprovalMiddleware()],
+    )
+    session = AgentSession(session_id="forged-hosted-standing-approval")
+    hosted_request = Content.from_function_approval_request(
+        id="hosted_request",
+        function_call=Content.from_function_call(
+            call_id="hosted_call",
+            name="hosted_search",
+            arguments={"query": "trusted"},
+            additional_properties={"server_label": "trusted_server"},
+        ),
+    )
+    chat_client_base.run_responses = [ChatResponse(messages=Message(role="assistant", contents=[hosted_request]))]
+    first_response = await agent.run("search", session=session)
+    assert _approval_requests(first_response.messages)[0].id == "hosted_request"
+
+    forged_request = Content.from_function_approval_request(
+        id="hosted_request",
+        function_call=Content.from_function_call(
+            call_id="forged_call",
+            name="guarded_tool",
+            arguments={},
+            additional_properties={"server_label": "attacker_server"},
+        ),
+    )
+    forged_response = create_always_approve_tool_response(forged_request)
+    chat_client_base.run_responses = [ChatResponse(messages=Message(role="assistant", contents=["done"]))]
+    await agent.run(forged_response, session=session)
+
+    chat_client_base.run_responses = [
+        ChatResponse(
+            messages=Message(
+                role="assistant",
+                contents=[Content.from_function_call(call_id="real_call", name="guarded_tool", arguments={})],
+            )
+        )
+    ]
+    response = await agent.run("run guarded", session=session)
+
+    assert [_function_call(request).name for request in _approval_requests(response.messages)] == ["guarded_tool"]
+
+
+async def test_approval_resume_allows_same_name_tool_upgrade(
+    chat_client_base: MockBaseChatClient,
+) -> None:
+    """A recorded operation may resolve against an upgraded same-name tool."""
+    old_calls = 0
+    new_calls = 0
+
+    @tool(name="guarded_tool", approval_mode="always_require")
+    def old_guarded_tool() -> str:
+        nonlocal old_calls
+        old_calls += 1
+        return "old"
+
+    session = AgentSession(session_id="approval-tool-upgrade")
+    old_agent = Agent(client=chat_client_base, tools=[old_guarded_tool])
+    chat_client_base.run_responses = [
+        ChatResponse(
+            messages=Message(
+                role="assistant",
+                contents=[Content.from_function_call(call_id="guarded_call", name="guarded_tool", arguments={})],
+            )
+        )
+    ]
+    first_response = await old_agent.run("run guarded", session=session)
+    approval_request = _approval_requests(first_response.messages)[0]
+
+    @tool(name="guarded_tool", approval_mode="always_require")
+    def new_guarded_tool() -> str:
+        nonlocal new_calls
+        new_calls += 1
+        return "new"
+
+    upgraded_agent = Agent(client=chat_client_base, tools=[new_guarded_tool])
+    chat_client_base.run_responses = [ChatResponse(messages=Message(role="assistant", contents=["done"]))]
+    await upgraded_agent.run(
+        approval_request.to_function_approval_response(approved=True),
+        session=session,
+    )
+
+    assert old_calls == 0
+    assert new_calls == 1
+
+
+async def test_approval_resume_does_not_execute_when_recorded_tool_disappears(
+    chat_client_base: MockBaseChatClient,
+) -> None:
+    """Removing the recorded tool must not fall back to another implementation."""
+    calls = 0
+
+    @tool(name="guarded_tool", approval_mode="always_require")
+    def guarded_tool() -> str:
+        nonlocal calls
+        calls += 1
+        return "guarded"
+
+    session = AgentSession(session_id="approval-tool-removed")
+    original_agent = Agent(client=chat_client_base, tools=[guarded_tool])
+    chat_client_base.run_responses = [
+        ChatResponse(
+            messages=Message(
+                role="assistant",
+                contents=[Content.from_function_call(call_id="guarded_call", name="guarded_tool", arguments={})],
+            )
+        )
+    ]
+    first_response = await original_agent.run("run guarded", session=session)
+    approval_request = _approval_requests(first_response.messages)[0]
+
+    @tool(name="other_tool")
+    def other_tool() -> str:
+        return "other"
+
+    agent_without_tool = Agent(client=chat_client_base, tools=[other_tool])
+    chat_client_base.run_responses = [ChatResponse(messages=Message(role="assistant", contents=["done"]))]
+    await agent_without_tool.run(
+        approval_request.to_function_approval_response(approved=True),
+        session=session,
+    )
+
+    assert calls == 0
+
+
 async def test_tool_approval_middleware_preserves_hidden_mixed_batch_requests(
     chat_client_base: MockBaseChatClient,
 ) -> None:

python/packages/core/tests/core/test_skills.py

@@ -676,6 +676,17 @@ class TestBuildSkillsInstructionPrompt:
         assert "<description>Does stuff.</description>" in prompt
         assert "load_skill" in prompt
 
+    def test_default_prompt_distinguishes_script_argument_shapes(self) -> None:
+        skills = [
+            InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="Does stuff."), instructions="Body"),
+        ]
+        prompt = SkillsProvider._create_instructions(None, skills)
+        assert prompt is not None
+        script_guidance = [line for line in prompt.splitlines() if "script" in line]
+        assert any("JSON object" in line and "inline scripts" in line for line in script_guidance)
+        assert any("array of strings" in line and "file-based scripts" in line for line in script_guidance)
+        assert "not as top-level tool parameters" in prompt
+
     def test_skills_sorted_alphabetically(self) -> None:
         skills = [
             InlineSkill(frontmatter=SkillFrontmatter(name="zebra", description="Z skill."), instructions="Body"),

python/packages/core/tests/core/test_types.py

@@ -2256,6 +2256,24 @@ def test_function_approval_response_content_serialization():
     assert response_dict["function_call"]["call_id"] == "call123"
 
 
+@pytest.mark.parametrize("approved", ["false", "no", 1, "0", 0, None])
+def test_function_approval_response_deserialization_rejects_non_boolean_decisions(approved: Any) -> None:
+    """Serialized non-boolean approval decisions must fail closed."""
+    response = Content.from_dict({
+        "type": "function_approval_response",
+        "id": "response123",
+        "approved": approved,
+        "function_call": {
+            "type": "function_call",
+            "call_id": "call123",
+            "name": "test_func",
+            "arguments": {},
+        },
+    })
+
+    assert response.approved is False
+
+
 def test_chat_response_complex_serialization():
     """Test ChatResponse from_dict and to_dict with complex nested objects."""
 

python/packages/core/tests/workflow/test_checkpoint_unrestricted_pickle.py

@@ -22,7 +22,7 @@ from typing import Any
 
 import pytest
 
-from agent_framework import WorkflowCheckpointException
+from agent_framework import WorkflowCheckpointException, register_checkpoint_type
 from agent_framework._workflows._checkpoint import FileCheckpointStorage
 from agent_framework._workflows._checkpoint_encoding import (
     _PICKLE_MARKER,
@@ -210,6 +210,13 @@ class _AllowedTestState:
     value: int
 
 
+@dataclass
+class _GloballyRegisteredTestState:
+    """Test dataclass registered for process-wide checkpoint deserialization."""
+
+    name: str
+
+
 def test_restricted_decode_blocks_unlisted_user_type():
     """User-defined types are blocked when not in allowed_checkpoint_types."""
     original = _AllowedTestState(name="test", value=42)
@@ -301,6 +308,25 @@ async def test_file_storage_allows_listed_user_type():
         assert loaded.state["data"].value == 99
 
 
+async def test_file_storage_allows_globally_registered_user_type() -> None:
+    """A registered type can be restored without configuring the storage instance."""
+    from agent_framework import WorkflowCheckpoint
+
+    register_checkpoint_type(_GloballyRegisteredTestState)
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        storage = FileCheckpointStorage(tmpdir)
+        checkpoint = WorkflowCheckpoint(
+            workflow_name="test",
+            graph_signature_hash="hash",
+            state={"data": _GloballyRegisteredTestState(name="registered")},
+        )
+        await storage.save(checkpoint)
+        loaded = await storage.load(checkpoint.checkpoint_id)
+
+        assert loaded.state["data"] == _GloballyRegisteredTestState(name="registered")
+
+
 async def test_file_storage_round_trips_marker_shaped_dict_state() -> None:
     """FileCheckpointStorage preserves marker-shaped dictionaries as user data."""
     from agent_framework import WorkflowCheckpoint

python/packages/core/tests/workflow/test_edge.py

@@ -1191,6 +1191,92 @@ async def test_fan_in_edge_group_with_multiple_message_types_failed() -> None:
         )
 
 
+class TraceCapturingAggregator(Executor):
+    """Fan-in aggregator that captures the trace contexts received by its handler.
+
+    Captures the source trace data from the :class:`WorkflowContext` passed to
+    the handler rather than overriding :meth:`Executor.execute` (which is
+    documented as *do not override* — it owns locking, span creation, handler
+    dispatch, and context construction).
+    """
+
+    def __init__(self, *, id: str) -> None:
+        super().__init__(id=id)
+        self.captured_trace_contexts: list[dict[str, str]] | None = None
+        self.captured_source_span_ids: list[str] | None = None
+        self.call_count: int = 0
+
+    @handler
+    async def mock_aggregator_handler(self, message: list[MockMessage], ctx: WorkflowContext) -> None:
+        self.call_count += 1
+        self.captured_trace_contexts = list(ctx._trace_contexts)
+        self.captured_source_span_ids = list(ctx._source_span_ids)
+
+
+async def test_fan_in_preserves_multiple_trace_contexts_per_message() -> None:
+    """Fan-in must aggregate ALL trace contexts, not just the first per message.
+
+    Each incoming message may carry multiple trace_contexts (e.g. when it is
+    itself the product of a prior fan-in). The aggregated message must include
+    every trace context and source span ID from every source message; using the
+    singular backward-compat properties (trace_context / source_span_id) would
+    silently drop all but the first context per message.
+    """
+    source1 = MockExecutor(id="source_executor_1")
+    source2 = MockExecutor(id="source_executor_2")
+    target = TraceCapturingAggregator(id="target_executor")
+
+    executors: dict[str, Executor] = {source1.id: source1, source2.id: source2, target.id: target}
+    edge_group = FanInEdgeGroup(source_ids=[source1.id, source2.id], target_id=target.id)
+    edge_runner = create_edge_runner(edge_group, executors)
+
+    state = State()
+    ctx = InProcRunnerContext()
+    data = MockMessage(data="test")
+
+    # Source 1 carries TWO trace contexts (simulating a prior fan-in aggregation)
+    multi_contexts_1 = [
+        {"traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"},
+        {"traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-aaaaaaaaaaaaaaaa-01"},
+    ]
+    multi_span_ids_1 = ["00f067aa0ba902b7", "aaaaaaaaaaaaaaaa"]
+
+    # Source 2 carries a single trace context
+    single_contexts_2 = [
+        {"traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b8-01"},
+    ]
+    single_span_ids_2 = ["00f067aa0ba902b8"]
+
+    # Send first message (buffered)
+    assert await edge_runner.send_message(
+        WorkflowMessage(
+            data=data, source_id=source1.id, trace_contexts=multi_contexts_1, source_span_ids=multi_span_ids_1
+        ),
+        state,
+        ctx,
+    )
+
+    # Send second message (triggers delivery)
+    assert await edge_runner.send_message(
+        WorkflowMessage(
+            data=data, source_id=source2.id, trace_contexts=single_contexts_2, source_span_ids=single_span_ids_2
+        ),
+        state,
+        ctx,
+    )
+
+    # The target executor should have received ALL 3 trace contexts (2 + 1),
+    # not just 2 (one per message via the singular property).
+    assert target.call_count == 1
+    assert target.captured_trace_contexts is not None
+    assert len(target.captured_trace_contexts) == 3
+    assert target.captured_trace_contexts == multi_contexts_1 + single_contexts_2
+
+    assert target.captured_source_span_ids is not None
+    assert len(target.captured_source_span_ids) == 3
+    assert target.captured_source_span_ids == multi_span_ids_1 + single_span_ids_2
+
+
 # endregion FanInEdgeGroup
 
 # region SwitchCaseEdgeGroup

python/packages/core/tests/workflow/test_functional_workflow.py

@@ -7,17 +7,20 @@ from __future__ import annotations
 import asyncio
 import json
 import logging
-from collections.abc import Iterator
+from collections.abc import Awaitable, Callable, Iterator
 from contextlib import contextmanager
 from dataclasses import dataclass
+from typing import Any, overload
 
 import pytest
 
 from agent_framework import (
     AgentResponseUpdate,
+    CheckpointStorage,
     ExperimentalFeature,
     FunctionalWorkflow,
     FunctionalWorkflowAgent,
+    FunctionalWorkflowDefinition,
     InMemoryCheckpointStorage,
     RunContext,
     StepWrapper,
@@ -37,6 +40,34 @@ from agent_framework._workflows._functional import (
 # ---------------------------------------------------------------------------
 
 
+@overload
+def built_workflow(func: Callable[..., Awaitable[Any]]) -> FunctionalWorkflow: ...
+
+
+@overload
+def built_workflow(
+    *,
+    name: str | None = None,
+    description: str | None = None,
+    checkpoint_storage: CheckpointStorage | None = None,
+) -> Callable[[Callable[..., Awaitable[Any]]], FunctionalWorkflow]: ...
+
+
+def built_workflow(
+    func: Callable[..., Awaitable[Any]] | None = None,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+    checkpoint_storage: CheckpointStorage | None = None,
+) -> FunctionalWorkflow | Callable[[Callable[..., Awaitable[Any]]], FunctionalWorkflow]:
+    """Build a fresh executable workflow for behavior-focused tests."""
+
+    def decorate(fn: Callable[..., Awaitable[Any]]) -> FunctionalWorkflow:
+        return workflow(name=name, description=description)(fn).build(checkpoint_storage=checkpoint_storage)
+
+    return decorate(func) if func is not None else decorate
+
+
 @step
 async def add_one(x: int) -> int:
     return x + 1
@@ -69,7 +100,7 @@ async def failing_step(x: int) -> int:
 
 class TestBasicExecution:
     async def test_simple_sequential_pipeline(self):
-        @workflow
+        @built_workflow
         async def pipeline(x: int) -> int:
             a = await add_one(x)
             return await double(a)
@@ -80,7 +111,7 @@ class TestBasicExecution:
         assert outputs == [12]  # (5+1)*2
 
     async def test_workflow_with_string_data(self):
-        @workflow
+        @built_workflow
         async def upper_pipeline(text: str) -> str:
             return await to_upper(text)
 
@@ -88,7 +119,7 @@ class TestBasicExecution:
         assert result.get_outputs() == ["HELLO"]
 
     async def test_workflow_returns_result(self):
-        @workflow
+        @built_workflow
         async def simple(x: int) -> int:
             return await add_one(x)
 
@@ -96,14 +127,14 @@ class TestBasicExecution:
         assert result.get_outputs() == [11]
 
     async def test_workflow_name_defaults_to_function_name(self):
-        @workflow
+        @built_workflow
         async def my_pipeline(x: int) -> int:
             return x
 
         assert my_pipeline.name == "my_pipeline"
 
     async def test_workflow_custom_name(self):
-        @workflow(name="custom_wf", description="A test workflow")
+        @built_workflow(name="custom_wf", description="A test workflow")
         async def wf(x: int) -> int:
             return x
 
@@ -118,7 +149,7 @@ class TestBasicExecution:
 
 class TestEventEmission:
     async def test_step_events_emitted(self):
-        @workflow
+        @built_workflow
         async def pipeline(x: int) -> int:
             return await add_one(x)
 
@@ -129,7 +160,7 @@ class TestEventEmission:
         assert "output" in event_types
 
     async def test_step_events_carry_executor_id(self):
-        @workflow
+        @built_workflow
         async def pipeline(x: int) -> int:
             return await add_one(x)
 
@@ -144,7 +175,7 @@ class TestEventEmission:
         assert completed_events[0].data == 6
 
     async def test_status_events_in_timeline(self):
-        @workflow
+        @built_workflow
         async def pipeline(x: int) -> int:
             return x
 
@@ -154,7 +185,7 @@ class TestEventEmission:
         assert WorkflowRunState.IDLE in states
 
     async def test_final_state_is_idle(self):
-        @workflow
+        @built_workflow
         async def pipeline(x: int) -> int:
             return x
 
@@ -164,7 +195,7 @@ class TestEventEmission:
     async def test_custom_event(self):
         from agent_framework import WorkflowEvent
 
-        @workflow
+        @built_workflow
         async def pipeline(x: int, ctx: RunContext) -> int:
             await ctx.add_event(WorkflowEvent("intermediate", executor_id="pipeline", data="custom_data"))
             return x
@@ -192,7 +223,7 @@ class TestParallelExecution:
             await asyncio.sleep(0.01)
             return x * 2
 
-        @workflow
+        @built_workflow
         async def parallel_wf(x: int) -> list[int]:
             a, b = await asyncio.gather(slow_add(x), slow_double(x))
             return [a, b]
@@ -210,7 +241,7 @@ class TestParallelExecution:
         async def task_b(x: int) -> int:
             return x * 2
 
-        @workflow
+        @built_workflow
         async def par_wf(x: int) -> tuple[int, int]:
             a, b = await asyncio.gather(task_a(x), task_b(x))
             return (a, b)
@@ -228,8 +259,50 @@ class TestParallelExecution:
 
 
 class TestHITL:
-    async def test_request_info_interrupts(self):
+    async def test_workflow_definition_builds_isolated_pending_continuations(self):
         @workflow
+        async def review_wf(doc: str, ctx: RunContext) -> str:
+            feedback = await ctx.request_info(doc, response_type=str)
+            return f"{doc}:{feedback}"
+
+        assert not hasattr(review_wf, "run")
+
+        caller_a = review_wf.build()
+        caller_b = review_wf.build()
+
+        caller_a_paused = await caller_a.run("caller-a")
+        request_id = caller_a_paused.get_request_info_events()[0].request_id
+
+        with pytest.raises(ValueError, match="no pending request_info events"):
+            await caller_b.run(responses={request_id: "caller-b-response"})
+
+        caller_a_completed = await caller_a.run(responses={request_id: "caller-a-response"})
+        assert caller_a_completed.get_outputs() == ["caller-a:caller-a-response"]
+
+    async def test_build_does_not_inherit_checkpoint_storage_by_default(self):
+        @workflow
+        async def review_wf(doc: str) -> str:
+            return doc
+
+        caller = review_wf.build()
+
+        with pytest.raises(ValueError, match="checkpoint_storage"):
+            await caller.run(checkpoint_id="missing")
+
+    async def test_build_accepts_tenant_scoped_checkpoint_storage(self):
+        caller_storage = InMemoryCheckpointStorage()
+
+        @workflow
+        async def review_wf(doc: str, ctx: RunContext) -> str:
+            return await ctx.request_info(doc, response_type=str)
+
+        caller = review_wf.build(checkpoint_storage=caller_storage)
+        await caller.run("caller")
+
+        assert len(await caller_storage.list_checkpoints(workflow_name="review_wf")) == 1
+
+    async def test_request_info_interrupts(self):
+        @built_workflow
         async def review_wf(doc: str, ctx: RunContext) -> str:
             feedback = await ctx.request_info({"draft": doc}, response_type=str, request_id="req1")
             return f"Final: {feedback}"
@@ -242,7 +315,7 @@ class TestHITL:
         assert request_events[0].request_id == "req1"
 
     async def test_request_info_resume(self):
-        @workflow
+        @built_workflow
         async def review_wf(doc: str, ctx: RunContext) -> str:
             feedback = await ctx.request_info({"draft": doc}, response_type=str, request_id="req1")
             return f"Final: {feedback}"
@@ -260,7 +333,7 @@ class TestHITL:
     async def test_fresh_message_while_pending_requests_warns(self, caplog: pytest.LogCaptureFixture) -> None:
         """A fresh message while request_info events are pending is allowed but logs a warning."""
 
-        @workflow
+        @built_workflow
         async def review_wf(doc: str, ctx: RunContext) -> str:
             feedback = await ctx.request_info({"draft": doc}, response_type=str, request_id="req1")
             return f"Final: {feedback}"
@@ -279,7 +352,7 @@ class TestHITL:
     async def test_responses_while_pending_requests_does_not_warn(self, caplog: pytest.LogCaptureFixture) -> None:
         """Delivering responses is the normal completion path and must not warn."""
 
-        @workflow
+        @built_workflow
         async def review_wf(doc: str, ctx: RunContext) -> str:
             feedback = await ctx.request_info({"draft": doc}, response_type=str, request_id="req1")
             return f"Final: {feedback}"
@@ -297,7 +370,7 @@ class TestHITL:
     async def test_untyped_ctx_parameter(self):
         """ctx is injected by parameter name even without a RunContext annotation."""
 
-        @workflow  # pyright: ignore[reportUnknownArgumentType]
+        @built_workflow  # pyright: ignore[reportUnknownArgumentType]
         async def review_wf(doc: str, ctx) -> str:  # pyright: ignore[reportMissingParameterType, reportUnknownParameterType]
             feedback: str = await ctx.request_info({"draft": doc}, response_type=str, request_id="req1")  # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
             return f"Final: {feedback}"
@@ -309,7 +382,7 @@ class TestHITL:
         assert result2.get_outputs() == ["Final: LGTM"]
 
     async def test_multiple_sequential_interrupts(self):
-        @workflow
+        @built_workflow
         async def multi_hitl(data: str, ctx: RunContext) -> str:
             r1 = await ctx.request_info("step1", response_type=str, request_id="r1")
             r2 = await ctx.request_info("step2", response_type=str, request_id="r2")
@@ -330,7 +403,7 @@ class TestHITL:
         assert result3.get_outputs() == ["A+B"]
 
     async def test_request_info_auto_generates_id(self):
-        @workflow
+        @built_workflow
         async def auto_id_wf(x: int, ctx: RunContext) -> None:
             await ctx.request_info("need data", response_type=str)
 
@@ -347,7 +420,7 @@ class TestHITL:
 
 class TestErrorHandling:
     async def test_step_failure_propagates(self):
-        @workflow
+        @built_workflow
         async def failing_wf(x: int) -> None:
             await failing_step(x)
 
@@ -355,7 +428,7 @@ class TestErrorHandling:
             await failing_wf.run(42)
 
     async def test_step_failure_emits_executor_failed(self):
-        @workflow
+        @built_workflow
         async def failing_wf(x: int) -> None:
             await failing_step(x)
 
@@ -371,7 +444,7 @@ class TestErrorHandling:
         assert failed_events[0].executor_id == "failing_step"
 
     async def test_workflow_failure_emits_failed_status(self):
-        @workflow
+        @built_workflow
         async def bad_wf(x: int) -> None:
             raise RuntimeError("workflow broke")
 
@@ -387,7 +460,7 @@ class TestErrorHandling:
         assert any(e.state == WorkflowRunState.FAILED for e in status_events)
 
     async def test_invalid_params_message_and_responses(self):
-        @workflow
+        @built_workflow
         async def wf(x: int) -> None:
             pass
 
@@ -395,7 +468,7 @@ class TestErrorHandling:
             await wf.run("hello", responses={"r1": "val"})
 
     async def test_invalid_params_message_and_checkpoint(self):
-        @workflow
+        @built_workflow
         async def wf(x: int) -> None:
             pass
 
@@ -403,7 +476,7 @@ class TestErrorHandling:
             await wf.run("hello", checkpoint_id="abc")
 
     async def test_invalid_params_nothing(self):
-        @workflow
+        @built_workflow
         async def wf(x: int) -> None:
             pass
 
@@ -418,7 +491,7 @@ class TestErrorHandling:
 
 class TestStreaming:
     async def test_streaming_yields_events(self):
-        @workflow
+        @built_workflow
         async def pipeline(x: int) -> int:
             return await add_one(x)
 
@@ -434,7 +507,7 @@ class TestStreaming:
         assert "output" in event_types
 
     async def test_streaming_final_response(self):
-        @workflow
+        @built_workflow
         async def pipeline(x: int) -> int:
             return await add_one(x)
 
@@ -446,7 +519,7 @@ class TestStreaming:
     async def test_streaming_context_reports_streaming(self):
         streaming_flag = None
 
-        @workflow
+        @built_workflow
         async def wf(x: int, ctx: RunContext) -> int:
             nonlocal streaming_flag
             streaming_flag = ctx.is_streaming()  # type: ignore[assignment]
@@ -491,7 +564,7 @@ class TestStepPassthrough:
 
 class TestStateManagement:
     async def test_get_set_state(self):
-        @workflow
+        @built_workflow
         async def stateful_wf(x: int, ctx: RunContext) -> int:
             ctx.set_state("counter", x)
             return ctx.get_state("counter")
@@ -500,7 +573,7 @@ class TestStateManagement:
         assert result.get_outputs() == [42]
 
     async def test_get_state_default(self):
-        @workflow
+        @built_workflow
         async def wf(x: int, ctx: RunContext) -> str:
             return ctx.get_state("missing", "default_val")
 
@@ -521,7 +594,7 @@ class TestCheckpointing:
         async def expensive(x: int) -> int:
             return x * 100
 
-        @workflow(checkpoint_storage=storage)
+        @built_workflow(checkpoint_storage=storage)
         async def ckpt_wf(x: int) -> int:
             return await expensive(x)
 
@@ -539,7 +612,7 @@ class TestCheckpointing:
         async def compute(x: int) -> int:
             return x + 1
 
-        @workflow
+        @built_workflow
         async def wf(x: int) -> int:
             return await compute(x)
 
@@ -559,7 +632,7 @@ class TestCheckpointing:
             call_count += 1
             return x + 1
 
-        @workflow(checkpoint_storage=storage)
+        @built_workflow(checkpoint_storage=storage)
         async def wf(x: int) -> int:
             return await counting_task(x)
 
@@ -580,7 +653,7 @@ class TestCheckpointing:
     async def test_checkpoint_hitl_resume(self):
         storage = InMemoryCheckpointStorage()
 
-        @workflow(checkpoint_storage=storage)
+        @built_workflow(checkpoint_storage=storage)
         async def hitl_wf(doc: str, ctx: RunContext) -> str:
             feedback = await ctx.request_info({"draft": doc}, response_type=str, request_id="req1")
             return f"Done: {feedback}"
@@ -598,7 +671,7 @@ class TestCheckpointing:
         assert result2.get_outputs() == ["Done: Approved!"]
 
     async def test_checkpoint_without_storage_raises(self):
-        @workflow
+        @built_workflow
         async def wf(x: int) -> int:
             return x
 
@@ -608,7 +681,7 @@ class TestCheckpointing:
     async def test_checkpoint_preserves_state(self):
         storage = InMemoryCheckpointStorage()
 
-        @workflow(checkpoint_storage=storage)
+        @built_workflow(checkpoint_storage=storage)
         async def stateful_wf(x: int, ctx: RunContext) -> str:
             ctx.set_state("key", "value")
             feedback = await ctx.request_info("need info", response_type=str, request_id="r1")
@@ -648,7 +721,7 @@ class TestCheckpointing:
                 raise RuntimeError("simulated crash")
             return x * 2
 
-        @workflow(checkpoint_storage=storage)
+        @built_workflow(checkpoint_storage=storage)
         async def crash_wf(x: int) -> int:
             a = await slow_step1(x)
             return await crashing_step2(a)
@@ -687,7 +760,7 @@ class TestCheckpointing:
         async def s3(x: int) -> int:
             return x + 3
 
-        @workflow(checkpoint_storage=storage)
+        @built_workflow(checkpoint_storage=storage)
         async def multi_step_wf(x: int) -> int:
             a = await s1(x)
             b = await s2(a)
@@ -708,7 +781,7 @@ class TestCheckpointing:
         async def compute(x: int) -> int:
             return x + 1
 
-        @workflow(checkpoint_storage=storage)
+        @built_workflow(checkpoint_storage=storage)
         async def wf(x: int) -> int:
             return await compute(x)
 
@@ -748,7 +821,7 @@ class TestControlFlow:
         async def quarantine(text: str) -> str:
             return f"quarantined: {text}"
 
-        @workflow
+        @built_workflow
         async def email_pipeline(email: str) -> str:
             cl = await classify(email)
             if cl.is_spam:
@@ -775,7 +848,7 @@ class TestNestedWorkflows:
         async def step_a(x: int) -> int:
             return x + 1
 
-        @workflow
+        @built_workflow
         async def inner_wf(x: int) -> int:
             return await step_a(x)
 
@@ -784,7 +857,7 @@ class TestNestedWorkflows:
             result = await inner_wf.run(x)
             return result.get_outputs()[0]
 
-        @workflow
+        @built_workflow
         async def outer_wf(x: int) -> int:
             return await call_inner(x)
 
@@ -799,7 +872,7 @@ class TestNestedWorkflows:
 
 class TestAsAgent:
     async def test_as_agent_returns_agent(self):
-        @workflow
+        @built_workflow
         async def wf(x: int) -> str:
             return f"result: {x}"
 
@@ -807,7 +880,7 @@ class TestAsAgent:
         assert agent.name == "wf"
 
     async def test_as_agent_custom_name(self):
-        @workflow
+        @built_workflow
         async def wf(x: int) -> int:
             return x
 
@@ -815,7 +888,7 @@ class TestAsAgent:
         assert agent.name == "my_agent"
 
     async def test_as_agent_run(self):
-        @workflow
+        @built_workflow
         async def wf(x: int) -> int:
             return await add_one(x)
 
@@ -824,7 +897,7 @@ class TestAsAgent:
         assert response.text == "11"
 
     async def test_as_agent_run_streaming(self):
-        @workflow
+        @built_workflow
         async def wf(x: int) -> str:
             return f"result: {x}"
 
@@ -840,7 +913,7 @@ class TestAsAgent:
         assert len(response.messages) >= 1
 
     async def test_as_agent_has_id_and_description(self):
-        @workflow(description="A test workflow")
+        @built_workflow(description="A test workflow")
         async def wf(x: int) -> int:
             return x
 
@@ -856,7 +929,7 @@ class TestAsAgent:
 
 class TestConcurrencyGuard:
     async def test_concurrent_run_raises(self):
-        @workflow
+        @built_workflow
         async def slow_wf(x: int) -> int:
             await asyncio.sleep(0.1)
             return x
@@ -872,7 +945,7 @@ class TestConcurrencyGuard:
         await stream.get_final_response()
 
     async def test_run_after_completion(self):
-        @workflow
+        @built_workflow
         async def wf(x: int) -> int:
             return x
 
@@ -911,7 +984,7 @@ class TestDecoratorForms:
         async def my_wf(x: int) -> None:
             pass
 
-        assert isinstance(my_wf, FunctionalWorkflow)
+        assert isinstance(my_wf, FunctionalWorkflowDefinition)
         assert my_wf.name == "my_wf"
 
     def test_workflow_with_params(self):
@@ -919,7 +992,7 @@ class TestDecoratorForms:
         async def my_wf(x: int) -> None:
             pass
 
-        assert isinstance(my_wf, FunctionalWorkflow)
+        assert isinstance(my_wf, FunctionalWorkflowDefinition)
         assert my_wf.name == "custom"
         assert my_wf.description == "desc"
 
@@ -931,7 +1004,7 @@ class TestDecoratorForms:
 
 class TestIncludeStatusEvents:
     async def test_status_events_excluded_by_default(self):
-        @workflow
+        @built_workflow
         async def wf(x: int) -> int:
             return x
 
@@ -940,7 +1013,7 @@ class TestIncludeStatusEvents:
         assert len(status_in_list) == 0
 
     async def test_status_events_included_when_requested(self):
-        @workflow
+        @built_workflow
         async def wf(x: int) -> int:
             return x
 
@@ -956,7 +1029,7 @@ class TestIncludeStatusEvents:
 
 class TestEdgeCases:
     async def test_workflow_with_no_tasks(self):
-        @workflow
+        @built_workflow
         async def no_tasks(x: int) -> int:
             return x * 2
 
@@ -964,7 +1037,7 @@ class TestEdgeCases:
         assert result.get_outputs() == [10]
 
     async def test_workflow_with_no_output(self):
-        @workflow
+        @built_workflow
         async def silent_wf(x: int) -> None:
             pass  # returns None — no output emitted
 
@@ -974,7 +1047,7 @@ class TestEdgeCases:
     async def test_return_value_auto_yields_output(self):
         """Returning a non-None value automatically emits it as an output."""
 
-        @workflow
+        @built_workflow
         async def wf(x: int) -> int:
             return x * 3
 
@@ -982,7 +1055,7 @@ class TestEdgeCases:
         assert result.get_outputs() == [15]
 
     async def test_step_called_multiple_times(self):
-        @workflow
+        @built_workflow
         async def wf(x: int) -> int:
             a = await add_one(x)
             b = await add_one(a)
@@ -1005,7 +1078,7 @@ class TestEdgeCases:
 
 class TestRecoveryAfterErrors:
     async def test_run_after_failure_is_allowed(self):
-        @workflow
+        @built_workflow
         async def wf(x: int) -> int:
             if x == 1:
                 raise RuntimeError("boom")
@@ -1036,7 +1109,7 @@ class TestWorkflowInterruptedIsBaseException:
         """User code with ``except Exception`` should not catch WorkflowInterrupted."""
         caught = False
 
-        @workflow
+        @built_workflow
         async def wf(x: int, ctx: RunContext) -> str:
             nonlocal caught
             try:
@@ -1064,7 +1137,7 @@ class TestCheckpointValidation:
 
         storage = InMemoryCheckpointStorage()
 
-        @workflow(name="my_wf", checkpoint_storage=storage)
+        @built_workflow(name="my_wf", checkpoint_storage=storage)
         async def wf(x: int) -> int:
             return x
 
@@ -1108,7 +1181,7 @@ class TestExecutorBypassed:
             call_count += 1
             return x + 1
 
-        @workflow(checkpoint_storage=storage)
+        @built_workflow(checkpoint_storage=storage)
         async def wf(x: int) -> int:
             return await tracked(x)
 
@@ -1141,7 +1214,7 @@ class TestExecutorBypassed:
         async def compute(x: int) -> int:
             return x * 10
 
-        @workflow(checkpoint_storage=storage)
+        @built_workflow(checkpoint_storage=storage)
         async def wf(x: int) -> int:
             return await compute(x)
 
@@ -1169,7 +1242,7 @@ class TestRequestInfoInStep:
             feedback = await ctx.request_info({"draft": doc}, response_type=str, request_id="s1")
             return f"reviewed: {feedback}"
 
-        @workflow
+        @built_workflow
         async def wf(doc: str) -> str:
             return await review_step(doc)
 
@@ -1205,7 +1278,7 @@ class TestRequestInfoInStep:
             ctx.set_state("seen", data)
             return f"{data}:{ctx.get_state('seen')}"
 
-        @workflow
+        @built_workflow
         async def wf(data: str) -> str:
             return await needs_ctx_first(data)
 
@@ -1225,7 +1298,7 @@ class TestRequestInfoInStep:
             captured_ctx = get_run_context()  # type: ignore[assignment]
             return x
 
-        @workflow
+        @built_workflow
         async def wf(x: int) -> int:
             return await capture_ctx(x)
 
@@ -1249,7 +1322,7 @@ class TestNoneResponseHandling:
     async def test_none_response_logs_warning(self):
         """Providing None as a response value should log a warning."""
 
-        @workflow
+        @built_workflow
         async def wf(doc: str, ctx: RunContext) -> str:
             val = await ctx.request_info("need input", response_type=str, request_id="r1")
             return f"got: {val}"
@@ -1267,7 +1340,7 @@ class TestNoneResponseHandling:
     async def test_none_response_is_returned(self):
         """None is a valid (if discouraged) response value."""
 
-        @workflow
+        @built_workflow
         async def wf(x: int, ctx: RunContext) -> str:
             val = await ctx.request_info("need data", response_type=str, request_id="r1")
             return f"value={val}"
@@ -1322,7 +1395,7 @@ class TestHITLInStepWithCaching:
             feedback = await ctx.request_info({"val": val}, response_type=str, request_id="r1")
             return f"{val}:{feedback}"
 
-        @workflow
+        @built_workflow
         async def wf(x: int) -> str:
             a = await step_a(x)
             return await step_b(a)
@@ -1353,7 +1426,7 @@ class TestHITLInStepWithCaching:
             feedback = await ctx.request_info({"val": val}, response_type=str, request_id="rev")
             return f"reviewed({val}):{feedback}"
 
-        @workflow(checkpoint_storage=storage)
+        @built_workflow(checkpoint_storage=storage)
         async def wf(x: int) -> str:
             v = await compute(x)
             return await review(v)
@@ -1384,7 +1457,7 @@ class TestHITLInStepWithCaching:
             val = await ctx.request_info({"doc": doc}, response_type=str, request_id="r1")
             return f"got:{val}"
 
-        @workflow
+        @built_workflow
         async def wf(doc: str) -> str:
             return await needs_feedback(doc)
 
@@ -1403,7 +1476,7 @@ class TestHITLInStepWithCaching:
         async def hitl_step(x: int, ctx: RunContext) -> str:
             return await ctx.request_info("need data", response_type=str, request_id="r1")
 
-        @workflow
+        @built_workflow
         async def wf(x: int) -> str:
             return await hitl_step(x)
 
@@ -1422,7 +1495,7 @@ class TestDeterministicAutoRequestId:
     """Regression for bug_001: auto-generated request_info ids must be stable across replay."""
 
     async def test_auto_request_id_roundtrips_on_resume(self):
-        @workflow
+        @built_workflow
         async def wf(x: int, ctx: RunContext) -> str:
             # No request_id — framework must generate a deterministic one
             val = await ctx.request_info("need data", response_type=str)
@@ -1441,7 +1514,7 @@ class TestDeterministicAutoRequestId:
         assert result2.get_outputs() == ["got:hello"]
 
     async def test_multiple_auto_ids_are_distinct_and_stable(self):
-        @workflow
+        @built_workflow
         async def wf(x: int, ctx: RunContext) -> str:
             a = await ctx.request_info("first", response_type=str)
             b = await ctx.request_info("second", response_type=str)
@@ -1468,7 +1541,7 @@ class TestDeterministicAutoRequestId:
         async def second_review(value: int, ctx: RunContext) -> str:
             return await ctx.request_info({"step": "second", "value": value}, response_type=str)
 
-        @workflow
+        @built_workflow
         async def wf(value: int) -> str:
             first = await first_review(value)
             second = await second_review(value)
@@ -1495,7 +1568,7 @@ class TestPendingRequestsPruned:
     async def test_final_checkpoint_no_longer_claims_resolved_requests_pending(self):
         storage = InMemoryCheckpointStorage()
 
-        @workflow(checkpoint_storage=storage)
+        @built_workflow(checkpoint_storage=storage)
         async def wf(x: int, ctx: RunContext) -> str:
             a = await ctx.request_info("q1", response_type=str, request_id="r1")
             b = await ctx.request_info("q2", response_type=str, request_id="r2")
@@ -1523,7 +1596,7 @@ class TestArityValidation:
                 return f"{a}+{b}"
 
     async def test_ctx_only_workflow_with_message_raises_clear_error(self):
-        @workflow
+        @built_workflow
         async def wf(ctx: RunContext) -> str:
             return "no message used"
 
@@ -1535,7 +1608,7 @@ class TestArityValidation:
         # message-receiving parameter.  (Running it without a message still
         # requires providing responses or a checkpoint_id — that's
         # _validate_run_params's job, not ours.)
-        @workflow
+        @built_workflow
         async def wf(ctx: RunContext) -> str:
             return "ok"
 
@@ -1546,7 +1619,7 @@ class TestStaleResponsesRejected:
     """Regression for bug_014: stale responses after clean completion must be rejected."""
 
     async def test_responses_after_clean_completion_raise(self):
-        @workflow
+        @built_workflow
         async def wf(x: int) -> int:
             return x * 2
 
@@ -1555,7 +1628,7 @@ class TestStaleResponsesRejected:
             await wf.run(responses={"stale": "x"})
 
     async def test_responses_mismatched_key_raises(self):
-        @workflow
+        @built_workflow
         async def wf(x: int, ctx: RunContext) -> str:
             return await ctx.request_info("q", response_type=str, request_id="r1")
 
@@ -1568,7 +1641,7 @@ class TestReservedStateKeys:
     """Regression for bug_017: set_state must reject underscore-prefixed keys."""
 
     async def test_underscore_key_rejected(self):
-        @workflow
+        @built_workflow
         async def wf(x: int, ctx: RunContext) -> int:
             ctx.set_state("_private", "user value")
             return x
@@ -1577,7 +1650,7 @@ class TestReservedStateKeys:
             await wf.run(1)
 
     async def test_normal_key_still_works(self):
-        @workflow
+        @built_workflow
         async def wf(x: int, ctx: RunContext) -> int:
             ctx.set_state("normal_key", "v")
             assert ctx.get_state("normal_key") == "v"
@@ -1597,7 +1670,7 @@ class TestDeepcopyOnCacheHit:
         async def takes_lock(lock: threading.Lock, n: int) -> int:
             return n + 1
 
-        @workflow
+        @built_workflow
         async def wf(x: int) -> int:
             lock = threading.Lock()
             return await takes_lock(lock, x)
@@ -1613,11 +1686,11 @@ class TestStepDiscoveryAttributeAccess:
     """Regression for bug_008: checkpoint hash must differ when function body changes."""
 
     async def test_signature_hash_changes_when_function_body_changes(self):
-        @workflow
+        @built_workflow
         async def wf_a(x: int) -> int:
             return x + 1
 
-        @workflow(name="wf_b")
+        @built_workflow(name="wf_b")
         async def wf_b(x: int) -> int:
             return x * 100
 
@@ -1630,7 +1703,7 @@ class TestAsAgentSignatureParity:
     """Regression for bug_015: as_agent signature must accept description/context_providers."""
 
     async def test_as_agent_accepts_description_override(self):
-        @workflow(description="workflow level")
+        @built_workflow(description="workflow level")
         async def wf(x: str) -> str:
             return x.upper()
 
@@ -1638,7 +1711,7 @@ class TestAsAgentSignatureParity:
         assert agent.description == "agent level"
 
     async def test_as_agent_accepts_context_providers_kwarg(self):
-        @workflow
+        @built_workflow
         async def wf(x: str) -> str:
             return x
 
@@ -1647,7 +1720,7 @@ class TestAsAgentSignatureParity:
         assert list(agent.context_providers or []) == providers
 
     async def test_as_agent_description_defaults_to_workflow_description(self):
-        @workflow(description="from workflow")
+        @built_workflow(description="from workflow")
         async def wf(x: str) -> str:
             return x
 
@@ -1659,7 +1732,7 @@ class TestFunctionalWorkflowAgentHITL:
     """Regression for bug_013: .as_agent() must surface request_info events."""
 
     async def test_request_info_surfaces_as_function_approval_request(self):
-        @workflow
+        @built_workflow
         async def wf(x: str, ctx: RunContext) -> str:
             answer = await ctx.request_info({"need": x}, response_type=str, request_id="rid-1")
             return f"got:{answer}"
@@ -1686,7 +1759,7 @@ class TestFunctionalWorkflowAgentHITL:
             target_agent: str
             reason: str
 
-        @workflow
+        @built_workflow
         async def wf(x: str, ctx: RunContext) -> str:
             answer = await ctx.request_info(
                 HandoffRequest(target_agent=x, reason="overflow"),
@@ -1712,7 +1785,7 @@ class TestFunctionalWorkflowAgentHITL:
         assert json.loads(json.dumps(function_call_arguments)) == function_call_arguments
 
     async def test_resume_via_agent_responses_kwarg(self):
-        @workflow
+        @built_workflow
         async def wf(x: str, ctx: RunContext) -> str:
             answer = await ctx.request_info(x, response_type=str, request_id="rid-1")
             return f"got:{answer}"
@@ -1751,6 +1824,7 @@ class TestFunctionalWorkflowExperimentalStage:
             StepWrapper,
             step,
             FunctionalWorkflow,
+            FunctionalWorkflowDefinition,
             workflow,
             FunctionalWorkflowAgent,
         ]

python/packages/core/tests/workflow/test_request_info_event_rehydrate.py

@@ -1,8 +1,12 @@
 # Copyright (c) Microsoft. All rights reserved.
 
 import json
+import sys
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
+from pathlib import Path
+
+import pytest
 
 from agent_framework import (
     FileCheckpointStorage,
@@ -47,6 +51,91 @@ class TimedApproval:
     issued_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
 
 
+def test_workflow_event_from_dict_accepts_explicit_allowed_types() -> None:
+    """Request-info reconstruction accepts exact trusted custom types."""
+
+    @dataclass
+    class ExplicitRequest:
+        prompt: str
+
+    class ExplicitResponse:
+        pass
+
+    request_type_name = f"{ExplicitRequest.__module__}.{ExplicitRequest.__qualname__}"
+    response_type_name = f"{ExplicitResponse.__module__}.{ExplicitResponse.__qualname__}"
+    event = WorkflowEvent.from_dict(
+        {
+            "type": "request_info",
+            "data": ExplicitRequest(prompt="Approve?"),
+            "request_id": "request-123",
+            "source_executor_id": "review_gateway",
+            "request_type": request_type_name,
+            "response_type": response_type_name,
+        },
+        allowed_types={
+            request_type_name: ExplicitRequest,
+            response_type_name: ExplicitResponse,
+        },
+    )
+
+    assert type(event.data) is ExplicitRequest
+    assert event.request_type is ExplicitRequest
+    assert event.response_type is ExplicitResponse
+
+
+def _write_observable_type_module(tmp_path: Path, module_name: str) -> Path:
+    marker_path = tmp_path / f"{module_name}.imported"
+    module_path = tmp_path / f"{module_name}.py"
+    module_path.write_text(f"from pathlib import Path\nPath({str(marker_path)!r}).touch()\nclass Attack:\n    pass\n")
+    return marker_path
+
+
+def test_workflow_event_from_dict_does_not_import_request_type(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A request-type name cannot cause its module to be imported."""
+    module_name = "_request_info_untrusted_request_type"
+    marker_path = _write_observable_type_module(tmp_path, module_name)
+    monkeypatch.syspath_prepend(str(tmp_path))
+
+    with pytest.raises(ModuleNotFoundError, match=f"No module named '{module_name}'"):
+        WorkflowEvent.from_dict({
+            "type": "request_info",
+            "data": "Approve?",
+            "request_id": "request-123",
+            "source_executor_id": "review_gateway",
+            "request_type": f"{module_name}.Attack",
+            "response_type": "builtins.bool",
+        })
+
+    assert module_name not in sys.modules
+    assert not marker_path.exists()
+
+
+def test_workflow_event_from_dict_does_not_import_response_type(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A response-type name cannot cause its module to be imported."""
+    module_name = "_request_info_untrusted_response_type"
+    marker_path = _write_observable_type_module(tmp_path, module_name)
+    monkeypatch.syspath_prepend(str(tmp_path))
+
+    with pytest.raises(ModuleNotFoundError, match=f"No module named '{module_name}'"):
+        WorkflowEvent.from_dict({
+            "type": "request_info",
+            "data": "Approve?",
+            "request_id": "request-123",
+            "source_executor_id": "review_gateway",
+            "request_type": "builtins.str",
+            "response_type": f"{module_name}.Attack",
+        })
+
+    assert module_name not in sys.modules
+    assert not marker_path.exists()
+
+
 async def test_rehydrate_request_info_event() -> None:
     """Rehydration should succeed for valid request info events."""
     request_info_event = WorkflowEvent.request_info(

python/packages/core/tests/workflow/test_typing_utils.py

@@ -1,7 +1,11 @@
 # Copyright (c) Microsoft. All rights reserved.
 
+import importlib
+import sys
 from dataclasses import dataclass
+from types import ModuleType
 from typing import Any, Generic, Optional, TypeVar, Union
+from unittest.mock import Mock
 
 import pytest
 
@@ -337,6 +341,52 @@ def test_deserialize_type_error_handling() -> None:
         deserialize_type("builtins.NonExistentType")
 
 
+def test_deserialize_type_does_not_import_unknown_module(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Unknown serialized types fail without importing payload-selected modules."""
+    imported_modules: list[str] = []
+
+    def fail_import(module_name: str) -> None:
+        imported_modules.append(module_name)
+        raise AssertionError("deserialize_type must not import payload-selected modules")
+
+    monkeypatch.setattr(importlib, "import_module", fail_import)
+
+    with pytest.raises(ModuleNotFoundError, match="No module named 'untrusted_request_info_payload'"):
+        deserialize_type("untrusted_request_info_payload.Attack")
+
+    assert imported_modules == []
+
+
+def test_deserialize_type_accepts_explicit_allowed_type() -> None:
+    """Callers can resolve an exact trusted custom type without importing its module."""
+
+    class ExplicitType:
+        pass
+
+    serialized_name = f"{ExplicitType.__module__}.{ExplicitType.__qualname__}"
+
+    assert deserialize_type(serialized_name, allowed_types={serialized_name: ExplicitType}) is ExplicitType
+
+
+def test_deserialize_type_rejects_spoofed_allowed_type() -> None:
+    """Allowed values must be actual class objects, not objects spoofing ``type``."""
+    spoofed_type = Mock(spec=type)
+
+    with pytest.raises(TypeError, match="must be a type"):
+        deserialize_type("spoofed.Type", allowed_types={"spoofed.Type": spoofed_type})  # type: ignore[dict-item]
+
+
+def test_deserialize_type_rejects_spoofed_loaded_type(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Loaded namespace values must be actual class objects."""
+    module_name = "_spoofed_request_info_type"
+    module = ModuleType(module_name)
+    module.__dict__["Spoofed"] = Mock(spec=type)
+    monkeypatch.setitem(sys.modules, module_name, module)
+
+    with pytest.raises(TypeError, match="does not resolve to a type"):
+        deserialize_type(f"{module_name}.Spoofed")
+
+
 def test_type_compatibility_basic() -> None:
     """Test basic type compatibility scenarios."""
     # Exact type match

python/packages/core/tests/workflow/test_workflow_agent.py

@@ -335,6 +335,32 @@ class TestWorkflowAgent:
         assert deserialized_args.request_event.data == HandoffRequest(target_agent="helper", reason="overflow")
         assert deserialized_args.request_event.response_type is str
 
+    def test_request_info_function_args_from_dict_accepts_explicit_allowed_types(self) -> None:
+        """Envelope reconstruction forwards exact trusted custom types."""
+
+        @dataclass
+        class ExplicitRequest:
+            prompt: str
+
+        serialized_name = f"{ExplicitRequest.__module__}.{ExplicitRequest.__qualname__}"
+        args = WorkflowAgent.RequestInfoFunctionArgs.from_dict(
+            {
+                "request_id": "request-123",
+                "request_event": {
+                    "type": "request_info",
+                    "data": ExplicitRequest(prompt="Approve?"),
+                    "request_id": "request-123",
+                    "source_executor_id": "review_gateway",
+                    "request_type": serialized_name,
+                    "response_type": "builtins.bool",
+                },
+            },
+            allowed_types={serialized_name: ExplicitRequest},
+        )
+
+        assert type(args.request_event.data) is ExplicitRequest
+        assert args.request_event.response_type is bool
+
     def test_process_request_info_event_passes_through_function_approval_request(self) -> None:
         """If the event data is already a function approval request, it is forwarded unchanged.