From 3b82252a9f9aa87c228edfe69606de0dc583070f Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 09:34:05 +0100 Subject: [PATCH 01/55] Fix Responses route prefix handling --- .../_responses_workflow.py | 5 ++- .../foundry_hosting/test_native_responses.py | 21 +++++++++--- .../foundry_hosting/tests/test_responses.py | 34 +++++++++++++++++++ 3 files changed, 55 insertions(+), 5 deletions(-) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py index 31f148331df..56198c37041 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py @@ -413,7 +413,10 @@ def __init__( def _bind_streaming_route(self, *, prefix: str, keep_alive: bool) -> None: """Adapt only the native POST route's public StreamingResponse cleanup lifetime.""" - path = f"/{prefix.strip('/')}/responses" if prefix.strip("/") else "/responses" + normalized_prefix = prefix.strip() + if normalized_prefix and not normalized_prefix.startswith("/"): + normalized_prefix = f"/{normalized_prefix}" + path = f"{normalized_prefix.rstrip('/')}/responses" for index, route in enumerate(self.router.routes): if not isinstance(route, Route) or route.path != path or "POST" not in (route.methods or ()): continue diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py index 14d9b1f11d3..ac85b057754 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py @@ -510,10 +510,23 @@ def create(request: ResponsesRequest) -> Workflow: @pytest.mark.parametrize("stream", [False, True]) -async def test_workflow_host_prefix_preserves_create_and_retrieval_routes(stream: bool) -> None: - server = _server(prefix="api/v1") +@pytest.mark.parametrize( + ("prefix", "path"), + [ + ("api/v1", "/api/v1"), + (" /api/v1/ ", "/api/v1"), + ("//api/v1/", "//api/v1"), + (" / ", ""), + ], +) +async def test_workflow_host_prefix_preserves_create_and_retrieval_routes( + stream: bool, prefix: str, path: str +) -> None: + server = _server(prefix=prefix) async with httpx.AsyncClient(transport=httpx.ASGITransport(app=server), base_url="http://test") as client: - created = await client.post("/api/v1/responses", json={"input": '{"text":"prefixed"}', "stream": stream}) + created = await client.post( + f"http://test{path}/responses", json={"input": '{"text":"prefixed"}', "stream": stream} + ) assert created.status_code == 200 if stream: events = [json.loads(line[6:]) for line in created.text.splitlines() if line.startswith("data: {")] @@ -522,7 +535,7 @@ async def test_workflow_host_prefix_preserves_create_and_retrieval_routes(stream result = created.json() assert result["status"] == "completed", result assert result["output"][0]["output"] == {"text": "prefixed", "count": 1} - stored = await client.get(f"/api/v1/responses/{result['id']}") + stored = await client.get(f"http://test{path}/responses/{result['id']}") assert stored.status_code == 200 assert stored.json()["output"] == result["output"] diff --git a/python/packages/foundry_hosting/tests/test_responses.py b/python/packages/foundry_hosting/tests/test_responses.py index 04ae6bc1a38..2b59556a643 100644 --- a/python/packages/foundry_hosting/tests/test_responses.py +++ b/python/packages/foundry_hosting/tests/test_responses.py @@ -1345,6 +1345,40 @@ def _sse_event_types(events: list[dict[str, Any]]) -> list[str]: # region Serialization Helpers +@pytest.mark.parametrize("stream", [False, True]) +async def test_agent_host_prefix_preserves_response_routes(stream: bool) -> None: + agent = _make_agent( + response=AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("Prefixed")])]) + ) + server = _make_server(agent, prefix="api/v1") + + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=server), base_url="http://test") as client: + created = await client.post("/api/v1/responses", json={"input": "hello", "stream": stream, "store": True}) + assert created.status_code == 200, created.text + if stream: + result = next( + event["data"]["response"] + for event in _parse_sse_events(created.text) + if event["event"] == "response.completed" + ) + else: + result = created.json() + assert result["status"] == "completed" + response_id = result["id"] + + stored = await client.get(f"/api/v1/responses/{response_id}") + assert stored.status_code == 200, stored.text + assert stored.json()["output"] == result["output"] + + inputs = await client.get(f"/api/v1/responses/{response_id}/input_items") + assert inputs.status_code == 200, inputs.text + assert inputs.json()["data"] + + deleted = await client.delete(f"/api/v1/responses/{response_id}") + assert deleted.status_code == 200, deleted.text + assert (await client.get(f"/api/v1/responses/{response_id}")).status_code == 404 + + @pytest.mark.parametrize("stream", [False, True]) @pytest.mark.parametrize("metadata", [None, {}, {"foo": "bar", "view": "concise"}]) async def test_request_metadata_is_returned_and_stored(stream: bool, metadata: dict[str, str] | None) -> None: From e76e87e6de2aca3b37c0614450fc7f30768d7a0b Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 09:34:44 +0100 Subject: [PATCH 02/55] Harden Foundry host settings and option boundaries --- .../_invocations_agent.py | 16 +- .../_invocations_shared.py | 38 ++- .../_invocations_workflow.py | 9 +- .../_shared.py | 147 ++++++++- .../tests/foundry_hosting/options_helpers.py | 85 +++++ .../foundry_hosting/test_host_options.py | 311 ++++++++++++++++++ .../foundry_hosting/tests/test_request.py | 11 +- 7 files changed, 601 insertions(+), 16 deletions(-) create mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/options_helpers.py create mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py index 5a55661ac97..1f3ca218cef 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py @@ -31,6 +31,7 @@ def __init__( prepare_options: InvocationOptionsHook | None = None, unsupported_options: UnsupportedOptions = "warn", legacy_wire_format: bool = False, + sse_keep_alive_interval_seconds: int | None = None, **kwargs: Any, ) -> None: """Create an agent host with session-backed application turns. @@ -51,13 +52,23 @@ def __init__( parse_input: Sync or async parser returning `InvocationRun`. Without a parser, accept JSON `message`, optional `options`, and `stream`. prepare_options: Sync or async hook receiving the request and a copy of caller generation - options. Return the replacement mapping; hosting validates it before agent dispatch. + options, for streaming and non-streaming requests. Return the replacement mapping. + Hosting validates protected fields after the hook and before resolving the factory, + unlike Responses factories which run before the hook. Removing a caller ``model`` + retains the agent/client inference default. Defaults are not mutated. unsupported_options: Policy for agents without runtime options: `"warn"`, `"ignore"`, or `"error"`. legacy_wire_format: Deprecated agent-only plain-text and raw-stream compatibility format. + Heartbeats are disabled in this format to avoid inserting SSE comments into raw text. + sse_keep_alive_interval_seconds: Positive streaming heartbeat interval. If omitted, use a positive + `SSE_KEEPALIVE_INTERVAL`, otherwise disable heartbeats. Not a request/model timeout. + An explicit interval cannot be combined with `legacy_wire_format=True`. **kwargs: Additional AgentServer host settings forwarded to the SDK. Raises: - TypeError: If the agent source or parser/hook is invalid, or native workflow settings are supplied. + TypeError: If the agent source, parser/hook, or heartbeat type is invalid, or removed, + Responses-only, or native workflow settings are supplied. + ValueError: If the heartbeat interval is nonpositive, raw legacy output requests heartbeats, + or an injected agent has unsupported background or transport defaults. """ if {"workflow", "checkpoint_store_provider"}.intersection(kwargs): raise TypeError("Use InvocationsWorkflowHostServer for native workflows and checkpoint storage.") @@ -69,5 +80,6 @@ def __init__( prepare_options=prepare_options, unsupported_options=unsupported_options, legacy_wire_format=legacy_wire_format, + sse_keep_alive_interval_seconds=sse_keep_alive_interval_seconds, **kwargs, ) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py index 98f5a5de3d7..2ada5429227 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py @@ -27,6 +27,7 @@ ChatResponse, ChatResponseUpdate, CheckpointStorage, + RawAgent, ResponseStream, SessionStore, SupportsAgentRun, @@ -58,9 +59,13 @@ WorkflowSource, WorkflowTurn, is_agent, + reject_removed_host_settings, resolve_agent, + validate_agent_background_options, validate_agent_source, + validate_default_transport_options, validate_request_options, + validate_sse_keep_alive_interval, validate_unsupported_options, workflow_agents, ) @@ -335,9 +340,23 @@ def __init__( prepare_options: InvocationOptionsHook | None = None, unsupported_options: UnsupportedOptions = "warn", legacy_wire_format: bool = False, + sse_keep_alive_interval_seconds: int | None = None, **kwargs: Any, ) -> None: """Initialize shared protocol plumbing after the public host selects its execution model.""" + reject_removed_host_settings(kwargs) + if forbidden := { + "max_history_items", + "history_source", + "background_source", + "enable_background_recovery", + "shutdown_grace_period_seconds", + }.intersection(kwargs): + raise TypeError( + f"Responses-only settings are not supported by Invocations: {', '.join(sorted(forbidden))}." + ) + validate_sse_keep_alive_interval(sse_keep_alive_interval_seconds) + unsupported_options = validate_unsupported_options(unsupported_options) if "parse_request" in kwargs: raise TypeError("parse_request was renamed to parse_input.") if agent is not None and workflow is not None: @@ -357,6 +376,10 @@ def __init__( raise TypeError("prepare_options must be a callable.") if not isinstance(legacy_wire_format, bool): raise TypeError("legacy_wire_format must be a boolean.") + if legacy_wire_format and sse_keep_alive_interval_seconds is not None: + raise ValueError("SSE heartbeats require framed SSE; disable legacy_wire_format.") + if is_agent(agent): + self._validate_agent_options(agent) if workflow is not None: if legacy_wire_format: raise ValueError("legacy_wire_format=True is incompatible with native workflows.") @@ -370,11 +393,15 @@ def __init__( WorkflowResolver(workflow) if workflow is not None else None ) super().__init__(openapi_spec=openapi_spec, **kwargs) + if legacy_wire_format: + self.config.sse_keepalive_interval = 0 + elif sse_keep_alive_interval_seconds is not None: + self.config.sse_keepalive_interval = sse_keep_alive_interval_seconds self._agent = agent self._owns_request_agent = agent is not None and not is_agent(agent) self._parse_input = parse_input self._prepare_options = prepare_options - self._unsupported_options = validate_unsupported_options(unsupported_options) + self._unsupported_options = unsupported_options self._legacy_wire_format = legacy_wire_format self._session_store_provider = ( AgentSessionStoreProvider(store_name="invocation_sessions") @@ -468,11 +495,18 @@ async def _request_agent(self, request: Request) -> AsyncGenerator[SupportsAgent if self._agent is None: raise RuntimeError("No agent is configured for Invocations.") agent = await resolve_agent(self._agent, request) + self._validate_agent_options(agent) async with AsyncExitStack() as resources: if self._owns_request_agent and isinstance(agent, AbstractAsyncContextManager): await resources.enter_async_context(agent) yield agent + @staticmethod + def _validate_agent_options(agent: SupportsAgentRun) -> None: + validate_agent_background_options(agent, provider_background=False) + if isinstance(agent, RawAgent): + validate_default_transport_options(agent.default_options, allow_agent_store=True) + @asynccontextmanager async def _request_session( self, @@ -549,10 +583,10 @@ async def _options(self, request: Request, parsed: InvocationRun) -> dict[str, A if not isinstance(result, Mapping) or any(not isinstance(key, str) for key in result): raise TypeError("prepare_options must return a mapping of MAF run options with string keys.") options = deepcopy(dict(result)) - validate_request_options(options) reserved = _AGENT_CONTROLLED_FIELDS.intersection(options) if reserved: raise ValueError(f"Invocations options cannot set agent-controlled fields: {', '.join(sorted(reserved))}.") + validate_request_options(options) return options def _agent_kwargs(self, agent: SupportsAgentRun, options: dict[str, Any]) -> dict[str, Any]: diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py index 3f956209228..e23a252e456 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py @@ -25,6 +25,7 @@ def __init__( parse_input: Callable[[Request], WorkflowTurn[Any] | Awaitable[WorkflowTurn[Any]]], openapi_spec: dict[str, Any] | None = None, checkpoint_store_provider: ContextScopedStoreProvider[CheckpointStorage] | None = None, + sse_keep_alive_interval_seconds: int | None = None, **kwargs: Any, ) -> None: """Create a native workflow host with explicit parsing and checkpoint ownership. @@ -41,12 +42,15 @@ def __init__( openapi_spec: Application OpenAPI specification forwarded to AgentServer. checkpoint_store_provider: Scoped checkpoint storage. Defaults to `CheckpointStoreProvider`. Native workflow history and pending replies are checkpoint-owned, not agent-session-owned. + sse_keep_alive_interval_seconds: Positive streaming heartbeat interval. If omitted, use a positive + `SSE_KEEPALIVE_INTERVAL`, otherwise disable heartbeats. Not a request/model timeout. **kwargs: Additional AgentServer host settings forwarded to the SDK. Agent option hooks and legacy wire format are not supported. Output uses JSON or framed SSE workflow events. Raises: - TypeError: If the workflow is not a request-aware factory, the parser is invalid, or an agent-only - setting is supplied. + TypeError: If the workflow is not a request-aware factory, the parser or heartbeat type is invalid, + or a removed, Responses-only, or agent-only setting is supplied. + ValueError: If the heartbeat interval is nonpositive. """ forbidden = { "agent", @@ -64,5 +68,6 @@ def __init__( parse_input=parse_input, openapi_spec=openapi_spec, checkpoint_store_provider=checkpoint_store_provider, + sse_keep_alive_interval_seconds=sse_keep_alive_interval_seconds, **kwargs, ) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py index 504bc3b0a8b..335b72244ac 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py @@ -33,7 +33,7 @@ WorkflowInvocationKwargs, WorkflowRunState, ) -from azure.ai.agentserver.responses import ResponseContext +from azure.ai.agentserver.responses import ResponseContext, ResponsesServerOptions from azure.ai.agentserver.responses.models import CreateResponse, Item from typing_extensions import TypeVar @@ -42,6 +42,86 @@ UnsupportedOptions: TypeAlias = Literal["ignore", "warn", "error"] +def reject_removed_host_settings(settings: Mapping[str, Any]) -> None: + """Reject removed SDK settings before constructing a host or allocating resources.""" + replacements = { + "options": "Use the supported first-class host parameters instead of ResponsesServerOptions.", + "default_fetch_history_count": "Use max_history_items on a host-managed Responses agent.", + "default_model": "Configure inference defaults on the agent or client.", + "create_span_hook": "Use Agent Framework observability instead.", + "additional_server_version": "Custom server version stamping is not supported.", + "steerable_conversations": "Conversation steering is not supported.", + "resilient_background": "Use enable_background_recovery on a Responses host.", + } + for name, message in replacements.items(): + if name in settings: + raise TypeError(f"{name} is no longer a supported host setting. {message}") + + +def validate_sse_keep_alive_interval(value: int | None) -> None: + """Validate an explicit heartbeat interval without replacing SDK environment resolution.""" + if value is not None: + if isinstance(value, bool) or not isinstance(value, int): + raise TypeError("sse_keep_alive_interval_seconds must be an integer or None.") + if value <= 0: + raise ValueError("sse_keep_alive_interval_seconds must be positive when supplied.") + + +def build_response_server_options( + *, + is_workflow: bool, + history_source: Literal["host_managed", "agent_managed", "inference_service"] = "host_managed", + background_source: Literal["host_managed", "inference_service"] = "host_managed", + max_history_items: int | None = None, + sse_keep_alive_interval_seconds: int | None = None, + shutdown_grace_period_seconds: int = 10, + enable_background_recovery: bool = False, +) -> ResponsesServerOptions: + """Validate supported settings and build SDK options without host initialization. + + Omit an unset history limit so the installed SDK supplies its own default. + Leave heartbeat environment resolution to the SDK: an explicit positive + interval wins over a positive ``SSE_KEEPALIVE_INTERVAL``, otherwise disabled. + Neither SDK ``from_env`` history overrides nor host model defaults are loaded. + """ + validate_sse_keep_alive_interval(sse_keep_alive_interval_seconds) + if isinstance(shutdown_grace_period_seconds, bool) or not isinstance(shutdown_grace_period_seconds, int): + raise TypeError("shutdown_grace_period_seconds must be an integer.") + if shutdown_grace_period_seconds <= 0: + raise ValueError("shutdown_grace_period_seconds must be positive.") + if not isinstance(enable_background_recovery, bool): + raise TypeError("enable_background_recovery must be a boolean.") + if history_source not in ("host_managed", "agent_managed", "inference_service"): + raise ValueError("history_source must be 'host_managed', 'agent_managed', or 'inference_service'.") + if background_source not in ("host_managed", "inference_service"): + raise ValueError("background_source must be 'host_managed' or 'inference_service'.") + if background_source == "inference_service" and (is_workflow or history_source != "inference_service"): + raise ValueError( + "Inference-service background requires a regular agent with history_source='inference_service'." + ) + if enable_background_recovery and not is_workflow and background_source != "inference_service": + raise ValueError( + "enable_background_recovery=True requires history_source='inference_service' and " + "background_source='inference_service' for regular agents." + ) + kwargs: dict[str, Any] = {} + if max_history_items is not None: + if isinstance(max_history_items, bool) or not isinstance(max_history_items, int): + raise TypeError("max_history_items must be an integer or None.") + if max_history_items <= 0: + raise ValueError("max_history_items must be positive when supplied.") + if is_workflow or history_source != "host_managed": + raise ValueError("max_history_items applies only to regular agents with history_source='host_managed'.") + kwargs["default_fetch_history_count"] = max_history_items + return ResponsesServerOptions( + sse_keep_alive_interval_seconds=sse_keep_alive_interval_seconds, + shutdown_grace_period_seconds=shutdown_grace_period_seconds, + resilient_background=enable_background_recovery, + steerable_conversations=False, + **kwargs, + ) + + InputT = TypeVar("InputT", default=Any) @@ -141,6 +221,17 @@ def __post_init__(self) -> None: _OPTION_NAMES = {"max_output_tokens": "max_tokens", "parallel_tool_calls": "allow_multiple_tool_calls"} +_RUN_CONTROLLED_FIELDS = frozenset({ + "additional_function_arguments", + "client_kwargs", + "compaction_strategy", + "function_invocation_kwargs", + "messages", + "middleware", + "session", + "tokenizer", +}) + _NATIVE_FIELDS = frozenset(CreateResponse.__annotations__) @@ -160,6 +251,10 @@ def response_run_options(request: CreateResponse) -> dict[str, Any]: raise TypeError("extra_body must be a mapping of model options.") if "extra_body" in value: raise ValueError("Nested extra_body is not supported; flatten provider options instead.") + if reserved := (_HOST_CONTROLLED_FIELDS | _RUN_CONTROLLED_FIELDS).intersection( + cast(Mapping[str, Any], value) + ): + raise ValueError(f"extra_body cannot set host-controlled fields: {', '.join(sorted(reserved))}.") nested_extra.update(cast(Mapping[str, Any], value)) elif name in _HOST_CONTROLLED_FIELDS: continue @@ -170,7 +265,7 @@ def response_run_options(request: CreateResponse) -> dict[str, Any]: return { **native, **{name: value for name, value in extra.items() if name not in _HOST_CONTROLLED_FIELDS}, - **{name: value for name, value in nested_extra.items() if name not in _HOST_CONTROLLED_FIELDS}, + **nested_extra, } @@ -231,15 +326,20 @@ def _set_workflow_responses(self, loader: Callable[[], Awaitable[dict[str, Any]] async def prepare_response_options(request: ResponsesRequest, hook: OptionsHook | None) -> None: - """Apply a synchronous or asynchronous developer hook to a copy of caller options.""" + """Apply a sync/async hook after factory resolution, without changing agent defaults. + + Return replacement per-run options for both streaming and non-streaming requests. + Removing a caller ``model`` leaves the developer's agent/client default intact. + The host validates protected fields after this hook and before dispatch. + """ if hook is None: return - result = hook(request, dict(request.options)) + result = hook(request, deepcopy(dict(request.options))) if inspect.isawaitable(result): result = await result - if not isinstance(result, Mapping): + if not isinstance(result, Mapping) or any(not isinstance(key, str) for key in result): raise TypeError("prepare_options must return a mapping of MAF run options.") - request.set_options(result) + request.set_options(deepcopy(dict(result))) async def response_input_messages(request: ResponsesRequest) -> list[Message]: @@ -256,11 +356,38 @@ async def response_input_messages(request: ResponsesRequest) -> list[Message]: def validate_request_options(options: Mapping[str, Any]) -> None: """Keep hosting identity, storage decisions, and private continuation out of model options.""" - reserved = _HOST_CONTROLLED_FIELDS.intersection(options) + if not isinstance(options, Mapping) or any(not isinstance(key, str) for key in options): + raise TypeError("Run options must be a mapping with string keys.") + reserved = (_HOST_CONTROLLED_FIELDS | _RUN_CONTROLLED_FIELDS).intersection(options) if reserved: raise ValueError(f"prepare_options cannot set host-controlled fields: {', '.join(sorted(reserved))}.") +def validate_agent_background_options(agent: SupportsAgentRun, *, provider_background: bool) -> None: + """Reject hidden provider background in hosting-visible agent defaults without mutating them. + + A selected regular-agent provider-background request may use a top-level + boolean default. A transport ``extra_body`` override is never supported. + Clients hard-wired internally to provider background are unsupported. + This does not select execution mode or validate client/storage capabilities. + """ + defaults = getattr(agent, "default_options", {}) + if not isinstance(defaults, Mapping): + raise TypeError("Agent default_options must be a mapping.") + defaults = cast(Mapping[str, Any], defaults) + background = defaults.get("background") + if background is not None and not isinstance(background, bool): + raise TypeError("Agent default background must be a boolean.") + if background is True and not provider_background: + raise ValueError( + "Agent default background=True requires an outer background request with " + "history_source='inference_service' and background_source='inference_service'." + ) + extra_body = defaults.get("extra_body") + if isinstance(extra_body, Mapping) and "background" in extra_body: + raise ValueError("Agent default extra_body cannot set host-controlled fields: background.") + + def validate_default_transport_options(defaults: Mapping[str, Any], *, allow_agent_store: bool) -> None: """Reject transport overrides that would bypass the host's inner storage and identity decisions.""" extra_body = defaults.get("extra_body") @@ -416,6 +543,12 @@ async def process(self, context: AgentContext, call_next: Callable[[], Awaitable if context.session is not None and context.session.service_session_id is not None: raise RuntimeError("Native workflow checkpoints cannot resume a private downstream service session.") effective = {**(context.options or {}), **options} + if (_CLIENT_CONTROLS - {"store", "instructions", "tools", "extra_body"}).intersection(effective): + raise ValueError("Native workflow model options cannot override hosting or transport controls.") + if (_CLIENT_CONTROLS - {"additional_function_arguments"}).intersection(context.client_kwargs): + raise ValueError("Native workflow client kwargs cannot override hosting or transport controls.") + validate_default_transport_options(effective, allow_agent_store=False) + validate_agent_background_options(context.agent, provider_background=False) client = getattr(context.agent, "client", None) if getattr(client, "STORES_BY_DEFAULT", None) is True: effective["store"] = False diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/options_helpers.py b/python/packages/foundry_hosting/tests/foundry_hosting/options_helpers.py new file mode 100644 index 00000000000..ccb067bcb8c --- /dev/null +++ b/python/packages/foundry_hosting/tests/foundry_hosting/options_helpers.py @@ -0,0 +1,85 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Offline clients and callbacks for host option-boundary tests.""" + +from __future__ import annotations + +import asyncio +from collections.abc import AsyncIterator, Awaitable, Mapping, Sequence +from typing import Any, cast + +from agent_framework import ( + Agent, + AgentContext, + BaseChatClient, + ChatOptions, + ChatResponse, + ChatResponseUpdate, + Content, + Message, + ResponseStream, + Workflow, + WorkflowBuilder, +) +from starlette.requests import Request + + +class OptionsClient(BaseChatClient[ChatOptions]): + STORES_BY_DEFAULT = False + + def __init__(self, *, delay: float = 0) -> None: + super().__init__() + self.calls: list[dict[str, Any]] = [] + self.delay = delay + + def _inner_get_response( + self, + *, + messages: Sequence[Message], + stream: bool, + options: Mapping[str, Any], + **kwargs: Any, + ) -> Awaitable[ChatResponse] | ResponseStream[ChatResponseUpdate, ChatResponse]: + self.calls.append(dict(options)) + return ResponseStream(self.updates(), finalizer=ChatResponse.from_updates) if stream else self.complete() + + async def updates(self) -> AsyncIterator[ChatResponseUpdate]: + if self.delay: + await asyncio.sleep(self.delay) + yield ChatResponseUpdate(role="assistant", contents=[Content.from_text("ok")]) + + async def complete(self) -> ChatResponse: + return ChatResponse(messages=[Message("assistant", ["ok"])]) + + +class OptionCallbacks: + def __init__(self, *, defaults: dict[str, Any] | None = None, injected: dict[str, Any] | None = None) -> None: + self.client = OptionsClient() + self.defaults = cast(ChatOptions, defaults or {}) + self.injected = injected or {} + self.events: list[str] = [] + + def factory(self, *, request: Request) -> Agent: + self.events.append("factory") + return Agent(client=self.client, default_options=self.defaults) + + def prepare(self, request: Request, options: dict[str, Any]) -> dict[str, Any]: + self.events.append("hook") + options.pop("model", None) + return options + + async def prepare_async(self, request: Request, options: dict[str, Any]) -> dict[str, Any]: + return self.prepare(request, options) + + async def inject(self, context: AgentContext, call_next: Any) -> None: + context.options = {**(context.options or {}), **self.injected} + await call_next() + + def workflow(self, request: Request) -> Workflow: + self.events.append("factory") + agent = Agent( + client=self.client, + default_options=self.defaults, + middleware=[self.inject] if self.injected else None, + ) + return WorkflowBuilder(start_executor=agent).build() diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py new file mode 100644 index 00000000000..3a1de89c8c7 --- /dev/null +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py @@ -0,0 +1,311 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Verify supported settings and option boundaries without external model calls.""" + +from __future__ import annotations + +from typing import Any, cast +from unittest.mock import AsyncMock, MagicMock, patch + +import httpx +import pytest +from agent_framework import Agent, AgentContext, AgentSession, ChatOptions, RawAgent +from azure.ai.agentserver.responses import ResponsesServerOptions + +from agent_framework_foundry_hosting import ( + InvocationsHostServer, + InvocationsWorkflowHostServer, + ResponsesRequest, + WorkflowTurn, +) +from agent_framework_foundry_hosting._scope import FoundryRequestScope +from agent_framework_foundry_hosting._shared import ( + _NativeAgentOptions, + build_response_server_options, + prepare_response_options, + reject_removed_host_settings, + validate_agent_background_options, + validate_request_options, +) + +from .options_helpers import OptionCallbacks, OptionsClient + + +def test_history_default_is_omitted_instead_of_forced_unlimited(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("DEFAULT_FETCH_HISTORY_ITEM_COUNT", "7") + with patch("agent_framework_foundry_hosting._shared.ResponsesServerOptions", wraps=ResponsesServerOptions) as sdk: + result = build_response_server_options(is_workflow=False) + assert "default_fetch_history_count" not in sdk.call_args.kwargs + assert result.default_fetch_history_count == ResponsesServerOptions().default_fetch_history_count + assert result.default_model is None + assert result.steerable_conversations is False + assert result.resilient_background is False + assert build_response_server_options(is_workflow=False, max_history_items=7).default_fetch_history_count == 7 + + +@pytest.mark.parametrize( + ("settings", "error"), + [ + ({"max_history_items": True}, TypeError), + ({"max_history_items": 1.5}, TypeError), + ({"max_history_items": 0}, ValueError), + ({"max_history_items": -1}, ValueError), + ({"sse_keep_alive_interval_seconds": True}, TypeError), + ({"sse_keep_alive_interval_seconds": "5"}, TypeError), + ({"sse_keep_alive_interval_seconds": 0}, ValueError), + ({"sse_keep_alive_interval_seconds": -1}, ValueError), + ({"shutdown_grace_period_seconds": True}, TypeError), + ({"shutdown_grace_period_seconds": 0}, ValueError), + ({"enable_background_recovery": 1}, TypeError), + ({"enable_background_recovery": True}, ValueError), + ({"history_source": "inference_service", "max_history_items": 2}, ValueError), + ({"history_source": "agent_managed", "max_history_items": 2}, ValueError), + ({"background_source": "inference_service"}, ValueError), + ({"history_source": "wrong"}, ValueError), + ({"background_source": "wrong"}, ValueError), + ], +) +def test_invalid_settings_fail_before_sdk_options_construction( + settings: dict[str, Any], error: type[Exception] +) -> None: + with patch("agent_framework_foundry_hosting._shared.ResponsesServerOptions") as sdk, pytest.raises(error): + build_response_server_options(is_workflow=False, **settings) + sdk.assert_not_called() + + +def test_recovery_and_workflow_history_eligibility() -> None: + assert build_response_server_options( + is_workflow=False, + history_source="inference_service", + background_source="inference_service", + enable_background_recovery=True, + ).resilient_background + assert build_response_server_options(is_workflow=True, enable_background_recovery=True).resilient_background + with pytest.raises(ValueError, match="regular agents"): + build_response_server_options(is_workflow=True, max_history_items=2) + with pytest.raises(ValueError, match="regular agent"): + build_response_server_options(is_workflow=True, background_source="inference_service") + + +@pytest.mark.parametrize( + "name", + [ + "options", + "default_fetch_history_count", + "default_model", + "create_span_hook", + "additional_server_version", + "steerable_conversations", + "resilient_background", + ], +) +def test_removed_host_settings_fail_even_when_none(name: str) -> None: + settings: dict[str, Any] = {name: None} + with pytest.raises(TypeError, match=name): + reject_removed_host_settings({name: None}) + with ( + patch("agent_framework_foundry_hosting._invocations_shared.InvocationAgentServerHost.__init__") as sdk, + pytest.raises(TypeError, match=name), + ): + InvocationsHostServer(Agent(client=OptionsClient()), **settings) + sdk.assert_not_called() + + +@pytest.mark.parametrize( + "name", + [ + "max_history_items", + "history_source", + "background_source", + "enable_background_recovery", + "shutdown_grace_period_seconds", + ], +) +def test_invocations_rejects_responses_only_settings_before_sdk(name: str) -> None: + settings: dict[str, Any] = {name: None} + with ( + patch("agent_framework_foundry_hosting._invocations_shared.InvocationAgentServerHost.__init__") as sdk, + pytest.raises(TypeError, match="Responses-only"), + ): + InvocationsHostServer(Agent(client=OptionsClient()), **settings) + sdk.assert_not_called() + + +@pytest.mark.parametrize("env", [None, "0", "-2", "3"]) +@pytest.mark.parametrize("explicit", [None, 5]) +def test_invocations_heartbeat_precedence_and_per_host_isolation( + monkeypatch: pytest.MonkeyPatch, env: str | None, explicit: int | None +) -> None: + if env is None: + monkeypatch.delenv("SSE_KEEPALIVE_INTERVAL", raising=False) + else: + monkeypatch.setenv("SSE_KEEPALIVE_INTERVAL", env) + first = InvocationsHostServer(Agent(client=OptionsClient()), sse_keep_alive_interval_seconds=explicit) + second = InvocationsHostServer(Agent(client=OptionsClient())) + inherited = max(0, int(env or "0")) + assert first.config.sse_keepalive_interval == (explicit if explicit is not None else inherited) + assert second.config.sse_keepalive_interval == inherited + assert first.config is not second.config + + +def test_legacy_raw_stream_does_not_inherit_heartbeats(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("SSE_KEEPALIVE_INTERVAL", "3") + with pytest.warns(DeprecationWarning): + server = InvocationsHostServer(Agent(client=OptionsClient()), legacy_wire_format=True) + assert server.config.sse_keepalive_interval == 0 + with pytest.raises(ValueError, match="framed SSE"): + InvocationsHostServer(Agent(client=OptionsClient()), legacy_wire_format=True, sse_keep_alive_interval_seconds=1) + + +@pytest.mark.parametrize("provider_background", [False, True]) +@pytest.mark.parametrize("background", [None, False, True, "true", 1]) +def test_agent_background_defaults_are_validated_without_mutation(provider_background: bool, background: Any) -> None: + agent = RawAgent(client=OptionsClient(), default_options=cast(ChatOptions, {"background": background})) + before = dict(agent.default_options) + if background is not None and not isinstance(background, bool): + with pytest.raises(TypeError, match="boolean"): + validate_agent_background_options(agent, provider_background=provider_background) + elif background is True and not provider_background: + with pytest.raises(ValueError, match="outer background"): + validate_agent_background_options(agent, provider_background=provider_background) + else: + validate_agent_background_options(agent, provider_background=provider_background) + assert agent.default_options == before + + +@pytest.mark.parametrize("provider_background", [False, True]) +def test_transport_body_cannot_bypass_background_selection(provider_background: bool) -> None: + agent = RawAgent(client=OptionsClient(), default_options=cast(ChatOptions, {"extra_body": {"background": True}})) + with pytest.raises(ValueError, match="extra_body"): + validate_agent_background_options(agent, provider_background=provider_background) + + +@pytest.mark.parametrize("field", ["additional_function_arguments", "client_kwargs", "function_invocation_kwargs"]) +def test_response_hook_cannot_supply_run_context(field: str) -> None: + with pytest.raises(ValueError, match=field): + validate_request_options({field: {"background": True}}) + + +@pytest.mark.parametrize("stream", [False, True]) +@pytest.mark.parametrize("async_hook", [False, True]) +async def test_invocations_hook_before_factory_preserves_developer_model(stream: bool, async_hook: bool) -> None: + callbacks = OptionCallbacks(defaults={"model": "developer", "temperature": 0.4}) + host = InvocationsHostServer( + callbacks.factory, + prepare_options=callbacks.prepare_async if async_hook else callbacks.prepare, + ) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: + response = await client.post( + "/invocations?agent_session_id=options", + json={"message": "hi", "stream": stream, "options": {"model": "caller", "temperature": 0.8}}, + ) + assert response.status_code == 200 + assert callbacks.events == ["hook", "factory"] + assert callbacks.client.calls[0]["model"] == "developer" + assert callbacks.client.calls[0]["temperature"] == 0.8 + assert callbacks.defaults == {"model": "developer", "temperature": 0.4} + + +@pytest.mark.parametrize("stream", [False, True]) +async def test_invocations_rejects_factory_hidden_background_before_model_call( + stream: bool, caplog: pytest.LogCaptureFixture +) -> None: + callbacks = OptionCallbacks(defaults={"background": True}) + host = InvocationsHostServer(callbacks.factory, prepare_options=callbacks.prepare) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: + response = await client.post("/invocations?agent_session_id=options", json={"message": "hi", "stream": stream}) + assert response.status_code == (200 if stream else 500) + assert "Agent invocation failed." in response.text + assert "background=True requires an outer background" in caplog.text + assert callbacks.events == ["hook", "factory"] + assert callbacks.client.calls == [] + + +@pytest.mark.parametrize("stream", [False, True]) +@pytest.mark.parametrize("source", ["defaults", "middleware"]) +async def test_native_workflow_rejects_inner_background_before_model_call( + stream: bool, source: str, caplog: pytest.LogCaptureFixture +) -> None: + callbacks = OptionCallbacks( + defaults={"background": True} if source == "defaults" else None, + injected={"background": True} if source == "middleware" else None, + ) + host = InvocationsWorkflowHostServer( + callbacks.workflow, parse_input=lambda request: WorkflowTurn(input="hi", stream=stream) + ) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: + response = await client.post("/invocations?agent_session_id=workflow-options", json={}) + assert response.status_code == (200 if stream else 500 if source == "middleware" else 400) + if source == "middleware": + assert "Workflow invocation failed." in response.text + assert "Native workflow model options cannot override hosting" in caplog.text + else: + assert "hosting identity defaults" in response.text + assert callbacks.client.calls == [] + + +async def test_native_middleware_rechecks_direct_client_kwargs() -> None: + client = OptionsClient() + context = AgentContext( + agent=Agent(client=client), + messages=[], + session=AgentSession(), + client_kwargs={"background": True}, + ) + policy = _NativeAgentOptions(FoundryRequestScope("session", None, None, False)) + with pytest.raises(ValueError, match="client kwargs"): + await policy.process(context, cast(Any, None)) + assert client.calls == [] + + +@pytest.mark.parametrize("stream", [False, True]) +@pytest.mark.parametrize("injected", [{"background": True}, {"extra_body": {"background": True}}]) +async def test_native_middleware_rechecks_effective_options(stream: bool, injected: dict[str, Any]) -> None: + context = AgentContext( + agent=Agent(client=OptionsClient()), + messages=[], + session=AgentSession(), + stream=stream, + options=injected, + ) + policy = _NativeAgentOptions(FoundryRequestScope("session", None, None, False)) + dispatch = AsyncMock() + with pytest.raises(ValueError, match="hosting|host-controlled"): + await policy.process(context, dispatch) + dispatch.assert_not_called() + + +@pytest.mark.parametrize("workflow", [False, True]) +async def test_explicit_interval_emits_heartbeat_on_real_invocations_stream(workflow: bool) -> None: + callbacks = OptionCallbacks() + callbacks.client = OptionsClient(delay=1.1) + host = ( + InvocationsWorkflowHostServer( + callbacks.workflow, + parse_input=lambda request: WorkflowTurn(input="hi", stream=True), + sse_keep_alive_interval_seconds=1, + ) + if workflow + else InvocationsHostServer(callbacks.factory, sse_keep_alive_interval_seconds=1) + ) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: + response = await client.post("/invocations?agent_session_id=heartbeat", json={"message": "hi", "stream": True}) + assert response.status_code == 200 + assert ": keep-alive\n\n" in response.text + assert "ok" in response.text + assert len(callbacks.client.calls) == 1 + + +async def test_response_hook_returns_independent_nested_options() -> None: + source: dict[str, Any] = {"metadata": {"source": "caller"}} + request = ResponsesRequest( + cast(Any, {}), + MagicMock(), + FoundryRequestScope("session", None, None, False), + source, + ) + await prepare_response_options(request, lambda request, options: options) + assert dict(request.options) == source + assert request.options["metadata"] is not source["metadata"] + with pytest.raises(TypeError, match="mapping"): + await prepare_response_options(request, lambda request, options: cast(Any, {1: "not-string"})) diff --git a/python/packages/foundry_hosting/tests/test_request.py b/python/packages/foundry_hosting/tests/test_request.py index 4a783d30556..16d514c69ca 100644 --- a/python/packages/foundry_hosting/tests/test_request.py +++ b/python/packages/foundry_hosting/tests/test_request.py @@ -56,19 +56,24 @@ def test_native_options_are_translated_before_flattened_extra_body() -> None: } -def test_nested_extra_body_is_also_overlaid_last_without_reserved_fields() -> None: +def test_nested_extra_body_is_overlaid_last_and_rejects_reserved_fields() -> None: request = cast( CreateResponse, { "max_output_tokens": 300, "extra_body": { "max_tokens": 150, - "session_id": "forged", - "continuation_token": {"response_id": "private"}, }, }, ) assert response_run_options(request) == {"max_tokens": 150} + with pytest.raises(ValueError, match="continuation_token, session_id"): + response_run_options( + cast( + CreateResponse, + {"extra_body": {"session_id": "forged", "continuation_token": {"response_id": "private"}}}, + ) + ) with pytest.raises(TypeError, match="extra_body must be a mapping"): response_run_options(cast(CreateResponse, {"extra_body": ["not a mapping"]})) with pytest.raises(ValueError, match="Nested extra_body is not supported"): From e0243ce5c27e0337b052eae2fada485f573450ed Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 09:37:46 +0100 Subject: [PATCH 03/55] Add conditional session-backed Foundry approval authority --- .../_approvals.py | 297 ++++++++++++++++++ .../_state_store.py | 95 +++++- .../tests/foundry_hosting/approval_helpers.py | 152 +++++++++ .../foundry_hosting/test_session_approvals.py | 252 +++++++++++++++ .../foundry_hosting/tests/test_state_store.py | 119 ++++++- 5 files changed, 909 insertions(+), 6 deletions(-) create mode 100644 python/packages/foundry_hosting/agent_framework_foundry_hosting/_approvals.py create mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/approval_helpers.py create mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/test_session_approvals.py diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_approvals.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_approvals.py new file mode 100644 index 00000000000..cb818226b3a --- /dev/null +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_approvals.py @@ -0,0 +1,297 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Keep hosted agent approval history separate from conditional pending authority.""" + +from __future__ import annotations + +import json +from collections.abc import Sequence +from dataclasses import dataclass +from typing import Any, cast +from uuid import uuid4 + +from agent_framework import AgentSession, Content, SessionStore + +from ._state_store import _ConditionalSessionStore # pyright: ignore[reportPrivateUsage] + +_APPROVAL_STATE_KEY = "__foundry_agent_approvals_v1" +_AUTHORITY_PREFIX = "__foundry_agent_approval/" +_MAX_HISTORY_REQUESTS = 1024 +_MAX_HISTORY_BYTES = 1024 * 1024 + + +@dataclass(frozen=True) +class _ApprovalClaim: + authority_id: str + revision: str + session_id: str + owner_response_id: str + requests: tuple[tuple[str, str], ...] + + +def _conditional_store(storage: SessionStore | None) -> _ConditionalSessionStore: + if not isinstance(storage, _ConditionalSessionStore): + raise RuntimeError( + "Hosted approvals require a session store implementing get_with_revision and compare_and_set " + "with atomic create-only and exact-revision writes; ordinary get/set is not sufficient." + ) + return storage + + +def _mapping(value: object, message: str) -> dict[str, Any]: + if not isinstance(value, dict) or any(not isinstance(key, str) for key in cast(dict[object, object], value)): + raise RuntimeError(message) + return cast(dict[str, Any], value) + + +def _requests(value: object) -> dict[str, str]: + raw = _mapping(value, "Unsupported approval history; start a fresh conversation.") + if any(not key or not isinstance(item, str) for key, item in raw.items()): + raise RuntimeError("Unsupported approval history; start a fresh conversation.") + return cast(dict[str, str], raw) + + +def _decode_request(value: str) -> Content: + try: + raw: object = json.loads(value) + except (TypeError, ValueError) as exc: + raise RuntimeError("Unsupported stored approval content; start a fresh conversation.") from exc + payload = _mapping(raw, "Unsupported stored approval content; start a fresh conversation.") + try: + content = Content.from_dict(payload) + except (TypeError, ValueError, KeyError) as exc: + raise RuntimeError("Unsupported stored approval content; start a fresh conversation.") from exc + if ( + content.type != "function_approval_request" + or not content.id + or content.function_call is None + or content.function_call.type != "function_call" + or not content.function_call.call_id + or not content.function_call.name + ): + raise RuntimeError("Unsupported stored approval content; start a fresh conversation.") + return content + + +class SessionApprovalState: + """Manage a regular agent's approval aliases through its session store. + + ``save_approval_request`` stages output only. The host must buffer approval + events until ``seal`` and the ordinary session snapshot writes succeed. + Input conversion can read history but cannot consume authority. Preflight + reads the canonical batch; claim conditionally consumes it immediately before + protected dispatch, after every other request check and reservation. + + A canonical entry is another private ``AgentSession`` in the same store, not + a separately configured approval backend. Response and conversation snapshots + contain only a link and historical content. Missing or expired canonical + entries fail closed, even when a historical snapshot still exists. + + Custom stores must implement revision reads and atomic create-only/exact- + revision writes. The default local Foundry backend cannot provide this + capability and raises ``RuntimeError``; ordinary non-approval sessions are + unaffected. History is capped at 1024 requests and 1 MiB of serialized content. + Unsupported state and history overflow require a fresh conversation, never + silent migration or pruning. Native workflow checkpoints do not use this + authority. + """ + + def __init__(self, session: AgentSession, storage: SessionStore | None, *, response_id: str | None = None) -> None: + self.session = session + self._storage = storage + self._response_id = response_id + self._staged: dict[str, str] = {} + self._sealed = False + value = session.state.get(_APPROVAL_STATE_KEY) + if _APPROVAL_STATE_KEY not in session.state: + self._state: dict[str, Any] = {"version": 1, "history": {}, "pending": None} + else: + state = _mapping(value, "Unsupported approval session state; start a fresh conversation.") + if type(state.get("version")) is not int or state["version"] != 1: + raise RuntimeError("Unsupported approval session version; start a fresh conversation.") + if "history" not in state or "pending" not in state: + raise RuntimeError("Unsupported approval session state; start a fresh conversation.") + _requests(state["history"]) + self._state = state + self._pending() + + def _pending(self) -> dict[str, Any] | None: + value = self._state["pending"] + if value is None: + return None + pending = _mapping(value, "Unsupported pending approval link; start a fresh conversation.") + if ( + not isinstance(pending.get("authority_id"), str) + or not pending["authority_id"].startswith(_AUTHORITY_PREFIX) + or not isinstance(pending.get("response_id"), str) + or not pending["response_id"] + or not isinstance(pending.get("wire_ids"), list) + ): + raise RuntimeError("Unsupported pending approval link; start a fresh conversation.") + ids = cast(list[object], pending["wire_ids"]) + if not ids or any(not isinstance(item, str) or not item for item in ids) or len(set(ids)) != len(ids): + raise RuntimeError("Unsupported pending approval link; start a fresh conversation.") + return pending + + async def load_approval_request(self, approval_request_id: str) -> Content: + """Reconstruct original content without granting or consuming authority.""" + history = _requests(self._state["history"]) + value = history.get(approval_request_id) + if value is None: + raise ValueError("Approval request is not in this session's history; start a fresh approval turn.") + return _decode_request(value) + + async def save_approval_request(self, approval_request_id: str, request: Content) -> None: + """Stage a wire mapping; the host must not publish it until sealing.""" + _conditional_store(self._storage) + if self._sealed or self._pending() is not None: + raise RuntimeError("Cannot publish another approval batch while this batch is pending or sealed.") + if not self._response_id: + raise RuntimeError("Approval recording requires the owning response ID.") + if not approval_request_id or not isinstance(approval_request_id, str): + raise ValueError("Approval wire ID must be a non-empty string.") + history = _requests(self._state["history"]) + if approval_request_id in history or approval_request_id in self._staged: + raise ValueError("Approval wire ID already exists in this session.") + if ( + request.type != "function_approval_request" + or not request.id + or request.function_call is None + or request.function_call.type != "function_call" + or not request.function_call.call_id + or not request.function_call.name + ): + raise ValueError("Only complete function approval requests can be recorded.") + if any(_decode_request(value).id == request.id for value in self._staged.values()): + raise ValueError("Framework approval request ID already exists in this pending batch.") + # JSON strings prevent session codecs from interpreting nested provider + # dictionaries with a registered `type` discriminator as live objects. + encoded = json.dumps(request.to_dict(), allow_nan=False, separators=(",", ":")) + if len(history) + len(self._staged) + 1 > _MAX_HISTORY_REQUESTS or ( + sum(len(item.encode("utf-8")) for item in (*history.values(), *self._staged.values(), encoded)) + > _MAX_HISTORY_BYTES + ): + raise RuntimeError("Hosted approval history limit reached; start a fresh conversation.") + self._staged[approval_request_id] = encoded + + async def seal(self) -> None: + """Persist the complete pending batch before publishing its snapshots. + + A failed acknowledgement may still have written an unreachable canonical + record. No alias is attached until the write succeeds. Never retry a + cancelled/failed publication as protected dispatch. + """ + if not self._staged: + return + if self._sealed: + raise RuntimeError("Approval batch is already sealed.") + storage = _conditional_store(self._storage) + authority_id = f"{_AUTHORITY_PREFIX}{uuid4()}" + authority = AgentSession(session_id=self.session.session_id) + authority.state[_APPROVAL_STATE_KEY] = { + "version": 1, + "response_id": self._response_id, + "phase": "pending", + "requests": dict(self._staged), + "claimed_by": None, + } + revision = await storage.compare_and_set(authority_id, authority, expected_revision=None) + if not isinstance(revision, str) or not revision: + raise RuntimeError("Session storage did not acknowledge the approval revision.") + self._state["history"] = {**_requests(self._state["history"]), **self._staged} + self._state["pending"] = { + "authority_id": authority_id, + "response_id": self._response_id, + "wire_ids": list(self._staged), + } + self.session.state[_APPROVAL_STATE_KEY] = self._state + self._sealed = True + + async def preflight(self, approval_ids: Sequence[str]) -> _ApprovalClaim | None: + """Validate exactly one complete batch without writing any state. + + Missing, duplicate, foreign, stale, and already claimed controls fail + before the host opens a response stream. A pending batch also rejects a + new user turn with no decisions; reset by starting a fresh conversation. + Approval and rejection both count as decisions. The host validates their + boolean values and rejects conflicting input-control kinds separately. + """ + pending = self._pending() + if pending is None: + if approval_ids: + raise ValueError("No pending approval batch in this session; start a fresh approval turn.") + return None + if ( + any(not isinstance(item, str) or not item for item in approval_ids) + or len(set(approval_ids)) != len(approval_ids) + or set(approval_ids) != set(pending["wire_ids"]) + ): + raise ValueError("Answer exactly the complete pending MCP approval batch without duplicates.") + storage = _conditional_store(self._storage) + authority, revision = await storage.get_with_revision(pending["authority_id"]) + if authority is None: + raise ValueError("Pending approval authority is missing or expired; start a fresh conversation.") + if not isinstance(revision, str) or not revision: + raise RuntimeError("Session storage returned approval authority without a revision.") + record = _mapping( + authority.state.get(_APPROVAL_STATE_KEY), + "Unsupported canonical approval state; start a fresh conversation.", + ) + if type(record.get("version")) is not int or record["version"] != 1: + raise RuntimeError("Unsupported canonical approval version; start a fresh conversation.") + requests = _requests(record.get("requests")) + if ( + authority.session_id != self.session.session_id + or record.get("response_id") != pending["response_id"] + or set(requests) != set(pending["wire_ids"]) + or any(_requests(self._state["history"]).get(key) != value for key, value in requests.items()) + ): + raise ValueError("Pending approval authority does not match this session and response.") + if record.get("phase") == "claimed": + raise ValueError("Pending approval batch was already claimed; start a fresh approval turn.") + if record.get("phase") != "pending" or "claimed_by" not in record or record["claimed_by"] is not None: + raise RuntimeError("Unsupported canonical approval phase; start a fresh conversation.") + for value in requests.values(): + _decode_request(value) + return _ApprovalClaim( + pending["authority_id"], + revision, + self.session.session_id, + pending["response_id"], + tuple(requests.items()), + ) + + async def claim(self, token: _ApprovalClaim, *, response_id: str) -> None: + """Irreversibly claim a validated revision before protected dispatch. + + Run only after all request validation and other session/conversation + reservations succeed. A losing writer, storage failure, or cancellation + must not dispatch. A crash after acknowledgement may lose work; never + reopen the batch or claim exactly-once external side effects. + """ + pending = self._pending() + if not response_id: + raise ValueError("Claiming response ID must be provided.") + if ( + pending is None + or token.session_id != self.session.session_id + or token.authority_id != pending["authority_id"] + or token.owner_response_id != pending["response_id"] + or set(dict(token.requests)) != set(pending["wire_ids"]) + ): + raise ValueError("Approval preflight token does not match the current session.") + authority = AgentSession(session_id=token.session_id) + authority.state[_APPROVAL_STATE_KEY] = { + "version": 1, + "response_id": token.owner_response_id, + "phase": "claimed", + "requests": dict(token.requests), + "claimed_by": response_id, + } + revision = await _conditional_store(self._storage).compare_and_set( + token.authority_id, authority, expected_revision=token.revision + ) + if not isinstance(revision, str) or not revision: + raise RuntimeError("Session storage did not acknowledge the approval claim revision.") + self._state["pending"] = None + self.session.state[_APPROVAL_STATE_KEY] = self._state diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_state_store.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_state_store.py index 539287adc74..f55fc23446b 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_state_store.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_state_store.py @@ -1,11 +1,13 @@ # Copyright (c) Microsoft. All rights reserved. +from __future__ import annotations import hashlib import json +import os from abc import ABC, abstractmethod from datetime import datetime -from typing import Any, Generic, Protocol, TypeVar +from typing import Any, Generic, Protocol, TypeVar, runtime_checkable from agent_framework import ( AgentSession, @@ -409,6 +411,35 @@ def get_store( # region Agent session persistence +class _SessionStoreConflict(RuntimeError): + """Signal a lost conditional session write without retrying it.""" + + +@runtime_checkable +class _ConditionalSessionStore(Protocol): + """Require revision-bound writes from stores supporting hosted approvals. + + Implementations must coordinate every writer to a key, including writers in + separate processes. Ordinary ``get``/``set`` and process-local locking do not + establish this capability. Missing entries return ``(None, None)``; existing + entries and successful writes return a non-empty, opaque revision. + Revisions identify one persisted version and must not be reused after writes. + """ + + async def get_with_revision(self, session_id: str) -> tuple[AgentSession | None, str | None]: + """Read an independent snapshot and its exact persisted revision.""" + ... + + async def compare_and_set(self, session_id: str, session: AgentSession, *, expected_revision: str | None) -> str: + """Create only for ``None``, otherwise replace only the exact revision. + + Raise ``RuntimeError`` on conflict; never retry as an unconditional write. + A failed or cancelled write may have committed. Callers must fail closed + rather than assume that retrying protected work is safe. + """ + ... + + class FoundryAgentSessionStore(SessionStore): """Agent session store backed by the `FoundryStateStore`.""" @@ -442,16 +473,70 @@ async def _get_store(self) -> FoundryStateStore: ) async def get(self, session_id: str) -> AgentSession | None: + session, revision = await self.get_with_revision(session_id) + self._etags[session_id] = revision + return session + + async def get_with_revision(self, session_id: str) -> tuple[AgentSession | None, str | None]: + """Read a session and its storage revision without a cached-write token. + + A revision belongs to this particular read, not to this store instance. + Approval claims pass it explicitly to ``compare_and_set``. + """ + SessionStore.validate_session_id(session_id) store = await self._get_store() async with store: item = await store.get_item(session_id, call_id=self.platform_context.call_id) if item is None: - self._etags[session_id] = None - return None + return None, None if not item.etag: raise RuntimeError("Foundry agent session storage returned a loaded session without an ETag.") - self._etags[session_id] = item.etag - return AgentSession.from_dict(item.value) + return AgentSession.from_dict(item.value), item.etag + + async def compare_and_set(self, session_id: str, session: AgentSession, *, expected_revision: str | None) -> str: + """Persist a create-only or exact-revision session transition. + + ``None`` requires an absent entry; a non-empty revision requires that + exact existing entry. Conflicts never fall back to an upsert. An + acknowledgement without a revision is a failure, even if storage wrote + the value. The caller must not dispatch protected work in that case. + + Raises: + ValueError: If the key or expected revision is invalid. + RuntimeError: If the write conflicts or storage acknowledges a write + without an ETag. Local Foundry storage is unsupported: supply a + custom conditional store. + """ + SessionStore.validate_session_id(session_id) + if expected_revision is not None and (not isinstance(expected_revision, str) or not expected_revision): + raise ValueError("expected_revision must be None or a non-empty string.") + if self._scope is None or not os.environ.get("FOUNDRY_HOSTING_ENVIRONMENT"): + raise RuntimeError( + "The default non-hosted Foundry session store cannot atomically claim approvals across processes. " + "Supply a custom session store implementing get_with_revision and compare_and_set " + "with atomic create-only and exact-revision writes." + ) + store = await self._get_store() + async with store: + try: + if expected_revision is None: + result = await store.create_item( + session_id, session.to_dict(), call_id=self.platform_context.call_id + ) + else: + result = await store.set_item( + session_id, + session.to_dict(), + if_match=expected_revision, + call_id=self.platform_context.call_id, + ) + except (FoundryStorageConflictError, FoundryStoragePreconditionError) as exc: + raise _SessionStoreConflict( + "Another request advanced this agent session; reload before writing." + ) from exc + if not result.etag: + raise RuntimeError("Foundry agent session storage did not return an ETag after saving.") + return result.etag async def set(self, session_id: str, session: AgentSession) -> None: store = await self._get_store() diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/approval_helpers.py b/python/packages/foundry_hosting/tests/foundry_hosting/approval_helpers.py new file mode 100644 index 00000000000..de2a8056f51 --- /dev/null +++ b/python/packages/foundry_hosting/tests/foundry_hosting/approval_helpers.py @@ -0,0 +1,152 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Durable conditional-store boundaries for hosted approval regression tests.""" + +from __future__ import annotations + +import asyncio +import json +import sqlite3 +import sys +from contextlib import closing +from pathlib import Path +from uuid import uuid4 + +from agent_framework import AgentSession, Content, SessionStore + +from agent_framework_foundry_hosting._approvals import SessionApprovalState + + +class SqliteSessionStore(SessionStore): + """Use actual database conditional writes shared by independent processes.""" + + def __init__(self, path: Path) -> None: + self.path = path + self.write_count = 0 + self.error_after_commit: BaseException | None = None + with closing(sqlite3.connect(path)) as connection, connection: + connection.execute( + "CREATE TABLE IF NOT EXISTS sessions " + "(key TEXT PRIMARY KEY, payload TEXT NOT NULL, revision TEXT NOT NULL)" + ) + + def _read(self, session_id: str) -> tuple[AgentSession | None, str | None]: + with closing(sqlite3.connect(self.path)) as connection: + row = connection.execute("SELECT payload, revision FROM sessions WHERE key = ?", (session_id,)).fetchone() + return (AgentSession.from_dict(json.loads(row[0])), row[1]) if row else (None, None) + + async def get_with_revision(self, session_id: str) -> tuple[AgentSession | None, str | None]: + return await asyncio.to_thread(self._read, session_id) + + async def get(self, session_id: str) -> AgentSession | None: + session, _ = await self.get_with_revision(session_id) + return session + + def _write(self, session_id: str, payload: str, expected_revision: str | None) -> str: + revision = str(uuid4()) + with closing(sqlite3.connect(self.path)) as connection, connection: + if expected_revision is None: + try: + connection.execute("INSERT INTO sessions VALUES (?, ?, ?)", (session_id, payload, revision)) + except sqlite3.IntegrityError as exc: + raise RuntimeError("Session revision conflict.") from exc + else: + result = connection.execute( + "UPDATE sessions SET payload = ?, revision = ? WHERE key = ? AND revision = ?", + (payload, revision, session_id, expected_revision), + ) + if result.rowcount != 1: + raise RuntimeError("Session revision conflict.") + return revision + + async def compare_and_set(self, session_id: str, session: AgentSession, *, expected_revision: str | None) -> str: + revision = await asyncio.to_thread(self._write, session_id, json.dumps(session.to_dict()), expected_revision) + self.write_count += 1 + if self.error_after_commit is not None: + raise self.error_after_commit + return revision + + async def set(self, session_id: str, session: AgentSession) -> None: + _, revision = await self.get_with_revision(session_id) + await self.compare_and_set(session_id, session, expected_revision=revision) + + async def delete(self, session_id: str) -> None: + await asyncio.to_thread(self._delete, session_id) + + def _delete(self, session_id: str) -> None: + with closing(sqlite3.connect(self.path)) as connection, connection: + connection.execute("DELETE FROM sessions WHERE key = ?", (session_id,)) + + +def approval_request(index: int = 0) -> Content: + call = Content.from_function_call( + call_id=f"call-{index}", + name="protected", + arguments={"index": index}, + hosted=True, + additional_properties={"provider": {"type": "message", "opaque_id": "original"}}, + ) + return Content.from_function_approval_request(f"approval-{index}", call) + + +async def pending_session(store: SqliteSessionStore, count: int = 2) -> AgentSession: + session = AgentSession(session_id="original-session") + state = SessionApprovalState(session, store, response_id="owner-response") + for index in range(count): + await state.save_approval_request(f"wire-{index}", approval_request(index)) + await state.seal() + await store.set("response-alias", session) + await store.set("conversation-alias", session) + return session + + +async def claim_stored_batch(path: str) -> None: + store = SqliteSessionStore(Path(path)) + session = await store.get("response-alias") + assert session is not None + state = SessionApprovalState(session, store) + token = await state.preflight(["wire-0", "wire-1"]) + assert token is not None + print("ready", flush=True) # noqa: T201 - subprocess barrier protocol + await asyncio.to_thread(sys.stdin.readline) + try: + await state.claim(token, response_id=str(uuid4())) + except RuntimeError: + print("conflict", flush=True) # noqa: T201 - subprocess result protocol + else: + print("claimed", flush=True) # noqa: T201 - subprocess result protocol + + +async def race_claims_in_processes(path: Path) -> list[str]: + script = ( + "import asyncio,sys; " + "sys.path.insert(0,sys.argv[1]); " + "from approval_helpers import claim_stored_batch; " + "asyncio.run(claim_stored_batch(sys.argv[2]))" + ) + processes = [ + await asyncio.create_subprocess_exec( + sys.executable, + "-c", + script, + str(Path(__file__).parent), + str(path), + stdin=asyncio.subprocess.PIPE, + stdout=asyncio.subprocess.PIPE, + stderr=asyncio.subprocess.PIPE, + ) + for _ in range(2) + ] + try: + for process in processes: + assert process.stdout is not None + assert await asyncio.wait_for(process.stdout.readline(), 30) == b"ready\n" + results = await asyncio.gather(*(process.communicate(b"go\n") for process in processes)) + for process, (_, error) in zip(processes, results, strict=True): + assert process.returncode == 0, error.decode() + return sorted(output.decode().strip() for output, _ in results) + finally: + for process in processes: + if process.returncode is None: + process.kill() + await process.wait() diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_session_approvals.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_session_approvals.py new file mode 100644 index 00000000000..4d1e181f115 --- /dev/null +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_session_approvals.py @@ -0,0 +1,252 @@ +# Copyright (c) Microsoft. All rights reserved. + +from __future__ import annotations + +import asyncio +import json +from unittest.mock import AsyncMock + +import pytest +from agent_framework import AgentSession, SessionStore + +from agent_framework_foundry_hosting._approvals import _APPROVAL_STATE_KEY, SessionApprovalState + +from .approval_helpers import ( # pyrefly: ignore[missing-import] - pytest's importlib namespace + SqliteSessionStore, + approval_request, + pending_session, + race_claims_in_processes, +) + + +async def test_batch_is_not_persisted_until_sealed(tmp_path) -> None: + store = SqliteSessionStore(tmp_path / "sessions.db") + session = AgentSession() + state = SessionApprovalState(session, store, response_id="response") + await state.save_approval_request("wire", approval_request()) + assert store.write_count == 0 + assert _APPROVAL_STATE_KEY not in session.state + await state.seal() + assert store.write_count == 1 + restored = AgentSession.from_dict(session.to_dict()) + history = SessionApprovalState(restored, store) + assert await history.load_approval_request("wire") == approval_request() + assert await history.preflight(["wire"]) is not None + + +async def test_history_roundtrip_preserves_provider_content_without_type_rehydration(tmp_path) -> None: + store = SqliteSessionStore(tmp_path / "sessions.db") + await pending_session(store) + session = await store.get("response-alias") + assert session is not None + content = await SessionApprovalState(session, store).load_approval_request("wire-0") + assert content == approval_request() + assert content.id == "approval-0" + assert content.function_call is not None + assert content.function_call.hosted is True + assert content.function_call.additional_properties["provider"] == {"type": "message", "opaque_id": "original"} + + +@pytest.mark.parametrize("ids", [[], ["wire-0"], ["wire-0", "wire-0"], ["wire-0", "foreign"], ["foreign"]]) +async def test_invalid_batch_never_mutates_authority_and_complete_retry_succeeds(tmp_path, ids) -> None: + store = SqliteSessionStore(tmp_path / "sessions.db") + session = await pending_session(store) + state = SessionApprovalState(session, store) + before = store.write_count + with pytest.raises(ValueError, match="complete pending MCP approval batch"): + await state.preflight(ids) + assert store.write_count == before + token = await state.preflight(["wire-1", "wire-0"]) + assert token is not None + assert store.write_count == before + await state.claim(token, response_id="resume") + assert store.write_count == before + 1 + + +async def test_response_and_conversation_aliases_share_one_irreversible_authority(tmp_path) -> None: + store = SqliteSessionStore(tmp_path / "sessions.db") + await pending_session(store) + response = await store.get("response-alias") + conversation = await store.get("conversation-alias") + assert response is not None and conversation is not None and response is not conversation + first = SessionApprovalState(response, store) + second = SessionApprovalState(conversation, store) + token1 = await first.preflight(["wire-0", "wire-1"]) + token2 = await second.preflight(["wire-0", "wire-1"]) + assert token1 is not None and token2 is not None + await first.claim(token1, response_id="first") + with pytest.raises(RuntimeError, match="revision conflict"): + await second.claim(token2, response_id="second") + with pytest.raises(ValueError, match="already claimed"): + await second.preflight(["wire-0", "wire-1"]) + assert await second.load_approval_request("wire-0") == approval_request() + assert await first.preflight([]) is None + + +async def test_two_processes_can_preflight_but_only_one_can_claim(tmp_path) -> None: + store = SqliteSessionStore(tmp_path / "sessions.db") + await pending_session(store) + assert await race_claims_in_processes(store.path) == ["claimed", "conflict"] + + +async def test_expired_canonical_is_not_recreated_from_snapshot(tmp_path) -> None: + store = SqliteSessionStore(tmp_path / "sessions.db") + session = await pending_session(store) + key = session.state[_APPROVAL_STATE_KEY]["pending"]["authority_id"] + await store.delete(key) + before = store.write_count + state = SessionApprovalState(session, store) + with pytest.raises(ValueError, match="missing or expired"): + await state.preflight(["wire-0", "wire-1"]) + assert store.write_count == before + assert await state.load_approval_request("wire-0") == approval_request() + + +@pytest.mark.parametrize("storage", [None, SessionStore()]) +async def test_unstored_and_nonconditional_stores_cannot_record_approvals(storage) -> None: + state = SessionApprovalState(AgentSession(), storage, response_id="response") + with pytest.raises(RuntimeError, match="ordinary get/set is not sufficient"): + await state.save_approval_request("wire", approval_request()) + + +async def test_empty_fresh_session_has_no_pending_authority() -> None: + state = SessionApprovalState(AgentSession(), None) + assert await state.preflight([]) is None + with pytest.raises(ValueError, match="No pending approval"): + await state.preflight(["wire"]) + with pytest.raises(ValueError, match="not in this session"): + await state.load_approval_request("wire") + + +@pytest.mark.parametrize("value", [None, {}, {"version": 2, "history": {}, "pending": None}]) +def test_unsupported_snapshot_format_requires_reset(value) -> None: + session = AgentSession() + session.state[_APPROVAL_STATE_KEY] = value + with pytest.raises(RuntimeError, match="Unsupported approval session"): + SessionApprovalState(session, None) + + +async def test_other_session_cannot_claim_copied_pending_link(tmp_path) -> None: + store = SqliteSessionStore(tmp_path / "sessions.db") + session = await pending_session(store) + other = AgentSession(session_id="other-session") + other.state.update(session.state) + with pytest.raises(ValueError, match="does not match"): + await SessionApprovalState(other, store).preflight(["wire-0", "wire-1"]) + + +async def test_persistence_failure_does_not_publish_snapshot_link(tmp_path, monkeypatch) -> None: + store = SqliteSessionStore(tmp_path / "sessions.db") + session = AgentSession() + state = SessionApprovalState(session, store, response_id="response") + await state.save_approval_request("wire", approval_request()) + monkeypatch.setattr(store, "compare_and_set", AsyncMock(side_effect=OSError("storage down"))) + with pytest.raises(OSError, match="storage down"): + await state.seal() + assert _APPROVAL_STATE_KEY not in session.state + + +async def test_cancelled_claim_propagates_and_does_not_clear_local_pending(tmp_path, monkeypatch) -> None: + store = SqliteSessionStore(tmp_path / "sessions.db") + session = await pending_session(store) + state = SessionApprovalState(session, store) + token = await state.preflight(["wire-0", "wire-1"]) + assert token is not None + monkeypatch.setattr(store, "compare_and_set", AsyncMock(side_effect=asyncio.CancelledError)) + with pytest.raises(asyncio.CancelledError): + await state.claim(token, response_id="resume") + assert session.state[_APPROVAL_STATE_KEY]["pending"] is not None + + +async def test_postclaim_failure_does_not_reopen_authority_on_reload(tmp_path) -> None: + store = SqliteSessionStore(tmp_path / "sessions.db") + session = await pending_session(store) + state = SessionApprovalState(session, store) + token = await state.preflight(["wire-0", "wire-1"]) + assert token is not None + await state.claim(token, response_id="crashed-before-dispatch") + # No final session snapshot is saved: a restarted process sees the old alias. + restarted = await SqliteSessionStore(store.path).get("response-alias") + assert restarted is not None + with pytest.raises(ValueError, match="already claimed"): + await SessionApprovalState(restarted, store).preflight(["wire-0", "wire-1"]) + + +async def test_duplicate_output_wire_id_rejects_before_sealing(tmp_path) -> None: + store = SqliteSessionStore(tmp_path / "sessions.db") + state = SessionApprovalState(AgentSession(), store, response_id="response") + await state.save_approval_request("wire", approval_request()) + with pytest.raises(ValueError, match="already exists"): + await state.save_approval_request("wire", approval_request()) + assert store.write_count == 0 + + +async def test_history_limit_fails_explicitly_without_pruning(tmp_path, monkeypatch) -> None: + store = SqliteSessionStore(tmp_path / "sessions.db") + state = SessionApprovalState(AgentSession(), store, response_id="response") + monkeypatch.setattr("agent_framework_foundry_hosting._approvals._MAX_HISTORY_REQUESTS", 1) + await state.save_approval_request("wire-0", approval_request()) + with pytest.raises(RuntimeError, match="history limit reached"): + await state.save_approval_request("wire-1", approval_request(1)) + assert store.write_count == 0 + + +async def test_duplicate_original_approval_cannot_get_another_wire_id(tmp_path) -> None: + store = SqliteSessionStore(tmp_path / "sessions.db") + state = SessionApprovalState(AgentSession(), store, response_id="response") + await state.save_approval_request("wire-0", approval_request()) + with pytest.raises(ValueError, match="Framework approval request ID already exists"): + await state.save_approval_request("wire-1", approval_request()) + assert store.write_count == 0 + + +@pytest.mark.parametrize("error", [OSError("lost acknowledgement"), asyncio.CancelledError()]) +async def test_lost_claim_acknowledgement_never_reopens_persisted_authority(tmp_path, error) -> None: + store = SqliteSessionStore(tmp_path / "sessions.db") + session = await pending_session(store) + state = SessionApprovalState(session, store) + token = await state.preflight(["wire-0", "wire-1"]) + assert token is not None + store.error_after_commit = error + with pytest.raises(type(error)): + await state.claim(token, response_id="uncertain") + assert session.state[_APPROVAL_STATE_KEY]["pending"] is not None + restarted_store = SqliteSessionStore(store.path) + restarted = await restarted_store.get("response-alias") + assert restarted is not None + with pytest.raises(ValueError, match="already claimed"): + await SessionApprovalState(restarted, restarted_store).preflight(["wire-0", "wire-1"]) + + +async def test_history_byte_limit_rejects_without_persistence(tmp_path, monkeypatch) -> None: + store = SqliteSessionStore(tmp_path / "sessions.db") + state = SessionApprovalState(AgentSession(), store, response_id="response") + monkeypatch.setattr("agent_framework_foundry_hosting._approvals._MAX_HISTORY_BYTES", 1) + with pytest.raises(RuntimeError, match="history limit reached"): + await state.save_approval_request("wire", approval_request()) + assert store.write_count == 0 + + +@pytest.mark.parametrize("version", [True, 2, None]) +async def test_unsupported_canonical_version_fails_without_consumption(tmp_path, version) -> None: + store = SqliteSessionStore(tmp_path / "sessions.db") + session = await pending_session(store) + key = session.state[_APPROVAL_STATE_KEY]["pending"]["authority_id"] + authority, revision = await store.get_with_revision(key) + assert authority is not None and revision is not None + authority.state[_APPROVAL_STATE_KEY]["version"] = version + await store.compare_and_set(key, authority, expected_revision=revision) + before = store.write_count + with pytest.raises(RuntimeError, match="Unsupported canonical approval version"): + await SessionApprovalState(session, store).preflight(["wire-0", "wire-1"]) + assert store.write_count == before + + +async def test_history_tampering_does_not_authorize_a_different_call(tmp_path) -> None: + store = SqliteSessionStore(tmp_path / "sessions.db") + session = await pending_session(store) + session.state[_APPROVAL_STATE_KEY]["history"]["wire-0"] = json.dumps(approval_request(9).to_dict()) + before = store.write_count + with pytest.raises(ValueError, match="does not match"): + await SessionApprovalState(session, store).preflight(["wire-0", "wire-1"]) + assert store.write_count == before diff --git a/python/packages/foundry_hosting/tests/test_state_store.py b/python/packages/foundry_hosting/tests/test_state_store.py index 5c622ca1e75..f659e45ec26 100644 --- a/python/packages/foundry_hosting/tests/test_state_store.py +++ b/python/packages/foundry_hosting/tests/test_state_store.py @@ -9,9 +9,14 @@ from agent_framework import AgentSession, Content, WorkflowCheckpoint, WorkflowCheckpointException from agent_framework._workflows._checkpoint_encoding import encode_checkpoint_value from azure.ai.agentserver.core import AgentConfig, FoundryAgentRequestContext -from azure.ai.agentserver.core.storage import FoundryStateStore, FoundryStorageConflictError +from azure.ai.agentserver.core.storage import ( + FoundryStateStore, + FoundryStorageConflictError, + FoundryStoragePreconditionError, +) from agent_framework_foundry_hosting import ContextScopedStoreProvider, StoreProvider +from agent_framework_foundry_hosting._scope import FoundryRequestScope from agent_framework_foundry_hosting._state_store import ( AgentSessionStoreProvider, CheckpointStoreProvider, @@ -19,6 +24,7 @@ FoundryCheckpointStore, FoundryFunctionApprovalStore, FunctionApprovalStoreProvider, + _SessionStoreConflict, ) @@ -576,6 +582,117 @@ async def test_get_missing_agent_session_returns_none() -> None: assert result is None +async def test_revision_reads_do_not_share_the_mutable_etag_cache() -> None: + store = _store() + session = AgentSession() + store.get_item = AsyncMock(return_value=SimpleNamespace(value=session.to_dict(), etag="exact-read")) + storage = FoundryAgentSessionStore(_platform_context()) + with patch( + "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", + new=AsyncMock(return_value=store), + ): + loaded, revision = await storage.get_with_revision("canonical") + assert loaded is not None and loaded.to_dict() == session.to_dict() + assert revision == "exact-read" + assert storage._etags == {} + + +async def test_revision_read_returns_none_only_for_absent_entry() -> None: + store = _store() + store.get_item = AsyncMock(return_value=None) + with patch( + "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", + new=AsyncMock(return_value=store), + ): + assert await FoundryAgentSessionStore(_platform_context()).get_with_revision("missing") == (None, None) + + +@pytest.mark.parametrize("expected_revision", [None, "exact-read"]) +async def test_hosted_conditional_write_uses_explicit_revision_not_cached_token( + monkeypatch: pytest.MonkeyPatch, expected_revision: str | None +) -> None: + monkeypatch.setenv("FOUNDRY_HOSTING_ENVIRONMENT", "hosted") + store = _store() + session = AgentSession() + scope = FoundryRequestScope.from_context(_config(is_hosted=True), _platform_context()) + storage = FoundryAgentSessionStore(_platform_context(), scope=scope) + storage._etags["canonical"] = "unrelated-cached-token" + with patch( + "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", + new=AsyncMock(return_value=store), + ): + revision = await storage.compare_and_set("canonical", session, expected_revision=expected_revision) + if expected_revision is None: + store.create_item.assert_awaited_once_with("canonical", session.to_dict(), call_id="call-1") + store.set_item.assert_not_awaited() + assert revision == "etag-1" + else: + store.set_item.assert_awaited_once_with( + "canonical", session.to_dict(), if_match=expected_revision, call_id="call-1" + ) + store.create_item.assert_not_awaited() + assert revision == "etag-2" + assert storage._etags["canonical"] == "unrelated-cached-token" + + +@pytest.mark.parametrize("conflict", [FoundryStorageConflictError, FoundryStoragePreconditionError]) +async def test_conditional_conflict_preserves_cause_and_never_retries( + monkeypatch: pytest.MonkeyPatch, conflict: type[Exception] +) -> None: + monkeypatch.setenv("FOUNDRY_HOSTING_ENVIRONMENT", "hosted") + store = _store() + error = conflict("conflict") + store.set_item = AsyncMock(side_effect=error) + scope = FoundryRequestScope.from_context(_config(is_hosted=True), _platform_context()) + with ( + patch( + "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", + new=AsyncMock(return_value=store), + ), + pytest.raises(_SessionStoreConflict) as raised, + ): + await FoundryAgentSessionStore(_platform_context(), scope=scope).compare_and_set( + "canonical", AgentSession(), expected_revision="read-revision" + ) + assert raised.value.__cause__ is error + store.set_item.assert_awaited_once() + store.create_item.assert_not_awaited() + + +@pytest.mark.parametrize("expected_revision", [None, "read-revision"]) +async def test_conditional_write_without_acknowledged_revision_fails_closed( + monkeypatch: pytest.MonkeyPatch, expected_revision: str | None +) -> None: + monkeypatch.setenv("FOUNDRY_HOSTING_ENVIRONMENT", "hosted") + store = _store() + store.set_item = AsyncMock(return_value=SimpleNamespace(etag=None)) + store.create_item = AsyncMock(return_value=SimpleNamespace(etag=None)) + scope = FoundryRequestScope.from_context(_config(is_hosted=True), _platform_context()) + with ( + patch( + "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", + new=AsyncMock(return_value=store), + ), + pytest.raises(RuntimeError, match="did not return an ETag"), + ): + await FoundryAgentSessionStore(_platform_context(), scope=scope).compare_and_set( + "canonical", AgentSession(), expected_revision=expected_revision + ) + + +async def test_default_nonhosted_approval_cas_fails_before_backend_access() -> None: + with ( + patch( + "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", new=AsyncMock() + ) as backend, + pytest.raises(RuntimeError, match="custom session store implementing get_with_revision and compare_and_set"), + ): + await FoundryAgentSessionStore(_platform_context()).compare_and_set( + "canonical", AgentSession(), expected_revision=None + ) + backend.assert_not_awaited() + + async def test_delete_agent_session_is_idempotent() -> None: store = _store() From 439847c4ec59fbd20039109e8d6bb576df2a2ba0 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 09:40:12 +0100 Subject: [PATCH 04/55] Use explicit Responses hosting settings --- .../_responses_agent.py | 92 +++++++++---- .../_responses_workflow.py | 30 +++-- .../foundry_hosting/test_native_responses.py | 16 ++- .../tests/test_foundry_hosting_imports.py | 19 ++- .../foundry_hosting/tests/test_responses.py | 127 +++++++++++++++--- .../tests/test_responses_int.py | 4 +- 6 files changed, 219 insertions(+), 69 deletions(-) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py index 1be4e3109b3..2b2c5c06ab1 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py @@ -75,7 +75,6 @@ _reject_busy_conversation, # pyright: ignore[reportPrivateUsage] _set_agent_session, # pyright: ignore[reportPrivateUsage] _SignalledIterator, # pyright: ignore[reportPrivateUsage] - _validate_response_server_options, # pyright: ignore[reportPrivateUsage] consent_url_from_error, ) from ._scope import FoundryRequestScope @@ -84,10 +83,13 @@ OptionsHook, ResponsesRequest, UnsupportedOptions, + build_response_server_options, is_agent, prepare_response_options, + reject_removed_host_settings, resolve_agent, response_run_options, + validate_agent_background_options, validate_agent_source, validate_default_transport_options, validate_request_options, @@ -127,6 +129,14 @@ class _AgentConfiguration: hosted_history: bool +def _validate_agent_defaults( + agent: SupportsAgentRun, *, provider_background: bool, allow_agent_store: bool +) -> None: + validate_agent_background_options(agent, provider_background=provider_background) + if isinstance(agent, RawAgent): + validate_default_transport_options(agent.default_options, allow_agent_store=allow_agent_store) + + def _validate_agent_configuration( agent: SupportsAgentRun, history_source: _HistorySource, @@ -224,13 +234,16 @@ def __init__( agent: AgentSource[ResponsesRequest], *, prefix: str = "", - options: ResponsesServerOptions | None = None, response_store: ResponseProviderProtocol | None = None, agent_session_store_provider: StoreProvider[SessionStore] | None = None, function_approval_store_provider: StoreProvider[FunctionApprovalStore] | None = None, allowed_oauth_consent_origins: Sequence[str] | None = None, history_source: Literal["host_managed", "agent_managed", "inference_service"] = "host_managed", background_source: Literal["host_managed", "inference_service"] = "host_managed", + max_history_items: int | None = None, + sse_keep_alive_interval_seconds: int | None = None, + shutdown_grace_period_seconds: int = 10, + enable_background_recovery: bool = False, prepare_options: OptionsHook | None = None, unsupported_options: UnsupportedOptions = "warn", **kwargs: Any, @@ -247,7 +260,6 @@ def __init__( `WorkflowAgent` instances and factory results are rejected. Use `ResponsesWorkflowHostServer` with a native workflow factory instead. prefix: The URL prefix for the server. - options: Optional server options. response_store: Optional response store for caller-facing persistence and history. agent_session_store_provider: Optional provider for MAF agent session storage. If not provided, a default `AgentSessionStoreProvider` will be used. @@ -284,6 +296,14 @@ def __init__( client into provider background polling and requires `history_source="inference_service"`. Each poll retains the caller's run options and `background=True`; local tools must be idempotent because a crash before the next private token is saved can replay them. + max_history_items: Positive outer history limit for host-managed history. `None` leaves the + installed SDK default unchanged; it does not mean unlimited. + sse_keep_alive_interval_seconds: Positive streaming heartbeat interval. If omitted, the SDK + uses a positive `SSE_KEEPALIVE_INTERVAL` environment value, or disables heartbeats. + shutdown_grace_period_seconds: Positive shutdown wait. The SDK also uses this duration when + DELETE waits for response persistence. Defaults to 10 seconds. + enable_background_recovery: Allow eligible provider-background work to recover after shutdown. + Defaults to `False`; it does not enable background execution or guarantee exactly-once effects. prepare_options: Developer hook to remove or replace caller model options for an agent. unsupported_options: `"warn"` (default), `"error"`, or `"ignore"` when a custom agent cannot accept runtime model options. @@ -306,14 +326,12 @@ def __init__( 3. The server owns the supplied agent instance and may add hosting-specific providers. Do not reuse the same agent with another host or invoke it directly after construction. An agent returned by a callable belongs to that request. - 4. `resilient_background=True` supports regular agents configured with + 4. `enable_background_recovery=True` supports regular agents configured with `history_source="inference_service", background_source="inference_service"`. For provider background, only a saved private continuation token can be polled after a crash; a crash before the token is saved cannot be replayed safely. Other regular-agent runs are not crash-recoverable. - 5. Steering is temporarily unavailable for all agents. `steerable_conversations=True` fails - at construction, before starting a host or enabling the process-wide TaskManager. The current - AgentServer SDK retains futures for rejected turns after the steering queue fills. + 5. Steering is unavailable. The upstream `options` bag and steering settings are not host parameters. 6. A stored, named `"inference_service"` or `"agent_managed"` conversation is claimed in the scoped session store before the agent runs. Conditional writes prevent a concurrent turn from mutating the same provider thread. If the turn fails or is cancelled, start a new conversation instead of @@ -322,26 +340,34 @@ def __init__( Raises: TypeError: If the agent is a `WorkflowAgent`, or native workflow settings are supplied. ValueError: If the history, background, or unsupported-options policy is invalid. - RuntimeError: If the agent configuration conflicts with the selected history source, - `resilient_background=True` is requested for a regular agent without provider background, or - `steerable_conversations=True` is requested while steering is unavailable. + RuntimeError: If the agent configuration conflicts with the selected history or background source. """ + reject_removed_host_settings(kwargs) if "store" in kwargs: raise TypeError("The constructor store= alias was removed; use response_store= instead.") - _validate_response_server_options(options) - if history_source not in ("host_managed", "agent_managed", "inference_service"): - raise ValueError("history_source must be 'host_managed', 'agent_managed', or 'inference_service'.") - if background_source not in ("host_managed", "inference_service"): - raise ValueError("background_source must be 'host_managed' or 'inference_service'.") - if background_source == "inference_service" and history_source != "inference_service": - raise ValueError("Provider background requires history_source='inference_service'.") - if background_source == "inference_service" and options and options.steerable_conversations: - raise ValueError("Provider background and steerable_conversations cannot be combined.") if {"workflow", "parse_input", "parse_response", "checkpoint_store_provider"}.intersection(kwargs): raise TypeError("Use ResponsesWorkflowHostServer for native workflows and checkpoint storage.") validate_agent_source(agent) + if prepare_options is not None and not callable(prepare_options): + raise TypeError("prepare_options must be a callable.") + unsupported_options = validate_unsupported_options(unsupported_options) + options = build_response_server_options( + is_workflow=False, + history_source=history_source, + background_source=background_source, + max_history_items=max_history_items, + sse_keep_alive_interval_seconds=sse_keep_alive_interval_seconds, + shutdown_grace_period_seconds=shutdown_grace_period_seconds, + enable_background_recovery=enable_background_recovery, + ) resolved_agent = agent if is_agent(agent) else None + if resolved_agent is not None: + _validate_agent_defaults( + resolved_agent, + provider_background=background_source == "inference_service", + allow_agent_store=history_source == "agent_managed", + ) configuration = ( _validate_agent_configuration(resolved_agent, history_source, options, background_source=background_source) if resolved_agent is not None @@ -356,23 +382,18 @@ def __init__( store=response_store, **kwargs, ) - if options and options.steerable_conversations: - from azure.ai.agentserver.core.tasks import set_resilient_tasks_enabled - - set_resilient_tasks_enabled(True) - self._agent_source = agent self._agent = resolved_agent self._configuration = configuration self._history_source: _HistorySource = history_source self._background_source: Literal["host_managed", "inference_service"] = background_source self._prepare_options = prepare_options - self._unsupported_options = validate_unsupported_options(unsupported_options) + self._unsupported_options = unsupported_options self._host_options = options self._uses_agent_server_history = ( configuration.agent_server_history if configuration is not None else history_source == "host_managed" ) - self._resilient_background = bool(options and options.resilient_background) + self._resilient_background = enable_background_recovery if resolved_agent is not None and configuration is not None: _initialize_agent_history(resolved_agent, configuration) @@ -456,6 +477,14 @@ async def _handle_response( raise _PublicResponseFailure(exc) from None agent = await resolve_agent(self._agent_source, hosted_request) try: + provider_background = ( + self._background_source == "inference_service" and request.get("background") is True + ) + _validate_agent_defaults( + agent, + provider_background=provider_background, + allow_agent_store=self._history_source == "agent_managed" and request.get("store") is not False, + ) configuration = self._configuration or _validate_agent_configuration( agent, self._history_source, self._host_options, background_source=self._background_source ) @@ -466,6 +495,11 @@ async def _handle_response( await prepare_response_options(hosted_request, self._prepare_options) try: validate_request_options(hosted_request.options) + _validate_agent_defaults( + agent, + provider_background=provider_background, + allow_agent_store=self._history_source == "agent_managed" and request.get("store") is not False, + ) except (TypeError, ValueError) as exc: raise _PublicResponseFailure(exc) from None except Exception as exc: @@ -963,8 +997,10 @@ async def _handle_inner_agent( "messages": messages, "session": session, } - chat_options = cast(ChatOptions[Any], dict(hosted_request.options)) + chat_options = dict(hosted_request.options) are_options_set = bool(chat_options) + if self._background_source == "inference_service": + chat_options["background"] = provider_background if configuration.agent_server_history: if configuration.client_stores_by_default: # The response provider already owns the transcript used for this run. Keep a @@ -1045,7 +1081,7 @@ async def _handle_inner_agent( messages=messages, session=session, session_storage=session_storage, - options=chat_options, + options=cast(ChatOptions[Any], chat_options), context=context, cancellation_signal=cancellation_signal, emitted_output_count=output_count, diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py index 56198c37041..6a323eb70b9 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py @@ -32,7 +32,7 @@ from agent_framework._telemetry import mark_feature_used from anyio import CancelScope from azure.ai.agentserver.core import get_request_context -from azure.ai.agentserver.responses import ResponseContext, ResponseProviderProtocol, ResponsesServerOptions +from azure.ai.agentserver.responses import ResponseContext, ResponseProviderProtocol from azure.ai.agentserver.responses._id_generator import IdGenerator from azure.ai.agentserver.responses.aio import ResponseEventStream from azure.ai.agentserver.responses.hosting import ResponsesAgentServerHost @@ -54,7 +54,6 @@ _OutputItemTracker, # pyright: ignore[reportPrivateUsage] _request_without_reserved_metadata, # pyright: ignore[reportPrivateUsage] _SignalledIterator, # pyright: ignore[reportPrivateUsage] - _validate_response_server_options, # pyright: ignore[reportPrivateUsage] ) from ._scope import FoundryRequestScope from ._shared import ( @@ -63,8 +62,10 @@ WorkflowResolver, WorkflowSource, WorkflowTurn, + build_response_server_options, prepare_response_options, prepare_workflow_kwargs, + reject_removed_host_settings, response_run_options, validate_request_options, validate_workflow_source, @@ -337,11 +338,13 @@ def __init__( *, parse_input: Callable[[ResponsesRequest], WorkflowTurn[Any] | Awaitable[WorkflowTurn[Any]]], prefix: str = "", - options: ResponsesServerOptions | None = None, response_store: ResponseProviderProtocol | None = None, checkpoint_store_provider: ContextScopedStoreProvider[CheckpointStorage] | None = None, prepare_options: OptionsHook | None = None, allowed_oauth_consent_origins: Sequence[str] | None = None, + sse_keep_alive_interval_seconds: int | None = None, + shutdown_grace_period_seconds: int = 10, + enable_background_recovery: bool = False, **kwargs: Any, ) -> None: """Create a native workflow host with explicit parsing and checkpoint ownership. @@ -356,8 +359,6 @@ def __init__( parse_input: Sync or async parser of this turn's `ResponsesRequest`. Return a typed `WorkflowTurn(input=...)` or a complete batch of validated pending `responses`. prefix: URL prefix for Responses routes. - options: AgentServer options, including outer background recovery. Steering remains disabled. - Outer background execution does not enable provider background on workflow agents. response_store: Backend for caller-facing Responses persistence, not the wire-level `store` flag. checkpoint_store_provider: Scoped checkpoint storage. Defaults to `CheckpointStoreProvider`. Native workflow history and pending replies are checkpoint-owned, not agent-session-owned. @@ -366,13 +367,20 @@ def __init__( This does not enable inner provider background or service-owned history. allowed_oauth_consent_origins: Optional exact HTTPS origins for consent links. Omission retains safe-HTTPS validation; an empty sequence rejects all origins. + sse_keep_alive_interval_seconds: Positive streaming heartbeat interval. If omitted, the SDK + uses a positive `SSE_KEEPALIVE_INTERVAL` environment value, or disables heartbeats. + shutdown_grace_period_seconds: Positive shutdown wait, also used by the SDK when DELETE waits + for response persistence. Defaults to 10 seconds. + enable_background_recovery: Allow checkpoint-backed outer workflow recovery. Defaults to `False`. + Outer background execution does not enable provider background on workflow agents. **kwargs: Additional AgentServer host settings forwarded to the SDK. Raises: TypeError: If the workflow is not a request-aware factory, the parser is not callable, or an agent-only setting is supplied. - RuntimeError: If steering is requested while unavailable. + ValueError: If a supported setting has an invalid value. """ + reject_removed_host_settings(kwargs) if "parse_response" in kwargs: raise TypeError("parse_response was renamed to parse_input.") forbidden = { @@ -382,6 +390,7 @@ def __init__( "history_source", "background_source", "unsupported_options", + "max_history_items", "store", }.intersection(kwargs) if forbidden: @@ -391,8 +400,13 @@ def __init__( raise TypeError("parse_input must be a callable.") if prepare_options is not None and not callable(prepare_options): raise TypeError("prepare_options must be a callable.") - _validate_response_server_options(options) allowed_origins = _normalize_allowed_oauth_consent_origins(allowed_oauth_consent_origins) + options = build_response_server_options( + is_workflow=True, + sse_keep_alive_interval_seconds=sse_keep_alive_interval_seconds, + shutdown_grace_period_seconds=shutdown_grace_period_seconds, + enable_background_recovery=enable_background_recovery, + ) super().__init__(prefix=prefix, options=options, store=response_store, **kwargs) self._resolver = WorkflowResolver(workflow) self._parse_input = parse_input @@ -400,7 +414,7 @@ def __init__( CheckpointStoreProvider() if checkpoint_store_provider is None else checkpoint_store_provider ) self._prepare_options = prepare_options - self._resilient_background = bool(options and options.resilient_background) + self._resilient_background = enable_background_recovery self._allowed_origins = allowed_origins self._bind_streaming_route( prefix=prefix, diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py index ac85b057754..715811eea49 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py @@ -35,7 +35,7 @@ ) from agent_framework._workflows._agent_utils import prepare_executor_run_kwargs from agent_framework._workflows._const import RESOLVED_WORKFLOW_RUN_KWARGS_KEY, WORKFLOW_RUN_KWARGS_KEY -from azure.ai.agentserver.responses import FileResponseStore, InMemoryResponseProvider, ResponsesServerOptions +from azure.ai.agentserver.responses import FileResponseStore, InMemoryResponseProvider from azure.ai.agentserver.responses._id_generator import IdGenerator from pydantic import BaseModel @@ -486,7 +486,7 @@ async def test_unsupported_shared_workflow_is_not_cloned_or_unwrapped() -> None: ResponsesWorkflowHostServer( workflow=cast(Any, _build()), parse_input=_parse, - options=ResponsesServerOptions(resilient_background=True), + enable_background_recovery=True, ) @@ -1065,8 +1065,13 @@ async def update_response(self, response: Any, **kwargs: Any) -> None: provider = FailingCheckpointStore(storage_dir=tmp_path / "responses") factory = _progress_factory(started, release, stopped) - options = ResponsesServerOptions(resilient_background=True, shutdown_grace_period_seconds=1) - server = _server(factory, parser=_parse_count, response_store=provider, options=options) + server = _server( + factory, + parser=_parse_count, + response_store=provider, + enable_background_recovery=True, + shutdown_grace_period_seconds=1, + ) paired = asyncio.Event() original = HostedWorkflowRun.stage @@ -1103,7 +1108,8 @@ async def stage(run: HostedWorkflowRun, snapshot: Any, **kwargs: Any) -> None: factory, parser=_parse_count, response_store=provider, - options=ResponsesServerOptions(resilient_background=True, shutdown_grace_period_seconds=1), + enable_background_recovery=True, + shutdown_grace_period_seconds=1, ) async with ( restarted.router.lifespan_context(restarted), diff --git a/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py b/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py index e3aa46d553f..6a32e94fe98 100644 --- a/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py +++ b/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py @@ -208,12 +208,23 @@ def test_legacy_parser_names_are_not_silently_forwarded_to_sdk(name: str, legacy initialize.assert_not_called() -def test_responses_workflow_host_preserves_steering_guard() -> None: - from azure.ai.agentserver.responses import ResponsesServerOptions +def test_responses_workflow_host_rejects_removed_options() -> None: + with pytest.raises(TypeError, match="options is no longer a supported host setting"): + cast(Any, hosting.ResponsesWorkflowHostServer)( + workflow=lambda _: None, + parse_input=lambda _: None, + options=None, + ) + - with pytest.raises(RuntimeError, match="steerable_conversations=True is temporarily unavailable"): +def test_responses_workflow_host_rejects_agent_history_limit_even_when_none() -> None: + with ( + patch("azure.ai.agentserver.responses.hosting.ResponsesAgentServerHost.__init__") as initialize, + pytest.raises(TypeError, match="max_history_items"), + ): cast(Any, hosting.ResponsesWorkflowHostServer)( workflow=lambda _: None, parse_input=lambda _: None, - options=ResponsesServerOptions(steerable_conversations=True), + max_history_items=None, ) + initialize.assert_not_called() diff --git a/python/packages/foundry_hosting/tests/test_responses.py b/python/packages/foundry_hosting/tests/test_responses.py index 2b59556a643..9902a7e5009 100644 --- a/python/packages/foundry_hosting/tests/test_responses.py +++ b/python/packages/foundry_hosting/tests/test_responses.py @@ -1614,6 +1614,89 @@ def test_stringify_mcp_output_extracts_only_text_content_mappings(self) -> None: class TestResponsesHostServerInit: + @pytest.mark.parametrize( + "name", + [ + "options", + "default_fetch_history_count", + "default_model", + "create_span_hook", + "additional_server_version", + "steerable_conversations", + "resilient_background", + ], + ) + def test_removed_host_setting_fails_before_sdk_or_agent_mutation(self, name: str) -> None: + agent = _make_agent() + with ( + patch("azure.ai.agentserver.responses.hosting.ResponsesAgentServerHost.__init__") as initialize, + pytest.raises(TypeError, match=name), + ): + ResponsesHostServer(agent, **{name: None}) + initialize.assert_not_called() + assert agent.context_providers == [] + assert agent.default_options == {} + + @pytest.mark.parametrize( + ("setting", "value", "error"), + [ + ("max_history_items", True, TypeError), + ("max_history_items", 0, ValueError), + ("sse_keep_alive_interval_seconds", False, TypeError), + ("sse_keep_alive_interval_seconds", 0, ValueError), + ("shutdown_grace_period_seconds", True, TypeError), + ("shutdown_grace_period_seconds", 0, ValueError), + ("enable_background_recovery", 1, TypeError), + ], + ) + def test_invalid_host_setting_fails_before_sdk_or_agent_mutation( + self, setting: str, value: Any, error: type[Exception] + ) -> None: + agent = _make_agent() + with ( + patch("azure.ai.agentserver.responses.hosting.ResponsesAgentServerHost.__init__") as initialize, + pytest.raises(error, match=setting), + ): + ResponsesHostServer(agent, **{setting: value}) + initialize.assert_not_called() + assert agent.context_providers == [] + + def test_history_limit_is_an_explicit_host_managed_override(self) -> None: + default = _make_server(_make_agent()) + limited = _make_server(_make_agent(), max_history_items=3) + assert default._host_options.default_fetch_history_count == ( # pyright: ignore[reportPrivateUsage] + ResponsesServerOptions().default_fetch_history_count + ) + assert limited._host_options.default_fetch_history_count == 3 # pyright: ignore[reportPrivateUsage] + with pytest.raises(ValueError, match="host_managed"): + _make_server(_make_agent(), history_source="agent_managed", max_history_items=3) + + @pytest.mark.parametrize("env", [None, "0", "3"]) + @pytest.mark.parametrize("explicit", [None, 5]) + def test_heartbeat_precedence( + self, monkeypatch: pytest.MonkeyPatch, env: str | None, explicit: int | None + ) -> None: + if env is None: + monkeypatch.delenv("SSE_KEEPALIVE_INTERVAL", raising=False) + else: + monkeypatch.setenv("SSE_KEEPALIVE_INTERVAL", env) + host = _make_server(_make_agent(), sse_keep_alive_interval_seconds=explicit) + assert host._endpoint._runtime_options.sse_keep_alive_interval_seconds == ( # pyright: ignore[reportPrivateUsage] + explicit if explicit is not None else (int(env) if env and int(env) > 0 else None) + ) + + def test_hidden_provider_background_fails_before_sdk_and_agent_mutation(self) -> None: + agent = _make_agent() + agent.default_options = {"background": True} + with ( + patch("azure.ai.agentserver.responses.hosting.ResponsesAgentServerHost.__init__") as initialize, + pytest.raises(ValueError, match="outer background"), + ): + ResponsesHostServer(agent) + initialize.assert_not_called() + assert agent.default_options == {"background": True} + assert agent.context_providers == [] + def test_rejects_workflow_agent_before_sdk_construction(self) -> None: agent = _WorkflowAgentMock() with ( @@ -1742,10 +1825,10 @@ def test_failed_init_does_not_mutate_agent(self) -> None: default_options={"store": True}, ) - with pytest.raises(RuntimeError, match="resilient_background"): + with pytest.raises(ValueError, match="enable_background_recovery"): ResponsesHostServer( agent, - options=ResponsesServerOptions(resilient_background=True), + enable_background_recovery=True, ) assert agent.default_options["store"] is True @@ -1755,15 +1838,15 @@ def test_init_rejects_resilient_background_for_non_workflow_agent(self, tmp_path agent = _make_agent( response=AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("hi")])]) ) - with pytest.raises(RuntimeError, match="resilient_background"): + with pytest.raises(ValueError, match="enable_background_recovery"): ResponsesHostServer( agent, response_store=FileResponseStore(storage_dir=tmp_path), - options=ResponsesServerOptions(resilient_background=True), + enable_background_recovery=True, ) def test_init_rejects_steerable_conversations(self) -> None: - with pytest.raises(RuntimeError, match="steerable_conversations=True is temporarily unavailable"): + with pytest.raises(TypeError, match="options is no longer a supported host setting"): ResponsesHostServer( _make_agent(), response_store=InMemoryResponseProvider(), @@ -1774,7 +1857,7 @@ def test_steering_rejected_before_enabling_task_manager_or_starting_host(self) - agent_factory = MagicMock() def construct(_turn: int) -> str: - with pytest.raises(RuntimeError, match="steerable_conversations=True is temporarily unavailable") as error: + with pytest.raises(TypeError, match="options is no longer a supported host setting") as error: ResponsesHostServer( agent=agent_factory, options=ResponsesServerOptions(steerable_conversations=True), @@ -1789,7 +1872,7 @@ def construct(_turn: int) -> str: failures = list(executor.map(construct, range(24))) assert len(failures) == 24 - assert all("Azure/azure-sdk-for-python#49233" in failure for failure in failures) + assert all("options is no longer a supported host setting" in failure for failure in failures) enable.assert_not_called() base_init.assert_not_called() agent_factory.assert_not_called() @@ -1798,7 +1881,7 @@ async def test_non_steerable_background_still_uses_outer_response_id(self) -> No agent = _make_agent( stream_updates=[AgentResponseUpdate(contents=[Content.from_text("finished")], role="assistant")] ) - server = _make_server(agent, options=ResponsesServerOptions(steerable_conversations=False)) + server = _make_server(agent) async with httpx.AsyncClient(transport=httpx.ASGITransport(app=server), base_url="http://test") as http: pending = await http.post("/responses", json={"input": "hello", "store": True, "background": True}) @@ -1819,7 +1902,7 @@ def test_provider_background_rejects_steering_and_wrong_history_source(self) -> agent = Agent(client=_ServiceStorageRecordingClient()) with pytest.raises(ValueError, match="history_source='inference_service'"): _make_server(agent, background_source="inference_service") - with pytest.raises(RuntimeError, match="temporarily unavailable"): + with pytest.raises(TypeError, match="options is no longer a supported host setting"): _make_server( agent, history_source="inference_service", @@ -2529,7 +2612,7 @@ async def run(messages: Any = None, *, session: AgentSession, **kwargs: Any) -> session_store=SessionStore(), history_source="inference_service", background_source="inference_service", - options=ResponsesServerOptions(resilient_background=True), + enable_background_recovery=True, response_store=FileResponseStore(storage_dir=tmp_path), ) request = CreateResponse(input="hello", store=True, background=True) @@ -2589,7 +2672,7 @@ async def run( session_store=store, history_source="inference_service", background_source="inference_service", - options=ResponsesServerOptions(resilient_background=True), + enable_background_recovery=True, response_store=FileResponseStore(storage_dir=tmp_path), ) request = CreateResponse(input="hello", store=True, background=True, temperature=0.35) @@ -2663,7 +2746,7 @@ async def run( session_store=store, history_source="inference_service", background_source="inference_service", - options=ResponsesServerOptions(resilient_background=True), + enable_background_recovery=True, response_store=FileResponseStore(storage_dir=tmp_path), ) context = ResponseContext( @@ -2699,7 +2782,7 @@ async def test_provider_recovery_without_saved_token_does_not_restart_job( session_store=SessionStore(), history_source="inference_service", background_source="inference_service", - options=ResponsesServerOptions(resilient_background=True), + enable_background_recovery=True, response_store=FileResponseStore(storage_dir=tmp_path), ) request = CreateResponse(input="hello", store=True, background=True) @@ -2742,7 +2825,7 @@ async def run( session_store=store, history_source="inference_service", background_source="inference_service", - options=ResponsesServerOptions(resilient_background=True), + enable_background_recovery=True, response_store=FileResponseStore(storage_dir=tmp_path), ) request = CreateResponse( @@ -2774,7 +2857,7 @@ async def run( session_store=store, history_source="inference_service", background_source="inference_service", - options=ResponsesServerOptions(resilient_background=True), + enable_background_recovery=True, response_store=FileResponseStore(storage_dir=tmp_path), ) recovered_context = ResponseContext(response_id="outer-recover", mode_flags=MagicMock()) @@ -2824,7 +2907,7 @@ def make_host() -> ResponsesHostServer: agent, history_source="inference_service", background_source="inference_service", - options=ResponsesServerOptions(resilient_background=True), + enable_background_recovery=True, response_store=FileResponseStore(storage_dir=tmp_path), ) @@ -2910,7 +2993,7 @@ def make_host() -> ResponsesHostServer: agent, history_source="inference_service", background_source="inference_service", - options=ResponsesServerOptions(resilient_background=True), + enable_background_recovery=True, response_store=FileResponseStore(storage_dir=tmp_path), ) @@ -3100,7 +3183,7 @@ async def set(self, session_id: str, session: AgentSession) -> None: session_store=store, history_source="inference_service", background_source="inference_service", - options=ResponsesServerOptions(resilient_background=True), + enable_background_recovery=True, response_store=FileResponseStore(storage_dir=tmp_path), ) context = ResponseContext(response_id="outer-tool-response", mode_flags=MagicMock()) @@ -3243,7 +3326,7 @@ async def sleep(_seconds: float) -> None: session_store=store, history_source="inference_service", background_source="inference_service", - options=ResponsesServerOptions(resilient_background=True), + enable_background_recovery=True, response_store=FileResponseStore(storage_dir=tmp_path), ) response_id = f"outer-{stage}-{interruption}" @@ -3359,7 +3442,7 @@ def make_host() -> ResponsesHostServer: agent, history_source="inference_service", background_source="inference_service", - options=ResponsesServerOptions(resilient_background=True), + enable_background_recovery=True, response_store=FileResponseStore(storage_dir=tmp_path), ) @@ -3468,7 +3551,7 @@ def make_host() -> ResponsesHostServer: session_store=store, history_source="inference_service", background_source="inference_service", - options=ResponsesServerOptions(resilient_background=True), + enable_background_recovery=True, response_store=FileResponseStore(storage_dir=tmp_path), ) @@ -3547,7 +3630,7 @@ async def run( session_store=FailingTokenStore() if phase == "save" else SessionStore(), history_source="inference_service", background_source="inference_service", - options=ResponsesServerOptions(resilient_background=True), + enable_background_recovery=True, response_store=FileResponseStore(storage_dir=tmp_path), ) request = CreateResponse(input="hello", store=True, background=True) diff --git a/python/packages/foundry_hosting/tests/test_responses_int.py b/python/packages/foundry_hosting/tests/test_responses_int.py index 8fc83283720..69dcb35abce 100644 --- a/python/packages/foundry_hosting/tests/test_responses_int.py +++ b/python/packages/foundry_hosting/tests/test_responses_int.py @@ -45,7 +45,7 @@ ) from agent_framework.foundry import FoundryChatClient, FoundryChatOptions from azure.ai.agentserver.core.tasks import set_resilient_tasks_enabled -from azure.ai.agentserver.responses import InMemoryResponseProvider, ResponsesServerOptions +from azure.ai.agentserver.responses import InMemoryResponseProvider from azure.identity import AzureCliCredential from openai import AsyncOpenAI, DefaultAsyncHttpxClient @@ -1069,7 +1069,7 @@ async def parse_input(request: ResponsesRequest) -> WorkflowTurn[list[Message]]: server = ResponsesWorkflowHostServer( workflow=lambda request: build_workflow(sleep_seconds), parse_input=parse_input, - options=ResponsesServerOptions(resilient_background=True), + enable_background_recovery=True, ) server.run(host="127.0.0.1", port=port) From aa0836b19d2c60f1395bf50f1be56f5b38644252 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 09:40:48 +0100 Subject: [PATCH 05/55] Python: Foundry hosting structured invocation-time OAuth consent and read-only approval translation - Toolbox call_tool converts MCP -32006 consent into structured oauth_consent_request plus paired function_result, blocks later protected Toolbox calls in the host scope, sanitizes disallowed consent links. - Approval conversion uses private read-only _ApprovalLookup; tracker uses staging _ApprovalRecorder awaited before yield; missing generated id raises RuntimeError. --- .../_responses_shared.py | 173 +++++++-- .../_toolbox.py | 47 ++- .../test_approval_translation.py | 147 ++++++++ .../test_oauth_consent_invocation.py | 341 ++++++++++++++++++ .../toolbox_consent_helpers.py | 140 +++++++ 5 files changed, 818 insertions(+), 30 deletions(-) create mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/test_approval_translation.py create mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/test_oauth_consent_invocation.py create mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/toolbox_consent_helpers.py diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py index 1298d66ad85..80b1aed70a4 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py @@ -21,8 +21,9 @@ Sequence, ) from contextlib import suppress -from dataclasses import asdict, dataclass, is_dataclass -from typing import Any, Generic, Literal, TypeGuard, TypeVar, cast +from contextvars import ContextVar +from dataclasses import asdict, dataclass, field, is_dataclass +from typing import Any, Generic, Literal, Protocol, TypeGuard, TypeVar, cast from urllib.parse import urlparse from agent_framework import ( @@ -94,12 +95,33 @@ ) from mcp import MCPError -from ._state_store import ( - FunctionApprovalStore, -) - logger = logging.getLogger(__name__) + +class _ApprovalLookup(Protocol): + """Read-only approval-request lookup used when converting stored history back to messages. + + Implementations must not consume, claim, or otherwise change approval authority; the host validates and claims + approval batches separately before protected execution. + """ + + async def load_approval_request(self, approval_request_id: str) -> Content: + """Return the original ``function_approval_request`` content for a public approval request ID.""" + ... + + +class _ApprovalRecorder(Protocol): + """Approval-request recorder used by the output tracker before an approval item is yielded. + + Implementations may only stage the mapping; the host must keep the yielded events buffered until the staged + approval batch is durable. + """ + + async def save_approval_request(self, approval_request_id: str, request: Content) -> None: + """Record the original ``function_approval_request`` content under its generated public ID.""" + ... + + _MODEL_OUTPUT_KIND_KEY = "model_output_kind" _MODEL_OUTPUT_REFUSAL = "refusal" _HOSTED_PROVIDER_STATE_KEY = "_foundry_provider_background" @@ -786,6 +808,103 @@ def consent_url_from_error(exc: BaseException) -> list[ConsentError] | None: return None +_REMOTE_ERROR_PREFIX = "Request failed (remote): " + +OAUTH_CONSENT_REQUIRED_RESULT = ( + "Error: OAuth consent is required. This tool invocation did not complete. The user must authorize access " + "before this tool can be invoked in a later request." +) +OAUTH_CONSENT_NOT_EXECUTED_RESULT = ( + "Error: This tool invocation was not executed because another tool requires OAuth consent. The user must " + "authorize access before protected tools can be invoked in a later request." +) + + +def tool_call_consent_url_from_error(exc: BaseException) -> str | None: + """Return the consent URL from a Foundry Toolbox ``tools/call`` consent error, if ``exc`` wraps one. + + The gateway reports invocation-time consent as MCP error ``-32006``. The URL is read from a string + ``error.data["detail"]``; when ``detail`` is absent, the error message is used after removing the + ``"Request failed (remote): "`` prefix. A ``detail`` value that is present but not a string yields an empty + URL so the caller fails closed. The ``tools/list`` JSON ``errors`` shape is also accepted. + + Args: + exc: The exception to inspect. ``exc`` itself or one of its ``args`` must be the ``MCPError``. + + Returns: + The raw consent URL (not yet validated), an empty string when the payload is malformed, or ``None`` when + ``exc`` is not a consent error. + """ + inner_exception = ( + exc if isinstance(exc, MCPError) else next((arg for arg in exc.args if isinstance(arg, MCPError)), None) + ) + if inner_exception is None or inner_exception.code != CONSENT_ERROR_CODE: + return None + data = inner_exception.error.data + if isinstance(data, Mapping) and "detail" in data: + detail = cast(Mapping[str, Any], data)["detail"] + return detail.strip() if isinstance(detail, str) else "" + message = inner_exception.error.message or "" + if "{" in message: + listed = consent_url_from_error(Exception(inner_exception)) + return listed[0].consent_url if listed else "" + message = message.removeprefix(_REMOTE_ERROR_PREFIX) + return message.strip() + + +@dataclass +class _ToolboxConsentScope: + """Request-wide invocation-time OAuth consent state shared by all tool-call tasks of one hosted request. + + The scope is a mutable object so state recorded in a copied task context remains visible to the host and to + later tool calls. Hosts must create a fresh scope for every request. + """ + + allowed_origins: frozenset[str] | None = None + consents: list[ConsentError] = field(default_factory=lambda: []) + consent_rejected: bool = False + + @property + def consent_required(self) -> bool: + """Whether a protected tool in this request requires OAuth consent.""" + return bool(self.consents) + + @property + def blocks_toolbox_calls(self) -> bool: + """Whether later Foundry Toolbox calls in this request must not contact the gateway.""" + return self.consent_required or self.consent_rejected + + +_toolbox_consent_scope: ContextVar[_ToolboxConsentScope | None] = ContextVar( + "_foundry_toolbox_consent_scope", default=None +) + + +def _activate_toolbox_consent_scope( # pyright: ignore[reportUnusedFunction] + *, allowed_origins: frozenset[str] | None = None +) -> _ToolboxConsentScope: + """Activate a fresh invocation-time OAuth consent scope in the current context. + + Call this in the request task before the agent run starts and before the first stream item is pulled, so all + tool-call tasks inherit the scope. The scope is intentionally not reset: async generator finalization may run + in a different context, and a fresh scope replaces it for the next request. + + Args: + allowed_origins: Normalized consent origin allowlist from ``_normalize_allowed_oauth_consent_origins``. + + Returns: + The active scope. + """ + scope = _ToolboxConsentScope(allowed_origins=allowed_origins) + _toolbox_consent_scope.set(scope) + return scope + + +def _current_toolbox_consent_scope() -> _ToolboxConsentScope | None: # pyright: ignore[reportUnusedFunction] + """Return the active invocation-time OAuth consent scope, if a host activated one.""" + return _toolbox_consent_scope.get() + + # endregion Foundry Toolbox Auth integration @@ -983,7 +1102,7 @@ async def handle_update( self, update: AgentResponseUpdate, *, - approval_storage: FunctionApprovalStore | None = None, + approval_storage: _ApprovalRecorder | None = None, complete_message: bool = False, ) -> AsyncGenerator[ResponseStreamEvent]: """Process one agent update: note its finish reason, then handle each of its contents. @@ -1008,7 +1127,7 @@ async def handle( content: Content, message_id: str | None = None, *, - approval_storage: FunctionApprovalStore | None = None, + approval_storage: _ApprovalRecorder | None = None, start_new_content_part: bool = False, ) -> AsyncGenerator[ResponseStreamEvent]: """Process a content item, yielding its events. @@ -1019,8 +1138,9 @@ async def handle( change in ``message_id`` across otherwise same-typed text content marks a new logical message and forces the previous output item closed, rather than being merged into it. - approval_storage: Used for content types that fall back to one-shot emission - (anything not recognized as a streaming delta type) to save/load approval requests. + approval_storage: Recorder that receives each ``function_approval_request`` under its generated + public ID before the approval item event is yielded. Recording may only stage the mapping; the + host must buffer yielded approval events until the staged batch is durable. start_new_content_part: Whether text and refusal content start a new independent content part instead of continuing the current streaming occurrence. """ @@ -1281,15 +1401,14 @@ async def handle( if isinstance(item, Mapping) else getattr(item, "id", None) ) - if isinstance(approval_request_id, str): - await approval_storage.save_approval_request(approval_request_id, content) - request_saved = True + if not isinstance(approval_request_id, str) or not approval_request_id: + raise RuntimeError( + "The approval request ID could not be extracted from the stream event, " + "so the approval request could not be recorded." + ) + await approval_storage.save_approval_request(approval_request_id, content) + request_saved = True yield event - if approval_storage is not None and not request_saved: - logger.warning( - "Approval request was not saved to approval storage because the approval request ID " - "could not be extracted from the stream event." - ) elif content.type == "oauth_consent_request": for event in self._close(): @@ -1586,13 +1705,13 @@ def _persist_pending_container_file_citations(self) -> None: async def _items_to_messages( # pyright: ignore[reportUnusedFunction] - input_items: Sequence[Item], *, approval_storage: FunctionApprovalStore | None = None + input_items: Sequence[Item], *, approval_storage: _ApprovalLookup | None = None ) -> list[Message]: """Converts a sequence of input items to a list of Messages, one per item. Args: input_items: The input items to convert. - approval_storage: An optional ApprovalStorage instance used to look up + approval_storage: An optional read-only approval lookup used to look up approval requests when converting MCP approval response items. Returns: @@ -1695,14 +1814,14 @@ def _shell_command_output_to_content(output: Mapping[str, Any]) -> Content: async def _item_to_message( item: Item, *, - approval_storage: FunctionApprovalStore | None = None, + approval_storage: _ApprovalLookup | None = None, _item_type_name: Literal["Item", "OutputItem"] = "Item", ) -> Message: """Converts an Item to a Message. Args: item: The Item to convert. - approval_storage: An optional ApprovalStorage instance used to look up + approval_storage: An optional read-only approval lookup used to look up approval requests when converting MCP approval response items. _item_type_name: The item type name to include in unsupported-type errors. @@ -1999,13 +2118,13 @@ async def _item_to_message( async def _output_items_to_messages( # pyright: ignore[reportUnusedFunction] history: Sequence[OutputItem], *, - approval_storage: FunctionApprovalStore | None = None, + approval_storage: _ApprovalLookup | None = None, ) -> list[Message]: """Converts a sequence of OutputItem objects to a list of Message objects. Args: history (Sequence[OutputItem]): The sequence of OutputItem objects to convert. - approval_storage (ApprovalStorage | None, optional): The approval storage to use for + approval_storage (_ApprovalLookup | None, optional): The approval storage to use for resolving MCP approval requests. Defaults to None. Returns: @@ -2017,14 +2136,12 @@ async def _output_items_to_messages( # pyright: ignore[reportUnusedFunction] return messages -async def _output_item_to_message( - item: OutputItem, *, approval_storage: FunctionApprovalStore | None = None -) -> Message: +async def _output_item_to_message(item: OutputItem, *, approval_storage: _ApprovalLookup | None = None) -> Message: """Converts an OutputItem to a Message. Args: item (OutputItem): The OutputItem to convert. - approval_storage (ApprovalStorage | None, optional): The approval storage to use for + approval_storage (_ApprovalLookup | None, optional): The approval storage to use for resolving MCP approval requests. Defaults to None. Returns: diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_toolbox.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_toolbox.py index d9a02501c56..63daf99ebff 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_toolbox.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_toolbox.py @@ -15,6 +15,7 @@ import httpx2 as httpx from agent_framework import ( CachingSkillsSource, + Content, DeduplicatingSkillsSource, MCPSkillsSource, MCPStreamableHTTPTool, @@ -23,7 +24,7 @@ SkillsSourceContext, ) from agent_framework._telemetry import mark_feature_used -from agent_framework.exceptions import ToolExecutionException +from agent_framework.exceptions import ToolExecutionException, UserInputRequiredException from azure.ai.agentserver.core import get_request_context from mcp.types import Tool from typing_extensions import override @@ -34,7 +35,7 @@ from collections.abc import AsyncGenerator, Generator from datetime import timedelta - from agent_framework import Content, Skill + from agent_framework import Skill from agent_framework._mcp import MCPSpecificApproval from azure.core.credentials import AccessToken, TokenCredential from azure.core.credentials_async import AsyncTokenCredential @@ -412,9 +413,51 @@ async def _prepare_for_run(self, kwargs: Mapping[str, Any]) -> None: @override async def call_tool(self, tool_name: str, **kwargs: Any) -> str | list[Content]: + """Call a Toolbox tool and translate invocation-time OAuth consent when a hosted request scope is active. + + Inside a Foundry Responses host request, a gateway ``-32006`` consent error with an allowed HTTPS consent + link raises ``UserInputRequiredException`` carrying a terminal ``function_result`` and an + ``oauth_consent_request``. Later Toolbox calls in the same request return a not-executed result without + contacting the gateway. A rejected consent link raises a sanitized ``ToolExecutionException`` and marks the + request scope so the host fails the response. Outside a hosted request scope, errors propagate unchanged. + """ + from ._responses_shared import ( + OAUTH_CONSENT_NOT_EXECUTED_RESULT, + OAUTH_CONSENT_REQUIRED_RESULT, + ConsentError, + _current_toolbox_consent_scope, # pyright: ignore[reportPrivateUsage] + _is_allowed_oauth_consent_link, # pyright: ignore[reportPrivateUsage] + tool_call_consent_url_from_error, + ) + + scope = _current_toolbox_consent_scope() + if scope is not None and scope.blocks_toolbox_calls: + return OAUTH_CONSENT_NOT_EXECUTED_RESULT token = _strict_toolbox_header_provider.set(True) try: return await super().call_tool(tool_name, **kwargs) + except ToolExecutionException as exc: + if scope is None: + raise + consent_link = tool_call_consent_url_from_error(exc) + if consent_link is None: + raise + if not _is_allowed_oauth_consent_link(consent_link, scope.allowed_origins): + scope.consent_rejected = True + raise ToolExecutionException( + f"Toolbox '{self.name}' returned an OAuth consent link that is not allowed." + ) from None + scope.consents.append(ConsentError(name=self.name, consent_url=consent_link)) + raise UserInputRequiredException( + contents=[ + Content.from_function_result(call_id="", result=OAUTH_CONSENT_REQUIRED_RESULT), + Content.from_oauth_consent_request( + consent_link, + additional_properties={"server_label": self.name}, + ), + ], + message="Foundry Toolbox OAuth consent is required.", + ) from exc finally: _strict_toolbox_header_provider.reset(token) diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_approval_translation.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_approval_translation.py new file mode 100644 index 00000000000..72b429f3386 --- /dev/null +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_approval_translation.py @@ -0,0 +1,147 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Responses approval translation against the read-only lookup and staging recorder protocols.""" + +from __future__ import annotations + +from collections.abc import Mapping +from typing import Any + +import pytest +from agent_framework import Content +from azure.ai.agentserver.responses.aio import ResponseEventStream +from azure.ai.agentserver.responses.models import ( + OutputItemMcpApprovalRequest, + OutputItemMcpApprovalResponseResource, +) + +from agent_framework_foundry_hosting._responses_shared import ( + _output_items_to_messages, + _OutputItemTracker, + _PublicResponseFailure, +) + + +def _approval_request(request_id: str = "orig-1") -> Content: + return Content.from_function_approval_request( + id=request_id, + function_call=Content.from_function_call("call-1", "dangerous", arguments='{"x": 1}'), + ) + + +class _RecordingLookup: + """Read-only lookup that records every access and exposes no mutating method.""" + + def __init__(self, requests: Mapping[str, Content]) -> None: + self._requests = dict(requests) + self.loads: list[str] = [] + + async def load_approval_request(self, approval_request_id: str) -> Content: + self.loads.append(approval_request_id) + return self._requests[approval_request_id] + + +class _OrderedRecorder: + def __init__(self, log: list[str]) -> None: + self._log = log + self.saved: list[tuple[str, Content]] = [] + + async def save_approval_request(self, approval_request_id: str, request: Content) -> None: + self._log.append(f"save:{approval_request_id}") + self.saved.append((approval_request_id, request)) + + +def _event_type(event: Any) -> str: + return event.get("type") if isinstance(event, Mapping) else event.type + + +async def test_history_conversion_only_reads_approval_requests() -> None: + lookup = _RecordingLookup({"wire-1": _approval_request()}) + items = [ + OutputItemMcpApprovalRequest({ + "type": "mcp_approval_request", + "id": "wire-1", + "server_label": "srv", + "name": "dangerous", + "arguments": "{}", + }), + OutputItemMcpApprovalResponseResource({ + "type": "mcp_approval_response", + "id": "resp-1", + "approval_request_id": "wire-1", + "approve": False, + }), + ] + + messages = await _output_items_to_messages(items, approval_storage=lookup) # type: ignore[arg-type] + + assert lookup.loads == ["wire-1", "wire-1"] + assert not hasattr(lookup, "save_approval_request") + assert messages[0].contents[0].type == "function_approval_request" + assert messages[1].contents[0].type == "function_approval_response" + assert messages[1].contents[0].approved is False + + +async def test_history_conversion_rejects_unknown_approval_ids() -> None: + lookup = _RecordingLookup({}) + item = OutputItemMcpApprovalResponseResource({ + "type": "mcp_approval_response", + "id": "resp-1", + "approval_request_id": "missing", + "approve": True, + }) + + with pytest.raises(_PublicResponseFailure): + await _output_items_to_messages([item], approval_storage=lookup) # type: ignore[arg-type] + + +async def test_history_conversion_requires_lookup() -> None: + item = OutputItemMcpApprovalResponseResource({ + "type": "mcp_approval_response", + "id": "resp-1", + "approval_request_id": "wire-1", + "approve": True, + }) + + with pytest.raises(ValueError, match="ApprovalStorage is required"): + await _output_items_to_messages([item]) + + +async def test_tracker_records_approval_before_yielding_its_events() -> None: + stream = ResponseEventStream(response_id="resp_approval") + stream.emit_created() + stream.emit_in_progress() + tracker = _OutputItemTracker(stream) + log: list[str] = [] + recorder = _OrderedRecorder(log) + request = _approval_request() + + async for event in tracker.handle(request, approval_storage=recorder): + log.append(_event_type(event)) + log.extend(_event_type(event) for event in tracker.close()) + + assert len(recorder.saved) == 1 + wire_id, saved = recorder.saved[0] + assert wire_id + assert saved is request + assert log[0] == f"save:{wire_id}" + assert "response.output_item.added" in log[1:] + + +async def test_tracker_fails_explicitly_without_generated_approval_id(monkeypatch: pytest.MonkeyPatch) -> None: + stream = ResponseEventStream(response_id="resp_approval") + stream.emit_created() + stream.emit_in_progress() + + async def _events_without_id(*_: Any, **__: Any) -> Any: + yield {"type": "response.output_item.added", "item": {"type": "mcp_approval_request"}} + + monkeypatch.setattr(stream, "output_item_mcp_approval_request", _events_without_id) + tracker = _OutputItemTracker(stream) + recorder = _OrderedRecorder([]) + + with pytest.raises(RuntimeError, match="approval request ID could not be extracted"): + async for _ in tracker.handle(_approval_request(), approval_storage=recorder): + pass + + assert recorder.saved == [] diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_oauth_consent_invocation.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_oauth_consent_invocation.py new file mode 100644 index 00000000000..05678aa4186 --- /dev/null +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_oauth_consent_invocation.py @@ -0,0 +1,341 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Invocation-time Foundry Toolbox OAuth consent and its Responses translation.""" + +from __future__ import annotations + +import asyncio +import contextvars +from collections.abc import Mapping +from typing import Any + +import pytest +from agent_framework import Agent, Content, Message, UserInputRequiredException +from agent_framework.exceptions import ToolExecutionException +from azure.ai.agentserver.responses.aio import ResponseEventStream +from mcp import MCPError + +from agent_framework_foundry_hosting._responses_shared import ( + OAUTH_CONSENT_NOT_EXECUTED_RESULT, + OAUTH_CONSENT_REQUIRED_RESULT, + _activate_toolbox_consent_scope, + _current_toolbox_consent_scope, + _normalize_allowed_oauth_consent_origins, + _OutputItemTracker, + tool_call_consent_url_from_error, +) + +from .toolbox_consent_helpers import ( + CONSENT_LINK, + BatchToolCallClient, + ToolboxConsentServer, + consent_toolbox, +) + +# region Error parsing + + +@pytest.mark.parametrize( + ("error", "expected"), + [ + (MCPError(-32006, "Request failed (remote): https://c.example.com/x"), "https://c.example.com/x"), + (MCPError(-32006, "ignored", {"detail": " https://d.example.com/y "}), "https://d.example.com/y"), + (MCPError(-32006, "Request failed (remote): https://c.example.com/x", {"detail": 7}), ""), + ( + MCPError( + -32006, + 'tools/list failed {"errors": [{"name": "s", "type": "mcp", "error": ' + '{"code": "CONSENT_REQUIRED", "message": "https://j.example.com/z"}}]}', + ), + "https://j.example.com/z", + ), + (MCPError(-32000, "Request failed (remote): https://c.example.com/x"), None), + ], +) +def test_tool_call_consent_url_from_error_parses_gateway_shapes(error: MCPError, expected: str | None) -> None: + assert tool_call_consent_url_from_error(error) == expected + assert tool_call_consent_url_from_error(ToolExecutionException("call failed", error)) == expected + + +def test_tool_call_consent_url_from_error_ignores_unrelated_exceptions() -> None: + assert tool_call_consent_url_from_error(ToolExecutionException("boom")) is None + assert tool_call_consent_url_from_error(ValueError("https://c.example.com")) is None + + +# endregion + +# region Scope + + +async def test_consent_scope_is_shared_with_copied_task_contexts() -> None: + async def run() -> None: + scope = _activate_toolbox_consent_scope() + + def mark() -> None: + current = _current_toolbox_consent_scope() + assert current is scope + current.consent_rejected = True + + contextvars.copy_context().run(mark) + await asyncio.create_task(asyncio.sleep(0)) + assert scope.blocks_toolbox_calls + + await asyncio.create_task(run()) + assert _current_toolbox_consent_scope() is None + + +# endregion + +# region Toolbox call_tool + + +async def _in_scope(coroutine_factory: Any, *, allowed_origins: frozenset[str] | None = None) -> Any: + async def run() -> Any: + scope = _activate_toolbox_consent_scope(allowed_origins=allowed_origins) + try: + return scope, await coroutine_factory() + except BaseException as exc: # noqa: BLE001 - returned for assertions + return scope, exc + + return await asyncio.create_task(run()) + + +async def test_call_tool_translates_allowed_consent_to_structured_user_input() -> None: + server = ToolboxConsentServer(["secure"]) + server.require_consent("secure") + async with consent_toolbox(server) as toolbox: + scope, result = await _in_scope(lambda: toolbox.call_tool("secure")) + + assert isinstance(result, UserInputRequiredException) + function_result, consent = result.contents + assert function_result.type == "function_result" + assert function_result.result == OAUTH_CONSENT_REQUIRED_RESULT + assert consent.type == "oauth_consent_request" + assert consent.consent_link == CONSENT_LINK + assert consent.user_input_request is True + assert scope.consent_required and scope.blocks_toolbox_calls + assert [(c.name, c.consent_url) for c in scope.consents] == [(toolbox.name, CONSENT_LINK)] + + +async def test_call_tool_uses_structured_detail_for_consent_link() -> None: + server = ToolboxConsentServer(["secure"]) + server.require_consent("secure", message="consent required", data={"detail": CONSENT_LINK}) + async with consent_toolbox(server) as toolbox: + _, result = await _in_scope(lambda: toolbox.call_tool("secure")) + + assert isinstance(result, UserInputRequiredException) + assert result.contents[1].consent_link == CONSENT_LINK + + +@pytest.mark.parametrize( + ("message", "allowed"), + [ + ("Request failed (remote): http://consent.example.com/authorize", None), + ("Request failed (remote): https://user:pw@consent.example.com/authorize", None), + (f"Request failed (remote): {CONSENT_LINK}", ["https://other.example.com"]), + ("Request failed (remote): ", None), + ], +) +async def test_call_tool_rejects_unsafe_or_disallowed_consent_links(message: str, allowed: list[str] | None) -> None: + server = ToolboxConsentServer(["secure"]) + server.require_consent("secure", message=message) + async with consent_toolbox(server) as toolbox: + scope, result = await _in_scope( + lambda: toolbox.call_tool("secure"), + allowed_origins=_normalize_allowed_oauth_consent_origins(allowed), + ) + + assert isinstance(result, ToolExecutionException) + assert not isinstance(result, UserInputRequiredException) + assert "consent.example.com" not in str(result) + assert result.__cause__ is None + assert scope.consent_rejected and not scope.consent_required and scope.blocks_toolbox_calls + + +async def test_call_tool_accepts_consent_link_from_allowed_origin() -> None: + server = ToolboxConsentServer(["secure"]) + server.require_consent("secure") + async with consent_toolbox(server) as toolbox: + _, result = await _in_scope( + lambda: toolbox.call_tool("secure"), + allowed_origins=_normalize_allowed_oauth_consent_origins(["https://consent.example.com"]), + ) + + assert isinstance(result, UserInputRequiredException) + + +async def test_call_tool_blocks_later_toolbox_calls_without_contacting_gateway() -> None: + server = ToolboxConsentServer(["secure", "open"]) + server.require_consent("secure") + async with consent_toolbox(server) as toolbox: + + async def both() -> Any: + with pytest.raises(UserInputRequiredException): + await toolbox.call_tool("secure") + return await toolbox.call_tool("open") + + _, result = await _in_scope(both) + + assert result == OAUTH_CONSENT_NOT_EXECUTED_RESULT + assert server.calls == ["secure"] + + +async def test_call_tool_without_scope_propagates_original_error() -> None: + server = ToolboxConsentServer(["secure"]) + server.require_consent("secure") + async with consent_toolbox(server) as toolbox: + with pytest.raises(ToolExecutionException) as error: + await toolbox.call_tool("secure") + + assert not isinstance(error.value, UserInputRequiredException) + assert tool_call_consent_url_from_error(error.value) == CONSENT_LINK + + +async def test_call_tool_in_scope_propagates_non_consent_errors() -> None: + server = ToolboxConsentServer(["secure"]) + server.consent_errors["secure"] = {"code": -32000, "message": "boom"} + async with consent_toolbox(server) as toolbox: + scope, result = await _in_scope(lambda: toolbox.call_tool("secure")) + + assert isinstance(result, ToolExecutionException) + assert not scope.blocks_toolbox_calls + + +# endregion + +# region Function loop + + +def _function_results(messages: list[Message]) -> dict[str, list[Content]]: + results: dict[str, list[Content]] = {} + for message in messages: + for content in message.contents: + if content.type == "function_result" and content.call_id is not None: + results.setdefault(content.call_id, []).append(content) + return results + + +def _all_contents(messages: list[Message]) -> list[Content]: + return [content for message in messages for content in message.contents] + + +@pytest.mark.parametrize("stream", [False, True]) +async def test_sequential_function_loop_returns_consent_and_blocks_later_calls(stream: bool) -> None: + server = ToolboxConsentServer(["before", "secure", "after"]) + server.require_consent("secure") + async with consent_toolbox(server) as toolbox: + client = BatchToolCallClient([function.name for function in toolbox.functions]) + agent = Agent(client=client, tools=toolbox, default_options={"allow_multiple_tool_calls": True}) + + async def run() -> list[Message]: + client.function_invocation_configuration["allow_concurrent_invocation"] = False # type: ignore[index] + if stream: + response_stream = agent.run("go", stream=True) + async for _ in response_stream: + pass + return list((await response_stream.get_final_response()).messages) + return list((await agent.run("go")).messages) + + scope, messages = await _in_scope(run) + + assert not isinstance(messages, BaseException), messages + assert server.calls == ["before", "secure"] + assert len(client.calls) == 1 + results = _function_results(messages) + assert all(len(items) == 1 for items in results.values()) + assert set(results) == {"call-0", "call-1", "call-2"} + assert results["call-1"][0].result == OAUTH_CONSENT_REQUIRED_RESULT + assert results["call-2"][0].result == OAUTH_CONSENT_NOT_EXECUTED_RESULT + assert "before-result" in str(results["call-0"][0].result) + consents = [c for c in _all_contents(messages) if c.type == "oauth_consent_request"] + assert [c.consent_link for c in consents] == [CONSENT_LINK] + assert scope.consent_required + + +@pytest.mark.parametrize("stream", [False, True]) +async def test_parallel_function_loop_preserves_completed_siblings(stream: bool) -> None: + server = ToolboxConsentServer(["secure", "open"]) + server.require_consent("secure") + async with consent_toolbox(server) as toolbox: + client = BatchToolCallClient([function.name for function in toolbox.functions]) + agent = Agent(client=client, tools=toolbox, default_options={"allow_multiple_tool_calls": True}) + + async def run() -> list[Message]: + if stream: + response_stream = agent.run("go", stream=True) + async for _ in response_stream: + pass + return list((await response_stream.get_final_response()).messages) + return list((await agent.run("go")).messages) + + _, messages = await _in_scope(run) + + assert not isinstance(messages, BaseException), messages + assert len(client.calls) == 1 + results = _function_results(messages) + assert set(results) == {"call-0", "call-1"} + assert all(len(items) == 1 for items in results.values()) + assert results["call-0"][0].result == OAUTH_CONSENT_REQUIRED_RESULT + # Concurrent siblings may already have started; their completed or not-executed result is preserved. + assert results["call-1"][0].result == OAUTH_CONSENT_NOT_EXECUTED_RESULT or "open-result" in str( + results["call-1"][0].result + ) + + +# endregion + +# region Responses translation + + +async def test_tracker_emits_terminal_output_then_consent_and_marks_response_incomplete() -> None: + stream = ResponseEventStream(response_id="resp_consent") + stream.emit_created() + stream.emit_in_progress() + tracker = _OutputItemTracker( + stream, allowed_oauth_consent_origins=_normalize_allowed_oauth_consent_origins(["https://consent.example.com"]) + ) + contents = [ + Content.from_function_call(call_id="call-1", name="secure", arguments="{}"), + Content.from_function_result(call_id="call-1", result=OAUTH_CONSENT_REQUIRED_RESULT), + Content.from_oauth_consent_request(CONSENT_LINK, additional_properties={"server_label": "secure-box"}), + Content.from_function_call(call_id="call-2", name="other", arguments="{}"), + Content.from_function_result(call_id="call-2", result=OAUTH_CONSENT_NOT_EXECUTED_RESULT), + ] + events: list[Any] = [] + for content in contents: + async for event in tracker.handle(content): + events.append(event) + events.extend(tracker.close()) + + done_items = [ + dict(e["item"]) if isinstance(e, Mapping) else e.item.as_dict() + for e in events + if (e.get("type") if isinstance(e, Mapping) else e.type) == "response.output_item.done" + ] + assert [item["type"] for item in done_items] == [ + "function_call", + "function_call_output", + "oauth_consent_request", + "function_call", + "function_call_output", + ] + outputs = {item["call_id"]: item["output"] for item in done_items if item["type"] == "function_call_output"} + assert outputs == {"call-1": OAUTH_CONSENT_REQUIRED_RESULT, "call-2": OAUTH_CONSENT_NOT_EXECUTED_RESULT} + consent = next(item for item in done_items if item["type"] == "oauth_consent_request") + assert consent["consent_link"] == CONSENT_LINK + assert consent["server_label"] == "secure-box" + assert tracker.oauth_consent_requested + + +async def test_tracker_rejects_consent_from_disallowed_origin() -> None: + stream = ResponseEventStream(response_id="resp_consent_rejected") + stream.emit_created() + tracker = _OutputItemTracker( + stream, allowed_oauth_consent_origins=_normalize_allowed_oauth_consent_origins(["https://other.example.com"]) + ) + with pytest.raises(ValueError, match="allowed safe HTTPS"): + async for _ in tracker.handle(Content.from_oauth_consent_request(CONSENT_LINK)): + pass + + +# endregion diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/toolbox_consent_helpers.py b/python/packages/foundry_hosting/tests/foundry_hosting/toolbox_consent_helpers.py new file mode 100644 index 00000000000..71bb3c3afd7 --- /dev/null +++ b/python/packages/foundry_hosting/tests/foundry_hosting/toolbox_consent_helpers.py @@ -0,0 +1,140 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Offline protocol boundaries for invocation-time Foundry Toolbox OAuth consent tests.""" + +from __future__ import annotations + +import json +from collections.abc import AsyncGenerator, AsyncIterator, Awaitable, Mapping, Sequence +from contextlib import asynccontextmanager +from typing import Any + +import httpx2 as httpx +from agent_framework import ( + BaseChatClient, + ChatResponse, + ChatResponseUpdate, + Content, + FunctionInvocationLayer, + Message, + ResponseStream, +) +from azure.core.credentials import AccessToken + +from agent_framework_foundry_hosting import FoundryToolbox + +CONSENT_LINK = "https://consent.example.com/authorize?state=abc" + + +class ConsentCredential: + def get_token(self, *scopes: str, **kwargs: Any) -> AccessToken: + return AccessToken("offline-token", 9999999999) + + +class ToolboxConsentServer: + """Offline MCP server whose listed tools succeed unless configured to return a ``-32006`` consent error.""" + + def __init__(self, tool_names: Sequence[str]) -> None: + self.tool_names = list(tool_names) + self.consent_errors: dict[str, dict[str, Any]] = {} + self.calls: list[str] = [] + + def require_consent( + self, + tool_name: str, + *, + message: str = f"Request failed (remote): {CONSENT_LINK}", + data: Any = None, + ) -> None: + error: dict[str, Any] = {"code": -32006, "message": message} + if data is not None: + error["data"] = data + self.consent_errors[tool_name] = error + + async def handle(self, request: httpx.Request) -> httpx.Response: + if request.method == "GET": + return httpx.Response(405) + if request.method == "DELETE": + return httpx.Response(200) + payload = json.loads(request.content) + method = payload.get("method") + if "id" not in payload: + return httpx.Response(202) + result: dict[str, Any] + if method == "server/discover": + return httpx.Response( + 200, + json={"jsonrpc": "2.0", "id": payload["id"], "error": {"code": -32601, "message": "Method not found"}}, + ) + if method == "initialize": + result = { + "protocolVersion": payload["params"]["protocolVersion"], + "capabilities": {"tools": {}}, + "serverInfo": {"name": "toolbox-consent", "version": "1"}, + } + elif method == "tools/list": + result = { + "tools": [ + {"name": name, "inputSchema": {"type": "object", "properties": {}}} for name in self.tool_names + ] + } + elif method == "tools/call": + name = payload["params"]["name"] + self.calls.append(name) + if (error := self.consent_errors.get(name)) is not None: + return httpx.Response(200, json={"jsonrpc": "2.0", "id": payload["id"], "error": error}) + result = {"content": [{"type": "text", "text": f"{name}-result"}]} + elif method == "ping": + result = {} + else: + raise AssertionError(f"Unexpected MCP method: {method}") + return httpx.Response(200, json={"jsonrpc": "2.0", "id": payload["id"], "result": result}) + + +@asynccontextmanager +async def consent_toolbox(server: ToolboxConsentServer, **kwargs: Any) -> AsyncGenerator[FoundryToolbox]: + toolbox = FoundryToolbox(ConsentCredential(), url="https://toolbox.invalid/toolboxes/secure/mcp", **kwargs) + original = toolbox._httpx_client + assert original is not None + await original.aclose() + toolbox._httpx_client = httpx.AsyncClient(transport=httpx.MockTransport(server.handle)) + try: + await toolbox.connect() + yield toolbox + finally: + await toolbox.close() + + +class BatchToolCallClient(FunctionInvocationLayer[Any], BaseChatClient[Any]): + """Requests one batch of function calls on its first turn, then answers with text.""" + + def __init__(self, tool_names: Sequence[str]) -> None: + super().__init__() + self.tool_names = list(tool_names) + self.calls: list[list[Message]] = [] + + def _inner_get_response( + self, + *, + messages: Sequence[Message], + stream: bool, + options: Mapping[str, Any], + **kwargs: Any, + ) -> Awaitable[ChatResponse] | ResponseStream[ChatResponseUpdate, ChatResponse]: + self.calls.append(list(messages)) + contents = ( + [ + Content.from_function_call(call_id=f"call-{index}", name=name, arguments="{}") + for index, name in enumerate(self.tool_names) + ] + if len(self.calls) == 1 + else [Content.from_text("done")] + ) + + async def updates() -> AsyncIterator[ChatResponseUpdate]: + yield ChatResponseUpdate(role="assistant", contents=contents) + + async def complete() -> ChatResponse: + return ChatResponse(messages=[Message("assistant", contents=contents)]) + + return ResponseStream(updates(), finalizer=ChatResponse.from_updates) if stream else complete() From 716f8308450abcde744c538878d815afe73700d5 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 09:41:00 +0100 Subject: [PATCH 06/55] Python: Remove legacy _validate_response_server_options after build_response_server_options adoption --- .../_responses_shared.py | 17 +---------------- 1 file changed, 1 insertion(+), 16 deletions(-) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py index 80b1aed70a4..254512a82b6 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py @@ -46,10 +46,7 @@ from agent_framework._mcp import _MCP_TOOL_RESULT_HOST_PAYLOAD_KEY # pyright: ignore[reportPrivateUsage] from agent_framework._types import _get_annotation_text_span_regions # pyright: ignore[reportPrivateUsage] from agent_framework.observability import OBSERVABILITY_SETTINGS -from azure.ai.agentserver.responses import ( - ResponseContext, - ResponsesServerOptions, -) +from azure.ai.agentserver.responses import ResponseContext from azure.ai.agentserver.responses._id_generator import IdGenerator from azure.ai.agentserver.responses.aio import ResponseEventStream from azure.ai.agentserver.responses.models import ( @@ -908,18 +905,6 @@ def _current_toolbox_consent_scope() -> _ToolboxConsentScope | None: # pyright: # endregion Foundry Toolbox Auth integration -def _validate_response_server_options( # pyright: ignore[reportUnusedFunction] - options: ResponsesServerOptions | None, -) -> None: - if options and options.steerable_conversations: - # TODO(foundry-hosting): Remove after Azure/azure-sdk-for-python#49233 ships and queue overflow is verified. - raise RuntimeError( - "steerable_conversations=True is temporarily unavailable: the current AgentServer SDK " - "retains futures for rejected steering turns. Wait for the official fix in " - "Azure/azure-sdk-for-python#49233, then update the dependency and verify queue overflow." - ) - - # region Active Builder State From 72330c85cb9c877431f8eebc9e6f211a5bd0ba6a Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 09:43:11 +0100 Subject: [PATCH 07/55] Distinguish invalid approval controls from backend errors --- .../_approvals.py | 20 +++--- .../foundry_hosting/test_session_approvals.py | 62 ++++++++++++++++--- 2 files changed, 65 insertions(+), 17 deletions(-) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_approvals.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_approvals.py index cb818226b3a..7f7d699ecc1 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_approvals.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_approvals.py @@ -20,6 +20,10 @@ _MAX_HISTORY_BYTES = 1024 * 1024 +class _InvalidApproval(ValueError): + """Reject invalid approval controls without classifying backend failures.""" + + @dataclass(frozen=True) class _ApprovalClaim: authority_id: str @@ -138,7 +142,7 @@ async def load_approval_request(self, approval_request_id: str) -> Content: history = _requests(self._state["history"]) value = history.get(approval_request_id) if value is None: - raise ValueError("Approval request is not in this session's history; start a fresh approval turn.") + raise _InvalidApproval("Approval request is not in this session's history; start a fresh approval turn.") return _decode_request(value) async def save_approval_request(self, approval_request_id: str, request: Content) -> None: @@ -215,22 +219,24 @@ async def preflight(self, approval_ids: Sequence[str]) -> _ApprovalClaim | None: new user turn with no decisions; reset by starting a fresh conversation. Approval and rejection both count as decisions. The host validates their boolean values and rejects conflicting input-control kinds separately. + Deliberate invalid controls raise ``_InvalidApproval``; storage failures + propagate unchanged, including backend ``ValueError`` exceptions. """ pending = self._pending() if pending is None: if approval_ids: - raise ValueError("No pending approval batch in this session; start a fresh approval turn.") + raise _InvalidApproval("No pending approval batch in this session; start a fresh approval turn.") return None if ( any(not isinstance(item, str) or not item for item in approval_ids) or len(set(approval_ids)) != len(approval_ids) or set(approval_ids) != set(pending["wire_ids"]) ): - raise ValueError("Answer exactly the complete pending MCP approval batch without duplicates.") + raise _InvalidApproval("Answer exactly the complete pending MCP approval batch without duplicates.") storage = _conditional_store(self._storage) authority, revision = await storage.get_with_revision(pending["authority_id"]) if authority is None: - raise ValueError("Pending approval authority is missing or expired; start a fresh conversation.") + raise _InvalidApproval("Pending approval authority is missing or expired; start a fresh conversation.") if not isinstance(revision, str) or not revision: raise RuntimeError("Session storage returned approval authority without a revision.") record = _mapping( @@ -246,9 +252,9 @@ async def preflight(self, approval_ids: Sequence[str]) -> _ApprovalClaim | None: or set(requests) != set(pending["wire_ids"]) or any(_requests(self._state["history"]).get(key) != value for key, value in requests.items()) ): - raise ValueError("Pending approval authority does not match this session and response.") + raise _InvalidApproval("Pending approval authority does not match this session and response.") if record.get("phase") == "claimed": - raise ValueError("Pending approval batch was already claimed; start a fresh approval turn.") + raise _InvalidApproval("Pending approval batch was already claimed; start a fresh approval turn.") if record.get("phase") != "pending" or "claimed_by" not in record or record["claimed_by"] is not None: raise RuntimeError("Unsupported canonical approval phase; start a fresh conversation.") for value in requests.values(): @@ -279,7 +285,7 @@ async def claim(self, token: _ApprovalClaim, *, response_id: str) -> None: or token.owner_response_id != pending["response_id"] or set(dict(token.requests)) != set(pending["wire_ids"]) ): - raise ValueError("Approval preflight token does not match the current session.") + raise _InvalidApproval("Approval preflight token does not match the current session.") authority = AgentSession(session_id=token.session_id) authority.state[_APPROVAL_STATE_KEY] = { "version": 1, diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_session_approvals.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_session_approvals.py index 4d1e181f115..f07d6e694b3 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_session_approvals.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_session_approvals.py @@ -4,12 +4,13 @@ import asyncio import json +from dataclasses import replace from unittest.mock import AsyncMock import pytest from agent_framework import AgentSession, SessionStore -from agent_framework_foundry_hosting._approvals import _APPROVAL_STATE_KEY, SessionApprovalState +from agent_framework_foundry_hosting._approvals import _APPROVAL_STATE_KEY, SessionApprovalState, _InvalidApproval from .approval_helpers import ( # pyrefly: ignore[missing-import] - pytest's importlib namespace SqliteSessionStore, @@ -53,7 +54,7 @@ async def test_invalid_batch_never_mutates_authority_and_complete_retry_succeeds session = await pending_session(store) state = SessionApprovalState(session, store) before = store.write_count - with pytest.raises(ValueError, match="complete pending MCP approval batch"): + with pytest.raises(_InvalidApproval, match="complete pending MCP approval batch"): await state.preflight(ids) assert store.write_count == before token = await state.preflight(["wire-1", "wire-0"]) @@ -77,7 +78,7 @@ async def test_response_and_conversation_aliases_share_one_irreversible_authorit await first.claim(token1, response_id="first") with pytest.raises(RuntimeError, match="revision conflict"): await second.claim(token2, response_id="second") - with pytest.raises(ValueError, match="already claimed"): + with pytest.raises(_InvalidApproval, match="already claimed"): await second.preflight(["wire-0", "wire-1"]) assert await second.load_approval_request("wire-0") == approval_request() assert await first.preflight([]) is None @@ -96,7 +97,7 @@ async def test_expired_canonical_is_not_recreated_from_snapshot(tmp_path) -> Non await store.delete(key) before = store.write_count state = SessionApprovalState(session, store) - with pytest.raises(ValueError, match="missing or expired"): + with pytest.raises(_InvalidApproval, match="missing or expired"): await state.preflight(["wire-0", "wire-1"]) assert store.write_count == before assert await state.load_approval_request("wire-0") == approval_request() @@ -112,9 +113,9 @@ async def test_unstored_and_nonconditional_stores_cannot_record_approvals(storag async def test_empty_fresh_session_has_no_pending_authority() -> None: state = SessionApprovalState(AgentSession(), None) assert await state.preflight([]) is None - with pytest.raises(ValueError, match="No pending approval"): + with pytest.raises(_InvalidApproval, match="No pending approval"): await state.preflight(["wire"]) - with pytest.raises(ValueError, match="not in this session"): + with pytest.raises(_InvalidApproval, match="not in this session"): await state.load_approval_request("wire") @@ -131,7 +132,7 @@ async def test_other_session_cannot_claim_copied_pending_link(tmp_path) -> None: session = await pending_session(store) other = AgentSession(session_id="other-session") other.state.update(session.state) - with pytest.raises(ValueError, match="does not match"): + with pytest.raises(_InvalidApproval, match="does not match"): await SessionApprovalState(other, store).preflight(["wire-0", "wire-1"]) @@ -168,7 +169,7 @@ async def test_postclaim_failure_does_not_reopen_authority_on_reload(tmp_path) - # No final session snapshot is saved: a restarted process sees the old alias. restarted = await SqliteSessionStore(store.path).get("response-alias") assert restarted is not None - with pytest.raises(ValueError, match="already claimed"): + with pytest.raises(_InvalidApproval, match="already claimed"): await SessionApprovalState(restarted, store).preflight(["wire-0", "wire-1"]) @@ -214,7 +215,7 @@ async def test_lost_claim_acknowledgement_never_reopens_persisted_authority(tmp_ restarted_store = SqliteSessionStore(store.path) restarted = await restarted_store.get("response-alias") assert restarted is not None - with pytest.raises(ValueError, match="already claimed"): + with pytest.raises(_InvalidApproval, match="already claimed"): await SessionApprovalState(restarted, restarted_store).preflight(["wire-0", "wire-1"]) @@ -247,6 +248,47 @@ async def test_history_tampering_does_not_authorize_a_different_call(tmp_path) - session = await pending_session(store) session.state[_APPROVAL_STATE_KEY]["history"]["wire-0"] = json.dumps(approval_request(9).to_dict()) before = store.write_count - with pytest.raises(ValueError, match="does not match"): + with pytest.raises(_InvalidApproval, match="does not match"): await SessionApprovalState(session, store).preflight(["wire-0", "wire-1"]) assert store.write_count == before + + +async def test_preflight_preserves_backend_value_error_without_classifying_invalid_input(tmp_path, monkeypatch) -> None: + store = SqliteSessionStore(tmp_path / "sessions.db") + session = await pending_session(store) + state = SessionApprovalState(session, store) + error = ValueError("backend decoding failed") + monkeypatch.setattr(store, "get_with_revision", AsyncMock(side_effect=error)) + before = store.write_count + with pytest.raises(ValueError) as caught: + await state.preflight(["wire-0", "wire-1"]) + assert caught.value is error + assert not isinstance(caught.value, _InvalidApproval) + assert store.write_count == before + + +async def test_claim_preserves_backend_value_error_without_classifying_invalid_input(tmp_path, monkeypatch) -> None: + store = SqliteSessionStore(tmp_path / "sessions.db") + session = await pending_session(store) + state = SessionApprovalState(session, store) + token = await state.preflight(["wire-0", "wire-1"]) + assert token is not None + error = ValueError("backend encoding failed") + monkeypatch.setattr(store, "compare_and_set", AsyncMock(side_effect=error)) + with pytest.raises(ValueError) as caught: + await state.claim(token, response_id="resume") + assert caught.value is error + assert not isinstance(caught.value, _InvalidApproval) + assert session.state[_APPROVAL_STATE_KEY]["pending"] is not None + + +async def test_claim_rejects_mismatched_token_as_invalid_approval_without_writing(tmp_path) -> None: + store = SqliteSessionStore(tmp_path / "sessions.db") + session = await pending_session(store) + state = SessionApprovalState(session, store) + token = await state.preflight(["wire-0", "wire-1"]) + assert token is not None + before = store.write_count + with pytest.raises(_InvalidApproval, match="token does not match"): + await state.claim(replace(token, session_id="other"), response_id="resume") + assert store.write_count == before From d494a2a9f7def306767fe8104feca80b6e4594a5 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 09:43:50 +0100 Subject: [PATCH 08/55] Document Foundry hosting support boundaries and add CAS custom storage sample --- python/packages/foundry_hosting/README.md | 104 +++++++++- .../test_custom_storage_sample.py | 195 ++++++++++++++++++ .../foundry-hosted-agents/README.md | 11 +- .../invocations/basic/README.md | 2 + .../invocations/telegram/README.md | 4 + .../responses/custom_storage/README.md | 56 ++++- .../responses/custom_storage/main.py | 80 +++++-- .../responses/foundry_toolbox/README.md | 2 + .../foundry_toolbox_mcp_skills/README.md | 2 + 9 files changed, 420 insertions(+), 36 deletions(-) create mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/test_custom_storage_sample.py diff --git a/python/packages/foundry_hosting/README.md b/python/packages/foundry_hosting/README.md index f37178cad2f..e8143d8ebab 100644 --- a/python/packages/foundry_hosting/README.md +++ b/python/packages/foundry_hosting/README.md @@ -13,8 +13,9 @@ Use `ResponsesHostServer` or `InvocationsHostServer` for agents. Use `ResponsesWorkflowHostServer` or `InvocationsWorkflowHostServer` for native workflows. Each workflow host requires a request-aware sync/async factory and an explicit parser. All four hosts remain in `agent-framework-foundry-hosting`, with matching lazy exports -under `agent_framework.foundry`. Invocations and Toolbox retain their experimental boundary; -the split does not promote them. +under `agent_framework.foundry`. The package is currently in beta, so its public APIs are +experimental. Responses hosting is the target for an initial stable release, subject to +qualification. Invocations hosting and `FoundryToolbox` remain experimental. **Breaking migration:** replace `ResponsesHostServer(workflow=..., parse_response=...)` with `ResponsesWorkflowHostServer(workflow=..., parse_input=...)`, and replace @@ -49,11 +50,37 @@ returning a new wrapper around shared executors does not isolate execution state Workflow hosts expose checkpoint storage, not agent-session storage or agent history/background policies. Responses workflows retain `prepare_options`; Invocations workflows use the parser's -explicit workflow kwargs instead. Existing SDK options and agent approval-store APIs are unchanged. +explicit workflow kwargs instead. Agent approval persistence follows the +[session-store contract below](#function-approvals). Agent hosts reject `WorkflowAgent`, whether supplied directly or returned by a factory. `checkpoint_store_provider` is available only on workflow hosts. No stored state is converted between native workflow and agent execution models. +## Responses route prefix + +`ResponsesHostServer` and `ResponsesWorkflowHostServer` pass `prefix` to the +[AgentServer Responses host](https://learn.microsoft.com/python/api/azure-ai-agentserver-responses/azure.ai.agentserver.responses.responsesagentserverhost?view=azure-python). +The native workflow host binds its create route at the same prefix. For example, with the +[request-aware factory below](#agent-instances-and-factories): + +```python +server = ResponsesHostServer(agent=create_agent, prefix="api/v1") +``` + +AgentServer applies the prefix to its Responses routes: + +| Operation | Default prefix (`""`) | `prefix="api/v1"` | +| --- | --- | --- | +| Create a response | `POST /responses` | `POST /api/v1/responses` | +| Retrieve a response | `GET /responses/{response_id}` | `GET /api/v1/responses/{response_id}` | +| Cancel a background response | `POST /responses/{response_id}/cancel` | `POST /api/v1/responses/{response_id}/cancel` | +| Delete a stored response | `DELETE /responses/{response_id}` | `DELETE /api/v1/responses/{response_id}` | +| List input items | `GET /responses/{response_id}/input_items` | `GET /api/v1/responses/{response_id}/input_items` | + +Use the same path prefix in clients and any reverse proxy. See the +[AgentServer protocol endpoints](https://learn.microsoft.com/python/api/overview/azure/ai-agentserver-responses-readme?view=azure-python#protocol-endpoints) +for the endpoint behavior and requirements. + ## Toolbox tool approvals `FoundryToolbox` uses each discovered tool's `_meta.tool_configuration.require_approval` when @@ -381,9 +408,12 @@ Each logical store is saved as one JSON file whose name is a URL-safe Base64 encoding of the store name. For example: - Responses agent sessions: `YWdlbnRfc2Vzc2lvbnM.json` -- Function approvals: `ZnVuY3Rpb25fYXBwcm92YWxz.json` - Workflow checkpoints: one file per context, encoded from `checkpoints/` +The file-based fallback supports ordinary session and checkpoint persistence, but cannot atomically +publish or claim agent approvals across processes. Local approval flows require a custom conditional +session store; see [Function approvals](#function-approvals). + > Read more about the Foundry durable state store in the [developer guide](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/agentserver/azure-ai-agentserver-core/docs/state-store-guide.md). ### User isolation @@ -417,7 +447,7 @@ conversation or response ID. | MAF `AgentSession.session_id` / `service_session_id` | Inner agent state and optional downstream service continuation; neither identifies the Foundry sandbox. | | Workflow checkpoint ID | Inner workflow state within a checkpoint context, not a Foundry session ID. | -The default hosted MAF session, checkpoint, and approval stores use a `v2` namespace +The default hosted MAF session and checkpoint stores use a `v2` namespace derived from the hashed platform identity, with `user_isolation=True` and an explicit platform `call_id` on each item operation. Checkpoint context IDs are hashed as well. The same user in two hosted sandboxes cannot read the other's default MAF state. @@ -533,9 +563,62 @@ locally. Stored checkpoints are scoped under `checkpoints`. ### Function approvals -`ResponsesHostServer` persists function approvals durably. By default, it uses the -`FoundryFunctionApprovalStore`, backed by Foundry storage when hosted and file-based -storage locally. Stored approvals are scoped under `function_approvals`. +`ResponsesHostServer` persists agent approval state through the same configured +`agent_session_store_provider` used for `AgentSession` snapshots. Approval authority belongs to +one pending response in the same trusted user/sandbox scope. Response and conversation snapshots +retain history and a link to that authority; they are not independent sources of permission. +Native workflow pending replies remain checkpoint-owned, not agent-session approvals. + +**Migration/reset:** pending approvals from the old separate function-approval store are not +migrated. Start a fresh conversation without an old `previous_response_id` or conversation ID and +obtain fresh approvals. Do not copy legacy approval records into session state. +Missing or expired authority fails closed, even when a snapshot still contains the historical +request. Retained approval history does not authorize another tool execution. + +#### Custom conditional session stores + +A custom store used for agent approvals must implement ordinary `SessionStore` operations and +these additional async methods. This is a structural capability; no extra public protocol or +private framework import is required. + +- `get_with_revision(session_id)` returns an independent `AgentSession` snapshot and its exact, + nonempty, opaque revision, or exactly `(None, None)` when absent. +- `compare_and_set(session_id, session, *, expected_revision)` returns the nonempty revision of the + persisted version. `expected_revision=None` means atomic **create only**; a nonempty revision + means replace only that exact existing version. + +Revisions must identify exact persisted versions and must never be reused after writes. A read's +revision belongs to that read, not to mutable per-request ETag state shared by multiple reads. +Conflicts raise `RuntimeError` or a subtype; never retry as an unconditional upsert. Storage I/O +errors and cancellation propagate. A write acknowledgement without a revision is a failure, even +if the backend stored the value. + +Storage lookup keys need not equal the snapshot's inner `AgentSession.session_id`. Support opaque +keys, including keys containing `/`, and preserve the inner session ID. Ordinary response or +conversation alias cleanup must not delete approval authority. Custom providers own retention: +alias and authority lifetimes are independent, and authority is never recreated from an alias +after it expires. + +The default hosted Foundry store uses server-side create-only and ETag-conditional writes. +The default non-hosted store rejects approval writes with an explicit error requiring +`get_with_revision` and `compare_and_set`. A single-process development store can coordinate only +its own process; production and multi-worker stores must coordinate all writers through the +backend. A process-local lock is not cross-process CAS. + +#### Approval batches and failure boundaries + +Reply to the complete pending approval batch. Approvals and rejections may be mixed, but omitted, +duplicate, stale, or foreign controls are invalid. Publishing pending authority requires +`store=true`; `store=false` cannot publish or resume host-managed approvals. + +Claiming a batch is an irreversible conditional transition before protected execution. It does +not provide exactly-once tool side effects: a crash after a successful claim can lose work. +A failed or cancelled claim write may already have committed. Do not reopen the batch or +automatically dispatch the protected work after an uncertain result. + +Approval history is bounded to 1,024 requests and 1 MiB of serialized approval-content JSON. +Exceeding either bound fails explicitly and requires a fresh conversation; history is not silently +pruned. ## Native Invocations workflows @@ -614,9 +697,8 @@ If a connection drops after commit, retrying the same trusted user/sandbox/call replays that response's complete stored snapshot without executing the workflow or replacing its head. A different call ID starts normal turn validation and cannot retrieve that snapshot. -Local callers may pass one built workflow for a one-shot non-pausing run. Any -workflow that can pause for external input must use a request-aware factory so a -fresh graph can restore and consume the durable reply on the next request. +All native Invocations requests, including local one-shot runs, require a +request-aware workflow factory that returns a fresh graph for each request. After a newer Invocations head is durably committed, the host reclaims completed ancestor response records and checkpoints oldest-first, retaining only current, pending, active or blocked authority. Cleanup failures are logged and retried by diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_custom_storage_sample.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_custom_storage_sample.py new file mode 100644 index 00000000000..09ad1783b75 --- /dev/null +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_custom_storage_sample.py @@ -0,0 +1,195 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Validate the conditional-write contract of the custom_storage hosting sample.""" + +from __future__ import annotations + +import importlib.util +import sys +from pathlib import Path +from types import ModuleType +from typing import Any + +import pytest +from agent_framework import AgentSession +from azure.core import MatchConditions +from azure.cosmos.exceptions import CosmosHttpResponseError, CosmosResourceNotFoundError + +from agent_framework_foundry_hosting import FoundryRequestScope + +_SAMPLE = ( + Path(__file__).resolve().parents[4] + / "samples" + / "04-hosting" + / "foundry-hosted-agents" + / "responses" + / "custom_storage" + / "main.py" +) +_APPROVAL_KEY = "__foundry_agent_approval/0b6c8b52-6f1d-4bb3-9a35-6a1e4c8f7f10" + + +@pytest.fixture(scope="module") +def sample() -> ModuleType: + spec = importlib.util.spec_from_file_location("custom_storage_sample", _SAMPLE) + assert spec is not None and spec.loader is not None + module = importlib.util.module_from_spec(spec) + sys.modules[spec.name] = module + spec.loader.exec_module(module) + return module + + +def _session(value: str) -> AgentSession: + session = AgentSession(session_id="inner-maf-session") + session.state["value"] = value + return session + + +def _http_error(status: int) -> CosmosHttpResponseError: + if status == 404: + return CosmosResourceNotFoundError(status_code=404, message="missing") + return CosmosHttpResponseError(status_code=status, message=f"status {status}") + + +class _FakeContainer: + """Server-side create-only and exact-ETag semantics for one partition.""" + + def __init__(self) -> None: + self.items: dict[tuple[str, str], dict[str, Any]] = {} + self._version = 0 + self.omit_etag = False + self.calls: list[tuple[str, dict[str, Any]]] = [] + + def _stamp(self, body: dict[str, Any]) -> dict[str, Any]: + self._version += 1 + stored = {**body, "_etag": f'"{self._version}"'} + self.items[body["scope_key"], body["id"]] = stored + return {**stored, "_etag": None} if self.omit_etag else dict(stored) + + async def read_item(self, *, item: str, partition_key: str) -> dict[str, Any]: + stored = self.items.get((partition_key, item)) + if stored is None: + raise _http_error(404) + return dict(stored) + + async def create_item(self, *, body: dict[str, Any]) -> dict[str, Any]: + self.calls.append(("create", {})) + if (body["scope_key"], body["id"]) in self.items: + raise _http_error(409) + return self._stamp(body) + + async def replace_item( + self, *, item: str, body: dict[str, Any], etag: str, match_condition: MatchConditions + ) -> dict[str, Any]: + self.calls.append(("replace", {"etag": etag, "match_condition": match_condition})) + stored = self.items.get((body["scope_key"], item)) + if stored is None: + raise _http_error(404) + if stored["_etag"] != etag: + raise _http_error(412) + return self._stamp(body) + + +def _cosmos_store(sample: ModuleType, container: _FakeContainer) -> Any: + scope = FoundryRequestScope(session_id="sandbox", user_id="user", call_id="call", is_hosted=True) + return sample.CosmosSessionStore(container=container, scope=scope) + + +def _local_store(sample: ModuleType, snapshots: dict[Any, Any], scope_key: str = "scope") -> Any: + return sample.LocalSessionStore(snapshots, scope_key=scope_key) + + +async def test_sample_does_not_import_private_hosting_types() -> None: + source = _SAMPLE.read_text(encoding="utf-8") + assert "_ConditionalSessionStore" not in source + assert "_SessionStoreConflict" not in source + assert "agent_framework_foundry_hosting._" not in source + + +@pytest.mark.parametrize("kind", ["local", "cosmos"]) +async def test_conditional_write_contract(sample: ModuleType, kind: str) -> None: + store = _local_store(sample, {}) if kind == "local" else _cosmos_store(sample, _FakeContainer()) + + assert await store.get_with_revision(_APPROVAL_KEY) == (None, None) + + first = await store.compare_and_set(_APPROVAL_KEY, _session("one"), expected_revision=None) + assert isinstance(first, str) and first + with pytest.raises(RuntimeError): + await store.compare_and_set(_APPROVAL_KEY, _session("dup"), expected_revision=None) + + loaded, revision = await store.get_with_revision(_APPROVAL_KEY) + assert revision == first + assert loaded is not None and loaded.session_id == "inner-maf-session" + assert loaded.state["value"] == "one" + loaded.state["value"] = "mutated" + again, _ = await store.get_with_revision(_APPROVAL_KEY) + assert again is not None and again.state["value"] == "one" + + second = await store.compare_and_set(_APPROVAL_KEY, _session("two"), expected_revision=first) + assert second and second != first + with pytest.raises(RuntimeError): + await store.compare_and_set(_APPROVAL_KEY, _session("stale"), expected_revision=first) + current, current_revision = await store.get_with_revision(_APPROVAL_KEY) + assert current is not None and current.state["value"] == "two" + assert current_revision == second + + with pytest.raises(ValueError): + await store.compare_and_set(_APPROVAL_KEY, _session("bad"), expected_revision="") + + +@pytest.mark.parametrize("kind", ["local", "cosmos"]) +async def test_exact_update_of_absent_key_conflicts(sample: ModuleType, kind: str) -> None: + store = _local_store(sample, {}) if kind == "local" else _cosmos_store(sample, _FakeContainer()) + with pytest.raises(RuntimeError): + await store.compare_and_set("missing", _session("x"), expected_revision="some-revision") + assert await store.get_with_revision("missing") == (None, None) + + +@pytest.mark.parametrize("kind", ["local", "cosmos"]) +async def test_revision_reads_do_not_change_ordinary_write_tokens(sample: ModuleType, kind: str) -> None: + store = _local_store(sample, {}) if kind == "local" else _cosmos_store(sample, _FakeContainer()) + assert await store.get("alias") is None + await store.set("alias", _session("one")) + _, revision = await store.get_with_revision("alias") + await store.compare_and_set("alias", _session("two"), expected_revision=revision) + with pytest.raises(RuntimeError): + await store.set("alias", _session("stale")) + + +async def test_local_store_scopes_are_isolated(sample: ModuleType) -> None: + snapshots: dict[Any, Any] = {} + first = _local_store(sample, snapshots, "scope-a") + second = _local_store(sample, snapshots, "scope-b") + await first.compare_and_set(_APPROVAL_KEY, _session("a"), expected_revision=None) + assert await second.get_with_revision(_APPROVAL_KEY) == (None, None) + + +async def test_cosmos_uses_server_conditions(sample: ModuleType) -> None: + container = _FakeContainer() + store = _cosmos_store(sample, container) + revision = await store.compare_and_set(_APPROVAL_KEY, _session("one"), expected_revision=None) + await store.compare_and_set(_APPROVAL_KEY, _session("two"), expected_revision=revision) + assert container.calls[0] == ("create", {}) + assert container.calls[1] == ("replace", {"etag": revision, "match_condition": MatchConditions.IfNotModified}) + assert all("/" not in item_id for _, item_id in container.items) + + +async def test_cosmos_missing_ack_revision_fails(sample: ModuleType) -> None: + container = _FakeContainer() + container.omit_etag = True + store = _cosmos_store(sample, container) + with pytest.raises(RuntimeError, match="ETag"): + await store.compare_and_set(_APPROVAL_KEY, _session("one"), expected_revision=None) + + +async def test_cosmos_other_errors_propagate(sample: ModuleType) -> None: + container = _FakeContainer() + + async def fail(*, body: dict[str, Any]) -> dict[str, Any]: + raise _http_error(503) + + container.create_item = fail # type: ignore[method-assign] + store = _cosmos_store(sample, container) + with pytest.raises(CosmosHttpResponseError) as exc_info: + await store.compare_and_set(_APPROVAL_KEY, _session("one"), expected_revision=None) + assert not isinstance(exc_info.value, RuntimeError) diff --git a/python/samples/04-hosting/foundry-hosted-agents/README.md b/python/samples/04-hosting/foundry-hosted-agents/README.md index db81091f2dd..b994e07f73b 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/README.md @@ -4,7 +4,12 @@ This directory contains samples that demonstrate how to use hosted [Agent Framew > [IMPORTANT] Migrating from Protocol version 1.0.0 to 2.0.0: Foundry Hosting Agents service has been updated to use Protocol version 2.0.0. If your application is using Protocol version 1.0.0, please upgrade to Protocol version 2.0.0 in your `agent.manifest.yaml` or `agent.yaml` and upgrade to the latest `agent-framework-foundry-hosting` package. `agent-framework-foundry-hosting==1.0.0a260625` is the last version that supports Protocol version 1.0.0. > -> The `agent-framework-foundry-hosting` Python API surface is intended to remain stable, but protocol 1.0.0 and 2.0.0 are incompatible. +> Protocol versions 1.0.0 and 2.0.0 are incompatible. + +The hosting package is currently in beta, so its public APIs are experimental. Responses hosting +is the target for an initial stable release, subject to qualification. Invocations hosting and +the `FoundryToolbox` integration remain experimental. + ## Samples ### Responses API @@ -74,6 +79,10 @@ An opaque call ID correlates one request; it is not a storage namespace. ### Invocations API +The Foundry-hosted Telegram integration is sample-only, not a built-in channel adapter in +`agent-framework-foundry-hosting`. The sample uses Azure AgentServer's `InvocationAgentServerHost` +directly, not Agent Framework's `InvocationsHostServer`. + | # | Sample | Description | |---|--------|-------------| | 1 | [Basic](invocations/basic/) | An Invocations agent with a custom JSON parser, durable MAF history, and JSON/SSE responses. | diff --git a/python/samples/04-hosting/foundry-hosted-agents/invocations/basic/README.md b/python/samples/04-hosting/foundry-hosted-agents/invocations/basic/README.md index a5bf15b3ba9..52be08fc94d 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/invocations/basic/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/invocations/basic/README.md @@ -1,5 +1,7 @@ # Invocations agent with a custom request parser +Agent Framework Invocations hosting is experimental. + [`main.py`](main.py) hosts an Agent Framework agent using the Foundry Invocations protocol. The sample accepts application JSON with a `prompt` field rather than the host's default `message` field. Its `parse_input` diff --git a/python/samples/04-hosting/foundry-hosted-agents/invocations/telegram/README.md b/python/samples/04-hosting/foundry-hosted-agents/invocations/telegram/README.md index f33634d418b..5810c11bd9d 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/invocations/telegram/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/invocations/telegram/README.md @@ -15,6 +15,10 @@ It is a complete learning deployment rather than a production reference architec polling, an app-owned FastAPI webhook, and in-memory state. This sample focuses on Foundry direct-code deployment, APIM ingress, managed identities, and durable history. +The Foundry-hosted Telegram integration is sample-only, not a built-in channel adapter in +`agent-framework-foundry-hosting`. This sample uses Azure AgentServer's `InvocationAgentServerHost` +directly, not Agent Framework's `InvocationsHostServer`. + ## What is deployed The self-contained Bicep templates create: diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md index 3e88df652e0..83a0117cc87 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md @@ -1,8 +1,11 @@ # Custom session storage (Responses protocol) This sample implements custom **MAF agent-session persistence**, including user -and sandbox isolation and optimistic concurrency. The outer Responses store and -function-approval store remain host-managed. This is not a workflow example. +and sandbox isolation and optimistic concurrency. The outer Responses store +remains host-managed. The same custom store also holds the host's agent +approval state, so it implements revision-based conditional writes (see +[Approval state](#approval-state-and-revisioned-writes)). This is not a +workflow example. ## Identity and storage keys @@ -51,11 +54,56 @@ newer snapshot. An absent delete is idempotent. Missing ETags and mismatched stored scope fail closed; other Cosmos failures propagate without a local fallback. -Local runs use isolated in-memory snapshots with the same conditional behavior. -They are lost when the process exits and are **single-user development only**: +Local runs use isolated in-memory snapshots with the same conditional behavior, +but only inside **one process and event loop**. The local store gives no +guarantee across workers or processes. Snapshots are lost when the process +exits and are **single-user development only**: local headers/session selectors are not a trusted platform authentication boundary. Explicit local sessions have separate namespaces. +## Approval state and revisioned writes + +The host keeps agent tool-approval state in the configured session store, not +in a separate approval store. Each tool-approval request needs a single atomic +claim. A custom store that holds approval state must therefore add two async +methods next to `get`/`set`/`delete`: + +```python +async def get_with_revision(self, session_id: str) -> tuple[AgentSession | None, str | None]: ... +async def compare_and_set( + self, session_id: str, session: AgentSession, *, expected_revision: str | None +) -> str: ... +``` + +The host detects these methods structurally. Do not import or subclass a +private hosting type. The sample stores follow these rules: + +- `get_with_revision` returns an independent snapshot and an opaque, non-empty + revision for that exact stored version. An absent key returns + `(None, None)`. Revision reads do not change the per-request ETags that + `get`/`set` use. +- `expected_revision=None` is an atomic **create-only** write. A revision means + an update only when the stored version still matches. A conflict raises + `RuntimeError`. The store never falls back to an upsert or retries the write + on its own. On success it returns the new revision. +- Keys are opaque strings. They can differ from `AgentSession.session_id` and + can contain characters such as `/`. Cosmos item IDs hash the key. +- Cosmos uses `create_item` and `replace_item` with the ETag and + `MatchConditions.IfNotModified`. The service enforces both conditions. + A write result without an ETag fails. +- A write that fails or is cancelled may still have been committed. Reload the + state before you decide what to do next. Do not assume that the write did + not happen. + +The local store implements the same methods for development. Its conditional +write is atomic only inside one process and event loop. Use a store with +server-side conditional writes, such as Cosmos, when more than one worker or +process can serve the same conversation. + +Without these methods, the host can still use the store for ordinary session +history. A non-hosted request that needs approval state fails with a +`RuntimeError` that names the missing methods. + ## Cosmos prerequisites Create the database/container separately and set: diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/main.py b/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/main.py index 0435acc9ef6..850ab4ceb74 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/main.py +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/main.py @@ -17,9 +17,11 @@ """Trusted user-and-sandbox session snapshots with optimistic concurrency. Hosted runs use an existing Cosmos DB container partitioned by /scope_key and -authenticate with managed identity. Local runs use process-local snapshots with -the same create-only/conditional-write behavior; they are not a multi-user -authentication boundary. +authenticate with managed identity. Both stores also expose the structural +``get_with_revision``/``compare_and_set`` capability that hosted agent approvals +require. Cosmos uses server-side create-only writes and exact ETag matches. Local +runs use process-local snapshots: their conditional writes are atomic only within +one process, and they are not a multi-user authentication boundary. """ from __future__ import annotations @@ -51,6 +53,11 @@ ) +def _validate_revision(expected_revision: str | None) -> None: + if expected_revision is not None and (not isinstance(expected_revision, str) or not expected_revision): + raise ValueError("expected_revision must be None or a non-empty string.") + + class CosmosSessionStore(SessionStore): """Keep a request's ETags separate from every other request's working copy.""" @@ -74,23 +81,37 @@ def _item_id(self, session_id: str) -> str: async def get(self, session_id: str) -> AgentSession | None: """Load by the host's response/conversation key, not the inner MAF ID.""" + session, etag = await self.get_with_revision(session_id) + self._etags[session_id] = etag + return session + + async def get_with_revision(self, session_id: str) -> tuple[AgentSession | None, str | None]: + """Return an independent snapshot and its ETag without caching that ETag.""" item_id = self._item_id(session_id) try: item = await self._container.read_item(item=item_id, partition_key=self._scope_key) except CosmosResourceNotFoundError: - self._etags[session_id] = None - return None + return None, None if item.get("scope_key") != self._scope_key or item.get("id") != item_id: raise RuntimeError("A stored agent session does not belong to this trusted user and sandbox.") etag = item.get("_etag") if not isinstance(etag, str) or not etag: raise RuntimeError("Stored Cosmos session is missing its ETag.") - session = AgentSession.from_dict(item["session"]) - self._etags[session_id] = etag - return session + return AgentSession.from_dict(item["session"]), etag async def set(self, session_id: str, session: AgentSession) -> None: """Create a new key, or replace only the version this request loaded.""" + self._etags[session_id] = await self.compare_and_set( + session_id, session, expected_revision=self._etags.get(session_id) + ) + + async def compare_and_set(self, session_id: str, session: AgentSession, *, expected_revision: str | None) -> str: + """Create only when ``expected_revision`` is None; otherwise replace only that ETag. + + Conflicts raise ``RuntimeError`` and are never retried as an upsert. A failed or + cancelled write may still have committed, so callers must reload before deciding. + """ + _validate_revision(expected_revision) item: dict[str, Any] = { "id": self._item_id(session_id), "scope_key": self._scope_key, @@ -99,26 +120,25 @@ async def set(self, session_id: str, session: AgentSession) -> None: if len(json.dumps(item, separators=(",", ":")).encode("utf-8")) > _MAX_COSMOS_ITEM_BYTES: raise ValueError(_SESSION_TOO_LARGE) try: - etag = self._etags.get(session_id) - if etag is None: + if expected_revision is None: result = await self._container.create_item(body=item) else: result = await self._container.replace_item( item=item["id"], body=item, - etag=etag, + etag=expected_revision, match_condition=MatchConditions.IfNotModified, ) except CosmosHttpResponseError as exc: if exc.status_code == 413: raise ValueError(_SESSION_TOO_LARGE) from exc - if exc.status_code not in (409, 412): + if exc.status_code not in (404, 409, 412): raise raise RuntimeError(_CONFLICT) from exc new_etag = result.get("_etag") if not isinstance(new_etag, str) or not new_etag: raise RuntimeError("Cosmos did not return an ETag after saving.") - self._etags[session_id] = new_etag + return new_etag async def delete(self, session_id: str) -> None: """Delete the loaded version; an absent key is an idempotent no-op.""" @@ -144,7 +164,11 @@ async def delete(self, session_id: str) -> None: class LocalSessionStore(SessionStore): - """Request-local concurrency tokens over scoped, process-local snapshots.""" + """Request-local concurrency tokens over scoped, process-local snapshots. + + Conditional writes are atomic only inside this single process and event loop. + They do not coordinate other workers or processes. + """ def __init__(self, snapshots: dict[tuple[str, str], tuple[str, dict[str, Any]]], *, scope_key: str) -> None: super().__init__() @@ -157,18 +181,34 @@ def _key(self, session_id: str) -> tuple[str, str]: return self._scope_key, session_id async def get(self, session_id: str) -> AgentSession | None: + session, revision = await self.get_with_revision(session_id) + self._etags[session_id] = revision + return session + + async def get_with_revision(self, session_id: str) -> tuple[AgentSession | None, str | None]: + """Return an independent snapshot and its revision without caching that revision.""" item = self._snapshots.get(self._key(session_id)) - self._etags[session_id] = item[0] if item else None - return AgentSession.from_dict(deepcopy(item[1])) if item else None + if item is None: + return None, None + return AgentSession.from_dict(deepcopy(item[1])), item[0] async def set(self, session_id: str, session: AgentSession) -> None: + self._etags[session_id] = await self.compare_and_set( + session_id, session, expected_revision=self._etags.get(session_id) + ) + + async def compare_and_set(self, session_id: str, session: AgentSession, *, expected_revision: str | None) -> str: + """Create only when ``expected_revision`` is None; otherwise replace only that revision.""" + _validate_revision(expected_revision) key = self._key(session_id) + snapshot = deepcopy(session.to_dict()) + # No await between the check and the write keeps this atomic within one event loop. item = self._snapshots.get(key) - if (item[0] if item else None) != self._etags.get(session_id): + if (item[0] if item else None) != expected_revision: raise RuntimeError(_CONFLICT) - etag = uuid.uuid4().hex - self._snapshots[key] = etag, deepcopy(session.to_dict()) - self._etags[session_id] = etag + revision = uuid.uuid4().hex + self._snapshots[key] = revision, snapshot + return revision async def delete(self, session_id: str) -> None: key = self._key(session_id) diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md index 1d1962379c8..cea1af76345 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md @@ -2,6 +2,8 @@ An [Agent Framework](https://github.com/microsoft/agent-framework) agent that uses **Foundry Toolbox** for tool discovery, hosted on Microsoft Foundry using the **Responses protocol**. Foundry Toolbox is a managed tool registry in Microsoft Foundry that lets you define tools centrally and share them across agents. +The Agent Framework `FoundryToolbox` integration is experimental. + ## Creating a Foundry Toolbox You can create a Foundry Toolbox by code. Refer to this sample for an example: [Foundry Toolbox CRUD Sample](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-projects/samples/toolboxes/sample_toolboxes_crud.py). diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox_mcp_skills/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox_mcp_skills/README.md index 509ad01d419..c91b2c273bb 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox_mcp_skills/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox_mcp_skills/README.md @@ -2,6 +2,8 @@ An [Agent Framework](https://github.com/microsoft/agent-framework) agent that discovers **Agent Skills attached to a Foundry Toolbox** over the **MCP protocol** and exposes them to the model using the [Agent Skills](https://agentskills.io/) progressive-disclosure pattern, hosted on Microsoft Foundry using the **Responses protocol**. +The Agent Framework `FoundryToolbox` integration is experimental. + This sample is **self-contained**: it ships the `SKILL.md` sources and a `toolbox.yaml`, and walks you through creating the skills and the toolbox from zero with `azd` — you don't need an existing toolbox to run it. ## How progressive disclosure works From b773183e0f5a907a4b13806c95894e770f3bd56f Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 09:45:00 +0100 Subject: [PATCH 09/55] Python: Restore _validate_response_server_options steering guard Reverts 716f8308. Removing the guard was outside the consent/translation scope; steering behavior stays owned by the constructor/options owners. --- .../_responses_shared.py | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py index 254512a82b6..80b1aed70a4 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py @@ -46,7 +46,10 @@ from agent_framework._mcp import _MCP_TOOL_RESULT_HOST_PAYLOAD_KEY # pyright: ignore[reportPrivateUsage] from agent_framework._types import _get_annotation_text_span_regions # pyright: ignore[reportPrivateUsage] from agent_framework.observability import OBSERVABILITY_SETTINGS -from azure.ai.agentserver.responses import ResponseContext +from azure.ai.agentserver.responses import ( + ResponseContext, + ResponsesServerOptions, +) from azure.ai.agentserver.responses._id_generator import IdGenerator from azure.ai.agentserver.responses.aio import ResponseEventStream from azure.ai.agentserver.responses.models import ( @@ -905,6 +908,18 @@ def _current_toolbox_consent_scope() -> _ToolboxConsentScope | None: # pyright: # endregion Foundry Toolbox Auth integration +def _validate_response_server_options( # pyright: ignore[reportUnusedFunction] + options: ResponsesServerOptions | None, +) -> None: + if options and options.steerable_conversations: + # TODO(foundry-hosting): Remove after Azure/azure-sdk-for-python#49233 ships and queue overflow is verified. + raise RuntimeError( + "steerable_conversations=True is temporarily unavailable: the current AgentServer SDK " + "retains futures for rejected steering turns. Wait for the official fix in " + "Azure/azure-sdk-for-python#49233, then update the dependency and verify queue overflow." + ) + + # region Active Builder State From 2c54461193b2404b1dfbfbe50f9cced309860623 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 09:45:54 +0100 Subject: [PATCH 10/55] Document Foundry Toolbox invocation-time OAuth consent behavior --- python/packages/foundry_hosting/README.md | 38 +++++++++++++++++++ .../responses/foundry_toolbox/README.md | 3 ++ 2 files changed, 41 insertions(+) diff --git a/python/packages/foundry_hosting/README.md b/python/packages/foundry_hosting/README.md index e8143d8ebab..6d8a7808bb6 100644 --- a/python/packages/foundry_hosting/README.md +++ b/python/packages/foundry_hosting/README.md @@ -371,6 +371,44 @@ An omitted allowlist preserves existing behavior and does not restrict the HTTPS the gate, so an empty sequence rejects every consent link. Entries are normalized as origins, so paths and query strings belong on the emitted consent link, not in the configuration. +### Invocation-time OAuth consent + +When a Foundry Toolbox MCP `tools/call` reports that the user must give OAuth consent, the Responses agent host +does not end the run with an opaque error. The response has status `incomplete`, and its output contains: + +- the `function_call` for the protected tool; +- a `function_call_output` for that call, whose text says that OAuth consent is required; +- an `oauth_consent_request` item with `consent_link` and `server_label`. + +The host emits a consent request for one `(consent_link, server_label)` pair only once in a response. Non-streaming +calls return these items in the final response. Streaming calls give the same items. The host buffers them and +publishes them only after it saves the approval authority and the session snapshots. + +Other tool calls in the same run behave as follows: + +- Tool calls that completed before the consent error keep their real results. +- The host does not run later protected Toolbox calls in the same run. Each one gets a + "not executed because another tool requires OAuth consent" output. +- Each `function_call` gets exactly one terminal output. + +To continue, the user opens `consent_link` and gives consent. The client then sends a new request with +`previous_response_id`, and the agent tries the tool again. + +Failure boundaries: + +- The response fails if a consent link is not a safe absolute HTTPS URL or is outside the configured origin + allowlist. The host does not expose that URL. +- The response fails with "OAuth consent continuation requires store=true." if the request has `store=false`. The host + exposes no consent or approval output for that request. +- Consent at connection time (`tools/list`) behaves as before. + +Limits: + +- The host does not cancel sibling tool calls that are already running. +- Only Toolbox tools are blocked. Other tools continue to run. +- The host must activate the request scope, so this behavior needs the hosted runtime. +- Core can log the consent exception. + ## Computer use The Responses host emits native `computer_call` and `computer_call_output` items, including ordered `actions`, diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md index cea1af76345..53a5e22a9bd 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md @@ -119,6 +119,9 @@ PAT-backed tools act as the configured external account; user-identity tools require the appropriate pass-through connection and the current call ID. A fresh Python object does not by itself grant external permissions. GitHub PAT/OAuth connections, project roles and consent are separate setup, not offline coverage. +If a Toolbox tool call needs OAuth consent, the response is `incomplete` and +contains an `oauth_consent_request`. Continuation needs `store=true`. See +[Invocation-time OAuth consent](../../../../../packages/foundry_hosting/README.md#invocation-time-oauth-consent). Native code-interpreter file citations are a separate tracked behavior (microsoft/agent-framework#7916), not implemented by this lifecycle change. From 7d54db8c15885166f7ecd52a7892213782c12a48 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 09:49:29 +0100 Subject: [PATCH 11/55] Remove legacy Foundry function approval store Delete FunctionApprovalStore, FoundryFunctionApprovalStore and FunctionApprovalStoreProvider from _state_store.py; session-backed approval authority replaces them. Drop the matching legacy tests while keeping session/checkpoint scope coverage. --- .../_state_store.py | 74 ---------- .../foundry_hosting/tests/test_state_store.py | 127 +----------------- 2 files changed, 6 insertions(+), 195 deletions(-) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_state_store.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_state_store.py index f55fc23446b..c3365286235 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_state_store.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_state_store.py @@ -13,7 +13,6 @@ AgentSession, CheckpointID, CheckpointStorage, - Content, SessionStore, WorkflowCheckpoint, WorkflowCheckpointException, @@ -335,79 +334,6 @@ def get_store_for_scope( # endregion Checkpoint persistence -# region Function approval persistence - - -class FunctionApprovalStore(Protocol): - """Store for saving function approval requests.""" - - async def save_approval_request(self, approval_request_id: str, request: Content) -> None: - """Save a function approval request under the given ID.""" - ... - - async def load_approval_request(self, approval_request_id: str) -> Content: - """Load a function approval request by its ID.""" - ... - - -class FoundryFunctionApprovalStore: - """Function approval store backed by the `FoundryStateStore`.""" - - DEFAULT_ROOT_SCOPE = "function_approvals" - - def __init__( - self, - platform_context: FoundryAgentRequestContext, - *, - scope: FoundryRequestScope | None = None, - ) -> None: - self.platform_context = platform_context - self._scope = scope - - async def _get_store(self) -> FoundryStateStore: - return await FoundryStateStore.get_or_create( - _store_name(self.DEFAULT_ROOT_SCOPE, self._scope), - user_isolation=True, - ) - - async def save_approval_request(self, approval_request_id: str, request: Content) -> None: - store = await self._get_store() - async with store: - try: - await store.create_item(approval_request_id, request.to_dict(), call_id=self.platform_context.call_id) - except FoundryStorageConflictError as ex: - raise ValueError(f"Approval request with ID '{approval_request_id}' already exists.") from ex - - async def load_approval_request(self, approval_request_id: str) -> Content: - store = await self._get_store() - async with store: - item = await store.get_item(approval_request_id, call_id=self.platform_context.call_id) - if item is None: - raise KeyError(f"Approval request with ID '{approval_request_id}' does not exist.") - return Content.from_dict(item.value) - - -class FunctionApprovalStoreProvider(StoreProvider[FunctionApprovalStore]): - """Provide function approval store for the active hosting environment. - - This defaults to using the `FoundryFunctionApprovalStore` in all environments. - """ - - def get_store( - self, - *, - config: AgentConfig, - platform_context: FoundryAgentRequestContext, - ) -> FunctionApprovalStore: - """Get function approval store for the requested hosting environment.""" - return FoundryFunctionApprovalStore( - platform_context, - scope=_store_scope(config, platform_context), - ) - - -# endregion Function approval persistence - # region Agent session persistence diff --git a/python/packages/foundry_hosting/tests/test_state_store.py b/python/packages/foundry_hosting/tests/test_state_store.py index f659e45ec26..2ea154c77d6 100644 --- a/python/packages/foundry_hosting/tests/test_state_store.py +++ b/python/packages/foundry_hosting/tests/test_state_store.py @@ -6,7 +6,7 @@ from unittest.mock import AsyncMock, MagicMock, patch import pytest -from agent_framework import AgentSession, Content, WorkflowCheckpoint, WorkflowCheckpointException +from agent_framework import AgentSession, WorkflowCheckpoint, WorkflowCheckpointException from agent_framework._workflows._checkpoint_encoding import encode_checkpoint_value from azure.ai.agentserver.core import AgentConfig, FoundryAgentRequestContext from azure.ai.agentserver.core.storage import ( @@ -22,8 +22,6 @@ CheckpointStoreProvider, FoundryAgentSessionStore, FoundryCheckpointStore, - FoundryFunctionApprovalStore, - FunctionApprovalStoreProvider, _SessionStoreConflict, ) @@ -88,7 +86,6 @@ def _platform_context( def test_storage_providers_use_public_abstraction() -> None: assert issubclass(CheckpointStoreProvider, ContextScopedStoreProvider) assert not issubclass(CheckpointStoreProvider, StoreProvider) - assert issubclass(FunctionApprovalStoreProvider, StoreProvider) assert issubclass(AgentSessionStoreProvider, StoreProvider) @@ -393,95 +390,6 @@ def test_checkpoint_stores_require_context_id(create_store: Callable[[], Any]) - create_store() -def _approval_request(approval_request_id: str) -> Content: - function_call = Content.from_function_call( - "call-1", - "delete_file", - arguments='{"path": "/foo"}', - additional_properties={"server_label": "my_server"}, - ) - return Content.from_function_approval_request(approval_request_id, function_call) - - -async def test_save_and_load_function_approval_request() -> None: - store = _store() - request = _approval_request("approval-1") - store.get_item = AsyncMock(return_value=SimpleNamespace(value=request.to_dict())) - - with patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", - new=AsyncMock(return_value=store), - ) as get_or_create: - storage = FoundryFunctionApprovalStore(_platform_context()) - await storage.save_approval_request("approval-1", request) - loaded = await storage.load_approval_request("approval-1") - - assert get_or_create.await_count == 2 - get_or_create.assert_awaited_with("function_approvals", user_isolation=True) - store.create_item.assert_awaited_once_with("approval-1", request.to_dict(), call_id="call-1") - store.get_item.assert_awaited_once_with("approval-1", call_id="call-1") - assert loaded == request - function_call = loaded.function_call - assert function_call is not None - assert function_call.name == "delete_file" - assert function_call.additional_properties["server_label"] == "my_server" - - -async def test_save_duplicate_function_approval_request_raises() -> None: - store = _store() - store.create_item = AsyncMock(side_effect=FoundryStorageConflictError("already exists")) - - with ( - patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", - new=AsyncMock(return_value=store), - ), - pytest.raises(ValueError, match="Approval request with ID 'approval-1' already exists"), - ): - await FoundryFunctionApprovalStore(_platform_context()).save_approval_request( - "approval-1", _approval_request("approval-1") - ) - - -async def test_load_missing_function_approval_request_raises() -> None: - store = _store() - store.get_item = AsyncMock(return_value=None) - - with ( - patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", - new=AsyncMock(return_value=store), - ), - pytest.raises(KeyError, match="Approval request with ID 'missing' does not exist"), - ): - await FoundryFunctionApprovalStore(_platform_context()).load_approval_request("missing") - - -@pytest.mark.parametrize("is_hosted", [True, False]) -def test_function_approval_storage_provider_uses_foundry_store(is_hosted: bool) -> None: - provider = FunctionApprovalStoreProvider() - config = _config(is_hosted=is_hosted) - platform_context = _platform_context() - - storage = provider.get_store(config=config, platform_context=platform_context) - - assert type(storage) is FoundryFunctionApprovalStore - assert storage.platform_context is platform_context - - -def test_function_approval_storage_provider_creates_request_scoped_storage() -> None: - with patch("agent_framework_foundry_hosting._state_store.FoundryFunctionApprovalStore") as storage_type: - provider = FunctionApprovalStoreProvider() - config = _config(is_hosted=False) - first_context = _platform_context("call-1") - second_context = _platform_context("call-2") - provider.get_store(config=config, platform_context=first_context) - provider.get_store(config=config, platform_context=second_context) - - assert storage_type.call_args_list[0].args == (first_context,) - assert storage_type.call_args_list[1].args == (second_context,) - - async def test_set_agent_session_uses_scoped_store() -> None: store = _store() session = AgentSession(session_id="agent-session-1") @@ -748,7 +656,7 @@ def test_agent_session_storage_provider_creates_request_scoped_storage() -> None assert storage_type.call_args_list[1].args == (second_context,) -@pytest.mark.parametrize("provider", ["agent", "checkpoint", "approval"]) +@pytest.mark.parametrize("provider", ["agent", "checkpoint"]) @pytest.mark.parametrize( ("platform_session_id", "request_session_id", "user_id", "call_id"), [ @@ -766,10 +674,8 @@ def test_hosted_store_providers_reject_missing_platform_identity( with pytest.raises(RuntimeError, match="FOUNDRY_AGENT_SESSION_ID|does not match|user ID and call ID"): if provider == "agent": AgentSessionStoreProvider().get_store(config=config, platform_context=context) - elif provider == "checkpoint": - CheckpointStoreProvider().get_store(config=config, context_id="workflow", platform_context=context) else: - FunctionApprovalStoreProvider().get_store(config=config, platform_context=context) + CheckpointStoreProvider().get_store(config=config, context_id="workflow", platform_context=context) async def test_hosted_store_names_partition_sandbox_and_forward_call_id() -> None: @@ -795,13 +701,10 @@ async def get_store(name: str, *, user_isolation: bool) -> MagicMock: config=config, context_id="../../conversation", platform_context=context ) await checkpoints.save(_checkpoint("checkpoint-1")) - approvals = FunctionApprovalStoreProvider().get_store(config=config, platform_context=context) - await approvals.save_approval_request("approval-1", _approval_request("approval-1")) - assert len(names) == len(set(names)) == 6 + assert len(names) == len(set(names)) == 4 assert all(name.split("/")[1] == "v2" and len(name) <= 128 for name in names) assert all("user-1" not in name and "sandbox" not in name and "conversation" not in name for name in names) - assert {call.kwargs["call_id"] for call in store.create_item.await_args_list} == {"call-1", "call-2"} assert {call.kwargs["call_id"] for call in store.set_item.await_args_list} == {"call-1", "call-2"} @@ -821,38 +724,29 @@ async def test_hosted_scope_does_not_read_existing_unscoped_agent_session() -> N assert await legacy.get_item("response-1", call_id=context.call_id) is not None -async def test_hosted_scope_does_not_read_existing_unscoped_checkpoint_or_approval() -> None: +async def test_hosted_scope_does_not_read_existing_unscoped_checkpoint() -> None: context = _platform_context() legacy_checkpoint = await FoundryStateStore.get_or_create("checkpoints/conversation-1", user_isolation=True) - legacy_approval = await FoundryStateStore.get_or_create("function_approvals", user_isolation=True) async with legacy_checkpoint: await legacy_checkpoint.create_item( "checkpoint-1", encode_checkpoint_value(_checkpoint("checkpoint-1").to_dict()), call_id=context.call_id ) - async with legacy_approval: - await legacy_approval.create_item( - "approval-1", _approval_request("approval-1").to_dict(), call_id=context.call_id - ) config = _config(is_hosted=True) checkpoints = CheckpointStoreProvider().get_store( config=config, context_id="conversation-1", platform_context=context ) - approvals = FunctionApprovalStoreProvider().get_store(config=config, platform_context=context) with pytest.raises(WorkflowCheckpointException, match="No checkpoint found"): await checkpoints.load("checkpoint-1") - with pytest.raises(KeyError, match="does not exist"): - await approvals.load_approval_request("approval-1") -async def test_hosted_session_checkpoint_and_approval_data_stay_in_one_sandbox() -> None: +async def test_hosted_session_and_checkpoint_data_stay_in_one_sandbox() -> None: config = _config(is_hosted=True) first_context = _platform_context(session_id="sandbox-1") second_context = _platform_context(session_id="sandbox-2") second_config = _config(is_hosted=True, session_id="sandbox-2") sessions = AgentSessionStoreProvider() checkpoints = CheckpointStoreProvider() - approvals = FunctionApprovalStoreProvider() first_session_store = sessions.get_store(config=config, platform_context=first_context) await first_session_store.set("response-1", AgentSession()) @@ -876,15 +770,6 @@ async def test_hosted_session_checkpoint_and_approval_data_stay_in_one_sandbox() with pytest.raises(WorkflowCheckpointException, match="No checkpoint found"): await second_checkpoint_store.load("checkpoint-1") - first_approval_store = approvals.get_store(config=config, platform_context=first_context) - await first_approval_store.save_approval_request("approval-1", _approval_request("approval-1")) - continued_approval_store = approvals.get_store(config=config, platform_context=continued_context) - assert await continued_approval_store.load_approval_request("approval-1") == _approval_request("approval-1") - second_approval_store = approvals.get_store(config=second_config, platform_context=second_context) - with pytest.raises(KeyError, match="does not exist"): - await second_approval_store.load_approval_request("approval-1") - assert await first_approval_store.load_approval_request("approval-1") == _approval_request("approval-1") - async def test_hosted_session_rejects_a_stale_etag_without_overwriting_the_winner() -> None: config = _config(is_hosted=True) From dcd6763e389dd59ff30e44c217b9108e3f6dbd6a Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 09:59:35 +0100 Subject: [PATCH 12/55] Clarify store=false OAuth consent failure wording --- python/packages/foundry_hosting/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/python/packages/foundry_hosting/README.md b/python/packages/foundry_hosting/README.md index 6d8a7808bb6..1c2ccfc0094 100644 --- a/python/packages/foundry_hosting/README.md +++ b/python/packages/foundry_hosting/README.md @@ -398,8 +398,9 @@ Failure boundaries: - The response fails if a consent link is not a safe absolute HTTPS URL or is outside the configured origin allowlist. The host does not expose that URL. -- The response fails with "OAuth consent continuation requires store=true." if the request has `store=false`. The host - exposes no consent or approval output for that request. +- Consent continuation requires `store=true`. If the request has `store=false`, the response fails and the host + exposes no consent or approval output. Consent appears during tool execution, after the response has started, so + this is a failed response, not an HTTP 400 rejection. - Consent at connection time (`tools/list`) behaves as before. Limits: From 0991cf631782462e34fa538bb8ef13cb328a0b9e Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 10:05:43 +0100 Subject: [PATCH 13/55] Strengthen custom storage sample CAS tests --- .../custom_storage_sample_helpers.py | 92 +++++++++ .../test_custom_storage_sample.py | 188 +++++++++--------- 2 files changed, 187 insertions(+), 93 deletions(-) create mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/custom_storage_sample_helpers.py diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/custom_storage_sample_helpers.py b/python/packages/foundry_hosting/tests/foundry_hosting/custom_storage_sample_helpers.py new file mode 100644 index 00000000000..980c436f82a --- /dev/null +++ b/python/packages/foundry_hosting/tests/foundry_hosting/custom_storage_sample_helpers.py @@ -0,0 +1,92 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Offline storage boundaries for the custom session-storage sample.""" + +from __future__ import annotations + +from copy import deepcopy +from types import ModuleType +from typing import Any + +from agent_framework import AgentSession +from azure.core import MatchConditions +from azure.cosmos.exceptions import CosmosHttpResponseError, CosmosResourceNotFoundError + +from agent_framework_foundry_hosting import FoundryRequestScope + + +def make_session(value: str) -> AgentSession: + session = AgentSession(session_id="inner-maf-session") + session.state["value"] = value + return session + + +def http_error(status: int) -> CosmosHttpResponseError: + if status == 404: + return CosmosResourceNotFoundError(status_code=404, message="missing") + return CosmosHttpResponseError(status_code=status, message=f"status {status}") + + +class FakeContainer: + """Emulate Cosmos create-only and exact-ETag operations in one event loop.""" + + def __init__(self) -> None: + self.items: dict[tuple[str, str], dict[str, Any]] = {} + self._version = 0 + self.omit_etag = False + self.create_error: int | None = None + self.calls: list[tuple[str, dict[str, Any]]] = [] + + def _stamp(self, body: dict[str, Any]) -> dict[str, Any]: + self._version += 1 + stored = {**deepcopy(body), "_etag": f'"{self._version}"'} + self.items[body["scope_key"], body["id"]] = stored + result = deepcopy(stored) + if self.omit_etag: + result["_etag"] = None + return result + + async def read_item(self, *, item: str, partition_key: str) -> dict[str, Any]: + stored = self.items.get((partition_key, item)) + if stored is None: + raise http_error(404) + return deepcopy(stored) + + async def create_item(self, *, body: dict[str, Any]) -> dict[str, Any]: + self.calls.append(("create", {})) + if self.create_error is not None: + raise http_error(self.create_error) + if (body["scope_key"], body["id"]) in self.items: + raise http_error(409) + return self._stamp(body) + + async def replace_item( + self, *, item: str, body: dict[str, Any], etag: str, match_condition: MatchConditions + ) -> dict[str, Any]: + self.calls.append(("replace", {"etag": etag, "match_condition": match_condition})) + assert match_condition == MatchConditions.IfNotModified + stored = self.items.get((body["scope_key"], item)) + if stored is None: + raise http_error(404) + if stored["_etag"] != etag: + raise http_error(412) + return self._stamp(body) + + async def delete_item(self, *, item: str, partition_key: str, etag: str, match_condition: MatchConditions) -> None: + self.calls.append(("delete", {"etag": etag, "match_condition": match_condition})) + assert match_condition == MatchConditions.IfNotModified + stored = self.items.get((partition_key, item)) + if stored is None: + raise http_error(404) + if stored["_etag"] != etag: + raise http_error(412) + del self.items[partition_key, item] + + +def cosmos_store(sample: ModuleType, container: FakeContainer) -> Any: + scope = FoundryRequestScope(session_id="sandbox", user_id="user", call_id="call", is_hosted=True) + return sample.CosmosSessionStore(container=container, scope=scope) + + +def local_store(sample: ModuleType, snapshots: dict[Any, Any], scope_key: str = "scope") -> Any: + return sample.LocalSessionStore(snapshots, scope_key=scope_key) diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_custom_storage_sample.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_custom_storage_sample.py index 09ad1783b75..bc7722b3898 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_custom_storage_sample.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_custom_storage_sample.py @@ -4,6 +4,7 @@ from __future__ import annotations +import asyncio import importlib.util import sys from pathlib import Path @@ -11,11 +12,12 @@ from typing import Any import pytest -from agent_framework import AgentSession from azure.core import MatchConditions -from azure.cosmos.exceptions import CosmosHttpResponseError, CosmosResourceNotFoundError +from azure.cosmos.exceptions import CosmosHttpResponseError -from agent_framework_foundry_hosting import FoundryRequestScope +from .custom_storage_sample_helpers import FakeContainer, cosmos_store, local_store, make_session + +pytestmark = pytest.mark.filterwarnings("ignore:.*SessionStore is experimental.*") _SAMPLE = ( Path(__file__).resolve().parents[4] @@ -39,66 +41,6 @@ def sample() -> ModuleType: return module -def _session(value: str) -> AgentSession: - session = AgentSession(session_id="inner-maf-session") - session.state["value"] = value - return session - - -def _http_error(status: int) -> CosmosHttpResponseError: - if status == 404: - return CosmosResourceNotFoundError(status_code=404, message="missing") - return CosmosHttpResponseError(status_code=status, message=f"status {status}") - - -class _FakeContainer: - """Server-side create-only and exact-ETag semantics for one partition.""" - - def __init__(self) -> None: - self.items: dict[tuple[str, str], dict[str, Any]] = {} - self._version = 0 - self.omit_etag = False - self.calls: list[tuple[str, dict[str, Any]]] = [] - - def _stamp(self, body: dict[str, Any]) -> dict[str, Any]: - self._version += 1 - stored = {**body, "_etag": f'"{self._version}"'} - self.items[body["scope_key"], body["id"]] = stored - return {**stored, "_etag": None} if self.omit_etag else dict(stored) - - async def read_item(self, *, item: str, partition_key: str) -> dict[str, Any]: - stored = self.items.get((partition_key, item)) - if stored is None: - raise _http_error(404) - return dict(stored) - - async def create_item(self, *, body: dict[str, Any]) -> dict[str, Any]: - self.calls.append(("create", {})) - if (body["scope_key"], body["id"]) in self.items: - raise _http_error(409) - return self._stamp(body) - - async def replace_item( - self, *, item: str, body: dict[str, Any], etag: str, match_condition: MatchConditions - ) -> dict[str, Any]: - self.calls.append(("replace", {"etag": etag, "match_condition": match_condition})) - stored = self.items.get((body["scope_key"], item)) - if stored is None: - raise _http_error(404) - if stored["_etag"] != etag: - raise _http_error(412) - return self._stamp(body) - - -def _cosmos_store(sample: ModuleType, container: _FakeContainer) -> Any: - scope = FoundryRequestScope(session_id="sandbox", user_id="user", call_id="call", is_hosted=True) - return sample.CosmosSessionStore(container=container, scope=scope) - - -def _local_store(sample: ModuleType, snapshots: dict[Any, Any], scope_key: str = "scope") -> Any: - return sample.LocalSessionStore(snapshots, scope_key=scope_key) - - async def test_sample_does_not_import_private_hosting_types() -> None: source = _SAMPLE.read_text(encoding="utf-8") assert "_ConditionalSessionStore" not in source @@ -108,88 +50,148 @@ async def test_sample_does_not_import_private_hosting_types() -> None: @pytest.mark.parametrize("kind", ["local", "cosmos"]) async def test_conditional_write_contract(sample: ModuleType, kind: str) -> None: - store = _local_store(sample, {}) if kind == "local" else _cosmos_store(sample, _FakeContainer()) + store = local_store(sample, {}) if kind == "local" else cosmos_store(sample, FakeContainer()) assert await store.get_with_revision(_APPROVAL_KEY) == (None, None) - first = await store.compare_and_set(_APPROVAL_KEY, _session("one"), expected_revision=None) + original = make_session("one") + original.state["nested"] = {"items": ["saved"]} + first = await store.compare_and_set(_APPROVAL_KEY, original, expected_revision=None) + original.state["nested"]["items"].append("original changed") assert isinstance(first, str) and first with pytest.raises(RuntimeError): - await store.compare_and_set(_APPROVAL_KEY, _session("dup"), expected_revision=None) + await store.compare_and_set(_APPROVAL_KEY, make_session("dup"), expected_revision=None) loaded, revision = await store.get_with_revision(_APPROVAL_KEY) assert revision == first assert loaded is not None and loaded.session_id == "inner-maf-session" assert loaded.state["value"] == "one" loaded.state["value"] = "mutated" + loaded.state["nested"]["items"].append("read changed") again, _ = await store.get_with_revision(_APPROVAL_KEY) assert again is not None and again.state["value"] == "one" + assert again.state["nested"] == {"items": ["saved"]} - second = await store.compare_and_set(_APPROVAL_KEY, _session("two"), expected_revision=first) + second = await store.compare_and_set(_APPROVAL_KEY, make_session("two"), expected_revision=first) assert second and second != first with pytest.raises(RuntimeError): - await store.compare_and_set(_APPROVAL_KEY, _session("stale"), expected_revision=first) + await store.compare_and_set(_APPROVAL_KEY, make_session("stale"), expected_revision=first) current, current_revision = await store.get_with_revision(_APPROVAL_KEY) assert current is not None and current.state["value"] == "two" assert current_revision == second with pytest.raises(ValueError): - await store.compare_and_set(_APPROVAL_KEY, _session("bad"), expected_revision="") + await store.compare_and_set(_APPROVAL_KEY, make_session("bad"), expected_revision="") @pytest.mark.parametrize("kind", ["local", "cosmos"]) async def test_exact_update_of_absent_key_conflicts(sample: ModuleType, kind: str) -> None: - store = _local_store(sample, {}) if kind == "local" else _cosmos_store(sample, _FakeContainer()) + store = local_store(sample, {}) if kind == "local" else cosmos_store(sample, FakeContainer()) with pytest.raises(RuntimeError): - await store.compare_and_set("missing", _session("x"), expected_revision="some-revision") + await store.compare_and_set("missing", make_session("x"), expected_revision="some-revision") assert await store.get_with_revision("missing") == (None, None) @pytest.mark.parametrize("kind", ["local", "cosmos"]) async def test_revision_reads_do_not_change_ordinary_write_tokens(sample: ModuleType, kind: str) -> None: - store = _local_store(sample, {}) if kind == "local" else _cosmos_store(sample, _FakeContainer()) + store = local_store(sample, {}) if kind == "local" else cosmos_store(sample, FakeContainer()) assert await store.get("alias") is None - await store.set("alias", _session("one")) + await store.set("alias", make_session("one")) _, revision = await store.get_with_revision("alias") - await store.compare_and_set("alias", _session("two"), expected_revision=revision) + await store.compare_and_set("alias", make_session("two"), expected_revision=revision) with pytest.raises(RuntimeError): - await store.set("alias", _session("stale")) + await store.set("alias", make_session("stale")) + + +@pytest.mark.parametrize("kind", ["local", "cosmos"]) +@pytest.mark.parametrize("operation", ["create", "update"]) +async def test_competing_request_views_allow_only_one_conditional_write( + sample: ModuleType, kind: str, operation: str +) -> None: + if kind == "local": + snapshots: dict[Any, Any] = {} + first, second = local_store(sample, snapshots), local_store(sample, snapshots) + else: + container = FakeContainer() + first, second = cosmos_store(sample, container), cosmos_store(sample, container) + + revision = None + if operation == "update": + revision = await first.compare_and_set(_APPROVAL_KEY, make_session("initial"), expected_revision=None) + assert (await second.get_with_revision(_APPROVAL_KEY))[1] == revision + + outcomes = await asyncio.gather( + first.compare_and_set(_APPROVAL_KEY, make_session("first"), expected_revision=revision), + second.compare_and_set(_APPROVAL_KEY, make_session("second"), expected_revision=revision), + return_exceptions=True, + ) + successes = [outcome for outcome in outcomes if isinstance(outcome, str)] + conflicts = [outcome for outcome in outcomes if isinstance(outcome, RuntimeError)] + assert len(successes) == len(conflicts) == 1 + assert successes[0] and successes[0] != revision + if kind == "cosmos": + assert isinstance(conflicts[0].__cause__, CosmosHttpResponseError) + stored, stored_revision = await first.get_with_revision(_APPROVAL_KEY) + assert stored is not None and stored.state["value"] in {"first", "second"} + assert stored_revision == successes[0] + + +@pytest.mark.parametrize("kind", ["local", "cosmos"]) +async def test_stale_delete_does_not_remove_another_requests_snapshot(sample: ModuleType, kind: str) -> None: + if kind == "local": + snapshots: dict[Any, Any] = {} + first, second = local_store(sample, snapshots), local_store(sample, snapshots) + else: + container = FakeContainer() + first, second = cosmos_store(sample, container), cosmos_store(sample, container) + + await first.set("alias", make_session("initial")) + assert await second.get("alias") is not None + await second.set("alias", make_session("newer")) + with pytest.raises(RuntimeError): + await first.delete("alias") + current = await second.get("alias") + assert current is not None and current.state["value"] == "newer" + await second.delete("alias") + await second.delete("alias") + assert await second.get("alias") is None async def test_local_store_scopes_are_isolated(sample: ModuleType) -> None: snapshots: dict[Any, Any] = {} - first = _local_store(sample, snapshots, "scope-a") - second = _local_store(sample, snapshots, "scope-b") - await first.compare_and_set(_APPROVAL_KEY, _session("a"), expected_revision=None) + first = local_store(sample, snapshots, "scope-a") + second = local_store(sample, snapshots, "scope-b") + await first.compare_and_set(_APPROVAL_KEY, make_session("a"), expected_revision=None) assert await second.get_with_revision(_APPROVAL_KEY) == (None, None) async def test_cosmos_uses_server_conditions(sample: ModuleType) -> None: - container = _FakeContainer() - store = _cosmos_store(sample, container) - revision = await store.compare_and_set(_APPROVAL_KEY, _session("one"), expected_revision=None) - await store.compare_and_set(_APPROVAL_KEY, _session("two"), expected_revision=revision) + container = FakeContainer() + store = cosmos_store(sample, container) + revision = await store.compare_and_set(_APPROVAL_KEY, make_session("one"), expected_revision=None) + await store.compare_and_set(_APPROVAL_KEY, make_session("two"), expected_revision=revision) assert container.calls[0] == ("create", {}) assert container.calls[1] == ("replace", {"etag": revision, "match_condition": MatchConditions.IfNotModified}) assert all("/" not in item_id for _, item_id in container.items) async def test_cosmos_missing_ack_revision_fails(sample: ModuleType) -> None: - container = _FakeContainer() + container = FakeContainer() container.omit_etag = True - store = _cosmos_store(sample, container) + store = cosmos_store(sample, container) with pytest.raises(RuntimeError, match="ETag"): - await store.compare_and_set(_APPROVAL_KEY, _session("one"), expected_revision=None) + await store.compare_and_set(_APPROVAL_KEY, make_session("one"), expected_revision=None) + stored, revision = await store.get_with_revision(_APPROVAL_KEY) + assert stored is not None and stored.state["value"] == "one" + assert revision + with pytest.raises(RuntimeError): + await store.compare_and_set(_APPROVAL_KEY, make_session("duplicate"), expected_revision=None) async def test_cosmos_other_errors_propagate(sample: ModuleType) -> None: - container = _FakeContainer() - - async def fail(*, body: dict[str, Any]) -> dict[str, Any]: - raise _http_error(503) - - container.create_item = fail # type: ignore[method-assign] - store = _cosmos_store(sample, container) + container = FakeContainer() + container.create_error = 503 + store = cosmos_store(sample, container) with pytest.raises(CosmosHttpResponseError) as exc_info: - await store.compare_and_set(_APPROVAL_KEY, _session("one"), expected_revision=None) + await store.compare_and_set(_APPROVAL_KEY, make_session("one"), expected_revision=None) assert not isinstance(exc_info.value, RuntimeError) From 8038d4280df1469146404dfc1f42aaf18b51920e Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 10:07:20 +0100 Subject: [PATCH 14/55] Clarify local custom store provider isolation --- .../test_custom_storage_sample.py | 21 +++++++++++++++++++ .../responses/custom_storage/README.md | 20 ++++++++++-------- .../responses/custom_storage/main.py | 11 +++++----- 3 files changed, 38 insertions(+), 14 deletions(-) diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_custom_storage_sample.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_custom_storage_sample.py index bc7722b3898..fec126bb47c 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_custom_storage_sample.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_custom_storage_sample.py @@ -10,8 +10,10 @@ from pathlib import Path from types import ModuleType from typing import Any +from unittest.mock import MagicMock import pytest +from azure.ai.agentserver.core import AgentConfig, FoundryAgentRequestContext from azure.core import MatchConditions from azure.cosmos.exceptions import CosmosHttpResponseError @@ -165,6 +167,25 @@ async def test_local_store_scopes_are_isolated(sample: ModuleType) -> None: assert await second.get_with_revision(_APPROVAL_KEY) == (None, None) +async def test_local_snapshots_are_shared_only_within_one_provider(sample: ModuleType) -> None: + config = MagicMock(spec=AgentConfig) + config.is_hosted = False + context = FoundryAgentRequestContext() + provider = sample.CustomSessionStoreProvider() + other_provider = sample.CustomSessionStoreProvider() + first = provider.get_store(config=config, platform_context=context) + same_provider = provider.get_store(config=config, platform_context=context) + other = other_provider.get_store(config=config, platform_context=context) + + revision = await first.compare_and_set(_APPROVAL_KEY, make_session("one"), expected_revision=None) + + assert first is not same_provider + stored, stored_revision = await same_provider.get_with_revision(_APPROVAL_KEY) + assert stored is not None and stored.state["value"] == "one" + assert stored_revision == revision + assert await other.get_with_revision(_APPROVAL_KEY) == (None, None) + + async def test_cosmos_uses_server_conditions(sample: ModuleType) -> None: container = FakeContainer() store = cosmos_store(sample, container) diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md index 83a0117cc87..e890f0155b5 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md @@ -54,12 +54,14 @@ newer snapshot. An absent delete is idempotent. Missing ETags and mismatched stored scope fail closed; other Cosmos failures propagate without a local fallback. -Local runs use isolated in-memory snapshots with the same conditional behavior, -but only inside **one process and event loop**. The local store gives no -guarantee across workers or processes. Snapshots are lost when the process -exits and are **single-user development only**: -local headers/session selectors are not a trusted platform authentication -boundary. Explicit local sessions have separate namespaces. +For local runs, each `CustomSessionStoreProvider` owns its in-memory snapshots. +Only the stores from that provider in **one process and event loop** coordinate +their conditional writes. Separate provider instances do not share snapshots, +even in the same process. Use one provider and one worker for local development. +Snapshots are lost when the provider and its stores are discarded or the +process exits. They are **single-user development only**: local headers and +session selectors are not a trusted platform authentication boundary. Explicit +local sessions have separate namespaces. ## Approval state and revisioned writes @@ -96,9 +98,9 @@ private hosting type. The sample stores follow these rules: not happen. The local store implements the same methods for development. Its conditional -write is atomic only inside one process and event loop. Use a store with -server-side conditional writes, such as Cosmos, when more than one worker or -process can serve the same conversation. +write is atomic only among stores from the same provider in one event loop. +Use a store with server-side conditional writes, such as Cosmos, when separate +providers, workers, or processes can serve the same conversation. Without these methods, the host can still use the store for ordinary session history. A non-hosted request that needs approval state fails with a diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/main.py b/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/main.py index 850ab4ceb74..8d5c1723c18 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/main.py +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/main.py @@ -20,8 +20,9 @@ authenticate with managed identity. Both stores also expose the structural ``get_with_revision``/``compare_and_set`` capability that hosted agent approvals require. Cosmos uses server-side create-only writes and exact ETag matches. Local -runs use process-local snapshots: their conditional writes are atomic only within -one process, and they are not a multi-user authentication boundary. +runs use snapshots owned by one provider: their conditional writes are atomic +only within one process and event loop, and they are not a multi-user +authentication boundary. """ from __future__ import annotations @@ -166,8 +167,8 @@ async def delete(self, session_id: str) -> None: class LocalSessionStore(SessionStore): """Request-local concurrency tokens over scoped, process-local snapshots. - Conditional writes are atomic only inside this single process and event loop. - They do not coordinate other workers or processes. + Conditional writes coordinate only stores sharing the same snapshots in one + event loop. Separate providers, workers, and processes do not share them. """ def __init__(self, snapshots: dict[tuple[str, str], tuple[str, dict[str, Any]]], *, scope_key: str) -> None: @@ -222,7 +223,7 @@ async def delete(self, session_id: str) -> None: class CustomSessionStoreProvider(StoreProvider[SessionStore]): - """Reuse only the backend; each request gets an isolated ETag/working-copy view.""" + """Share one backend across request-specific ETag and working-copy views.""" def __init__(self) -> None: self._local_snapshots: dict[tuple[str, str], tuple[str, dict[str, Any]]] = {} From 8a713288bfd6d08bda8fb86b8ffd60e072e35745 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 10:17:25 +0100 Subject: [PATCH 15/55] Fix native workflow stateless tool ownership --- .../_shared.py | 37 +++++++-- .../foundry_hosting/test_workflow_state.py | 76 ++++++++++++++----- .../foundry_hosting/workflow_tool_helpers.py | 66 ++++++++++++++++ 3 files changed, 157 insertions(+), 22 deletions(-) create mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/workflow_tool_helpers.py diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py index 335b72244ac..dbea4323e1b 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py @@ -14,6 +14,7 @@ from typing import Any, Generic, Literal, Protocol, TypeAlias, TypeGuard, cast from agent_framework import ( + SKIP_PARSING, Agent, AgentContext, AgentExecutor, @@ -21,6 +22,7 @@ AgentResponse, AgentRunInputs, Content, + FunctionTool, HistoryProvider, InMemoryHistoryProvider, Message, @@ -423,7 +425,7 @@ class AgentFactory(Protocol[AgentRequestT]): def __call__(self, *, request: AgentRequestT) -> SupportsAgentRun | Awaitable[SupportsAgentRun]: """Create an agent, optionally using the current request.""" - ... + raise NotImplementedError AgentSource: TypeAlias = SupportsAgentRun | AgentFactory[RequestT] @@ -774,12 +776,31 @@ def validate_workflow_source(source: object) -> None: raise TypeError("A workflow factory must accept one request argument.") from exc +def _is_stateless_function_tool(value: object) -> bool: + if type(value) is not FunctionTool: + return False + return ( + inspect.isfunction(value.func) + and value.func.__closure__ is None + and value._instance is None # pyright: ignore[reportPrivateUsage] + and value.max_invocations is None + and value.max_invocation_exceptions is None + and ( + value.result_parser is None + or value.result_parser is SKIP_PARSING + or (inspect.isfunction(value.result_parser) and value.result_parser.__closure__ is None) + ) + ) + + class WorkflowResolver(Generic[RequestT]): """Reject reuse of mutable graphs and known request-bound resources. This is an ownership guard, not a clone operation or a proof that arbitrary - application globals are stateless. Factories must allocate their resources - without performing workflow or tool side effects. + application globals, function attributes, or default arguments are stateless. + Plain function tools without bound instances, closures, or lifetime limits may + be shared. Applications must keep those functions stateless. Factories must + allocate mutable resources without performing workflow or tool side effects. """ def __init__(self, source: WorkflowSource[RequestT]) -> None: @@ -824,13 +845,19 @@ def collect(graph: Workflow) -> None: resources.extend(agent.mcp_tools) tools = agent.default_options.get("tools", ()) if isinstance(tools, Sequence): - resources.extend(tool for tool in cast(Sequence[object], tools) if not isinstance(tool, Mapping)) + for tool in cast(Sequence[object], tools): + if isinstance(tool, Mapping) or _is_stateless_function_tool(tool): + continue + resources.append(tool) + if isinstance(tool, FunctionTool) and tool._instance is not None: # pyright: ignore[reportPrivateUsage] + resources.append(tool._instance) # pyright: ignore[reportPrivateUsage] unique_resources = {id(resource): resource for resource in resources} for identifier, resource in unique_resources.items(): previous = self._owned.get(id(resource)) if (previous is not None and previous() is resource) or self._strong_owned.get(identifier) is resource: raise RuntimeError( - "Native workflow requests cannot share workflows, executors, agents, clients, or providers. " + "Native workflow requests cannot share workflows, executors, agents, clients, providers, " + "or mutable tools. " "Use a request-aware factory that creates fresh instances." ) for identifier, resource in unique_resources.items(): diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py index 0a9896bb218..af04a6c5126 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py @@ -28,7 +28,6 @@ WorkflowInvocationKwargs, handler, response_handler, - tool, ) from agent_framework._workflows._const import RESOLVED_WORKFLOW_RUN_KWARGS_KEY from azure.ai.agentserver.core import AgentConfig, FoundryAgentRequestContext @@ -44,6 +43,15 @@ WorkflowHead, ) +from .workflow_tool_helpers import ( + MutableToolOwner, + UnusedClient, + mutable_function_tool, + shared_async_function, + shared_function, + workflow_with_tools, +) + def _scope(*, user: str = "user", sandbox: str = "sandbox", call: str = "call") -> FoundryRequestScope: return FoundryRequestScope(sandbox, user, call, False) @@ -263,30 +271,64 @@ async def create(request: object) -> Workflow: assert requests == [one, two] -@pytest.mark.parametrize("mcp", [False, True]) -async def test_resolver_rejects_reused_local_and_mcp_tools(mcp: bool) -> None: - class _UnusedClient(BaseChatClient): - async def _inner_get_response(self, **kwargs: Any) -> Any: - raise AssertionError("Ownership validation must not call the model.") - - @tool - def local_tool(value: str) -> str: - """Return a value without accessing external services.""" - return value +@pytest.mark.parametrize("shared", [shared_function, shared_async_function]) +async def test_resolver_allows_reused_stateless_function_tools(shared: Any) -> None: + resolver: WorkflowResolver[object] = WorkflowResolver(lambda request: workflow_with_tools([shared])) + first, second = await resolver.resolve(object()), await resolver.resolve(object()) + assert first is not second + for workflow in (first, second): + executor = workflow.get_start_executor() + assert isinstance(executor, AgentExecutor) + assert executor.agent.default_options["tools"][0] is shared - shared = MCPStreamableHTTPTool(name="shared", url="https://unused.example.test/mcp") if mcp else local_tool - def create(request: object) -> Workflow: - agent = Agent(client=_UnusedClient(), name="agent", tools=[shared]) - return _workflow(AgentExecutor(agent, id="agent")) - - resolver: WorkflowResolver[object] = WorkflowResolver(create) +async def test_resolver_rejects_reused_mcp_tools() -> None: + shared = MCPStreamableHTTPTool(name="shared", url="https://unused.example.test/mcp") + resolver: WorkflowResolver[object] = WorkflowResolver( + lambda request: workflow_with_tools([shared_function, shared]) + ) first = await resolver.resolve(object()) with pytest.raises(RuntimeError, match="cannot share"): await resolver.resolve(object()) assert first.get_start_executor().id == "agent" +@pytest.mark.parametrize( + "kind", ["bound", "closure", "subclass", "parser", "max_invocations", "max_invocation_exceptions"] +) +async def test_resolver_rejects_reused_mutable_tools_but_allows_fresh_ones(kind: str) -> None: + shared = mutable_function_tool(kind) + resolver: WorkflowResolver[object] = WorkflowResolver( + lambda request: workflow_with_tools([shared_function, shared]) + ) + await resolver.resolve(object()) + with pytest.raises(RuntimeError, match="mutable tools"): + await resolver.resolve(object()) + fresh: WorkflowResolver[object] = WorkflowResolver( + lambda request: workflow_with_tools([shared_function, mutable_function_tool(kind)]) + ) + await fresh.resolve(object()) + await fresh.resolve(object()) + + +async def test_resolver_rejects_reused_owner_even_with_fresh_bound_tool_wrappers() -> None: + owner = MutableToolOwner() + resolver: WorkflowResolver[object] = WorkflowResolver(lambda request: workflow_with_tools([owner.count])) + await resolver.resolve(object()) + with pytest.raises(RuntimeError, match="cannot share"): + await resolver.resolve(object()) + + +async def test_resolver_rejects_reused_client_with_stateless_tools() -> None: + client = UnusedClient() + resolver: WorkflowResolver[object] = WorkflowResolver( + lambda request: workflow_with_tools([shared_function], client=client) + ) + await resolver.resolve(object()) + with pytest.raises(RuntimeError, match="cannot share"): + await resolver.resolve(object()) + + async def test_resolver_rejects_reused_registry_backed_agent_resources() -> None: class _UnusedClient(BaseChatClient): async def _inner_get_response(self, **kwargs: Any) -> Any: diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/workflow_tool_helpers.py b/python/packages/foundry_hosting/tests/foundry_hosting/workflow_tool_helpers.py new file mode 100644 index 00000000000..2866bc010a4 --- /dev/null +++ b/python/packages/foundry_hosting/tests/foundry_hosting/workflow_tool_helpers.py @@ -0,0 +1,66 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Model-free tools and workflow factories for resource-ownership tests.""" + +from __future__ import annotations + +from typing import Any + +from agent_framework import Agent, AgentExecutor, BaseChatClient, FunctionTool, Workflow, WorkflowBuilder, tool + + +class UnusedClient(BaseChatClient): + async def _inner_get_response(self, **kwargs: Any) -> Any: + raise AssertionError("Ownership validation must not call the model.") + + +@tool +def shared_function(value: str) -> str: + """Return a value without accessing external services.""" + return value + + +@tool +async def shared_async_function(value: str) -> str: + """Return a value asynchronously without accessing external services.""" + return value + + +class MutableToolOwner: + def __init__(self) -> None: + self.calls = 0 + + @tool + def count(self, value: str) -> str: + """Count calls and return the input.""" + self.calls += 1 + return value + + +class CustomFunctionTool(FunctionTool): + pass + + +def mutable_function_tool(kind: str) -> FunctionTool: + if kind == "bound": + return MutableToolOwner().count + if kind == "closure": + calls: list[str] = [] + + @tool + def capture(value: str) -> str: + """Record and return the input.""" + calls.append(value) + return value + + return capture + if kind == "subclass": + return CustomFunctionTool(name="custom", func=shared_function.func) + if kind == "parser": + return FunctionTool(name="parser", func=shared_function.func, result_parser=MutableToolOwner().count) + return FunctionTool(name="limited", func=shared_function.func, **{kind: 1}) + + +def workflow_with_tools(tools: list[Any], *, client: BaseChatClient | None = None) -> Workflow: + agent = Agent(client=client or UnusedClient(), name="agent", tools=tools) + return WorkflowBuilder(start_executor=AgentExecutor(agent, id="agent")).build() From 191ee4f9714d61f19cfb69a8bf4edc88d3fe484a Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 10:18:41 +0100 Subject: [PATCH 16/55] Reject wildcard and list revisions in Foundry session CAS Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../_state_store.py | 12 +++++++++--- .../foundry_hosting/tests/test_state_store.py | 18 ++++++++++++++++++ 2 files changed, 27 insertions(+), 3 deletions(-) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_state_store.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_state_store.py index c3365286235..939f93f2c2c 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_state_store.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_state_store.py @@ -423,7 +423,8 @@ async def compare_and_set(self, session_id: str, session: AgentSession, *, expec """Persist a create-only or exact-revision session transition. ``None`` requires an absent entry; a non-empty revision requires that - exact existing entry. Conflicts never fall back to an upsert. An + exact existing entry. Wildcard and list revisions are rejected. + Conflicts never fall back to an upsert. An acknowledgement without a revision is a failure, even if storage wrote the value. The caller must not dispatch protected work in that case. @@ -434,8 +435,13 @@ async def compare_and_set(self, session_id: str, session: AgentSession, *, expec custom conditional store. """ SessionStore.validate_session_id(session_id) - if expected_revision is not None and (not isinstance(expected_revision, str) or not expected_revision): - raise ValueError("expected_revision must be None or a non-empty string.") + if expected_revision is not None and ( + not isinstance(expected_revision, str) + or not expected_revision + or expected_revision.strip() == "*" + or "," in expected_revision + ): + raise ValueError("expected_revision must be None or one exact non-wildcard revision.") if self._scope is None or not os.environ.get("FOUNDRY_HOSTING_ENVIRONMENT"): raise RuntimeError( "The default non-hosted Foundry session store cannot atomically claim approvals across processes. " diff --git a/python/packages/foundry_hosting/tests/test_state_store.py b/python/packages/foundry_hosting/tests/test_state_store.py index 2ea154c77d6..34601b2d705 100644 --- a/python/packages/foundry_hosting/tests/test_state_store.py +++ b/python/packages/foundry_hosting/tests/test_state_store.py @@ -588,6 +588,24 @@ async def test_conditional_write_without_acknowledged_revision_fails_closed( ) +@pytest.mark.parametrize("expected_revision", ["*", " * ", '"a", "b"']) +async def test_conditional_write_rejects_wildcard_or_list_revision_before_backend_access( + monkeypatch: pytest.MonkeyPatch, expected_revision: str +) -> None: + monkeypatch.setenv("FOUNDRY_HOSTING_ENVIRONMENT", "hosted") + scope = FoundryRequestScope.from_context(_config(is_hosted=True), _platform_context()) + with ( + patch( + "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", new=AsyncMock() + ) as backend, + pytest.raises(ValueError, match="exact non-wildcard revision"), + ): + await FoundryAgentSessionStore(_platform_context(), scope=scope).compare_and_set( + "canonical", AgentSession(), expected_revision=expected_revision + ) + backend.assert_not_awaited() + + async def test_default_nonhosted_approval_cas_fails_before_backend_access() -> None: with ( patch( From 3520a8f006d4c3937e2fdc5b89f81f6a04ac129f Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 10:20:48 +0100 Subject: [PATCH 17/55] Harden custom Cosmos approval CAS sample --- .../custom_storage_sample_helpers.py | 18 ++- .../test_custom_storage_sample.py | 107 +++++++++++++++++- .../responses/custom_storage/README.md | 13 ++- .../responses/custom_storage/main.py | 25 +++- 4 files changed, 148 insertions(+), 15 deletions(-) diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/custom_storage_sample_helpers.py b/python/packages/foundry_hosting/tests/foundry_hosting/custom_storage_sample_helpers.py index 980c436f82a..2c2072500da 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/custom_storage_sample_helpers.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/custom_storage_sample_helpers.py @@ -14,6 +14,8 @@ from agent_framework_foundry_hosting import FoundryRequestScope +_STORED_ETAG = object() + def make_session(value: str) -> AgentSession: session = AgentSession(session_id="inner-maf-session") @@ -33,17 +35,23 @@ class FakeContainer: def __init__(self) -> None: self.items: dict[tuple[str, str], dict[str, Any]] = {} self._version = 0 - self.omit_etag = False + self.acknowledgement_etag: object = _STORED_ETAG self.create_error: int | None = None self.calls: list[tuple[str, dict[str, Any]]] = [] + @staticmethod + def _matches_if_match(condition: str, current: str) -> bool: + if condition.strip() == "*" or condition == current: + return True + return current in (candidate.strip() for candidate in condition.split(",")) + def _stamp(self, body: dict[str, Any]) -> dict[str, Any]: self._version += 1 stored = {**deepcopy(body), "_etag": f'"{self._version}"'} self.items[body["scope_key"], body["id"]] = stored result = deepcopy(stored) - if self.omit_etag: - result["_etag"] = None + if self.acknowledgement_etag is not _STORED_ETAG: + result["_etag"] = self.acknowledgement_etag return result async def read_item(self, *, item: str, partition_key: str) -> dict[str, Any]: @@ -68,7 +76,7 @@ async def replace_item( stored = self.items.get((body["scope_key"], item)) if stored is None: raise http_error(404) - if stored["_etag"] != etag: + if not self._matches_if_match(etag, stored["_etag"]): raise http_error(412) return self._stamp(body) @@ -78,7 +86,7 @@ async def delete_item(self, *, item: str, partition_key: str, etag: str, match_c stored = self.items.get((partition_key, item)) if stored is None: raise http_error(404) - if stored["_etag"] != etag: + if not self._matches_if_match(etag, stored["_etag"]): raise http_error(412) del self.items[partition_key, item] diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_custom_storage_sample.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_custom_storage_sample.py index fec126bb47c..3f6821f1e6f 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_custom_storage_sample.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_custom_storage_sample.py @@ -90,7 +90,7 @@ async def test_conditional_write_contract(sample: ModuleType, kind: str) -> None async def test_exact_update_of_absent_key_conflicts(sample: ModuleType, kind: str) -> None: store = local_store(sample, {}) if kind == "local" else cosmos_store(sample, FakeContainer()) with pytest.raises(RuntimeError): - await store.compare_and_set("missing", make_session("x"), expected_revision="some-revision") + await store.compare_and_set("missing", make_session("x"), expected_revision='"missing"') assert await store.get_with_revision("missing") == (None, None) @@ -198,7 +198,7 @@ async def test_cosmos_uses_server_conditions(sample: ModuleType) -> None: async def test_cosmos_missing_ack_revision_fails(sample: ModuleType) -> None: container = FakeContainer() - container.omit_etag = True + container.acknowledgement_etag = None store = cosmos_store(sample, container) with pytest.raises(RuntimeError, match="ETag"): await store.compare_and_set(_APPROVAL_KEY, make_session("one"), expected_revision=None) @@ -209,6 +209,109 @@ async def test_cosmos_missing_ack_revision_fails(sample: ModuleType) -> None: await store.compare_and_set(_APPROVAL_KEY, make_session("duplicate"), expected_revision=None) +@pytest.mark.parametrize("condition", ["*", '"stale","1"']) +async def test_cosmos_fake_models_non_exact_if_match(sample: ModuleType, condition: str) -> None: + container = FakeContainer() + store = cosmos_store(sample, container) + await store.compare_and_set(_APPROVAL_KEY, make_session("one"), expected_revision=None) + scope_key, item_id = next(iter(container.items)) + body = {"id": item_id, "scope_key": scope_key, "session": make_session("replaced").to_dict()} + + await container.replace_item(item=item_id, body=body, etag=condition, match_condition=MatchConditions.IfNotModified) + + stored, _ = await store.get_with_revision(_APPROVAL_KEY) + assert stored is not None and stored.state["value"] == "replaced" + + +@pytest.mark.parametrize( + "revision", + ["*", " * ", '"1","2"', '"1", "2"', '"2","1"', 'W/"2"', "2", '"2"\n', '"2"\x00', '"2",*'], +) +async def test_cosmos_rejects_non_exact_revision_before_write(sample: ModuleType, revision: str) -> None: + container = FakeContainer() + store = cosmos_store(sample, container) + first = await store.compare_and_set(_APPROVAL_KEY, make_session("one"), expected_revision=None) + current = await store.compare_and_set(_APPROVAL_KEY, make_session("two"), expected_revision=first) + calls = len(container.calls) + + with pytest.raises(RuntimeError, match="ETag"): + await store.compare_and_set(_APPROVAL_KEY, make_session("overwritten"), expected_revision=revision) + + assert len(container.calls) == calls + stored, stored_revision = await store.get_with_revision(_APPROVAL_KEY) + assert stored is not None and stored.state["value"] == "two" + assert stored_revision == current + + +@pytest.mark.parametrize("etag", ['""', '"*"', '"a,b"', '"\xe9"']) +async def test_cosmos_accepts_one_opaque_strong_etag(sample: ModuleType, etag: str) -> None: + container = FakeContainer() + store = cosmos_store(sample, container) + await store.compare_and_set(_APPROVAL_KEY, make_session("one"), expected_revision=None) + container.items[next(iter(container.items))]["_etag"] = etag + assert (await store.get_with_revision(_APPROVAL_KEY))[1] == etag + + new_revision = await store.compare_and_set(_APPROVAL_KEY, make_session("two"), expected_revision=etag) + + assert new_revision != etag + stored, _ = await store.get_with_revision(_APPROVAL_KEY) + assert stored is not None and stored.state["value"] == "two" + + +@pytest.mark.parametrize("etag", [None, "", 42, "*", "unquoted", 'W/"one"', '"one","two"', '"one"\n']) +async def test_cosmos_rejects_invalid_read_etag(sample: ModuleType, etag: object) -> None: + container = FakeContainer() + store = cosmos_store(sample, container) + await store.compare_and_set(_APPROVAL_KEY, make_session("one"), expected_revision=None) + container.items[next(iter(container.items))]["_etag"] = etag + + with pytest.raises(RuntimeError, match="ETag"): + await store.get_with_revision(_APPROVAL_KEY) + with pytest.raises(RuntimeError, match="ETag"): + await store.get(_APPROVAL_KEY) + with pytest.raises(RuntimeError, match="ETag"): + await store.delete(_APPROVAL_KEY) + assert all(call[0] != "delete" for call in container.calls) + + +@pytest.mark.parametrize("etag", [None, "", 42, "*", "unquoted", 'W/"one"', '"one","two"', '"one"\n']) +async def test_cosmos_rejects_invalid_write_acknowledgement(sample: ModuleType, etag: object) -> None: + container = FakeContainer() + container.acknowledgement_etag = etag + store = cosmos_store(sample, container) + + with pytest.raises(RuntimeError, match="ETag"): + await store.compare_and_set(_APPROVAL_KEY, make_session("one"), expected_revision=None) + + stored, revision = await store.get_with_revision(_APPROVAL_KEY) + assert stored is not None and stored.state["value"] == "one" + assert revision + + +async def test_cosmos_rejects_invalid_cached_delete_etag(sample: ModuleType) -> None: + container = FakeContainer() + store = cosmos_store(sample, container) + await store.set(_APPROVAL_KEY, make_session("one")) + store._etags[_APPROVAL_KEY] = "*" + + with pytest.raises(RuntimeError, match="ETag"): + await store.delete(_APPROVAL_KEY) + + assert all(call[0] != "delete" for call in container.calls) + stored, _ = await store.get_with_revision(_APPROVAL_KEY) + assert stored is not None and stored.state["value"] == "one" + + +async def test_local_store_keeps_opaque_revision_values(sample: ModuleType) -> None: + snapshots = {("scope", _APPROVAL_KEY): ("opaque-version", make_session("one").to_dict())} + store = local_store(sample, snapshots) + assert (await store.get_with_revision(_APPROVAL_KEY))[1] == "opaque-version" + + revision = await store.compare_and_set(_APPROVAL_KEY, make_session("two"), expected_revision="opaque-version") + + assert revision != "opaque-version" + + async def test_cosmos_other_errors_propagate(sample: ModuleType) -> None: container = FakeContainer() container.create_error = 503 diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md index e890f0155b5..c0ff6a9b898 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md @@ -91,8 +91,11 @@ private hosting type. The sample stores follow these rules: - Keys are opaque strings. They can differ from `AgentSession.session_id` and can contain characters such as `/`. Cosmos item IDs hash the key. - Cosmos uses `create_item` and `replace_item` with the ETag and - `MatchConditions.IfNotModified`. The service enforces both conditions. - A write result without an ETag fails. + `MatchConditions.IfNotModified`. The service applies each condition in the + account's write region; see [Cosmos prerequisites](#cosmos-prerequisites). + The store accepts one quoted, strong ETag as a revision. It rejects wildcard + and list `If-Match` values before sending a write or delete. A missing or + invalid ETag in a read or write result fails. - A write that fails or is cancelled may still have been committed. Reload the state before you decide what to do next. Do not assume that the write did not happen. @@ -116,6 +119,12 @@ COSMOS_DATABASE_NAME= COSMOS_CONTAINER_NAME= ``` +For approval state, the Cosmos account **must use one write region**. +Multi-write-region accounts can accept conditional updates independently in +different regions before resolving conflicts. This sample does not provide a +single global approval claim in that configuration. See +[Cosmos optimistic concurrency and global distribution](https://learn.microsoft.com/en-us/azure/cosmos-db/database-transactions-optimistic-concurrency#optimistic-concurrency-control-and-global-distribution). + The hosted provider uses `azure.identity.aio.ManagedIdentityCredential`, with the platform-provided `FOUNDRY_AGENT_INSTANCE_CLIENT_ID` when present. Grant that managed identity **Cosmos DB Built-in Data Contributor** at the narrowest diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/main.py b/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/main.py index 8d5c1723c18..231729059d0 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/main.py +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/main.py @@ -1,3 +1,5 @@ +# Copyright (c) Microsoft. All rights reserved. + # /// script # requires-python = ">=3.11" # dependencies = [ @@ -12,17 +14,15 @@ # ] # /// -# Copyright (c) Microsoft. All rights reserved. - """Trusted user-and-sandbox session snapshots with optimistic concurrency. Hosted runs use an existing Cosmos DB container partitioned by /scope_key and authenticate with managed identity. Both stores also expose the structural ``get_with_revision``/``compare_and_set`` capability that hosted agent approvals -require. Cosmos uses server-side create-only writes and exact ETag matches. Local -runs use snapshots owned by one provider: their conditional writes are atomic -only within one process and event loop, and they are not a multi-user -authentication boundary. +require. Cosmos uses server-side create-only writes and exact ETag matches; use +a single-write-region account for approval authority. Local runs use snapshots +owned by one provider: their conditional writes are atomic only within one +process and event loop, and they are not a multi-user authentication boundary. """ from __future__ import annotations @@ -31,6 +31,7 @@ import hashlib import json import os +import re import uuid from contextlib import AsyncExitStack from copy import deepcopy @@ -48,6 +49,7 @@ from dotenv import load_dotenv _CONFLICT = "Another request advanced this agent session; reload before writing." +_SINGLE_ETAG = re.compile(r'"[\x21\x23-\x7e\x80-\xff]*"') _MAX_COSMOS_ITEM_BYTES = 2_000_000 _SESSION_TOO_LARGE = ( "Agent session exceeds the 2,000,000-byte Cosmos snapshot budget; reduce session state or start a new conversation." @@ -59,6 +61,12 @@ def _validate_revision(expected_revision: str | None) -> None: raise ValueError("expected_revision must be None or a non-empty string.") +def _validate_cosmos_etag(etag: str) -> None: + # If-Match treats a wildcard or list as something other than one exact revision. + if _SINGLE_ETAG.fullmatch(etag) is None: + raise RuntimeError("A Cosmos revision must be a single strong ETag.") + + class CosmosSessionStore(SessionStore): """Keep a request's ETags separate from every other request's working copy.""" @@ -98,6 +106,7 @@ async def get_with_revision(self, session_id: str) -> tuple[AgentSession | None, etag = item.get("_etag") if not isinstance(etag, str) or not etag: raise RuntimeError("Stored Cosmos session is missing its ETag.") + _validate_cosmos_etag(etag) return AgentSession.from_dict(item["session"]), etag async def set(self, session_id: str, session: AgentSession) -> None: @@ -113,6 +122,8 @@ async def compare_and_set(self, session_id: str, session: AgentSession, *, expec cancelled write may still have committed, so callers must reload before deciding. """ _validate_revision(expected_revision) + if expected_revision is not None: + _validate_cosmos_etag(expected_revision) item: dict[str, Any] = { "id": self._item_id(session_id), "scope_key": self._scope_key, @@ -139,6 +150,7 @@ async def compare_and_set(self, session_id: str, session: AgentSession, *, expec new_etag = result.get("_etag") if not isinstance(new_etag, str) or not new_etag: raise RuntimeError("Cosmos did not return an ETag after saving.") + _validate_cosmos_etag(new_etag) return new_etag async def delete(self, session_id: str) -> None: @@ -148,6 +160,7 @@ async def delete(self, session_id: str) -> None: await self.get(session_id) etag = self._etags[session_id] if etag is not None: + _validate_cosmos_etag(etag) try: await self._container.delete_item( item=item_id, From 5d3641703c117c1e528761645b1fbd5d96fbcd84 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 10:21:51 +0100 Subject: [PATCH 18/55] Clarify workflow tool ownership guidance --- python/packages/foundry_hosting/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/python/packages/foundry_hosting/README.md b/python/packages/foundry_hosting/README.md index 1c2ccfc0094..ce4fe71d61d 100644 --- a/python/packages/foundry_hosting/README.md +++ b/python/packages/foundry_hosting/README.md @@ -686,8 +686,8 @@ validates the entire reply batch against its exact pending checkpoint. A sync/async `build_workflow(request)` factory returns a **built**, fresh `Workflow`, with stable name, executor IDs and graph identity. Build fresh executors, agents, -clients, providers and tools for each request; allocation must not execute tools or -workflow side effects. Both hosted and local workflows require a factory; built instances +clients, providers and mutable tools for each request. Allocation must not execute +tools or workflow side effects. Both hosted and local workflows require a factory; built instances are rejected at construction. Factory-owned agents are entered and closed per turn; applications must explicitly own external credentials/providers through their resource-managing agent subclasses. Do not configure another From 5a2bf847c6f041f2dc42a18b8c5dcc3038f1c07c Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 10:25:15 +0100 Subject: [PATCH 19/55] Validate provider background after hosted agent middleware --- .../_invocations_shared.py | 5 +- .../_shared.py | 75 ++++++++- .../foundry_hosting/background_helpers.py | 80 ++++++++++ .../test_background_middleware.py | 151 ++++++++++++++++++ .../foundry_hosting/test_workflow_state.py | 1 + .../foundry_hosting/workflow_tool_helpers.py | 6 +- 6 files changed, 308 insertions(+), 10 deletions(-) create mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/background_helpers.py create mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/test_background_middleware.py diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py index 2ada5429227..5483dad505a 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py @@ -58,6 +58,7 @@ WorkflowResolver, WorkflowSource, WorkflowTurn, + foreground_agent_run_kwargs, is_agent, reject_removed_host_settings, resolve_agent, @@ -649,7 +650,7 @@ async def stream_response() -> AsyncGenerator[str]: try: lock = self._session_locks.setdefault(partition_key, asyncio.Lock()) async with lock, self._request_agent(request) as agent: - run_kwargs = self._agent_kwargs(agent, options) + run_kwargs = {**self._agent_kwargs(agent, options), **foreground_agent_run_kwargs(agent)} async with self._request_session(partition_key, context, hosted_scope=hosted_scope) as session: stream = agent.run(parsed.messages, session=session, stream=True, **run_kwargs) completed = False @@ -708,7 +709,7 @@ async def stream_response() -> AsyncGenerator[str]: try: lock = self._session_locks.setdefault(partition_key, asyncio.Lock()) async with lock, self._request_agent(request) as agent: - run_kwargs = self._agent_kwargs(agent, options) + run_kwargs = {**self._agent_kwargs(agent, options), **foreground_agent_run_kwargs(agent)} async with self._request_session(partition_key, context, hosted_scope=hosted_scope) as session: response = await agent.run(parsed.messages, session=session, **run_kwargs) if self._legacy_wire_format: diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py index dbea4323e1b..51f6989e7f8 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py @@ -19,8 +19,12 @@ AgentContext, AgentExecutor, AgentMiddleware, + AgentMiddlewareLayer, AgentResponse, AgentRunInputs, + ChatContext, + ChatMiddleware, + ChatMiddlewareLayer, Content, FunctionTool, HistoryProvider, @@ -376,18 +380,71 @@ def validate_agent_background_options(agent: SupportsAgentRun, *, provider_backg defaults = getattr(agent, "default_options", {}) if not isinstance(defaults, Mapping): raise TypeError("Agent default_options must be a mapping.") - defaults = cast(Mapping[str, Any], defaults) - background = defaults.get("background") + validate_provider_background_options(cast(Mapping[str, Any], defaults), provider_background=provider_background) + + +def validate_provider_background_options(options: Mapping[str, Any], *, provider_background: bool) -> None: + """Validate visible provider-background options without changing the execution mode. + + Permit a boolean top-level default only when compatible with the selected + mode. Reject transport-body overrides even when false. This pure check does + not inspect client internals or produce protocol responses. + """ + background = options.get("background") if background is not None and not isinstance(background, bool): - raise TypeError("Agent default background must be a boolean.") + raise TypeError("Provider background must be a boolean.") if background is True and not provider_background: raise ValueError( - "Agent default background=True requires an outer background request with " + "Provider background=True requires an outer background request with " "history_source='inference_service' and background_source='inference_service'." ) - extra_body = defaults.get("extra_body") + extra_body = options.get("extra_body") if isinstance(extra_body, Mapping) and "background" in extra_body: - raise ValueError("Agent default extra_body cannot set host-controlled fields: background.") + raise ValueError("Provider extra_body cannot set host-controlled fields: background.") + + +class _ForegroundChatOptions(ChatMiddleware): + async def process(self, context: ChatContext, call_next: Callable[[], Awaitable[None]]) -> None: + validate_provider_background_options(context.options or {}, provider_background=False) + validate_provider_background_options(context.kwargs, provider_background=False) + await call_next() + + +_FOREGROUND_CHAT_OPTIONS = _ForegroundChatOptions() + + +def _append_foreground_chat_options(agent: SupportsAgentRun, client_kwargs: dict[str, Any]) -> None: + if not isinstance(agent, RawAgent) or not isinstance(cast(RawAgent[Any], agent).client, ChatMiddlewareLayer): + return + middleware = client_kwargs.get("middleware", ()) + if not isinstance(middleware, Sequence) or isinstance(middleware, (str, bytes)): + raise TypeError("Client middleware must be a sequence.") + client_kwargs["middleware"] = [*middleware, _FOREGROUND_CHAT_OPTIONS] + + +class _ForegroundAgentOptions(AgentMiddleware): + async def process(self, context: AgentContext, call_next: Callable[[], Awaitable[None]]) -> None: + validate_agent_background_options(context.agent, provider_background=False) + validate_provider_background_options(context.options or {}, provider_background=False) + validate_provider_background_options(context.client_kwargs, provider_background=False) + _append_foreground_chat_options(context.agent, context.client_kwargs) + await call_next() + + +_FOREGROUND_AGENT_OPTIONS = _ForegroundAgentOptions() + + +def foreground_agent_run_kwargs(agent: SupportsAgentRun) -> dict[str, Any]: + """Guard ordinary agent and chat middleware using request-local run arguments. + + Custom clients and context-provider-contributed chat middleware must not + enable provider background internally; they have no final hosting hook. + """ + if isinstance(agent, AgentMiddlewareLayer): + return {"middleware": [_FOREGROUND_AGENT_OPTIONS]} + kwargs: dict[str, Any] = {} + _append_foreground_chat_options(agent, kwargs) + return {"client_kwargs": kwargs} if kwargs else {} def validate_default_transport_options(defaults: Mapping[str, Any], *, allow_agent_store: bool) -> None: @@ -547,7 +604,7 @@ async def process(self, context: AgentContext, call_next: Callable[[], Awaitable effective = {**(context.options or {}), **options} if (_CLIENT_CONTROLS - {"store", "instructions", "tools", "extra_body"}).intersection(effective): raise ValueError("Native workflow model options cannot override hosting or transport controls.") - if (_CLIENT_CONTROLS - {"additional_function_arguments"}).intersection(context.client_kwargs): + if (_CLIENT_CONTROLS - {"additional_function_arguments", "middleware"}).intersection(context.client_kwargs): raise ValueError("Native workflow client kwargs cannot override hosting or transport controls.") validate_default_transport_options(effective, allow_agent_store=False) validate_agent_background_options(context.agent, provider_background=False) @@ -563,6 +620,7 @@ async def process(self, context: AgentContext, call_next: Callable[[], Awaitable "user_id": self.scope.user_id, "call_id": self.scope.call_id, } + _append_foreground_chat_options(context.agent, context.client_kwargs) def check_result(result: AgentResponse[Any]) -> None: if context.session is not None and context.session.service_session_id is not None: @@ -677,6 +735,9 @@ def validate_values(value: Any) -> dict[str, Any]: "RawAgent workflow generation overrides must be materialized in the fresh factory defaults." ) values.pop("options", None) + if isinstance(agent.client, ChatMiddlewareLayer): + # Run kwargs are checkpointed; install policy on the fresh factory-owned client instead. + agent.client.chat_middleware = [*(agent.client.chat_middleware or ()), _FOREGROUND_CHAT_OPTIONS] global_functions = validate_values(functions.get("global_kwargs", {})) specific_functions = { key: validate_values(value) for key, value in cast(dict[str, Any], functions.get("executor_kwargs", {})).items() diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/background_helpers.py b/python/packages/foundry_hosting/tests/foundry_hosting/background_helpers.py new file mode 100644 index 00000000000..193e859fe10 --- /dev/null +++ b/python/packages/foundry_hosting/tests/foundry_hosting/background_helpers.py @@ -0,0 +1,80 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Real agents and middleware for provider-background boundary tests.""" + +from __future__ import annotations + +from collections.abc import Awaitable, Callable +from typing import Any + +from agent_framework import ( + Agent, + AgentContext, + ChatContext, + ChatMiddlewareLayer, + ChatMiddlewareTypes, + RawAgent, + Workflow, + WorkflowBuilder, +) +from starlette.requests import Request + +from .options_helpers import OptionsClient + + +class LayeredOptionsClient(ChatMiddlewareLayer, OptionsClient): + pass + + +class BackgroundCallbacks: + def __init__( + self, + *, + source: str, + location: str, + injected: dict[str, Any], + raw: bool = False, + ) -> None: + self.client = LayeredOptionsClient() + self.source = source + self.location = location + self.injected = injected + middleware: list[ChatMiddlewareTypes] = [self.inject_chat] if source == "chat" else [] + self.client.chat_middleware = middleware + self.agent = ( + RawAgent(client=self.client) + if raw + else Agent(client=self.client, middleware=[self.inject_agent] if source == "agent" else None) + ) + + async def inject_agent(self, context: AgentContext, call_next: Callable[[], Awaitable[None]]) -> None: + if self.location == "options": + context.options = {**(context.options or {}), **self.injected} + else: + context.client_kwargs.update(self.injected) + await call_next() + + async def inject_chat(self, context: ChatContext, call_next: Callable[[], Awaitable[None]]) -> None: + if self.location == "options": + context.options = {**(context.options or {}), **self.injected} + else: + context.kwargs.update(self.injected) + await call_next() + + def factory(self, *, request: Request) -> Agent[Any] | RawAgent[Any]: + return self.agent + + def workflow(self, request: Request) -> Workflow: + return WorkflowBuilder(start_executor=self.agent).build() + + +class AgentChatCallbacks(BackgroundCallbacks): + def __init__(self) -> None: + super().__init__(source="none", location="options", injected={"background": True}) + self.agent = Agent(client=self.client, middleware=[self.inject_chat]) + + +class ReplacedMiddlewareCallbacks(BackgroundCallbacks): + async def inject_agent(self, context: AgentContext, call_next: Callable[[], Awaitable[None]]) -> None: + context.client_kwargs["middleware"] = (self.inject_chat,) + await call_next() diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_background_middleware.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_background_middleware.py new file mode 100644 index 00000000000..66229500b10 --- /dev/null +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_background_middleware.py @@ -0,0 +1,151 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Check provider-background options after ordinary agent and chat middleware.""" + +from __future__ import annotations + +from typing import Any + +import httpx +import pytest +from agent_framework import RawAgent + +from agent_framework_foundry_hosting import InvocationsHostServer, InvocationsWorkflowHostServer, WorkflowTurn +from agent_framework_foundry_hosting._shared import ( + foreground_agent_run_kwargs, + validate_provider_background_options, +) + +from .background_helpers import AgentChatCallbacks, BackgroundCallbacks, ReplacedMiddlewareCallbacks +from .options_helpers import OptionsClient + + +@pytest.mark.parametrize("provider_background", [False, True]) +@pytest.mark.parametrize("background", [None, False, True, 0, "true"]) +def test_pure_background_validator(provider_background: bool, background: Any) -> None: + options = {"background": background, "temperature": 0.4} + original = options.copy() + if background is not None and not isinstance(background, bool): + with pytest.raises(TypeError, match="boolean"): + validate_provider_background_options(options, provider_background=provider_background) + elif background is True and not provider_background: + with pytest.raises(ValueError, match="outer background"): + validate_provider_background_options(options, provider_background=provider_background) + else: + validate_provider_background_options(options, provider_background=provider_background) + assert options == original + + +@pytest.mark.parametrize("provider_background", [False, True]) +@pytest.mark.parametrize("background", [None, False, True]) +def test_pure_validator_rejects_all_nested_background(provider_background: bool, background: Any) -> None: + with pytest.raises(ValueError, match="host-controlled"): + validate_provider_background_options( + {"extra_body": {"background": background}}, provider_background=provider_background + ) + + +@pytest.mark.parametrize("workflow", [False, True]) +@pytest.mark.parametrize("stream", [False, True]) +@pytest.mark.parametrize("source", ["agent", "chat"]) +@pytest.mark.parametrize("location", ["options", "kwargs"]) +@pytest.mark.parametrize("injected", [{"background": True}, {"extra_body": {"background": True}}]) +async def test_middleware_background_is_rejected_before_provider( + workflow: bool, stream: bool, source: str, location: str, injected: dict[str, Any], caplog: pytest.LogCaptureFixture +) -> None: + callbacks = BackgroundCallbacks(source=source, location=location, injected=injected) + original_middleware = None if callbacks.agent.middleware is None else list(callbacks.agent.middleware) + original_defaults = callbacks.agent.default_options.copy() + host = ( + InvocationsWorkflowHostServer( + callbacks.workflow, parse_input=lambda request: WorkflowTurn(input="hi", stream=stream) + ) + if workflow + else InvocationsHostServer(callbacks.agent) + ) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: + response = await client.post( + "/invocations?agent_session_id=background", json={"message": "hi", "stream": stream} + ) + assert response.status_code == (200 if stream else 500) + assert "invocation failed" in response.text.lower() + assert "background" in caplog.text or "transport controls" in caplog.text + assert callbacks.client.calls == [] + assert callbacks.agent.default_options == original_defaults + if not workflow: + assert callbacks.agent.middleware == original_middleware + + +@pytest.mark.parametrize("workflow", [False, True]) +@pytest.mark.parametrize("stream", [False, True]) +async def test_raw_agent_client_middleware_background_is_rejected( + workflow: bool, stream: bool, caplog: pytest.LogCaptureFixture +) -> None: + callbacks = BackgroundCallbacks(source="chat", location="options", injected={"background": True}, raw=True) + host = ( + InvocationsWorkflowHostServer( + callbacks.workflow, parse_input=lambda request: WorkflowTurn(input="hi", stream=stream) + ) + if workflow + else InvocationsHostServer(callbacks.agent) + ) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: + response = await client.post( + "/invocations?agent_session_id=raw-background", json={"message": "hi", "stream": stream} + ) + assert response.status_code == (200 if stream else 500) + assert "background" in caplog.text + assert callbacks.client.calls == [] + + +@pytest.mark.parametrize("workflow", [False, True]) +@pytest.mark.parametrize("stream", [False, True]) +@pytest.mark.parametrize("callbacks_type", [AgentChatCallbacks, ReplacedMiddlewareCallbacks]) +async def test_run_guard_survives_agent_chat_middleware_and_replaced_client_middleware( + workflow: bool, stream: bool, callbacks_type: type[BackgroundCallbacks] +) -> None: + callbacks = ( + AgentChatCallbacks() + if callbacks_type is AgentChatCallbacks + else callbacks_type(source="agent", location="options", injected={"background": True}) + ) + host = ( + InvocationsWorkflowHostServer( + callbacks.workflow, parse_input=lambda request: WorkflowTurn(input="hi", stream=stream) + ) + if workflow + else InvocationsHostServer(callbacks.agent) + ) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: + response = await client.post( + "/invocations?agent_session_id=background", json={"message": "hi", "stream": stream} + ) + assert "invocation failed" in response.text.lower() + assert callbacks.client.calls == [] + + +@pytest.mark.parametrize("workflow", [False, True]) +@pytest.mark.parametrize("raw", [False, True]) +@pytest.mark.parametrize("stream", [False, True]) +async def test_supported_middleware_preserves_foreground_generation(workflow: bool, raw: bool, stream: bool) -> None: + callbacks = BackgroundCallbacks(source="chat", location="options", injected={"temperature": 0.2}, raw=raw) + host = ( + InvocationsWorkflowHostServer( + callbacks.workflow, parse_input=lambda request: WorkflowTurn(input="hi", stream=stream) + ) + if workflow + else InvocationsHostServer(callbacks.agent) + ) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: + response = await client.post( + "/invocations?agent_session_id=foreground", json={"message": "hi", "stream": stream} + ) + assert response.status_code == 200 + assert "ok" in response.text + assert callbacks.client.calls[0]["temperature"] == 0.2 + if not (workflow and raw): + assert callbacks.client.chat_middleware == [callbacks.inject_chat] + + +def test_unlayered_client_receives_no_middleware_kwarg() -> None: + assert foreground_agent_run_kwargs(RawAgent(client=OptionsClient())) == {} diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py index af04a6c5126..34f63833543 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py @@ -279,6 +279,7 @@ async def test_resolver_allows_reused_stateless_function_tools(shared: Any) -> N for workflow in (first, second): executor = workflow.get_start_executor() assert isinstance(executor, AgentExecutor) + assert isinstance(executor.agent, RawAgent) assert executor.agent.default_options["tools"][0] is shared diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/workflow_tool_helpers.py b/python/packages/foundry_hosting/tests/foundry_hosting/workflow_tool_helpers.py index 2866bc010a4..9de39007638 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/workflow_tool_helpers.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/workflow_tool_helpers.py @@ -58,7 +58,11 @@ def capture(value: str) -> str: return CustomFunctionTool(name="custom", func=shared_function.func) if kind == "parser": return FunctionTool(name="parser", func=shared_function.func, result_parser=MutableToolOwner().count) - return FunctionTool(name="limited", func=shared_function.func, **{kind: 1}) + if kind == "max_invocations": + return FunctionTool(name="limited", func=shared_function.func, max_invocations=1) + if kind == "max_invocation_exceptions": + return FunctionTool(name="limited", func=shared_function.func, max_invocation_exceptions=1) + raise ValueError(f"Unknown mutable tool kind: {kind}") def workflow_with_tools(tools: list[Any], *, client: BaseChatClient | None = None) -> Workflow: From dd9c10e7080d624024336263a515d1cbd1a8d5d5 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 10:26:29 +0100 Subject: [PATCH 20/55] Withdraw unagreed provider-background middleware guard Reverts 5a2bf847c6f041f2dc42a18b8c5dcc3038f1c07c. The interface was not agreed with E before implementation. The original commit stays available as a reference proposal. --- .../_invocations_shared.py | 5 +- .../_shared.py | 75 +-------- .../foundry_hosting/background_helpers.py | 80 ---------- .../test_background_middleware.py | 151 ------------------ .../foundry_hosting/test_workflow_state.py | 1 - .../foundry_hosting/workflow_tool_helpers.py | 6 +- 6 files changed, 10 insertions(+), 308 deletions(-) delete mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/background_helpers.py delete mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/test_background_middleware.py diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py index 5483dad505a..2ada5429227 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py @@ -58,7 +58,6 @@ WorkflowResolver, WorkflowSource, WorkflowTurn, - foreground_agent_run_kwargs, is_agent, reject_removed_host_settings, resolve_agent, @@ -650,7 +649,7 @@ async def stream_response() -> AsyncGenerator[str]: try: lock = self._session_locks.setdefault(partition_key, asyncio.Lock()) async with lock, self._request_agent(request) as agent: - run_kwargs = {**self._agent_kwargs(agent, options), **foreground_agent_run_kwargs(agent)} + run_kwargs = self._agent_kwargs(agent, options) async with self._request_session(partition_key, context, hosted_scope=hosted_scope) as session: stream = agent.run(parsed.messages, session=session, stream=True, **run_kwargs) completed = False @@ -709,7 +708,7 @@ async def stream_response() -> AsyncGenerator[str]: try: lock = self._session_locks.setdefault(partition_key, asyncio.Lock()) async with lock, self._request_agent(request) as agent: - run_kwargs = {**self._agent_kwargs(agent, options), **foreground_agent_run_kwargs(agent)} + run_kwargs = self._agent_kwargs(agent, options) async with self._request_session(partition_key, context, hosted_scope=hosted_scope) as session: response = await agent.run(parsed.messages, session=session, **run_kwargs) if self._legacy_wire_format: diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py index 51f6989e7f8..dbea4323e1b 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py @@ -19,12 +19,8 @@ AgentContext, AgentExecutor, AgentMiddleware, - AgentMiddlewareLayer, AgentResponse, AgentRunInputs, - ChatContext, - ChatMiddleware, - ChatMiddlewareLayer, Content, FunctionTool, HistoryProvider, @@ -380,71 +376,18 @@ def validate_agent_background_options(agent: SupportsAgentRun, *, provider_backg defaults = getattr(agent, "default_options", {}) if not isinstance(defaults, Mapping): raise TypeError("Agent default_options must be a mapping.") - validate_provider_background_options(cast(Mapping[str, Any], defaults), provider_background=provider_background) - - -def validate_provider_background_options(options: Mapping[str, Any], *, provider_background: bool) -> None: - """Validate visible provider-background options without changing the execution mode. - - Permit a boolean top-level default only when compatible with the selected - mode. Reject transport-body overrides even when false. This pure check does - not inspect client internals or produce protocol responses. - """ - background = options.get("background") + defaults = cast(Mapping[str, Any], defaults) + background = defaults.get("background") if background is not None and not isinstance(background, bool): - raise TypeError("Provider background must be a boolean.") + raise TypeError("Agent default background must be a boolean.") if background is True and not provider_background: raise ValueError( - "Provider background=True requires an outer background request with " + "Agent default background=True requires an outer background request with " "history_source='inference_service' and background_source='inference_service'." ) - extra_body = options.get("extra_body") + extra_body = defaults.get("extra_body") if isinstance(extra_body, Mapping) and "background" in extra_body: - raise ValueError("Provider extra_body cannot set host-controlled fields: background.") - - -class _ForegroundChatOptions(ChatMiddleware): - async def process(self, context: ChatContext, call_next: Callable[[], Awaitable[None]]) -> None: - validate_provider_background_options(context.options or {}, provider_background=False) - validate_provider_background_options(context.kwargs, provider_background=False) - await call_next() - - -_FOREGROUND_CHAT_OPTIONS = _ForegroundChatOptions() - - -def _append_foreground_chat_options(agent: SupportsAgentRun, client_kwargs: dict[str, Any]) -> None: - if not isinstance(agent, RawAgent) or not isinstance(cast(RawAgent[Any], agent).client, ChatMiddlewareLayer): - return - middleware = client_kwargs.get("middleware", ()) - if not isinstance(middleware, Sequence) or isinstance(middleware, (str, bytes)): - raise TypeError("Client middleware must be a sequence.") - client_kwargs["middleware"] = [*middleware, _FOREGROUND_CHAT_OPTIONS] - - -class _ForegroundAgentOptions(AgentMiddleware): - async def process(self, context: AgentContext, call_next: Callable[[], Awaitable[None]]) -> None: - validate_agent_background_options(context.agent, provider_background=False) - validate_provider_background_options(context.options or {}, provider_background=False) - validate_provider_background_options(context.client_kwargs, provider_background=False) - _append_foreground_chat_options(context.agent, context.client_kwargs) - await call_next() - - -_FOREGROUND_AGENT_OPTIONS = _ForegroundAgentOptions() - - -def foreground_agent_run_kwargs(agent: SupportsAgentRun) -> dict[str, Any]: - """Guard ordinary agent and chat middleware using request-local run arguments. - - Custom clients and context-provider-contributed chat middleware must not - enable provider background internally; they have no final hosting hook. - """ - if isinstance(agent, AgentMiddlewareLayer): - return {"middleware": [_FOREGROUND_AGENT_OPTIONS]} - kwargs: dict[str, Any] = {} - _append_foreground_chat_options(agent, kwargs) - return {"client_kwargs": kwargs} if kwargs else {} + raise ValueError("Agent default extra_body cannot set host-controlled fields: background.") def validate_default_transport_options(defaults: Mapping[str, Any], *, allow_agent_store: bool) -> None: @@ -604,7 +547,7 @@ async def process(self, context: AgentContext, call_next: Callable[[], Awaitable effective = {**(context.options or {}), **options} if (_CLIENT_CONTROLS - {"store", "instructions", "tools", "extra_body"}).intersection(effective): raise ValueError("Native workflow model options cannot override hosting or transport controls.") - if (_CLIENT_CONTROLS - {"additional_function_arguments", "middleware"}).intersection(context.client_kwargs): + if (_CLIENT_CONTROLS - {"additional_function_arguments"}).intersection(context.client_kwargs): raise ValueError("Native workflow client kwargs cannot override hosting or transport controls.") validate_default_transport_options(effective, allow_agent_store=False) validate_agent_background_options(context.agent, provider_background=False) @@ -620,7 +563,6 @@ async def process(self, context: AgentContext, call_next: Callable[[], Awaitable "user_id": self.scope.user_id, "call_id": self.scope.call_id, } - _append_foreground_chat_options(context.agent, context.client_kwargs) def check_result(result: AgentResponse[Any]) -> None: if context.session is not None and context.session.service_session_id is not None: @@ -735,9 +677,6 @@ def validate_values(value: Any) -> dict[str, Any]: "RawAgent workflow generation overrides must be materialized in the fresh factory defaults." ) values.pop("options", None) - if isinstance(agent.client, ChatMiddlewareLayer): - # Run kwargs are checkpointed; install policy on the fresh factory-owned client instead. - agent.client.chat_middleware = [*(agent.client.chat_middleware or ()), _FOREGROUND_CHAT_OPTIONS] global_functions = validate_values(functions.get("global_kwargs", {})) specific_functions = { key: validate_values(value) for key, value in cast(dict[str, Any], functions.get("executor_kwargs", {})).items() diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/background_helpers.py b/python/packages/foundry_hosting/tests/foundry_hosting/background_helpers.py deleted file mode 100644 index 193e859fe10..00000000000 --- a/python/packages/foundry_hosting/tests/foundry_hosting/background_helpers.py +++ /dev/null @@ -1,80 +0,0 @@ -# Copyright (c) Microsoft. All rights reserved. - -"""Real agents and middleware for provider-background boundary tests.""" - -from __future__ import annotations - -from collections.abc import Awaitable, Callable -from typing import Any - -from agent_framework import ( - Agent, - AgentContext, - ChatContext, - ChatMiddlewareLayer, - ChatMiddlewareTypes, - RawAgent, - Workflow, - WorkflowBuilder, -) -from starlette.requests import Request - -from .options_helpers import OptionsClient - - -class LayeredOptionsClient(ChatMiddlewareLayer, OptionsClient): - pass - - -class BackgroundCallbacks: - def __init__( - self, - *, - source: str, - location: str, - injected: dict[str, Any], - raw: bool = False, - ) -> None: - self.client = LayeredOptionsClient() - self.source = source - self.location = location - self.injected = injected - middleware: list[ChatMiddlewareTypes] = [self.inject_chat] if source == "chat" else [] - self.client.chat_middleware = middleware - self.agent = ( - RawAgent(client=self.client) - if raw - else Agent(client=self.client, middleware=[self.inject_agent] if source == "agent" else None) - ) - - async def inject_agent(self, context: AgentContext, call_next: Callable[[], Awaitable[None]]) -> None: - if self.location == "options": - context.options = {**(context.options or {}), **self.injected} - else: - context.client_kwargs.update(self.injected) - await call_next() - - async def inject_chat(self, context: ChatContext, call_next: Callable[[], Awaitable[None]]) -> None: - if self.location == "options": - context.options = {**(context.options or {}), **self.injected} - else: - context.kwargs.update(self.injected) - await call_next() - - def factory(self, *, request: Request) -> Agent[Any] | RawAgent[Any]: - return self.agent - - def workflow(self, request: Request) -> Workflow: - return WorkflowBuilder(start_executor=self.agent).build() - - -class AgentChatCallbacks(BackgroundCallbacks): - def __init__(self) -> None: - super().__init__(source="none", location="options", injected={"background": True}) - self.agent = Agent(client=self.client, middleware=[self.inject_chat]) - - -class ReplacedMiddlewareCallbacks(BackgroundCallbacks): - async def inject_agent(self, context: AgentContext, call_next: Callable[[], Awaitable[None]]) -> None: - context.client_kwargs["middleware"] = (self.inject_chat,) - await call_next() diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_background_middleware.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_background_middleware.py deleted file mode 100644 index 66229500b10..00000000000 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_background_middleware.py +++ /dev/null @@ -1,151 +0,0 @@ -# Copyright (c) Microsoft. All rights reserved. - -"""Check provider-background options after ordinary agent and chat middleware.""" - -from __future__ import annotations - -from typing import Any - -import httpx -import pytest -from agent_framework import RawAgent - -from agent_framework_foundry_hosting import InvocationsHostServer, InvocationsWorkflowHostServer, WorkflowTurn -from agent_framework_foundry_hosting._shared import ( - foreground_agent_run_kwargs, - validate_provider_background_options, -) - -from .background_helpers import AgentChatCallbacks, BackgroundCallbacks, ReplacedMiddlewareCallbacks -from .options_helpers import OptionsClient - - -@pytest.mark.parametrize("provider_background", [False, True]) -@pytest.mark.parametrize("background", [None, False, True, 0, "true"]) -def test_pure_background_validator(provider_background: bool, background: Any) -> None: - options = {"background": background, "temperature": 0.4} - original = options.copy() - if background is not None and not isinstance(background, bool): - with pytest.raises(TypeError, match="boolean"): - validate_provider_background_options(options, provider_background=provider_background) - elif background is True and not provider_background: - with pytest.raises(ValueError, match="outer background"): - validate_provider_background_options(options, provider_background=provider_background) - else: - validate_provider_background_options(options, provider_background=provider_background) - assert options == original - - -@pytest.mark.parametrize("provider_background", [False, True]) -@pytest.mark.parametrize("background", [None, False, True]) -def test_pure_validator_rejects_all_nested_background(provider_background: bool, background: Any) -> None: - with pytest.raises(ValueError, match="host-controlled"): - validate_provider_background_options( - {"extra_body": {"background": background}}, provider_background=provider_background - ) - - -@pytest.mark.parametrize("workflow", [False, True]) -@pytest.mark.parametrize("stream", [False, True]) -@pytest.mark.parametrize("source", ["agent", "chat"]) -@pytest.mark.parametrize("location", ["options", "kwargs"]) -@pytest.mark.parametrize("injected", [{"background": True}, {"extra_body": {"background": True}}]) -async def test_middleware_background_is_rejected_before_provider( - workflow: bool, stream: bool, source: str, location: str, injected: dict[str, Any], caplog: pytest.LogCaptureFixture -) -> None: - callbacks = BackgroundCallbacks(source=source, location=location, injected=injected) - original_middleware = None if callbacks.agent.middleware is None else list(callbacks.agent.middleware) - original_defaults = callbacks.agent.default_options.copy() - host = ( - InvocationsWorkflowHostServer( - callbacks.workflow, parse_input=lambda request: WorkflowTurn(input="hi", stream=stream) - ) - if workflow - else InvocationsHostServer(callbacks.agent) - ) - async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: - response = await client.post( - "/invocations?agent_session_id=background", json={"message": "hi", "stream": stream} - ) - assert response.status_code == (200 if stream else 500) - assert "invocation failed" in response.text.lower() - assert "background" in caplog.text or "transport controls" in caplog.text - assert callbacks.client.calls == [] - assert callbacks.agent.default_options == original_defaults - if not workflow: - assert callbacks.agent.middleware == original_middleware - - -@pytest.mark.parametrize("workflow", [False, True]) -@pytest.mark.parametrize("stream", [False, True]) -async def test_raw_agent_client_middleware_background_is_rejected( - workflow: bool, stream: bool, caplog: pytest.LogCaptureFixture -) -> None: - callbacks = BackgroundCallbacks(source="chat", location="options", injected={"background": True}, raw=True) - host = ( - InvocationsWorkflowHostServer( - callbacks.workflow, parse_input=lambda request: WorkflowTurn(input="hi", stream=stream) - ) - if workflow - else InvocationsHostServer(callbacks.agent) - ) - async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: - response = await client.post( - "/invocations?agent_session_id=raw-background", json={"message": "hi", "stream": stream} - ) - assert response.status_code == (200 if stream else 500) - assert "background" in caplog.text - assert callbacks.client.calls == [] - - -@pytest.mark.parametrize("workflow", [False, True]) -@pytest.mark.parametrize("stream", [False, True]) -@pytest.mark.parametrize("callbacks_type", [AgentChatCallbacks, ReplacedMiddlewareCallbacks]) -async def test_run_guard_survives_agent_chat_middleware_and_replaced_client_middleware( - workflow: bool, stream: bool, callbacks_type: type[BackgroundCallbacks] -) -> None: - callbacks = ( - AgentChatCallbacks() - if callbacks_type is AgentChatCallbacks - else callbacks_type(source="agent", location="options", injected={"background": True}) - ) - host = ( - InvocationsWorkflowHostServer( - callbacks.workflow, parse_input=lambda request: WorkflowTurn(input="hi", stream=stream) - ) - if workflow - else InvocationsHostServer(callbacks.agent) - ) - async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: - response = await client.post( - "/invocations?agent_session_id=background", json={"message": "hi", "stream": stream} - ) - assert "invocation failed" in response.text.lower() - assert callbacks.client.calls == [] - - -@pytest.mark.parametrize("workflow", [False, True]) -@pytest.mark.parametrize("raw", [False, True]) -@pytest.mark.parametrize("stream", [False, True]) -async def test_supported_middleware_preserves_foreground_generation(workflow: bool, raw: bool, stream: bool) -> None: - callbacks = BackgroundCallbacks(source="chat", location="options", injected={"temperature": 0.2}, raw=raw) - host = ( - InvocationsWorkflowHostServer( - callbacks.workflow, parse_input=lambda request: WorkflowTurn(input="hi", stream=stream) - ) - if workflow - else InvocationsHostServer(callbacks.agent) - ) - async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: - response = await client.post( - "/invocations?agent_session_id=foreground", json={"message": "hi", "stream": stream} - ) - assert response.status_code == 200 - assert "ok" in response.text - assert callbacks.client.calls[0]["temperature"] == 0.2 - if not (workflow and raw): - assert callbacks.client.chat_middleware == [callbacks.inject_chat] - - -def test_unlayered_client_receives_no_middleware_kwarg() -> None: - assert foreground_agent_run_kwargs(RawAgent(client=OptionsClient())) == {} diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py index 34f63833543..af04a6c5126 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py @@ -279,7 +279,6 @@ async def test_resolver_allows_reused_stateless_function_tools(shared: Any) -> N for workflow in (first, second): executor = workflow.get_start_executor() assert isinstance(executor, AgentExecutor) - assert isinstance(executor.agent, RawAgent) assert executor.agent.default_options["tools"][0] is shared diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/workflow_tool_helpers.py b/python/packages/foundry_hosting/tests/foundry_hosting/workflow_tool_helpers.py index 9de39007638..2866bc010a4 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/workflow_tool_helpers.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/workflow_tool_helpers.py @@ -58,11 +58,7 @@ def capture(value: str) -> str: return CustomFunctionTool(name="custom", func=shared_function.func) if kind == "parser": return FunctionTool(name="parser", func=shared_function.func, result_parser=MutableToolOwner().count) - if kind == "max_invocations": - return FunctionTool(name="limited", func=shared_function.func, max_invocations=1) - if kind == "max_invocation_exceptions": - return FunctionTool(name="limited", func=shared_function.func, max_invocation_exceptions=1) - raise ValueError(f"Unknown mutable tool kind: {kind}") + return FunctionTool(name="limited", func=shared_function.func, **{kind: 1}) def workflow_with_tools(tools: list[Any], *, client: BaseChatClient | None = None) -> Workflow: From 02f1f990721e1fced58b040f540eff8370f13bc3 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 10:28:02 +0100 Subject: [PATCH 21/55] Clarify scope of custom Cosmos storage prerequisite --- python/packages/foundry_hosting/README.md | 3 ++- .../foundry-hosted-agents/responses/custom_storage/README.md | 5 ++++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/python/packages/foundry_hosting/README.md b/python/packages/foundry_hosting/README.md index ce4fe71d61d..ef52f8bee57 100644 --- a/python/packages/foundry_hosting/README.md +++ b/python/packages/foundry_hosting/README.md @@ -533,7 +533,8 @@ writes for concurrent turns, including the pre-dispatch claim. Local callers can first loading a session. See the [custom storage provider sample](../../samples/04-hosting/foundry-hosted-agents/responses/custom_storage/) -for an example that uses an in-memory session store locally and Azure Cosmos DB when hosted. +for an example that uses an in-memory session store locally and a user-managed Azure Cosmos DB account when hosted. +Its Cosmos prerequisites apply to that custom provider, not to the default Foundry-managed store. Native Responses refusal parts are stored as text carrying `additional_properties["model_output_kind"] == "refusal"` and emitted as diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md index c0ff6a9b898..556180712c1 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md @@ -119,11 +119,14 @@ COSMOS_DATABASE_NAME= COSMOS_CONTAINER_NAME= ``` -For approval state, the Cosmos account **must use one write region**. +For approval state, the user-managed Cosmos account configured for this sample +**must use one write region**. Multi-write-region accounts can accept conditional updates independently in different regions before resolving conflicts. This sample does not provide a single global approval claim in that configuration. See [Cosmos optimistic concurrency and global distribution](https://learn.microsoft.com/en-us/azure/cosmos-db/database-transactions-optimistic-concurrency#optimistic-concurrency-control-and-global-distribution). +This prerequisite applies to the sample's custom provider, not to the +Foundry-managed state store. The hosted provider uses `azure.identity.aio.ManagedIdentityCredential`, with the platform-provided `FOUNDRY_AGENT_INSTANCE_CLIENT_ID` when present. Grant that From 3cc4905f7f0afe0c32bbb93c3b9b10ca33d19987 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 10:31:33 +0100 Subject: [PATCH 22/55] Restore agreed background guard and test RawAgent middleware Restore the previously integrated guard after an incorrect local revert. Add coverage for RawAgent background overrides and rejection of run-level workflow middleware. --- .../_invocations_shared.py | 5 +- .../_shared.py | 75 +++++++- .../foundry_hosting/background_helpers.py | 80 ++++++++ .../test_background_middleware.py | 173 ++++++++++++++++++ .../foundry_hosting/test_workflow_state.py | 1 + .../foundry_hosting/workflow_tool_helpers.py | 6 +- 6 files changed, 330 insertions(+), 10 deletions(-) create mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/background_helpers.py create mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/test_background_middleware.py diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py index 2ada5429227..5483dad505a 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py @@ -58,6 +58,7 @@ WorkflowResolver, WorkflowSource, WorkflowTurn, + foreground_agent_run_kwargs, is_agent, reject_removed_host_settings, resolve_agent, @@ -649,7 +650,7 @@ async def stream_response() -> AsyncGenerator[str]: try: lock = self._session_locks.setdefault(partition_key, asyncio.Lock()) async with lock, self._request_agent(request) as agent: - run_kwargs = self._agent_kwargs(agent, options) + run_kwargs = {**self._agent_kwargs(agent, options), **foreground_agent_run_kwargs(agent)} async with self._request_session(partition_key, context, hosted_scope=hosted_scope) as session: stream = agent.run(parsed.messages, session=session, stream=True, **run_kwargs) completed = False @@ -708,7 +709,7 @@ async def stream_response() -> AsyncGenerator[str]: try: lock = self._session_locks.setdefault(partition_key, asyncio.Lock()) async with lock, self._request_agent(request) as agent: - run_kwargs = self._agent_kwargs(agent, options) + run_kwargs = {**self._agent_kwargs(agent, options), **foreground_agent_run_kwargs(agent)} async with self._request_session(partition_key, context, hosted_scope=hosted_scope) as session: response = await agent.run(parsed.messages, session=session, **run_kwargs) if self._legacy_wire_format: diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py index dbea4323e1b..51f6989e7f8 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py @@ -19,8 +19,12 @@ AgentContext, AgentExecutor, AgentMiddleware, + AgentMiddlewareLayer, AgentResponse, AgentRunInputs, + ChatContext, + ChatMiddleware, + ChatMiddlewareLayer, Content, FunctionTool, HistoryProvider, @@ -376,18 +380,71 @@ def validate_agent_background_options(agent: SupportsAgentRun, *, provider_backg defaults = getattr(agent, "default_options", {}) if not isinstance(defaults, Mapping): raise TypeError("Agent default_options must be a mapping.") - defaults = cast(Mapping[str, Any], defaults) - background = defaults.get("background") + validate_provider_background_options(cast(Mapping[str, Any], defaults), provider_background=provider_background) + + +def validate_provider_background_options(options: Mapping[str, Any], *, provider_background: bool) -> None: + """Validate visible provider-background options without changing the execution mode. + + Permit a boolean top-level default only when compatible with the selected + mode. Reject transport-body overrides even when false. This pure check does + not inspect client internals or produce protocol responses. + """ + background = options.get("background") if background is not None and not isinstance(background, bool): - raise TypeError("Agent default background must be a boolean.") + raise TypeError("Provider background must be a boolean.") if background is True and not provider_background: raise ValueError( - "Agent default background=True requires an outer background request with " + "Provider background=True requires an outer background request with " "history_source='inference_service' and background_source='inference_service'." ) - extra_body = defaults.get("extra_body") + extra_body = options.get("extra_body") if isinstance(extra_body, Mapping) and "background" in extra_body: - raise ValueError("Agent default extra_body cannot set host-controlled fields: background.") + raise ValueError("Provider extra_body cannot set host-controlled fields: background.") + + +class _ForegroundChatOptions(ChatMiddleware): + async def process(self, context: ChatContext, call_next: Callable[[], Awaitable[None]]) -> None: + validate_provider_background_options(context.options or {}, provider_background=False) + validate_provider_background_options(context.kwargs, provider_background=False) + await call_next() + + +_FOREGROUND_CHAT_OPTIONS = _ForegroundChatOptions() + + +def _append_foreground_chat_options(agent: SupportsAgentRun, client_kwargs: dict[str, Any]) -> None: + if not isinstance(agent, RawAgent) or not isinstance(cast(RawAgent[Any], agent).client, ChatMiddlewareLayer): + return + middleware = client_kwargs.get("middleware", ()) + if not isinstance(middleware, Sequence) or isinstance(middleware, (str, bytes)): + raise TypeError("Client middleware must be a sequence.") + client_kwargs["middleware"] = [*middleware, _FOREGROUND_CHAT_OPTIONS] + + +class _ForegroundAgentOptions(AgentMiddleware): + async def process(self, context: AgentContext, call_next: Callable[[], Awaitable[None]]) -> None: + validate_agent_background_options(context.agent, provider_background=False) + validate_provider_background_options(context.options or {}, provider_background=False) + validate_provider_background_options(context.client_kwargs, provider_background=False) + _append_foreground_chat_options(context.agent, context.client_kwargs) + await call_next() + + +_FOREGROUND_AGENT_OPTIONS = _ForegroundAgentOptions() + + +def foreground_agent_run_kwargs(agent: SupportsAgentRun) -> dict[str, Any]: + """Guard ordinary agent and chat middleware using request-local run arguments. + + Custom clients and context-provider-contributed chat middleware must not + enable provider background internally; they have no final hosting hook. + """ + if isinstance(agent, AgentMiddlewareLayer): + return {"middleware": [_FOREGROUND_AGENT_OPTIONS]} + kwargs: dict[str, Any] = {} + _append_foreground_chat_options(agent, kwargs) + return {"client_kwargs": kwargs} if kwargs else {} def validate_default_transport_options(defaults: Mapping[str, Any], *, allow_agent_store: bool) -> None: @@ -547,7 +604,7 @@ async def process(self, context: AgentContext, call_next: Callable[[], Awaitable effective = {**(context.options or {}), **options} if (_CLIENT_CONTROLS - {"store", "instructions", "tools", "extra_body"}).intersection(effective): raise ValueError("Native workflow model options cannot override hosting or transport controls.") - if (_CLIENT_CONTROLS - {"additional_function_arguments"}).intersection(context.client_kwargs): + if (_CLIENT_CONTROLS - {"additional_function_arguments", "middleware"}).intersection(context.client_kwargs): raise ValueError("Native workflow client kwargs cannot override hosting or transport controls.") validate_default_transport_options(effective, allow_agent_store=False) validate_agent_background_options(context.agent, provider_background=False) @@ -563,6 +620,7 @@ async def process(self, context: AgentContext, call_next: Callable[[], Awaitable "user_id": self.scope.user_id, "call_id": self.scope.call_id, } + _append_foreground_chat_options(context.agent, context.client_kwargs) def check_result(result: AgentResponse[Any]) -> None: if context.session is not None and context.session.service_session_id is not None: @@ -677,6 +735,9 @@ def validate_values(value: Any) -> dict[str, Any]: "RawAgent workflow generation overrides must be materialized in the fresh factory defaults." ) values.pop("options", None) + if isinstance(agent.client, ChatMiddlewareLayer): + # Run kwargs are checkpointed; install policy on the fresh factory-owned client instead. + agent.client.chat_middleware = [*(agent.client.chat_middleware or ()), _FOREGROUND_CHAT_OPTIONS] global_functions = validate_values(functions.get("global_kwargs", {})) specific_functions = { key: validate_values(value) for key, value in cast(dict[str, Any], functions.get("executor_kwargs", {})).items() diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/background_helpers.py b/python/packages/foundry_hosting/tests/foundry_hosting/background_helpers.py new file mode 100644 index 00000000000..193e859fe10 --- /dev/null +++ b/python/packages/foundry_hosting/tests/foundry_hosting/background_helpers.py @@ -0,0 +1,80 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Real agents and middleware for provider-background boundary tests.""" + +from __future__ import annotations + +from collections.abc import Awaitable, Callable +from typing import Any + +from agent_framework import ( + Agent, + AgentContext, + ChatContext, + ChatMiddlewareLayer, + ChatMiddlewareTypes, + RawAgent, + Workflow, + WorkflowBuilder, +) +from starlette.requests import Request + +from .options_helpers import OptionsClient + + +class LayeredOptionsClient(ChatMiddlewareLayer, OptionsClient): + pass + + +class BackgroundCallbacks: + def __init__( + self, + *, + source: str, + location: str, + injected: dict[str, Any], + raw: bool = False, + ) -> None: + self.client = LayeredOptionsClient() + self.source = source + self.location = location + self.injected = injected + middleware: list[ChatMiddlewareTypes] = [self.inject_chat] if source == "chat" else [] + self.client.chat_middleware = middleware + self.agent = ( + RawAgent(client=self.client) + if raw + else Agent(client=self.client, middleware=[self.inject_agent] if source == "agent" else None) + ) + + async def inject_agent(self, context: AgentContext, call_next: Callable[[], Awaitable[None]]) -> None: + if self.location == "options": + context.options = {**(context.options or {}), **self.injected} + else: + context.client_kwargs.update(self.injected) + await call_next() + + async def inject_chat(self, context: ChatContext, call_next: Callable[[], Awaitable[None]]) -> None: + if self.location == "options": + context.options = {**(context.options or {}), **self.injected} + else: + context.kwargs.update(self.injected) + await call_next() + + def factory(self, *, request: Request) -> Agent[Any] | RawAgent[Any]: + return self.agent + + def workflow(self, request: Request) -> Workflow: + return WorkflowBuilder(start_executor=self.agent).build() + + +class AgentChatCallbacks(BackgroundCallbacks): + def __init__(self) -> None: + super().__init__(source="none", location="options", injected={"background": True}) + self.agent = Agent(client=self.client, middleware=[self.inject_chat]) + + +class ReplacedMiddlewareCallbacks(BackgroundCallbacks): + async def inject_agent(self, context: AgentContext, call_next: Callable[[], Awaitable[None]]) -> None: + context.client_kwargs["middleware"] = (self.inject_chat,) + await call_next() diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_background_middleware.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_background_middleware.py new file mode 100644 index 00000000000..8b16cbd4287 --- /dev/null +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_background_middleware.py @@ -0,0 +1,173 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Check provider-background options after ordinary agent and chat middleware.""" + +from __future__ import annotations + +from typing import Any + +import httpx +import pytest +from agent_framework import RawAgent + +from agent_framework_foundry_hosting import InvocationsHostServer, InvocationsWorkflowHostServer, WorkflowTurn +from agent_framework_foundry_hosting._shared import ( + foreground_agent_run_kwargs, + validate_provider_background_options, +) + +from .background_helpers import AgentChatCallbacks, BackgroundCallbacks, ReplacedMiddlewareCallbacks +from .options_helpers import OptionsClient + + +@pytest.mark.parametrize("provider_background", [False, True]) +@pytest.mark.parametrize("background", [None, False, True, 0, "true"]) +def test_pure_background_validator(provider_background: bool, background: Any) -> None: + options = {"background": background, "temperature": 0.4} + original = options.copy() + if background is not None and not isinstance(background, bool): + with pytest.raises(TypeError, match="boolean"): + validate_provider_background_options(options, provider_background=provider_background) + elif background is True and not provider_background: + with pytest.raises(ValueError, match="outer background"): + validate_provider_background_options(options, provider_background=provider_background) + else: + validate_provider_background_options(options, provider_background=provider_background) + assert options == original + + +@pytest.mark.parametrize("provider_background", [False, True]) +@pytest.mark.parametrize("background", [None, False, True]) +def test_pure_validator_rejects_all_nested_background(provider_background: bool, background: Any) -> None: + with pytest.raises(ValueError, match="host-controlled"): + validate_provider_background_options( + {"extra_body": {"background": background}}, provider_background=provider_background + ) + + +@pytest.mark.parametrize("workflow", [False, True]) +@pytest.mark.parametrize("stream", [False, True]) +@pytest.mark.parametrize("source", ["agent", "chat"]) +@pytest.mark.parametrize("location", ["options", "kwargs"]) +@pytest.mark.parametrize("injected", [{"background": True}, {"extra_body": {"background": True}}]) +async def test_middleware_background_is_rejected_before_provider( + workflow: bool, stream: bool, source: str, location: str, injected: dict[str, Any], caplog: pytest.LogCaptureFixture +) -> None: + callbacks = BackgroundCallbacks(source=source, location=location, injected=injected) + original_middleware = None if callbacks.agent.middleware is None else list(callbacks.agent.middleware) + original_defaults = callbacks.agent.default_options.copy() + host = ( + InvocationsWorkflowHostServer( + callbacks.workflow, parse_input=lambda request: WorkflowTurn(input="hi", stream=stream) + ) + if workflow + else InvocationsHostServer(callbacks.agent) + ) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: + response = await client.post( + "/invocations?agent_session_id=background", json={"message": "hi", "stream": stream} + ) + assert response.status_code == (200 if stream else 500) + assert "invocation failed" in response.text.lower() + assert "background" in caplog.text or "transport controls" in caplog.text + assert callbacks.client.calls == [] + assert callbacks.agent.default_options == original_defaults + if not workflow: + assert callbacks.agent.middleware == original_middleware + + +@pytest.mark.parametrize("workflow", [False, True]) +@pytest.mark.parametrize("stream", [False, True]) +@pytest.mark.parametrize("location", ["options", "kwargs"]) +@pytest.mark.parametrize("injected", [{"background": True}, {"extra_body": {"background": True}}]) +async def test_raw_agent_client_middleware_background_is_rejected( + workflow: bool, stream: bool, location: str, injected: dict[str, Any], caplog: pytest.LogCaptureFixture +) -> None: + callbacks = BackgroundCallbacks(source="chat", location=location, injected=injected, raw=True) + host = ( + InvocationsWorkflowHostServer( + callbacks.workflow, parse_input=lambda request: WorkflowTurn(input="hi", stream=stream) + ) + if workflow + else InvocationsHostServer(callbacks.agent) + ) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: + response = await client.post( + "/invocations?agent_session_id=raw-background", json={"message": "hi", "stream": stream} + ) + assert response.status_code == (200 if stream else 500) + assert "background" in caplog.text + assert callbacks.client.calls == [] + + +@pytest.mark.parametrize("stream", [False, True]) +@pytest.mark.parametrize("shape", ["flat", "options"]) +async def test_native_raw_agent_rejects_run_level_middleware(stream: bool, shape: str) -> None: + callbacks = BackgroundCallbacks(source="none", location="options", injected={"background": True}, raw=True) + client_kwargs: dict[str, Any] = {"middleware": [callbacks.inject_chat]} + if shape == "options": + client_kwargs = {"options": client_kwargs} + host = InvocationsWorkflowHostServer( + callbacks.workflow, + parse_input=lambda request: WorkflowTurn(input="hi", stream=stream, client_kwargs=client_kwargs), + ) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: + response = await client.post("/invocations?agent_session_id=raw-middleware", json={"message": "hi"}) + assert response.status_code == (200 if stream else 400) + assert "cannot override hosting" in response.text + if stream: + assert "event: error" in response.text + assert callbacks.client.calls == [] + + +@pytest.mark.parametrize("workflow", [False, True]) +@pytest.mark.parametrize("stream", [False, True]) +@pytest.mark.parametrize("callbacks_type", [AgentChatCallbacks, ReplacedMiddlewareCallbacks]) +async def test_run_guard_survives_agent_chat_middleware_and_replaced_client_middleware( + workflow: bool, stream: bool, callbacks_type: type[BackgroundCallbacks] +) -> None: + callbacks = ( + AgentChatCallbacks() + if callbacks_type is AgentChatCallbacks + else callbacks_type(source="agent", location="options", injected={"background": True}) + ) + host = ( + InvocationsWorkflowHostServer( + callbacks.workflow, parse_input=lambda request: WorkflowTurn(input="hi", stream=stream) + ) + if workflow + else InvocationsHostServer(callbacks.agent) + ) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: + response = await client.post( + "/invocations?agent_session_id=background", json={"message": "hi", "stream": stream} + ) + assert "invocation failed" in response.text.lower() + assert callbacks.client.calls == [] + + +@pytest.mark.parametrize("workflow", [False, True]) +@pytest.mark.parametrize("raw", [False, True]) +@pytest.mark.parametrize("stream", [False, True]) +async def test_supported_middleware_preserves_foreground_generation(workflow: bool, raw: bool, stream: bool) -> None: + callbacks = BackgroundCallbacks(source="chat", location="options", injected={"temperature": 0.2}, raw=raw) + host = ( + InvocationsWorkflowHostServer( + callbacks.workflow, parse_input=lambda request: WorkflowTurn(input="hi", stream=stream) + ) + if workflow + else InvocationsHostServer(callbacks.agent) + ) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: + response = await client.post( + "/invocations?agent_session_id=foreground", json={"message": "hi", "stream": stream} + ) + assert response.status_code == 200 + assert "ok" in response.text + assert callbacks.client.calls[0]["temperature"] == 0.2 + if not (workflow and raw): + assert callbacks.client.chat_middleware == [callbacks.inject_chat] + + +def test_unlayered_client_receives_no_middleware_kwarg() -> None: + assert foreground_agent_run_kwargs(RawAgent(client=OptionsClient())) == {} diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py index af04a6c5126..34f63833543 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py @@ -279,6 +279,7 @@ async def test_resolver_allows_reused_stateless_function_tools(shared: Any) -> N for workflow in (first, second): executor = workflow.get_start_executor() assert isinstance(executor, AgentExecutor) + assert isinstance(executor.agent, RawAgent) assert executor.agent.default_options["tools"][0] is shared diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/workflow_tool_helpers.py b/python/packages/foundry_hosting/tests/foundry_hosting/workflow_tool_helpers.py index 2866bc010a4..9de39007638 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/workflow_tool_helpers.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/workflow_tool_helpers.py @@ -58,7 +58,11 @@ def capture(value: str) -> str: return CustomFunctionTool(name="custom", func=shared_function.func) if kind == "parser": return FunctionTool(name="parser", func=shared_function.func, result_parser=MutableToolOwner().count) - return FunctionTool(name="limited", func=shared_function.func, **{kind: 1}) + if kind == "max_invocations": + return FunctionTool(name="limited", func=shared_function.func, max_invocations=1) + if kind == "max_invocation_exceptions": + return FunctionTool(name="limited", func=shared_function.func, max_invocation_exceptions=1) + raise ValueError(f"Unknown mutable tool kind: {kind}") def workflow_with_tools(tools: list[Any], *, client: BaseChatClient | None = None) -> Workflow: From 2a240d3fc31b9cdb8aed4f4183118783e26a1680 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 10:35:43 +0100 Subject: [PATCH 23/55] Reconcile Foundry hosting background and steering docs --- .../0055-python-foundry-hosting-contracts.md | 11 ++++++ python/packages/foundry_hosting/README.md | 37 +++++++++++++------ .../responses/basic/provider_background.py | 3 +- .../resilient_long_running_workflow/main.py | 3 +- .../steerable_long_running_agent/README.md | 4 +- .../steerable_long_running_agent/main.py | 2 +- .../verify_steering.py | 7 ++-- 7 files changed, 45 insertions(+), 22 deletions(-) diff --git a/docs/decisions/0055-python-foundry-hosting-contracts.md b/docs/decisions/0055-python-foundry-hosting-contracts.md index 2997fc3f34f..721b74608cb 100644 --- a/docs/decisions/0055-python-foundry-hosting-contracts.md +++ b/docs/decisions/0055-python-foundry-hosting-contracts.md @@ -110,6 +110,17 @@ Outer workflow background must not enable background on constituent agents. Nati background is unsupported. Do not introduce a per-agent workflow-host background switch. Recovery permission neither selects an execution mode nor guarantees exactly-once external side effects. +Allow top-level `background` values of `False` or `None`, and reject nested `extra_body.background` in +every mode. Validate caller options, hook results, and developer defaults before execution. Also check the +effective options and client kwargs from ordinary agent middleware and client-level chat middleware before +the provider call. For a native `RawAgent`, install the check after existing client middleware on the fresh +client that the host owns. Make native `WorkflowTurn` reject client-level and run-level middleware. Report +middleware violations as execution failures, not as client input errors. + +Do not claim universal interception and do not change Core for this check. Core can append chat middleware +from context providers after the guard, so applications must not enable provider background there. Clients +that internally force provider background are unsupported. + ### Supported host settings Expose supported first-class settings and construct SDK options internally, without another framework diff --git a/python/packages/foundry_hosting/README.md b/python/packages/foundry_hosting/README.md index ef52f8bee57..93ddee7703a 100644 --- a/python/packages/foundry_hosting/README.md +++ b/python/packages/foundry_hosting/README.md @@ -227,7 +227,7 @@ history or decode pending replies. `agent=workflow.as_agent()` is no longer supp Wrapper context providers, history, event projection, and request-info translation are not silently unwrapped. See [Migrate `WorkflowAgent` hosting](#migrate-workflowagent-hosting). -With `resilient_background=True`, the application must also enable the +With `enable_background_recovery=True`, the application must also enable the AgentServer resilient task subsystem. Host-owned checkpoint/output pairs recover emitted output and usage without selecting newer unpaired workflow state. This is not an exactly-once guarantee for external tools: make @@ -318,7 +318,8 @@ Outer background work always uses the caller-visible `response.id` for polling; background automatically. `background_source="host_managed"` (default) uses only the outer background worker. `background_source="inference_service"` is a separate opt-in for `history_source="inference_service"` with a storing Responses client. Its private continuation token is saved under the outer ID and never returned to the caller. -Use `ResponsesServerOptions(resilient_background=True)` to permit recovery from a **saved** token; a crash before +Set `enable_background_recovery=True` to permit recovery from a **saved** token; for regular agents it requires +`history_source="inference_service"` and `background_source="inference_service"`. A crash before the token is saved cannot safely restart the inner job. Completed polling output, including local function calls, results, and usage, is saved together with the next token in the private response-ID snapshot before emission. Outer output checkpoints record which saved batches have been emitted, so recovery restores their usage and @@ -330,15 +331,29 @@ Each poll retains the caller's generation options and `background=True`, so a to another background response and saves its next token. A crash after a local tool side effect but before that next token is saved can still repeat the tool on recovery; use idempotent tools or avoid provider background for side-effecting local tools. This mechanism does not provide exactly-once tool execution. -Provider background and steering cannot be combined. -Regular agent runs without this opt-in are not crash-replayable. **Steering is temporarily unavailable:** -`steerable_conversations=True` fails during host construction, before enabling the process-wide TaskManager. -The current AgentServer SDK retains unbounded futures for rejected turns when its steering queue fills. Do not -use a queue-length precheck: another worker can append before it. The guard can be removed only after -[Azure/azure-sdk-for-python#49233](https://github.com/Azure/azure-sdk-for-python/pull/49233) ships in an -official `azure-ai-agentserver-core` wheel, the minimum dependency and `uv.lock` are updated, and a -concurrent queue-overflow regression proves rejected turns leave no pending futures. No future SDK -version is assumed. Non-steerable agent background polling is unchanged. +Regular agent runs without this opt-in are not crash-replayable. + +Provider background is selected only by the host. A provider call may use `background=True` only for an outer +background request with both `history_source="inference_service"` and `background_source="inference_service"`. +A top-level `background` of `False` or `None` is allowed in every mode. A nested `extra_body["background"]` is +always rejected, even when it is `False`. The host checks these values in caller options, the `prepare_options` +result, and developer defaults before execution. It also checks the effective options and client kwargs that +ordinary agent middleware and client-level chat middleware produce, before the provider call. Invocations hosts +and native workflow constituent agents never use provider background, and an outer workflow `background=True` does +not enable it for those agents. A native `WorkflowTurn` rejects client-level and run-level `middleware`. + +This guard does not intercept every path. Agent Framework Core can append chat middleware that a context provider +contributes **after** the guard; that middleware must not enable provider background. Clients that internally +force provider background are unsupported. Invalid defaults and request options fail before execution. A +middleware violation is an application failure during execution: a non-streaming request returns HTTP 500, and a +stream ends with a terminal error event. + +**Steering is unavailable.** `steerable_conversations` and the other removed `ResponsesServerOptions` settings are +not host parameters; passing them raises `TypeError` during host construction. The AgentServer SDK can retain +unbounded futures for rejected turns when its steering queue fills +([Azure/azure-sdk-for-python#49233](https://github.com/Azure/azure-sdk-for-python/pull/49233)). Any future +steering support needs a published SDK fix, a dependency update, and a concurrent queue-overflow regression. +No future SDK version is assumed. Agent background polling without steering is unchanged. Native CreateResponse generation fields become MAF runtime options (notably `max_output_tokens` -> `max_tokens` and `parallel_tool_calls` -> `allow_multiple_tool_calls`). Flattened OpenAI `extra_body` fields overlay translated keys diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/basic/provider_background.py b/python/samples/04-hosting/foundry-hosted-agents/responses/basic/provider_background.py index 67e46fe0b7c..1712885b910 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/basic/provider_background.py +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/basic/provider_background.py @@ -7,7 +7,6 @@ from agent_framework import Agent from agent_framework.foundry import FoundryChatClient from agent_framework_foundry_hosting import ResponsesHostServer, ResponsesRequest -from azure.ai.agentserver.responses import ResponsesServerOptions from azure.identity import DefaultAzureCredential from dotenv import load_dotenv @@ -31,7 +30,7 @@ def main() -> None: agent=create_agent, history_source="inference_service", background_source="inference_service", - options=ResponsesServerOptions(resilient_background=True), + enable_background_recovery=True, ).run() diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/resilient_long_running_workflow/main.py b/python/samples/04-hosting/foundry-hosted-agents/responses/resilient_long_running_workflow/main.py index a95415d83ce..2e3b2754430 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/resilient_long_running_workflow/main.py +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/resilient_long_running_workflow/main.py @@ -15,7 +15,6 @@ WorkflowTurn, ) from azure.ai.agentserver.core.tasks import set_resilient_tasks_enabled -from azure.ai.agentserver.responses import ResponsesServerOptions from pydantic import BaseModel, Field @@ -72,7 +71,7 @@ def main() -> None: checkpoint_store_provider=CheckpointStoreProvider( allowed_checkpoint_types=[f"{CountdownRequest.__module__}:{CountdownRequest.__qualname__}"], ), - options=ResponsesServerOptions(resilient_background=True), + enable_background_recovery=True, ).run() diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/README.md index f0b2f5526fa..77eb36bd912 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/README.md @@ -1,7 +1,7 @@ # Long-running Responses agent (steering temporarily unavailable) -**Steering is currently gated.** `ResponsesHostServer` rejects -`ResponsesServerOptions(steerable_conversations=True)` during construction rather than starting a +**Steering is currently gated.** `ResponsesHostServer` rejects the removed +`steerable_conversations` setting with `TypeError` during construction rather than starting a TaskManager that can retain unbounded futures after rejected steering requests. The upstream fix is [Azure/azure-sdk-for-python#49233](https://github.com/Azure/azure-sdk-for-python/pull/49233); steering will be re-enabled only after a patched official `azure-ai-agentserver-core` wheel is released, diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/main.py b/python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/main.py index 8169f5769b8..2f6be261903 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/main.py +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/main.py @@ -4,7 +4,7 @@ The agent is asked to count down from a target number, pacing its own output with a short remark before each number so a response takes a while to fully generate. This sample currently runs -without steering; the hosting layer rejects ``steerable_conversations=True`` until a patched +without steering; the hosting layer rejects the removed ``steerable_conversations`` setting until a patched AgentServer SDK is released and verified. Environment variables: diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/verify_steering.py b/python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/verify_steering.py index f5c6b2f89f1..d63a93b04cc 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/verify_steering.py +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/verify_steering.py @@ -10,7 +10,6 @@ from agent_framework import SupportsAgentRun from agent_framework_foundry_hosting import ResponsesHostServer, ResponsesRequest -from azure.ai.agentserver.responses import ResponsesServerOptions def _agent_factory(*, request: ResponsesRequest) -> SupportsAgentRun: @@ -20,9 +19,9 @@ def _agent_factory(*, request: ResponsesRequest) -> SupportsAgentRun: def main() -> None: """Confirm that the constructor rejects steering before creating an agent or host.""" try: - ResponsesHostServer(agent=_agent_factory, options=ResponsesServerOptions(steerable_conversations=True)) - except RuntimeError as exc: - if "steerable_conversations=True is temporarily unavailable" not in str(exc): + ResponsesHostServer(agent=_agent_factory, steerable_conversations=True) + except TypeError as exc: + if "steerable_conversations is no longer a supported host setting" not in str(exc): raise print("Steering is temporarily unavailable; no agent or host was started.") return From 84d15e85f5b8a0412ff271dbf69af48680d338a7 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 10:36:33 +0100 Subject: [PATCH 24/55] Fix consent test typing and use atomic session store in Toolbox approval test --- .../foundry_hosting/test_approval_translation.py | 4 +++- .../test_oauth_consent_invocation.py | 7 ++++--- .../foundry_hosting/toolbox_approval_helpers.py | 14 +++++++++++++- .../packages/foundry_hosting/tests/test_toolbox.py | 12 ++++++++++-- 4 files changed, 30 insertions(+), 7 deletions(-) diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_approval_translation.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_approval_translation.py index 72b429f3386..879fe347dd6 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_approval_translation.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_approval_translation.py @@ -52,7 +52,9 @@ async def save_approval_request(self, approval_request_id: str, request: Content def _event_type(event: Any) -> str: - return event.get("type") if isinstance(event, Mapping) else event.type + event_type = event.get("type") if isinstance(event, Mapping) else event.type # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType] + assert isinstance(event_type, str) + return event_type async def test_history_conversion_only_reads_approval_requests() -> None: diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_oauth_consent_invocation.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_oauth_consent_invocation.py index 05678aa4186..9ec974446ed 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_oauth_consent_invocation.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_oauth_consent_invocation.py @@ -10,7 +10,7 @@ from typing import Any import pytest -from agent_framework import Agent, Content, Message, UserInputRequiredException +from agent_framework import Agent, ChatOptions, Content, Message, UserInputRequiredException from agent_framework.exceptions import ToolExecutionException from azure.ai.agentserver.responses.aio import ResponseEventStream from mcp import MCPError @@ -73,6 +73,7 @@ async def run() -> None: def mark() -> None: current = _current_toolbox_consent_scope() + assert current is not None assert current is scope current.consent_rejected = True @@ -225,7 +226,7 @@ async def test_sequential_function_loop_returns_consent_and_blocks_later_calls(s server.require_consent("secure") async with consent_toolbox(server) as toolbox: client = BatchToolCallClient([function.name for function in toolbox.functions]) - agent = Agent(client=client, tools=toolbox, default_options={"allow_multiple_tool_calls": True}) + agent = Agent(client=client, tools=toolbox, default_options=ChatOptions(allow_multiple_tool_calls=True)) async def run() -> list[Message]: client.function_invocation_configuration["allow_concurrent_invocation"] = False # type: ignore[index] @@ -258,7 +259,7 @@ async def test_parallel_function_loop_preserves_completed_siblings(stream: bool) server.require_consent("secure") async with consent_toolbox(server) as toolbox: client = BatchToolCallClient([function.name for function in toolbox.functions]) - agent = Agent(client=client, tools=toolbox, default_options={"allow_multiple_tool_calls": True}) + agent = Agent(client=client, tools=toolbox, default_options=ChatOptions(allow_multiple_tool_calls=True)) async def run() -> list[Message]: if stream: diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/toolbox_approval_helpers.py b/python/packages/foundry_hosting/tests/foundry_hosting/toolbox_approval_helpers.py index 81fd0550e76..c48c2a1fcae 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/toolbox_approval_helpers.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/toolbox_approval_helpers.py @@ -18,10 +18,22 @@ FunctionInvocationLayer, Message, ResponseStream, + SessionStore, ) +from azure.ai.agentserver.core import AgentConfig, FoundryAgentRequestContext from azure.core.credentials import AccessToken -from agent_framework_foundry_hosting import FoundryToolbox +from agent_framework_foundry_hosting import FoundryToolbox, StoreProvider + + +class FixedSessionStoreProvider(StoreProvider[SessionStore]): + """Return one application-owned session store for every request.""" + + def __init__(self, store: SessionStore) -> None: + self.store = store + + def get_store(self, *, config: AgentConfig, platform_context: FoundryAgentRequestContext) -> SessionStore: + return self.store class ToolboxCredential: diff --git a/python/packages/foundry_hosting/tests/test_toolbox.py b/python/packages/foundry_hosting/tests/test_toolbox.py index 6396df53df1..166a6fe18d9 100644 --- a/python/packages/foundry_hosting/tests/test_toolbox.py +++ b/python/packages/foundry_hosting/tests/test_toolbox.py @@ -9,6 +9,7 @@ import json from collections.abc import Awaitable, Callable from datetime import datetime, timedelta, timezone +from pathlib import Path from types import SimpleNamespace from typing import Any, cast from unittest.mock import AsyncMock, Mock, patch @@ -44,7 +45,11 @@ _ToolboxAuth, ) +from .foundry_hosting.approval_helpers import ( # pyrefly: ignore[missing-import] - pytest's importlib namespace + SqliteSessionStore, +) from .foundry_hosting.toolbox_approval_helpers import ( # pyrefly: ignore[missing-import] - pytest's importlib namespace + FixedSessionStoreProvider, ToolboxApprovalClient, ToolboxApprovalServer, toolbox_connection, @@ -1494,12 +1499,15 @@ async def test_metadata_approval_pauses_and_resumes_once(stream: bool, approved: @pytest.mark.parametrize("stream", [False, True]) -async def test_responses_host_returns_metadata_approval_before_tool_execution(stream: bool) -> None: +async def test_responses_host_returns_metadata_approval_before_tool_execution(stream: bool, tmp_path: Path) -> None: mcp_server = ToolboxApprovalServer() mcp_server.tools = [toolbox_tool()] model = ToolboxApprovalClient("learn___microsoft_docs_search") async with toolbox_connection(mcp_server) as toolbox: - host = ResponsesHostServer(agent=Agent(client=model, tools=toolbox)) + host = ResponsesHostServer( + agent=Agent(client=model, tools=toolbox), + agent_session_store_provider=FixedSessionStoreProvider(SqliteSessionStore(tmp_path / "sessions.db")), + ) async with host_httpx.AsyncClient( transport=host_httpx.ASGITransport(app=host), base_url="http://test" ) as client: From 1687482388085f7f55fbb17570a64d5fd8b56f4b Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 10:43:55 +0100 Subject: [PATCH 25/55] Wire Responses approval and consent lifecycle --- .../__init__.py | 9 - .../_responses_agent.py | 283 ++++-- .../_responses_preflight.py | 264 +++++ .../_responses_workflow.py | 8 + .../foundry_hosting/responses_host_helpers.py | 282 ++++++ .../foundry_hosting/test_native_responses.py | 209 +++- .../foundry_hosting/tests/test_responses.py | 926 +++++++++++++++++- 7 files changed, 1848 insertions(+), 133 deletions(-) create mode 100644 python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_preflight.py create mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/responses_host_helpers.py diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/__init__.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/__init__.py index 08a11a53272..3e072a8c534 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/__init__.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/__init__.py @@ -20,9 +20,6 @@ ContextScopedStoreProvider, FoundryAgentSessionStore, FoundryCheckpointStore, - FoundryFunctionApprovalStore, - FunctionApprovalStore, - FunctionApprovalStoreProvider, StoreProvider, ) from ._toolbox import FoundryToolbox @@ -38,12 +35,9 @@ "ContextScopedStoreProvider": "._state_store", "FoundryAgentSessionStore": "._state_store", "FoundryCheckpointStore": "._state_store", - "FoundryFunctionApprovalStore": "._state_store", "FoundryRequestScope": "._scope", "FoundryToolbox": "._toolbox", "InvocationRun": "._shared", - "FunctionApprovalStore": "._state_store", - "FunctionApprovalStoreProvider": "._state_store", "InvocationsHostServer": "._invocations_agent", "InvocationsWorkflowHostServer": "._invocations_workflow", "ResponsesHostServer": "._responses_agent", @@ -61,11 +55,8 @@ "ContextScopedStoreProvider", "FoundryAgentSessionStore", "FoundryCheckpointStore", - "FoundryFunctionApprovalStore", "FoundryRequestScope", "FoundryToolbox", - "FunctionApprovalStore", - "FunctionApprovalStoreProvider", "InvocationRun", "InvocationsHostServer", "InvocationsWorkflowHostServer", diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py index 2b2c5c06ab1..1329049b77c 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py @@ -9,19 +9,27 @@ from collections.abc import ( AsyncGenerator, AsyncIterable, + Awaitable, + Callable, Generator, Mapping, Sequence, ) -from contextlib import AbstractAsyncContextManager, AsyncExitStack, aclosing, suppress -from copy import copy -from dataclasses import dataclass +from contextlib import AbstractAsyncContextManager, AsyncExitStack, aclosing +from copy import copy, deepcopy +from dataclasses import dataclass, field from typing import Any, Literal, cast from agent_framework import ( + AgentContext, + AgentMiddleware, + AgentMiddlewareLayer, AgentResponse, AgentResponseUpdate, AgentSession, + ChatContext, + ChatMiddleware, + ChatMiddlewareLayer, ChatOptions, ContextProvider, FinishReason, @@ -35,7 +43,7 @@ ) from agent_framework._telemetry import mark_feature_used from agent_framework.exceptions import AgentFrameworkException -from azure.ai.agentserver.core import get_request_context +from azure.ai.agentserver.core import FoundryAgentRequestContext, get_request_context from azure.ai.agentserver.responses import ( ResponseContext, ResponseProviderProtocol, @@ -51,7 +59,14 @@ ) from azure.ai.agentserver.responses.streaming._checkpoint import ResponseCheckpointEvent +from ._approvals import SessionApprovalState, _InvalidApproval # pyright: ignore[reportPrivateUsage] from ._feature_usage import FeatureIndex +from ._responses_preflight import ( + _InvalidApprovalInput, # pyright: ignore[reportPrivateUsage] + approval_controls, + bind_approval_preflight, + has_unresolved_input, +) from ._responses_shared import ( _HOSTED_CONVERSATION_CLAIM_KEY, # pyright: ignore[reportPrivateUsage] _HOSTED_CONVERSATION_COMMITTED_KEY, # pyright: ignore[reportPrivateUsage] @@ -61,6 +76,7 @@ _HOSTED_SERVICE_CHILD_KEY, # pyright: ignore[reportPrivateUsage] _HOSTED_SOURCE_CONVERSATION_KEY, # pyright: ignore[reportPrivateUsage] _PUBLIC_STREAM_FAILURE_MESSAGE, # pyright: ignore[reportPrivateUsage] + _activate_toolbox_consent_scope, # pyright: ignore[reportPrivateUsage] _agent_response_updates, # pyright: ignore[reportPrivateUsage] _await_before_signal, # pyright: ignore[reportPrivateUsage] _create_response_event_stream, # pyright: ignore[reportPrivateUsage] @@ -84,6 +100,7 @@ ResponsesRequest, UnsupportedOptions, build_response_server_options, + foreground_agent_run_kwargs, is_agent, prepare_response_options, reject_removed_host_settings, @@ -92,13 +109,12 @@ validate_agent_background_options, validate_agent_source, validate_default_transport_options, + validate_provider_background_options, validate_request_options, validate_unsupported_options, ) from ._state_store import ( AgentSessionStoreProvider, - FunctionApprovalStore, - FunctionApprovalStoreProvider, StoreProvider, ) @@ -129,9 +145,61 @@ class _AgentConfiguration: hosted_history: bool -def _validate_agent_defaults( - agent: SupportsAgentRun, *, provider_background: bool, allow_agent_store: bool -) -> None: +@dataclass +class _DeferredOutput: + snapshot: dict[str, Any] | None = None + events: list[ResponseStreamEvent | ResponseCheckpointEvent] = field( + default_factory=lambda: list[ResponseStreamEvent | ResponseCheckpointEvent]() + ) + + +def _validate_selected_provider_background(options: Mapping[str, Any], kwargs: Mapping[str, Any]) -> None: + validate_provider_background_options(options, provider_background=True) + validate_provider_background_options(kwargs, provider_background=True) + if options.get("background") is not True or ("background" in kwargs and kwargs["background"] is not True): + raise ValueError("A selected provider-background request must retain background=True.") + + +class _ProviderBackgroundChatOptions(ChatMiddleware): + async def process(self, context: ChatContext, call_next: Callable[[], Awaitable[None]]) -> None: + _validate_selected_provider_background(context.options or {}, context.kwargs) + await call_next() + + +_PROVIDER_BACKGROUND_CHAT_OPTIONS = _ProviderBackgroundChatOptions() + + +def _append_provider_background_chat_options(agent: RawAgent[Any], client_kwargs: dict[str, Any]) -> None: + if not isinstance(agent.client, ChatMiddlewareLayer): + return + middleware = client_kwargs.get("middleware", ()) + if not isinstance(middleware, Sequence) or isinstance(middleware, (str, bytes)): + raise TypeError("Client middleware must be a sequence.") + client_kwargs["middleware"] = [*middleware, _PROVIDER_BACKGROUND_CHAT_OPTIONS] + + +class _ProviderBackgroundAgentOptions(AgentMiddleware): + async def process(self, context: AgentContext, call_next: Callable[[], Awaitable[None]]) -> None: + agent = context.agent + validate_agent_background_options(agent, provider_background=True) + _validate_selected_provider_background(context.options or {}, context.client_kwargs) + if isinstance(agent, RawAgent): + _append_provider_background_chat_options(cast(RawAgent[Any], agent), context.client_kwargs) + await call_next() + + +_PROVIDER_BACKGROUND_AGENT_OPTIONS = _ProviderBackgroundAgentOptions() + + +def _provider_background_run_kwargs(agent: RawAgent[Any]) -> dict[str, Any]: + if isinstance(agent, AgentMiddlewareLayer): + return {"middleware": [_PROVIDER_BACKGROUND_AGENT_OPTIONS]} + kwargs: dict[str, Any] = {} + _append_provider_background_chat_options(agent, kwargs) + return {"client_kwargs": kwargs} if kwargs else {} + + +def _validate_agent_defaults(agent: SupportsAgentRun, *, provider_background: bool, allow_agent_store: bool) -> None: validate_agent_background_options(agent, provider_background=provider_background) if isinstance(agent, RawAgent): validate_default_transport_options(agent.default_options, allow_agent_store=allow_agent_store) @@ -147,7 +215,7 @@ def _validate_agent_configuration( resilient_background = bool(options and options.resilient_background) if resilient_background and background_source != "inference_service": raise RuntimeError( - "resilient_background=True requires background_source='inference_service' for regular agents. " + "enable_background_recovery=True requires background_source='inference_service' for regular agents. " "Use ResponsesWorkflowHostServer for checkpoint-based workflow recovery." ) if background_source == "inference_service" and ( @@ -236,7 +304,6 @@ def __init__( prefix: str = "", response_store: ResponseProviderProtocol | None = None, agent_session_store_provider: StoreProvider[SessionStore] | None = None, - function_approval_store_provider: StoreProvider[FunctionApprovalStore] | None = None, allowed_oauth_consent_origins: Sequence[str] | None = None, history_source: Literal["host_managed", "agent_managed", "inference_service"] = "host_managed", background_source: Literal["host_managed", "inference_service"] = "host_managed", @@ -262,9 +329,8 @@ def __init__( prefix: The URL prefix for the server. response_store: Optional response store for caller-facing persistence and history. agent_session_store_provider: Optional provider for MAF agent session storage. - If not provided, a default `AgentSessionStoreProvider` will be used. - function_approval_store_provider: Optional provider for function approval storage. - If not provided, a default `FunctionApprovalStoreProvider` will be used. + If not provided, a default `AgentSessionStoreProvider` will be used. Approval continuations require + atomic create-only and revision-conditional writes in this store. allowed_oauth_consent_origins: Optional exact HTTPS origins allowed for OAuth consent links. When omitted, hosting retains its existing safe-HTTPS validation without restricting the destination origin. When provided, every link must match an entry; an empty sequence rejects @@ -343,6 +409,8 @@ def __init__( RuntimeError: If the agent configuration conflicts with the selected history or background source. """ reject_removed_host_settings(kwargs) + if "function_approval_store_provider" in kwargs: + raise TypeError("Approval state is managed by agent_session_store_provider.") if "store" in kwargs: raise TypeError("The constructor store= alias was removed; use response_store= instead.") if {"workflow", "parse_input", "parse_response", "checkpoint_store_provider"}.intersection(kwargs): @@ -401,11 +469,7 @@ def __init__( self._session_storage_provider = ( AgentSessionStoreProvider() if agent_session_store_provider is None else agent_session_store_provider ) - self._function_approval_storage_provider = ( - FunctionApprovalStoreProvider() - if function_approval_store_provider is None - else function_approval_store_provider - ) + bind_approval_preflight(self, prefix=prefix, preflight=self._preflight_approvals) # Lazy agent lifecycle: the agent (and any MCP tools it owns) is entered on # the first request rather than at server startup, so that authentication @@ -419,6 +483,38 @@ def __init__( mark_feature_used(FeatureIndex.FOUNDRY_HOSTING) + async def _preflight_approvals( + self, + request: CreateResponse, + context: ResponseContext, + platform_context: FoundryAgentRequestContext, + ) -> None: + items = [cast(Mapping[str, Any], item) for item in await context.get_input_items()] + ids = approval_controls(items) + previous = request.get("previous_response_id") + previous = previous if isinstance(previous, str) and previous else None + session_id = context.conversation_id or previous + if session_id is None: + if ids: + raise _InvalidApprovalInput("The approval has no pending agent session.") + return + storage = self._session_storage_provider.get_store(config=self.config, platform_context=platform_context) + session = await storage.get(session_id) + if session is None: + if ids: + raise _InvalidApprovalInput("The approval is unavailable in this agent session.") + return + state = SessionApprovalState(session, storage) + try: + claim = await state.preflight(ids) + except _InvalidApproval as exc: + raise _InvalidApprovalInput(str(exc)) from exc + if claim is not None: + if request.get("store") is False: + raise _InvalidApprovalInput("Approval continuation requires store=true.") + if len(items) != len(ids) or has_unresolved_input(request, items): + raise _InvalidApprovalInput("Pending MCP approvals cannot be mixed with other input.") + async def _ensure_agent_ready(self) -> None: """Lazily enter the agent's async context exactly once. @@ -668,6 +764,7 @@ async def _handle_prepared_response( return tracker = _OutputItemTracker(response_event_stream, self._allowed_oauth_consent_origins) + deferred = _DeferredOutput() try: inner = self._handle_inner_agent( request, @@ -678,14 +775,12 @@ async def _handle_prepared_response( agent, configuration, hosted_request, + deferred, ) - try: + async with aclosing(inner): async for event in inner: yield event - except BaseException: - await inner.aclose() - raise if cancellation_signal.is_set() and context.client_cancelled: # A cancelled run drains the inner generator without raising @@ -718,14 +813,16 @@ async def _handle_prepared_response( else: yield response_event_stream.emit_completed(usage=tracker.usage) except Exception as ex: - for event in tracker.close(): - yield event - + failure_tracker: _OutputItemTracker | None = tracker + if deferred.snapshot is not None: + response_event_stream.response.clear() + response_event_stream.response.update(deferred.snapshot) + failure_tracker = None for event in self._emit_failure( context.response_id, "response production", response_event_stream, - tracker, + failure_tracker, ex, ): yield event @@ -734,8 +831,9 @@ async def _load_request_messages( self, context: ResponseContext, *, - approval_storage: FunctionApprovalStore | None, + approval_storage: SessionApprovalState | None, configuration: _AgentConfiguration | None = None, + approval_ready: asyncio.Future[SessionApprovalState] | None = None, ) -> list[Message]: """Load the request's input and prior history concurrently, assembled for the run. @@ -756,13 +854,15 @@ async def _load_request_messages( async def _load_input() -> list[Message]: input_items = await context.get_input_items() - return await _items_to_messages(input_items, approval_storage=approval_storage) + resolved_storage = await approval_ready if approval_ready is not None else approval_storage + return await _items_to_messages(input_items, approval_storage=resolved_storage) async def _load_history() -> list[Message]: if not uses_agent_server_history: return [] history = await context.get_history() - return await _output_items_to_messages(history, approval_storage=approval_storage) + resolved_storage = await approval_ready if approval_ready is not None else approval_storage + return await _output_items_to_messages(history, approval_storage=resolved_storage) input_task = asyncio.ensure_future(_load_input()) history_task = asyncio.ensure_future(_load_history()) @@ -788,6 +888,7 @@ async def _handle_inner_agent( agent: SupportsAgentRun, configuration: _AgentConfiguration, hosted_request: ResponsesRequest, + deferred: _DeferredOutput, ) -> AsyncGenerator[ResponseStreamEvent | ResponseCheckpointEvent]: """Handle a regular (non-workflow) agent. @@ -864,11 +965,6 @@ async def _handle_inner_agent( ) request_context = get_request_context() - approval_storage = ( - self._function_approval_storage_provider.get_store(config=self.config, platform_context=request_context) - if stored - else None - ) previous_response_id = request.get("previous_response_id") session_load_id = ( context.response_id @@ -882,26 +978,24 @@ async def _handle_inner_agent( ) session_storage = ( self._session_storage_provider.get_store(config=self.config, platform_context=request_context) - if stored or (session_load_id is not None and self._history_source == "agent_managed") + if stored or session_load_id is not None else None ) - - # Load the caller's input items and prior conversation history concurrently with the - # session load below. These are independent storage round-trips with no data dependency - # between them, so overlapping them removes serial latency from the request critical path. + approval_ready: asyncio.Future[SessionApprovalState] = asyncio.get_running_loop().create_future() request_messages_task = asyncio.ensure_future( self._load_request_messages( context, - approval_storage=approval_storage, + approval_storage=None, configuration=configuration, + approval_ready=approval_ready, ) ) - - session = ( + stored_session = ( await session_storage.get(session_load_id) if session_storage is not None and session_load_id is not None else None ) + session = stored_session if stored or self._history_source == "agent_managed" else None if session is None: if context.is_recovery and provider_background: raise _PublicResponseFailure( @@ -914,6 +1008,20 @@ async def _handle_inner_agent( ) ) session = agent.create_session() + approval_session = stored_session or session + approval_storage = SessionApprovalState(approval_session, session_storage, response_id=context.response_id) + input_items = [cast(Mapping[str, Any], item) for item in await context.get_input_items()] + try: + approval_ids = approval_controls(input_items) + approval_claim = await approval_storage.preflight(approval_ids) + if approval_claim is not None: + if not stored: + raise _InvalidApprovalInput("Approval continuation requires store=true.") + if len(input_items) != len(approval_ids) or has_unresolved_input(request, input_items): + raise _InvalidApprovalInput("Pending MCP approvals cannot be mixed with other input.") + except (_InvalidApproval, _InvalidApprovalInput) as exc: + raise _PublicResponseFailure(exc) from None + approval_ready.set_result(approval_storage) provider_state = session.state.get(_HOSTED_PROVIDER_STATE_KEY) if context.conversation_id is not None: if context.is_recovery and provider_background: @@ -974,8 +1082,7 @@ async def _handle_inner_agent( # task so it is not orphaned, and log only ordinary failures. if request_messages_task is not None: request_messages_task.cancel() - with suppress(BaseException): - await request_messages_task + await asyncio.gather(request_messages_task, return_exceptions=True) if isinstance(ex, Exception): _log_response_failure("state storage preparation", context.response_id, ex) raise @@ -1031,6 +1138,9 @@ async def _handle_inner_agent( if self._unsupported_options == "warn": logger.warning("Agent doesn't support runtime options. They will be ignored.") + if not provider_background: + run_kwargs.update(foreground_agent_run_kwargs(cast(SupportsAgentRun, agent))) + if previous_response_id is not None and context.conversation_id is None and not context.is_recovery: if ( stored @@ -1066,6 +1176,43 @@ async def _handle_inner_agent( finally: session.state.pop(_HOSTED_CONVERSATION_CLAIM_KEY, None) + if approval_claim is not None: + await approval_storage.claim(approval_claim, response_id=context.response_id) + + consent_scope = _activate_toolbox_consent_scope(allowed_origins=self._allowed_oauth_consent_origins) + + async def track_update( + update: AgentResponseUpdate, *, complete_message: bool = False + ) -> AsyncGenerator[ResponseStreamEvent]: + if consent_scope.consent_rejected: + raise _PublicResponseFailure(ValueError("OAuth consent link rejected.")) + has_continuation = any( + content.type in ("function_approval_request", "oauth_consent_request") or content.user_input_request + for content in update.contents + ) + if not stored and (has_continuation or consent_scope.consent_required): + raise _PublicResponseFailure( + ValueError("OAuth consent or approval continuation requires store=true.") + ) + if self._history_source == "inference_service" and ( + consent_scope.consent_required + or any(content.type == "oauth_consent_request" for content in update.contents) + ): + raise _PublicResponseFailure( + ValueError( + "Invocation-time OAuth consent is unsupported with history_source='inference_service'." + ) + ) + if deferred.snapshot is None and has_continuation: + deferred.snapshot = deepcopy(response_event_stream.response) + async for event in tracker.handle_update( + update, approval_storage=approval_storage, complete_message=complete_message + ): + if deferred.snapshot is None: + yield event + else: + deferred.events.append(event) + inner_stream: ResponseStream[AgentResponseUpdate, AgentResponse[Any]] | None = None updates: _SignalledIterator[AgentResponseUpdate] | None = None if provider_background: @@ -1091,32 +1238,35 @@ async def _handle_inner_agent( for update in _agent_response_updates(response, context.response_id): if context.shutdown.is_set() or cancellation_signal.is_set(): break - async for event in tracker.handle_update( - update, approval_storage=approval_storage, complete_message=True - ): + async for event in track_update(update, complete_message=True): yield event if context.shutdown.is_set() or cancellation_signal.is_set(): continue for event in tracker.close(): - yield event + if deferred.snapshot is None: + yield event + else: + deferred.events.append(event) private_metadata = _hosted_internal_metadata(response_event_stream) private_metadata[_HOSTED_PROVIDER_OUTPUT_COUNT_KEY] = output_count private_metadata[_HOSTED_PROVIDER_USAGE_KEY] = tracker.usage_details if self._resilient_background: - yield response_event_stream.checkpoint() + checkpoint = response_event_stream.checkpoint() + if deferred.snapshot is None: + yield checkpoint + else: + deferred.events.append(checkpoint) else: inner_stream = agent.run(stream=True, **run_kwargs) # type: ignore[reportUnknownMemberType] updates = _SignalledIterator(inner_stream, context.shutdown, cancellation_signal) async with aclosing(updates): async for update in updates: - if not stored and any( - content.type in ("function_approval_request", "oauth_consent_request") - or content.user_input_request - for content in update.contents - ): - raise ValueError("Approval and user-input continuation requires store=true.") - async for event in tracker.handle_update(update, approval_storage=approval_storage): + async for event in track_update(update): yield event + if consent_scope.consent_rejected: + raise _PublicResponseFailure(ValueError("OAuth consent link rejected.")) + if consent_scope.consent_required and not stored: + raise _PublicResponseFailure(ValueError("OAuth consent continuation requires store=true.")) if inner_stream is not None and isinstance(updates, _SignalledIterator) and not updates.signalled: final = await inner_stream.get_final_response() if final.continuation_token is not None and final.finish_reason is None: @@ -1181,6 +1331,13 @@ async def _handle_inner_agent( cancellation_signal.is_set() and not context.client_cancelled and not context.shutdown.is_set() ) if stored and session_storage is not None and not stored_output_violation and final_provider_state: + if ( + request_failure is None + and not request_interrupted + and not context.shutdown.is_set() + and not cancellation_signal.is_set() + ): + await approval_storage.seal() if context.conversation_id is not None: session.state[_HOSTED_SOURCE_CONVERSATION_KEY] = context.conversation_id await _set_agent_session(session_storage, context.response_id, session) @@ -1218,6 +1375,9 @@ async def _handle_inner_agent( raise request_failure elif save_failure is not None: raise save_failure + if not request_interrupted and not context.shutdown.is_set() and not cancellation_signal.is_set(): + for event in deferred.events: + yield event async def _provider_background_responses( self, @@ -1246,7 +1406,7 @@ async def proceed(*, has_token: bool) -> bool: if has_token and self._resilient_background: await context.exit_for_recovery() if has_token: - raise RuntimeError("Provider background recovery requires resilient_background=True.") + raise RuntimeError("Provider background recovery requires enable_background_recovery=True.") raise _PublicResponseFailure( RuntimeError( "Provider background submission stopped before its token was saved; cannot safely retry it." @@ -1260,7 +1420,12 @@ async def run_provider( options: ChatOptions[Any], *, input_messages: list[Message] | None, phase: Literal["submit", "poll"] ) -> AgentResponse[Any]: try: - return await agent.run(input_messages, session=session, options=options) + return await agent.run( + input_messages, + session=session, + options=options, + **_provider_background_run_kwargs(agent), + ) except Exception as exc: logger.warning("Inner provider background %s failed (%s).", phase, type(exc).__name__) raise RuntimeError(f"Inner provider background {phase} failed; inspect the host logs.") diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_preflight.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_preflight.py new file mode 100644 index 00000000000..d99fd812adf --- /dev/null +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_preflight.py @@ -0,0 +1,264 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Read-only approval validation before the Responses SDK opens a stream.""" + +from __future__ import annotations + +import logging +from collections.abc import Awaitable, Callable, Mapping, Sequence +from copy import deepcopy +from typing import Any, cast + +from azure.ai.agentserver.core import ( + FoundryAgentRequestContext, + read_request_id, + reset_request_context, + set_request_context, +) +from azure.ai.agentserver.core.platform_headers import FOUNDRY_CALL_ID, USER_ID +from azure.ai.agentserver.responses import ( + FoundryApiError, + PlatformContext, + ResponseContext, +) +from azure.ai.agentserver.responses._egress import strip_internal_metadata +from azure.ai.agentserver.responses.hosting import ResponsesAgentServerHost +from azure.ai.agentserver.responses.hosting._endpoint_handler import _ResponseEndpointHandler # pyright: ignore[reportPrivateUsage] +from azure.ai.agentserver.responses.hosting._request_parsing import ( + _prevalidate_identity_payload, # pyright: ignore[reportPrivateUsage] + _resolve_conversation_id, # pyright: ignore[reportPrivateUsage] + _resolve_identity_fields, # pyright: ignore[reportPrivateUsage] + _resolve_session_id, # pyright: ignore[reportPrivateUsage] +) +from azure.ai.agentserver.responses.hosting._validation import ( + ERROR_SOURCE_PLATFORM, + error_response, + is_platform_error, + parse_and_validate_create_response, +) +from azure.ai.agentserver.responses.models import CreateResponse +from azure.ai.agentserver.responses.models._helpers import get_input_expanded, to_output_item +from azure.ai.agentserver.responses.models.runtime import ResponseModeFlags +from starlette.requests import Request +from starlette.responses import Response +from starlette.routing import Route + +from ._scope import FoundryRequestScope +from ._workflow_state import FoundryWorkflowBindingStore + +logger = logging.getLogger(__name__) + + +class _InvalidApprovalInput(ValueError): + """A caller's approval controls cannot resume the current pending batch.""" + + +_Preflight = Callable[[CreateResponse, ResponseContext, FoundryAgentRequestContext], Awaitable[None]] + + +def _create_route_path(prefix: str) -> str: + normalized = prefix.strip() + if normalized and not normalized.startswith("/"): + normalized = f"/{normalized}" + return f"{normalized.rstrip('/')}/responses" + + +def bind_approval_preflight(host: ResponsesAgentServerHost, *, prefix: str, preflight: _Preflight) -> None: + """Wrap only SDK create; delegate malformed requests and draining to the SDK.""" + for index, route in enumerate(host.router.routes): + if ( + not isinstance(route, Route) + or route.path != _create_route_path(prefix) + or route.name != "create_response" + or "POST" not in (route.methods or ()) + ): + continue + handler = cast(Callable[[Request], Awaitable[Response]], route.endpoint) + endpoint = getattr(handler, "__self__", None) + if not isinstance(endpoint, _ResponseEndpointHandler): + raise RuntimeError("The Responses SDK create endpoint is unavailable for approval preflight.") + + async def checked_create( + request: Request, + *, + endpoint: _ResponseEndpointHandler = endpoint, + handler: Callable[[Request], Awaitable[Response]] = handler, + ) -> Response: + if endpoint._is_draining: # pyright: ignore[reportPrivateUsage] + return await handler(request) + + # The SDK mutates the cached JSON when stripping internal metadata. + # Inspect a copy so its own validation receives the original request. + try: + payload = deepcopy(await request.json()) + strip_internal_metadata(payload) + _prevalidate_identity_payload(payload) + parsed = parse_and_validate_create_response( + payload, + options=endpoint._runtime_options, # pyright: ignore[reportPrivateUsage] + ) + response_id, agent_reference = _resolve_identity_fields(parsed, request_headers=request.headers) + session_id = _resolve_session_id( + parsed, + payload, + env_session_id=host.config.session_id or "", + agent_reference=agent_reference, + ) + except (TypeError, ValueError, KeyError, AttributeError): + return await handler(request) + + platform = PlatformContext( + user_id_key=request.headers.get(USER_ID), + call_id=request.headers.get(FOUNDRY_CALL_ID), + ) + platform_context = FoundryAgentRequestContext( + user_id=platform.user_id_key or None, + call_id=platform.call_id or None, + session_id=session_id, + ) + previous = parsed.get("previous_response_id") + previous = previous if isinstance(previous, str) and previous else None + conversation_id = _resolve_conversation_id(parsed) + input_items = [ + output + for item in get_input_expanded(parsed) + if (output := to_output_item(item, response_id)) is not None + ] + context = ResponseContext( + response_id=response_id, + request=parsed, + mode_flags=ResponseModeFlags( + stream=bool(parsed.get("stream")), + store=parsed.get("store") is not False, + background=bool(parsed.get("background")), + ), + provider=endpoint._provider, # pyright: ignore[reportPrivateUsage] + input_items=input_items, + previous_response_id=previous, + conversation_id=conversation_id, + platform_context=platform, + session_id=session_id, + ) + headers = endpoint._session_headers(session_id) # pyright: ignore[reportPrivateUsage] + request_id = read_request_id(request.scope) + token = set_request_context(platform_context) + try: + await preflight(parsed, context, platform_context) + except _InvalidApprovalInput as exc: + return error_response(exc, headers, request_id=request_id) + except Exception as exc: + logger.error("Responses approval preflight failed (%s).", type(exc).__name__) + # A backend may raise ValueError; it is not an invalid request. + error = RuntimeError("Responses approval preflight failed; inspect the host logs.") + source = ERROR_SOURCE_PLATFORM if is_platform_error(exc) or isinstance(exc, FoundryApiError) else None + return error_response(error, headers, request_id=request_id, error_source=source) + finally: + reset_request_context(token) + return await handler(request) + + host.router.routes[index] = Route( + route.path, + endpoint=checked_create, + methods=list(route.methods or ()), + name=route.name, + include_in_schema=route.include_in_schema, + ) + return + raise RuntimeError("The Responses SDK create route is unavailable for approval preflight.") + + +def approval_controls(items: list[Mapping[str, Any]]) -> list[str]: + """Extract validated MCP decisions without applying generic reply rules.""" + ids: list[str] = [] + for item in items: + if item.get("type") != "mcp_approval_response": + continue + wire_id, decision = item.get("approval_request_id"), item.get("approve") + if not isinstance(wire_id, str) or not wire_id or type(decision) is not bool: + raise _InvalidApprovalInput("An approval reply requires its exact ID and a boolean decision.") + ids.append(wire_id) + return ids + + +def has_unresolved_input(request: Mapping[str, Any], items: Sequence[Mapping[str, Any]]) -> bool: + """Detect input references the SDK silently omitted during resolution.""" + return len(get_input_expanded(cast(CreateResponse, request))) != len(items) + + +async def preflight_workflow_approvals( + request: CreateResponse, + context: ResponseContext, + platform_context: FoundryAgentRequestContext, + host: ResponsesAgentServerHost, +) -> None: + """Check a native MCP batch against its exact completed checkpoint pair.""" + items = [cast(Mapping[str, Any], item) for item in await context.get_input_items()] + ids = approval_controls(items) + previous = request.get("previous_response_id") + previous = previous if isinstance(previous, str) and previous else None + if previous is None and context.conversation_id is None: + if ids: + raise _InvalidApprovalInput("The approval has no pending workflow checkpoint.") + return + scope = FoundryRequestScope.from_context(host.config, platform_context, local_session_id=context.response_id) + storage = FoundryWorkflowBindingStore(scope) + record = None + if previous is not None: + record, _ = await storage.get_response(previous) + if record is not None and record.status == "completed" and record.binding.conversation_id is None: + head, _ = await storage.get_head(record.binding.lineage_id, None) + else: + head = None + else: + head, _ = await storage.get_head(context.response_id, context.conversation_id) + if head is not None and head.binding is not None: + record, _ = await storage.get_response(head.binding.response_id) + + if ( + record is None + or record.status != "completed" + or record.snapshot is None + or head is None + or head.blocked + or head.response_id is not None + or head.binding != record.binding + ): + if ids: + raise _InvalidApprovalInput("The approval is unavailable in the current workflow checkpoint.") + return + aliases = record.approvals or {} + output = record.snapshot.get("output") + if not isinstance(output, list): + raise RuntimeError("The workflow approval snapshot has invalid output.") + approval_ids: set[str] = set() + for raw_item in cast(list[Any], output): + if not isinstance(raw_item, dict): + continue + item = cast(dict[str, Any], raw_item) + wire_id = item.get("id") + if item.get("type") == "mcp_approval_request" and isinstance(wire_id, str) and wire_id in aliases: + approval_ids.add(wire_id) + if not approval_ids: + if ids: + raise _InvalidApprovalInput("The workflow has no pending MCP approval batch.") + return + if request.get("store") is False: + raise _InvalidApprovalInput("Approval continuation requires store=true.") + if has_unresolved_input(request, items): + raise _InvalidApprovalInput("Pending workflow approvals cannot include unresolved input references.") + controls: list[str] = [] + for item in items: + item_type = item.get("type") + if item_type == "mcp_approval_response": + wire_id = item.get("approval_request_id") + if wire_id not in approval_ids: + raise _InvalidApprovalInput("An approval reply must match this exact pending checkpoint.") + elif item_type in ("function_call_output", "computer_call_output"): + wire_id = item.get("call_id") + if not isinstance(wire_id, str) or wire_id not in aliases or wire_id in approval_ids: + raise _InvalidApprovalInput("A reply must match this exact pending checkpoint.") + else: + raise _InvalidApprovalInput("Pending workflow approvals cannot be mixed with new input.") + controls.append(cast(str, wire_id)) + if len(controls) != len(set(controls)) or set(controls) != set(aliases): + raise _InvalidApprovalInput("Answer exactly the complete pending workflow request batch.") diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py index 6a323eb70b9..62dcd0981d0 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py @@ -45,6 +45,7 @@ from starlette.types import Send from ._feature_usage import FeatureIndex +from ._responses_preflight import bind_approval_preflight, has_unresolved_input, preflight_workflow_approvals from ._responses_shared import ( _HOSTED_PROVIDER_USAGE_KEY, # pyright: ignore[reportPrivateUsage] _agent_response_updates, # pyright: ignore[reportPrivateUsage] @@ -164,6 +165,8 @@ async def _load_replies(request: ResponsesRequest, run: HostedWorkflowRun) -> di items = await request.get_input_items() if not run.pending_requests or not items: raise _WorkflowRequestError("Workflow replies require an exact pending stored checkpoint.") + if has_unresolved_input(request.request, items): + raise _WorkflowRequestError("Pending workflow replies cannot include unresolved input references.") replies: dict[str, Any] = {} for input_item in items: item = cast(Mapping[str, Any], input_item) @@ -416,6 +419,11 @@ def __init__( self._prepare_options = prepare_options self._resilient_background = enable_background_recovery self._allowed_origins = allowed_origins + bind_approval_preflight( + self, + prefix=prefix, + preflight=lambda request, context, platform: preflight_workflow_approvals(request, context, platform, self), + ) self._bind_streaming_route( prefix=prefix, keep_alive=bool( diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/responses_host_helpers.py b/python/packages/foundry_hosting/tests/foundry_hosting/responses_host_helpers.py new file mode 100644 index 00000000000..3998ed9c4bb --- /dev/null +++ b/python/packages/foundry_hosting/tests/foundry_hosting/responses_host_helpers.py @@ -0,0 +1,282 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Controlled provider and storage boundaries for Responses host integration tests.""" + +from __future__ import annotations + +import asyncio +from collections.abc import AsyncIterator, Awaitable, Callable, Mapping, Sequence +from pathlib import Path +from typing import Any + +from agent_framework import ( + AgentContext, + AgentMiddleware, + AgentResponseUpdate, + AgentSession, + BaseChatClient, + ChatContext, + ChatMiddleware, + ChatMiddlewareLayer, + ChatResponse, + ChatResponseUpdate, + Content, + FunctionInvocationLayer, + Message, + ResponseStream, + SessionStore, +) +from agent_framework.openai import OpenAIContinuationToken + +from .approval_helpers import SqliteSessionStore + + +class BackgroundAgentMiddleware(AgentMiddleware): + def __init__(self, *, nested: bool, value: bool = True, in_kwargs: bool = False, on_poll: bool = False) -> None: + self.nested = nested + self.value = value + self.in_kwargs = in_kwargs + self.on_poll = on_poll + + async def process(self, context: AgentContext, call_next: Callable[[], Awaitable[None]]) -> None: + if not self.on_poll or (context.options or {}).get("continuation_token") is not None: + override = {"extra_body": {"background": self.value}} if self.nested else {"background": self.value} + if self.in_kwargs: + context.client_kwargs.update(override) + else: + context.options = {**(context.options or {}), **override} + await call_next() + + +class BackgroundChatMiddleware(ChatMiddleware): + def __init__(self, *, nested: bool, value: bool = True, in_kwargs: bool = False, on_poll: bool = False) -> None: + self.nested = nested + self.value = value + self.in_kwargs = in_kwargs + self.on_poll = on_poll + + async def process(self, context: ChatContext, call_next: Callable[[], Awaitable[None]]) -> None: + if not self.on_poll or (context.options or {}).get("continuation_token") is not None: + override = {"extra_body": {"background": self.value}} if self.nested else {"background": self.value} + if self.in_kwargs: + context.kwargs.update(override) + else: + context.options = {**(context.options or {}), **override} + await call_next() + + +class BackgroundPollingClient(ChatMiddlewareLayer[Any], BaseChatClient[Any]): + STORES_BY_DEFAULT = True + + def __init__(self) -> None: + super().__init__() + self.calls: list[dict[str, Any]] = [] + + def _inner_get_response( + self, + *, + messages: Sequence[Message], + stream: bool, + options: Mapping[str, Any], + **kwargs: Any, + ) -> Awaitable[ChatResponse] | ResponseStream[ChatResponseUpdate, ChatResponse]: + del messages, kwargs + assert not stream + self.calls.append(dict(options)) + + async def response() -> ChatResponse: + if len(self.calls) == 1: + return ChatResponse( + conversation_id="provider-conversation", + continuation_token=OpenAIContinuationToken(response_id="provider-token"), + ) + return ChatResponse(messages=[Message("assistant", "done")], conversation_id="provider-conversation") + + return response() + + +class ApprovalPublishingClient(ChatMiddlewareLayer[Any], BaseChatClient[Any]): + STORES_BY_DEFAULT = False + + def __init__(self, approval: Content) -> None: + super().__init__() + self.approval = approval + self.calls = 0 + + def _inner_get_response( + self, + *, + messages: Sequence[Message], + stream: bool, + options: Mapping[str, Any], + **kwargs: Any, + ) -> Awaitable[ChatResponse] | ResponseStream[ChatResponseUpdate, ChatResponse]: + del messages, options, kwargs + assert stream + self.calls += 1 + + async def updates() -> AsyncIterator[ChatResponseUpdate]: + yield ChatResponseUpdate(role="assistant", contents=[self.approval]) + + return ResponseStream(updates(), finalizer=ChatResponse.from_updates) + + +class UnlayeredClient(BaseChatClient[Any]): + STORES_BY_DEFAULT = True + + def __init__(self) -> None: + super().__init__() + self.kwargs: list[dict[str, Any]] = [] + + def _inner_get_response( + self, + *, + messages: Sequence[Message], + stream: bool, + options: Mapping[str, Any], + **kwargs: Any, + ) -> Awaitable[ChatResponse] | ResponseStream[ChatResponseUpdate, ChatResponse]: + del messages, options + self.kwargs.append(dict(kwargs)) + + async def updates() -> AsyncIterator[ChatResponseUpdate]: + yield ChatResponseUpdate(role="assistant", contents=[Content.from_text("done")], conversation_id="service") + + async def response() -> ChatResponse: + return ChatResponse(messages=[Message("assistant", "done")], conversation_id="service") + + return ResponseStream(updates(), finalizer=ChatResponse.from_updates) if stream else response() + + +class GatedApprovalStore(SqliteSessionStore): + def __init__(self, path: Path, *, fail_alias: bool = False) -> None: + super().__init__(path) + self.started = asyncio.Event() + self.release = asyncio.Event() + self.fail_alias = fail_alias + + async def compare_and_set(self, session_id: str, session: AgentSession, *, expected_revision: str | None) -> str: + if session_id.startswith("__foundry_agent_approval/") and expected_revision is None: + self.started.set() + await self.release.wait() + return await super().compare_and_set(session_id, session, expected_revision=expected_revision) + + async def set(self, session_id: str, session: AgentSession) -> None: + if self.fail_alias: + raise RuntimeError("response session snapshot failed") + await super().set(session_id, session) + + +class GatedClaimStore(SqliteSessionStore): + def __init__(self, path: Path) -> None: + super().__init__(path) + self.started = asyncio.Event() + self.release = asyncio.Event() + self.claims = 0 + + async def compare_and_set(self, session_id: str, session: AgentSession, *, expected_revision: str | None) -> str: + if session_id.startswith("__foundry_agent_approval/") and expected_revision is not None: + self.claims += 1 + if self.claims == 2: + self.started.set() + await self.release.wait() + return await super().compare_and_set(session_id, session, expected_revision=expected_revision) + + +class GatedRequestRead: + def __init__(self) -> None: + self.started = asyncio.Event() + self.stopped = asyncio.Event() + + async def load(self) -> list[Any]: + self.started.set() + try: + await asyncio.Event().wait() + finally: + self.stopped.set() + return [] + + +class GatedSessionLoadStore(SessionStore): + def __init__(self, request_started: asyncio.Event) -> None: + super().__init__() + self.request_started = request_started + self.started = asyncio.Event() + self.stopped = asyncio.Event() + + async def get(self, session_id: str) -> AgentSession | None: + del session_id + await self.request_started.wait() + self.started.set() + try: + await asyncio.Event().wait() + finally: + self.stopped.set() + return None + + +class GatedAgentStream: + def __init__(self) -> None: + self.started = asyncio.Event() + self.release = asyncio.Event() + self.stopped = asyncio.Event() + + async def updates(self) -> AsyncIterator[AgentResponseUpdate]: + self.started.set() + try: + await self.release.wait() + yield AgentResponseUpdate(role="assistant", contents=[Content.from_text("too late")]) + finally: + self.stopped.set() + + +async def collect_host_events(source: AsyncIterator[Any], events: list[Any]) -> None: + async for event in source: + events.append(event) + + +class StatefulConsentClient(FunctionInvocationLayer[Any], ChatMiddlewareLayer[Any], BaseChatClient[Any]): + """Mimic a service-backed conversation with one settled and one consent batch.""" + + STORES_BY_DEFAULT = True + + def __init__(self, tool_names: Sequence[str]) -> None: + super().__init__() + self.tool_names = list(tool_names) + self.calls: list[list[Message]] = [] + self.options: list[dict[str, Any]] = [] + + def _inner_get_response( + self, + *, + messages: Sequence[Message], + stream: bool, + options: Mapping[str, Any], + **kwargs: Any, + ) -> Awaitable[ChatResponse] | ResponseStream[ChatResponseUpdate, ChatResponse]: + del kwargs + self.calls.append(list(messages)) + self.options.append(dict(options)) + if len(self.calls) == 1: + contents = [Content.from_function_call(call_id="old-0", name=self.tool_names[0], arguments="{}")] + elif len(self.calls) == 2: + contents = [ + Content.from_function_call(call_id=f"pending-{index}", name=name, arguments="{}") + for index, name in enumerate(self.tool_names) + ] + else: + contents = [Content.from_text("done")] + + async def updates() -> AsyncIterator[ChatResponseUpdate]: + yield ChatResponseUpdate( + role="assistant", contents=contents, conversation_id="provider-conversation", response_id="provider" + ) + + async def complete() -> ChatResponse: + return ChatResponse( + messages=[Message("assistant", contents=contents)], + conversation_id="provider-conversation", + response_id="provider", + ) + + return ResponseStream(updates(), finalizer=ChatResponse.from_updates) if stream else complete() diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py index 715811eea49..995ccf945cd 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py @@ -7,7 +7,7 @@ import logging from collections.abc import AsyncIterator, Awaitable, Callable, Mapping, MutableMapping, Sequence from typing import Any, cast -from unittest.mock import patch +from unittest.mock import AsyncMock, MagicMock, patch import httpx import pytest @@ -37,6 +37,13 @@ from agent_framework._workflows._const import RESOLVED_WORKFLOW_RUN_KWARGS_KEY, WORKFLOW_RUN_KWARGS_KEY from azure.ai.agentserver.responses import FileResponseStore, InMemoryResponseProvider from azure.ai.agentserver.responses._id_generator import IdGenerator +from azure.ai.agentserver.responses.models import ( + CreateResponse, + ItemReferenceParam, + MCPApprovalResponse, + OutputItem, + ResponseObject, +) from pydantic import BaseModel from agent_framework_foundry_hosting import ( @@ -47,6 +54,7 @@ ResponsesWorkflowHostServer, WorkflowTurn, ) +from agent_framework_foundry_hosting._responses_workflow import _load_replies, _WorkflowRequestError from agent_framework_foundry_hosting._workflow_state import FoundryWorkflowBindingStore, HostedWorkflowRun @@ -428,31 +436,166 @@ async def test_named_conversation_rejects_old_wire_replies_when_core_request_ids assert _texts(accepted) == ["new question:False", "new question:False"] -async def test_approval_wire_ids_bind_only_to_exact_pending_checkpoint() -> None: - server = _server(lambda request: _build(_Approvals()), parser=_parse_text) +@pytest.mark.parametrize("stream", [False, True]) +async def test_approval_wire_ids_bind_only_to_exact_pending_checkpoint(stream: bool) -> None: + provider = InMemoryResponseProvider() + server = _server(lambda request: _build(_Approvals()), parser=_parse_text, response_store=provider) first = await _post(server, "/safe") assert first["status"] == "completed", first wire_ids = [item["id"] for item in first["output"] if item["type"] == "mcp_approval_request"] assert len(wire_ids) == 2 full = [ - {"type": "mcp_approval_response", "approval_request_id": wire_ids[0], "approve": True}, - {"type": "mcp_approval_response", "approval_request_id": wire_ids[1], "approve": False}, + MCPApprovalResponse(type="mcp_approval_response", approval_request_id=wire_ids[0], approve=True), + MCPApprovalResponse(type="mcp_approval_response", approval_request_id=wire_ids[1], approve=False), ] - for replies in ( - full[:1], - [full[0], dict(full[0]), full[1]], - [{**full[0], "approval_request_id": "forged"}, full[1]], - ): - rejected = await _post(server, replies, previous_response_id=first["id"]) - assert rejected["status"] == "failed" - assert not rejected["output"] - wrong_scope = await _post(server, full, sandbox="other", previous_response_id=first["id"]) - assert wrong_scope["status"] == "failed" - completed = await _post(server, full, previous_response_id=first["id"]) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=server), base_url="http://test") as client: + with ( + patch.object(server._resolver, "resolve", wraps=server._resolver.resolve) as resolver, # pyright: ignore[reportPrivateUsage] + patch.object(server, "_parse_input", wraps=server._parse_input) as parser, # pyright: ignore[reportPrivateUsage] + ): + for replies, sandbox in ( + (full[:1], "sandbox"), + ([full[0], dict(full[0]), full[1]], "sandbox"), + ([{**full[0], "approval_request_id": "forged"}, full[1]], "sandbox"), + ([*full, {"type": "item_reference", "id": "missing-item"}], "sandbox"), + (full, "other"), + ): + rejected = await client.post( + "/responses", + headers={"x-agent-user-id": "user", "x-agent-foundry-call-id": "call"}, + json={ + "input": replies, + "agent_session_id": sandbox, + "previous_response_id": first["id"], + "stream": stream, + }, + ) + assert rejected.status_code == 400 + assert rejected.headers["content-type"].startswith("application/json") + assert rejected.headers["x-agent-session-id"] == sandbox + assert "response.created" not in rejected.text + for id_in_header in (True, False): + for replies in (full[:1], [full[0], full[0]]): + headers = {"x-agent-user-id": "user", "x-agent-foundry-call-id": "call"} + payload = { + "input": replies, + "agent_session_id": "sandbox", + "previous_response_id": first["id"], + "stream": stream, + } + if id_in_header: + headers["x-agent-response-id"] = first["id"] + else: + payload["response_id"] = first["id"] + redelivery = await client.post("/responses", headers=headers, json=payload) + assert redelivery.status_code == 400 + assert redelivery.headers["content-type"].startswith("application/json") + assert "response.created" not in redelivery.text + resolver.assert_not_called() + parser.assert_not_called() + direct_request = ResponsesRequest( + CreateResponse(input=[*full, ItemReferenceParam(type="item_reference", id="missing-item")]), + MagicMock(response_id="handler-revalidation", get_input_items=AsyncMock(return_value=full)), + MagicMock(spec=FoundryRequestScope), + {}, + ) + pending_run = MagicMock(spec=HostedWorkflowRun) + pending_run.pending_requests = {"first": object(), "second": object()} + with pytest.raises(_WorkflowRequestError, match="unresolved input references"): + await _load_replies(direct_request, pending_run) + + referenced_id = "resolved-decision" + await provider.create_response( + cast(ResponseObject, {**first, "id": "reference-seed", "output": []}), + [cast(OutputItem, {**full[0], "id": referenced_id})], + [], + ) + continuation_id = IdGenerator.new_response_id(first["id"]) + continuation = [{"type": "item_reference", "id": referenced_id}, full[1]] + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=server), base_url="http://test") as client: + accepted = await client.post( + "/responses", + headers={"x-agent-user-id": "user", "x-agent-foundry-call-id": "call"}, + json={ + "input": continuation, + "agent_session_id": "sandbox", + "previous_response_id": first["id"], + "response_id": continuation_id, + "stream": stream, + }, + ) + assert accepted.status_code == 200 + if stream: + events = [json.loads(line[6:]) for line in accepted.text.splitlines() if line.startswith("data: {")] + completed = next(event["response"] for event in events if event["type"] == "response.completed") + else: + completed = accepted.json() + assert completed["status"] == "completed", completed + assert completed["id"] == continuation_id + assert _texts(completed) == ["first:True", "second:False"] + + with ( + patch.object(server._resolver, "resolve", wraps=server._resolver.resolve) as resolver, # pyright: ignore[reportPrivateUsage] + patch.object(server, "_parse_input", wraps=server._parse_input) as parser, # pyright: ignore[reportPrivateUsage] + ): + for id_in_header in (True, False): + headers = {"x-agent-user-id": "user", "x-agent-foundry-call-id": "call"} + payload = { + "input": continuation, + "agent_session_id": "sandbox", + "previous_response_id": first["id"], + "stream": stream, + } + if id_in_header: + headers["x-agent-response-id"] = continuation_id + else: + payload["response_id"] = continuation_id + replay = await client.post("/responses", headers=headers, json=payload) + assert replay.status_code == 400 + assert replay.headers["content-type"].startswith("application/json") + assert "response.created" not in replay.text + resolver.assert_not_called() + parser.assert_not_called() + + +@pytest.mark.parametrize("stream", [False, True]) +async def test_named_conversation_rejects_new_input_while_approvals_are_pending(stream: bool) -> None: + server = _server(lambda request: _build(_Approvals()), parser=_parse_text) + conversation = IdGenerator.new_id("conv") + first = await _post(server, "/safe", conversation=conversation) + wire_ids = [item["id"] for item in first["output"] if item["type"] == "mcp_approval_request"] + assert len(wire_ids) == 2 + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=server), base_url="http://test") as client: + with ( + patch.object(server._resolver, "resolve", wraps=server._resolver.resolve) as resolver, # pyright: ignore[reportPrivateUsage] + patch.object(server, "_parse_input", wraps=server._parse_input) as parser, # pyright: ignore[reportPrivateUsage] + ): + for id_in_header in (None, True, False): + headers = {"x-agent-user-id": "user", "x-agent-foundry-call-id": "call"} + payload = { + "input": "a new request", + "agent_session_id": "sandbox", + "conversation": conversation, + "stream": stream, + } + if id_in_header is True: + headers["x-agent-response-id"] = first["id"] + elif id_in_header is False: + payload["response_id"] = first["id"] + rejected = await client.post("/responses", headers=headers, json=payload) + assert rejected.status_code == 400 + assert rejected.headers["content-type"].startswith("application/json") + assert "response.created" not in rejected.text + resolver.assert_not_called() + parser.assert_not_called() + + replies = [ + {"type": "mcp_approval_response", "approval_request_id": wire_id, "approve": index == 0} + for index, wire_id in enumerate(wire_ids) + ] + completed = await _post(server, replies, conversation=conversation) assert completed["status"] == "completed", completed assert _texts(completed) == ["first:True", "second:False"] - replay = await _post(server, full, previous_response_id=first["id"]) - assert replay["status"] == "failed" async def test_store_false_has_no_durable_native_state_and_cannot_pause() -> None: @@ -519,9 +662,7 @@ def create(request: ResponsesRequest) -> Workflow: (" / ", ""), ], ) -async def test_workflow_host_prefix_preserves_create_and_retrieval_routes( - stream: bool, prefix: str, path: str -) -> None: +async def test_workflow_host_prefix_preserves_create_and_retrieval_routes(stream: bool, prefix: str, path: str) -> None: server = _server(prefix=prefix) async with httpx.AsyncClient(transport=httpx.ASGITransport(app=server), base_url="http://test") as client: created = await client.post( @@ -916,6 +1057,32 @@ async def test_real_sdk_background_cancel_drains_suspended_executor_and_blocks_c assert record is not None and record.status == "blocked" +@pytest.mark.parametrize( + ("prefix", "path"), [("api/v1", "/api/v1"), (" /api/v1/ ", "/api/v1"), ("//api/v1/", "//api/v1")] +) +async def test_prefixed_workflow_background_cancel_uses_sdk_routes(prefix: str, path: str) -> None: + started, release, stopped = (asyncio.Event() for _ in range(3)) + server = _server(_progress_factory(started, release, stopped), parser=_parse_count, prefix=prefix) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=server), base_url="http://test") as client: + created = await client.post( + f"http://test{path}/responses", + json={"input": "2", "agent_session_id": "sandbox", "store": True, "background": True}, + ) + assert created.status_code == 200, created.text + response_id = created.json()["id"] + await asyncio.wait_for(started.wait(), 2) + cancelled = await client.post(f"http://test{path}/responses/{response_id}/cancel") + assert cancelled.status_code == 200, cancelled.text + await asyncio.wait_for(stopped.wait(), 2) + for _ in range(150): + fetched = await client.get(f"http://test{path}/responses/{response_id}") + if fetched.status_code == 200 and fetched.json()["status"] == "cancelled": + break + await asyncio.sleep(0.01) + assert fetched.status_code == 200, fetched.text + assert fetched.json()["status"] == "cancelled" + + async def test_real_sdk_raw_agent_cancel_closes_request_owned_client_in_trusted_context() -> None: from azure.ai.agentserver.core import get_request_context diff --git a/python/packages/foundry_hosting/tests/test_responses.py b/python/packages/foundry_hosting/tests/test_responses.py index 9902a7e5009..189792ca013 100644 --- a/python/packages/foundry_hosting/tests/test_responses.py +++ b/python/packages/foundry_hosting/tests/test_responses.py @@ -71,6 +71,8 @@ from azure.ai.agentserver.responses.models import ( CreateResponse, Item, + ItemReferenceParam, + MCPApprovalResponse, Metadata, OutputItem, ResponseIncompleteReason, @@ -85,10 +87,13 @@ from pydantic import TypeAdapter from agent_framework_foundry_hosting import ResponsesHostServer, ResponsesRequest +from agent_framework_foundry_hosting._approvals import SessionApprovalState from agent_framework_foundry_hosting._responses_shared import ( _INCOMPLETE_REASON_KEY, # pyright: ignore[reportPrivateUsage] _LATEST_CHECKPOINT_ID_KEY, # pyright: ignore[reportPrivateUsage] CONSENT_ERROR_CODE, + OAUTH_CONSENT_NOT_EXECUTED_RESULT, + OAUTH_CONSENT_REQUIRED_RESULT, ConsentError, _agent_response_updates, # pyright: ignore[reportPrivateUsage] _annotations_to_output_text, # pyright: ignore[reportPrivateUsage] @@ -109,7 +114,28 @@ from agent_framework_foundry_hosting._state_store import ( AgentSessionStoreProvider, FoundryAgentSessionStore, - FunctionApprovalStoreProvider, +) + +from .foundry_hosting.approval_helpers import SqliteSessionStore +from .foundry_hosting.responses_host_helpers import ( + ApprovalPublishingClient, + BackgroundAgentMiddleware, + BackgroundChatMiddleware, + BackgroundPollingClient, + GatedAgentStream, + GatedApprovalStore, + GatedClaimStore, + GatedRequestRead, + GatedSessionLoadStore, + StatefulConsentClient, + UnlayeredClient, + collect_host_events, +) +from .foundry_hosting.toolbox_consent_helpers import ( + CONSENT_LINK, + BatchToolCallClient, + ToolboxConsentServer, + consent_toolbox, ) _OPENAI_HTTPX = cast(Any, import_module(DefaultAsyncHttpxClient.__mro__[1].__module__.partition(".")[0])) @@ -1379,6 +1405,34 @@ async def test_agent_host_prefix_preserves_response_routes(stream: bool) -> None assert (await client.get(f"/api/v1/responses/{response_id}")).status_code == 404 +@pytest.mark.parametrize( + ("prefix", "path"), [("api/v1", "/api/v1"), (" /api/v1/ ", "/api/v1"), ("//api/v1/", "//api/v1")] +) +async def test_prefixed_agent_background_cancel_uses_sdk_routes(prefix: str, path: str) -> None: + gated = GatedAgentStream() + agent = _make_agent() + agent.run = MagicMock(side_effect=lambda **kwargs: ResponseStream(gated.updates())) + server = _make_server(agent, prefix=prefix) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=server), base_url="http://test") as client: + created = await client.post( + f"http://test{path}/responses", json={"input": "wait", "store": True, "background": True} + ) + assert created.status_code == 200, created.text + response_id = created.json()["id"] + await asyncio.wait_for(gated.started.wait(), 2) + cancelled = await client.post(f"http://test{path}/responses/{response_id}/cancel") + assert cancelled.status_code == 200, cancelled.text + await asyncio.wait_for(gated.stopped.wait(), 2) + for _ in range(150): + fetched = await client.get(f"http://test{path}/responses/{response_id}") + if fetched.status_code == 200 and fetched.json()["status"] == "cancelled": + break + await asyncio.sleep(0.01) + assert fetched.status_code == 200, fetched.text + assert fetched.json()["status"] == "cancelled" + assert "too late" not in fetched.text + + @pytest.mark.parametrize("stream", [False, True]) @pytest.mark.parametrize("metadata", [None, {}, {"foo": "bar", "view": "concise"}]) async def test_request_metadata_is_returned_and_stored(stream: bool, metadata: dict[str, str] | None) -> None: @@ -1628,11 +1682,12 @@ class TestResponsesHostServerInit: ) def test_removed_host_setting_fails_before_sdk_or_agent_mutation(self, name: str) -> None: agent = _make_agent() + kwargs: dict[str, Any] = {name: None} with ( patch("azure.ai.agentserver.responses.hosting.ResponsesAgentServerHost.__init__") as initialize, pytest.raises(TypeError, match=name), ): - ResponsesHostServer(agent, **{name: None}) + ResponsesHostServer(agent, **kwargs) initialize.assert_not_called() assert agent.context_providers == [] assert agent.default_options == {} @@ -1673,9 +1728,7 @@ def test_history_limit_is_an_explicit_host_managed_override(self) -> None: @pytest.mark.parametrize("env", [None, "0", "3"]) @pytest.mark.parametrize("explicit", [None, 5]) - def test_heartbeat_precedence( - self, monkeypatch: pytest.MonkeyPatch, env: str | None, explicit: int | None - ) -> None: + def test_heartbeat_precedence(self, monkeypatch: pytest.MonkeyPatch, env: str | None, explicit: int | None) -> None: if env is None: monkeypatch.delenv("SSE_KEEPALIVE_INTERVAL", raising=False) else: @@ -1739,10 +1792,7 @@ def test_init_uses_default_store_providers(self) -> None: server._session_storage_provider, # pyright: ignore[reportPrivateUsage] AgentSessionStoreProvider, ) - assert isinstance( - server._function_approval_storage_provider, # pyright: ignore[reportPrivateUsage] - FunctionApprovalStoreProvider, - ) + assert not hasattr(server, "_function_approval_storage_provider") def test_init_rejects_history_provider_with_load_messages(self) -> None: @@ -1981,6 +2031,181 @@ async def test_previous_response_requires_existing_agent_session(self) -> None: agent.run.assert_not_called() agent.create_session.assert_not_called() + @pytest.mark.parametrize("stream", [False, True]) + @pytest.mark.parametrize("kind", ["agent", "chat"]) + @pytest.mark.parametrize("nested", [False, True]) + @pytest.mark.parametrize("in_kwargs", [False, True]) + async def test_middleware_cannot_enable_provider_background_on_foreground( + self, stream: bool, kind: str, nested: bool, in_kwargs: bool + ) -> None: + client = StatefulConsentClient(["tool"]) + middleware = ( + BackgroundAgentMiddleware(nested=nested, in_kwargs=in_kwargs) + if kind == "agent" + else BackgroundChatMiddleware(nested=nested, in_kwargs=in_kwargs) + ) + agent = Agent(client=client, middleware=[middleware]) + server = _make_server(agent, history_source="inference_service") + + response = await _post(server, stream=stream) + + assert response.status_code == 200 + if stream: + assert "response.failed" in _sse_event_types(_parse_sse_events(response.text)) + else: + assert response.json()["status"] == "failed" + assert client.calls == [] + + @pytest.mark.parametrize("kind", ["agent", "chat"]) + @pytest.mark.parametrize("nested", [False, True]) + @pytest.mark.parametrize("in_kwargs", [False, True]) + async def test_middleware_cannot_disable_selected_provider_background( + self, kind: str, nested: bool, in_kwargs: bool + ) -> None: + client = StatefulConsentClient(["tool"]) + middleware = ( + BackgroundAgentMiddleware(nested=nested, value=False, in_kwargs=in_kwargs) + if kind == "agent" + else BackgroundChatMiddleware(nested=nested, value=False, in_kwargs=in_kwargs) + ) + agent = Agent(client=client, middleware=[middleware]) + server = _make_server( + agent, + session_store=SessionStore(), + history_source="inference_service", + background_source="inference_service", + ) + request = CreateResponse(input="hello", store=True, background=True) + context = ResponseContext(response_id="outer-response", mode_flags=MagicMock()) + with patch.object(ResponseContext, "get_input_items", new=AsyncMock(return_value=[])): + events = [event async for event in server._handle_response(request, context, asyncio.Event())] + + assert any(isinstance(event, Mapping) and event.get("type") == "response.failed" for event in events) + assert client.calls == [] + + @pytest.mark.parametrize("kind", ["agent", "chat"]) + @pytest.mark.parametrize("in_kwargs", [False, True]) + async def test_middleware_cannot_disable_provider_background_on_poll(self, kind: str, in_kwargs: bool) -> None: + client = BackgroundPollingClient() + middleware = ( + BackgroundAgentMiddleware(nested=False, value=False, in_kwargs=in_kwargs, on_poll=True) + if kind == "agent" + else BackgroundChatMiddleware(nested=False, value=False, in_kwargs=in_kwargs, on_poll=True) + ) + agent = Agent(client=client, middleware=[middleware]) + server = _make_server( + agent, + session_store=SessionStore(), + history_source="inference_service", + background_source="inference_service", + ) + request = CreateResponse(input="hello", store=True, background=True) + context = ResponseContext(response_id="outer-response", mode_flags=MagicMock()) + with ( + patch.object(ResponseContext, "get_input_items", new=AsyncMock(return_value=[])), + patch("agent_framework_foundry_hosting._responses_agent.asyncio.sleep", new=AsyncMock()), + ): + events = [event async for event in server._handle_response(request, context, asyncio.Event())] + + assert any(isinstance(event, Mapping) and event.get("type") == "response.failed" for event in events) + assert len(client.calls) == 1 + assert client.calls[0]["background"] is True + assert agent.middleware == [middleware] + assert not client.chat_middleware + + async def test_provider_background_guard_allows_submit_and_poll_without_mutating_agent(self) -> None: + client = BackgroundPollingClient() + agent = Agent(client=client) + server = _make_server( + agent, + session_store=SessionStore(), + history_source="inference_service", + background_source="inference_service", + ) + request = CreateResponse(input="hello", store=True, background=True) + context = ResponseContext(response_id="outer-response", mode_flags=MagicMock()) + with ( + patch.object(ResponseContext, "get_input_items", new=AsyncMock(return_value=[])), + patch("agent_framework_foundry_hosting._responses_agent.asyncio.sleep", new=AsyncMock()), + ): + events = [event async for event in server._handle_response(request, context, asyncio.Event())] + + assert any(isinstance(event, Mapping) and event.get("type") == "response.completed" for event in events) + assert [call["background"] for call in client.calls] == [True, True] + assert client.calls[1]["continuation_token"] == {"response_id": "provider-token"} + assert not agent.middleware + assert not client.chat_middleware + + @pytest.mark.parametrize("provider_background", [False, True]) + async def test_raw_agent_client_chat_middleware_cannot_override_background(self, provider_background: bool) -> None: + client = StatefulConsentClient(["tool"]) + middleware = BackgroundChatMiddleware(nested=False, value=not provider_background) + client.chat_middleware.append(middleware) + agent = RawAgent(client=client) + server = _make_server( + agent, + session_store=SessionStore(), + history_source="inference_service", + background_source="inference_service" if provider_background else "host_managed", + ) + request = CreateResponse(input="hello", store=True, background=provider_background) + context = ResponseContext(response_id="outer-response", mode_flags=MagicMock()) + with patch.object(ResponseContext, "get_input_items", new=AsyncMock(return_value=[])): + events = [event async for event in server._handle_response(request, context, asyncio.Event())] + + assert any(isinstance(event, Mapping) and event.get("type") == "response.failed" for event in events) + assert client.calls == [] + assert client.chat_middleware == [middleware] + + @pytest.mark.parametrize("stream", [False, True]) + async def test_middleware_failure_after_approval_claim_does_not_restore_authority( + self, stream: bool, tmp_path: Path + ) -> None: + client = ApprovalPublishingClient(_make_function_approval_request_content()) + agent = Agent(client=client, middleware=[]) + server = _make_server(agent, session_store=SqliteSessionStore(tmp_path / "middleware-approval.sqlite")) + first = await _post(server) + approval_id = next(item["id"] for item in first.json()["output"] if item["type"] == "mcp_approval_request") + agent.middleware = [BackgroundAgentMiddleware(nested=False)] + payload = { + "input": [{"type": "mcp_approval_response", "approval_request_id": approval_id, "approve": True}], + "previous_response_id": first.json()["id"], + "stream": stream, + } + + rejected = await _post_json(server, payload) + + assert rejected.status_code == 200 + if stream: + assert "response.failed" in _sse_event_types(_parse_sse_events(rejected.text)) + else: + assert rejected.json()["status"] == "failed" + assert client.calls == 1 + replay = await _post_json(server, payload) + assert replay.status_code == 400 + assert client.calls == 1 + + @pytest.mark.parametrize("provider_background", [False, True]) + @pytest.mark.parametrize("layered_agent", [False, True]) + async def test_unlayered_clients_receive_no_middleware_kwarg( + self, provider_background: bool, layered_agent: bool + ) -> None: + client = UnlayeredClient() + agent = Agent(client=client) if layered_agent else RawAgent(client=client) + server = _make_server( + agent, + history_source="inference_service", + background_source="inference_service" if provider_background else "host_managed", + ) + request = CreateResponse(input="hello", store=True, background=provider_background) + context = ResponseContext(response_id="unlayered-response", mode_flags=MagicMock()) + with patch.object(ResponseContext, "get_input_items", new=AsyncMock(return_value=[])): + events = [event async for event in server._handle_response(request, context, asyncio.Event())] + + assert any(isinstance(event, Mapping) and event.get("type") == "response.completed" for event in events) + assert client.kwargs + assert all("middleware" not in kwargs for kwargs in client.kwargs) + # endregion @@ -2277,8 +2502,8 @@ async def test_invalid_approval_does_not_consume_service_parent(self) -> None: }, ) - assert invalid.json()["status"] == "failed" - assert "unknown-approval" in invalid.json()["error"]["message"] + assert invalid.status_code == 400 + assert "No pending approval batch" in invalid.json()["error"]["message"] parent = await store.get(parent_id) assert parent is not None and "_foundry_service_child" not in parent.state assert len(client.calls) == 1 @@ -2318,8 +2543,6 @@ async def test_store_false_neither_saves_session_nor_stores_inner_response(self, agent = Agent(client=client, default_options=OpenAIChatOptions(store=True)) store = SessionStore() server = _make_server(agent, session_store=store, history_source=mode) - approvals = MagicMock(spec=FunctionApprovalStoreProvider) - server._function_approval_storage_provider = approvals # pyright: ignore[reportPrivateUsage] response = await _post_json(server, {"input": "one shot", "store": False, "model": "test-model"}) @@ -2330,7 +2553,6 @@ async def test_store_false_neither_saves_session_nor_stores_inner_response(self, assert agent.default_options["store"] is True provider = cast(MagicMock, server._session_storage_provider) # pyright: ignore[reportPrivateUsage] provider.get_store.assert_not_called() - approvals.get_store.assert_not_called() async def test_store_false_rejects_external_history_and_custom_agent(self) -> None: history = _PerServiceCallHistoryProvider() @@ -8267,10 +8489,11 @@ class TestFunctionApprovalRoundTrip: `function_approval_response` content delivered to the agent. """ - async def test_non_streaming_emits_mcp_approval_request_and_persists_to_storage(self) -> None: + async def test_non_streaming_emits_mcp_approval_request_and_persists_to_storage(self, tmp_path: Path) -> None: request_content = _make_function_approval_request_content() agent = _make_agent(response=AgentResponse(messages=[Message(role="assistant", contents=[request_content])])) - server = _make_server(agent) + store = SqliteSessionStore(tmp_path / "approvals.sqlite") + server = _make_server(agent, session_store=store) resp = await _post(server, stream=False) @@ -8284,15 +8507,17 @@ async def test_non_streaming_emits_mcp_approval_request_and_persists_to_storage( assert approval_items[0]["server_label"] == "my_server" # Storage must contain a saved entry under the emitted request id. - loaded = await server._function_approval_storage_provider.get_store( # pyright: ignore[reportPrivateUsage] - config=server.config, platform_context=get_request_context() - ).load_approval_request(approval_request_id) + session = await store.get(body["id"]) + assert session is not None + loaded = await SessionApprovalState(session, store).load_approval_request(approval_request_id) assert loaded.type == "function_approval_request" assert loaded.function_call is not None assert loaded.function_call.name == "delete_file" @pytest.mark.parametrize("with_preamble", [False, True]) - async def test_streaming_emits_mcp_approval_request_and_persists_to_storage(self, with_preamble: bool) -> None: + async def test_streaming_emits_mcp_approval_request_and_persists_to_storage( + self, with_preamble: bool, tmp_path: Path + ) -> None: request_content = _make_function_approval_request_content(request_id="apr_streaming") updates: list[AgentResponseUpdate] = [] preambles = ("Checking the refund policy.", "The refund requires approval.") @@ -8319,7 +8544,8 @@ async def test_streaming_emits_mcp_approval_request_and_persists_to_storage(self ) updates.append(AgentResponseUpdate(contents=[request_content], role="assistant")) agent = _make_agent(stream_updates=updates) - server = _make_server(agent) + store = SqliteSessionStore(tmp_path / "approvals.sqlite") + server = _make_server(agent, session_store=store) resp = await _post(server, stream=True) @@ -8344,12 +8570,13 @@ async def test_streaming_emits_mcp_approval_request_and_persists_to_storage(self break assert approval_request_id is not None - loaded = await server._function_approval_storage_provider.get_store( # pyright: ignore[reportPrivateUsage] - config=server.config, platform_context=get_request_context() - ).load_approval_request(approval_request_id) + response_id = next(e["data"]["response"]["id"] for e in events if e["event"] == "response.completed") + session = await store.get(response_id) + assert session is not None + loaded = await SessionApprovalState(session, store).load_approval_request(approval_request_id) assert loaded.type == "function_approval_request" - async def test_round_trip_approval_response_reaches_agent(self) -> None: + async def test_round_trip_approval_response_reaches_agent(self, tmp_path: Path) -> None: """Two-turn: turn 1 emits an approval request; turn 2 sends an approval response and the agent receives a `function_approval_response`.""" request_content = _make_function_approval_request_content() @@ -8360,7 +8587,7 @@ async def test_round_trip_approval_response_reaches_agent(self) -> None: AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("done")])]), ] ) - server = _make_server(agent) + server = _make_server(agent, session_store=SqliteSessionStore(tmp_path / "approvals.sqlite")) first = await _post(server, stream=False) assert first.status_code == 200 @@ -8380,6 +8607,7 @@ async def test_round_trip_approval_response_reaches_agent(self) -> None: } ], "stream": False, + "previous_response_id": first_body["id"], } second = await _post_json(server, second_payload) assert second.status_code == 200 @@ -8395,7 +8623,7 @@ async def test_round_trip_approval_response_reaches_agent(self) -> None: assert approval_responses[0].approved is True assert approval_responses[0].function_call.name == "delete_file" - async def test_round_trip_approval_response_rejected(self) -> None: + async def test_round_trip_approval_response_rejected(self, tmp_path: Path) -> None: """Same as above but the user rejects the approval; the agent must receive `approved=False`.""" request_content = _make_function_approval_request_content() @@ -8406,7 +8634,7 @@ async def test_round_trip_approval_response_rejected(self) -> None: AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("ok")])]), ] ) - server = _make_server(agent) + server = _make_server(agent, session_store=SqliteSessionStore(tmp_path / "approvals.sqlite")) first = await _post(server, stream=False) approval_request_id = next( @@ -8425,6 +8653,7 @@ async def test_round_trip_approval_response_rejected(self) -> None: } ], "stream": False, + "previous_response_id": first.json()["id"], }, ) assert second.status_code == 200 @@ -8437,9 +8666,7 @@ async def test_round_trip_approval_response_rejected(self) -> None: assert approval_responses[0].approved is False async def test_approval_response_referencing_unknown_id_fails(self) -> None: - """Sending an `mcp_approval_response` for a request id that was - never persisted must surface as a ``response.failed`` event whose - ``error.message`` contains the missing approval request id.""" + """A response without pending session authority is rejected before execution.""" agent = _make_agent( response=AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("ok")])]) ) @@ -8459,15 +8686,411 @@ async def test_approval_response_referencing_unknown_id_fails(self) -> None: "stream": False, }, ) - # The handler converts the underlying KeyError into a terminal - # ``response.failed`` event, so non-streaming callers see HTTP 200 - # with status="failed" and a meaningful error message rather than - # a generic 5xx response. - assert resp.status_code == 200 - body = resp.json() - assert body["status"] == "failed" - error: dict[str, Any] = body.get("error") or {} - assert "apr_unknown" in (error.get("message") or "") + assert resp.status_code == 400 + agent.run.assert_not_called() + + @pytest.mark.parametrize("stream", [False, True]) + async def test_invalid_batches_are_rejected_before_headers_without_consuming_authority( + self, stream: bool, tmp_path: Path + ) -> None: + requests = [ + _make_function_approval_request_content(request_id=f"request-{index}", call_id=f"call-{index}") + for index in range(2) + ] + agent = _make_multi_response_agent([ + AgentResponse(messages=[Message(role="assistant", contents=requests)]), + AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("done")])]), + ]) + store = SqliteSessionStore(tmp_path / "approvals.sqlite") + response_store = InMemoryResponseProvider() + server = _make_server(agent, session_store=store, response_store=response_store) + first = await _post(server) + assert first.status_code == 200 + previous_id = first.json()["id"] + approval_ids = [item["id"] for item in first.json()["output"] if item["type"] == "mcp_approval_request"] + assert len(approval_ids) == 2 + decisions = [ + MCPApprovalResponse(type="mcp_approval_response", approval_request_id=approval_id, approve=index == 0) + for index, approval_id in enumerate(approval_ids) + ] + assert (await response_store.get_items([approval_ids[0]]))[0] is not None + invalid_inputs: list[Any] = [ + decisions[:1], + [decisions[0], decisions[0]], + [decisions[0], {**decisions[1], "approval_request_id": "foreign"}], + "continue", + [*decisions, {"type": "message", "role": "user", "content": "extra"}], + [*decisions, {"type": "item_reference", "id": approval_ids[0]}], + [*decisions, {"type": "item_reference", "id": "missing-item"}], + [{"type": "item_reference", "id": "missing-item"}], + ] + for invalid_input in invalid_inputs: + response = await _post_json( + server, + {"input": invalid_input, "previous_response_id": previous_id, "stream": stream}, + ) + assert response.status_code == 400, response.text + assert response.headers["content-type"].startswith("application/json") + assert response.headers["x-platform-error-source"] == "user" + assert "response.created" not in response.text + assert agent.run.call_count == 1 + + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=server), base_url="http://test") as client: + for id_in_header in (True, False): + for invalid_input in (decisions[:1], [decisions[0], decisions[0]]): + payload = {"input": invalid_input, "previous_response_id": previous_id, "stream": stream} + headers = {"x-agent-response-id": previous_id} if id_in_header else {} + if not id_in_header: + payload["response_id"] = previous_id + redelivery = await client.post("/responses", headers=headers, json=payload) + assert redelivery.status_code == 400 + assert redelivery.headers["content-type"].startswith("application/json") + assert "response.created" not in redelivery.text + assert agent.run.call_count == 1 + + rejected_store = await _post_json( + server, + {"input": decisions, "previous_response_id": previous_id, "stream": stream, "store": False}, + ) + assert rejected_store.status_code == 400, rejected_store.text + assert rejected_store.headers["content-type"].startswith("application/json") + assert agent.run.call_count == 1 + + direct_request = CreateResponse( + input=[*decisions, ItemReferenceParam(type="item_reference", id="missing-item")], + previous_response_id=previous_id, + ) + direct_context = ResponseContext( + response_id="handler-revalidation", + mode_flags=MagicMock(), + request=direct_request, + previous_response_id=previous_id, + provider=response_store, + ) + with patch.object(ResponseContext, "get_input_items", new=AsyncMock(return_value=decisions)): + direct_events = [ + event async for event in server._handle_response(direct_request, direct_context, asyncio.Event()) + ] + assert any( + isinstance(event, Mapping) + and event.get("type") == "response.failed" + and "Pending MCP approvals cannot be mixed" in str(event) + for event in direct_events + ) + assert agent.run.call_count == 1 + + referenced_id = "resolved-decision" + await response_store.create_response( + cast(ResponseObject, {**first.json(), "id": "reference-seed", "output": []}), + [cast(OutputItem, {**decisions[0], "id": referenced_id})], + [], + ) + continuation_id = IdGenerator.new_response_id(previous_id) + continuation = { + "input": [decisions[1], {"type": "item_reference", "id": referenced_id}], + "previous_response_id": previous_id, + "stream": stream, + } + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=server), base_url="http://test") as client: + accepted = await client.post( + "/responses", headers={"x-agent-response-id": continuation_id}, json=continuation + ) + assert accepted.status_code == 200, accepted.text + if stream: + events = _parse_sse_events(accepted.text) + completed = next(event["data"]["response"] for event in events if event["event"] == "response.completed") + else: + completed = accepted.json() + assert completed["status"] == "completed" + assert completed["id"] == continuation_id + received = [ + content.approved + for message in agent.run.call_args.kwargs["messages"] + for content in message.contents + if content.type == "function_approval_response" + ] + assert received == [False, True] + replay = await _post_json(server, {"input": decisions, "previous_response_id": previous_id, "stream": stream}) + assert replay.status_code == 400 + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=server), base_url="http://test") as client: + for id_in_header in (True, False): + payload = dict(continuation) + headers = {"x-agent-response-id": continuation_id} if id_in_header else {} + if not id_in_header: + payload["response_id"] = continuation_id + redelivery = await client.post("/responses", headers=headers, json=payload) + assert redelivery.status_code == 400 + assert redelivery.headers["content-type"].startswith("application/json") + assert "response.created" not in redelivery.text + assert agent.run.call_count == 2 + + @pytest.mark.parametrize("platform_error", [False, True]) + async def test_backend_value_error_is_not_mapped_to_invalid_approval( + self, platform_error: bool, tmp_path: Path + ) -> None: + from azure.ai.agentserver.responses.hosting._validation import tag_platform_error + + request = _make_function_approval_request_content() + agent = _make_agent(response=AgentResponse(messages=[Message(role="assistant", contents=[request])])) + store = SqliteSessionStore(tmp_path / "approvals.sqlite") + server = _make_server(agent, session_store=store) + first = await _post(server) + previous_id = first.json()["id"] + approval_id = next(item["id"] for item in first.json()["output"] if item["type"] == "mcp_approval_request") + session = await store.get(previous_id) + assert session is not None + error = ValueError(_SESSION_STORAGE_ERROR_DETAIL) + if platform_error: + tag_platform_error(error) + with ( + patch.object(store, "get", new=AsyncMock(return_value=session)), + patch.object(store, "get_with_revision", new=AsyncMock(side_effect=error)), + ): + response = await _post_json( + server, + { + "input": [{"type": "mcp_approval_response", "approval_request_id": approval_id, "approve": True}], + "previous_response_id": previous_id, + "stream": True, + }, + ) + assert response.status_code == 500 + assert response.headers["x-platform-error-source"] == ("platform" if platform_error else "upstream") + assert _SESSION_STORAGE_ERROR_DETAIL not in response.text + assert _SESSION_STORAGE_ERROR_DETAIL not in str(response.headers) + assert agent.run.call_count == 1 + + @pytest.mark.parametrize("fail_alias", [False, True]) + async def test_approval_events_wait_for_authority_and_session_snapshots( + self, fail_alias: bool, tmp_path: Path + ) -> None: + approval = _make_function_approval_request_content() + agent = _make_agent(stream_updates=[AgentResponseUpdate(contents=[approval], role="assistant")]) + store = GatedApprovalStore(tmp_path / "gated.sqlite", fail_alias=fail_alias) + server = _make_server(agent, session_store=store) + context = ResponseContext(response_id="response-gated", mode_flags=MagicMock()) + events: list[Any] = [] + task = asyncio.create_task( + collect_host_events( + cast(AsyncIterator[Any], server._handle_response(CreateResponse(input="go"), context, asyncio.Event())), + events, + ) + ) + try: + await asyncio.wait_for(store.started.wait(), 5) + assert "mcp_approval_request" not in str(events) + assert await store.get("response-gated") is None + store.release.set() + await asyncio.wait_for(task, 5) + finally: + store.release.set() + if not task.done(): + task.cancel() + with suppress(asyncio.CancelledError): + await task + + if fail_alias: + assert "mcp_approval_request" not in str(events) + assert any(event.get("type") == "response.failed" for event in events) + else: + assert any( + event.get("type") == "response.output_item.added" and event["item"]["type"] == "mcp_approval_request" + for event in events + ) + assert await store.get("response-gated") is not None + + async def test_background_approval_checkpoint_waits_for_durable_authority(self, tmp_path: Path) -> None: + approval = _make_function_approval_request_content() + agent = _make_agent() + agent.client.STORES_BY_DEFAULT = True + agent.run = AsyncMock( + side_effect=[ + AgentResponse(messages=[], continuation_token=OpenAIContinuationToken(response_id="provider-token")), + AgentResponse(messages=[Message(role="assistant", contents=[approval])]), + ] + ) + store = GatedApprovalStore(tmp_path / "background-approval.sqlite") + server = _make_server( + agent, + session_store=store, + history_source="inference_service", + background_source="inference_service", + enable_background_recovery=True, + response_store=FileResponseStore(storage_dir=tmp_path), + ) + context = ResponseContext(response_id="background-approval", mode_flags=MagicMock()) + request = CreateResponse(input="go", store=True, background=True) + events: list[Any] = [] + with ( + patch.object(ResponseContext, "get_input_items", new=AsyncMock(return_value=[])), + patch("agent_framework_foundry_hosting._responses_agent.asyncio.sleep", new=AsyncMock()), + ): + task = asyncio.create_task( + collect_host_events( + cast(AsyncIterator[Any], server._handle_response(request, context, asyncio.Event())), + events, + ) + ) + try: + await asyncio.wait_for(store.started.wait(), timeout=5) + assert "mcp_approval_request" not in str(events) + assert not any(isinstance(event, ResponseCheckpointEvent) for event in events) + private_snapshot = await store.get("background-approval") + assert private_snapshot is not None + assert private_snapshot.state["_foundry_provider_background"]["completed"] is True + store.release.set() + await asyncio.wait_for(task, timeout=5) + finally: + store.release.set() + if not task.done(): + task.cancel() + await asyncio.gather(task, return_exceptions=True) + + assert any(isinstance(event, ResponseCheckpointEvent) for event in events) + assert any( + isinstance(event, Mapping) + and event.get("type") == "response.output_item.added" + and event["item"]["type"] == "mcp_approval_request" + for event in events + ) + final_snapshot = await store.get("background-approval") + assert final_snapshot is not None + assert any("approval" in key for key in final_snapshot.state) + + @pytest.mark.parametrize("stream", [False, True]) + async def test_concurrent_continuations_only_dispatch_one_claim(self, stream: bool, tmp_path: Path) -> None: + approval = _make_function_approval_request_content() + agent = _make_multi_response_agent([ + AgentResponse(messages=[Message(role="assistant", contents=[approval])]), + AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("done")])]), + ]) + store = GatedClaimStore(tmp_path / "race.sqlite") + server = _make_server(agent, session_store=store) + first = await _post(server) + approval_id = next(item["id"] for item in first.json()["output"] if item["type"] == "mcp_approval_request") + payload = { + "input": [{"type": "mcp_approval_response", "approval_request_id": approval_id, "approve": True}], + "previous_response_id": first.json()["id"], + "stream": stream, + } + tasks = [asyncio.create_task(_post_json(server, payload)) for _ in range(2)] + try: + await asyncio.wait_for(store.started.wait(), 5) + assert agent.run.call_count == 1 + store.release.set() + responses = await asyncio.wait_for(asyncio.gather(*tasks), 5) + finally: + store.release.set() + for task in tasks: + if not task.done(): + task.cancel() + await asyncio.gather(*tasks, return_exceptions=True) + + assert agent.run.call_count == 2 + if stream: + terminals = [ + next( + event["event"] + for event in _parse_sse_events(response.text) + if event["event"] in {"response.completed", "response.failed"} + ) + for response in responses + ] + assert sorted(terminals) == ["response.completed", "response.failed"] + else: + assert sorted(response.json()["status"] for response in responses) == ["completed", "failed"] + + @pytest.mark.parametrize("cancelled", [False, True]) + async def test_lost_claim_ack_does_not_dispatch_or_reopen_approval(self, cancelled: bool, tmp_path: Path) -> None: + approval = _make_function_approval_request_content() + agent = _make_agent(response=AgentResponse(messages=[Message(role="assistant", contents=[approval])])) + store = SqliteSessionStore(tmp_path / "lost-ack.sqlite") + server = _make_server(agent, session_store=store) + first = await _post(server) + approval_id = next(item["id"] for item in first.json()["output"] if item["type"] == "mcp_approval_request") + payload = { + "input": [{"type": "mcp_approval_response", "approval_request_id": approval_id, "approve": True}], + "previous_response_id": first.json()["id"], + } + store.error_after_commit = ( + asyncio.CancelledError() if cancelled else RuntimeError("claim acknowledged unsuccessfully") + ) + if cancelled: + with pytest.raises(asyncio.CancelledError): + await _post_json(server, payload) + else: + failed = await _post_json(server, payload) + assert failed.status_code == 200 + assert failed.json()["status"] == "failed" + assert agent.run.call_count == 1 + store.error_after_commit = None + replay = await _post_json(server, payload) + assert replay.status_code == 400 + assert agent.run.call_count == 1 + + @pytest.mark.parametrize("stream", [False, True]) + async def test_approval_is_isolated_by_platform_user(self, stream: bool, tmp_path: Path) -> None: + approval = _make_function_approval_request_content() + agent = _make_multi_response_agent([ + AgentResponse(messages=[Message(role="assistant", contents=[approval])]), + AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("done")])]), + ]) + stores = { + "owner": SqliteSessionStore(tmp_path / "owner.sqlite"), + "other": SqliteSessionStore(tmp_path / "other.sqlite"), + } + provider = MagicMock(spec=AgentSessionStoreProvider) + provider.get_store.side_effect = lambda **kwargs: stores[kwargs["platform_context"].user_id] + server = _make_server(agent, agent_session_store_provider=provider) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=server), base_url="http://test") as client: + first = await client.post("/responses", json={"input": "go"}, headers={"x-agent-user-id": "owner"}) + assert first.status_code == 200, first.text + approval_id = next(item["id"] for item in first.json()["output"] if item["type"] == "mcp_approval_request") + payload = { + "input": [{"type": "mcp_approval_response", "approval_request_id": approval_id, "approve": True}], + "previous_response_id": first.json()["id"], + "stream": stream, + } + denied = await client.post("/responses", json=payload, headers={"x-agent-user-id": "other"}) + assert denied.status_code == 400, denied.text + assert denied.headers["content-type"].startswith("application/json") + assert agent.run.call_count == 1 + accepted = await client.post("/responses", json=payload, headers={"x-agent-user-id": "owner"}) + assert accepted.status_code == 200, accepted.text + if stream: + assert "response.completed" in _sse_event_types(_parse_sse_events(accepted.text)) + else: + assert accepted.json()["status"] == "completed" + assert agent.run.call_count == 2 + + @pytest.mark.parametrize("stream", [False, True]) + async def test_conversation_and_response_aliases_share_approval_authority( + self, stream: bool, tmp_path: Path + ) -> None: + approval = _make_function_approval_request_content() + agent = _make_multi_response_agent([ + AgentResponse(messages=[Message(role="assistant", contents=[approval])]), + AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("done")])]), + ]) + server = _make_server(agent, session_store=SqliteSessionStore(tmp_path / "aliases.sqlite")) + conversation_id = IdGenerator.new_id("conv") + first = await _post_json(server, {"input": "go", "conversation": conversation_id}) + assert first.status_code == 200, first.text + previous_id = first.json()["id"] + approval_id = next(item["id"] for item in first.json()["output"] if item["type"] == "mcp_approval_request") + decision = [{"type": "mcp_approval_response", "approval_request_id": approval_id, "approve": True}] + + invalid = await _post_json(server, {"input": "continue", "conversation": conversation_id, "stream": stream}) + assert invalid.status_code == 400 + accepted = await _post_json(server, {"input": decision, "conversation": conversation_id, "stream": stream}) + assert accepted.status_code == 200, accepted.text + if stream: + assert "response.completed" in _sse_event_types(_parse_sse_events(accepted.text)) + else: + assert accepted.json()["status"] == "completed" + replay = await _post_json(server, {"input": decision, "previous_response_id": previous_id, "stream": stream}) + assert replay.status_code == 400 + assert agent.run.call_count == 2 # endregion @@ -8478,6 +9101,178 @@ async def test_approval_response_referencing_unknown_id_fails(self) -> None: # region Agent lifecycle (lazy entry & OAuth consent surfacing) +@pytest.mark.xdist_group("session_isolation") +class TestToolboxConsentHost: + @pytest.mark.parametrize("stream", [False, True]) + async def test_consent_preserves_function_results_and_stored_continuation( + self, stream: bool, tmp_path: Path + ) -> None: + gateway = ToolboxConsentServer(["before", "secure", "after"]) + gateway.require_consent("secure") + async with consent_toolbox(gateway) as toolbox: + client = BatchToolCallClient([function.name for function in toolbox.functions]) + client.function_invocation_configuration["allow_concurrent_invocation"] = False # type: ignore[index] + agent = Agent(client=client, tools=toolbox, default_options=ChatOptions(allow_multiple_tool_calls=True)) + server = _make_server(agent, session_store=SqliteSessionStore(tmp_path / "consent.sqlite")) + + first = await _post(server, stream=stream) + assert first.status_code == 200, first.text + if stream: + events = _parse_sse_events(first.text) + response = next( + event["data"]["response"] for event in events if event["event"] == "response.incomplete" + ) + else: + response = first.json() + assert response["status"] == "incomplete" + outputs = response["output"] + calls = [item for item in outputs if item["type"] == "function_call"] + results = [item for item in outputs if item["type"] == "function_call_output"] + consents = [item for item in outputs if item["type"] == "oauth_consent_request"] + assert len(calls) == len(results) == 3 + assert {item["call_id"] for item in calls} == {item["call_id"] for item in results} + assert len({item["call_id"] for item in results}) == 3 + by_call = {item["call_id"]: item["output"] for item in results} + assert "before-result" in str(by_call["call-0"]) + assert by_call["call-1"] == OAUTH_CONSENT_REQUIRED_RESULT + assert by_call["call-2"] == OAUTH_CONSENT_NOT_EXECUTED_RESULT + assert len(consents) == 1 + assert consents[0]["consent_link"] == CONSENT_LINK + assert gateway.calls == ["before", "secure"] + + gateway.consent_errors.clear() + second = await _post_json( + server, + {"input": "Consent granted", "previous_response_id": response["id"], "stream": stream}, + ) + assert second.status_code == 200, second.text + if stream: + assert "response.completed" in _sse_event_types(_parse_sse_events(second.text)) + else: + assert second.json()["status"] == "completed" + assert len(client.calls) == 2 + history_results = [ + content.call_id + for message in client.calls[1] + for content in message.contents + if content.type == "function_result" + ] + assert len(history_results) == 3 + assert set(history_results) == {"call-0", "call-1", "call-2"} + + @pytest.mark.parametrize("stream", [False, True]) + async def test_service_history_fails_on_invocation_time_consent_before_publication( + self, stream: bool, tmp_path: Path + ) -> None: + gateway = ToolboxConsentServer(["before", "secure", "after"]) + gateway.require_consent("secure") + async with consent_toolbox(gateway) as toolbox: + client = StatefulConsentClient([function.name for function in toolbox.functions]) + client.function_invocation_configuration["allow_concurrent_invocation"] = False # type: ignore[index] + agent = Agent(client=client, tools=toolbox, default_options=ChatOptions(allow_multiple_tool_calls=True)) + server = _make_server( + agent, + session_store=SqliteSessionStore(tmp_path / "service-consent.sqlite"), + history_source="inference_service", + ) + response = await _post(server, stream=stream) + assert response.status_code == 200, response.text + assert CONSENT_LINK not in response.text + assert "oauth_consent_request" not in response.text + assert ( + "Invocation-time OAuth consent is unsupported with history_source='inference_service'." in response.text + ) + if stream: + events = _parse_sse_events(response.text) + assert "response.failed" in _sse_event_types(events) + assert "response.incomplete" not in _sse_event_types(events) + else: + assert response.json()["status"] == "failed" + assert len(client.calls) == 2 + assert gateway.calls == ["before", "before", "secure"] + + @pytest.mark.parametrize("stream", [False, True]) + @pytest.mark.parametrize("background_source", ["host_managed", "inference_service"]) + async def test_service_history_background_fails_on_invocation_time_consent_before_publication( + self, stream: bool, background_source: str, tmp_path: Path + ) -> None: + gateway = ToolboxConsentServer(["before", "secure", "after"]) + gateway.require_consent("secure") + async with consent_toolbox(gateway) as toolbox: + client = StatefulConsentClient([function.name for function in toolbox.functions]) + client.function_invocation_configuration["allow_concurrent_invocation"] = False # type: ignore[index] + agent = Agent(client=client, tools=toolbox) + server = _make_server( + agent, + session_store=SqliteSessionStore(tmp_path / "background-consent.sqlite"), + history_source="inference_service", + background_source=background_source, + ) + request = CreateResponse(input="go", store=True, background=True, stream=stream) + context = ResponseContext(response_id="background-consent", mode_flags=MagicMock()) + with patch.object(ResponseContext, "get_input_items", new=AsyncMock(return_value=[])): + events = [event async for event in server._handle_response(request, context, asyncio.Event())] + + assert CONSENT_LINK not in str(events) + assert "oauth_consent_request" not in str(events) + assert "Invocation-time OAuth consent is unsupported with history_source='inference_service'." in str(events) + types = [event.get("type") for event in events if isinstance(event, Mapping)] + assert "response.failed" in types + assert "response.incomplete" not in types + assert gateway.calls == ["before", "before", "secure"] + + @pytest.mark.parametrize("stream", [False, True]) + async def test_new_store_false_consent_fails_without_exposing_continuation( + self, stream: bool, tmp_path: Path + ) -> None: + gateway = ToolboxConsentServer(["secure"]) + gateway.require_consent("secure") + async with consent_toolbox(gateway) as toolbox: + client = BatchToolCallClient([function.name for function in toolbox.functions]) + agent = Agent(client=client, tools=toolbox) + server = _make_server(agent, session_store=SqliteSessionStore(tmp_path / "consent.sqlite")) + response = await _post_json(server, {"input": "go", "store": False, "stream": stream}) + + assert response.status_code == 200 + assert CONSENT_LINK not in response.text + assert "oauth_consent_request" not in response.text + assert "requires store=true" in response.text + if stream: + events = _parse_sse_events(response.text) + assert "response.failed" in _sse_event_types(events) + else: + assert response.json()["status"] == "failed" + assert gateway.calls == ["secure"] + + @pytest.mark.parametrize("stream", [False, True]) + @pytest.mark.parametrize("link", [CONSENT_LINK, "http://consent.example.com/authorize?state=secret"]) + async def test_disallowed_consent_fails_without_exposing_link( + self, stream: bool, link: str, tmp_path: Path + ) -> None: + gateway = ToolboxConsentServer(["secure", "after"]) + gateway.require_consent("secure", message=f"Request failed (remote): {link}") + async with consent_toolbox(gateway) as toolbox: + client = BatchToolCallClient([function.name for function in toolbox.functions]) + client.function_invocation_configuration["allow_concurrent_invocation"] = False # type: ignore[index] + agent = Agent(client=client, tools=toolbox) + server = _make_server( + agent, + session_store=SqliteSessionStore(tmp_path / "rejected-consent.sqlite"), + allowed_oauth_consent_origins=["https://allowed.example.com"], + ) + response = await _post(server, stream=stream) + + assert response.status_code == 200 + assert link not in response.text + assert "oauth_consent_request" not in response.text + assert "OAuth consent link rejected" in response.text + if stream: + assert "response.failed" in _sse_event_types(_parse_sse_events(response.text)) + else: + assert response.json()["status"] == "failed" + assert gateway.calls == ["secure"] + + def _make_consent_error( url: str = "https://consent.example.com/auth", name: str = "Foundry Toolbox", @@ -8800,16 +9595,26 @@ async def test_explicit_none_origin_allowlist_accepts_any_safe_https_consent(sel oauth_items = [item for item in body["output"] if item["type"] == "oauth_consent_request"] assert [item["consent_link"] for item in oauth_items] == ["https://external.example/authorize"] - async def test_configured_origin_allowlist_accepts_connect_time_consent(self) -> None: + @pytest.mark.parametrize("history_source", ["host_managed", "inference_service"]) + @pytest.mark.parametrize("stream", [False, True]) + async def test_configured_origin_allowlist_accepts_connect_time_consent( + self, history_source: str, stream: bool + ) -> None: agent = _make_agent( response=AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("hi")])]) ) agent.__aenter__.side_effect = _make_consent_error("https://auth.example.com/authorize?state=1") - server = _make_server(agent, allowed_oauth_consent_origins=["https://auth.example.com"]) + agent.client.STORES_BY_DEFAULT = history_source == "inference_service" + server = _make_server( + agent, allowed_oauth_consent_origins=["https://auth.example.com"], history_source=history_source + ) - resp = await _post(server, input_text="hello", stream=False) + resp = await _post(server, input_text="hello", stream=stream) - assert resp.json()["status"] == "incomplete" + if stream: + assert "response.incomplete" in _sse_event_types(_parse_sse_events(resp.text)) + else: + assert resp.json()["status"] == "incomplete" async def test_configured_origin_allowlist_rejects_connect_time_consent( self, caplog: pytest.LogCaptureFixture @@ -9700,5 +10505,38 @@ async def _drain() -> list[Any]: # The in-flight input read must have been cancelled by the handler's cleanup, not orphaned. await asyncio.wait_for(sibling_cancelled.wait(), timeout=1) + async def test_session_preparation_cancellation_drains_reads_and_propagates(self) -> None: + reader = GatedRequestRead() + store = GatedSessionLoadStore(reader.started) + agent = _make_agent() + server = _make_server(agent, session_store=store) + request = CreateResponse(input="hi", previous_response_id="previous", stream=True) + context = ResponseContext(response_id="response-cancel", mode_flags=MagicMock()) + events: list[Any] = [] + + with ( + patch.object(ResponseContext, "get_input_items", new=AsyncMock(side_effect=reader.load)), + patch.object(ResponseContext, "get_history", new=AsyncMock(return_value=[])), + ): + task = asyncio.create_task( + collect_host_events( + cast(AsyncIterator[Any], server._handle_response(request, context, asyncio.Event())), + events, + ) + ) + try: + await asyncio.wait_for(store.started.wait(), timeout=2) + task.cancel() + with pytest.raises(asyncio.CancelledError): + await task + finally: + if not task.done(): + task.cancel() + await asyncio.gather(task, return_exceptions=True) + + assert reader.stopped.is_set() + assert store.stopped.is_set() + agent.run.assert_not_called() + # endregion From 0cc33bf4b0ad1e3c4799d9d1d1d5d79fef567e72 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 10:51:30 +0100 Subject: [PATCH 26/55] docs: reconcile final Foundry hosting contracts and samples --- .../0055-python-foundry-hosting-contracts.md | 28 +++- python/packages/foundry_hosting/README.md | 133 ++++++++++++++++-- .../foundry_hosting/test_options_sample.py | 77 ++++++++++ .../responses/basic/README.md | 29 +++- .../responses/basic/options.py | 4 +- 5 files changed, 241 insertions(+), 30 deletions(-) create mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/test_options_sample.py diff --git a/docs/decisions/0055-python-foundry-hosting-contracts.md b/docs/decisions/0055-python-foundry-hosting-contracts.md index 721b74608cb..c58679f5cbc 100644 --- a/docs/decisions/0055-python-foundry-hosting-contracts.md +++ b/docs/decisions/0055-python-foundry-hosting-contracts.md @@ -146,27 +146,43 @@ or other request-option precedence. ### Approvals and consent Use session-backed authority for regular-agent approvals rather than a separate public approval-store API. -Native workflow pending authority remains checkpoint-owned. Canonical pending state, conditional consumption, -persistence ordering, custom-store capabilities, and failure semantics require a complete design before -replacing existing approval storage. +Native workflow pending authority remains checkpoint-owned. Keep one canonical pending batch in the configured +session store; response and conversation aliases retain history and a link, not independent permission. +Require structural `get_with_revision` and `compare_and_set` methods with create-only and exact-revision +semantics. Foundry-managed storage uses AgentServer's create-only and conditional-write primitives without +assumptions about its underlying topology. Custom providers must coordinate all writers; a process-local +lock does not provide cross-process approval authority. Old separate-store approvals require a fresh +conversation, not a silent migration. Reject incomplete hosted MCP approval sets with HTTP 400 before streaming, response headers, `response.created`, or protected dispatch, without consuming pending authority. A complete batch may mix approvals and rejections. +Revalidate and claim authority after other reservations and before protected dispatch. A race after preflight +can still fail after streaming starts. A consumed or uncertain claim is not reopened automatically, including +when the client repeats the same response ID. Non-approval redelivery retains the SDK's behavior. +No claim provides exactly-once external side effects. Represent invocation-time OAuth consent as structured consent with incomplete response status. Pair each emitted function call with one terminal result, preserve completed sibling results, and stop later protected calls. Require `store=true` so continuation can retain the required state; do not support ephemeral consent under `store=false`. +Buffer authority-bearing output until authority and snapshots are saved. Invocation-time consent with +inference-service history is unsupported and fails explicitly; connection-time consent remains separate. +A consent failure after execution starts is a failed response, not a pre-header HTTP 400. + +### Caller options + +Preserve protocol-specific option ordering. Responses translates generation fields before factory resolution +and its hook; Invocations parses and applies its hook before factory resolution. Deep-copy per-run hook input +and replacement mappings without changing developer defaults. Protect hosting and execution controls after +the hook, and reject those controls inside nested transport options. The host split does not authorize +removing existing hooks or applying workflow-only assumptions to regular agents. ### Unresolved boundaries Do not infer a single-target restriction or a multi-target router without a documented Foundry platform contract. Request `model` is not implicitly an agent selector. -Broader option precedence and validation details require separate design. The host split does not -authorize removing existing hooks or applying workflow-only assumptions to regular agents. - Keep current dependency requirements and the steering guard until published-wheel compatibility and concurrent queue-overflow behavior are verified. An upstream merge alone is not release evidence. These decisions do not redesign Core, concurrency, checkpoints, retries, or external exactly-once execution. diff --git a/python/packages/foundry_hosting/README.md b/python/packages/foundry_hosting/README.md index 93ddee7703a..4fbb77aabbd 100644 --- a/python/packages/foundry_hosting/README.md +++ b/python/packages/foundry_hosting/README.md @@ -56,6 +56,56 @@ Agent hosts reject `WorkflowAgent`, whether supplied directly or returned by a f `checkpoint_store_provider` is available only on workflow hosts. No stored state is converted between native workflow and agent execution models. +## Explicit host configuration + +Configure inference defaults on the agent or client, not on the host. Supported hosting settings are: + +| Setting and default | Applies to | Meaning | +| --- | --- | --- | +| `max_history_items=None` | Responses agents | A positive integer caps prior outer history items, only with `history_source="host_managed"`. `None` leaves the installed SDK default unchanged; it does not mean unlimited. | +| `sse_keep_alive_interval_seconds=None` | All four hosts with framed SSE | A positive integer sets the heartbeat interval in seconds. `None` inherits a positive `SSE_KEEPALIVE_INTERVAL`; an absent or nonpositive environment value disables heartbeats. | +| `shutdown_grace_period_seconds=10` | Both Responses hosts | A positive integer sets shutdown waiting in seconds. The SDK also uses it when DELETE waits for response persistence. It is not a model or request timeout. | +| `enable_background_recovery=False` | Both Responses hosts | A boolean permits eligible background recovery. It does not select background execution or guarantee exactly-once effects. | + +For example, after defining the [request-aware factory below](#agent-instances-and-factories): + +```python +server = ResponsesHostServer( + agent=create_agent, + max_history_items=100, + sse_keep_alive_interval_seconds=15, + shutdown_grace_period_seconds=20, +) +``` + +Explicit integer settings reject booleans and non-integers with `TypeError`, and nonpositive values with +`ValueError`. A positive history cap in another history mode raises `ValueError`. Workflow hosts reject +`max_history_items`, including explicit `None`; they do not use outer transcript history caps. +Invocations hosts reject the Responses-only settings `history_source`, `background_source`, +`max_history_items`, `shutdown_grace_period_seconds`, and `enable_background_recovery`, even when `None`. +The existing upstream Invocations `graceful_shutdown_timeout` passthrough is a separate setting. + +An explicit positive SSE interval takes precedence over a positive environment value. However, the SDK parses +`SSE_KEEPALIVE_INTERVAL` before applying that override: malformed values, including an empty string, still raise +`ValueError` even with an explicit interval. Heartbeats do not set a request timeout. Invocations agent +`legacy_wire_format=True` disables inherited heartbeats because its stream is raw text; combining that mode +with an explicit interval raises `ValueError`. + +The public `ResponsesServerOptions` bag is no longer accepted through `options=`. Removed host settings +`default_fetch_history_count`, `default_model`, `create_span_hook`, `additional_server_version`, +`steerable_conversations`, and `resilient_background` also raise `TypeError`, including when `None`. +Use the first-class settings above, agent/client defaults, and Agent Framework observability instead. + +| Host | Continuation state | `prepare_options` | Background recovery | +| --- | --- | --- | --- | +| `ResponsesHostServer` | Agent session plus the selected history source | Sync or async | Eligible inference-service background only | +| `ResponsesWorkflowHostServer` | Exact native workflow checkpoint | Sync or async, before `parse_input` | Checkpoint-backed outer recovery | +| `InvocationsHostServer` | Agent session; application-owned model history | Sync or async | No provider-background recovery | +| `InvocationsWorkflowHostServer` | Exact native workflow checkpoint | Not supported; use `WorkflowTurn` kwargs | No provider-background recovery | + +These are API support boundaries, not live deployment qualification or a promotion of the experimental +surfaces described above. + ## Responses route prefix `ResponsesHostServer` and `ResponsesWorkflowHostServer` pass `prefix` to the @@ -333,6 +383,20 @@ next token is saved can still repeat the tool on recovery; use idempotent tools for side-effecting local tools. This mechanism does not provide exactly-once tool execution. Regular agent runs without this opt-in are not crash-replayable. +The supported regular-agent combinations are: + +| `history_source` | `background_source` | Provider background | `enable_background_recovery=True` | +| --- | --- | --- | --- | +| `"host_managed"` | `"host_managed"` | No; outer background only | Rejected | +| `"agent_managed"` | `"host_managed"` | No; outer background only | Rejected | +| `"inference_service"` | `"host_managed"` | No; outer background only | Rejected | +| `"inference_service"` | `"inference_service"` | Only when the outer request has `background=true` | Supported for saved private tokens | + +`background_source="inference_service"` with either other history mode is rejected. All background requests +require outer `store=true`. For checkpoint-backed native Responses workflow recovery, use +`enable_background_recovery=True` and enable the AgentServer resilient task subsystem; agent history/background +source settings do not apply. This does not enable provider background on workflow agents. + Provider background is selected only by the host. A provider call may use `background=True` only for an outer background request with both `history_source="inference_service"` and `background_source="inference_service"`. A top-level `background` of `False` or `None` is allowed in every mode. A nested `extra_body["background"]` is @@ -355,16 +419,34 @@ unbounded futures for rejected turns when its steering queue fills steering support needs a published SDK fix, a dependency update, and a concurrent queue-overflow regression. No future SDK version is assumed. Agent background polling without steering is unchanged. -Native CreateResponse generation fields become MAF runtime options (notably `max_output_tokens` -> `max_tokens` and -`parallel_tool_calls` -> `allow_multiple_tool_calls`). Flattened OpenAI `extra_body` fields overlay translated keys -**last**. A sync or async `prepare_options(request: ResponsesRequest, options: dict)` hook can remove or replace -*caller* options before `Agent.run`; removed values fall back to the developer's unchanged agent defaults. Hosting -filters caller platform IDs and private continuation/storage controls from model options and rejects attempts to -reintroduce them through the hook. Nested `extra_body` transport overrides are rejected for both caller -input and developer hooks, because they could override the host's `store=False` after the OpenAI SDK merges -the body. Developer defaults also cannot use this transport channel for host-controlled fields on -explicit history modes or unstored requests. A custom agent cannot accept MAF runtime options: choose -`unsupported_options` as `"ignore"`, `"warn"` (default), or `"error"` for that case. See the +### Preparing caller options + +Native CreateResponse generation fields become MAF runtime options, notably `max_output_tokens` -> `max_tokens` +and `parallel_tool_calls` -> `allow_multiple_tool_calls`. Precedence, from lowest to highest, is: +native generation fields, flattened unknown generation fields, generation fields inside a literal `extra_body` +mapping, then the `prepare_options` replacement. The OpenAI client normally flattens its `extra_body` into the +wire request; a literal nested mapping is also accepted for generation settings. + +A sync or async `prepare_options(request: ResponsesRequest, options: dict[str, Any])` hook receives a fresh +deep copy of this turn's effective caller options. It must return a replacement mapping with string keys; +the host deep-copies that result again. Mutating the argument without returning a mapping is invalid. +Removing `"model"` lets the developer's unchanged agent/client model default apply, while other caller +settings such as `"temperature"` remain. This works for streaming and non-streaming requests. + +Responses agent ordering is translation, factory resolution and configuration checks, hook, then protected-option +validation before execution. The factory therefore sees translated options **before** the hook. Invocations +agent ordering is parser, hook, protected-option validation, factory, then default validation before entering +the agent. Do not rely on identical HTTP error timing between protocols. Responses workflows retain their +hook before `parse_input`; Invocations workflows have no option hook. + +Native request-envelope controls such as identity, storage, and continuation fields are not forwarded as +generation options. Putting those controls or agent execution controls inside `extra_body` raises `ValueError` +before the hook; the host does not silently strip them. Hook results also cannot contain host controls, +`extra_body`, or execution controls such as `client_kwargs`, `middleware`, `session`, and tool-invocation kwargs. +Responses native `instructions` and `tools` remain supported; Invocations agent options additionally reject both. +Developer defaults cannot use nested transport controls to bypass storage or background policy. +For a custom agent that cannot accept MAF runtime options, choose +`unsupported_options` as `"ignore"`, `"warn"` (default), or `"error"`. See the [agent history and options samples](../../samples/04-hosting/foundry-hosted-agents/responses/basic/). ### OAuth consent origin allowlist @@ -388,8 +470,9 @@ belong on the emitted consent link, not in the configuration. ### Invocation-time OAuth consent -When a Foundry Toolbox MCP `tools/call` reports that the user must give OAuth consent, the Responses agent host -does not end the run with an opaque error. The response has status `incomplete`, and its output contains: +With `history_source="host_managed"` or `"agent_managed"` and `store=true`, a Foundry Toolbox MCP `tools/call` +that requires OAuth consent produces a structured continuation rather than an opaque error. +The Responses agent response has status `incomplete`, and its output contains: - the `function_call` for the protected tool; - a `function_call_output` for that call, whose text says that OAuth consent is required; @@ -416,6 +499,8 @@ Failure boundaries: - Consent continuation requires `store=true`. If the request has `store=false`, the response fails and the host exposes no consent or approval output. Consent appears during tool execution, after the response has started, so this is a failed response, not an HTTP 400 rejection. +- Invocation-time consent is unsupported with `history_source="inference_service"`: the response fails explicitly + rather than publishing a continuation that the service-owned history cannot safely resume. - Consent at connection time (`tools/list`) behaves as before. Limits: @@ -529,9 +614,9 @@ and file-based storage locally. Responses sessions use the `agent_sessions` logi Invocations sessions use the separate `invocation_sessions` store. Each stored agent turn saves a snapshot under its **own** outer `response.id`. For a named `conversation`, a -separate mutable conversation-head key is also updated. Loaded MAF sessions use PR1's ETag condition for that key: -a competing turn that advanced the head causes a visible conflict rather than a stale overwrite. A superseded -steered turn saves its response snapshot but skips the head update. In `"inference_service"` or `"agent_managed"` history mode, a +separate mutable conversation-head key is also updated. Loaded MAF sessions use that key's loaded revision: +a competing turn that advanced the head causes a visible conflict rather than a stale overwrite. In +`"inference_service"` or `"agent_managed"` history mode, a stored named-conversation turn first claims that head with a conditional write *before* calling the inner agent. Another request that read the old head loses the CAS; one that reads the claim fails before touching the provider. The claim is cleared when the winning turn successfully commits the new head. If a dispatched turn fails or is @@ -627,6 +712,8 @@ Native workflow pending replies remain checkpoint-owned, not agent-session appro **Migration/reset:** pending approvals from the old separate function-approval store are not migrated. Start a fresh conversation without an old `previous_response_id` or conversation ID and obtain fresh approvals. Do not copy legacy approval records into session state. +The public `FunctionApprovalStore`, `FoundryFunctionApprovalStore`, and `FunctionApprovalStoreProvider` +exports and the `function_approval_store_provider=` constructor setting are removed. Missing or expired authority fails closed, even when a snapshot still contains the historical request. Retained approval history does not authorize another tool execution. @@ -666,10 +753,26 @@ Reply to the complete pending approval batch. Approvals and rejections may be mi duplicate, stale, or foreign controls are invalid. Publishing pending authority requires `store=true`; `store=false` cannot publish or resume host-managed approvals. +Both Responses hosts perform a read-only MCP approval preflight. Invalid or incomplete batches return +HTTP 400 before headers, `response.created`, parsing, or protected execution, without consuming usable +authority. A conversation with pending approvals also rejects a plain new turn; finish its pending batch +instead. Unsupported state formats, missing conditional-store capability, and storage failures are not +classified as invalid approval controls. + +The handler independently revalidates the batch and claims it only after other input/options checks and +reservations. A competing request can win between preflight and claim: the losing request can therefore +fail after streaming starts, but does not dispatch protected work. +Supplying a duplicate response ID through `x-agent-response-id` or body `response_id` does not bypass +preflight. After a successful claim, repeating the complete approval continuation is rejected with HTTP 400, +not replayed as another execution. Non-approval redelivery still delegates to AgentServer; this is not a +general idempotency guarantee. + Claiming a batch is an irreversible conditional transition before protected execution. It does not provide exactly-once tool side effects: a crash after a successful claim can lose work. A failed or cancelled claim write may already have committed. Do not reopen the batch or automatically dispatch the protected work after an uncertain result. +Reconcile any external effects before deciding what to retry; start a fresh conversation and obtain fresh +approvals for new work rather than reusing consumed or uncertain authority. Approval history is bounded to 1,024 requests and 1 MiB of serialized approval-content JSON. Exceeding either bound fails explicitly and requires a fresh conversation; history is not silently diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_options_sample.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_options_sample.py new file mode 100644 index 00000000000..fed1df412cb --- /dev/null +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_options_sample.py @@ -0,0 +1,77 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Exercise the documented option hook through the real Responses host offline.""" + +from __future__ import annotations + +import importlib.util +from copy import deepcopy +from pathlib import Path +from types import ModuleType +from typing import Any +from unittest.mock import patch + +import httpx +import pytest +from agent_framework import Agent, ChatOptions + +from agent_framework_foundry_hosting import ResponsesHostServer + +from .options_helpers import OptionsClient + + +@pytest.fixture(scope="module") +def options_sample() -> ModuleType: + path = ( + Path(__file__).resolve().parents[4] + / "samples" + / "04-hosting" + / "foundry-hosted-agents" + / "responses" + / "basic" + / "options.py" + ) + spec = importlib.util.spec_from_file_location("foundry_responses_options_sample", path) + assert spec is not None and spec.loader is not None + module = importlib.util.module_from_spec(spec) + with patch("dotenv.load_dotenv", return_value=False): + spec.loader.exec_module(module) + return module + + +@pytest.mark.parametrize("stream", [False, True]) +@pytest.mark.parametrize("nested", [False, True]) +async def test_sample_hook_preserves_developer_model_and_other_caller_options( + options_sample: ModuleType, stream: bool, nested: bool +) -> None: + model = OptionsClient() + defaults: ChatOptions = {"model": "developer", "temperature": 0.4, "max_tokens": 256} + agent = Agent(client=model, default_options=defaults) + original_defaults = deepcopy(agent.default_options) + host = ResponsesHostServer(agent, prepare_options=options_sample.prepare_options) + payload: dict[str, Any] = { + "input": "hi", + "model": "caller", + "temperature": 0.8, + "max_output_tokens": 300, + "max_tokens": 200, + "stream": stream, + "store": False, + } + if nested: + payload["extra_body"] = {"model": "nested-caller", "temperature": 0.6, "max_tokens": 150} + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: + response = await client.post("/responses", json=payload) + + assert response.status_code == 200 + assert "response.failed" not in response.text + if stream: + assert "event: response.completed" in response.text + else: + assert response.json()["status"] == "completed" + assert len(model.calls) == 1 + assert model.calls[0]["model"] == "developer" + assert model.calls[0]["temperature"] == (0.6 if nested else 0.8) + assert model.calls[0]["max_tokens"] == (150 if nested else 200) + assert agent.default_options == original_defaults + assert defaults == {"model": "developer", "temperature": 0.4, "max_tokens": 256} diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/basic/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/basic/README.md index 479856271ce..6ed7d1a8730 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/basic/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/basic/README.md @@ -8,7 +8,7 @@ who supplies the agent's model history: | [main.py](main.py) | `"host_managed"` | The outer Responses transcript; the inner client runs with `store=False`. | | [service_history.py](service_history.py) | `"inference_service"` | Only new input goes to the model; its private `service_session_id` persists for later turns. | | [agent_history.py](agent_history.py) | `"agent_managed"` | This agent opts into `InMemoryHistoryProvider` with `default_options={"store": False}`; another `"agent_managed"` configuration with `store=True` can use service history instead. | -| [options.py](options.py) | `"host_managed"` | The hook removes the caller's token limit so the agent default is used. | +| [options.py](options.py) | `"host_managed"` | The hook removes the effective caller model so the configured client model is used; other generation settings remain. | | [provider_background.py](provider_background.py) | `"inference_service"` | `background_source="inference_service"` opts into provider background with a private recovery token. | For the same two stored requests—first **"My name is Ada"**, then **"What is my name?"** with the first @@ -78,12 +78,27 @@ the existing thread may have changed even if its outer response did not complete ## Options and compatibility Native CreateResponse generation fields become MAF run options (`max_output_tokens` becomes `max_tokens` and -`parallel_tool_calls` becomes `allow_multiple_tool_calls`). Flattened OpenAI `extra_body` values overlay translated -keys **last**. The developer's `prepare_options(request, options)` hook can then remove or replace *caller* options; -removing one exposes the agent's own unchanged `default_options`. In [options.py](options.py), -`max_output_tokens=300` plus `extra_body={"max_tokens": 150}` becomes `max_tokens=150` before the hook removes it; -the model receives the agent's `max_tokens=256` default instead. Platform IDs, storage flags, and private -continuation tokens are never caller model options; the hook cannot add them back. +`parallel_tool_calls` becomes `allow_multiple_tool_calls`). Flattened unknown generation fields override those +translated fields; generation fields inside a literal `extra_body` mapping override both. The developer's +`prepare_options(request, options)` hook then returns the replacement *caller* options. The host deep-copies +both its input and result, and keeps developer defaults unchanged. + +In [options.py](options.py), the hook removes `"model"` from the effective merged options, so the client uses +the configured `FOUNDRY_MODEL` (or hosted deployment-name fallback). It preserves `"temperature"` and +`"max_tokens"` if supplied. For example: + +```bash +curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" \ + -d '{"input":"Hi","model":"caller-selected-model","temperature":0.3,"max_output_tokens":150}' +``` + +The client uses the developer's model with `temperature=0.3` and `max_tokens=150`, not the caller's model. +If the caller omits a token limit, the agent's `max_tokens=256` default applies. +Responses factories see translated caller options before the hook. Platform IDs, storage flags, and private +continuation tokens are never caller model options; the hook cannot add them back. Host controls inside +`extra_body` fail before the hook, rather than being silently stripped. +See [explicit host configuration](../../../../../packages/foundry_hosting/README.md#explicit-host-configuration) +for history caps, heartbeat intervals, shutdown waiting, and eligible recovery modes. `history_source="host_managed"` and `history_source="agent_managed"` retain their existing meaning without a deprecation warning. For **stored** requests, `"agent_managed"` passes only new input to the agent, whose diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/basic/options.py b/python/samples/04-hosting/foundry-hosted-agents/responses/basic/options.py index 681e27d1849..ec415b6c868 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/basic/options.py +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/basic/options.py @@ -16,8 +16,8 @@ def prepare_options(_request: ResponsesRequest, options: dict[str, Any]) -> dict[str, Any]: - """Use the agent's output-token default instead of the caller's override.""" - options.pop("max_tokens", None) + """Keep the developer's model while preserving other caller generation settings.""" + options.pop("model", None) return options From 4c50dcb8f867f0ab81f3744ad77306d2a059d9be Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 11:09:49 +0100 Subject: [PATCH 27/55] Remove legacy Invocations wire format --- .../_invocations_agent.py | 5 -- .../_invocations_shared.py | 44 +++---------- .../_invocations_workflow.py | 5 +- .../_shared.py | 1 + .../foundry_hosting/test_host_options.py | 9 --- .../test_invocations_workflow.py | 4 +- .../foundry_hosting/tests/test_invocations.py | 63 ++----------------- 7 files changed, 16 insertions(+), 115 deletions(-) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py index 1f3ca218cef..4ebf66e7dfa 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py @@ -30,7 +30,6 @@ def __init__( parse_input: Callable[[Request], InvocationRun | Awaitable[InvocationRun]] | None = None, prepare_options: InvocationOptionsHook | None = None, unsupported_options: UnsupportedOptions = "warn", - legacy_wire_format: bool = False, sse_keep_alive_interval_seconds: int | None = None, **kwargs: Any, ) -> None: @@ -57,11 +56,8 @@ def __init__( unlike Responses factories which run before the hook. Removing a caller ``model`` retains the agent/client inference default. Defaults are not mutated. unsupported_options: Policy for agents without runtime options: `"warn"`, `"ignore"`, or `"error"`. - legacy_wire_format: Deprecated agent-only plain-text and raw-stream compatibility format. - Heartbeats are disabled in this format to avoid inserting SSE comments into raw text. sse_keep_alive_interval_seconds: Positive streaming heartbeat interval. If omitted, use a positive `SSE_KEEPALIVE_INTERVAL`, otherwise disable heartbeats. Not a request/model timeout. - An explicit interval cannot be combined with `legacy_wire_format=True`. **kwargs: Additional AgentServer host settings forwarded to the SDK. Raises: @@ -79,7 +75,6 @@ def __init__( parse_input=parse_input, prepare_options=prepare_options, unsupported_options=unsupported_options, - legacy_wire_format=legacy_wire_format, sse_keep_alive_interval_seconds=sse_keep_alive_interval_seconds, **kwargs, ) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py index 5483dad505a..164597f7dc0 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py @@ -11,7 +11,6 @@ import math import sys import uuid -import warnings import weakref from collections.abc import AsyncGenerator, Awaitable, Callable, Mapping, Sequence from contextlib import AbstractAsyncContextManager, AsyncExitStack, asynccontextmanager @@ -340,7 +339,6 @@ def __init__( parse_input: InvocationParser | None = None, prepare_options: InvocationOptionsHook | None = None, unsupported_options: UnsupportedOptions = "warn", - legacy_wire_format: bool = False, sse_keep_alive_interval_seconds: int | None = None, **kwargs: Any, ) -> None: @@ -375,15 +373,9 @@ def __init__( raise TypeError("parse_input must be a callable.") if prepare_options is not None and not callable(prepare_options): raise TypeError("prepare_options must be a callable.") - if not isinstance(legacy_wire_format, bool): - raise TypeError("legacy_wire_format must be a boolean.") - if legacy_wire_format and sse_keep_alive_interval_seconds is not None: - raise ValueError("SSE heartbeats require framed SSE; disable legacy_wire_format.") if is_agent(agent): self._validate_agent_options(agent) if workflow is not None: - if legacy_wire_format: - raise ValueError("legacy_wire_format=True is incompatible with native workflows.") if prepare_options is not None: raise ValueError("prepare_options is agent-only; use the workflow parser's explicit client_kwargs.") if agent_session_store_provider is not None: @@ -394,16 +386,13 @@ def __init__( WorkflowResolver(workflow) if workflow is not None else None ) super().__init__(openapi_spec=openapi_spec, **kwargs) - if legacy_wire_format: - self.config.sse_keepalive_interval = 0 - elif sse_keep_alive_interval_seconds is not None: + if sse_keep_alive_interval_seconds is not None: self.config.sse_keepalive_interval = sse_keep_alive_interval_seconds self._agent = agent self._owns_request_agent = agent is not None and not is_agent(agent) self._parse_input = parse_input self._prepare_options = prepare_options self._unsupported_options = unsupported_options - self._legacy_wire_format = legacy_wire_format self._session_store_provider = ( AgentSessionStoreProvider(store_name="invocation_sessions") if agent_session_store_provider is None @@ -415,13 +404,6 @@ def __init__( self._session_locks: weakref.WeakValueDictionary[str | tuple[str, str], asyncio.Lock] = ( weakref.WeakValueDictionary() ) - if legacy_wire_format: - message = ( - "legacy_wire_format=True is deprecated; migrate Invocations clients to JSON responses " - "and framed SSE events before removing this compatibility mode." - ) - warnings.warn(message, DeprecationWarning, stacklevel=3) - logger.warning("DEPRECATION: %s", message) self.invoke_handler(self._handle_invoke) mark_feature_used(FeatureIndex.FOUNDRY_HOSTING) @@ -657,15 +639,10 @@ async def stream_response() -> AsyncGenerator[str]: try: async for update in stream: if update.text: - frame = ( - update.text - if self._legacy_wire_format - else _sse("delta", {"text": update.text}) - ) # The SDK may close a suspended generator from another task. reset_request_context(token) token = None - yield frame + yield _sse("delta", {"text": update.text}) token = set_request_context(context) if isinstance(stream, ResponseStream): await stream.get_final_response() @@ -678,23 +655,18 @@ async def stream_response() -> AsyncGenerator[str]: await self._close_interrupted_stream(stream) except Exception: logger.exception("Failed to close interrupted Invocations agent stream") - if not self._legacy_wire_format: - session_id = partition_key[0] if isinstance(partition_key, tuple) else partition_key - if token is not None: - reset_request_context(token) - token = None - yield _sse("done", {"session_id": session_id}) + session_id = partition_key[0] if isinstance(partition_key, tuple) else partition_key + if token is not None: + reset_request_context(token) + token = None + yield _sse("done", {"session_id": session_id}) except _UnsupportedAgentOptions as exc: - if self._legacy_wire_format: - raise if token is not None: reset_request_context(token) token = None yield _sse("error", {"message": str(exc), "code": "unsupported_options", "status": 400}) except Exception as exc: logger.exception("Invocations agent stream failed") - if self._legacy_wire_format: - raise message, status, code = _invocation_failure(exc) if token is not None: reset_request_context(token) @@ -712,8 +684,6 @@ async def stream_response() -> AsyncGenerator[str]: run_kwargs = {**self._agent_kwargs(agent, options), **foreground_agent_run_kwargs(agent)} async with self._request_session(partition_key, context, hosted_scope=hosted_scope) as session: response = await agent.run(parsed.messages, session=session, **run_kwargs) - if self._legacy_wire_format: - return Response(content=response.text) return JSONResponse({"response": response.text}) except _UnsupportedAgentOptions as exc: return JSONResponse({"error": str(exc)}, status_code=400) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py index e23a252e456..6fd950f0454 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py @@ -44,8 +44,8 @@ def __init__( Native workflow history and pending replies are checkpoint-owned, not agent-session-owned. sse_keep_alive_interval_seconds: Positive streaming heartbeat interval. If omitted, use a positive `SSE_KEEPALIVE_INTERVAL`, otherwise disable heartbeats. Not a request/model timeout. - **kwargs: Additional AgentServer host settings forwarded to the SDK. Agent option hooks and - legacy wire format are not supported. Output uses JSON or framed SSE workflow events. + **kwargs: Additional AgentServer host settings forwarded to the SDK. Output uses JSON or framed + SSE workflow events. Raises: TypeError: If the workflow is not a request-aware factory, the parser or heartbeat type is invalid, @@ -57,7 +57,6 @@ def __init__( "agent_session_store_provider", "prepare_options", "unsupported_options", - "legacy_wire_format", }.intersection(kwargs) if forbidden: raise TypeError(f"Unsupported native workflow host settings: {', '.join(sorted(forbidden))}.") diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py index 51f6989e7f8..e9e6c36b109 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py @@ -58,6 +58,7 @@ def reject_removed_host_settings(settings: Mapping[str, Any]) -> None: "additional_server_version": "Custom server version stamping is not supported.", "steerable_conversations": "Conversation steering is not supported.", "resilient_background": "Use enable_background_recovery on a Responses host.", + "legacy_wire_format": "Invocations always use JSON responses and framed SSE events.", } for name, message in replacements.items(): if name in settings: diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py index 3a1de89c8c7..f77a55a5a37 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py @@ -148,15 +148,6 @@ def test_invocations_heartbeat_precedence_and_per_host_isolation( assert first.config is not second.config -def test_legacy_raw_stream_does_not_inherit_heartbeats(monkeypatch: pytest.MonkeyPatch) -> None: - monkeypatch.setenv("SSE_KEEPALIVE_INTERVAL", "3") - with pytest.warns(DeprecationWarning): - server = InvocationsHostServer(Agent(client=OptionsClient()), legacy_wire_format=True) - assert server.config.sse_keepalive_interval == 0 - with pytest.raises(ValueError, match="framed SSE"): - InvocationsHostServer(Agent(client=OptionsClient()), legacy_wire_format=True, sse_keep_alive_interval_seconds=1) - - @pytest.mark.parametrize("provider_background", [False, True]) @pytest.mark.parametrize("background", [None, False, True, "true", 1]) def test_agent_background_defaults_are_validated_without_mutation(provider_background: bool, background: Any) -> None: diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_invocations_workflow.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_invocations_workflow.py index 81ef021147a..27778381950 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_invocations_workflow.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_invocations_workflow.py @@ -444,8 +444,8 @@ def create(_request: Request) -> Workflow: with pytest.raises(TypeError, match="parse_input"): cast(Any, InvocationsWorkflowHostServer)(workflow=create) - def test_workflow_rejects_agent_legacy_wire_format(self) -> None: - with pytest.raises(TypeError, match="legacy_wire_format"): + def test_workflow_rejects_removed_legacy_wire_format_setting(self) -> None: + with pytest.raises(TypeError, match="legacy_wire_format is no longer a supported host setting"): InvocationsWorkflowHostServer( workflow=lambda _: WorkflowBuilder(name="tickets", start_executor=_TicketExecutor([])).build(), parse_input=_parse_ticket, diff --git a/python/packages/foundry_hosting/tests/test_invocations.py b/python/packages/foundry_hosting/tests/test_invocations.py index 3a488f95365..5e9f2b22364 100644 --- a/python/packages/foundry_hosting/tests/test_invocations.py +++ b/python/packages/foundry_hosting/tests/test_invocations.py @@ -13,7 +13,6 @@ import asyncio import json -import logging import uuid import weakref from collections.abc import AsyncIterator, Awaitable, Callable, Generator, Mapping, Sequence @@ -668,7 +667,7 @@ def create_agent(request: Request, name: str) -> _FakeAgent: ("parse_input", 42, "parse_input must be a callable"), ("prepare_options", 42, "prepare_options must be a callable"), ("unsupported_options", "discard", "unsupported_options"), - ("legacy_wire_format", "false", "legacy_wire_format must be a boolean"), + ("legacy_wire_format", True, "legacy_wire_format is no longer a supported host setting"), ], ) def test_rejects_invalid_configuration(self, parameter: str, value: Any, error: str) -> None: @@ -887,10 +886,9 @@ def create_agent(*, request: Request) -> _FakeAgent: assert provider.contexts == [] @pytest.mark.parametrize("stream", [False, True]) - @pytest.mark.parametrize("legacy_wire_format", [False, True]) @pytest.mark.parametrize("policy", ["ignore", "warn", "error"]) - async def test_http_route_rejects_tool_context_options_under_every_wire_and_options_policy( - self, stream: bool, legacy_wire_format: bool, policy: Literal["ignore", "warn", "error"] + async def test_http_route_rejects_tool_context_options_under_every_options_policy( + self, stream: bool, policy: Literal["ignore", "warn", "error"] ) -> None: agent = _make_agent(response_text="ok", stream_texts=["ok"]) provider = _SessionStoreProvider(_mock_session_store()) @@ -901,14 +899,9 @@ def create_host() -> InvocationsHostServer: agent, agent_session_store_provider=provider, unsupported_options=policy, - legacy_wire_format=legacy_wire_format, ) - if legacy_wire_format: - with pytest.warns(DeprecationWarning, match="legacy_wire_format"): - server = create_host() - else: - server = create_host() + server = create_host() async with httpx.AsyncClient(transport=httpx.ASGITransport(app=server), base_url="http://test") as client: response = await client.post( "/invocations", @@ -1367,54 +1360,6 @@ async def test_invalid_json_uses_client_status_on_actual_http_route(self) -> Non assert "error" in response.json() assert agent.calls == [] - async def test_legacy_wire_format_is_explicit_once_warned_and_unchanged( - self, caplog: pytest.LogCaptureFixture - ) -> None: - with pytest.warns(DeprecationWarning, match="legacy_wire_format"): - server = InvocationsHostServer( - _make_agent(response_text="Hello!", stream_texts=["Hel", "lo", "!"]), legacy_wire_format=True - ) - with _request_context(session_id="legacy"): - for _ in range(2): - plain = await server._handle_invoke(_make_request({"message": "hi"})) # pyright: ignore[reportPrivateUsage] - assert bytes(plain.body).decode() == "Hello!" - streamed = await server._handle_invoke( # pyright: ignore[reportPrivateUsage] - _make_request({"message": "hi", "stream": True}) - ) - assert isinstance(streamed, StreamingResponse) - assert await _collect_stream(streamed) == "Hello!" - - deprecations = [ - record - for record in caplog.records - if record.levelno == logging.WARNING and "DEPRECATION:" in record.message - ] - assert len(deprecations) == 1 - - async def test_legacy_stream_failure_terminates_instead_of_sending_new_frame(self) -> None: - class FailingAgent(_FakeAgent): - def run( - self, messages: Any = None, *, stream: bool = False, session: AgentSession | None = None, **kwargs: Any - ) -> Any: - async def updates() -> AsyncIterator[AgentResponseUpdate]: - yield AgentResponseUpdate(contents=[Content.from_text("first")]) - raise RuntimeError("provider failed") - - return updates() - - with pytest.warns(DeprecationWarning): - server = InvocationsHostServer(FailingAgent(), legacy_wire_format=True) - with _request_context(session_id="legacy-failure"): - response = await server._handle_invoke( # pyright: ignore[reportPrivateUsage] - _make_request({"message": "hi", "stream": True}) - ) - assert isinstance(response, StreamingResponse) - iterator = cast(Any, response.body_iterator) - assert await anext(iterator) == "first" - with pytest.raises(RuntimeError, match="provider failed"): - await anext(iterator) - - # endregion From b8a8f8d6033963f4fb8a7b9af617ad84c55bade3 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 11:11:10 +0100 Subject: [PATCH 28/55] docs: remove legacy Invocations wire format guidance --- python/packages/foundry_hosting/README.md | 20 +++++-------------- .../invocations/basic/README.md | 12 +++-------- 2 files changed, 8 insertions(+), 24 deletions(-) diff --git a/python/packages/foundry_hosting/README.md b/python/packages/foundry_hosting/README.md index 4fbb77aabbd..33b0859345c 100644 --- a/python/packages/foundry_hosting/README.md +++ b/python/packages/foundry_hosting/README.md @@ -87,9 +87,7 @@ The existing upstream Invocations `graceful_shutdown_timeout` passthrough is a s An explicit positive SSE interval takes precedence over a positive environment value. However, the SDK parses `SSE_KEEPALIVE_INTERVAL` before applying that override: malformed values, including an empty string, still raise -`ValueError` even with an explicit interval. Heartbeats do not set a request timeout. Invocations agent -`legacy_wire_format=True` disables inherited heartbeats because its stream is raw text; combining that mode -with an explicit interval raises `ValueError`. +`ValueError` even with an explicit interval. Heartbeats do not set a request timeout. The public `ResponsesServerOptions` bag is no longer accepted through `options=`. Removed host settings `default_fetch_history_count`, `default_model`, `create_span_hook`, `additional_server_version`, @@ -646,7 +644,7 @@ and user ID. Consumers must use it as a whole and must not parse it or depend on representation. Repeated requests for the same identifier pair restore the saved session. Locally, the platform session ID is used unchanged. -### Invocations agent requests and wire compatibility +### Invocations agent requests and response format By default, `POST /invocations` accepts `{"message": "Hi", "options": {}, "stream": false}`. Applications can supply a sync or async `parse_input(request)` returning a typed `InvocationRun(messages, options, stream)` to accept their @@ -658,12 +656,12 @@ runtime options. It also rejects agent execution controls: `additional_function_ `client_kwargs`, `middleware`, `session`, `tools`, `instructions`, `compaction_strategy`, and `tokenizer`. Trusted tool arguments belong in developer-configured agent defaults or middleware/factories, not in request options or hook output. A hook may strip denied caller fields before validation; allowed generation and provider-specific options remain -available. These restrictions apply to both wire formats and every `unsupported_options` policy. +available. These restrictions apply to streaming and non-streaming requests under every `unsupported_options` policy. When an agent cannot accept runtime options, `unsupported_options="warn"` (default) logs and ignores them; `"ignore"` silently drops them and `"error"` rejects them. For request-scoped factories, unsupported options discovered after streaming starts are reported as an SSE `error` event with `status: 400`. -**New default:** non-streaming success is JSON `{"response": "..."}`. Streaming success is real SSE +Non-streaming success is JSON `{"response": "..."}`. Streaming success is framed SSE `event: delta` with `{"text": "..."}`, followed by `event: done` with the platform sandbox `session_id`. The `done` event is sent only after the final MAF `ResponseStream` is finalized and the session is persisted. Client validation errors return JSON HTTP 400 before streaming where possible. Provider errors are logged and @@ -673,14 +671,6 @@ same-session requests in one process, but a CAS conflict can still follow extern processes; it does not guarantee exactly-once execution. See the [Invocations agent/parser example](../../samples/04-hosting/foundry-hosted-agents/invocations/basic/). -**Deprecated opt-in:** set `InvocationsHostServer(agent, legacy_wire_format=True)` only for existing clients -that must keep the previous plain-text non-streaming response and raw text-chunk streaming format. The host logs -and emits a deprecation warning once on construction. Errors are never returned as successful text: non-stream -failures still use JSON error statuses; a post-start legacy stream failure terminates the stream rather than -injecting unexpected SSE framing. Migrate all opted-in clients to JSON/SSE; remove the compatibility mode only -after those callers have migrated and a separate, deliberate breaking-change decision, never by silently -switching an opted-in deployment. - Both hosts accept `agent_session_store_provider` to select a `StoreProvider[SessionStore]`. Session state must support `AgentSession` serialization. Use `register_state_type()` codecs for custom types; unsupported live objects fail during persistence. Restored sessions preserve @@ -869,7 +859,7 @@ including the verified `agent_session_id` query alternative when the platform does not configure `FOUNDRY_AGENT_SESSION_ID`. Body/header IDs cannot establish sandbox routing or select private checkpoints. The agent path still uses its separate `invocation_sessions` store, existing hooks/defaults and JSON/`delta` SSE -contract. Agent-only `legacy_wire_format=True`, `prepare_options` and +contract. Agent-only `prepare_options` and `agent_session_store_provider` are rejected for native workflows rather than silently reinterpreted. diff --git a/python/samples/04-hosting/foundry-hosted-agents/invocations/basic/README.md b/python/samples/04-hosting/foundry-hosted-agents/invocations/basic/README.md index 52be08fc94d..657ffaaea9c 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/invocations/basic/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/invocations/basic/README.md @@ -30,7 +30,7 @@ curl -i -X POST http://localhost:8088/invocations \ -d '{"prompt": "Hi", "options": {"temperature": 0.3}}' ``` -The default wire format is JSON, for example: +Non-streaming success is JSON, for example: ```http HTTP/1.1 200 OK @@ -74,11 +74,7 @@ for scope and retention details. Malformed requests return JSON client errors. Streaming failures produce `event: error` instead of `done`; a competing host's session write is reported as a conflict, not silently overwritten. Do not blindly retry calls with -non-idempotent tools. Existing clients that still require the old plain-text -response and raw text-chunk stream can set `legacy_wire_format=True` on the -host temporarily; the host warns once and the mode is deprecated. Migrate -clients to JSON and framed SSE before removing that opt-in in a deliberate -breaking change. +non-idempotent tools. Follow the [parent deployment guide](../../README.md#deploying-the-agent-to-foundry) when deploying this example to Foundry. @@ -152,9 +148,7 @@ If the connection drops after commit, retry the request with the same trusted user, sandbox and platform call ID to replay the complete stored response without executing the ticket workflow again. Failures produce `error`, not `done`. Non-streaming pauses expose the same -`request_info` data in the JSON event list. Native workflows do not support -`legacy_wire_format=True`; the old plain-text/raw-chunk opt-in applies only -to the agent entrypoint. +`request_info` data in the JSON event list. ### Checkpoints, fresh factories and pending replies From 3d0afc855f1347fe82f04359bceef10bf5864a15 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 11:14:33 +0100 Subject: [PATCH 29/55] Format Invocations tests --- python/packages/foundry_hosting/tests/test_invocations.py | 1 + 1 file changed, 1 insertion(+) diff --git a/python/packages/foundry_hosting/tests/test_invocations.py b/python/packages/foundry_hosting/tests/test_invocations.py index 5e9f2b22364..1b39430d660 100644 --- a/python/packages/foundry_hosting/tests/test_invocations.py +++ b/python/packages/foundry_hosting/tests/test_invocations.py @@ -1360,6 +1360,7 @@ async def test_invalid_json_uses_client_status_on_actual_http_route(self) -> Non assert "error" in response.json() assert agent.calls == [] + # endregion From 55d3875cd8b9db5d6786e55e8c3a6082e1662129 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 11:30:52 +0100 Subject: [PATCH 30/55] Remove unused Responses options validator --- .../_responses_shared.py | 17 +---------------- 1 file changed, 1 insertion(+), 16 deletions(-) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py index 80b1aed70a4..254512a82b6 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py @@ -46,10 +46,7 @@ from agent_framework._mcp import _MCP_TOOL_RESULT_HOST_PAYLOAD_KEY # pyright: ignore[reportPrivateUsage] from agent_framework._types import _get_annotation_text_span_regions # pyright: ignore[reportPrivateUsage] from agent_framework.observability import OBSERVABILITY_SETTINGS -from azure.ai.agentserver.responses import ( - ResponseContext, - ResponsesServerOptions, -) +from azure.ai.agentserver.responses import ResponseContext from azure.ai.agentserver.responses._id_generator import IdGenerator from azure.ai.agentserver.responses.aio import ResponseEventStream from azure.ai.agentserver.responses.models import ( @@ -908,18 +905,6 @@ def _current_toolbox_consent_scope() -> _ToolboxConsentScope | None: # pyright: # endregion Foundry Toolbox Auth integration -def _validate_response_server_options( # pyright: ignore[reportUnusedFunction] - options: ResponsesServerOptions | None, -) -> None: - if options and options.steerable_conversations: - # TODO(foundry-hosting): Remove after Azure/azure-sdk-for-python#49233 ships and queue overflow is verified. - raise RuntimeError( - "steerable_conversations=True is temporarily unavailable: the current AgentServer SDK " - "retains futures for rejected steering turns. Wait for the official fix in " - "Azure/azure-sdk-for-python#49233, then update the dependency and verify queue overflow." - ) - - # region Active Builder State From 067e1215bbc8301bba78b1b5c058f442fc3b316d Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 11:33:16 +0100 Subject: [PATCH 31/55] Unify hosting background middleware guards --- .../_invocations_shared.py | 12 +++- .../_responses_agent.py | 61 +------------------ .../_shared.py | 61 +++++++++++++------ .../test_background_middleware.py | 11 +--- 4 files changed, 57 insertions(+), 88 deletions(-) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py index 164597f7dc0..b232a19a36c 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py @@ -57,7 +57,7 @@ WorkflowResolver, WorkflowSource, WorkflowTurn, - foreground_agent_run_kwargs, + background_agent_run_kwargs, is_agent, reject_removed_host_settings, resolve_agent, @@ -632,7 +632,10 @@ async def stream_response() -> AsyncGenerator[str]: try: lock = self._session_locks.setdefault(partition_key, asyncio.Lock()) async with lock, self._request_agent(request) as agent: - run_kwargs = {**self._agent_kwargs(agent, options), **foreground_agent_run_kwargs(agent)} + run_kwargs = { + **self._agent_kwargs(agent, options), + **background_agent_run_kwargs(agent, provider_background=False), + } async with self._request_session(partition_key, context, hosted_scope=hosted_scope) as session: stream = agent.run(parsed.messages, session=session, stream=True, **run_kwargs) completed = False @@ -681,7 +684,10 @@ async def stream_response() -> AsyncGenerator[str]: try: lock = self._session_locks.setdefault(partition_key, asyncio.Lock()) async with lock, self._request_agent(request) as agent: - run_kwargs = {**self._agent_kwargs(agent, options), **foreground_agent_run_kwargs(agent)} + run_kwargs = { + **self._agent_kwargs(agent, options), + **background_agent_run_kwargs(agent, provider_background=False), + } async with self._request_session(partition_key, context, hosted_scope=hosted_scope) as session: response = await agent.run(parsed.messages, session=session, **run_kwargs) return JSONResponse({"response": response.text}) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py index 1329049b77c..b767b605e32 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py @@ -9,8 +9,6 @@ from collections.abc import ( AsyncGenerator, AsyncIterable, - Awaitable, - Callable, Generator, Mapping, Sequence, @@ -21,15 +19,9 @@ from typing import Any, Literal, cast from agent_framework import ( - AgentContext, - AgentMiddleware, - AgentMiddlewareLayer, AgentResponse, AgentResponseUpdate, AgentSession, - ChatContext, - ChatMiddleware, - ChatMiddlewareLayer, ChatOptions, ContextProvider, FinishReason, @@ -99,8 +91,8 @@ OptionsHook, ResponsesRequest, UnsupportedOptions, + background_agent_run_kwargs, build_response_server_options, - foreground_agent_run_kwargs, is_agent, prepare_response_options, reject_removed_host_settings, @@ -109,7 +101,6 @@ validate_agent_background_options, validate_agent_source, validate_default_transport_options, - validate_provider_background_options, validate_request_options, validate_unsupported_options, ) @@ -153,52 +144,6 @@ class _DeferredOutput: ) -def _validate_selected_provider_background(options: Mapping[str, Any], kwargs: Mapping[str, Any]) -> None: - validate_provider_background_options(options, provider_background=True) - validate_provider_background_options(kwargs, provider_background=True) - if options.get("background") is not True or ("background" in kwargs and kwargs["background"] is not True): - raise ValueError("A selected provider-background request must retain background=True.") - - -class _ProviderBackgroundChatOptions(ChatMiddleware): - async def process(self, context: ChatContext, call_next: Callable[[], Awaitable[None]]) -> None: - _validate_selected_provider_background(context.options or {}, context.kwargs) - await call_next() - - -_PROVIDER_BACKGROUND_CHAT_OPTIONS = _ProviderBackgroundChatOptions() - - -def _append_provider_background_chat_options(agent: RawAgent[Any], client_kwargs: dict[str, Any]) -> None: - if not isinstance(agent.client, ChatMiddlewareLayer): - return - middleware = client_kwargs.get("middleware", ()) - if not isinstance(middleware, Sequence) or isinstance(middleware, (str, bytes)): - raise TypeError("Client middleware must be a sequence.") - client_kwargs["middleware"] = [*middleware, _PROVIDER_BACKGROUND_CHAT_OPTIONS] - - -class _ProviderBackgroundAgentOptions(AgentMiddleware): - async def process(self, context: AgentContext, call_next: Callable[[], Awaitable[None]]) -> None: - agent = context.agent - validate_agent_background_options(agent, provider_background=True) - _validate_selected_provider_background(context.options or {}, context.client_kwargs) - if isinstance(agent, RawAgent): - _append_provider_background_chat_options(cast(RawAgent[Any], agent), context.client_kwargs) - await call_next() - - -_PROVIDER_BACKGROUND_AGENT_OPTIONS = _ProviderBackgroundAgentOptions() - - -def _provider_background_run_kwargs(agent: RawAgent[Any]) -> dict[str, Any]: - if isinstance(agent, AgentMiddlewareLayer): - return {"middleware": [_PROVIDER_BACKGROUND_AGENT_OPTIONS]} - kwargs: dict[str, Any] = {} - _append_provider_background_chat_options(agent, kwargs) - return {"client_kwargs": kwargs} if kwargs else {} - - def _validate_agent_defaults(agent: SupportsAgentRun, *, provider_background: bool, allow_agent_store: bool) -> None: validate_agent_background_options(agent, provider_background=provider_background) if isinstance(agent, RawAgent): @@ -1139,7 +1084,7 @@ async def _handle_inner_agent( logger.warning("Agent doesn't support runtime options. They will be ignored.") if not provider_background: - run_kwargs.update(foreground_agent_run_kwargs(cast(SupportsAgentRun, agent))) + run_kwargs.update(background_agent_run_kwargs(cast(SupportsAgentRun, agent), provider_background=False)) if previous_response_id is not None and context.conversation_id is None and not context.is_recovery: if ( @@ -1424,7 +1369,7 @@ async def run_provider( input_messages, session=session, options=options, - **_provider_background_run_kwargs(agent), + **background_agent_run_kwargs(agent, provider_background=True), ) except Exception as exc: logger.warning("Inner provider background %s failed (%s).", phase, type(exc).__name__) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py index e9e6c36b109..fae4aa3ebc1 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py @@ -404,47 +404,74 @@ def validate_provider_background_options(options: Mapping[str, Any], *, provider raise ValueError("Provider extra_body cannot set host-controlled fields: background.") -class _ForegroundChatOptions(ChatMiddleware): +def _validate_background_run( + options: Mapping[str, Any], kwargs: Mapping[str, Any], *, provider_background: bool +) -> None: + validate_provider_background_options(options, provider_background=provider_background) + validate_provider_background_options(kwargs, provider_background=provider_background) + if provider_background and ( + options.get("background") is not True or ("background" in kwargs and kwargs["background"] is not True) + ): + raise ValueError("A selected provider-background request must retain background=True.") + + +class _BackgroundChatOptions(ChatMiddleware): + def __init__(self, *, provider_background: bool) -> None: + self._provider_background = provider_background + async def process(self, context: ChatContext, call_next: Callable[[], Awaitable[None]]) -> None: - validate_provider_background_options(context.options or {}, provider_background=False) - validate_provider_background_options(context.kwargs, provider_background=False) + _validate_background_run(context.options or {}, context.kwargs, provider_background=self._provider_background) await call_next() -_FOREGROUND_CHAT_OPTIONS = _ForegroundChatOptions() +_FOREGROUND_CHAT_OPTIONS = _BackgroundChatOptions(provider_background=False) +_PROVIDER_BACKGROUND_CHAT_OPTIONS = _BackgroundChatOptions(provider_background=True) -def _append_foreground_chat_options(agent: SupportsAgentRun, client_kwargs: dict[str, Any]) -> None: +def _append_background_chat_options( + agent: SupportsAgentRun, client_kwargs: dict[str, Any], *, provider_background: bool +) -> None: if not isinstance(agent, RawAgent) or not isinstance(cast(RawAgent[Any], agent).client, ChatMiddlewareLayer): return middleware = client_kwargs.get("middleware", ()) if not isinstance(middleware, Sequence) or isinstance(middleware, (str, bytes)): raise TypeError("Client middleware must be a sequence.") - client_kwargs["middleware"] = [*middleware, _FOREGROUND_CHAT_OPTIONS] + guard = _PROVIDER_BACKGROUND_CHAT_OPTIONS if provider_background else _FOREGROUND_CHAT_OPTIONS + client_kwargs["middleware"] = [*middleware, guard] -class _ForegroundAgentOptions(AgentMiddleware): +class _BackgroundAgentOptions(AgentMiddleware): + def __init__(self, *, provider_background: bool) -> None: + self._provider_background = provider_background + async def process(self, context: AgentContext, call_next: Callable[[], Awaitable[None]]) -> None: - validate_agent_background_options(context.agent, provider_background=False) - validate_provider_background_options(context.options or {}, provider_background=False) - validate_provider_background_options(context.client_kwargs, provider_background=False) - _append_foreground_chat_options(context.agent, context.client_kwargs) + validate_agent_background_options(context.agent, provider_background=self._provider_background) + _validate_background_run( + context.options or {}, context.client_kwargs, provider_background=self._provider_background + ) + _append_background_chat_options( + context.agent, context.client_kwargs, provider_background=self._provider_background + ) await call_next() -_FOREGROUND_AGENT_OPTIONS = _ForegroundAgentOptions() +_FOREGROUND_AGENT_OPTIONS = _BackgroundAgentOptions(provider_background=False) +_PROVIDER_BACKGROUND_AGENT_OPTIONS = _BackgroundAgentOptions(provider_background=True) -def foreground_agent_run_kwargs(agent: SupportsAgentRun) -> dict[str, Any]: - """Guard ordinary agent and chat middleware using request-local run arguments. +def background_agent_run_kwargs(agent: SupportsAgentRun, *, provider_background: bool) -> dict[str, Any]: + """Guard agent and chat middleware using request-local run arguments. Custom clients and context-provider-contributed chat middleware must not enable provider background internally; they have no final hosting hook. """ + if provider_background and not isinstance(agent, RawAgent): + return {} if isinstance(agent, AgentMiddlewareLayer): - return {"middleware": [_FOREGROUND_AGENT_OPTIONS]} + guard = _PROVIDER_BACKGROUND_AGENT_OPTIONS if provider_background else _FOREGROUND_AGENT_OPTIONS + return {"middleware": [guard]} kwargs: dict[str, Any] = {} - _append_foreground_chat_options(agent, kwargs) + _append_background_chat_options(agent, kwargs, provider_background=provider_background) return {"client_kwargs": kwargs} if kwargs else {} @@ -621,7 +648,7 @@ async def process(self, context: AgentContext, call_next: Callable[[], Awaitable "user_id": self.scope.user_id, "call_id": self.scope.call_id, } - _append_foreground_chat_options(context.agent, context.client_kwargs) + _append_background_chat_options(context.agent, context.client_kwargs, provider_background=False) def check_result(result: AgentResponse[Any]) -> None: if context.session is not None and context.session.service_session_id is not None: diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_background_middleware.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_background_middleware.py index 8b16cbd4287..1130ba6a3bc 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_background_middleware.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_background_middleware.py @@ -8,16 +8,11 @@ import httpx import pytest -from agent_framework import RawAgent from agent_framework_foundry_hosting import InvocationsHostServer, InvocationsWorkflowHostServer, WorkflowTurn -from agent_framework_foundry_hosting._shared import ( - foreground_agent_run_kwargs, - validate_provider_background_options, -) +from agent_framework_foundry_hosting._shared import validate_provider_background_options from .background_helpers import AgentChatCallbacks, BackgroundCallbacks, ReplacedMiddlewareCallbacks -from .options_helpers import OptionsClient @pytest.mark.parametrize("provider_background", [False, True]) @@ -167,7 +162,3 @@ async def test_supported_middleware_preserves_foreground_generation(workflow: bo assert callbacks.client.calls[0]["temperature"] == 0.2 if not (workflow and raw): assert callbacks.client.chat_middleware == [callbacks.inject_chat] - - -def test_unlayered_client_receives_no_middleware_kwarg() -> None: - assert foreground_agent_run_kwargs(RawAgent(client=OptionsClient())) == {} From d7470ef88978f95e9e388db50fefafecf9a8fafe Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 11:34:10 +0100 Subject: [PATCH 32/55] Unify invalid approval preflight errors --- .../_responses_agent.py | 20 ++++++-------- .../_responses_preflight.py | 27 +++++++++---------- 2 files changed, 20 insertions(+), 27 deletions(-) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py index b767b605e32..2ff590c1c40 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py @@ -54,7 +54,6 @@ from ._approvals import SessionApprovalState, _InvalidApproval # pyright: ignore[reportPrivateUsage] from ._feature_usage import FeatureIndex from ._responses_preflight import ( - _InvalidApprovalInput, # pyright: ignore[reportPrivateUsage] approval_controls, bind_approval_preflight, has_unresolved_input, @@ -441,24 +440,21 @@ async def _preflight_approvals( session_id = context.conversation_id or previous if session_id is None: if ids: - raise _InvalidApprovalInput("The approval has no pending agent session.") + raise _InvalidApproval("The approval has no pending agent session.") return storage = self._session_storage_provider.get_store(config=self.config, platform_context=platform_context) session = await storage.get(session_id) if session is None: if ids: - raise _InvalidApprovalInput("The approval is unavailable in this agent session.") + raise _InvalidApproval("The approval is unavailable in this agent session.") return state = SessionApprovalState(session, storage) - try: - claim = await state.preflight(ids) - except _InvalidApproval as exc: - raise _InvalidApprovalInput(str(exc)) from exc + claim = await state.preflight(ids) if claim is not None: if request.get("store") is False: - raise _InvalidApprovalInput("Approval continuation requires store=true.") + raise _InvalidApproval("Approval continuation requires store=true.") if len(items) != len(ids) or has_unresolved_input(request, items): - raise _InvalidApprovalInput("Pending MCP approvals cannot be mixed with other input.") + raise _InvalidApproval("Pending MCP approvals cannot be mixed with other input.") async def _ensure_agent_ready(self) -> None: """Lazily enter the agent's async context exactly once. @@ -961,10 +957,10 @@ async def _handle_inner_agent( approval_claim = await approval_storage.preflight(approval_ids) if approval_claim is not None: if not stored: - raise _InvalidApprovalInput("Approval continuation requires store=true.") + raise _InvalidApproval("Approval continuation requires store=true.") if len(input_items) != len(approval_ids) or has_unresolved_input(request, input_items): - raise _InvalidApprovalInput("Pending MCP approvals cannot be mixed with other input.") - except (_InvalidApproval, _InvalidApprovalInput) as exc: + raise _InvalidApproval("Pending MCP approvals cannot be mixed with other input.") + except _InvalidApproval as exc: raise _PublicResponseFailure(exc) from None approval_ready.set_result(approval_storage) provider_state = session.state.get(_HOSTED_PROVIDER_STATE_KEY) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_preflight.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_preflight.py index d99fd812adf..760d0c0371d 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_preflight.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_preflight.py @@ -43,16 +43,13 @@ from starlette.responses import Response from starlette.routing import Route +from ._approvals import _InvalidApproval # pyright: ignore[reportPrivateUsage] from ._scope import FoundryRequestScope from ._workflow_state import FoundryWorkflowBindingStore logger = logging.getLogger(__name__) -class _InvalidApprovalInput(ValueError): - """A caller's approval controls cannot resume the current pending batch.""" - - _Preflight = Callable[[CreateResponse, ResponseContext, FoundryAgentRequestContext], Awaitable[None]] @@ -144,7 +141,7 @@ async def checked_create( token = set_request_context(platform_context) try: await preflight(parsed, context, platform_context) - except _InvalidApprovalInput as exc: + except _InvalidApproval as exc: return error_response(exc, headers, request_id=request_id) except Exception as exc: logger.error("Responses approval preflight failed (%s).", type(exc).__name__) @@ -175,7 +172,7 @@ def approval_controls(items: list[Mapping[str, Any]]) -> list[str]: continue wire_id, decision = item.get("approval_request_id"), item.get("approve") if not isinstance(wire_id, str) or not wire_id or type(decision) is not bool: - raise _InvalidApprovalInput("An approval reply requires its exact ID and a boolean decision.") + raise _InvalidApproval("An approval reply requires its exact ID and a boolean decision.") ids.append(wire_id) return ids @@ -198,7 +195,7 @@ async def preflight_workflow_approvals( previous = previous if isinstance(previous, str) and previous else None if previous is None and context.conversation_id is None: if ids: - raise _InvalidApprovalInput("The approval has no pending workflow checkpoint.") + raise _InvalidApproval("The approval has no pending workflow checkpoint.") return scope = FoundryRequestScope.from_context(host.config, platform_context, local_session_id=context.response_id) storage = FoundryWorkflowBindingStore(scope) @@ -224,7 +221,7 @@ async def preflight_workflow_approvals( or head.binding != record.binding ): if ids: - raise _InvalidApprovalInput("The approval is unavailable in the current workflow checkpoint.") + raise _InvalidApproval("The approval is unavailable in the current workflow checkpoint.") return aliases = record.approvals or {} output = record.snapshot.get("output") @@ -240,25 +237,25 @@ async def preflight_workflow_approvals( approval_ids.add(wire_id) if not approval_ids: if ids: - raise _InvalidApprovalInput("The workflow has no pending MCP approval batch.") + raise _InvalidApproval("The workflow has no pending MCP approval batch.") return if request.get("store") is False: - raise _InvalidApprovalInput("Approval continuation requires store=true.") + raise _InvalidApproval("Approval continuation requires store=true.") if has_unresolved_input(request, items): - raise _InvalidApprovalInput("Pending workflow approvals cannot include unresolved input references.") + raise _InvalidApproval("Pending workflow approvals cannot include unresolved input references.") controls: list[str] = [] for item in items: item_type = item.get("type") if item_type == "mcp_approval_response": wire_id = item.get("approval_request_id") if wire_id not in approval_ids: - raise _InvalidApprovalInput("An approval reply must match this exact pending checkpoint.") + raise _InvalidApproval("An approval reply must match this exact pending checkpoint.") elif item_type in ("function_call_output", "computer_call_output"): wire_id = item.get("call_id") if not isinstance(wire_id, str) or wire_id not in aliases or wire_id in approval_ids: - raise _InvalidApprovalInput("A reply must match this exact pending checkpoint.") + raise _InvalidApproval("A reply must match this exact pending checkpoint.") else: - raise _InvalidApprovalInput("Pending workflow approvals cannot be mixed with new input.") + raise _InvalidApproval("Pending workflow approvals cannot be mixed with new input.") controls.append(cast(str, wire_id)) if len(controls) != len(set(controls)) or set(controls) != set(aliases): - raise _InvalidApprovalInput("Answer exactly the complete pending workflow request batch.") + raise _InvalidApproval("Answer exactly the complete pending workflow request batch.") From 29e01d6d455f02d68903a171ae3db1fa190c1c7c Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 11:34:45 +0100 Subject: [PATCH 33/55] Validate approval history once per preflight --- .../agent_framework_foundry_hosting/_approvals.py | 15 +++++++++------ .../foundry_hosting/test_session_approvals.py | 3 ++- 2 files changed, 11 insertions(+), 7 deletions(-) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_approvals.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_approvals.py index 7f7d699ecc1..b4ad7bfaf33 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_approvals.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_approvals.py @@ -246,12 +246,15 @@ async def preflight(self, approval_ids: Sequence[str]) -> _ApprovalClaim | None: if type(record.get("version")) is not int or record["version"] != 1: raise RuntimeError("Unsupported canonical approval version; start a fresh conversation.") requests = _requests(record.get("requests")) - if ( - authority.session_id != self.session.session_id - or record.get("response_id") != pending["response_id"] - or set(requests) != set(pending["wire_ids"]) - or any(_requests(self._state["history"]).get(key) != value for key, value in requests.items()) - ): + matches_owner = ( + authority.session_id == self.session.session_id + and record.get("response_id") == pending["response_id"] + and set(requests) == set(pending["wire_ids"]) + ) + if matches_owner: + history = _requests(self._state["history"]) + matches_owner = all(history.get(key) == value for key, value in requests.items()) + if not matches_owner: raise _InvalidApproval("Pending approval authority does not match this session and response.") if record.get("phase") == "claimed": raise _InvalidApproval("Pending approval batch was already claimed; start a fresh approval turn.") diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_session_approvals.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_session_approvals.py index f07d6e694b3..a229391a820 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_session_approvals.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_session_approvals.py @@ -246,10 +246,11 @@ async def test_unsupported_canonical_version_fails_without_consumption(tmp_path, async def test_history_tampering_does_not_authorize_a_different_call(tmp_path) -> None: store = SqliteSessionStore(tmp_path / "sessions.db") session = await pending_session(store) + state = SessionApprovalState(session, store) session.state[_APPROVAL_STATE_KEY]["history"]["wire-0"] = json.dumps(approval_request(9).to_dict()) before = store.write_count with pytest.raises(_InvalidApproval, match="does not match"): - await SessionApprovalState(session, store).preflight(["wire-0", "wire-1"]) + await state.preflight(["wire-0", "wire-1"]) assert store.write_count == before From e9ecd8adb33b56c4c950b6bdbed971444928bbd2 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 11:35:44 +0100 Subject: [PATCH 34/55] Centralize deferred response event buffering --- .../_responses_agent.py | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py index 2ff590c1c40..d18c1961c1c 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py @@ -142,6 +142,12 @@ class _DeferredOutput: default_factory=lambda: list[ResponseStreamEvent | ResponseCheckpointEvent]() ) + def defer(self, event: ResponseStreamEvent | ResponseCheckpointEvent) -> bool: + if self.snapshot is None: + return False + self.events.append(event) + return True + def _validate_agent_defaults(agent: SupportsAgentRun, *, provider_background: bool, allow_agent_store: bool) -> None: validate_agent_background_options(agent, provider_background=provider_background) @@ -1149,10 +1155,8 @@ async def track_update( async for event in tracker.handle_update( update, approval_storage=approval_storage, complete_message=complete_message ): - if deferred.snapshot is None: + if not deferred.defer(event): yield event - else: - deferred.events.append(event) inner_stream: ResponseStream[AgentResponseUpdate, AgentResponse[Any]] | None = None updates: _SignalledIterator[AgentResponseUpdate] | None = None @@ -1184,19 +1188,15 @@ async def track_update( if context.shutdown.is_set() or cancellation_signal.is_set(): continue for event in tracker.close(): - if deferred.snapshot is None: + if not deferred.defer(event): yield event - else: - deferred.events.append(event) private_metadata = _hosted_internal_metadata(response_event_stream) private_metadata[_HOSTED_PROVIDER_OUTPUT_COUNT_KEY] = output_count private_metadata[_HOSTED_PROVIDER_USAGE_KEY] = tracker.usage_details if self._resilient_background: checkpoint = response_event_stream.checkpoint() - if deferred.snapshot is None: + if not deferred.defer(checkpoint): yield checkpoint - else: - deferred.events.append(checkpoint) else: inner_stream = agent.run(stream=True, **run_kwargs) # type: ignore[reportUnknownMemberType] updates = _SignalledIterator(inner_stream, context.shutdown, cancellation_signal) From 2975070212d4bdb4e7203f85442440ddddb89ef6 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 11:37:36 +0100 Subject: [PATCH 35/55] Consolidate redundant storage and steering tests --- .../foundry_hosting/test_custom_storage_sample.py | 15 ++------------- .../foundry_hosting/tests/test_responses.py | 8 -------- 2 files changed, 2 insertions(+), 21 deletions(-) diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_custom_storage_sample.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_custom_storage_sample.py index 3f6821f1e6f..324be59f687 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_custom_storage_sample.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_custom_storage_sample.py @@ -196,19 +196,6 @@ async def test_cosmos_uses_server_conditions(sample: ModuleType) -> None: assert all("/" not in item_id for _, item_id in container.items) -async def test_cosmos_missing_ack_revision_fails(sample: ModuleType) -> None: - container = FakeContainer() - container.acknowledgement_etag = None - store = cosmos_store(sample, container) - with pytest.raises(RuntimeError, match="ETag"): - await store.compare_and_set(_APPROVAL_KEY, make_session("one"), expected_revision=None) - stored, revision = await store.get_with_revision(_APPROVAL_KEY) - assert stored is not None and stored.state["value"] == "one" - assert revision - with pytest.raises(RuntimeError): - await store.compare_and_set(_APPROVAL_KEY, make_session("duplicate"), expected_revision=None) - - @pytest.mark.parametrize("condition", ["*", '"stale","1"']) async def test_cosmos_fake_models_non_exact_if_match(sample: ModuleType, condition: str) -> None: container = FakeContainer() @@ -286,6 +273,8 @@ async def test_cosmos_rejects_invalid_write_acknowledgement(sample: ModuleType, stored, revision = await store.get_with_revision(_APPROVAL_KEY) assert stored is not None and stored.state["value"] == "one" assert revision + with pytest.raises(RuntimeError): + await store.compare_and_set(_APPROVAL_KEY, make_session("duplicate"), expected_revision=None) async def test_cosmos_rejects_invalid_cached_delete_etag(sample: ModuleType) -> None: diff --git a/python/packages/foundry_hosting/tests/test_responses.py b/python/packages/foundry_hosting/tests/test_responses.py index 189792ca013..da06c6eba18 100644 --- a/python/packages/foundry_hosting/tests/test_responses.py +++ b/python/packages/foundry_hosting/tests/test_responses.py @@ -1895,14 +1895,6 @@ def test_init_rejects_resilient_background_for_non_workflow_agent(self, tmp_path enable_background_recovery=True, ) - def test_init_rejects_steerable_conversations(self) -> None: - with pytest.raises(TypeError, match="options is no longer a supported host setting"): - ResponsesHostServer( - _make_agent(), - response_store=InMemoryResponseProvider(), - options=ResponsesServerOptions(steerable_conversations=True), - ) - def test_steering_rejected_before_enabling_task_manager_or_starting_host(self) -> None: agent_factory = MagicMock() From dbbb27da2ca0b4c646659320c615a48d9e004698 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 11:37:36 +0100 Subject: [PATCH 36/55] Remove repeated hosting guidance --- .../0055-python-foundry-hosting-contracts.md | 1 + python/packages/foundry_hosting/README.md | 38 +++---------------- .../_invocations_agent.py | 4 +- .../_responses_agent.py | 16 +++----- 4 files changed, 13 insertions(+), 46 deletions(-) diff --git a/docs/decisions/0055-python-foundry-hosting-contracts.md b/docs/decisions/0055-python-foundry-hosting-contracts.md index c58679f5cbc..80630c7f287 100644 --- a/docs/decisions/0055-python-foundry-hosting-contracts.md +++ b/docs/decisions/0055-python-foundry-hosting-contracts.md @@ -37,6 +37,7 @@ Choose separate agent and native workflow hosts. Share protocol internals, but k configuration, and state ownership specific to each execution model. The decisions below define the intended hosting contracts, not the implementation status of each feature. +See the [Foundry Hosting README](../../python/packages/foundry_hosting/README.md) for the current usage contract. ### Host boundaries diff --git a/python/packages/foundry_hosting/README.md b/python/packages/foundry_hosting/README.md index 33b0859345c..5195838f783 100644 --- a/python/packages/foundry_hosting/README.md +++ b/python/packages/foundry_hosting/README.md @@ -2,10 +2,7 @@ This package provides the integration of Agent Framework agents and workflows with the Foundry Agent Server, which can be hosted on Foundry infrastructure. -Implementation is grouped by protocol: `_responses_agent.py` and `_responses_workflow.py` define the Responses hosts, -and `_responses_shared.py` contains their wire and streaming helpers. Invocations uses the same `_invocations_agent.py`, -`_invocations_workflow.py`, and `_invocations_shared.py` layout. Cross-protocol request contracts, option validation, -and agent/workflow factories live in `_shared.py`. Applications use the public package imports below. +See [ADR 0055](../../../docs/decisions/0055-python-foundry-hosting-contracts.md) for the design rationale. ## Choose the host @@ -107,27 +104,9 @@ surfaces described above. ## Responses route prefix `ResponsesHostServer` and `ResponsesWorkflowHostServer` pass `prefix` to the -[AgentServer Responses host](https://learn.microsoft.com/python/api/azure-ai-agentserver-responses/azure.ai.agentserver.responses.responsesagentserverhost?view=azure-python). -The native workflow host binds its create route at the same prefix. For example, with the -[request-aware factory below](#agent-instances-and-factories): - -```python -server = ResponsesHostServer(agent=create_agent, prefix="api/v1") -``` - -AgentServer applies the prefix to its Responses routes: - -| Operation | Default prefix (`""`) | `prefix="api/v1"` | -| --- | --- | --- | -| Create a response | `POST /responses` | `POST /api/v1/responses` | -| Retrieve a response | `GET /responses/{response_id}` | `GET /api/v1/responses/{response_id}` | -| Cancel a background response | `POST /responses/{response_id}/cancel` | `POST /api/v1/responses/{response_id}/cancel` | -| Delete a stored response | `DELETE /responses/{response_id}` | `DELETE /api/v1/responses/{response_id}` | -| List input items | `GET /responses/{response_id}/input_items` | `GET /api/v1/responses/{response_id}/input_items` | - -Use the same path prefix in clients and any reverse proxy. See the -[AgentServer protocol endpoints](https://learn.microsoft.com/python/api/overview/azure/ai-agentserver-responses-readme?view=azure-python#protocol-endpoints) -for the endpoint behavior and requirements. +[AgentServer Responses host](https://learn.microsoft.com/python/api/azure-ai-agentserver-responses/azure.ai.agentserver.responses.responsesagentserverhost?view=azure-python), +so clients and reverse proxies must use the same path prefix for its +[protocol endpoints](https://learn.microsoft.com/python/api/overview/azure/ai-agentserver-responses-readme?view=azure-python#protocol-endpoints). ## Toolbox tool approvals @@ -348,12 +327,7 @@ add a transient in-memory provider to support function-call loops, but **never e The host owns the provided agent instance and any providers it adds; do not reuse it with another host. A factory creates an independent agent for each request. -The existing `history_source="agent_managed"` still preserves the agent's own provider **or** service storage defaults -on stored requests, including `default_options={"store": True}`. Custom `SupportsAgentRun` -implementations can continue using that mode for stored requests; it is not a forced-provider mode. -The outer storage-backend constructor argument is `response_store=`. The old `store=` backend -argument is rejected, including `None` and calls that also supply `response_store=`. -The backend selector does not set the caller's per-request `store` flag. +Custom `SupportsAgentRun` implementations can use `history_source="agent_managed"` for stored requests. `store=False` returns a one-shot response without **writing** host-managed session, conversation, or approval state; it also disables downstream service storage regardless of the developer's defaults. Unsafe custom agents, external @@ -845,8 +819,6 @@ If a connection drops after commit, retrying the same trusted user/sandbox/call replays that response's complete stored snapshot without executing the workflow or replacing its head. A different call ID starts normal turn validation and cannot retrieve that snapshot. -All native Invocations requests, including local one-shot runs, require a -request-aware workflow factory that returns a fresh graph for each request. After a newer Invocations head is durably committed, the host reclaims completed ancestor response records and checkpoints oldest-first, retaining only current, pending, active or blocked authority. Cleanup failures are logged and retried by diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py index 4ebf66e7dfa..d1862e53b4e 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py @@ -63,8 +63,8 @@ def __init__( Raises: TypeError: If the agent source, parser/hook, or heartbeat type is invalid, or removed, Responses-only, or native workflow settings are supplied. - ValueError: If the heartbeat interval is nonpositive, raw legacy output requests heartbeats, - or an injected agent has unsupported background or transport defaults. + ValueError: If the heartbeat interval is nonpositive or an injected agent has unsupported background + or transport defaults. """ if {"workflow", "checkpoint_store_provider"}.intersection(kwargs): raise TypeError("Use InvocationsWorkflowHostServer for native workflows and checkpoint storage.") diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py index d18c1961c1c..3b913632a35 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py @@ -303,10 +303,6 @@ def __init__( the host-persisted MAF `AgentSession`. With `default_options={"store": True}`, the downstream service retains history instead. - For example, after a stored response to "My name is Ada", a stored follow-up - "What is my name?" sends both turns to the model with `"host_managed"`, but - sends only the follow-up with `"inference_service"` (plus a private service continuation). - With `"agent_managed"`, the developer chooses either of those agent-owned history sources. background_source: `"host_managed"` (default) runs background work in the Responses host without invoking provider-native background APIs; `"inference_service"` opts a storing, resumable client into provider background polling and requires `history_source="inference_service"`. @@ -333,22 +329,20 @@ def __init__( The former constructor `store=` alias is rejected. Outer `response.id` is the polling/continuation handle; any inner `service_session_id` is private and never replaces it. - 1. With `history_source="host_managed"`, - the agent must not have a load-enabled history provider: the host supplies the transcript. - 2. Context providers must not keep required state only on their Python instances, + 1. Context providers must not keep required state only on their Python instances, because the hosting environment may get deactivated between requests. Provider state carried by `AgentSession`, including `InMemoryHistoryProvider` messages in `history_source="agent_managed"` mode, is persisted by the configured session store. - 3. The server owns the supplied agent instance and may add hosting-specific providers. + 2. The server owns the supplied agent instance and may add hosting-specific providers. Do not reuse the same agent with another host or invoke it directly after construction. An agent returned by a callable belongs to that request. - 4. `enable_background_recovery=True` supports regular agents configured with + 3. `enable_background_recovery=True` supports regular agents configured with `history_source="inference_service", background_source="inference_service"`. For provider background, only a saved private continuation token can be polled after a crash; a crash before the token is saved cannot be replayed safely. Other regular-agent runs are not crash-recoverable. - 5. Steering is unavailable. The upstream `options` bag and steering settings are not host parameters. - 6. A stored, named `"inference_service"` or `"agent_managed"` conversation is claimed in the scoped + 4. Steering is unavailable. The upstream `options` bag and steering settings are not host parameters. + 5. A stored, named `"inference_service"` or `"agent_managed"` conversation is claimed in the scoped session store before the agent runs. Conditional writes prevent a concurrent turn from mutating the same provider thread. If the turn fails or is cancelled, start a new conversation instead of reusing a potentially changed downstream thread. From 75369c7e8e210d95d02059588d3ca99684698ac5 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 11:52:06 +0100 Subject: [PATCH 37/55] Preserve approval preflight error boundaries --- .../_responses_agent.py | 20 ++++++++----- .../_responses_preflight.py | 27 +++++++++-------- .../foundry_hosting/test_native_responses.py | 30 +++++++++++++++++++ .../foundry_hosting/tests/test_responses.py | 27 ++++++++++++++++- 4 files changed, 83 insertions(+), 21 deletions(-) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py index 3b913632a35..59b8111f60c 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py @@ -54,6 +54,7 @@ from ._approvals import SessionApprovalState, _InvalidApproval # pyright: ignore[reportPrivateUsage] from ._feature_usage import FeatureIndex from ._responses_preflight import ( + _InvalidApprovalInput, # pyright: ignore[reportPrivateUsage] approval_controls, bind_approval_preflight, has_unresolved_input, @@ -440,21 +441,24 @@ async def _preflight_approvals( session_id = context.conversation_id or previous if session_id is None: if ids: - raise _InvalidApproval("The approval has no pending agent session.") + raise _InvalidApprovalInput("The approval has no pending agent session.") return storage = self._session_storage_provider.get_store(config=self.config, platform_context=platform_context) session = await storage.get(session_id) if session is None: if ids: - raise _InvalidApproval("The approval is unavailable in this agent session.") + raise _InvalidApprovalInput("The approval is unavailable in this agent session.") return state = SessionApprovalState(session, storage) - claim = await state.preflight(ids) + try: + claim = await state.preflight(ids) + except _InvalidApproval as exc: + raise _InvalidApprovalInput(str(exc)) from exc if claim is not None: if request.get("store") is False: - raise _InvalidApproval("Approval continuation requires store=true.") + raise _InvalidApprovalInput("Approval continuation requires store=true.") if len(items) != len(ids) or has_unresolved_input(request, items): - raise _InvalidApproval("Pending MCP approvals cannot be mixed with other input.") + raise _InvalidApprovalInput("Pending MCP approvals cannot be mixed with other input.") async def _ensure_agent_ready(self) -> None: """Lazily enter the agent's async context exactly once. @@ -957,10 +961,10 @@ async def _handle_inner_agent( approval_claim = await approval_storage.preflight(approval_ids) if approval_claim is not None: if not stored: - raise _InvalidApproval("Approval continuation requires store=true.") + raise _InvalidApprovalInput("Approval continuation requires store=true.") if len(input_items) != len(approval_ids) or has_unresolved_input(request, input_items): - raise _InvalidApproval("Pending MCP approvals cannot be mixed with other input.") - except _InvalidApproval as exc: + raise _InvalidApprovalInput("Pending MCP approvals cannot be mixed with other input.") + except (_InvalidApproval, _InvalidApprovalInput) as exc: raise _PublicResponseFailure(exc) from None approval_ready.set_result(approval_storage) provider_state = session.state.get(_HOSTED_PROVIDER_STATE_KEY) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_preflight.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_preflight.py index 760d0c0371d..d99fd812adf 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_preflight.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_preflight.py @@ -43,13 +43,16 @@ from starlette.responses import Response from starlette.routing import Route -from ._approvals import _InvalidApproval # pyright: ignore[reportPrivateUsage] from ._scope import FoundryRequestScope from ._workflow_state import FoundryWorkflowBindingStore logger = logging.getLogger(__name__) +class _InvalidApprovalInput(ValueError): + """A caller's approval controls cannot resume the current pending batch.""" + + _Preflight = Callable[[CreateResponse, ResponseContext, FoundryAgentRequestContext], Awaitable[None]] @@ -141,7 +144,7 @@ async def checked_create( token = set_request_context(platform_context) try: await preflight(parsed, context, platform_context) - except _InvalidApproval as exc: + except _InvalidApprovalInput as exc: return error_response(exc, headers, request_id=request_id) except Exception as exc: logger.error("Responses approval preflight failed (%s).", type(exc).__name__) @@ -172,7 +175,7 @@ def approval_controls(items: list[Mapping[str, Any]]) -> list[str]: continue wire_id, decision = item.get("approval_request_id"), item.get("approve") if not isinstance(wire_id, str) or not wire_id or type(decision) is not bool: - raise _InvalidApproval("An approval reply requires its exact ID and a boolean decision.") + raise _InvalidApprovalInput("An approval reply requires its exact ID and a boolean decision.") ids.append(wire_id) return ids @@ -195,7 +198,7 @@ async def preflight_workflow_approvals( previous = previous if isinstance(previous, str) and previous else None if previous is None and context.conversation_id is None: if ids: - raise _InvalidApproval("The approval has no pending workflow checkpoint.") + raise _InvalidApprovalInput("The approval has no pending workflow checkpoint.") return scope = FoundryRequestScope.from_context(host.config, platform_context, local_session_id=context.response_id) storage = FoundryWorkflowBindingStore(scope) @@ -221,7 +224,7 @@ async def preflight_workflow_approvals( or head.binding != record.binding ): if ids: - raise _InvalidApproval("The approval is unavailable in the current workflow checkpoint.") + raise _InvalidApprovalInput("The approval is unavailable in the current workflow checkpoint.") return aliases = record.approvals or {} output = record.snapshot.get("output") @@ -237,25 +240,25 @@ async def preflight_workflow_approvals( approval_ids.add(wire_id) if not approval_ids: if ids: - raise _InvalidApproval("The workflow has no pending MCP approval batch.") + raise _InvalidApprovalInput("The workflow has no pending MCP approval batch.") return if request.get("store") is False: - raise _InvalidApproval("Approval continuation requires store=true.") + raise _InvalidApprovalInput("Approval continuation requires store=true.") if has_unresolved_input(request, items): - raise _InvalidApproval("Pending workflow approvals cannot include unresolved input references.") + raise _InvalidApprovalInput("Pending workflow approvals cannot include unresolved input references.") controls: list[str] = [] for item in items: item_type = item.get("type") if item_type == "mcp_approval_response": wire_id = item.get("approval_request_id") if wire_id not in approval_ids: - raise _InvalidApproval("An approval reply must match this exact pending checkpoint.") + raise _InvalidApprovalInput("An approval reply must match this exact pending checkpoint.") elif item_type in ("function_call_output", "computer_call_output"): wire_id = item.get("call_id") if not isinstance(wire_id, str) or wire_id not in aliases or wire_id in approval_ids: - raise _InvalidApproval("A reply must match this exact pending checkpoint.") + raise _InvalidApprovalInput("A reply must match this exact pending checkpoint.") else: - raise _InvalidApproval("Pending workflow approvals cannot be mixed with new input.") + raise _InvalidApprovalInput("Pending workflow approvals cannot be mixed with new input.") controls.append(cast(str, wire_id)) if len(controls) != len(set(controls)) or set(controls) != set(aliases): - raise _InvalidApproval("Answer exactly the complete pending workflow request batch.") + raise _InvalidApprovalInput("Answer exactly the complete pending workflow request batch.") diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py index 995ccf945cd..4eb35379ef3 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py @@ -54,6 +54,7 @@ ResponsesWorkflowHostServer, WorkflowTurn, ) +from agent_framework_foundry_hosting._approvals import _InvalidApproval from agent_framework_foundry_hosting._responses_workflow import _load_replies, _WorkflowRequestError from agent_framework_foundry_hosting._workflow_state import FoundryWorkflowBindingStore, HostedWorkflowRun @@ -436,6 +437,35 @@ async def test_named_conversation_rejects_old_wire_replies_when_core_request_ids assert _texts(accepted) == ["new question:False", "new question:False"] +@pytest.mark.parametrize("stream", [False, True]) +async def test_workflow_approval_lookup_error_is_a_backend_failure(stream: bool) -> None: + server = _server(lambda request: _build(_Approvals()), parser=_parse_text) + first = await _post(server, "/safe") + approval_id = next(item["id"] for item in first["output"] if item["type"] == "mcp_approval_request") + detail = "private workflow storage failure" + + with ( + patch.object(FoundryWorkflowBindingStore, "get_response", new=AsyncMock(side_effect=_InvalidApproval(detail))), + patch.object(server._resolver, "resolve", wraps=server._resolver.resolve) as resolver, # pyright: ignore[reportPrivateUsage] + ): + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=server), base_url="http://test") as client: + response = await client.post( + "/responses", + headers={"x-agent-user-id": "user", "x-agent-foundry-call-id": "call"}, + json={ + "input": [{"type": "mcp_approval_response", "approval_request_id": approval_id, "approve": True}], + "agent_session_id": "sandbox", + "previous_response_id": first["id"], + "stream": stream, + }, + ) + + assert response.status_code == 500 + assert response.headers["x-platform-error-source"] == "upstream" + assert detail not in response.text + resolver.assert_not_called() + + @pytest.mark.parametrize("stream", [False, True]) async def test_approval_wire_ids_bind_only_to_exact_pending_checkpoint(stream: bool) -> None: provider = InMemoryResponseProvider() diff --git a/python/packages/foundry_hosting/tests/test_responses.py b/python/packages/foundry_hosting/tests/test_responses.py index da06c6eba18..1b6e718ceb1 100644 --- a/python/packages/foundry_hosting/tests/test_responses.py +++ b/python/packages/foundry_hosting/tests/test_responses.py @@ -87,7 +87,7 @@ from pydantic import TypeAdapter from agent_framework_foundry_hosting import ResponsesHostServer, ResponsesRequest -from agent_framework_foundry_hosting._approvals import SessionApprovalState +from agent_framework_foundry_hosting._approvals import SessionApprovalState, _InvalidApproval from agent_framework_foundry_hosting._responses_shared import ( _INCOMPLETE_REASON_KEY, # pyright: ignore[reportPrivateUsage] _LATEST_CHECKPOINT_ID_KEY, # pyright: ignore[reportPrivateUsage] @@ -8852,6 +8852,31 @@ async def test_backend_value_error_is_not_mapped_to_invalid_approval( assert _SESSION_STORAGE_ERROR_DETAIL not in str(response.headers) assert agent.run.call_count == 1 + @pytest.mark.parametrize("stream", [False, True]) + async def test_session_lookup_approval_error_is_a_backend_failure(self, stream: bool, tmp_path: Path) -> None: + approval = _make_function_approval_request_content() + agent = _make_agent(response=AgentResponse(messages=[Message(role="assistant", contents=[approval])])) + store = SqliteSessionStore(tmp_path / "approvals.sqlite") + server = _make_server(agent, session_store=store) + first = await _post(server) + previous_id = first.json()["id"] + approval_id = next(item["id"] for item in first.json()["output"] if item["type"] == "mcp_approval_request") + + with patch.object(store, "get", new=AsyncMock(side_effect=_InvalidApproval(_SESSION_STORAGE_ERROR_DETAIL))): + response = await _post_json( + server, + { + "input": [{"type": "mcp_approval_response", "approval_request_id": approval_id, "approve": True}], + "previous_response_id": previous_id, + "stream": stream, + }, + ) + + assert response.status_code == 500 + assert response.headers["x-platform-error-source"] == "upstream" + assert _SESSION_STORAGE_ERROR_DETAIL not in response.text + assert agent.run.call_count == 1 + @pytest.mark.parametrize("fail_alias", [False, True]) async def test_approval_events_wait_for_authority_and_session_snapshots( self, fail_alias: bool, tmp_path: Path From 4d083b0ff3265410d7e543e755462216419b154a Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 11:55:40 +0100 Subject: [PATCH 38/55] Preserve typed background guard dispatch --- .../foundry_hosting/agent_framework_foundry_hosting/_shared.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py index fae4aa3ebc1..6efe5063415 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py @@ -471,7 +471,7 @@ def background_agent_run_kwargs(agent: SupportsAgentRun, *, provider_background: guard = _PROVIDER_BACKGROUND_AGENT_OPTIONS if provider_background else _FOREGROUND_AGENT_OPTIONS return {"middleware": [guard]} kwargs: dict[str, Any] = {} - _append_background_chat_options(agent, kwargs, provider_background=provider_background) + _append_background_chat_options(cast(SupportsAgentRun, agent), kwargs, provider_background=provider_background) return {"client_kwargs": kwargs} if kwargs else {} From 20277b17adaf414d449aa6b49c60bc7df4761f32 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 11:59:43 +0100 Subject: [PATCH 39/55] Remove unused workflow approval lookup --- .../agent_framework_foundry_hosting/_responses_workflow.py | 7 ------- 1 file changed, 7 deletions(-) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py index 62dcd0981d0..4c08941d13e 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py @@ -246,13 +246,6 @@ async def save_approval_request(self, approval_request_id: str, request: Content raise _WorkflowRequestError("Approval output must match one unique request in the exact pause checkpoint.") self.aliases[approval_request_id] = matches[0] - async def load_approval_request(self, approval_request_id: str) -> Content: - request_id = self.aliases.get(approval_request_id) - event = self.pending.get(request_id) if request_id is not None else None - if event is None or not isinstance(event.data, Content): - raise _WorkflowRequestError("The approval is unavailable in this pending checkpoint.") - return event.data - async def _project( event: WorkflowEvent[Any], From 8f543032090be9138953898be8aa0681f19270b6 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 12:03:44 +0100 Subject: [PATCH 40/55] Remove approval lookup protocol --- .../_responses_shared.py | 38 ++- .../approval_translation_helpers.py | 37 +++ .../test_approval_translation.py | 229 ++++++++++++------ 3 files changed, 206 insertions(+), 98 deletions(-) create mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/approval_translation_helpers.py diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py index 254512a82b6..7d14cbf9734 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py @@ -92,19 +92,9 @@ ) from mcp import MCPError -logger = logging.getLogger(__name__) - +from ._approvals import SessionApprovalState -class _ApprovalLookup(Protocol): - """Read-only approval-request lookup used when converting stored history back to messages. - - Implementations must not consume, claim, or otherwise change approval authority; the host validates and claims - approval batches separately before protected execution. - """ - - async def load_approval_request(self, approval_request_id: str) -> Content: - """Return the original ``function_approval_request`` content for a public approval request ID.""" - ... +logger = logging.getLogger(__name__) class _ApprovalRecorder(Protocol): @@ -1690,14 +1680,14 @@ def _persist_pending_container_file_citations(self) -> None: async def _items_to_messages( # pyright: ignore[reportUnusedFunction] - input_items: Sequence[Item], *, approval_storage: _ApprovalLookup | None = None + input_items: Sequence[Item], *, approval_storage: SessionApprovalState | None = None ) -> list[Message]: """Converts a sequence of input items to a list of Messages, one per item. Args: input_items: The input items to convert. - approval_storage: An optional read-only approval lookup used to look up - approval requests when converting MCP approval response items. + approval_storage: Optional session-backed approval state used to read + approval requests without consuming their authority. Returns: A list of Messages, one per supported input item. @@ -1799,15 +1789,15 @@ def _shell_command_output_to_content(output: Mapping[str, Any]) -> Content: async def _item_to_message( item: Item, *, - approval_storage: _ApprovalLookup | None = None, + approval_storage: SessionApprovalState | None = None, _item_type_name: Literal["Item", "OutputItem"] = "Item", ) -> Message: """Converts an Item to a Message. Args: item: The Item to convert. - approval_storage: An optional read-only approval lookup used to look up - approval requests when converting MCP approval response items. + approval_storage: Optional session-backed approval state used to read + approval requests without consuming their authority. _item_type_name: The item type name to include in unsupported-type errors. Returns: @@ -2103,14 +2093,14 @@ async def _item_to_message( async def _output_items_to_messages( # pyright: ignore[reportUnusedFunction] history: Sequence[OutputItem], *, - approval_storage: _ApprovalLookup | None = None, + approval_storage: SessionApprovalState | None = None, ) -> list[Message]: """Converts a sequence of OutputItem objects to a list of Message objects. Args: history (Sequence[OutputItem]): The sequence of OutputItem objects to convert. - approval_storage (_ApprovalLookup | None, optional): The approval storage to use for - resolving MCP approval requests. Defaults to None. + approval_storage: Optional session-backed approval state used to read + approval requests without consuming their authority. Returns: list[Message]: The list of Message objects. @@ -2121,13 +2111,13 @@ async def _output_items_to_messages( # pyright: ignore[reportUnusedFunction] return messages -async def _output_item_to_message(item: OutputItem, *, approval_storage: _ApprovalLookup | None = None) -> Message: +async def _output_item_to_message(item: OutputItem, *, approval_storage: SessionApprovalState | None = None) -> Message: """Converts an OutputItem to a Message. Args: item (OutputItem): The OutputItem to convert. - approval_storage (_ApprovalLookup | None, optional): The approval storage to use for - resolving MCP approval requests. Defaults to None. + approval_storage: Optional session-backed approval state used to read + approval requests without consuming their authority. Returns: Message: The converted Message. diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/approval_translation_helpers.py b/python/packages/foundry_hosting/tests/foundry_hosting/approval_translation_helpers.py new file mode 100644 index 00000000000..d737f259a3e --- /dev/null +++ b/python/packages/foundry_hosting/tests/foundry_hosting/approval_translation_helpers.py @@ -0,0 +1,37 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Helpers for Responses approval translation tests.""" + +from __future__ import annotations + +from collections.abc import AsyncIterator, Mapping +from typing import Any + +from agent_framework import Content + + +def _approval_request(request_id: str = "orig-1") -> Content: + return Content.from_function_approval_request( + id=request_id, + function_call=Content.from_function_call("call-1", "dangerous", arguments='{"x": 1}'), + ) + + +class _OrderedRecorder: + def __init__(self, log: list[str]) -> None: + self._log = log + self.saved: list[tuple[str, Content]] = [] + + async def save_approval_request(self, approval_request_id: str, request: Content) -> None: + self._log.append(f"save:{approval_request_id}") + self.saved.append((approval_request_id, request)) + + +def _event_type(event: Any) -> str: + event_type = event.get("type") if isinstance(event, Mapping) else event.type # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType] + assert isinstance(event_type, str) + return event_type + + +async def _events_without_id(*_: Any, **__: Any) -> AsyncIterator[dict[str, Any]]: + yield {"type": "response.output_item.added", "item": {"type": "mcp_approval_request"}} diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_approval_translation.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_approval_translation.py index 879fe347dd6..40b2dec74a1 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_approval_translation.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_approval_translation.py @@ -1,68 +1,140 @@ # Copyright (c) Microsoft. All rights reserved. -"""Responses approval translation against the read-only lookup and staging recorder protocols.""" +"""Responses approval translation and output staging.""" from __future__ import annotations -from collections.abc import Mapping +from copy import deepcopy +from pathlib import Path from typing import Any import pytest -from agent_framework import Content +from agent_framework import AgentSession from azure.ai.agentserver.responses.aio import ResponseEventStream from azure.ai.agentserver.responses.models import ( + Item, + ItemMcpApprovalRequest, + MCPApprovalResponse, + OutputItem, OutputItemMcpApprovalRequest, OutputItemMcpApprovalResponseResource, ) +from agent_framework_foundry_hosting._approvals import SessionApprovalState from agent_framework_foundry_hosting._responses_shared import ( + _items_to_messages, _output_items_to_messages, _OutputItemTracker, _PublicResponseFailure, ) - -def _approval_request(request_id: str = "orig-1") -> Content: - return Content.from_function_approval_request( - id=request_id, - function_call=Content.from_function_call("call-1", "dangerous", arguments='{"x": 1}'), - ) - - -class _RecordingLookup: - """Read-only lookup that records every access and exposes no mutating method.""" - - def __init__(self, requests: Mapping[str, Content]) -> None: - self._requests = dict(requests) - self.loads: list[str] = [] - - async def load_approval_request(self, approval_request_id: str) -> Content: - self.loads.append(approval_request_id) - return self._requests[approval_request_id] +from .approval_helpers import ( # pyrefly: ignore[missing-import] - pytest's importlib namespace + SqliteSessionStore, + approval_request, + pending_session, +) +from .approval_translation_helpers import ( # pyrefly: ignore[missing-import] - pytest's importlib namespace + _approval_request, + _event_type, + _events_without_id, + _OrderedRecorder, +) -class _OrderedRecorder: - def __init__(self, log: list[str]) -> None: - self._log = log - self.saved: list[tuple[str, Content]] = [] +@pytest.mark.parametrize("approved", [True, False]) +async def test_history_and_input_conversions_only_read_approval_state(tmp_path: Path, approved: bool) -> None: + store = SqliteSessionStore(tmp_path / "sessions.db") + session = await pending_session(store) + state = SessionApprovalState(session, store) + token = await state.preflight(["wire-0", "wire-1"]) + assert token is not None + session_before = deepcopy(session.to_dict()) + writes_before = store.write_count + stored_before: dict[str, tuple[dict[str, Any], str | None]] = {} + for key in ("response-alias", "conversation-alias", token.authority_id): + stored, revision = await store.get_with_revision(key) + assert stored is not None + stored_before[key] = (stored.to_dict(), revision) + + output_items: list[OutputItem] = [ + OutputItemMcpApprovalRequest({ + "type": "mcp_approval_request", + "id": "wire-0", + "server_label": "untrusted", + "name": "untrusted", + "arguments": '{"index": 999}', + }), + OutputItemMcpApprovalResponseResource({ + "type": "mcp_approval_response", + "id": "resp-1", + "approval_request_id": "wire-0", + "approve": approved, + }), + ] + input_items: list[Item] = [ + ItemMcpApprovalRequest({ + "type": "mcp_approval_request", + "id": "wire-0", + "server_label": "untrusted", + "name": "untrusted", + "arguments": '{"index": 999}', + }), + MCPApprovalResponse({ + "type": "mcp_approval_response", + "approval_request_id": "wire-0", + "approve": approved, + }), + ] - async def save_approval_request(self, approval_request_id: str, request: Content) -> None: - self._log.append(f"save:{approval_request_id}") - self.saved.append((approval_request_id, request)) + output_messages = await _output_items_to_messages(output_items, approval_storage=state) + input_messages = await _items_to_messages(input_items, approval_storage=state) + + for messages in (output_messages, input_messages): + assert [message.role for message in messages] == ["assistant", "user"] + request = messages[0].contents[0] + response = messages[1].contents[0] + assert request == approval_request() + assert response.type == "function_approval_response" + assert response.id == "approval-0" + assert response.approved is approved + assert response.function_call == request.function_call + + assert session.to_dict() == session_before + assert store.write_count == writes_before + assert await state.preflight(["wire-0", "wire-1"]) == token + for key, expected in stored_before.items(): + stored, revision = await store.get_with_revision(key) + assert stored is not None + assert (stored.to_dict(), revision) == expected + + +async def test_partial_input_conversion_does_not_consume_pending_approvals(tmp_path: Path) -> None: + store = SqliteSessionStore(tmp_path / "sessions.db") + session = await pending_session(store) + state = SessionApprovalState(session, store) + token = await state.preflight(["wire-0", "wire-1"]) + assert token is not None + session_before = deepcopy(session.to_dict()) + writes_before = store.write_count + items: list[Item] = [ + MCPApprovalResponse({"type": "mcp_approval_response", "approval_request_id": "wire-0", "approve": True}), + MCPApprovalResponse({"type": "mcp_approval_response", "approval_request_id": "missing", "approve": False}), + ] + with pytest.raises(_PublicResponseFailure, match="not in this session's history"): + await _items_to_messages(items, approval_storage=state) -def _event_type(event: Any) -> str: - event_type = event.get("type") if isinstance(event, Mapping) else event.type # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType] - assert isinstance(event_type, str) - return event_type + assert session.to_dict() == session_before + assert store.write_count == writes_before + assert await state.preflight(["wire-0", "wire-1"]) == token -async def test_history_conversion_only_reads_approval_requests() -> None: - lookup = _RecordingLookup({"wire-1": _approval_request()}) - items = [ +@pytest.mark.parametrize( + "item", + [ OutputItemMcpApprovalRequest({ "type": "mcp_approval_request", - "id": "wire-1", + "id": "missing", "server_label": "srv", "name": "dangerous", "arguments": "{}", @@ -70,43 +142,55 @@ async def test_history_conversion_only_reads_approval_requests() -> None: OutputItemMcpApprovalResponseResource({ "type": "mcp_approval_response", "id": "resp-1", - "approval_request_id": "wire-1", - "approve": False, + "approval_request_id": "missing", + "approve": True, }), - ] - - messages = await _output_items_to_messages(items, approval_storage=lookup) # type: ignore[arg-type] - - assert lookup.loads == ["wire-1", "wire-1"] - assert not hasattr(lookup, "save_approval_request") - assert messages[0].contents[0].type == "function_approval_request" - assert messages[1].contents[0].type == "function_approval_response" - assert messages[1].contents[0].approved is False - - -async def test_history_conversion_rejects_unknown_approval_ids() -> None: - lookup = _RecordingLookup({}) - item = OutputItemMcpApprovalResponseResource({ - "type": "mcp_approval_response", - "id": "resp-1", - "approval_request_id": "missing", - "approve": True, - }) - - with pytest.raises(_PublicResponseFailure): - await _output_items_to_messages([item], approval_storage=lookup) # type: ignore[arg-type] - - -async def test_history_conversion_requires_lookup() -> None: - item = OutputItemMcpApprovalResponseResource({ - "type": "mcp_approval_response", - "id": "resp-1", - "approval_request_id": "wire-1", - "approve": True, - }) - + ], + ids=["request", "response"], +) +async def test_history_conversion_rejects_unknown_approval_ids(item: OutputItem) -> None: + state = SessionApprovalState(AgentSession(), None) + + with pytest.raises(_PublicResponseFailure, match="not in this session's history"): + await _output_items_to_messages([item], approval_storage=state) + + +@pytest.mark.parametrize( + ("input_item", "output_item"), + [ + ( + ItemMcpApprovalRequest({ + "type": "mcp_approval_request", + "id": "wire-1", + "server_label": "srv", + "name": "dangerous", + "arguments": "{}", + }), + OutputItemMcpApprovalRequest({ + "type": "mcp_approval_request", + "id": "wire-1", + "server_label": "srv", + "name": "dangerous", + "arguments": "{}", + }), + ), + ( + MCPApprovalResponse({"type": "mcp_approval_response", "approval_request_id": "wire-1", "approve": True}), + OutputItemMcpApprovalResponseResource({ + "type": "mcp_approval_response", + "id": "resp-1", + "approval_request_id": "wire-1", + "approve": True, + }), + ), + ], + ids=["request", "response"], +) +async def test_approval_conversion_requires_session_state(input_item: Item, output_item: OutputItem) -> None: with pytest.raises(ValueError, match="ApprovalStorage is required"): - await _output_items_to_messages([item]) + await _items_to_messages([input_item]) + with pytest.raises(ValueError, match="ApprovalStorage is required"): + await _output_items_to_messages([output_item]) async def test_tracker_records_approval_before_yielding_its_events() -> None: @@ -135,9 +219,6 @@ async def test_tracker_fails_explicitly_without_generated_approval_id(monkeypatc stream.emit_created() stream.emit_in_progress() - async def _events_without_id(*_: Any, **__: Any) -> Any: - yield {"type": "response.output_item.added", "item": {"type": "mcp_approval_request"}} - monkeypatch.setattr(stream, "output_item_mcp_approval_request", _events_without_id) tracker = _OutputItemTracker(stream) recorder = _OrderedRecorder([]) From 4cb7d154bfa5066cb52a3b85811f58a0237aa045 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 12:07:08 +0100 Subject: [PATCH 41/55] Clarify factory resource lifecycle limits --- .../0055-python-foundry-hosting-contracts.md | 14 ++++++--- python/packages/foundry_hosting/README.md | 30 +++++++++++++------ .../foundry-hosted-agents/README.md | 7 +++-- .../responses/azure_search_rag/README.md | 8 +++-- .../responses/custom_storage/README.md | 7 +++-- .../responses/files/README.md | 8 ++--- .../responses/foundry_memory/README.md | 6 ++-- .../responses/foundry_toolbox/README.md | 15 +++++----- .../foundry_toolbox_mcp_skills/README.md | 14 +++++---- .../responses/mcp/README.md | 5 ++-- .../responses/monty_codeact/README.md | 5 ++-- .../responses/observability/README.md | 5 ++-- .../responses/tools/README.md | 8 +++-- 13 files changed, 82 insertions(+), 50 deletions(-) diff --git a/docs/decisions/0055-python-foundry-hosting-contracts.md b/docs/decisions/0055-python-foundry-hosting-contracts.md index 80630c7f287..7633ed1f576 100644 --- a/docs/decisions/0055-python-foundry-hosting-contracts.md +++ b/docs/decisions/0055-python-foundry-hosting-contracts.md @@ -79,9 +79,14 @@ clients, providers, and mutable tools. A new graph wrapper around shared executo Reject known shared execution resources rather than cloning them. This guard cannot prove that arbitrary application globals are isolated. Keep workflow names and executor IDs stable for checkpoint restoration. -Close factory-owned context-managed agents for the request, including failure and cancellation cleanup. -Applications own cleanup of other resources they create; caller-owned shared resources must not be closed. -State needed across requests belongs in supported stores, not request-owned instance fields. +Unwind successfully entered factory-agent contexts when a request finishes, fails, or is cancelled. +`Agent` also unwinds client and MCP contexts already entered if a later context fails to enter. +Allocations before agent entry and partial allocations from a failed client `__aenter__` may not be +cleaned up; calling `agent.close()` before entry does not dispose an unentered client. +Applications own cleanup of other resources they create. An entered caller-supplied context-managed +client can be closed on agent exit; ownership depends on its context contract, and the host cannot +reliably identify shared clients on first use. State needed across requests belongs in supported stores, +not request-owned instance fields. ### Persistence and history ownership @@ -199,7 +204,8 @@ These decisions do not redesign Core, concurrency, checkpoints, retries, or exte ## Validation Cover public imports and signatures, invalid construction before SDK side effects, sync/async factory -invocation, failure/cancellation cleanup, and rejection of shared workflow resources. +invocation, cleanup of successfully entered contexts on failure/cancellation, and rejection of shared +workflow resources. Exercise streaming and non-streaming execution, session/checkpoint continuation, pending replies, and model-free process crash/recovery. Validate maintained samples against public exports. Offline checks do not establish live Foundry deployment compatibility. diff --git a/python/packages/foundry_hosting/README.md b/python/packages/foundry_hosting/README.md index 5195838f783..4da74d6a6bf 100644 --- a/python/packages/foundry_hosting/README.md +++ b/python/packages/foundry_hosting/README.md @@ -261,6 +261,8 @@ state. This is not an exactly-once guarantee for external tools: make side-effecting operations idempotent. Legacy unscoped workflow state is not read; migration starts a fresh Responses chain. +### Factory resource lifecycle + For Responses integrations, use a factory when a provider, tool cache, client or credential carries request identity or needs request-owned cleanup. `FoundryToolbox` resolves platform headers at each operation boundary and @@ -269,15 +271,23 @@ not retain the first request's call ID. The integration samples still construct it inside the factory because they also own request-scoped clients, credentials and providers. -Factory agents are entered/exited for each request, including failed entry and -cancellation. `Agent` manages context-managed clients and MCP tools, but it does -not automatically manage every context provider or external credential. The +The host unwinds successfully entered factory-agent contexts when a request +finishes, fails or is cancelled. `Agent` also unwinds client and MCP contexts +it has entered if a later context fails to enter. Allocations made before agent +entry and partial allocations from a failed client `__aenter__` may not be +cleaned up. Calling `agent.close()` before entry does not dispose an unentered +client. + +`Agent` manages context-managed clients and MCP tools, but it does not +automatically manage every context provider or external credential. Exiting an +entered `Agent` can close a caller-supplied context-managed client; ownership +depends on the client's context contract. The host cannot reliably identify a +shared client on first use, so applications must ensure that shared clients +support the agent's entry and exit behavior. The [integration samples](../../samples/04-hosting/foundry-hosted-agents/) explicitly own their SDK transports, credentials and providers: Search is request-owned; Memory binds a fresh provider/project client to the trusted user and current call; custom Cosmos state uses user **and** sandbox namespaces with conditional writes. -Only close resources that the factory creates and owns, never a supplied shared -client or somebody else's credential. ## Responses agent history and storage @@ -771,10 +781,12 @@ A sync/async `build_workflow(request)` factory returns a **built**, fresh `Workf with stable name, executor IDs and graph identity. Build fresh executors, agents, clients, providers and mutable tools for each request. Allocation must not execute tools or workflow side effects. Both hosted and local workflows require a factory; built instances -are rejected at construction. Factory-owned agents are entered and -closed per turn; applications must explicitly own external credentials/providers -through their resource-managing agent subclasses. Do not configure another -checkpoint store on `WorkflowBuilder` or share mutable graphs between requests. +are rejected at construction. Successfully entered factory-agent contexts are +unwound per turn; see [factory resource lifecycle](#factory-resource-lifecycle) +for the pre-entry and client-ownership limits. Applications must explicitly own +external credentials and providers through their resource-managing agent +subclasses. Do not configure another checkpoint store on `WorkflowBuilder` or +share mutable graphs between requests. Native `AgentExecutor` graphs support `Agent` and constrained bare `RawAgent`. For `Agent`, hosting applies options through a request-owned agent middleware diff --git a/python/samples/04-hosting/foundry-hosted-agents/README.md b/python/samples/04-hosting/foundry-hosted-agents/README.md index b994e07f73b..abfc055efe7 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/README.md @@ -36,8 +36,11 @@ The integration examples use **request-owned factories** and the current `history_source="host_managed"` API. Use the current workspace, or a hosting release containing that API; before the coordinated beta is published, older PyPI wheels are not evidence that the examples include these behaviors. -Toolbox/skills connections inherit the current request's call ID and are closed -afterward. Files and custom MAF state are sandbox-specific; Foundry Memory +Toolbox/skills connections inherit the current request's call ID; entered +contexts are unwound after the request. Pre-entry allocations and partial +allocations from failed client entry may not be cleaned up. See +[factory resource lifecycle](../../../packages/foundry_hosting/README.md#factory-resource-lifecycle). +Files and custom MAF state are sandbox-specific; Foundry Memory intentionally shares long-term memories across the **same user's** sandboxes. Their READMEs document the external resource/permission boundaries. GitHub MCP PAT/OAuth and Telegram/Key Vault require separate setup; the diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/azure_search_rag/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/azure_search_rag/README.md index 0209037e016..b7188b5a8ad 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/azure_search_rag/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/azure_search_rag/README.md @@ -15,9 +15,11 @@ The agent uses `FoundryChatClient` from the Agent Framework to create a Response See [main.py](main.py) for the full implementation. `create_agent` allocates a fresh Search provider, credential and model client for -each request. The sample's context-managed client explicitly enters/closes the -provider and closes its own SDK transports and credential, including failed -entry and cancellation; `Agent` does not automatically enter every provider. +each request. Once entered, the sample's client context closes the provider and +its own SDK transports and credential on exit. The client also attempts cleanup +if Search provider entry fails; `Agent` does not automatically enter every +provider. If the request ends before client entry, those allocations may not be +cleaned up. `history_source="host_managed"` owns conversation history and disables inner model storage. Only first-party Foundry model calls receive the platform call ID; it is not forwarded to Search as an authorization substitute. diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md index 556180712c1..8b1072e95e6 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md @@ -156,9 +156,10 @@ does not access/write this custom session store. For hosted use, configure the endpoint/database/container in the manifest and follow the [parent deployment instructions](../../README.md#deploying-the-agent-to-foundry). -The provider closes the Cosmos client and its own credential at shutdown; -request clients are closed after their request, including failed tool entry and -cancellation. +The provider closes the Cosmos client and its own credential at shutdown. +After a request client enters, its context closes its own transports and +credential on exit, including cancellation. If a request ends before client +entry, those allocations may not be cleaned up. Live Cosmos access and deployment need separately approved resources and permissions. diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/files/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/files/README.md index 9efc115b127..3405b693610 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/files/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/files/README.md @@ -24,10 +24,10 @@ Set `FOUNDRY_PROJECT_ENDPOINT` and `FOUNDRY_MODEL`, plus either see the [Toolbox sample](../foundry_toolbox/). Authenticate local runs with `az login`. Deployed runs use the sandbox's managed identity. -`ResponsesHostServer(agent=create_agent, history_source="host_managed")` creates -fresh clients and a Toolbox MCP connection for each request and closes their -transports afterward. This request-owned lifecycle gives the sample a clear -cleanup boundary; `FoundryToolbox` also rebinds its MCP session to current +`ResponsesHostServer(agent=create_agent, history_source="host_managed")` uses a +factory that creates a fresh client and Toolbox configuration for the request. +Successfully entered contexts are unwound after the request; pre-entry allocations +may not be cleaned up. `FoundryToolbox` also rebinds its MCP session to current platform headers if an instance is reused across requests. The outer Responses service supplies history; the host disables downstream model storage. An outer `store=false` request writes no host-managed state, but does not undo external diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_memory/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_memory/README.md index 315e3d92308..61f7ed9a260 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_memory/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_memory/README.md @@ -20,9 +20,9 @@ The request-aware `create_agent` factory builds a new agent, credential, project client and Memory provider **inside each request**. Chat and Memory share that request's project client, not a process-wide client. Its headers capture the current platform call ID for both Memory and model calls; raw user IDs are not -forwarded. The request-owned client's context manager closes its own OpenAI and -project transports and credential on completion or cancellation. It does not -change ownership of developer-supplied clients elsewhere in the framework. +forwarded. Once entered, the request-owned client context closes its own OpenAI +and project transports and credential on completion or cancellation. Host cleanup +may not cover allocations when a request ends before client entry. The Memory namespace is a framed hash of the **trusted platform user ID**. It intentionally excludes the sandbox, conversation, MAF session and call IDs: the diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md index 53a5e22a9bd..179f0a7ecdf 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md @@ -100,16 +100,17 @@ See [main.py](main.py) for the full implementation. ### Request-owned resources The host receives `agent=create_agent`, not a process-wide agent instance. -Every request creates a fresh client and Toolbox MCP connection, then closes -them afterward. This gives the sample one clear owner for its model transports, -credential and Toolbox lifecycle. `FoundryToolbox` also supports long-lived -instances: it resolves the current platform headers before each operation and +The factory creates a fresh client and Toolbox configuration for the request. +Successfully entered contexts are unwound after the request. `FoundryToolbox` +also supports long-lived instances: it resolves the current platform headers before each operation and reconnects the MCP session when that identity changes, so a shared instance does not retain an earlier caller's `x-agent-foundry-call-id`. -The sample client closes only its own model/project transports and credential, -including when MCP entry fails or the request is cancelled. Local authentication -uses `AzureCliCredential`; deployed authentication uses managed identity. +After entry, the sample client context closes its own model/project transports +and credential on exit, including if later MCP entry fails or the request is +cancelled. If the request ends before client entry, those allocations may not +be cleaned up. Local authentication uses `AzureCliCredential`; deployed +authentication uses managed identity. `history_source="host_managed"` reconstructs the outer Responses transcript and disables inner model storage. Caller `store=false` prevents host-managed state, not external tool side effects. diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox_mcp_skills/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox_mcp_skills/README.md index c91b2c273bb..01290146ae5 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox_mcp_skills/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox_mcp_skills/README.md @@ -33,18 +33,20 @@ The `FoundryToolbox` is attached to the agent and its skills are exposed through The agent is hosted with the `ResponsesHostServer`, which provisions a REST API endpoint compatible with the OpenAI Responses protocol on `http://localhost:8088`. -`agent=create_agent` builds a new Toolbox, skills provider/cache, credential and -client for **each request**, giving those resources one deterministic owner and -cleanup boundary. `FoundryToolbox` also scopes tool and skill-resource +The `create_agent` factory builds a new Toolbox, skills provider/cache, credential +and client for the request. Successfully entered contexts are unwound after the +request. `FoundryToolbox` also scopes tool and skill-resource operations to the current platform call ID when an instance is reused, rebinding its MCP session when that identity changes. `tools=` still connects the Toolbox and `context_providers=` still reads skills from that same session; both are required. Only loading the vetted sample skill body is auto-approved, not arbitrary skill scripts or external actions. -The factory's client context closes its owned SDK transports and credential -after completion, failed tool entry or cancellation. Local runs use -`AzureCliCredential`; hosted runs use managed identity. +After entry, the factory's client context closes its owned SDK transports and +credential on exit, including if later tool entry fails or the request is +cancelled. If the request ends before client entry, those allocations may not +be cleaned up. +Local runs use `AzureCliCredential`; hosted runs use managed identity. `history_source="host_managed"` owns conversation history and disables inner model storage. Scope the configured Toolbox/skill resources and RBAC to the intended project; a fresh provider is not an external authorization boundary. diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/mcp/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/mcp/README.md index bd619918241..b9ca92e049a 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/mcp/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/mcp/README.md @@ -10,8 +10,9 @@ The agent uses `FoundryChatClient` from the Agent Framework to create an OpenAI- See [main.py](main.py) for the full implementation. -`agent=create_agent` creates fresh client and hosted-MCP tool configuration for -each request and closes the request's own SDK transports and credential. +The `create_agent` factory creates fresh client and hosted-MCP tool configuration +for the request. Once entered, the client context closes its own SDK transports +and credential on exit; pre-entry allocations may not be cleaned up. Local model authentication uses `AzureCliCredential`; deployed calls use managed identity. `history_source="host_managed"` supplies the outer transcript and disables inner model storage. diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/monty_codeact/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/monty_codeact/README.md index 7bf5d5fb7e8..0950921ab37 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/monty_codeact/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/monty_codeact/README.md @@ -24,8 +24,9 @@ See [main.py](main.py) for the full implementation. `ResponsesHostServer(agent=create_agent, history_source="host_managed")` constructs a fresh CodeAct provider, client and credential for each request. No interpreter/provider instance, tool connection or model client is reused -from an earlier caller. The factory's client context closes its owned SDK -transports and credential after the request. Local calls use +from an earlier caller. Once entered, the factory's client context closes its +owned SDK transports and credential on exit; pre-entry allocations may not be +cleaned up. Local calls use `AzureCliCredential`; hosted calls use managed identity. The host supplies conversation history and disables inner model storage. The diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/observability/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/observability/README.md index 4801a2ac3fd..43a0a186ee6 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/observability/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/observability/README.md @@ -25,8 +25,9 @@ a production default. Never log platform identity values or tokens. The host receives `agent=create_agent` and builds a new client/credential for each request, capturing only that request's first-party platform headers. Native OpenTelemetry context propagation links spans to the incoming request rather -than a preceding caller. The context-managed sample client closes its own SDK -transports and credential after the request. Local authentication uses +than a preceding caller. Once entered, the sample client context closes its own +SDK transports and credential on exit; pre-entry allocations may not be cleaned +up. Local authentication uses `AzureCliCredential`; hosted authentication uses managed identity. `history_source="host_managed"` owns the outer transcript and disables inner model storage. diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/tools/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/tools/README.md index 49a1d4b3da0..f3b138aa886 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/tools/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/tools/README.md @@ -24,9 +24,11 @@ When a tool is set to `always_require`, the agent host emits an `mcp_approval_re The agent is hosted using the [Agent Framework](https://github.com/microsoft/agent-framework) with the `ResponsesHostServer`, which provisions a REST API endpoint compatible with the OpenAI Responses protocol. -The host uses `agent=create_agent` and `history_source="host_managed"`. Each -request receives its own client and credential; their owned transports are -closed afterward. History and approval continuation remain in the host's +The host uses `agent=create_agent` and `history_source="host_managed"`. The +factory creates a client and credential for the request. Once entered, the client +context closes its owned transports on exit; pre-entry allocations may not be +cleaned up. +History and approval continuation remain in the host's trusted user/sandbox-scoped stores, not on a reused agent instance. A fresh factory does not remove pending approvals: return the approval response with the same outer continuation and sandbox. `store=false` cannot establish a From 0bf85c9988e464990452f4f18b8155d0cf2da6e0 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 12:33:52 +0100 Subject: [PATCH 42/55] Python: Remove CAS approval authority; keep session approval request map Drop the SessionApprovalState pending/seal/preflight/claim authority, the separate authority session, limits, _ConditionalSessionStore, _SessionStoreConflict, get_with_revision and compare_and_set. Keep a minimal SessionApprovalState(session) wire-id -> request map stored in session.state and rely on Core's built-in session approval handling. Return the custom storage sample and its tests to plain get/set/delete. --- .../_approvals.py | 331 +++--------------- .../_state_store.py | 99 +----- .../tests/foundry_hosting/approval_helpers.py | 110 +----- .../custom_storage_sample_helpers.py | 18 +- .../foundry_hosting/responses_host_helpers.py | 38 -- .../test_custom_storage_sample.py | 277 ++++----------- .../foundry_hosting/test_session_approvals.py | 322 ++++------------- .../foundry_hosting/tests/test_state_store.py | 133 ------- .../responses/custom_storage/main.py | 88 +---- 9 files changed, 232 insertions(+), 1184 deletions(-) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_approvals.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_approvals.py index b4ad7bfaf33..2eb8a844d7f 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_approvals.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_approvals.py @@ -1,306 +1,89 @@ # Copyright (c) Microsoft. All rights reserved. -"""Keep hosted agent approval history separate from conditional pending authority.""" +"""Translate hosted MCP approval wire IDs to the agent's approval requests.""" from __future__ import annotations import json -from collections.abc import Sequence -from dataclasses import dataclass from typing import Any, cast -from uuid import uuid4 -from agent_framework import AgentSession, Content, SessionStore +from agent_framework import AgentSession, Content -from ._state_store import _ConditionalSessionStore # pyright: ignore[reportPrivateUsage] - -_APPROVAL_STATE_KEY = "__foundry_agent_approvals_v1" -_AUTHORITY_PREFIX = "__foundry_agent_approval/" -_MAX_HISTORY_REQUESTS = 1024 -_MAX_HISTORY_BYTES = 1024 * 1024 +_APPROVAL_STATE_KEY = "__foundry_agent_approval_requests_v1" +_UNSUPPORTED = "Unsupported stored approval requests; start a fresh conversation." class _InvalidApproval(ValueError): - """Reject invalid approval controls without classifying backend failures.""" - - -@dataclass(frozen=True) -class _ApprovalClaim: - authority_id: str - revision: str - session_id: str - owner_response_id: str - requests: tuple[tuple[str, str], ...] - - -def _conditional_store(storage: SessionStore | None) -> _ConditionalSessionStore: - if not isinstance(storage, _ConditionalSessionStore): - raise RuntimeError( - "Hosted approvals require a session store implementing get_with_revision and compare_and_set " - "with atomic create-only and exact-revision writes; ordinary get/set is not sufficient." - ) - return storage - - -def _mapping(value: object, message: str) -> dict[str, Any]: - if not isinstance(value, dict) or any(not isinstance(key, str) for key in cast(dict[object, object], value)): - raise RuntimeError(message) - return cast(dict[str, Any], value) - + """Reject an approval reply that names no request in this session.""" -def _requests(value: object) -> dict[str, str]: - raw = _mapping(value, "Unsupported approval history; start a fresh conversation.") - if any(not key or not isinstance(item, str) for key, item in raw.items()): - raise RuntimeError("Unsupported approval history; start a fresh conversation.") - return cast(dict[str, str], raw) - -def _decode_request(value: str) -> Content: - try: - raw: object = json.loads(value) - except (TypeError, ValueError) as exc: - raise RuntimeError("Unsupported stored approval content; start a fresh conversation.") from exc - payload = _mapping(raw, "Unsupported stored approval content; start a fresh conversation.") - try: - content = Content.from_dict(payload) - except (TypeError, ValueError, KeyError) as exc: - raise RuntimeError("Unsupported stored approval content; start a fresh conversation.") from exc - if ( - content.type != "function_approval_request" - or not content.id - or content.function_call is None - or content.function_call.type != "function_call" - or not content.function_call.call_id - or not content.function_call.name - ): - raise RuntimeError("Unsupported stored approval content; start a fresh conversation.") - return content +def _is_approval_request(content: Content) -> bool: + return ( + content.type == "function_approval_request" + and bool(content.id) + and content.function_call is not None + and content.function_call.type == "function_call" + and bool(content.function_call.call_id) + and bool(content.function_call.name) + ) class SessionApprovalState: - """Manage a regular agent's approval aliases through its session store. - - ``save_approval_request`` stages output only. The host must buffer approval - events until ``seal`` and the ordinary session snapshot writes succeed. - Input conversion can read history but cannot consume authority. Preflight - reads the canonical batch; claim conditionally consumes it immediately before - protected dispatch, after every other request check and reservation. - - A canonical entry is another private ``AgentSession`` in the same store, not - a separately configured approval backend. Response and conversation snapshots - contain only a link and historical content. Missing or expired canonical - entries fail closed, even when a historical snapshot still exists. - - Custom stores must implement revision reads and atomic create-only/exact- - revision writes. The default local Foundry backend cannot provide this - capability and raises ``RuntimeError``; ordinary non-approval sessions are - unaffected. History is capped at 1024 requests and 1 MiB of serialized content. - Unsupported state and history overflow require a fresh conversation, never - silent migration or pruning. Native workflow checkpoints do not use this - authority. + """Keep the wire-ID to approval-request map in the agent's own session state. + + The Responses protocol uses wire IDs minted by the host, so the host must map + a reply back to the original ``function_approval_request``. This class does + no I/O and grants no authority. The host persists the map with the ordinary + session snapshot, and Core's session approval tracking alone binds and + consumes pending requests. A forked or retried session snapshot can therefore + answer the same approval again. """ - def __init__(self, session: AgentSession, storage: SessionStore | None, *, response_id: str | None = None) -> None: + def __init__(self, session: AgentSession) -> None: self.session = session - self._storage = storage - self._response_id = response_id - self._staged: dict[str, str] = {} - self._sealed = False - value = session.state.get(_APPROVAL_STATE_KEY) - if _APPROVAL_STATE_KEY not in session.state: - self._state: dict[str, Any] = {"version": 1, "history": {}, "pending": None} - else: - state = _mapping(value, "Unsupported approval session state; start a fresh conversation.") - if type(state.get("version")) is not int or state["version"] != 1: - raise RuntimeError("Unsupported approval session version; start a fresh conversation.") - if "history" not in state or "pending" not in state: - raise RuntimeError("Unsupported approval session state; start a fresh conversation.") - _requests(state["history"]) - self._state = state - self._pending() - def _pending(self) -> dict[str, Any] | None: - value = self._state["pending"] + def _requests(self) -> dict[str, str]: + value = self.session.state.get(_APPROVAL_STATE_KEY) if value is None: - return None - pending = _mapping(value, "Unsupported pending approval link; start a fresh conversation.") - if ( - not isinstance(pending.get("authority_id"), str) - or not pending["authority_id"].startswith(_AUTHORITY_PREFIX) - or not isinstance(pending.get("response_id"), str) - or not pending["response_id"] - or not isinstance(pending.get("wire_ids"), list) + return {} + if not isinstance(value, dict) or any( + not isinstance(key, str) or not key or not isinstance(item, str) + for key, item in cast(dict[object, object], value).items() ): - raise RuntimeError("Unsupported pending approval link; start a fresh conversation.") - ids = cast(list[object], pending["wire_ids"]) - if not ids or any(not isinstance(item, str) or not item for item in ids) or len(set(ids)) != len(ids): - raise RuntimeError("Unsupported pending approval link; start a fresh conversation.") - return pending - - async def load_approval_request(self, approval_request_id: str) -> Content: - """Reconstruct original content without granting or consuming authority.""" - history = _requests(self._state["history"]) - value = history.get(approval_request_id) - if value is None: - raise _InvalidApproval("Approval request is not in this session's history; start a fresh approval turn.") - return _decode_request(value) + raise RuntimeError(_UNSUPPORTED) + return cast(dict[str, str], value) async def save_approval_request(self, approval_request_id: str, request: Content) -> None: - """Stage a wire mapping; the host must not publish it until sealing.""" - _conditional_store(self._storage) - if self._sealed or self._pending() is not None: - raise RuntimeError("Cannot publish another approval batch while this batch is pending or sealed.") - if not self._response_id: - raise RuntimeError("Approval recording requires the owning response ID.") - if not approval_request_id or not isinstance(approval_request_id, str): + """Record the request emitted under ``approval_request_id``.""" + if not isinstance(approval_request_id, str) or not approval_request_id: raise ValueError("Approval wire ID must be a non-empty string.") - history = _requests(self._state["history"]) - if approval_request_id in history or approval_request_id in self._staged: - raise ValueError("Approval wire ID already exists in this session.") - if ( - request.type != "function_approval_request" - or not request.id - or request.function_call is None - or request.function_call.type != "function_call" - or not request.function_call.call_id - or not request.function_call.name - ): + if not _is_approval_request(request): raise ValueError("Only complete function approval requests can be recorded.") - if any(_decode_request(value).id == request.id for value in self._staged.values()): - raise ValueError("Framework approval request ID already exists in this pending batch.") + requests = self._requests() + if approval_request_id in requests: + raise ValueError("Approval wire ID already exists in this session.") # JSON strings prevent session codecs from interpreting nested provider # dictionaries with a registered `type` discriminator as live objects. - encoded = json.dumps(request.to_dict(), allow_nan=False, separators=(",", ":")) - if len(history) + len(self._staged) + 1 > _MAX_HISTORY_REQUESTS or ( - sum(len(item.encode("utf-8")) for item in (*history.values(), *self._staged.values(), encoded)) - > _MAX_HISTORY_BYTES - ): - raise RuntimeError("Hosted approval history limit reached; start a fresh conversation.") - self._staged[approval_request_id] = encoded - - async def seal(self) -> None: - """Persist the complete pending batch before publishing its snapshots. - - A failed acknowledgement may still have written an unreachable canonical - record. No alias is attached until the write succeeds. Never retry a - cancelled/failed publication as protected dispatch. - """ - if not self._staged: - return - if self._sealed: - raise RuntimeError("Approval batch is already sealed.") - storage = _conditional_store(self._storage) - authority_id = f"{_AUTHORITY_PREFIX}{uuid4()}" - authority = AgentSession(session_id=self.session.session_id) - authority.state[_APPROVAL_STATE_KEY] = { - "version": 1, - "response_id": self._response_id, - "phase": "pending", - "requests": dict(self._staged), - "claimed_by": None, - } - revision = await storage.compare_and_set(authority_id, authority, expected_revision=None) - if not isinstance(revision, str) or not revision: - raise RuntimeError("Session storage did not acknowledge the approval revision.") - self._state["history"] = {**_requests(self._state["history"]), **self._staged} - self._state["pending"] = { - "authority_id": authority_id, - "response_id": self._response_id, - "wire_ids": list(self._staged), - } - self.session.state[_APPROVAL_STATE_KEY] = self._state - self._sealed = True + requests[approval_request_id] = json.dumps(request.to_dict(), allow_nan=False, separators=(",", ":")) + self.session.state[_APPROVAL_STATE_KEY] = requests - async def preflight(self, approval_ids: Sequence[str]) -> _ApprovalClaim | None: - """Validate exactly one complete batch without writing any state. - - Missing, duplicate, foreign, stale, and already claimed controls fail - before the host opens a response stream. A pending batch also rejects a - new user turn with no decisions; reset by starting a fresh conversation. - Approval and rejection both count as decisions. The host validates their - boolean values and rejects conflicting input-control kinds separately. - Deliberate invalid controls raise ``_InvalidApproval``; storage failures - propagate unchanged, including backend ``ValueError`` exceptions. - """ - pending = self._pending() - if pending is None: - if approval_ids: - raise _InvalidApproval("No pending approval batch in this session; start a fresh approval turn.") - return None - if ( - any(not isinstance(item, str) or not item for item in approval_ids) - or len(set(approval_ids)) != len(approval_ids) - or set(approval_ids) != set(pending["wire_ids"]) - ): - raise _InvalidApproval("Answer exactly the complete pending MCP approval batch without duplicates.") - storage = _conditional_store(self._storage) - authority, revision = await storage.get_with_revision(pending["authority_id"]) - if authority is None: - raise _InvalidApproval("Pending approval authority is missing or expired; start a fresh conversation.") - if not isinstance(revision, str) or not revision: - raise RuntimeError("Session storage returned approval authority without a revision.") - record = _mapping( - authority.state.get(_APPROVAL_STATE_KEY), - "Unsupported canonical approval state; start a fresh conversation.", - ) - if type(record.get("version")) is not int or record["version"] != 1: - raise RuntimeError("Unsupported canonical approval version; start a fresh conversation.") - requests = _requests(record.get("requests")) - matches_owner = ( - authority.session_id == self.session.session_id - and record.get("response_id") == pending["response_id"] - and set(requests) == set(pending["wire_ids"]) - ) - if matches_owner: - history = _requests(self._state["history"]) - matches_owner = all(history.get(key) == value for key, value in requests.items()) - if not matches_owner: - raise _InvalidApproval("Pending approval authority does not match this session and response.") - if record.get("phase") == "claimed": - raise _InvalidApproval("Pending approval batch was already claimed; start a fresh approval turn.") - if record.get("phase") != "pending" or "claimed_by" not in record or record["claimed_by"] is not None: - raise RuntimeError("Unsupported canonical approval phase; start a fresh conversation.") - for value in requests.values(): - _decode_request(value) - return _ApprovalClaim( - pending["authority_id"], - revision, - self.session.session_id, - pending["response_id"], - tuple(requests.items()), - ) - - async def claim(self, token: _ApprovalClaim, *, response_id: str) -> None: - """Irreversibly claim a validated revision before protected dispatch. + async def load_approval_request(self, approval_request_id: str) -> Content: + """Return the request recorded under ``approval_request_id``. - Run only after all request validation and other session/conversation - reservations succeed. A losing writer, storage failure, or cancellation - must not dispatch. A crash after acknowledgement may lose work; never - reopen the batch or claim exactly-once external side effects. + Raises: + _InvalidApproval: If this session has no request with that wire ID. + RuntimeError: If the stored map or entry is malformed. """ - pending = self._pending() - if not response_id: - raise ValueError("Claiming response ID must be provided.") - if ( - pending is None - or token.session_id != self.session.session_id - or token.authority_id != pending["authority_id"] - or token.owner_response_id != pending["response_id"] - or set(dict(token.requests)) != set(pending["wire_ids"]) - ): - raise _InvalidApproval("Approval preflight token does not match the current session.") - authority = AgentSession(session_id=token.session_id) - authority.state[_APPROVAL_STATE_KEY] = { - "version": 1, - "response_id": token.owner_response_id, - "phase": "claimed", - "requests": dict(token.requests), - "claimed_by": response_id, - } - revision = await _conditional_store(self._storage).compare_and_set( - token.authority_id, authority, expected_revision=token.revision - ) - if not isinstance(revision, str) or not revision: - raise RuntimeError("Session storage did not acknowledge the approval claim revision.") - self._state["pending"] = None - self.session.state[_APPROVAL_STATE_KEY] = self._state + value = self._requests().get(approval_request_id) + if value is None: + raise _InvalidApproval("Approval request is not in this session; start a fresh approval turn.") + try: + payload: Any = json.loads(value) + if not isinstance(payload, dict): + raise TypeError + content = Content.from_dict(cast(dict[str, Any], payload)) + except (TypeError, ValueError, KeyError) as exc: + raise RuntimeError(_UNSUPPORTED) from exc + if not _is_approval_request(content): + raise RuntimeError(_UNSUPPORTED) + return content diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_state_store.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_state_store.py index 939f93f2c2c..7eaac49224d 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_state_store.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_state_store.py @@ -4,10 +4,9 @@ import hashlib import json -import os from abc import ABC, abstractmethod from datetime import datetime -from typing import Any, Generic, Protocol, TypeVar, runtime_checkable +from typing import Any, Generic, TypeVar from agent_framework import ( AgentSession, @@ -337,35 +336,6 @@ def get_store_for_scope( # region Agent session persistence -class _SessionStoreConflict(RuntimeError): - """Signal a lost conditional session write without retrying it.""" - - -@runtime_checkable -class _ConditionalSessionStore(Protocol): - """Require revision-bound writes from stores supporting hosted approvals. - - Implementations must coordinate every writer to a key, including writers in - separate processes. Ordinary ``get``/``set`` and process-local locking do not - establish this capability. Missing entries return ``(None, None)``; existing - entries and successful writes return a non-empty, opaque revision. - Revisions identify one persisted version and must not be reused after writes. - """ - - async def get_with_revision(self, session_id: str) -> tuple[AgentSession | None, str | None]: - """Read an independent snapshot and its exact persisted revision.""" - ... - - async def compare_and_set(self, session_id: str, session: AgentSession, *, expected_revision: str | None) -> str: - """Create only for ``None``, otherwise replace only the exact revision. - - Raise ``RuntimeError`` on conflict; never retry as an unconditional write. - A failed or cancelled write may have committed. Callers must fail closed - rather than assume that retrying protected work is safe. - """ - ... - - class FoundryAgentSessionStore(SessionStore): """Agent session store backed by the `FoundryStateStore`.""" @@ -399,76 +369,17 @@ async def _get_store(self) -> FoundryStateStore: ) async def get(self, session_id: str) -> AgentSession | None: - session, revision = await self.get_with_revision(session_id) - self._etags[session_id] = revision - return session - - async def get_with_revision(self, session_id: str) -> tuple[AgentSession | None, str | None]: - """Read a session and its storage revision without a cached-write token. - - A revision belongs to this particular read, not to this store instance. - Approval claims pass it explicitly to ``compare_and_set``. - """ SessionStore.validate_session_id(session_id) store = await self._get_store() async with store: item = await store.get_item(session_id, call_id=self.platform_context.call_id) if item is None: - return None, None + self._etags[session_id] = None + return None if not item.etag: raise RuntimeError("Foundry agent session storage returned a loaded session without an ETag.") - return AgentSession.from_dict(item.value), item.etag - - async def compare_and_set(self, session_id: str, session: AgentSession, *, expected_revision: str | None) -> str: - """Persist a create-only or exact-revision session transition. - - ``None`` requires an absent entry; a non-empty revision requires that - exact existing entry. Wildcard and list revisions are rejected. - Conflicts never fall back to an upsert. An - acknowledgement without a revision is a failure, even if storage wrote - the value. The caller must not dispatch protected work in that case. - - Raises: - ValueError: If the key or expected revision is invalid. - RuntimeError: If the write conflicts or storage acknowledges a write - without an ETag. Local Foundry storage is unsupported: supply a - custom conditional store. - """ - SessionStore.validate_session_id(session_id) - if expected_revision is not None and ( - not isinstance(expected_revision, str) - or not expected_revision - or expected_revision.strip() == "*" - or "," in expected_revision - ): - raise ValueError("expected_revision must be None or one exact non-wildcard revision.") - if self._scope is None or not os.environ.get("FOUNDRY_HOSTING_ENVIRONMENT"): - raise RuntimeError( - "The default non-hosted Foundry session store cannot atomically claim approvals across processes. " - "Supply a custom session store implementing get_with_revision and compare_and_set " - "with atomic create-only and exact-revision writes." - ) - store = await self._get_store() - async with store: - try: - if expected_revision is None: - result = await store.create_item( - session_id, session.to_dict(), call_id=self.platform_context.call_id - ) - else: - result = await store.set_item( - session_id, - session.to_dict(), - if_match=expected_revision, - call_id=self.platform_context.call_id, - ) - except (FoundryStorageConflictError, FoundryStoragePreconditionError) as exc: - raise _SessionStoreConflict( - "Another request advanced this agent session; reload before writing." - ) from exc - if not result.etag: - raise RuntimeError("Foundry agent session storage did not return an ETag after saving.") - return result.etag + self._etags[session_id] = item.etag + return AgentSession.from_dict(item.value) async def set(self, session_id: str, session: AgentSession) -> None: store = await self._get_store() diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/approval_helpers.py b/python/packages/foundry_hosting/tests/foundry_hosting/approval_helpers.py index de2a8056f51..738fab71808 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/approval_helpers.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/approval_helpers.py @@ -1,16 +1,14 @@ # Copyright (c) Microsoft. All rights reserved. -"""Durable conditional-store boundaries for hosted approval regression tests.""" +"""Durable session-store boundaries for hosted approval regression tests.""" from __future__ import annotations import asyncio import json import sqlite3 -import sys from contextlib import closing from pathlib import Path -from uuid import uuid4 from agent_framework import AgentSession, Content, SessionStore @@ -18,57 +16,32 @@ class SqliteSessionStore(SessionStore): - """Use actual database conditional writes shared by independent processes.""" + """Persist sessions in a real database shared by independent processes.""" def __init__(self, path: Path) -> None: self.path = path self.write_count = 0 - self.error_after_commit: BaseException | None = None with closing(sqlite3.connect(path)) as connection, connection: - connection.execute( - "CREATE TABLE IF NOT EXISTS sessions " - "(key TEXT PRIMARY KEY, payload TEXT NOT NULL, revision TEXT NOT NULL)" - ) + connection.execute("CREATE TABLE IF NOT EXISTS sessions (key TEXT PRIMARY KEY, payload TEXT NOT NULL)") - def _read(self, session_id: str) -> tuple[AgentSession | None, str | None]: + def _read(self, session_id: str) -> AgentSession | None: with closing(sqlite3.connect(self.path)) as connection: - row = connection.execute("SELECT payload, revision FROM sessions WHERE key = ?", (session_id,)).fetchone() - return (AgentSession.from_dict(json.loads(row[0])), row[1]) if row else (None, None) - - async def get_with_revision(self, session_id: str) -> tuple[AgentSession | None, str | None]: - return await asyncio.to_thread(self._read, session_id) + row = connection.execute("SELECT payload FROM sessions WHERE key = ?", (session_id,)).fetchone() + return AgentSession.from_dict(json.loads(row[0])) if row else None async def get(self, session_id: str) -> AgentSession | None: - session, _ = await self.get_with_revision(session_id) - return session + return await asyncio.to_thread(self._read, session_id) - def _write(self, session_id: str, payload: str, expected_revision: str | None) -> str: - revision = str(uuid4()) + def _write(self, session_id: str, payload: str) -> None: with closing(sqlite3.connect(self.path)) as connection, connection: - if expected_revision is None: - try: - connection.execute("INSERT INTO sessions VALUES (?, ?, ?)", (session_id, payload, revision)) - except sqlite3.IntegrityError as exc: - raise RuntimeError("Session revision conflict.") from exc - else: - result = connection.execute( - "UPDATE sessions SET payload = ?, revision = ? WHERE key = ? AND revision = ?", - (payload, revision, session_id, expected_revision), - ) - if result.rowcount != 1: - raise RuntimeError("Session revision conflict.") - return revision - - async def compare_and_set(self, session_id: str, session: AgentSession, *, expected_revision: str | None) -> str: - revision = await asyncio.to_thread(self._write, session_id, json.dumps(session.to_dict()), expected_revision) - self.write_count += 1 - if self.error_after_commit is not None: - raise self.error_after_commit - return revision + connection.execute( + "INSERT INTO sessions VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET payload = excluded.payload", + (session_id, payload), + ) async def set(self, session_id: str, session: AgentSession) -> None: - _, revision = await self.get_with_revision(session_id) - await self.compare_and_set(session_id, session, expected_revision=revision) + await asyncio.to_thread(self._write, session_id, json.dumps(session.to_dict())) + self.write_count += 1 async def delete(self, session_id: str) -> None: await asyncio.to_thread(self._delete, session_id) @@ -91,62 +64,9 @@ def approval_request(index: int = 0) -> Content: async def pending_session(store: SqliteSessionStore, count: int = 2) -> AgentSession: session = AgentSession(session_id="original-session") - state = SessionApprovalState(session, store, response_id="owner-response") + state = SessionApprovalState(session) for index in range(count): await state.save_approval_request(f"wire-{index}", approval_request(index)) - await state.seal() await store.set("response-alias", session) await store.set("conversation-alias", session) return session - - -async def claim_stored_batch(path: str) -> None: - store = SqliteSessionStore(Path(path)) - session = await store.get("response-alias") - assert session is not None - state = SessionApprovalState(session, store) - token = await state.preflight(["wire-0", "wire-1"]) - assert token is not None - print("ready", flush=True) # noqa: T201 - subprocess barrier protocol - await asyncio.to_thread(sys.stdin.readline) - try: - await state.claim(token, response_id=str(uuid4())) - except RuntimeError: - print("conflict", flush=True) # noqa: T201 - subprocess result protocol - else: - print("claimed", flush=True) # noqa: T201 - subprocess result protocol - - -async def race_claims_in_processes(path: Path) -> list[str]: - script = ( - "import asyncio,sys; " - "sys.path.insert(0,sys.argv[1]); " - "from approval_helpers import claim_stored_batch; " - "asyncio.run(claim_stored_batch(sys.argv[2]))" - ) - processes = [ - await asyncio.create_subprocess_exec( - sys.executable, - "-c", - script, - str(Path(__file__).parent), - str(path), - stdin=asyncio.subprocess.PIPE, - stdout=asyncio.subprocess.PIPE, - stderr=asyncio.subprocess.PIPE, - ) - for _ in range(2) - ] - try: - for process in processes: - assert process.stdout is not None - assert await asyncio.wait_for(process.stdout.readline(), 30) == b"ready\n" - results = await asyncio.gather(*(process.communicate(b"go\n") for process in processes)) - for process, (_, error) in zip(processes, results, strict=True): - assert process.returncode == 0, error.decode() - return sorted(output.decode().strip() for output, _ in results) - finally: - for process in processes: - if process.returncode is None: - process.kill() - await process.wait() diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/custom_storage_sample_helpers.py b/python/packages/foundry_hosting/tests/foundry_hosting/custom_storage_sample_helpers.py index 2c2072500da..f2ce84216ff 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/custom_storage_sample_helpers.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/custom_storage_sample_helpers.py @@ -14,8 +14,6 @@ from agent_framework_foundry_hosting import FoundryRequestScope -_STORED_ETAG = object() - def make_session(value: str) -> AgentSession: session = AgentSession(session_id="inner-maf-session") @@ -35,24 +33,14 @@ class FakeContainer: def __init__(self) -> None: self.items: dict[tuple[str, str], dict[str, Any]] = {} self._version = 0 - self.acknowledgement_etag: object = _STORED_ETAG self.create_error: int | None = None self.calls: list[tuple[str, dict[str, Any]]] = [] - @staticmethod - def _matches_if_match(condition: str, current: str) -> bool: - if condition.strip() == "*" or condition == current: - return True - return current in (candidate.strip() for candidate in condition.split(",")) - def _stamp(self, body: dict[str, Any]) -> dict[str, Any]: self._version += 1 stored = {**deepcopy(body), "_etag": f'"{self._version}"'} self.items[body["scope_key"], body["id"]] = stored - result = deepcopy(stored) - if self.acknowledgement_etag is not _STORED_ETAG: - result["_etag"] = self.acknowledgement_etag - return result + return deepcopy(stored) async def read_item(self, *, item: str, partition_key: str) -> dict[str, Any]: stored = self.items.get((partition_key, item)) @@ -76,7 +64,7 @@ async def replace_item( stored = self.items.get((body["scope_key"], item)) if stored is None: raise http_error(404) - if not self._matches_if_match(etag, stored["_etag"]): + if etag != stored["_etag"]: raise http_error(412) return self._stamp(body) @@ -86,7 +74,7 @@ async def delete_item(self, *, item: str, partition_key: str, etag: str, match_c stored = self.items.get((partition_key, item)) if stored is None: raise http_error(404) - if not self._matches_if_match(etag, stored["_etag"]): + if etag != stored["_etag"]: raise http_error(412) del self.items[partition_key, item] diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/responses_host_helpers.py b/python/packages/foundry_hosting/tests/foundry_hosting/responses_host_helpers.py index 3998ed9c4bb..7fa95fbe1ca 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/responses_host_helpers.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/responses_host_helpers.py @@ -6,7 +6,6 @@ import asyncio from collections.abc import AsyncIterator, Awaitable, Callable, Mapping, Sequence -from pathlib import Path from typing import Any from agent_framework import ( @@ -28,8 +27,6 @@ ) from agent_framework.openai import OpenAIContinuationToken -from .approval_helpers import SqliteSessionStore - class BackgroundAgentMiddleware(AgentMiddleware): def __init__(self, *, nested: bool, value: bool = True, in_kwargs: bool = False, on_poll: bool = False) -> None: @@ -148,41 +145,6 @@ async def response() -> ChatResponse: return ResponseStream(updates(), finalizer=ChatResponse.from_updates) if stream else response() -class GatedApprovalStore(SqliteSessionStore): - def __init__(self, path: Path, *, fail_alias: bool = False) -> None: - super().__init__(path) - self.started = asyncio.Event() - self.release = asyncio.Event() - self.fail_alias = fail_alias - - async def compare_and_set(self, session_id: str, session: AgentSession, *, expected_revision: str | None) -> str: - if session_id.startswith("__foundry_agent_approval/") and expected_revision is None: - self.started.set() - await self.release.wait() - return await super().compare_and_set(session_id, session, expected_revision=expected_revision) - - async def set(self, session_id: str, session: AgentSession) -> None: - if self.fail_alias: - raise RuntimeError("response session snapshot failed") - await super().set(session_id, session) - - -class GatedClaimStore(SqliteSessionStore): - def __init__(self, path: Path) -> None: - super().__init__(path) - self.started = asyncio.Event() - self.release = asyncio.Event() - self.claims = 0 - - async def compare_and_set(self, session_id: str, session: AgentSession, *, expected_revision: str | None) -> str: - if session_id.startswith("__foundry_agent_approval/") and expected_revision is not None: - self.claims += 1 - if self.claims == 2: - self.started.set() - await self.release.wait() - return await super().compare_and_set(session_id, session, expected_revision=expected_revision) - - class GatedRequestRead: def __init__(self) -> None: self.started = asyncio.Event() diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_custom_storage_sample.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_custom_storage_sample.py index 324be59f687..21336b04af1 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_custom_storage_sample.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_custom_storage_sample.py @@ -1,10 +1,9 @@ # Copyright (c) Microsoft. All rights reserved. -"""Validate the conditional-write contract of the custom_storage hosting sample.""" +"""Validate the optimistic-concurrency session store in the custom_storage hosting sample.""" from __future__ import annotations -import asyncio import importlib.util import sys from pathlib import Path @@ -17,7 +16,12 @@ from azure.core import MatchConditions from azure.cosmos.exceptions import CosmosHttpResponseError -from .custom_storage_sample_helpers import FakeContainer, cosmos_store, local_store, make_session +from .custom_storage_sample_helpers import ( # pyrefly: ignore[missing-import] - pytest's importlib namespace + FakeContainer, + cosmos_store, + local_store, + make_session, +) pytestmark = pytest.mark.filterwarnings("ignore:.*SessionStore is experimental.*") @@ -30,7 +34,6 @@ / "custom_storage" / "main.py" ) -_APPROVAL_KEY = "__foundry_agent_approval/0b6c8b52-6f1d-4bb3-9a35-6a1e4c8f7f10" @pytest.fixture(scope="module") @@ -43,110 +46,63 @@ def sample() -> ModuleType: return module -async def test_sample_does_not_import_private_hosting_types() -> None: +def _stores(sample: ModuleType, kind: str) -> tuple[Any, Any]: + if kind == "local": + snapshots: dict[Any, Any] = {} + return local_store(sample, snapshots), local_store(sample, snapshots) + container = FakeContainer() + return cosmos_store(sample, container), cosmos_store(sample, container) + + +async def test_sample_uses_only_the_public_session_store_contract() -> None: source = _SAMPLE.read_text(encoding="utf-8") - assert "_ConditionalSessionStore" not in source - assert "_SessionStoreConflict" not in source assert "agent_framework_foundry_hosting._" not in source + assert "compare_and_set" not in source + assert "get_with_revision" not in source @pytest.mark.parametrize("kind", ["local", "cosmos"]) -async def test_conditional_write_contract(sample: ModuleType, kind: str) -> None: - store = local_store(sample, {}) if kind == "local" else cosmos_store(sample, FakeContainer()) - - assert await store.get_with_revision(_APPROVAL_KEY) == (None, None) - +async def test_get_set_roundtrip_returns_independent_snapshots(sample: ModuleType, kind: str) -> None: + store, _ = _stores(sample, kind) + assert await store.get("alias") is None original = make_session("one") - original.state["nested"] = {"items": ["saved"]} - first = await store.compare_and_set(_APPROVAL_KEY, original, expected_revision=None) - original.state["nested"]["items"].append("original changed") - assert isinstance(first, str) and first - with pytest.raises(RuntimeError): - await store.compare_and_set(_APPROVAL_KEY, make_session("dup"), expected_revision=None) - - loaded, revision = await store.get_with_revision(_APPROVAL_KEY) - assert revision == first - assert loaded is not None and loaded.session_id == "inner-maf-session" - assert loaded.state["value"] == "one" - loaded.state["value"] = "mutated" - loaded.state["nested"]["items"].append("read changed") - again, _ = await store.get_with_revision(_APPROVAL_KEY) - assert again is not None and again.state["value"] == "one" - assert again.state["nested"] == {"items": ["saved"]} - - second = await store.compare_and_set(_APPROVAL_KEY, make_session("two"), expected_revision=first) - assert second and second != first - with pytest.raises(RuntimeError): - await store.compare_and_set(_APPROVAL_KEY, make_session("stale"), expected_revision=first) - current, current_revision = await store.get_with_revision(_APPROVAL_KEY) + await store.set("alias", original) + original.state["value"] = "mutated" + loaded = await store.get("alias") + assert loaded is not None and loaded.state["value"] == "one" + loaded.state["value"] = "two" + await store.set("alias", loaded) + current = await store.get("alias") assert current is not None and current.state["value"] == "two" - assert current_revision == second - - with pytest.raises(ValueError): - await store.compare_and_set(_APPROVAL_KEY, make_session("bad"), expected_revision="") @pytest.mark.parametrize("kind", ["local", "cosmos"]) -async def test_exact_update_of_absent_key_conflicts(sample: ModuleType, kind: str) -> None: - store = local_store(sample, {}) if kind == "local" else cosmos_store(sample, FakeContainer()) - with pytest.raises(RuntimeError): - await store.compare_and_set("missing", make_session("x"), expected_revision='"missing"') - assert await store.get_with_revision("missing") == (None, None) - - -@pytest.mark.parametrize("kind", ["local", "cosmos"]) -async def test_revision_reads_do_not_change_ordinary_write_tokens(sample: ModuleType, kind: str) -> None: - store = local_store(sample, {}) if kind == "local" else cosmos_store(sample, FakeContainer()) - assert await store.get("alias") is None - await store.set("alias", make_session("one")) - _, revision = await store.get_with_revision("alias") - await store.compare_and_set("alias", make_session("two"), expected_revision=revision) - with pytest.raises(RuntimeError): - await store.set("alias", make_session("stale")) +async def test_stale_request_view_cannot_overwrite_newer_session(sample: ModuleType, kind: str) -> None: + first, second = _stores(sample, kind) + await first.set("alias", make_session("initial")) + assert await second.get("alias") is not None + await second.set("alias", make_session("newer")) + with pytest.raises(RuntimeError, match="reload before writing"): + await first.set("alias", make_session("stale")) + current = await second.get("alias") + assert current is not None and current.state["value"] == "newer" @pytest.mark.parametrize("kind", ["local", "cosmos"]) -@pytest.mark.parametrize("operation", ["create", "update"]) -async def test_competing_request_views_allow_only_one_conditional_write( - sample: ModuleType, kind: str, operation: str -) -> None: - if kind == "local": - snapshots: dict[Any, Any] = {} - first, second = local_store(sample, snapshots), local_store(sample, snapshots) - else: - container = FakeContainer() - first, second = cosmos_store(sample, container), cosmos_store(sample, container) - - revision = None - if operation == "update": - revision = await first.compare_and_set(_APPROVAL_KEY, make_session("initial"), expected_revision=None) - assert (await second.get_with_revision(_APPROVAL_KEY))[1] == revision - - outcomes = await asyncio.gather( - first.compare_and_set(_APPROVAL_KEY, make_session("first"), expected_revision=revision), - second.compare_and_set(_APPROVAL_KEY, make_session("second"), expected_revision=revision), - return_exceptions=True, - ) - successes = [outcome for outcome in outcomes if isinstance(outcome, str)] - conflicts = [outcome for outcome in outcomes if isinstance(outcome, RuntimeError)] - assert len(successes) == len(conflicts) == 1 - assert successes[0] and successes[0] != revision - if kind == "cosmos": - assert isinstance(conflicts[0].__cause__, CosmosHttpResponseError) - stored, stored_revision = await first.get_with_revision(_APPROVAL_KEY) - assert stored is not None and stored.state["value"] in {"first", "second"} - assert stored_revision == successes[0] +async def test_competing_creates_allow_only_one_writer(sample: ModuleType, kind: str) -> None: + first, second = _stores(sample, kind) + assert await first.get("alias") is None + assert await second.get("alias") is None + await first.set("alias", make_session("first")) + with pytest.raises(RuntimeError, match="reload before writing"): + await second.set("alias", make_session("second")) + current = await second.get("alias") + assert current is not None and current.state["value"] == "first" @pytest.mark.parametrize("kind", ["local", "cosmos"]) async def test_stale_delete_does_not_remove_another_requests_snapshot(sample: ModuleType, kind: str) -> None: - if kind == "local": - snapshots: dict[Any, Any] = {} - first, second = local_store(sample, snapshots), local_store(sample, snapshots) - else: - container = FakeContainer() - first, second = cosmos_store(sample, container), cosmos_store(sample, container) - + first, second = _stores(sample, kind) await first.set("alias", make_session("initial")) assert await second.get("alias") is not None await second.set("alias", make_session("newer")) @@ -163,8 +119,8 @@ async def test_local_store_scopes_are_isolated(sample: ModuleType) -> None: snapshots: dict[Any, Any] = {} first = local_store(sample, snapshots, "scope-a") second = local_store(sample, snapshots, "scope-b") - await first.compare_and_set(_APPROVAL_KEY, make_session("a"), expected_revision=None) - assert await second.get_with_revision(_APPROVAL_KEY) == (None, None) + await first.set("alias", make_session("a")) + assert await second.get("alias") is None async def test_local_snapshots_are_shared_only_within_one_provider(sample: ModuleType) -> None: @@ -172,139 +128,44 @@ async def test_local_snapshots_are_shared_only_within_one_provider(sample: Modul config.is_hosted = False context = FoundryAgentRequestContext() provider = sample.CustomSessionStoreProvider() - other_provider = sample.CustomSessionStoreProvider() first = provider.get_store(config=config, platform_context=context) same_provider = provider.get_store(config=config, platform_context=context) - other = other_provider.get_store(config=config, platform_context=context) + other = sample.CustomSessionStoreProvider().get_store(config=config, platform_context=context) - revision = await first.compare_and_set(_APPROVAL_KEY, make_session("one"), expected_revision=None) + await first.set("alias", make_session("one")) assert first is not same_provider - stored, stored_revision = await same_provider.get_with_revision(_APPROVAL_KEY) + stored = await same_provider.get("alias") assert stored is not None and stored.state["value"] == "one" - assert stored_revision == revision - assert await other.get_with_revision(_APPROVAL_KEY) == (None, None) - - -async def test_cosmos_uses_server_conditions(sample: ModuleType) -> None: - container = FakeContainer() - store = cosmos_store(sample, container) - revision = await store.compare_and_set(_APPROVAL_KEY, make_session("one"), expected_revision=None) - await store.compare_and_set(_APPROVAL_KEY, make_session("two"), expected_revision=revision) - assert container.calls[0] == ("create", {}) - assert container.calls[1] == ("replace", {"etag": revision, "match_condition": MatchConditions.IfNotModified}) - assert all("/" not in item_id for _, item_id in container.items) - - -@pytest.mark.parametrize("condition", ["*", '"stale","1"']) -async def test_cosmos_fake_models_non_exact_if_match(sample: ModuleType, condition: str) -> None: - container = FakeContainer() - store = cosmos_store(sample, container) - await store.compare_and_set(_APPROVAL_KEY, make_session("one"), expected_revision=None) - scope_key, item_id = next(iter(container.items)) - body = {"id": item_id, "scope_key": scope_key, "session": make_session("replaced").to_dict()} - - await container.replace_item(item=item_id, body=body, etag=condition, match_condition=MatchConditions.IfNotModified) - - stored, _ = await store.get_with_revision(_APPROVAL_KEY) - assert stored is not None and stored.state["value"] == "replaced" + assert await other.get("alias") is None -@pytest.mark.parametrize( - "revision", - ["*", " * ", '"1","2"', '"1", "2"', '"2","1"', 'W/"2"', "2", '"2"\n', '"2"\x00', '"2",*'], -) -async def test_cosmos_rejects_non_exact_revision_before_write(sample: ModuleType, revision: str) -> None: +async def test_cosmos_uses_server_side_create_and_exact_etag_conditions(sample: ModuleType) -> None: container = FakeContainer() store = cosmos_store(sample, container) - first = await store.compare_and_set(_APPROVAL_KEY, make_session("one"), expected_revision=None) - current = await store.compare_and_set(_APPROVAL_KEY, make_session("two"), expected_revision=first) - calls = len(container.calls) - - with pytest.raises(RuntimeError, match="ETag"): - await store.compare_and_set(_APPROVAL_KEY, make_session("overwritten"), expected_revision=revision) - - assert len(container.calls) == calls - stored, stored_revision = await store.get_with_revision(_APPROVAL_KEY) - assert stored is not None and stored.state["value"] == "two" - assert stored_revision == current - - -@pytest.mark.parametrize("etag", ['""', '"*"', '"a,b"', '"\xe9"']) -async def test_cosmos_accepts_one_opaque_strong_etag(sample: ModuleType, etag: str) -> None: - container = FakeContainer() - store = cosmos_store(sample, container) - await store.compare_and_set(_APPROVAL_KEY, make_session("one"), expected_revision=None) - container.items[next(iter(container.items))]["_etag"] = etag - assert (await store.get_with_revision(_APPROVAL_KEY))[1] == etag - - new_revision = await store.compare_and_set(_APPROVAL_KEY, make_session("two"), expected_revision=etag) - - assert new_revision != etag - stored, _ = await store.get_with_revision(_APPROVAL_KEY) - assert stored is not None and stored.state["value"] == "two" - - -@pytest.mark.parametrize("etag", [None, "", 42, "*", "unquoted", 'W/"one"', '"one","two"', '"one"\n']) -async def test_cosmos_rejects_invalid_read_etag(sample: ModuleType, etag: object) -> None: - container = FakeContainer() - store = cosmos_store(sample, container) - await store.compare_and_set(_APPROVAL_KEY, make_session("one"), expected_revision=None) - container.items[next(iter(container.items))]["_etag"] = etag - - with pytest.raises(RuntimeError, match="ETag"): - await store.get_with_revision(_APPROVAL_KEY) - with pytest.raises(RuntimeError, match="ETag"): - await store.get(_APPROVAL_KEY) - with pytest.raises(RuntimeError, match="ETag"): - await store.delete(_APPROVAL_KEY) - assert all(call[0] != "delete" for call in container.calls) - - -@pytest.mark.parametrize("etag", [None, "", 42, "*", "unquoted", 'W/"one"', '"one","two"', '"one"\n']) -async def test_cosmos_rejects_invalid_write_acknowledgement(sample: ModuleType, etag: object) -> None: - container = FakeContainer() - container.acknowledgement_etag = etag - store = cosmos_store(sample, container) - - with pytest.raises(RuntimeError, match="ETag"): - await store.compare_and_set(_APPROVAL_KEY, make_session("one"), expected_revision=None) - - stored, revision = await store.get_with_revision(_APPROVAL_KEY) - assert stored is not None and stored.state["value"] == "one" - assert revision - with pytest.raises(RuntimeError): - await store.compare_and_set(_APPROVAL_KEY, make_session("duplicate"), expected_revision=None) + await store.set("alias", make_session("one")) + await store.set("alias", make_session("two")) + await store.delete("alias") + assert container.calls == [ + ("create", {}), + ("replace", {"etag": '"1"', "match_condition": MatchConditions.IfNotModified}), + ("delete", {"etag": '"2"', "match_condition": MatchConditions.IfNotModified}), + ] -async def test_cosmos_rejects_invalid_cached_delete_etag(sample: ModuleType) -> None: +async def test_cosmos_rejects_stored_session_without_etag(sample: ModuleType) -> None: container = FakeContainer() store = cosmos_store(sample, container) - await store.set(_APPROVAL_KEY, make_session("one")) - store._etags[_APPROVAL_KEY] = "*" - - with pytest.raises(RuntimeError, match="ETag"): - await store.delete(_APPROVAL_KEY) - - assert all(call[0] != "delete" for call in container.calls) - stored, _ = await store.get_with_revision(_APPROVAL_KEY) - assert stored is not None and stored.state["value"] == "one" - - -async def test_local_store_keeps_opaque_revision_values(sample: ModuleType) -> None: - snapshots = {("scope", _APPROVAL_KEY): ("opaque-version", make_session("one").to_dict())} - store = local_store(sample, snapshots) - assert (await store.get_with_revision(_APPROVAL_KEY))[1] == "opaque-version" - - revision = await store.compare_and_set(_APPROVAL_KEY, make_session("two"), expected_revision="opaque-version") - - assert revision != "opaque-version" + await store.set("alias", make_session("one")) + for item in container.items.values(): + del item["_etag"] + with pytest.raises(RuntimeError, match="missing its ETag"): + await cosmos_store(sample, container).get("alias") async def test_cosmos_other_errors_propagate(sample: ModuleType) -> None: container = FakeContainer() container.create_error = 503 - store = cosmos_store(sample, container) with pytest.raises(CosmosHttpResponseError) as exc_info: - await store.compare_and_set(_APPROVAL_KEY, make_session("one"), expected_revision=None) + await cosmos_store(sample, container).set("alias", make_session("one")) assert not isinstance(exc_info.value, RuntimeError) diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_session_approvals.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_session_approvals.py index a229391a820..a2b4a80ee90 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_session_approvals.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_session_approvals.py @@ -2,13 +2,8 @@ from __future__ import annotations -import asyncio -import json -from dataclasses import replace -from unittest.mock import AsyncMock - import pytest -from agent_framework import AgentSession, SessionStore +from agent_framework import AgentSession, Content from agent_framework_foundry_hosting._approvals import _APPROVAL_STATE_KEY, SessionApprovalState, _InvalidApproval @@ -16,280 +11,91 @@ SqliteSessionStore, approval_request, pending_session, - race_claims_in_processes, ) -async def test_batch_is_not_persisted_until_sealed(tmp_path) -> None: - store = SqliteSessionStore(tmp_path / "sessions.db") +async def test_save_and_load_roundtrip_in_session_state() -> None: session = AgentSession() - state = SessionApprovalState(session, store, response_id="response") + state = SessionApprovalState(session) await state.save_approval_request("wire", approval_request()) - assert store.write_count == 0 - assert _APPROVAL_STATE_KEY not in session.state - await state.seal() - assert store.write_count == 1 - restored = AgentSession.from_dict(session.to_dict()) - history = SessionApprovalState(restored, store) - assert await history.load_approval_request("wire") == approval_request() - assert await history.preflight(["wire"]) is not None + assert set(session.state[_APPROVAL_STATE_KEY]) == {"wire"} + assert await state.load_approval_request("wire") == approval_request() -async def test_history_roundtrip_preserves_provider_content_without_type_rehydration(tmp_path) -> None: +async def test_requests_persist_through_session_store_without_type_rehydration(tmp_path) -> None: store = SqliteSessionStore(tmp_path / "sessions.db") await pending_session(store) - session = await store.get("response-alias") - assert session is not None - content = await SessionApprovalState(session, store).load_approval_request("wire-0") - assert content == approval_request() - assert content.id == "approval-0" - assert content.function_call is not None - assert content.function_call.hosted is True - assert content.function_call.additional_properties["provider"] == {"type": "message", "opaque_id": "original"} - - -@pytest.mark.parametrize("ids", [[], ["wire-0"], ["wire-0", "wire-0"], ["wire-0", "foreign"], ["foreign"]]) -async def test_invalid_batch_never_mutates_authority_and_complete_retry_succeeds(tmp_path, ids) -> None: - store = SqliteSessionStore(tmp_path / "sessions.db") - session = await pending_session(store) - state = SessionApprovalState(session, store) - before = store.write_count - with pytest.raises(_InvalidApproval, match="complete pending MCP approval batch"): - await state.preflight(ids) - assert store.write_count == before - token = await state.preflight(["wire-1", "wire-0"]) - assert token is not None - assert store.write_count == before - await state.claim(token, response_id="resume") - assert store.write_count == before + 1 - - -async def test_response_and_conversation_aliases_share_one_irreversible_authority(tmp_path) -> None: - store = SqliteSessionStore(tmp_path / "sessions.db") - await pending_session(store) - response = await store.get("response-alias") - conversation = await store.get("conversation-alias") - assert response is not None and conversation is not None and response is not conversation - first = SessionApprovalState(response, store) - second = SessionApprovalState(conversation, store) - token1 = await first.preflight(["wire-0", "wire-1"]) - token2 = await second.preflight(["wire-0", "wire-1"]) - assert token1 is not None and token2 is not None - await first.claim(token1, response_id="first") - with pytest.raises(RuntimeError, match="revision conflict"): - await second.claim(token2, response_id="second") - with pytest.raises(_InvalidApproval, match="already claimed"): - await second.preflight(["wire-0", "wire-1"]) - assert await second.load_approval_request("wire-0") == approval_request() - assert await first.preflight([]) is None - - -async def test_two_processes_can_preflight_but_only_one_can_claim(tmp_path) -> None: - store = SqliteSessionStore(tmp_path / "sessions.db") - await pending_session(store) - assert await race_claims_in_processes(store.path) == ["claimed", "conflict"] - - -async def test_expired_canonical_is_not_recreated_from_snapshot(tmp_path) -> None: - store = SqliteSessionStore(tmp_path / "sessions.db") - session = await pending_session(store) - key = session.state[_APPROVAL_STATE_KEY]["pending"]["authority_id"] - await store.delete(key) - before = store.write_count - state = SessionApprovalState(session, store) - with pytest.raises(_InvalidApproval, match="missing or expired"): - await state.preflight(["wire-0", "wire-1"]) - assert store.write_count == before - assert await state.load_approval_request("wire-0") == approval_request() + for alias in ("response-alias", "conversation-alias"): + session = await store.get(alias) + assert session is not None + content = await SessionApprovalState(session).load_approval_request("wire-0") + assert content == approval_request() + assert content.function_call is not None + assert content.function_call.hosted is True + assert content.function_call.additional_properties["provider"] == {"type": "message", "opaque_id": "original"} -@pytest.mark.parametrize("storage", [None, SessionStore()]) -async def test_unstored_and_nonconditional_stores_cannot_record_approvals(storage) -> None: - state = SessionApprovalState(AgentSession(), storage, response_id="response") - with pytest.raises(RuntimeError, match="ordinary get/set is not sufficient"): - await state.save_approval_request("wire", approval_request()) - - -async def test_empty_fresh_session_has_no_pending_authority() -> None: - state = SessionApprovalState(AgentSession(), None) - assert await state.preflight([]) is None - with pytest.raises(_InvalidApproval, match="No pending approval"): - await state.preflight(["wire"]) - with pytest.raises(_InvalidApproval, match="not in this session"): - await state.load_approval_request("wire") - - -@pytest.mark.parametrize("value", [None, {}, {"version": 2, "history": {}, "pending": None}]) -def test_unsupported_snapshot_format_requires_reset(value) -> None: +async def test_loading_does_not_consume_so_forks_and_retries_see_the_same_request() -> None: session = AgentSession() - session.state[_APPROVAL_STATE_KEY] = value - with pytest.raises(RuntimeError, match="Unsupported approval session"): - SessionApprovalState(session, None) + await SessionApprovalState(session).save_approval_request("wire", approval_request()) + fork = AgentSession.from_dict(session.to_dict()) + for state in (SessionApprovalState(session), SessionApprovalState(fork)): + assert await state.load_approval_request("wire") == approval_request() + assert await state.load_approval_request("wire") == approval_request() -async def test_other_session_cannot_claim_copied_pending_link(tmp_path) -> None: - store = SqliteSessionStore(tmp_path / "sessions.db") - session = await pending_session(store) - other = AgentSession(session_id="other-session") - other.state.update(session.state) - with pytest.raises(_InvalidApproval, match="does not match"): - await SessionApprovalState(other, store).preflight(["wire-0", "wire-1"]) +async def test_unknown_wire_id_raises_invalid_approval() -> None: + state = SessionApprovalState(AgentSession()) + with pytest.raises(_InvalidApproval, match="not in this session"): + await state.load_approval_request("missing") + assert issubclass(_InvalidApproval, ValueError) -async def test_persistence_failure_does_not_publish_snapshot_link(tmp_path, monkeypatch) -> None: - store = SqliteSessionStore(tmp_path / "sessions.db") +@pytest.mark.parametrize("wire_id", ["", None]) +async def test_save_rejects_empty_wire_id(wire_id) -> None: session = AgentSession() - state = SessionApprovalState(session, store, response_id="response") - await state.save_approval_request("wire", approval_request()) - monkeypatch.setattr(store, "compare_and_set", AsyncMock(side_effect=OSError("storage down"))) - with pytest.raises(OSError, match="storage down"): - await state.seal() + with pytest.raises(ValueError, match="non-empty string"): + await SessionApprovalState(session).save_approval_request(wire_id, approval_request()) assert _APPROVAL_STATE_KEY not in session.state -async def test_cancelled_claim_propagates_and_does_not_clear_local_pending(tmp_path, monkeypatch) -> None: - store = SqliteSessionStore(tmp_path / "sessions.db") - session = await pending_session(store) - state = SessionApprovalState(session, store) - token = await state.preflight(["wire-0", "wire-1"]) - assert token is not None - monkeypatch.setattr(store, "compare_and_set", AsyncMock(side_effect=asyncio.CancelledError)) - with pytest.raises(asyncio.CancelledError): - await state.claim(token, response_id="resume") - assert session.state[_APPROVAL_STATE_KEY]["pending"] is not None - - -async def test_postclaim_failure_does_not_reopen_authority_on_reload(tmp_path) -> None: - store = SqliteSessionStore(tmp_path / "sessions.db") - session = await pending_session(store) - state = SessionApprovalState(session, store) - token = await state.preflight(["wire-0", "wire-1"]) - assert token is not None - await state.claim(token, response_id="crashed-before-dispatch") - # No final session snapshot is saved: a restarted process sees the old alias. - restarted = await SqliteSessionStore(store.path).get("response-alias") - assert restarted is not None - with pytest.raises(_InvalidApproval, match="already claimed"): - await SessionApprovalState(restarted, store).preflight(["wire-0", "wire-1"]) - - -async def test_duplicate_output_wire_id_rejects_before_sealing(tmp_path) -> None: - store = SqliteSessionStore(tmp_path / "sessions.db") - state = SessionApprovalState(AgentSession(), store, response_id="response") - await state.save_approval_request("wire", approval_request()) +async def test_save_rejects_duplicate_wire_id_without_overwriting() -> None: + session = AgentSession() + state = SessionApprovalState(session) + await state.save_approval_request("wire", approval_request(0)) with pytest.raises(ValueError, match="already exists"): - await state.save_approval_request("wire", approval_request()) - assert store.write_count == 0 - - -async def test_history_limit_fails_explicitly_without_pruning(tmp_path, monkeypatch) -> None: - store = SqliteSessionStore(tmp_path / "sessions.db") - state = SessionApprovalState(AgentSession(), store, response_id="response") - monkeypatch.setattr("agent_framework_foundry_hosting._approvals._MAX_HISTORY_REQUESTS", 1) - await state.save_approval_request("wire-0", approval_request()) - with pytest.raises(RuntimeError, match="history limit reached"): - await state.save_approval_request("wire-1", approval_request(1)) - assert store.write_count == 0 - - -async def test_duplicate_original_approval_cannot_get_another_wire_id(tmp_path) -> None: - store = SqliteSessionStore(tmp_path / "sessions.db") - state = SessionApprovalState(AgentSession(), store, response_id="response") - await state.save_approval_request("wire-0", approval_request()) - with pytest.raises(ValueError, match="Framework approval request ID already exists"): - await state.save_approval_request("wire-1", approval_request()) - assert store.write_count == 0 - - -@pytest.mark.parametrize("error", [OSError("lost acknowledgement"), asyncio.CancelledError()]) -async def test_lost_claim_acknowledgement_never_reopens_persisted_authority(tmp_path, error) -> None: - store = SqliteSessionStore(tmp_path / "sessions.db") - session = await pending_session(store) - state = SessionApprovalState(session, store) - token = await state.preflight(["wire-0", "wire-1"]) - assert token is not None - store.error_after_commit = error - with pytest.raises(type(error)): - await state.claim(token, response_id="uncertain") - assert session.state[_APPROVAL_STATE_KEY]["pending"] is not None - restarted_store = SqliteSessionStore(store.path) - restarted = await restarted_store.get("response-alias") - assert restarted is not None - with pytest.raises(_InvalidApproval, match="already claimed"): - await SessionApprovalState(restarted, restarted_store).preflight(["wire-0", "wire-1"]) - - -async def test_history_byte_limit_rejects_without_persistence(tmp_path, monkeypatch) -> None: - store = SqliteSessionStore(tmp_path / "sessions.db") - state = SessionApprovalState(AgentSession(), store, response_id="response") - monkeypatch.setattr("agent_framework_foundry_hosting._approvals._MAX_HISTORY_BYTES", 1) - with pytest.raises(RuntimeError, match="history limit reached"): - await state.save_approval_request("wire", approval_request()) - assert store.write_count == 0 - - -@pytest.mark.parametrize("version", [True, 2, None]) -async def test_unsupported_canonical_version_fails_without_consumption(tmp_path, version) -> None: - store = SqliteSessionStore(tmp_path / "sessions.db") - session = await pending_session(store) - key = session.state[_APPROVAL_STATE_KEY]["pending"]["authority_id"] - authority, revision = await store.get_with_revision(key) - assert authority is not None and revision is not None - authority.state[_APPROVAL_STATE_KEY]["version"] = version - await store.compare_and_set(key, authority, expected_revision=revision) - before = store.write_count - with pytest.raises(RuntimeError, match="Unsupported canonical approval version"): - await SessionApprovalState(session, store).preflight(["wire-0", "wire-1"]) - assert store.write_count == before - - -async def test_history_tampering_does_not_authorize_a_different_call(tmp_path) -> None: - store = SqliteSessionStore(tmp_path / "sessions.db") - session = await pending_session(store) - state = SessionApprovalState(session, store) - session.state[_APPROVAL_STATE_KEY]["history"]["wire-0"] = json.dumps(approval_request(9).to_dict()) - before = store.write_count - with pytest.raises(_InvalidApproval, match="does not match"): - await state.preflight(["wire-0", "wire-1"]) - assert store.write_count == before - - -async def test_preflight_preserves_backend_value_error_without_classifying_invalid_input(tmp_path, monkeypatch) -> None: - store = SqliteSessionStore(tmp_path / "sessions.db") - session = await pending_session(store) - state = SessionApprovalState(session, store) - error = ValueError("backend decoding failed") - monkeypatch.setattr(store, "get_with_revision", AsyncMock(side_effect=error)) - before = store.write_count - with pytest.raises(ValueError) as caught: - await state.preflight(["wire-0", "wire-1"]) - assert caught.value is error - assert not isinstance(caught.value, _InvalidApproval) - assert store.write_count == before + await state.save_approval_request("wire", approval_request(1)) + assert await state.load_approval_request("wire") == approval_request(0) -async def test_claim_preserves_backend_value_error_without_classifying_invalid_input(tmp_path, monkeypatch) -> None: - store = SqliteSessionStore(tmp_path / "sessions.db") - session = await pending_session(store) - state = SessionApprovalState(session, store) - token = await state.preflight(["wire-0", "wire-1"]) - assert token is not None - error = ValueError("backend encoding failed") - monkeypatch.setattr(store, "compare_and_set", AsyncMock(side_effect=error)) - with pytest.raises(ValueError) as caught: - await state.claim(token, response_id="resume") - assert caught.value is error - assert not isinstance(caught.value, _InvalidApproval) - assert session.state[_APPROVAL_STATE_KEY]["pending"] is not None +@pytest.mark.parametrize( + "request_content", + [ + Content.from_text("not an approval"), + Content.from_function_approval_request("approval", Content.from_function_call(call_id="", name="tool")), + ], +) +async def test_save_rejects_incomplete_requests(request_content) -> None: + session = AgentSession() + with pytest.raises(ValueError, match="complete function approval requests"): + await SessionApprovalState(session).save_approval_request("wire", request_content) + assert _APPROVAL_STATE_KEY not in session.state -async def test_claim_rejects_mismatched_token_as_invalid_approval_without_writing(tmp_path) -> None: - store = SqliteSessionStore(tmp_path / "sessions.db") - session = await pending_session(store) - state = SessionApprovalState(session, store) - token = await state.preflight(["wire-0", "wire-1"]) - assert token is not None - before = store.write_count - with pytest.raises(_InvalidApproval, match="token does not match"): - await state.claim(replace(token, session_id="other"), response_id="resume") - assert store.write_count == before +@pytest.mark.parametrize( + "stored", + [ + [], + {"wire": 1}, + {"": "{}"}, + {"wire": "not json"}, + {"wire": "[]"}, + {"wire": '{"type":"text","text":"x"}'}, + ], +) +async def test_malformed_stored_map_fails_closed(stored) -> None: + session = AgentSession() + session.state[_APPROVAL_STATE_KEY] = stored + state = SessionApprovalState(session) + with pytest.raises(RuntimeError, match="start a fresh conversation"): + await state.load_approval_request("wire") diff --git a/python/packages/foundry_hosting/tests/test_state_store.py b/python/packages/foundry_hosting/tests/test_state_store.py index 34601b2d705..de8afe76b5c 100644 --- a/python/packages/foundry_hosting/tests/test_state_store.py +++ b/python/packages/foundry_hosting/tests/test_state_store.py @@ -11,18 +11,14 @@ from azure.ai.agentserver.core import AgentConfig, FoundryAgentRequestContext from azure.ai.agentserver.core.storage import ( FoundryStateStore, - FoundryStorageConflictError, - FoundryStoragePreconditionError, ) from agent_framework_foundry_hosting import ContextScopedStoreProvider, StoreProvider -from agent_framework_foundry_hosting._scope import FoundryRequestScope from agent_framework_foundry_hosting._state_store import ( AgentSessionStoreProvider, CheckpointStoreProvider, FoundryAgentSessionStore, FoundryCheckpointStore, - _SessionStoreConflict, ) @@ -490,135 +486,6 @@ async def test_get_missing_agent_session_returns_none() -> None: assert result is None -async def test_revision_reads_do_not_share_the_mutable_etag_cache() -> None: - store = _store() - session = AgentSession() - store.get_item = AsyncMock(return_value=SimpleNamespace(value=session.to_dict(), etag="exact-read")) - storage = FoundryAgentSessionStore(_platform_context()) - with patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", - new=AsyncMock(return_value=store), - ): - loaded, revision = await storage.get_with_revision("canonical") - assert loaded is not None and loaded.to_dict() == session.to_dict() - assert revision == "exact-read" - assert storage._etags == {} - - -async def test_revision_read_returns_none_only_for_absent_entry() -> None: - store = _store() - store.get_item = AsyncMock(return_value=None) - with patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", - new=AsyncMock(return_value=store), - ): - assert await FoundryAgentSessionStore(_platform_context()).get_with_revision("missing") == (None, None) - - -@pytest.mark.parametrize("expected_revision", [None, "exact-read"]) -async def test_hosted_conditional_write_uses_explicit_revision_not_cached_token( - monkeypatch: pytest.MonkeyPatch, expected_revision: str | None -) -> None: - monkeypatch.setenv("FOUNDRY_HOSTING_ENVIRONMENT", "hosted") - store = _store() - session = AgentSession() - scope = FoundryRequestScope.from_context(_config(is_hosted=True), _platform_context()) - storage = FoundryAgentSessionStore(_platform_context(), scope=scope) - storage._etags["canonical"] = "unrelated-cached-token" - with patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", - new=AsyncMock(return_value=store), - ): - revision = await storage.compare_and_set("canonical", session, expected_revision=expected_revision) - if expected_revision is None: - store.create_item.assert_awaited_once_with("canonical", session.to_dict(), call_id="call-1") - store.set_item.assert_not_awaited() - assert revision == "etag-1" - else: - store.set_item.assert_awaited_once_with( - "canonical", session.to_dict(), if_match=expected_revision, call_id="call-1" - ) - store.create_item.assert_not_awaited() - assert revision == "etag-2" - assert storage._etags["canonical"] == "unrelated-cached-token" - - -@pytest.mark.parametrize("conflict", [FoundryStorageConflictError, FoundryStoragePreconditionError]) -async def test_conditional_conflict_preserves_cause_and_never_retries( - monkeypatch: pytest.MonkeyPatch, conflict: type[Exception] -) -> None: - monkeypatch.setenv("FOUNDRY_HOSTING_ENVIRONMENT", "hosted") - store = _store() - error = conflict("conflict") - store.set_item = AsyncMock(side_effect=error) - scope = FoundryRequestScope.from_context(_config(is_hosted=True), _platform_context()) - with ( - patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", - new=AsyncMock(return_value=store), - ), - pytest.raises(_SessionStoreConflict) as raised, - ): - await FoundryAgentSessionStore(_platform_context(), scope=scope).compare_and_set( - "canonical", AgentSession(), expected_revision="read-revision" - ) - assert raised.value.__cause__ is error - store.set_item.assert_awaited_once() - store.create_item.assert_not_awaited() - - -@pytest.mark.parametrize("expected_revision", [None, "read-revision"]) -async def test_conditional_write_without_acknowledged_revision_fails_closed( - monkeypatch: pytest.MonkeyPatch, expected_revision: str | None -) -> None: - monkeypatch.setenv("FOUNDRY_HOSTING_ENVIRONMENT", "hosted") - store = _store() - store.set_item = AsyncMock(return_value=SimpleNamespace(etag=None)) - store.create_item = AsyncMock(return_value=SimpleNamespace(etag=None)) - scope = FoundryRequestScope.from_context(_config(is_hosted=True), _platform_context()) - with ( - patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", - new=AsyncMock(return_value=store), - ), - pytest.raises(RuntimeError, match="did not return an ETag"), - ): - await FoundryAgentSessionStore(_platform_context(), scope=scope).compare_and_set( - "canonical", AgentSession(), expected_revision=expected_revision - ) - - -@pytest.mark.parametrize("expected_revision", ["*", " * ", '"a", "b"']) -async def test_conditional_write_rejects_wildcard_or_list_revision_before_backend_access( - monkeypatch: pytest.MonkeyPatch, expected_revision: str -) -> None: - monkeypatch.setenv("FOUNDRY_HOSTING_ENVIRONMENT", "hosted") - scope = FoundryRequestScope.from_context(_config(is_hosted=True), _platform_context()) - with ( - patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", new=AsyncMock() - ) as backend, - pytest.raises(ValueError, match="exact non-wildcard revision"), - ): - await FoundryAgentSessionStore(_platform_context(), scope=scope).compare_and_set( - "canonical", AgentSession(), expected_revision=expected_revision - ) - backend.assert_not_awaited() - - -async def test_default_nonhosted_approval_cas_fails_before_backend_access() -> None: - with ( - patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", new=AsyncMock() - ) as backend, - pytest.raises(RuntimeError, match="custom session store implementing get_with_revision and compare_and_set"), - ): - await FoundryAgentSessionStore(_platform_context()).compare_and_set( - "canonical", AgentSession(), expected_revision=None - ) - backend.assert_not_awaited() - - async def test_delete_agent_session_is_idempotent() -> None: store = _store() diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/main.py b/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/main.py index 231729059d0..c2214351e2d 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/main.py +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/main.py @@ -17,12 +17,9 @@ """Trusted user-and-sandbox session snapshots with optimistic concurrency. Hosted runs use an existing Cosmos DB container partitioned by /scope_key and -authenticate with managed identity. Both stores also expose the structural -``get_with_revision``/``compare_and_set`` capability that hosted agent approvals -require. Cosmos uses server-side create-only writes and exact ETag matches; use -a single-write-region account for approval authority. Local runs use snapshots -owned by one provider: their conditional writes are atomic only within one -process and event loop, and they are not a multi-user authentication boundary. +authenticate with managed identity. Local runs use process-local snapshots with +the same create-only/conditional-write behavior; they are not a multi-user +authentication boundary. """ from __future__ import annotations @@ -31,7 +28,6 @@ import hashlib import json import os -import re import uuid from contextlib import AsyncExitStack from copy import deepcopy @@ -49,24 +45,12 @@ from dotenv import load_dotenv _CONFLICT = "Another request advanced this agent session; reload before writing." -_SINGLE_ETAG = re.compile(r'"[\x21\x23-\x7e\x80-\xff]*"') _MAX_COSMOS_ITEM_BYTES = 2_000_000 _SESSION_TOO_LARGE = ( "Agent session exceeds the 2,000,000-byte Cosmos snapshot budget; reduce session state or start a new conversation." ) -def _validate_revision(expected_revision: str | None) -> None: - if expected_revision is not None and (not isinstance(expected_revision, str) or not expected_revision): - raise ValueError("expected_revision must be None or a non-empty string.") - - -def _validate_cosmos_etag(etag: str) -> None: - # If-Match treats a wildcard or list as something other than one exact revision. - if _SINGLE_ETAG.fullmatch(etag) is None: - raise RuntimeError("A Cosmos revision must be a single strong ETag.") - - class CosmosSessionStore(SessionStore): """Keep a request's ETags separate from every other request's working copy.""" @@ -90,40 +74,23 @@ def _item_id(self, session_id: str) -> str: async def get(self, session_id: str) -> AgentSession | None: """Load by the host's response/conversation key, not the inner MAF ID.""" - session, etag = await self.get_with_revision(session_id) - self._etags[session_id] = etag - return session - - async def get_with_revision(self, session_id: str) -> tuple[AgentSession | None, str | None]: - """Return an independent snapshot and its ETag without caching that ETag.""" item_id = self._item_id(session_id) try: item = await self._container.read_item(item=item_id, partition_key=self._scope_key) except CosmosResourceNotFoundError: - return None, None + self._etags[session_id] = None + return None if item.get("scope_key") != self._scope_key or item.get("id") != item_id: raise RuntimeError("A stored agent session does not belong to this trusted user and sandbox.") etag = item.get("_etag") if not isinstance(etag, str) or not etag: raise RuntimeError("Stored Cosmos session is missing its ETag.") - _validate_cosmos_etag(etag) - return AgentSession.from_dict(item["session"]), etag + session = AgentSession.from_dict(item["session"]) + self._etags[session_id] = etag + return session async def set(self, session_id: str, session: AgentSession) -> None: """Create a new key, or replace only the version this request loaded.""" - self._etags[session_id] = await self.compare_and_set( - session_id, session, expected_revision=self._etags.get(session_id) - ) - - async def compare_and_set(self, session_id: str, session: AgentSession, *, expected_revision: str | None) -> str: - """Create only when ``expected_revision`` is None; otherwise replace only that ETag. - - Conflicts raise ``RuntimeError`` and are never retried as an upsert. A failed or - cancelled write may still have committed, so callers must reload before deciding. - """ - _validate_revision(expected_revision) - if expected_revision is not None: - _validate_cosmos_etag(expected_revision) item: dict[str, Any] = { "id": self._item_id(session_id), "scope_key": self._scope_key, @@ -132,26 +99,26 @@ async def compare_and_set(self, session_id: str, session: AgentSession, *, expec if len(json.dumps(item, separators=(",", ":")).encode("utf-8")) > _MAX_COSMOS_ITEM_BYTES: raise ValueError(_SESSION_TOO_LARGE) try: - if expected_revision is None: + etag = self._etags.get(session_id) + if etag is None: result = await self._container.create_item(body=item) else: result = await self._container.replace_item( item=item["id"], body=item, - etag=expected_revision, + etag=etag, match_condition=MatchConditions.IfNotModified, ) except CosmosHttpResponseError as exc: if exc.status_code == 413: raise ValueError(_SESSION_TOO_LARGE) from exc - if exc.status_code not in (404, 409, 412): + if exc.status_code not in (409, 412): raise raise RuntimeError(_CONFLICT) from exc new_etag = result.get("_etag") if not isinstance(new_etag, str) or not new_etag: raise RuntimeError("Cosmos did not return an ETag after saving.") - _validate_cosmos_etag(new_etag) - return new_etag + self._etags[session_id] = new_etag async def delete(self, session_id: str) -> None: """Delete the loaded version; an absent key is an idempotent no-op.""" @@ -160,7 +127,6 @@ async def delete(self, session_id: str) -> None: await self.get(session_id) etag = self._etags[session_id] if etag is not None: - _validate_cosmos_etag(etag) try: await self._container.delete_item( item=item_id, @@ -195,34 +161,18 @@ def _key(self, session_id: str) -> tuple[str, str]: return self._scope_key, session_id async def get(self, session_id: str) -> AgentSession | None: - session, revision = await self.get_with_revision(session_id) - self._etags[session_id] = revision - return session - - async def get_with_revision(self, session_id: str) -> tuple[AgentSession | None, str | None]: - """Return an independent snapshot and its revision without caching that revision.""" item = self._snapshots.get(self._key(session_id)) - if item is None: - return None, None - return AgentSession.from_dict(deepcopy(item[1])), item[0] + self._etags[session_id] = item[0] if item else None + return AgentSession.from_dict(deepcopy(item[1])) if item else None async def set(self, session_id: str, session: AgentSession) -> None: - self._etags[session_id] = await self.compare_and_set( - session_id, session, expected_revision=self._etags.get(session_id) - ) - - async def compare_and_set(self, session_id: str, session: AgentSession, *, expected_revision: str | None) -> str: - """Create only when ``expected_revision`` is None; otherwise replace only that revision.""" - _validate_revision(expected_revision) key = self._key(session_id) - snapshot = deepcopy(session.to_dict()) - # No await between the check and the write keeps this atomic within one event loop. item = self._snapshots.get(key) - if (item[0] if item else None) != expected_revision: + if (item[0] if item else None) != self._etags.get(session_id): raise RuntimeError(_CONFLICT) - revision = uuid.uuid4().hex - self._snapshots[key] = revision, snapshot - return revision + etag = uuid.uuid4().hex + self._snapshots[key] = etag, deepcopy(session.to_dict()) + self._etags[session_id] = etag async def delete(self, session_id: str) -> None: key = self._key(session_id) From 8925c74885203c8ccada1695d0a5d0f08ee296f0 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 12:35:45 +0100 Subject: [PATCH 43/55] Python: Update approval translation tests for session request map --- .../test_approval_translation.py | 30 ++++++++----------- 1 file changed, 12 insertions(+), 18 deletions(-) diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_approval_translation.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_approval_translation.py index 40b2dec74a1..a1609f0d5ba 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_approval_translation.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_approval_translation.py @@ -45,16 +45,14 @@ async def test_history_and_input_conversions_only_read_approval_state(tmp_path: Path, approved: bool) -> None: store = SqliteSessionStore(tmp_path / "sessions.db") session = await pending_session(store) - state = SessionApprovalState(session, store) - token = await state.preflight(["wire-0", "wire-1"]) - assert token is not None + state = SessionApprovalState(session) session_before = deepcopy(session.to_dict()) writes_before = store.write_count - stored_before: dict[str, tuple[dict[str, Any], str | None]] = {} - for key in ("response-alias", "conversation-alias", token.authority_id): - stored, revision = await store.get_with_revision(key) + stored_before: dict[str, dict[str, Any]] = {} + for key in ("response-alias", "conversation-alias"): + stored = await store.get(key) assert stored is not None - stored_before[key] = (stored.to_dict(), revision) + stored_before[key] = stored.to_dict() output_items: list[OutputItem] = [ OutputItemMcpApprovalRequest({ @@ -101,19 +99,16 @@ async def test_history_and_input_conversions_only_read_approval_state(tmp_path: assert session.to_dict() == session_before assert store.write_count == writes_before - assert await state.preflight(["wire-0", "wire-1"]) == token for key, expected in stored_before.items(): - stored, revision = await store.get_with_revision(key) + stored = await store.get(key) assert stored is not None - assert (stored.to_dict(), revision) == expected + assert stored.to_dict() == expected -async def test_partial_input_conversion_does_not_consume_pending_approvals(tmp_path: Path) -> None: +async def test_unknown_input_conversion_does_not_mutate_session(tmp_path: Path) -> None: store = SqliteSessionStore(tmp_path / "sessions.db") session = await pending_session(store) - state = SessionApprovalState(session, store) - token = await state.preflight(["wire-0", "wire-1"]) - assert token is not None + state = SessionApprovalState(session) session_before = deepcopy(session.to_dict()) writes_before = store.write_count items: list[Item] = [ @@ -121,12 +116,11 @@ async def test_partial_input_conversion_does_not_consume_pending_approvals(tmp_p MCPApprovalResponse({"type": "mcp_approval_response", "approval_request_id": "missing", "approve": False}), ] - with pytest.raises(_PublicResponseFailure, match="not in this session's history"): + with pytest.raises(_PublicResponseFailure, match="not in this session"): await _items_to_messages(items, approval_storage=state) assert session.to_dict() == session_before assert store.write_count == writes_before - assert await state.preflight(["wire-0", "wire-1"]) == token @pytest.mark.parametrize( @@ -149,9 +143,9 @@ async def test_partial_input_conversion_does_not_consume_pending_approvals(tmp_p ids=["request", "response"], ) async def test_history_conversion_rejects_unknown_approval_ids(item: OutputItem) -> None: - state = SessionApprovalState(AgentSession(), None) + state = SessionApprovalState(AgentSession()) - with pytest.raises(_PublicResponseFailure, match="not in this session's history"): + with pytest.raises(_PublicResponseFailure, match="not in this session"): await _output_items_to_messages([item], approval_storage=state) From e247c0c9000b22a53705c96651a541584f8dc933 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 13:02:18 +0100 Subject: [PATCH 44/55] Python: Use Core session approvals and workflow request_info for Foundry Responses approvals Remove the Responses approval preflight, claim/seal and pre-stream 400 path. Agents pass the same AgentSession to Core, which owns pending approvals. Workflows rely on request_info and checkpoints; partial batches re-project still-pending requests under new wire IDs, and failures before the first superstep release the claim without blocking the lineage. Update ADR 0055, the package README and the custom_storage sample README. --- .../0055-python-foundry-hosting-contracts.md | 41 +- python/packages/foundry_hosting/README.md | 117 ++--- .../_responses_agent.py | 83 +-- .../_responses_preflight.py | 264 ---------- .../_responses_shared.py | 63 ++- .../_responses_workflow.py | 41 +- .../_workflow_state.py | 80 +-- .../foundry_hosting/agent_approval_helpers.py | 115 +++++ .../foundry_hosting/test_agent_approvals.py | 126 +++++ .../test_approval_translation.py | 13 +- .../test_invocations_workflow.py | 54 +- .../foundry_hosting/test_native_responses.py | 297 ++++++----- .../foundry_hosting/test_workflow_state.py | 106 ++-- .../foundry_hosting/tests/test_responses.py | 471 ++---------------- .../responses/custom_storage/README.md | 60 +-- 15 files changed, 736 insertions(+), 1195 deletions(-) delete mode 100644 python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_preflight.py create mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/agent_approval_helpers.py create mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/test_agent_approvals.py diff --git a/docs/decisions/0055-python-foundry-hosting-contracts.md b/docs/decisions/0055-python-foundry-hosting-contracts.md index 7633ed1f576..aa0022fa7b2 100644 --- a/docs/decisions/0055-python-foundry-hosting-contracts.md +++ b/docs/decisions/0055-python-foundry-hosting-contracts.md @@ -57,8 +57,8 @@ remain experimental. Separate classes do not require separate distribution packa ### Request adaptation and construction Use `parse_input` for custom input adaptation across both protocols. Agent parsers return `InvocationRun`; -workflow parsers return `WorkflowTurn` containing either typed start input or complete pending replies. -Parsing does not replace the host's checkpoint and pending-authority validation. +workflow parsers return `WorkflowTurn` containing either typed start input or pending replies. +Parsing does not replace the host's checkpoint binding or the workflow runtime's reply validation. Use `ResponsesRequest` for the Responses wrapper, including factory and option-hook inputs. Do not retain aliases for the former parser keywords or request-type name. @@ -91,7 +91,7 @@ not request-owned instance fields. ### Persistence and history ownership Regular agents continue through agent-session storage. Native workflows continue through their exact -scoped checkpoints, including pending-reply authority. Neither execution model converts the other's state. +scoped checkpoints, including pending `request_info` requests. Neither execution model converts the other's state. Native workflow agents use checkpoint-owned history, not private inference-service continuation. Keep three storage decisions distinct: @@ -151,28 +151,29 @@ or other request-option precedence. ### Approvals and consent -Use session-backed authority for regular-agent approvals rather than a separate public approval-store API. -Native workflow pending authority remains checkpoint-owned. Keep one canonical pending batch in the configured -session store; response and conversation aliases retain history and a link, not independent permission. -Require structural `get_with_revision` and `compare_and_set` methods with create-only and exact-revision -semantics. Foundry-managed storage uses AgentServer's create-only and conditional-write primitives without -assumptions about its underlying topology. Custom providers must coordinate all writers; a process-local -lock does not provide cross-process approval authority. Old separate-store approvals require a fresh -conversation, not a silent migration. - -Reject incomplete hosted MCP approval sets with HTTP 400 before streaming, response headers, -`response.created`, or protected dispatch, without consuming pending authority. -A complete batch may mix approvals and rejections. -Revalidate and claim authority after other reservations and before protected dispatch. A race after preflight -can still fail after streaming starts. A consumed or uncertain claim is not reopened automatically, including -when the client repeats the same response ID. Non-approval redelivery retains the SDK's behavior. -No claim provides exactly-once external side effects. +Use the framework's built-in approval handling and do not add a host approval authority. +Regular agents keep pending approval requests in the same `AgentSession` that the host loads and saves through +the configured session store. Core binds each approval response to a recorded pending request, rebuilds the call +from that request, and consumes it. The host stores only a translation map from the SDK-generated wire item ID to +the original request in that session's state. This map does not authorize execution. Native workflows use +`request_info` and their exact checkpoint; the host translates wire IDs to request IDs in its checkpoint binding. +There is no separate public approval-store API, no conditional-write capability for custom session stores, and no +silent migration of old separate-store approvals. + +Do not preflight approval replies before the response starts. The host drops a reply with an unknown wire ID +with a warning, and the framework does not execute a reply that matches no pending request. A turn whose input +contains only dropped replies fails. Partial batches follow the framework: an agent holds the batch until every +request has a reply, and a workflow runs the answered requests. Responses hosts emit requests that are still +pending again under new wire IDs; Invocations workflows keep their request IDs. A batch may mix approvals and rejections. A workflow reply that the runtime rejects before its first superstep releases the +lineage head unchanged; a failure after a superstep starts blocks that lineage. Concurrent replies, forks, and +retries have the same guarantees as any agent run with a shared session or any workflow checkpoint resume. +No path provides exactly-once external side effects. Represent invocation-time OAuth consent as structured consent with incomplete response status. Pair each emitted function call with one terminal result, preserve completed sibling results, and stop later protected calls. Require `store=true` so continuation can retain the required state; do not support ephemeral consent under `store=false`. -Buffer authority-bearing output until authority and snapshots are saved. Invocation-time consent with +Buffer consent and approval output until the session snapshots are saved. Invocation-time consent with inference-service history is unsupported and fails explicitly; connection-time consent remains separate. A consent failure after execution starts is a failed response, not a pre-header HTTP 400. diff --git a/python/packages/foundry_hosting/README.md b/python/packages/foundry_hosting/README.md index 4da74d6a6bf..59d199b3784 100644 --- a/python/packages/foundry_hosting/README.md +++ b/python/packages/foundry_hosting/README.md @@ -462,7 +462,7 @@ The Responses agent response has status `incomplete`, and its output contains: The host emits a consent request for one `(consent_link, server_label)` pair only once in a response. Non-streaming calls return these items in the final response. Streaming calls give the same items. The host buffers them and -publishes them only after it saves the approval authority and the session snapshots. +publishes them only after it saves the session snapshots. Other tool calls in the same run behave as follows: @@ -531,9 +531,8 @@ encoding of the store name. For example: - Responses agent sessions: `YWdlbnRfc2Vzc2lvbnM.json` - Workflow checkpoints: one file per context, encoded from `checkpoints/` -The file-based fallback supports ordinary session and checkpoint persistence, but cannot atomically -publish or claim agent approvals across processes. Local approval flows require a custom conditional -session store; see [Function approvals](#function-approvals). +The file-based fallback supports ordinary session and checkpoint persistence, including pending agent +approvals. It coordinates writers within one process only. > Read more about the Foundry durable state store in the [developer guide](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/agentserver/azure-ai-agentserver-core/docs/state-store-guide.md). @@ -608,7 +607,7 @@ The committed head also records its completing outer response ID. If a crash occ outer completion, that response can recover its saved final output without reclaiming or rewriting the head. A different in-flight claim or completing response is not accepted as ownership. When continuing by `previous_response_id`, the prior response is claimed with a conditional write **after** -the input is validated, so an invalid approval response does not consume a usable parent. A second branch +the input is validated, so invalid input does not consume a usable parent. A second branch cannot reuse the same downstream service thread; attempting to fork a named service conversation is also rejected. New hosted keys are created only if absent. Custom store providers must provide equivalent scoped conditional writes for concurrent turns, including the pre-dispatch claim. Local callers can still upsert directly without @@ -677,80 +676,39 @@ locally. Stored checkpoints are scoped under `checkpoints`. ### Function approvals -`ResponsesHostServer` persists agent approval state through the same configured -`agent_session_store_provider` used for `AgentSession` snapshots. Approval authority belongs to -one pending response in the same trusted user/sandbox scope. Response and conversation snapshots -retain history and a link to that authority; they are not independent sources of permission. -Native workflow pending replies remain checkpoint-owned, not agent-session approvals. +`ResponsesHostServer` uses the framework's built-in approval handling. Core records each pending +`function_approval_request` in the `AgentSession`, and the host saves that session with the configured +`agent_session_store_provider`. When a reply arrives, the host loads the same session and translates each +`mcp_approval_response` to a `function_approval_response`. Core binds the reply to its recorded request, +rebuilds the call from that request, and consumes it. A reply that matches no pending request is not executed. + +The SDK generates the wire ID of each `mcp_approval_request` item. The host keeps a map from that wire ID to +the original request in the same session state. The map only translates IDs; it does not authorize execution. +Custom session stores need only the ordinary `SessionStore` operations. + +- Approvals and rejections may be mixed in one reply. +- A partial reply is allowed. Core holds the batch until every request has a reply, and the response emits the + unanswered requests again under new wire IDs. Reply to those new IDs. +- The host drops a reply with an unknown wire ID and logs a warning. A turn whose input contains only dropped + replies fails. +- Invalid replies are not rejected before the response starts. They produce a failed response instead of an + HTTP 400. +- `store=false` cannot persist or resume pending approvals. +- Concurrent replies, forks, and retries have the same guarantees as any agent run that shares a session. + Approval handling does not provide exactly-once tool side effects. + +Native workflows keep pending replies in their `request_info` requests and checkpoint, not in an agent session. +`ResponsesWorkflowHostServer` maps wire IDs to request IDs in the checkpoint binding. A partial reply runs the +answered requests, and the response emits the unanswered requests again under new wire IDs. A reply that the +workflow runtime rejects before its first superstep, such as an unknown request ID or a mismatched reply type, +fails the turn and leaves the lineage head unchanged, so a valid reply can be retried. A failure after a +superstep starts blocks that lineage. **Migration/reset:** pending approvals from the old separate function-approval store are not migrated. Start a fresh conversation without an old `previous_response_id` or conversation ID and obtain fresh approvals. Do not copy legacy approval records into session state. The public `FunctionApprovalStore`, `FoundryFunctionApprovalStore`, and `FunctionApprovalStoreProvider` exports and the `function_approval_store_provider=` constructor setting are removed. -Missing or expired authority fails closed, even when a snapshot still contains the historical -request. Retained approval history does not authorize another tool execution. - -#### Custom conditional session stores - -A custom store used for agent approvals must implement ordinary `SessionStore` operations and -these additional async methods. This is a structural capability; no extra public protocol or -private framework import is required. - -- `get_with_revision(session_id)` returns an independent `AgentSession` snapshot and its exact, - nonempty, opaque revision, or exactly `(None, None)` when absent. -- `compare_and_set(session_id, session, *, expected_revision)` returns the nonempty revision of the - persisted version. `expected_revision=None` means atomic **create only**; a nonempty revision - means replace only that exact existing version. - -Revisions must identify exact persisted versions and must never be reused after writes. A read's -revision belongs to that read, not to mutable per-request ETag state shared by multiple reads. -Conflicts raise `RuntimeError` or a subtype; never retry as an unconditional upsert. Storage I/O -errors and cancellation propagate. A write acknowledgement without a revision is a failure, even -if the backend stored the value. - -Storage lookup keys need not equal the snapshot's inner `AgentSession.session_id`. Support opaque -keys, including keys containing `/`, and preserve the inner session ID. Ordinary response or -conversation alias cleanup must not delete approval authority. Custom providers own retention: -alias and authority lifetimes are independent, and authority is never recreated from an alias -after it expires. - -The default hosted Foundry store uses server-side create-only and ETag-conditional writes. -The default non-hosted store rejects approval writes with an explicit error requiring -`get_with_revision` and `compare_and_set`. A single-process development store can coordinate only -its own process; production and multi-worker stores must coordinate all writers through the -backend. A process-local lock is not cross-process CAS. - -#### Approval batches and failure boundaries - -Reply to the complete pending approval batch. Approvals and rejections may be mixed, but omitted, -duplicate, stale, or foreign controls are invalid. Publishing pending authority requires -`store=true`; `store=false` cannot publish or resume host-managed approvals. - -Both Responses hosts perform a read-only MCP approval preflight. Invalid or incomplete batches return -HTTP 400 before headers, `response.created`, parsing, or protected execution, without consuming usable -authority. A conversation with pending approvals also rejects a plain new turn; finish its pending batch -instead. Unsupported state formats, missing conditional-store capability, and storage failures are not -classified as invalid approval controls. - -The handler independently revalidates the batch and claims it only after other input/options checks and -reservations. A competing request can win between preflight and claim: the losing request can therefore -fail after streaming starts, but does not dispatch protected work. -Supplying a duplicate response ID through `x-agent-response-id` or body `response_id` does not bypass -preflight. After a successful claim, repeating the complete approval continuation is rejected with HTTP 400, -not replayed as another execution. Non-approval redelivery still delegates to AgentServer; this is not a -general idempotency guarantee. - -Claiming a batch is an irreversible conditional transition before protected execution. It does -not provide exactly-once tool side effects: a crash after a successful claim can lose work. -A failed or cancelled claim write may already have committed. Do not reopen the batch or -automatically dispatch the protected work after an uncertain result. -Reconcile any external effects before deciding what to retry; start a fresh conversation and obtain fresh -approvals for new work rather than reusing consumed or uncertain authority. - -Approval history is bounded to 1,024 requests and 1 MiB of serialized approval-content JSON. -Exceeding either bound fails explicitly and requires a fresh conversation; history is not silently -pruned. ## Native Invocations workflows @@ -802,10 +760,11 @@ caller JSON cannot assert factory ownership. The workflow uses one fixed Invocations lineage inside the trusted user and platform sandbox scope. Later turns restore the **exact** committed checkpoint, not a workflow name's unrelated latest checkpoint. Graph changes, stale writers, -forged/cross-scope/replayed decisions and duplicate authority fail before -executor/response-handler dispatch. Reply with the complete pending batch: -partial, unallowlisted, or invalid batches do not claim or consume any usable -authority, so the complete valid batch can be retried. Native factories +cross-scope and replayed replies fail before executor/response-handler dispatch. +A partial reply runs the answered requests; the rest stay pending under their +request IDs. Unallowlisted batches are rejected before the turn is claimed. A +reply that the workflow runtime rejects before its first superstep fails the turn +and leaves the head unchanged, so a valid reply can be retried. Native factories and explicit `client_kwargs`/`function_invocation_kwargs` keep their existing purposes; they do not introduce arbitrary entry-state or per-executor run-option APIs. Host-controlled identity, storage and execution controls cannot be supplied @@ -824,8 +783,8 @@ then `done` with the **sandbox** `session_id`. Live output is provisional until is conditionally committed. Snapshot retention is bounded by both event count and encoded bytes; exceeding either limit fails the turn without `done`. A conflict, encoding failure, execution failure or -interruption cannot emit successful completion. Failed claimed turns are blocked -to avoid replaying uncertain effects; start a new sandbox instead of blindly +interruption cannot emit successful completion. Turns that fail after their first +superstep starts are blocked to avoid replaying uncertain effects; start a new sandbox instead of blindly retrying non-idempotent work. Checkpoints do not provide exactly-once tool effects. If a connection drops after commit, retrying the same trusted user/sandbox/call ID replays that response's complete stored snapshot without executing the workflow or diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py index 59b8111f60c..18d9369a6cc 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py @@ -35,7 +35,7 @@ ) from agent_framework._telemetry import mark_feature_used from agent_framework.exceptions import AgentFrameworkException -from azure.ai.agentserver.core import FoundryAgentRequestContext, get_request_context +from azure.ai.agentserver.core import get_request_context from azure.ai.agentserver.responses import ( ResponseContext, ResponseProviderProtocol, @@ -51,14 +51,8 @@ ) from azure.ai.agentserver.responses.streaming._checkpoint import ResponseCheckpointEvent -from ._approvals import SessionApprovalState, _InvalidApproval # pyright: ignore[reportPrivateUsage] +from ._approvals import SessionApprovalState from ._feature_usage import FeatureIndex -from ._responses_preflight import ( - _InvalidApprovalInput, # pyright: ignore[reportPrivateUsage] - approval_controls, - bind_approval_preflight, - has_unresolved_input, -) from ._responses_shared import ( _HOSTED_CONVERSATION_CLAIM_KEY, # pyright: ignore[reportPrivateUsage] _HOSTED_CONVERSATION_COMMITTED_KEY, # pyright: ignore[reportPrivateUsage] @@ -280,8 +274,8 @@ def __init__( prefix: The URL prefix for the server. response_store: Optional response store for caller-facing persistence and history. agent_session_store_provider: Optional provider for MAF agent session storage. - If not provided, a default `AgentSessionStoreProvider` will be used. Approval continuations require - atomic create-only and revision-conditional writes in this store. + If not provided, a default `AgentSessionStoreProvider` will be used. MCP approval + continuations use the same saved `AgentSession`. allowed_oauth_consent_origins: Optional exact HTTPS origins allowed for OAuth consent links. When omitted, hosting retains its existing safe-HTTPS validation without restricting the destination origin. When provided, every link must match an entry; an empty sequence rejects @@ -414,7 +408,6 @@ def __init__( self._session_storage_provider = ( AgentSessionStoreProvider() if agent_session_store_provider is None else agent_session_store_provider ) - bind_approval_preflight(self, prefix=prefix, preflight=self._preflight_approvals) # Lazy agent lifecycle: the agent (and any MCP tools it owns) is entered on # the first request rather than at server startup, so that authentication @@ -428,38 +421,6 @@ def __init__( mark_feature_used(FeatureIndex.FOUNDRY_HOSTING) - async def _preflight_approvals( - self, - request: CreateResponse, - context: ResponseContext, - platform_context: FoundryAgentRequestContext, - ) -> None: - items = [cast(Mapping[str, Any], item) for item in await context.get_input_items()] - ids = approval_controls(items) - previous = request.get("previous_response_id") - previous = previous if isinstance(previous, str) and previous else None - session_id = context.conversation_id or previous - if session_id is None: - if ids: - raise _InvalidApprovalInput("The approval has no pending agent session.") - return - storage = self._session_storage_provider.get_store(config=self.config, platform_context=platform_context) - session = await storage.get(session_id) - if session is None: - if ids: - raise _InvalidApprovalInput("The approval is unavailable in this agent session.") - return - state = SessionApprovalState(session, storage) - try: - claim = await state.preflight(ids) - except _InvalidApproval as exc: - raise _InvalidApprovalInput(str(exc)) from exc - if claim is not None: - if request.get("store") is False: - raise _InvalidApprovalInput("Approval continuation requires store=true.") - if len(items) != len(ids) or has_unresolved_input(request, items): - raise _InvalidApprovalInput("Pending MCP approvals cannot be mixed with other input.") - async def _ensure_agent_ready(self) -> None: """Lazily enter the agent's async context exactly once. @@ -800,7 +761,15 @@ async def _load_request_messages( async def _load_input() -> list[Message]: input_items = await context.get_input_items() resolved_storage = await approval_ready if approval_ready is not None else approval_storage - return await _items_to_messages(input_items, approval_storage=resolved_storage) + messages = await _items_to_messages(input_items, approval_storage=resolved_storage) + if ( + input_items + and not messages + and all(cast(Mapping[str, Any], item).get("type") == "mcp_approval_response" for item in input_items) + ): + # Do not run the model, or consume a single-use parent, when every reply was dropped. + raise _PublicResponseFailure(ValueError("No approval reply matches a request in this session.")) + return messages async def _load_history() -> list[Message]: if not uses_agent_server_history: @@ -926,6 +895,7 @@ async def _handle_inner_agent( if stored or session_load_id is not None else None ) + # Reads start before the session loads; wire-ID translation waits for the session's approval map. approval_ready: asyncio.Future[SessionApprovalState] = asyncio.get_running_loop().create_future() request_messages_task = asyncio.ensure_future( self._load_request_messages( @@ -953,19 +923,8 @@ async def _handle_inner_agent( ) ) session = agent.create_session() - approval_session = stored_session or session - approval_storage = SessionApprovalState(approval_session, session_storage, response_id=context.response_id) - input_items = [cast(Mapping[str, Any], item) for item in await context.get_input_items()] - try: - approval_ids = approval_controls(input_items) - approval_claim = await approval_storage.preflight(approval_ids) - if approval_claim is not None: - if not stored: - raise _InvalidApprovalInput("Approval continuation requires store=true.") - if len(input_items) != len(approval_ids) or has_unresolved_input(request, input_items): - raise _InvalidApprovalInput("Pending MCP approvals cannot be mixed with other input.") - except (_InvalidApproval, _InvalidApprovalInput) as exc: - raise _PublicResponseFailure(exc) from None + # Core's session approval tracking binds and consumes replies; this map only translates wire IDs. + approval_storage = SessionApprovalState(session) approval_ready.set_result(approval_storage) provider_state = session.state.get(_HOSTED_PROVIDER_STATE_KEY) if context.conversation_id is not None: @@ -1121,9 +1080,6 @@ async def _handle_inner_agent( finally: session.state.pop(_HOSTED_CONVERSATION_CLAIM_KEY, None) - if approval_claim is not None: - await approval_storage.claim(approval_claim, response_id=context.response_id) - consent_scope = _activate_toolbox_consent_scope(allowed_origins=self._allowed_oauth_consent_origins) async def track_update( @@ -1270,13 +1226,6 @@ async def track_update( cancellation_signal.is_set() and not context.client_cancelled and not context.shutdown.is_set() ) if stored and session_storage is not None and not stored_output_violation and final_provider_state: - if ( - request_failure is None - and not request_interrupted - and not context.shutdown.is_set() - and not cancellation_signal.is_set() - ): - await approval_storage.seal() if context.conversation_id is not None: session.state[_HOSTED_SOURCE_CONVERSATION_KEY] = context.conversation_id await _set_agent_session(session_storage, context.response_id, session) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_preflight.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_preflight.py deleted file mode 100644 index d99fd812adf..00000000000 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_preflight.py +++ /dev/null @@ -1,264 +0,0 @@ -# Copyright (c) Microsoft. All rights reserved. - -"""Read-only approval validation before the Responses SDK opens a stream.""" - -from __future__ import annotations - -import logging -from collections.abc import Awaitable, Callable, Mapping, Sequence -from copy import deepcopy -from typing import Any, cast - -from azure.ai.agentserver.core import ( - FoundryAgentRequestContext, - read_request_id, - reset_request_context, - set_request_context, -) -from azure.ai.agentserver.core.platform_headers import FOUNDRY_CALL_ID, USER_ID -from azure.ai.agentserver.responses import ( - FoundryApiError, - PlatformContext, - ResponseContext, -) -from azure.ai.agentserver.responses._egress import strip_internal_metadata -from azure.ai.agentserver.responses.hosting import ResponsesAgentServerHost -from azure.ai.agentserver.responses.hosting._endpoint_handler import _ResponseEndpointHandler # pyright: ignore[reportPrivateUsage] -from azure.ai.agentserver.responses.hosting._request_parsing import ( - _prevalidate_identity_payload, # pyright: ignore[reportPrivateUsage] - _resolve_conversation_id, # pyright: ignore[reportPrivateUsage] - _resolve_identity_fields, # pyright: ignore[reportPrivateUsage] - _resolve_session_id, # pyright: ignore[reportPrivateUsage] -) -from azure.ai.agentserver.responses.hosting._validation import ( - ERROR_SOURCE_PLATFORM, - error_response, - is_platform_error, - parse_and_validate_create_response, -) -from azure.ai.agentserver.responses.models import CreateResponse -from azure.ai.agentserver.responses.models._helpers import get_input_expanded, to_output_item -from azure.ai.agentserver.responses.models.runtime import ResponseModeFlags -from starlette.requests import Request -from starlette.responses import Response -from starlette.routing import Route - -from ._scope import FoundryRequestScope -from ._workflow_state import FoundryWorkflowBindingStore - -logger = logging.getLogger(__name__) - - -class _InvalidApprovalInput(ValueError): - """A caller's approval controls cannot resume the current pending batch.""" - - -_Preflight = Callable[[CreateResponse, ResponseContext, FoundryAgentRequestContext], Awaitable[None]] - - -def _create_route_path(prefix: str) -> str: - normalized = prefix.strip() - if normalized and not normalized.startswith("/"): - normalized = f"/{normalized}" - return f"{normalized.rstrip('/')}/responses" - - -def bind_approval_preflight(host: ResponsesAgentServerHost, *, prefix: str, preflight: _Preflight) -> None: - """Wrap only SDK create; delegate malformed requests and draining to the SDK.""" - for index, route in enumerate(host.router.routes): - if ( - not isinstance(route, Route) - or route.path != _create_route_path(prefix) - or route.name != "create_response" - or "POST" not in (route.methods or ()) - ): - continue - handler = cast(Callable[[Request], Awaitable[Response]], route.endpoint) - endpoint = getattr(handler, "__self__", None) - if not isinstance(endpoint, _ResponseEndpointHandler): - raise RuntimeError("The Responses SDK create endpoint is unavailable for approval preflight.") - - async def checked_create( - request: Request, - *, - endpoint: _ResponseEndpointHandler = endpoint, - handler: Callable[[Request], Awaitable[Response]] = handler, - ) -> Response: - if endpoint._is_draining: # pyright: ignore[reportPrivateUsage] - return await handler(request) - - # The SDK mutates the cached JSON when stripping internal metadata. - # Inspect a copy so its own validation receives the original request. - try: - payload = deepcopy(await request.json()) - strip_internal_metadata(payload) - _prevalidate_identity_payload(payload) - parsed = parse_and_validate_create_response( - payload, - options=endpoint._runtime_options, # pyright: ignore[reportPrivateUsage] - ) - response_id, agent_reference = _resolve_identity_fields(parsed, request_headers=request.headers) - session_id = _resolve_session_id( - parsed, - payload, - env_session_id=host.config.session_id or "", - agent_reference=agent_reference, - ) - except (TypeError, ValueError, KeyError, AttributeError): - return await handler(request) - - platform = PlatformContext( - user_id_key=request.headers.get(USER_ID), - call_id=request.headers.get(FOUNDRY_CALL_ID), - ) - platform_context = FoundryAgentRequestContext( - user_id=platform.user_id_key or None, - call_id=platform.call_id or None, - session_id=session_id, - ) - previous = parsed.get("previous_response_id") - previous = previous if isinstance(previous, str) and previous else None - conversation_id = _resolve_conversation_id(parsed) - input_items = [ - output - for item in get_input_expanded(parsed) - if (output := to_output_item(item, response_id)) is not None - ] - context = ResponseContext( - response_id=response_id, - request=parsed, - mode_flags=ResponseModeFlags( - stream=bool(parsed.get("stream")), - store=parsed.get("store") is not False, - background=bool(parsed.get("background")), - ), - provider=endpoint._provider, # pyright: ignore[reportPrivateUsage] - input_items=input_items, - previous_response_id=previous, - conversation_id=conversation_id, - platform_context=platform, - session_id=session_id, - ) - headers = endpoint._session_headers(session_id) # pyright: ignore[reportPrivateUsage] - request_id = read_request_id(request.scope) - token = set_request_context(platform_context) - try: - await preflight(parsed, context, platform_context) - except _InvalidApprovalInput as exc: - return error_response(exc, headers, request_id=request_id) - except Exception as exc: - logger.error("Responses approval preflight failed (%s).", type(exc).__name__) - # A backend may raise ValueError; it is not an invalid request. - error = RuntimeError("Responses approval preflight failed; inspect the host logs.") - source = ERROR_SOURCE_PLATFORM if is_platform_error(exc) or isinstance(exc, FoundryApiError) else None - return error_response(error, headers, request_id=request_id, error_source=source) - finally: - reset_request_context(token) - return await handler(request) - - host.router.routes[index] = Route( - route.path, - endpoint=checked_create, - methods=list(route.methods or ()), - name=route.name, - include_in_schema=route.include_in_schema, - ) - return - raise RuntimeError("The Responses SDK create route is unavailable for approval preflight.") - - -def approval_controls(items: list[Mapping[str, Any]]) -> list[str]: - """Extract validated MCP decisions without applying generic reply rules.""" - ids: list[str] = [] - for item in items: - if item.get("type") != "mcp_approval_response": - continue - wire_id, decision = item.get("approval_request_id"), item.get("approve") - if not isinstance(wire_id, str) or not wire_id or type(decision) is not bool: - raise _InvalidApprovalInput("An approval reply requires its exact ID and a boolean decision.") - ids.append(wire_id) - return ids - - -def has_unresolved_input(request: Mapping[str, Any], items: Sequence[Mapping[str, Any]]) -> bool: - """Detect input references the SDK silently omitted during resolution.""" - return len(get_input_expanded(cast(CreateResponse, request))) != len(items) - - -async def preflight_workflow_approvals( - request: CreateResponse, - context: ResponseContext, - platform_context: FoundryAgentRequestContext, - host: ResponsesAgentServerHost, -) -> None: - """Check a native MCP batch against its exact completed checkpoint pair.""" - items = [cast(Mapping[str, Any], item) for item in await context.get_input_items()] - ids = approval_controls(items) - previous = request.get("previous_response_id") - previous = previous if isinstance(previous, str) and previous else None - if previous is None and context.conversation_id is None: - if ids: - raise _InvalidApprovalInput("The approval has no pending workflow checkpoint.") - return - scope = FoundryRequestScope.from_context(host.config, platform_context, local_session_id=context.response_id) - storage = FoundryWorkflowBindingStore(scope) - record = None - if previous is not None: - record, _ = await storage.get_response(previous) - if record is not None and record.status == "completed" and record.binding.conversation_id is None: - head, _ = await storage.get_head(record.binding.lineage_id, None) - else: - head = None - else: - head, _ = await storage.get_head(context.response_id, context.conversation_id) - if head is not None and head.binding is not None: - record, _ = await storage.get_response(head.binding.response_id) - - if ( - record is None - or record.status != "completed" - or record.snapshot is None - or head is None - or head.blocked - or head.response_id is not None - or head.binding != record.binding - ): - if ids: - raise _InvalidApprovalInput("The approval is unavailable in the current workflow checkpoint.") - return - aliases = record.approvals or {} - output = record.snapshot.get("output") - if not isinstance(output, list): - raise RuntimeError("The workflow approval snapshot has invalid output.") - approval_ids: set[str] = set() - for raw_item in cast(list[Any], output): - if not isinstance(raw_item, dict): - continue - item = cast(dict[str, Any], raw_item) - wire_id = item.get("id") - if item.get("type") == "mcp_approval_request" and isinstance(wire_id, str) and wire_id in aliases: - approval_ids.add(wire_id) - if not approval_ids: - if ids: - raise _InvalidApprovalInput("The workflow has no pending MCP approval batch.") - return - if request.get("store") is False: - raise _InvalidApprovalInput("Approval continuation requires store=true.") - if has_unresolved_input(request, items): - raise _InvalidApprovalInput("Pending workflow approvals cannot include unresolved input references.") - controls: list[str] = [] - for item in items: - item_type = item.get("type") - if item_type == "mcp_approval_response": - wire_id = item.get("approval_request_id") - if wire_id not in approval_ids: - raise _InvalidApprovalInput("An approval reply must match this exact pending checkpoint.") - elif item_type in ("function_call_output", "computer_call_output"): - wire_id = item.get("call_id") - if not isinstance(wire_id, str) or wire_id not in aliases or wire_id in approval_ids: - raise _InvalidApprovalInput("A reply must match this exact pending checkpoint.") - else: - raise _InvalidApprovalInput("Pending workflow approvals cannot be mixed with new input.") - controls.append(cast(str, wire_id)) - if len(controls) != len(set(controls)) or set(controls) != set(aliases): - raise _InvalidApprovalInput("Answer exactly the complete pending workflow request batch.") diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py index 7d14cbf9734..29b29c4e166 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py @@ -92,16 +92,16 @@ ) from mcp import MCPError -from ._approvals import SessionApprovalState +from ._approvals import SessionApprovalState, _InvalidApproval # pyright: ignore[reportPrivateUsage] logger = logging.getLogger(__name__) class _ApprovalRecorder(Protocol): - """Approval-request recorder used by the output tracker before an approval item is yielded. + """Records the wire ID of each approval item before the output tracker yields it. - Implementations may only stage the mapping; the host must keep the yielded events buffered until the staged - approval batch is durable. + The mapping only translates IDs. The host must buffer the yielded events until the state that holds the + mapping is saved. """ async def save_approval_request(self, approval_request_id: str, request: Content) -> None: @@ -1114,8 +1114,8 @@ async def handle( logical message and forces the previous output item closed, rather than being merged into it. approval_storage: Recorder that receives each ``function_approval_request`` under its generated - public ID before the approval item event is yielded. Recording may only stage the mapping; the - host must buffer yielded approval events until the staged batch is durable. + public ID before the approval item event is yielded. The host must buffer yielded approval + events until the state that holds the mapping is saved. start_new_content_part: Whether text and refusal content start a new independent content part instead of continuing the current streaming occurrence. """ @@ -1694,7 +1694,10 @@ async def _items_to_messages( # pyright: ignore[reportUnusedFunction] """ messages: list[Message] = [] for item in input_items: - messages.append(await _item_to_message(item, approval_storage=approval_storage)) + try: + messages.append(await _item_to_message(item, approval_storage=approval_storage)) + except _InvalidApproval as exc: + _log_dropped_approval(exc) return messages @@ -1786,6 +1789,17 @@ def _shell_command_output_to_content(output: Mapping[str, Any]) -> Content: ) +async def _load_approval_request(approval_storage: SessionApprovalState | None, wire_id: str) -> Content: + if approval_storage is None: + raise ValueError("ApprovalStorage is required to load approval request.") + return await approval_storage.load_approval_request(wire_id) + + +def _log_dropped_approval(exc: _InvalidApproval) -> None: + # Core authorizes approvals against the session's pending requests; an unknown wire ID is dropped. + logger.warning("Ignoring an MCP approval item: %s", exc) + + async def _item_to_message( item: Item, *, @@ -1805,6 +1819,7 @@ async def _item_to_message( Raises: ValueError: If the Item type is not supported. + _InvalidApproval: If an MCP approval item's wire ID is not in the session. """ if item["type"] == "message": if isinstance(item["content"], str): @@ -1881,32 +1896,12 @@ async def _item_to_message( ) if item["type"] == "mcp_approval_request": - if approval_storage is not None: - try: - function_approval_request_content = await approval_storage.load_approval_request(item["id"]) - except (KeyError, ValueError) as exc: - raise _PublicResponseFailure(exc) from None - else: - raise ValueError("ApprovalStorage is required to load approval request.") - return Message( - role="assistant", - contents=[function_approval_request_content], - ) + request_content = await _load_approval_request(approval_storage, item["id"]) + return Message(role="assistant", contents=[request_content]) if item["type"] == "mcp_approval_response": - if approval_storage is not None: - try: - function_approval_request_content = await approval_storage.load_approval_request( - item["approval_request_id"] - ) - except (KeyError, ValueError) as exc: - raise _PublicResponseFailure(exc) from None - else: - raise ValueError("ApprovalStorage is required to load approval request.") - return Message( - role="user", - contents=[function_approval_request_content.to_function_approval_response(item["approve"])], - ) + request_content = await _load_approval_request(approval_storage, item["approval_request_id"]) + return Message(role="user", contents=[request_content.to_function_approval_response(item["approve"])]) if item["type"] == "code_interpreter_call": return Message( @@ -2107,7 +2102,10 @@ async def _output_items_to_messages( # pyright: ignore[reportUnusedFunction] """ messages: list[Message] = [] for item in history: - messages.append(await _output_item_to_message(item, approval_storage=approval_storage)) + try: + messages.append(await _output_item_to_message(item, approval_storage=approval_storage)) + except _InvalidApproval as exc: + _log_dropped_approval(exc) return messages @@ -2124,6 +2122,7 @@ async def _output_item_to_message(item: OutputItem, *, approval_storage: Session Raises: ValueError: If the OutputItem type is not supported. + _InvalidApproval: If an MCP approval item's wire ID is not in the session. """ if item["type"] == "oauth_consent_request": item_data = cast("Mapping[str, Any]", item) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py index 4c08941d13e..5f1589ab408 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py @@ -37,6 +37,7 @@ from azure.ai.agentserver.responses.aio import ResponseEventStream from azure.ai.agentserver.responses.hosting import ResponsesAgentServerHost from azure.ai.agentserver.responses.models import CreateResponse, ResponseObject, ResponseStreamEvent +from azure.ai.agentserver.responses.models._helpers import get_input_expanded from azure.ai.agentserver.responses.streaming._checkpoint import ResponseCheckpointEvent from pydantic import BaseModel from starlette.requests import Request @@ -45,7 +46,6 @@ from starlette.types import Send from ._feature_usage import FeatureIndex -from ._responses_preflight import bind_approval_preflight, has_unresolved_input, preflight_workflow_approvals from ._responses_shared import ( _HOSTED_PROVIDER_USAGE_KEY, # pyright: ignore[reportPrivateUsage] _agent_response_updates, # pyright: ignore[reportPrivateUsage] @@ -164,8 +164,8 @@ def _snapshot(stream: ResponseEventStream) -> dict[str, Any]: async def _load_replies(request: ResponsesRequest, run: HostedWorkflowRun) -> dict[str, Any]: items = await request.get_input_items() if not run.pending_requests or not items: - raise _WorkflowRequestError("Workflow replies require an exact pending stored checkpoint.") - if has_unresolved_input(request.request, items): + raise _WorkflowRequestError("Workflow replies require a pending stored checkpoint.") + if len(get_input_expanded(cast(CreateResponse, request.request))) != len(items): raise _WorkflowRequestError("Pending workflow replies cannot include unresolved input references.") replies: dict[str, Any] = {} for input_item in items: @@ -176,12 +176,11 @@ async def _load_replies(request: ResponsesRequest, run: HostedWorkflowRun) -> di raise _WorkflowRequestError("An approval reply requires its exact ID and a boolean decision.") request_id = run.approvals.get(wire_id) pending = run.pending_requests.get(request_id) if request_id is not None else None - if ( - pending is None - or not isinstance(pending.data, Content) - or pending.data.type != "function_approval_request" - ): - raise _WorkflowRequestError("The approval is unavailable in this exact pending checkpoint.") + if request_id is None or pending is None: + logger.warning("Ignoring an approval reply that is not pending in this workflow checkpoint.") + continue + if not isinstance(pending.data, Content) or pending.data.type != "function_approval_request": + raise _WorkflowRequestError("An approval reply cannot answer a non-approval workflow request.") response = pending.data.to_function_approval_response(decision) elif item.get("type") in ("function_call_output", "computer_call_output"): call_id = item.get("call_id") @@ -189,7 +188,8 @@ async def _load_replies(request: ResponsesRequest, run: HostedWorkflowRun) -> di raise _WorkflowRequestError("A workflow reply requires its pending call ID.") request_id = run.approvals.get(call_id) if request_id is None or request_id not in run.pending_requests: - raise _WorkflowRequestError("A reply must match its wire ID in the exact pending workflow checkpoint.") + logger.warning("Ignoring a workflow reply that is not pending in this workflow checkpoint.") + continue pending = run.pending_requests[request_id] if isinstance(pending.data, Content) and pending.data.type == "function_approval_request": raise _WorkflowRequestError("An approval cannot be replaced by a function result.") @@ -220,11 +220,9 @@ async def _load_replies(request: ResponsesRequest, run: HostedWorkflowRun) -> di raise _WorkflowRequestError("A typed workflow reply must contain valid JSON.") from exc else: raise _WorkflowRequestError("Pending workflow replies cannot be mixed with new input.") - if request_id is None or request_id in replies: + if request_id in replies: raise _WorkflowRequestError("Duplicate workflow replies are not allowed.") replies[request_id] = response - if set(replies) != set(run.pending_requests): - raise _WorkflowRequestError("Answer exactly the complete pending workflow request batch.") validated = run.validate_turn(WorkflowTurn(responses=replies)) return dict(validated.responses or {}) @@ -412,11 +410,6 @@ def __init__( self._prepare_options = prepare_options self._resilient_background = enable_background_recovery self._allowed_origins = allowed_origins - bind_approval_preflight( - self, - prefix=prefix, - preflight=lambda request, context, platform: preflight_workflow_approvals(request, context, platform, self), - ) self._bind_streaming_route( prefix=prefix, keep_alive=bool( @@ -646,6 +639,18 @@ async def checkpoint_stamp() -> str | None: # ruff: ignore[unused-async] await abort() return phase = "final output persistence" + if run.stored and not run.has_completed_output: + # Core does not re-emit requests left unanswered by a partial reply; project them under new wire IDs. + checkpoint = await run.get_checkpoint(run.checkpoint_id) + projected = set(aliases.values()) | { + event.request_id for event in buffered if event.type == "request_info" + } + if checkpoint is not None: + buffered.extend( + event + for request_id, event in checkpoint.pending_request_info_events.items() + if request_id not in projected + ) if buffered: for event in await flush(run.checkpoint_id): yield wire(event) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_workflow_state.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_workflow_state.py index ae822942767..34107962f8a 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_workflow_state.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_workflow_state.py @@ -18,16 +18,12 @@ ChatResponse, ChatResponseUpdate, CheckpointStorage, - Content, Workflow, WorkflowCheckpoint, WorkflowEvent, WorkflowInvocationKwargs, WorkflowRunState, ) -from agent_framework._workflows._agent_executor import ( - _validate_computer_tool_result, # pyright: ignore[reportPrivateUsage] -) from agent_framework._workflows._checkpoint_encoding import encode_checkpoint_value from agent_framework._workflows._const import ( RESOLVED_WORKFLOW_RUN_KWARGS_KEY, @@ -35,9 +31,6 @@ WORKFLOW_RUN_KWARGS_KEY, ) from agent_framework._workflows._typing_utils import is_instance_of -from agent_framework._workflows._workflow import ( - _coerce_request_info_response, # pyright: ignore[reportPrivateUsage] -) from azure.ai.agentserver.core import AgentConfig, FoundryAgentRequestContext from azure.ai.agentserver.core.storage import ( FoundryStateStore, @@ -345,8 +338,9 @@ class HostedWorkflowRun: """A native turn with explicit validation, claim, pairing, commit, and abort boundaries. Protocol hosts own output encoding and lifecycle signals. Closing ``events`` - never commits a turn. A failed or cancelled claim is blocked rather than - releasing potentially consumed approvals or replaying external side effects. + never commits a turn. A claim that fails before the first superstep starts is + released, because no executor or reply handler has run. Later failures block + the lineage rather than replaying consumed replies or external side effects. """ def __init__( @@ -369,6 +363,8 @@ def __init__( self.binding: WorkflowBinding self._head: WorkflowHead | None = None self._head_etag: str | None = None + self._pre_claim_head: WorkflowHead | None = None + self._superstep_started = False self._record: WorkflowRecord | None = None self._record_etag: str | None = None self._storage: _CheckpointWrites | None = None @@ -652,49 +648,11 @@ def validate_turn(self, turn: WorkflowTurn[Any]) -> WorkflowTurn[Any]: return turn pending = self.pending_requests if turn.responses is not None: - if not self.stored or self._checkpoint is None: + # Core validates each reply against its pending request before the first superstep. + if not self.stored or self._checkpoint is None or not pending: raise ValueError("Workflow replies require a pending stored checkpoint.") - if set(turn.responses) != set(pending) or not pending: - raise ValueError("Workflow replies must answer exactly the complete pending request batch.") - replies: dict[str, Any] = {} - reply_ids: set[tuple[str, str]] = set() - for request_id, reply in turn.responses.items(): - event = pending[request_id] - try: - reply = _coerce_request_info_response(reply, event.response_type, request_id) - except (TypeError, ValueError) as exc: - raise ValueError("A workflow reply does not match its pending request type.") from exc - if isinstance(event.data, Content): - request = event.data - if isinstance(reply, Content): - identifier = reply.id if reply.type == "function_approval_response" else reply.call_id - if identifier is not None: - key = (reply.type, identifier) - if key in reply_ids: - raise ValueError("Duplicate workflow reply authority is not allowed.") - reply_ids.add(key) - if request.type == "function_approval_request" and ( - not isinstance(reply, Content) - or reply.type != "function_approval_response" - or reply.id != request.id - or type(reply.approved) is not bool - or reply.function_call is None - or request.function_call is None - or reply.function_call.to_dict() != request.function_call.to_dict() - ): - raise ValueError("The approval decision does not match its exact pending function call.") - if request.type == "function_call" and ( - not isinstance(reply, Content) - or reply.type != "function_result" - or reply.call_id != request.call_id - ): - raise ValueError("The function result does not match its pending call.") - if request.type == "computer_tool_call": - if not isinstance(reply, Content): - raise ValueError("A computer reply must be typed Content.") - _validate_computer_tool_result(request, reply) - replies[request_id] = reply - turn = replace(turn, responses=replies) + if not turn.responses: + raise ValueError("Workflow replies must answer at least one pending request.") else: if pending: raise ValueError("This workflow is awaiting replies; do not replace them with new input.") @@ -715,6 +673,7 @@ async def claim(self) -> None: self._claimed = True return owner = secrets.token_hex(16) + self._pre_claim_head = self._head head = replace( self._head or WorkflowHead(self.binding.lineage_id, self.binding.conversation_id), response_id=self.binding.response_id, @@ -730,7 +689,6 @@ async def claim(self) -> None: ) self._record_etag = await self.store.save_response(record, expected_etag=self._record_etag) self._record = record - await self._reclaim_completed_ancestors() async def assert_claim(self) -> None: if not self._claimed: @@ -776,6 +734,8 @@ async def events( and data.continuation_token is not None ): raise RuntimeError("Native workflows cannot checkpoint unfinished provider background output.") + if event.type == "superstep_started": + self._superstep_started = True if event.type == "superstep_completed": validate_workflow_provider_state(self.workflow) if event.type == "request_info" and not self.stored: @@ -871,6 +831,7 @@ async def commit(self, snapshot: Mapping[str, Any] | None = None) -> None: self._head_etag = await self.store.save_head(head, expected_etag=self._head_etag) self._head = head self._claimed = False + await self._reclaim_completed_ancestors() async def _reclaim_completed_ancestors(self) -> None: """Best-effort reclaim after the new head is durably committed. @@ -911,10 +872,23 @@ async def _reclaim_completed_ancestors(self) -> None: logger.exception("Failed to reclaim superseded native workflow state; a later commit can retry cleanup") async def abort(self) -> None: - """Block interrupted/failed authority instead of permitting unsafe reply or effect replay.""" + """Release a claim that never started a superstep; otherwise block the lineage against unsafe replay.""" if not self.stored or not self._claimed or self.already_completed: return await self.assert_claim() + if ( + not self._superstep_started + and not self.recovery + and self._pre_claim_head is not None + and self._record_etag is not None + ): + # Core rejects invalid replies before any executor runs, so the head and checkpoint stay usable. + self._head_etag = await self.store.save_head(self._pre_claim_head, expected_etag=self._head_etag) + self._head = self._pre_claim_head + await self.store.delete_response(self.binding.response_id, expected_etag=self._record_etag) + self._record = self._record_etag = None + self._claimed = False + return if self._record is not None: record = replace(self._record, status="blocked") self._record_etag = await self.store.save_response(record, expected_etag=self._record_etag) diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/agent_approval_helpers.py b/python/packages/foundry_hosting/tests/foundry_hosting/agent_approval_helpers.py new file mode 100644 index 00000000000..75e42899a6b --- /dev/null +++ b/python/packages/foundry_hosting/tests/foundry_hosting/agent_approval_helpers.py @@ -0,0 +1,115 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Real-Agent boundaries for hosted approval round trips.""" + +from __future__ import annotations + +import json +from collections.abc import AsyncIterator, Awaitable, Mapping, Sequence +from pathlib import Path +from typing import Any + +import httpx2 as httpx +from agent_framework import ( + Agent, + BaseChatClient, + ChatResponse, + ChatResponseUpdate, + Content, + FunctionInvocationLayer, + FunctionTool, + Message, + ResponseStream, + tool, +) + +from agent_framework_foundry_hosting import ResponsesHostServer + +from .approval_helpers import SqliteSessionStore +from .toolbox_approval_helpers import FixedSessionStoreProvider + + +class BatchApprovalClient(FunctionInvocationLayer[Any], BaseChatClient[Any]): + """Call the protected tool for each name after user text; answer with text otherwise.""" + + def __init__(self, names: Sequence[str]) -> None: + super().__init__() + self.names = list(names) + + def _inner_get_response( + self, + *, + messages: Sequence[Message], + stream: bool, + options: Mapping[str, Any], + **kwargs: Any, + ) -> Awaitable[ChatResponse] | ResponseStream[ChatResponseUpdate, ChatResponse]: + last = messages[-1] + contents = ( + [ + Content.from_function_call(call_id=f"call-{name}", name="protected", arguments={"name": name}) + for name in self.names + ] + if last.role == "user" and any(content.type == "text" for content in last.contents) + else [Content.from_text("done")] + ) + + async def updates() -> AsyncIterator[ChatResponseUpdate]: + yield ChatResponseUpdate(role="assistant", contents=contents) + + async def complete() -> ChatResponse: + return ChatResponse(messages=[Message("assistant", contents=contents)]) + + return ResponseStream(updates(), finalizer=ChatResponse.from_updates) if stream else complete() + + +def protected_tool(executed: list[str]) -> FunctionTool: + @tool(approval_mode="always_require") + def protected(name: str) -> str: + """Run a protected action.""" + executed.append(name) + return f"ran {name}" + + return protected + + +def approval_host(tmp_path: Path, executed: list[str], names: Sequence[str] = ("a", "b")) -> ResponsesHostServer: + return ResponsesHostServer( + agent=Agent(client=BatchApprovalClient(names), tools=[protected_tool(executed)]), + agent_session_store_provider=FixedSessionStoreProvider(SqliteSessionStore(tmp_path / "sessions.db")), + ) + + +async def post_turn(client: httpx.AsyncClient, payload: dict[str, Any], *, stream: bool) -> dict[str, Any]: + """Post one turn and return its terminal response body.""" + response = await client.post("/responses", json={"model": "test-model", **payload, "stream": stream}) + assert response.status_code == 200, response.text + if not stream: + return response.json() + events = [ + json.loads(line[6:]) + for line in response.text.splitlines() + if line.startswith("data: ") and line != "data: [DONE]" + ] + return next( + event["response"] + for event in events + if event["type"] in ("response.completed", "response.failed", "response.incomplete") + ) + + +def approval_ids(body: dict[str, Any]) -> dict[str, str]: + """Map each requested tool argument name to its wire approval id.""" + return { + json.loads(item["arguments"])["name"]: item["id"] + for item in body["output"] + if item["type"] == "mcp_approval_request" + } + + +def approval_reply(approval_request_id: str, approve: bool) -> dict[str, Any]: + return {"type": "mcp_approval_response", "approval_request_id": approval_request_id, "approve": approve} + + +def tool_outputs(body: dict[str, Any]) -> list[str]: + return [item["output"] for item in body["output"] if item["type"] == "function_call_output"] diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_agent_approvals.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_agent_approvals.py new file mode 100644 index 00000000000..0a48e38b4e3 --- /dev/null +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_agent_approvals.py @@ -0,0 +1,126 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Hosted agents rely on Core pending approvals in the same AgentSession.""" + +from __future__ import annotations + +from pathlib import Path + +import httpx2 as httpx +import pytest +from azure.ai.agentserver.responses._id_generator import IdGenerator + +from .agent_approval_helpers import ( # pyrefly: ignore[missing-import] - pytest's importlib namespace + approval_host, + approval_ids, + approval_reply, + post_turn, + tool_outputs, +) + +REJECTED = "Error: Tool call invocation was rejected by user." + +pytestmark = pytest.mark.parametrize("stream", [False, True]) + + +async def test_mixed_batch_runs_approved_call_and_rejects_the_other(stream: bool, tmp_path: Path) -> None: + executed: list[str] = [] + host = approval_host(tmp_path, executed) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: + first = await post_turn(client, {"input": "go"}, stream=stream) + ids = approval_ids(first) + assert set(ids) == {"a", "b"} + assert executed == [] + + second = await post_turn( + client, + { + "input": [approval_reply(ids["a"], True), approval_reply(ids["b"], False)], + "previous_response_id": first["id"], + }, + stream=stream, + ) + + assert second["status"] == "completed" + assert sorted(tool_outputs(second)) == sorted(["ran a", REJECTED]) + assert executed == ["a"] + + +async def test_partial_batch_keeps_the_unanswered_request_pending(stream: bool, tmp_path: Path) -> None: + executed: list[str] = [] + host = approval_host(tmp_path, executed) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: + first = await post_turn(client, {"input": "go"}, stream=stream) + ids = approval_ids(first) + + partial = await post_turn( + client, + {"input": [approval_reply(ids["a"], True)], "previous_response_id": first["id"]}, + stream=stream, + ) + assert partial["status"] == "completed" + assert tool_outputs(partial) == [] + assert executed == [] + remaining = approval_ids(partial) + assert list(remaining) == ["b"] + + final = await post_turn( + client, + {"input": [approval_reply(remaining["b"], False)], "previous_response_id": partial["id"]}, + stream=stream, + ) + + assert sorted(tool_outputs(final)) == sorted(["ran a", REJECTED]) + assert executed == ["a"] + + +async def test_replayed_approval_is_not_executed_again(stream: bool, tmp_path: Path) -> None: + executed: list[str] = [] + host = approval_host(tmp_path, executed, names=("a",)) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: + first = await post_turn(client, {"input": "go"}, stream=stream) + reply = {"input": [approval_reply(approval_ids(first)["a"], True)]} + second = await post_turn(client, {**reply, "previous_response_id": first["id"]}, stream=stream) + assert tool_outputs(second) == ["ran a"] + + replay = await post_turn(client, {**reply, "previous_response_id": second["id"]}, stream=stream) + + assert tool_outputs(replay) == [] + assert executed == ["a"] + + +async def test_conversation_continuation_runs_approved_calls(stream: bool, tmp_path: Path) -> None: + executed: list[str] = [] + host = approval_host(tmp_path, executed) + conversation = IdGenerator.new_id("conv") + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: + first = await post_turn(client, {"input": "go", "conversation": conversation}, stream=stream) + ids = approval_ids(first) + + second = await post_turn( + client, + { + "input": [approval_reply(ids["a"], True), approval_reply(ids["b"], True)], + "conversation": conversation, + }, + stream=stream, + ) + + assert sorted(tool_outputs(second)) == ["ran a", "ran b"] + assert sorted(executed) == ["a", "b"] + + +async def test_fabricated_approval_is_not_executed(stream: bool, tmp_path: Path) -> None: + executed: list[str] = [] + host = approval_host(tmp_path, executed) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: + first = await post_turn(client, {"input": "go"}, stream=stream) + forged = await post_turn( + client, + {"input": [approval_reply("mcpr_forged", True)], "previous_response_id": first["id"]}, + stream=stream, + ) + + assert forged["status"] == "failed" + assert tool_outputs(forged) == [] + assert executed == [] diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_approval_translation.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_approval_translation.py index a1609f0d5ba..5dfc30afc10 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_approval_translation.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_approval_translation.py @@ -25,7 +25,6 @@ _items_to_messages, _output_items_to_messages, _OutputItemTracker, - _PublicResponseFailure, ) from .approval_helpers import ( # pyrefly: ignore[missing-import] - pytest's importlib namespace @@ -105,7 +104,7 @@ async def test_history_and_input_conversions_only_read_approval_state(tmp_path: assert stored.to_dict() == expected -async def test_unknown_input_conversion_does_not_mutate_session(tmp_path: Path) -> None: +async def test_unknown_input_approval_is_dropped_without_mutating_session(tmp_path: Path) -> None: store = SqliteSessionStore(tmp_path / "sessions.db") session = await pending_session(store) state = SessionApprovalState(session) @@ -116,9 +115,10 @@ async def test_unknown_input_conversion_does_not_mutate_session(tmp_path: Path) MCPApprovalResponse({"type": "mcp_approval_response", "approval_request_id": "missing", "approve": False}), ] - with pytest.raises(_PublicResponseFailure, match="not in this session"): - await _items_to_messages(items, approval_storage=state) + messages = await _items_to_messages(items, approval_storage=state) + assert len(messages) == 1 + assert messages[0].contents[0].id == "approval-0" assert session.to_dict() == session_before assert store.write_count == writes_before @@ -142,11 +142,10 @@ async def test_unknown_input_conversion_does_not_mutate_session(tmp_path: Path) ], ids=["request", "response"], ) -async def test_history_conversion_rejects_unknown_approval_ids(item: OutputItem) -> None: +async def test_history_conversion_drops_unknown_approval_ids(item: OutputItem) -> None: state = SessionApprovalState(AgentSession()) - with pytest.raises(_PublicResponseFailure, match="not in this session"): - await _output_items_to_messages([item], approval_storage=state) + assert await _output_items_to_messages([item], approval_storage=state) == [] @pytest.mark.parametrize( diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_invocations_workflow.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_invocations_workflow.py index 27778381950..53b83aa16cb 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_invocations_workflow.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_invocations_workflow.py @@ -731,8 +731,8 @@ def factory(_request: Request) -> Workflow: async with raw_bindings: keys = await raw_bindings.list_keys(call_id=None) assert len(keys.keys) == 2 # Current response record plus the fixed lineage head. - # The current turn retains its entry and final checkpoints; prior turns are reclaimed. - assert len(await stores[-1].list_checkpoint_ids(workflow_name="tickets")) == 2 + # Reclaim runs after commit, so only the committed final checkpoint remains. + assert len(await stores[-1].list_checkpoint_ids(workflow_name="tickets")) == 1 before = list(calls) replay, events = await _invoke( @@ -796,7 +796,7 @@ async def handle(self, _: Ticket, ctx: WorkflowContext[None, Any]) -> None: class TestNativeWorkflowPendingReplies: @pytest.mark.parametrize("stream", [False, True]) - async def test_json_approval_metadata_is_bound_to_exact_pending_calls_before_dispatch(self, stream: bool) -> None: + async def test_json_approval_replies_dispatch_once_and_replay_is_rejected(self, stream: bool) -> None: decisions: list[bool] = [] async def parser(request: Request) -> WorkflowTurn[Ticket]: @@ -818,18 +818,6 @@ def factory(_request: Request) -> Workflow: item["request_id"]: Content.from_dict(item["data"]).to_function_approval_response(True).to_dict() for item in pending } - request_ids = list(valid) - duplicated = {request_ids[0]: valid[request_ids[0]], request_ids[1]: valid[request_ids[0]]} - response, rejected = await _invoke(_host(factory, parser=parser), {"responses": duplicated, "stream": stream}) - assert response.status_code == (200 if stream else 400) - assert [event["event"] for event in rejected] == ["error"] - assert decisions == [] - forged = json.loads(json.dumps(valid)) - forged[request_ids[0]]["function_call"]["arguments"] = {"ticket_id": "forged"} - response, rejected = await _invoke(_host(factory, parser=parser), {"responses": forged, "stream": stream}) - assert response.status_code == (200 if stream else 400) - assert [event["event"] for event in rejected] == ["error"] - assert decisions == [] response, _ = await _invoke(_host(factory, parser=parser), {"responses": valid, "stream": stream}) assert response.status_code == 200 assert decisions == [True, True] @@ -887,9 +875,7 @@ def factory(_request: Request) -> Workflow: assert replies == [{"accepted": True}, {"accepted": False}] @pytest.mark.parametrize("stream", [False, True]) - async def test_partial_replies_do_not_consume_authority_and_complete_replies_survive_restart( - self, stream: bool - ) -> None: + async def test_partial_replies_dispatch_answered_requests_and_keep_the_rest_pending(self, stream: bool) -> None: replies: list[tuple[str, bool]] = [] def factory(_request: Request) -> Workflow: @@ -900,28 +886,25 @@ def factory(_request: Request) -> Workflow: pending = [item for item in events if item["event"] == "request_info"] assert len(pending) == 2 ids = {item["data"]["reviewer"]: item["request_id"] for item in pending} - first_reply = {"responses": {ids["support"]: {"approved": True}}, "stream": stream} - response, events = await _invoke(_host(factory), first_reply) - assert response.status_code == (200 if stream else 400) - assert [item["event"] for item in events] == ["error"] - assert replies == [] + response, _ = await _invoke( + _host(factory), {"responses": {ids["support"]: {"approved": True}}, "stream": stream} + ) + assert response.status_code == 200 + assert replies == [("support", True)] - complete = { - "responses": {ids["support"]: {"approved": True}, ids["security"]: {"approved": False}}, - "stream": stream, - } - response, events = await _invoke(_host(factory), complete) + rest = {"responses": {ids["security"]: {"approved": False}}, "stream": stream} + response, events = await _invoke(_host(factory), rest) assert response.status_code == 200 - assert sorted(replies) == [("security", False), ("support", True)] + assert replies == [("support", True), ("security", False)] assert not [item for item in events if item["event"] == "request_info"] - response, events = await _invoke(_host(factory), complete) + response, events = await _invoke(_host(factory), rest) assert response.status_code == (200 if stream else 400) assert [item["event"] for item in events] == ["error"] assert len(replies) == 2 - @pytest.mark.parametrize("identity", ["other-sandbox", "other-user", "forged-request"]) - async def test_pending_reply_cannot_cross_scope_or_forge_a_request(self, identity: str) -> None: + @pytest.mark.parametrize("identity", ["other-sandbox", "other-user"]) + async def test_pending_reply_cannot_cross_scope(self, identity: str) -> None: replies: list[tuple[str, bool]] = [] def factory(_request: Request) -> Workflow: @@ -940,7 +923,7 @@ def factory(_request: Request) -> Workflow: other.config.session_id = "" response, _ = await _invoke( other, - {"responses": {"forged" if identity == "forged-request" else request_id: {"approved": True}}}, + {"responses": {request_id: {"approved": True}}}, session_id="sandbox-b" if identity == "other-sandbox" else "sandbox-a", user_id="user-b" if identity == "other-user" else "user-a", call_id="second", @@ -965,7 +948,7 @@ def factory(_request: Request) -> Workflow: assert response.status_code == 200 assert len(replies) == 2 - async def test_invalid_mixed_reply_batch_does_not_consume_valid_authority(self) -> None: + async def test_unknown_reply_id_fails_in_core_without_dispatch_and_valid_retry_succeeds(self) -> None: replies: list[tuple[str, bool]] = [] def factory(_request: Request) -> Workflow: @@ -976,7 +959,8 @@ def factory(_request: Request) -> Workflow: response, _ = await _invoke( _host(factory), {"responses": {ids[0]: {"approved": True}, "forged": {"approved": True}}} ) - assert response.status_code == 400 + # Core rejects the unknown request ID before the first superstep; the claim is released, not blocked. + assert response.status_code == 500 assert replies == [] response, _ = await _invoke(_host(factory), {"responses": {key: {"approved": True} for key in ids}}) assert response.status_code == 200 diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py index 4eb35379ef3..38f975760bf 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py @@ -54,7 +54,6 @@ ResponsesWorkflowHostServer, WorkflowTurn, ) -from agent_framework_foundry_hosting._approvals import _InvalidApproval from agent_framework_foundry_hosting._responses_workflow import _load_replies, _WorkflowRequestError from agent_framework_foundry_hosting._workflow_state import FoundryWorkflowBindingStore, HostedWorkflowRun @@ -389,7 +388,7 @@ async def test_graph_change_cannot_choose_a_new_unrelated_checkpoint() -> None: assert "graph" in second["error"]["message"] -async def test_generic_pending_replies_are_complete_and_consumed_once() -> None: +async def test_generic_partial_replies_reproject_unanswered_requests_under_new_ids() -> None: server = _server(lambda request: _build(_Review()), parser=_parse_text) first = await _post(server, "review") assert first["status"] == "completed", first @@ -400,19 +399,27 @@ async def test_generic_pending_replies_are_complete_and_consumed_once() -> None: [{"type": "function_call_output", "call_id": call_ids[0], "output": "true"}], previous_response_id=first["id"], ) - assert partial["status"] == "failed" - assert not partial["output"] - full = [ - {"type": "function_call_output", "call_id": call_ids[0], "output": "true"}, - {"type": "function_call_output", "call_id": call_ids[1], "output": "false"}, - ] - duplicate = await _post(server, [full[0], dict(full[0]), full[1]], previous_response_id=first["id"]) + assert partial["status"] == "completed", partial + assert _texts(partial) == ["review:True"] + new_ids = [item["call_id"] for item in partial["output"] if item["type"] == "function_call"] + assert len(new_ids) == 1 and new_ids[0] not in call_ids + reply = {"type": "function_call_output", "call_id": new_ids[0], "output": "false"} + + duplicate = await _post(server, [reply, dict(reply)], previous_response_id=partial["id"]) assert duplicate["status"] == "failed" assert not duplicate["output"] - completed = await _post(server, full, previous_response_id=first["id"]) + stale = await _post( + server, + [{"type": "function_call_output", "call_id": call_ids[1], "output": "false"}], + previous_response_id=partial["id"], + ) + assert stale["status"] == "failed" + assert not stale["output"] + + completed = await _post(server, [reply], previous_response_id=partial["id"]) assert completed["status"] == "completed", completed - assert _texts(completed) == ["review:True", "review:False"] - replay = await _post(server, full, previous_response_id=first["id"]) + assert _texts(completed) == ["review:False"] + replay = await _post(server, [reply], previous_response_id=partial["id"]) assert replay["status"] == "failed" assert not replay["output"] @@ -438,16 +445,13 @@ async def test_named_conversation_rejects_old_wire_replies_when_core_request_ids @pytest.mark.parametrize("stream", [False, True]) -async def test_workflow_approval_lookup_error_is_a_backend_failure(stream: bool) -> None: +async def test_workflow_binding_lookup_error_fails_without_leaking_detail(stream: bool) -> None: server = _server(lambda request: _build(_Approvals()), parser=_parse_text) first = await _post(server, "/safe") approval_id = next(item["id"] for item in first["output"] if item["type"] == "mcp_approval_request") detail = "private workflow storage failure" - with ( - patch.object(FoundryWorkflowBindingStore, "get_response", new=AsyncMock(side_effect=_InvalidApproval(detail))), - patch.object(server._resolver, "resolve", wraps=server._resolver.resolve) as resolver, # pyright: ignore[reportPrivateUsage] - ): + with patch.object(FoundryWorkflowBindingStore, "get_response", new=AsyncMock(side_effect=RuntimeError(detail))): async with httpx.AsyncClient(transport=httpx.ASGITransport(app=server), base_url="http://test") as client: response = await client.post( "/responses", @@ -460,14 +464,28 @@ async def test_workflow_approval_lookup_error_is_a_backend_failure(stream: bool) }, ) - assert response.status_code == 500 - assert response.headers["x-platform-error-source"] == "upstream" + assert response.status_code == 200 assert detail not in response.text - resolver.assert_not_called() + if stream: + assert "response.failed" in response.text + else: + assert response.json()["status"] == "failed" + + +def _terminal(response: httpx.Response, stream: bool) -> dict[str, Any]: + assert response.status_code == 200, response.text + if not stream: + return response.json() + events = [json.loads(line[6:]) for line in response.text.splitlines() if line.startswith("data: {")] + return next( + event["response"] + for event in events + if event["type"] in ("response.completed", "response.failed", "response.incomplete") + ) @pytest.mark.parametrize("stream", [False, True]) -async def test_approval_wire_ids_bind_only_to_exact_pending_checkpoint(stream: bool) -> None: +async def test_invalid_approval_replies_fail_in_stream_and_leave_the_pause_usable(stream: bool) -> None: provider = InMemoryResponseProvider() server = _server(lambda request: _build(_Approvals()), parser=_parse_text, response_store=provider) first = await _post(server, "/safe") @@ -478,51 +496,43 @@ async def test_approval_wire_ids_bind_only_to_exact_pending_checkpoint(stream: b MCPApprovalResponse(type="mcp_approval_response", approval_request_id=wire_ids[0], approve=True), MCPApprovalResponse(type="mcp_approval_response", approval_request_id=wire_ids[1], approve=False), ] + headers = {"x-agent-user-id": "user", "x-agent-foundry-call-id": "call"} async with httpx.AsyncClient(transport=httpx.ASGITransport(app=server), base_url="http://test") as client: - with ( - patch.object(server._resolver, "resolve", wraps=server._resolver.resolve) as resolver, # pyright: ignore[reportPrivateUsage] - patch.object(server, "_parse_input", wraps=server._parse_input) as parser, # pyright: ignore[reportPrivateUsage] + for replies, sandbox in ( + ([full[0], dict(full[0]), full[1]], "sandbox"), + ([*full, {"type": "item_reference", "id": "missing-item"}], "sandbox"), + (full, "other"), ): - for replies, sandbox in ( - (full[:1], "sandbox"), - ([full[0], dict(full[0]), full[1]], "sandbox"), - ([{**full[0], "approval_request_id": "forged"}, full[1]], "sandbox"), - ([*full, {"type": "item_reference", "id": "missing-item"}], "sandbox"), - (full, "other"), - ): - rejected = await client.post( + rejected = _terminal( + await client.post( "/responses", - headers={"x-agent-user-id": "user", "x-agent-foundry-call-id": "call"}, + headers=headers, json={ "input": replies, "agent_session_id": sandbox, "previous_response_id": first["id"], "stream": stream, }, - ) - assert rejected.status_code == 400 - assert rejected.headers["content-type"].startswith("application/json") - assert rejected.headers["x-agent-session-id"] == sandbox - assert "response.created" not in rejected.text - for id_in_header in (True, False): - for replies in (full[:1], [full[0], full[0]]): - headers = {"x-agent-user-id": "user", "x-agent-foundry-call-id": "call"} - payload = { - "input": replies, - "agent_session_id": "sandbox", - "previous_response_id": first["id"], - "stream": stream, - } - if id_in_header: - headers["x-agent-response-id"] = first["id"] - else: - payload["response_id"] = first["id"] - redelivery = await client.post("/responses", headers=headers, json=payload) - assert redelivery.status_code == 400 - assert redelivery.headers["content-type"].startswith("application/json") - assert "response.created" not in redelivery.text - resolver.assert_not_called() - parser.assert_not_called() + ), + stream, + ) + assert rejected["status"] == "failed" + assert not rejected["output"] + redelivery = _terminal( + await client.post( + "/responses", + headers={**headers, "x-agent-response-id": first["id"]}, + json={ + "input": full, + "agent_session_id": "sandbox", + "previous_response_id": first["id"], + "stream": stream, + }, + ), + stream, + ) + assert redelivery["status"] == "failed" + assert not redelivery["output"] direct_request = ResponsesRequest( CreateResponse(input=[*full, ItemReferenceParam(type="item_reference", id="missing-item")]), MagicMock(response_id="handler-revalidation", get_input_items=AsyncMock(return_value=full)), @@ -543,49 +553,115 @@ async def test_approval_wire_ids_bind_only_to_exact_pending_checkpoint(stream: b continuation_id = IdGenerator.new_response_id(first["id"]) continuation = [{"type": "item_reference", "id": referenced_id}, full[1]] async with httpx.AsyncClient(transport=httpx.ASGITransport(app=server), base_url="http://test") as client: - accepted = await client.post( - "/responses", - headers={"x-agent-user-id": "user", "x-agent-foundry-call-id": "call"}, - json={ - "input": continuation, - "agent_session_id": "sandbox", - "previous_response_id": first["id"], - "response_id": continuation_id, - "stream": stream, - }, + completed = _terminal( + await client.post( + "/responses", + headers=headers, + json={ + "input": continuation, + "agent_session_id": "sandbox", + "previous_response_id": first["id"], + "response_id": continuation_id, + "stream": stream, + }, + ), + stream, ) - assert accepted.status_code == 200 - if stream: - events = [json.loads(line[6:]) for line in accepted.text.splitlines() if line.startswith("data: {")] - completed = next(event["response"] for event in events if event["type"] == "response.completed") - else: - completed = accepted.json() assert completed["status"] == "completed", completed assert completed["id"] == continuation_id assert _texts(completed) == ["first:True", "second:False"] + replay = _terminal( + await client.post( + "/responses", + headers=headers, + json={ + "input": full, + "agent_session_id": "sandbox", + "previous_response_id": first["id"], + "stream": stream, + }, + ), + stream, + ) + assert replay["status"] == "failed" + assert not replay["output"] - with ( - patch.object(server._resolver, "resolve", wraps=server._resolver.resolve) as resolver, # pyright: ignore[reportPrivateUsage] - patch.object(server, "_parse_input", wraps=server._parse_input) as parser, # pyright: ignore[reportPrivateUsage] - ): - for id_in_header in (True, False): - headers = {"x-agent-user-id": "user", "x-agent-foundry-call-id": "call"} - payload = { - "input": continuation, + +@pytest.mark.parametrize("stream", [False, True]) +async def test_rejected_typed_reply_fails_then_same_parent_accepts_a_valid_retry(stream: bool) -> None: + server = _server(lambda request: _build(_Review()), parser=_parse_text) + first = await _post(server, "review") + call_ids = [item["call_id"] for item in first["output"]] + headers = {"x-agent-user-id": "user", "x-agent-foundry-call-id": "call"} + + async def reply(output: str) -> dict[str, Any]: + replies = [{"type": "function_call_output", "call_id": call_id, "output": output} for call_id in call_ids] + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=server), base_url="http://test") as client: + response = await client.post( + "/responses", + headers=headers, + json={ + "input": replies, "agent_session_id": "sandbox", "previous_response_id": first["id"], "stream": stream, - } - if id_in_header: - headers["x-agent-response-id"] = continuation_id - else: - payload["response_id"] = continuation_id - replay = await client.post("/responses", headers=headers, json=payload) - assert replay.status_code == 400 - assert replay.headers["content-type"].startswith("application/json") - assert "response.created" not in replay.text - resolver.assert_not_called() - parser.assert_not_called() + }, + ) + return _terminal(response, stream) + + rejected = await reply('{"not": "a bool"}') + assert rejected["status"] == "failed" + assert not rejected["output"] + completed = await reply("true") + assert completed["status"] == "completed", completed + assert _texts(completed) == ["review:True", "review:True"] + + +@pytest.mark.parametrize("stream", [False, True]) +async def test_forged_and_partial_approvals_execute_only_pending_answers(stream: bool) -> None: + server = _server(lambda request: _build(_Approvals()), parser=_parse_text) + first = await _post(server, "/safe") + wire_ids = [item["id"] for item in first["output"] if item["type"] == "mcp_approval_request"] + headers = {"x-agent-user-id": "user", "x-agent-foundry-call-id": "call"} + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=server), base_url="http://test") as client: + + async def reply(previous_id: str, replies: list[dict[str, Any]]) -> dict[str, Any]: + return _terminal( + await client.post( + "/responses", + headers=headers, + json={ + "input": replies, + "agent_session_id": "sandbox", + "previous_response_id": previous_id, + "stream": stream, + }, + ), + stream, + ) + + partial = await reply( + first["id"], + [ + {"type": "mcp_approval_response", "approval_request_id": "forged", "approve": True}, + {"type": "mcp_approval_response", "approval_request_id": wire_ids[1], "approve": False}, + ], + ) + assert partial["status"] == "completed", partial + assert _texts(partial) == ["second:False"] + remaining = [item["id"] for item in partial["output"] if item["type"] == "mcp_approval_request"] + assert len(remaining) == 1 and remaining[0] not in wire_ids + + stale = await reply( + partial["id"], [{"type": "mcp_approval_response", "approval_request_id": wire_ids[0], "approve": True}] + ) + assert stale["status"] == "failed" + assert not stale["output"] + completed = await reply( + partial["id"], [{"type": "mcp_approval_response", "approval_request_id": remaining[0], "approve": True}] + ) + assert completed["status"] == "completed", completed + assert _texts(completed) == ["first:True"] @pytest.mark.parametrize("stream", [False, True]) @@ -596,28 +672,21 @@ async def test_named_conversation_rejects_new_input_while_approvals_are_pending( wire_ids = [item["id"] for item in first["output"] if item["type"] == "mcp_approval_request"] assert len(wire_ids) == 2 async with httpx.AsyncClient(transport=httpx.ASGITransport(app=server), base_url="http://test") as client: - with ( - patch.object(server._resolver, "resolve", wraps=server._resolver.resolve) as resolver, # pyright: ignore[reportPrivateUsage] - patch.object(server, "_parse_input", wraps=server._parse_input) as parser, # pyright: ignore[reportPrivateUsage] - ): - for id_in_header in (None, True, False): - headers = {"x-agent-user-id": "user", "x-agent-foundry-call-id": "call"} - payload = { - "input": "a new request", - "agent_session_id": "sandbox", - "conversation": conversation, - "stream": stream, - } - if id_in_header is True: - headers["x-agent-response-id"] = first["id"] - elif id_in_header is False: - payload["response_id"] = first["id"] - rejected = await client.post("/responses", headers=headers, json=payload) - assert rejected.status_code == 400 - assert rejected.headers["content-type"].startswith("application/json") - assert "response.created" not in rejected.text - resolver.assert_not_called() - parser.assert_not_called() + for id_in_header in (None, True, False): + headers = {"x-agent-user-id": "user", "x-agent-foundry-call-id": "call"} + payload = { + "input": "a new request", + "agent_session_id": "sandbox", + "conversation": conversation, + "stream": stream, + } + if id_in_header is True: + headers["x-agent-response-id"] = first["id"] + elif id_in_header is False: + payload["response_id"] = first["id"] + rejected = _terminal(await client.post("/responses", headers=headers, json=payload), stream) + assert rejected["status"] == "failed" + assert not rejected["output"] replies = [ {"type": "mcp_approval_response", "approval_request_id": wire_id, "approve": index == 0} diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py index 34f63833543..07e66d95c97 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py @@ -30,6 +30,7 @@ response_handler, ) from agent_framework._workflows._const import RESOLVED_WORKFLOW_RUN_KWARGS_KEY +from agent_framework.exceptions import AgentInvalidResponseException from azure.ai.agentserver.core import AgentConfig, FoundryAgentRequestContext from azure.ai.agentserver.core.storage import FoundryStorageConflictError, FoundryStoragePreconditionError @@ -114,6 +115,25 @@ async def decide(self, request: Content, response: Content, ctx: WorkflowContext await ctx.yield_output("approved" if response.approved else "rejected") +class _Computer(Executor): + def __init__(self) -> None: + super().__init__("computer") + + @handler + async def start(self, message: str, ctx: WorkflowContext[str, str]) -> None: + call = Content.from_computer_tool_call( + id="item-1", + call_id="computer-1", + actions=[{"type": "screenshot"}], + pending_safety_checks=[{"id": "check-1", "code": "risk", "message": message}], + ) + await ctx.request_info(call, Content, request_id="computer-1") + + @response_handler + async def done(self, request: Content, response: Content, ctx: WorkflowContext[str, str]) -> None: + await ctx.yield_output(f"computer:{response.call_id}") + + class _Loop(Executor): def __init__(self, calls: list[str] | None = None) -> None: super().__init__("loop") @@ -546,42 +566,70 @@ async def test_graph_and_name_mismatch(changed: Workflow) -> None: await _prepare("two", workflow=changed, lineage_id="invocations") -async def test_partial_and_invalid_replies_do_not_claim_or_consume() -> None: +async def test_invalid_replies_fail_before_superstep_and_release_the_head() -> None: first = await _prepare("one", workflow=_workflow(_Review())) await _finish(first, WorkflowTurn(input="review")) - second = await _prepare("two", workflow=_workflow(_Review()), previous_response_id="one") - for replies in ({"first": True}, {"first": True, "forged": False}, {"first": {}, "second": True}): + for index, replies in enumerate(({"first": True, "forged": False}, {"first": {}, "second": True})): + attempt = await _prepare(f"bad-{index}", workflow=_workflow(_Review()), previous_response_id="one") + turn = attempt.validate_turn(WorkflowTurn(responses=replies)) + await attempt.claim() with pytest.raises(ValueError): - second.validate_turn(WorkflowTurn(responses=replies)) - head, _ = await second.store.get_head("one", None) - assert head is not None and head.response_id is None - assert await _finish(second, WorkflowTurn(responses={"first": True, "second": False})) == [ - "review:True", - "review:False", - ] + async for _ in attempt.events(turn): + pass + await attempt.abort() + head, _ = await attempt.store.get_head("one", None) + assert head is not None and head.response_id is None and not head.blocked + assert await attempt.store.get_response(f"bad-{index}") == (None, None) + + partial = await _prepare("partial", workflow=_workflow(_Review()), previous_response_id="one") + assert await _finish(partial, WorkflowTurn(responses={"first": True})) == ["review:True"] + rest = await _prepare("rest", workflow=_workflow(_Review()), previous_response_id="partial") + assert set(rest.pending_requests) == {"second"} + assert await _finish(rest, WorkflowTurn(responses={"second": False})) == ["review:False"] with pytest.raises(WorkflowConflictError, match="stale or forked"): await _prepare("replay", workflow=_workflow(_Review()), previous_response_id="one") -async def test_forged_embedded_approval_is_rejected_before_consumption() -> None: - first = await _prepare("one", workflow=_workflow(_Approval())) - await _finish(first, WorkflowTurn(input="/safe")) - second = await _prepare("two", workflow=_workflow(_Approval()), previous_response_id="one") - pending = second.pending_requests["approval-1"].data - forged = Content.from_function_call("call-1", "delete", arguments={"path": "/forged"}, id="approval-1") - with pytest.raises(ValueError, match="exact pending"): - second.validate_turn( - WorkflowTurn( - responses={ - "approval-1": Content.from_function_approval_response(True, "approval-1", forged), - } - ) - ) - decision = pending.to_function_approval_response(True) - assert await _finish(second, WorkflowTurn(responses={"approval-1": decision})) == ["approved"] +async def test_unacknowledged_computer_result_releases_the_head_for_a_valid_retry() -> None: + first = await _prepare("one", workflow=_workflow(_Computer())) + await _finish(first, WorkflowTurn(input="review")) + unacknowledged = Content.from_computer_tool_result(call_id="computer-1") + attempt = await _prepare("bad", workflow=_workflow(_Computer()), previous_response_id="one") + turn = attempt.validate_turn(WorkflowTurn(responses={"computer-1": unacknowledged})) + await attempt.claim() + with pytest.raises(AgentInvalidResponseException, match="safety checks"): + async for _ in attempt.events(turn): + pass + await attempt.abort() + head, _ = await attempt.store.get_head("one", None) + assert head is not None and head.response_id is None and not head.blocked + + acknowledged = Content.from_computer_tool_result( + call_id="computer-1", acknowledged_safety_checks=[{"id": "check-1", "code": "risk", "message": "review"}] + ) + retry = await _prepare("retry", workflow=_workflow(_Computer()), previous_response_id="one") + assert await _finish(retry, WorkflowTurn(responses={"computer-1": acknowledged})) == ["computer:computer-1"] -async def test_racing_claims_consume_authority_once() -> None: +async def test_failure_after_first_superstep_still_blocks_the_lineage() -> None: + first = await _prepare("one", workflow=_workflow(_Review())) + await _finish(first, WorkflowTurn(input="review")) + attempt = await _prepare("bad", workflow=_workflow(_Review()), previous_response_id="one") + turn = attempt.validate_turn(WorkflowTurn(responses={"first": True, "second": False})) + await attempt.claim() + events = attempt.events(turn) + async for event in events: + if event.type == "superstep_started": + break + await events.aclose() + await attempt.abort() + head, _ = await attempt.store.get_head("one", None) + assert head is not None and head.blocked + with pytest.raises(WorkflowBlockedError): + await _prepare("retry", workflow=_workflow(_Review()), previous_response_id="one") + + +async def test_racing_claims_admit_one_and_pre_superstep_abort_releases() -> None: first = await _prepare("one") await _finish(first, WorkflowTurn(input=1)) left = await _prepare("left", previous_response_id="one") @@ -592,8 +640,8 @@ async def test_racing_claims_consume_authority_once() -> None: with pytest.raises(RuntimeError, match="Another request"): await right.claim() await left.abort() - with pytest.raises(RuntimeError, match="fresh workflow lineage"): - await _prepare("retry", previous_response_id="one") + retry = await _prepare("retry", previous_response_id="one") + assert await _finish(retry, WorkflowTurn(input=1)) == [2] @pytest.mark.parametrize("error", [FoundryStorageConflictError, FoundryStoragePreconditionError]) diff --git a/python/packages/foundry_hosting/tests/test_responses.py b/python/packages/foundry_hosting/tests/test_responses.py index 1b6e718ceb1..8bdee7b7bce 100644 --- a/python/packages/foundry_hosting/tests/test_responses.py +++ b/python/packages/foundry_hosting/tests/test_responses.py @@ -71,7 +71,6 @@ from azure.ai.agentserver.responses.models import ( CreateResponse, Item, - ItemReferenceParam, MCPApprovalResponse, Metadata, OutputItem, @@ -87,7 +86,7 @@ from pydantic import TypeAdapter from agent_framework_foundry_hosting import ResponsesHostServer, ResponsesRequest -from agent_framework_foundry_hosting._approvals import SessionApprovalState, _InvalidApproval +from agent_framework_foundry_hosting._approvals import SessionApprovalState from agent_framework_foundry_hosting._responses_shared import ( _INCOMPLETE_REASON_KEY, # pyright: ignore[reportPrivateUsage] _LATEST_CHECKPOINT_ID_KEY, # pyright: ignore[reportPrivateUsage] @@ -123,8 +122,6 @@ BackgroundChatMiddleware, BackgroundPollingClient, GatedAgentStream, - GatedApprovalStore, - GatedClaimStore, GatedRequestRead, GatedSessionLoadStore, StatefulConsentClient, @@ -2150,7 +2147,7 @@ async def test_raw_agent_client_chat_middleware_cannot_override_background(self, assert client.chat_middleware == [middleware] @pytest.mark.parametrize("stream", [False, True]) - async def test_middleware_failure_after_approval_claim_does_not_restore_authority( + async def test_middleware_failure_on_approval_reply_leaves_parent_pending( self, stream: bool, tmp_path: Path ) -> None: client = ApprovalPublishingClient(_make_function_approval_request_content()) @@ -2173,9 +2170,11 @@ async def test_middleware_failure_after_approval_claim_does_not_restore_authorit else: assert rejected.json()["status"] == "failed" assert client.calls == 1 + # The failed turn saved nothing, so the parent still holds the pending request. + agent.middleware = [] replay = await _post_json(server, payload) - assert replay.status_code == 400 - assert client.calls == 1 + assert replay.status_code == 200 + assert client.calls == 2 @pytest.mark.parametrize("provider_background", [False, True]) @pytest.mark.parametrize("layered_agent", [False, True]) @@ -2494,8 +2493,9 @@ async def test_invalid_approval_does_not_consume_service_parent(self) -> None: }, ) - assert invalid.status_code == 400 - assert "No pending approval batch" in invalid.json()["error"]["message"] + assert invalid.status_code == 200 + assert invalid.json()["status"] == "failed" + assert "No approval reply matches" in invalid.json()["error"]["message"] parent = await store.get(parent_id) assert parent is not None and "_foundry_service_child" not in parent.state assert len(client.calls) == 1 @@ -7027,7 +7027,6 @@ async def test_mcp_approval_request(self) -> None: assert msg.contents[0].type == "function_approval_request" async def test_mcp_approval_response(self) -> None: - from azure.ai.agentserver.responses.models import MCPApprovalResponse saved = _make_function_approval_request_content(request_id="apr-1") storage = _function_approval_store(saved) @@ -8452,7 +8451,6 @@ async def test_input_item_mcp_approval_request_loads_from_storage(self) -> None: assert msg.contents[0].id == "apr-1" async def test_input_item_mcp_approval_response_resolves_to_approval_response(self) -> None: - from azure.ai.agentserver.responses.models import MCPApprovalResponse saved = _make_function_approval_request_content(request_id="apr-1") storage = _function_approval_store(saved) @@ -8501,7 +8499,7 @@ async def test_non_streaming_emits_mcp_approval_request_and_persists_to_storage( # Storage must contain a saved entry under the emitted request id. session = await store.get(body["id"]) assert session is not None - loaded = await SessionApprovalState(session, store).load_approval_request(approval_request_id) + loaded = await SessionApprovalState(session).load_approval_request(approval_request_id) assert loaded.type == "function_approval_request" assert loaded.function_call is not None assert loaded.function_call.name == "delete_file" @@ -8565,7 +8563,7 @@ async def test_streaming_emits_mcp_approval_request_and_persists_to_storage( response_id = next(e["data"]["response"]["id"] for e in events if e["event"] == "response.completed") session = await store.get(response_id) assert session is not None - loaded = await SessionApprovalState(session, store).load_approval_request(approval_request_id) + loaded = await SessionApprovalState(session).load_approval_request(approval_request_id) assert loaded.type == "function_approval_request" async def test_round_trip_approval_response_reaches_agent(self, tmp_path: Path) -> None: @@ -8657,10 +8655,12 @@ async def test_round_trip_approval_response_rejected(self, tmp_path: Path) -> No assert len(approval_responses) == 1 assert approval_responses[0].approved is False - async def test_approval_response_referencing_unknown_id_fails(self) -> None: - """A response without pending session authority is rejected before execution.""" + @pytest.mark.parametrize("stream", [False, True]) + async def test_approval_response_referencing_unknown_id_fails_without_running(self, stream: bool) -> None: + """An unknown wire ID is not translated; a reply with nothing left fails before the agent runs.""" agent = _make_agent( - response=AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("ok")])]) + response=AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("ok")])]), + stream_updates=[AgentResponseUpdate(contents=[Content.from_text("ok")], role="assistant")], ) server = _make_server(agent) @@ -8668,388 +8668,51 @@ async def test_approval_response_referencing_unknown_id_fails(self) -> None: server, { "model": "test-model", - "input": [ - { - "type": "mcp_approval_response", - "approval_request_id": "apr_unknown", - "approve": True, - } - ], - "stream": False, + "input": [{"type": "mcp_approval_response", "approval_request_id": "apr_unknown", "approve": True}], + "stream": stream, }, ) - assert resp.status_code == 400 - agent.run.assert_not_called() - - @pytest.mark.parametrize("stream", [False, True]) - async def test_invalid_batches_are_rejected_before_headers_without_consuming_authority( - self, stream: bool, tmp_path: Path - ) -> None: - requests = [ - _make_function_approval_request_content(request_id=f"request-{index}", call_id=f"call-{index}") - for index in range(2) - ] - agent = _make_multi_response_agent([ - AgentResponse(messages=[Message(role="assistant", contents=requests)]), - AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("done")])]), - ]) - store = SqliteSessionStore(tmp_path / "approvals.sqlite") - response_store = InMemoryResponseProvider() - server = _make_server(agent, session_store=store, response_store=response_store) - first = await _post(server) - assert first.status_code == 200 - previous_id = first.json()["id"] - approval_ids = [item["id"] for item in first.json()["output"] if item["type"] == "mcp_approval_request"] - assert len(approval_ids) == 2 - decisions = [ - MCPApprovalResponse(type="mcp_approval_response", approval_request_id=approval_id, approve=index == 0) - for index, approval_id in enumerate(approval_ids) - ] - assert (await response_store.get_items([approval_ids[0]]))[0] is not None - invalid_inputs: list[Any] = [ - decisions[:1], - [decisions[0], decisions[0]], - [decisions[0], {**decisions[1], "approval_request_id": "foreign"}], - "continue", - [*decisions, {"type": "message", "role": "user", "content": "extra"}], - [*decisions, {"type": "item_reference", "id": approval_ids[0]}], - [*decisions, {"type": "item_reference", "id": "missing-item"}], - [{"type": "item_reference", "id": "missing-item"}], - ] - for invalid_input in invalid_inputs: - response = await _post_json( - server, - {"input": invalid_input, "previous_response_id": previous_id, "stream": stream}, - ) - assert response.status_code == 400, response.text - assert response.headers["content-type"].startswith("application/json") - assert response.headers["x-platform-error-source"] == "user" - assert "response.created" not in response.text - assert agent.run.call_count == 1 - - async with httpx.AsyncClient(transport=httpx.ASGITransport(app=server), base_url="http://test") as client: - for id_in_header in (True, False): - for invalid_input in (decisions[:1], [decisions[0], decisions[0]]): - payload = {"input": invalid_input, "previous_response_id": previous_id, "stream": stream} - headers = {"x-agent-response-id": previous_id} if id_in_header else {} - if not id_in_header: - payload["response_id"] = previous_id - redelivery = await client.post("/responses", headers=headers, json=payload) - assert redelivery.status_code == 400 - assert redelivery.headers["content-type"].startswith("application/json") - assert "response.created" not in redelivery.text - assert agent.run.call_count == 1 - - rejected_store = await _post_json( - server, - {"input": decisions, "previous_response_id": previous_id, "stream": stream, "store": False}, - ) - assert rejected_store.status_code == 400, rejected_store.text - assert rejected_store.headers["content-type"].startswith("application/json") - assert agent.run.call_count == 1 - - direct_request = CreateResponse( - input=[*decisions, ItemReferenceParam(type="item_reference", id="missing-item")], - previous_response_id=previous_id, - ) - direct_context = ResponseContext( - response_id="handler-revalidation", - mode_flags=MagicMock(), - request=direct_request, - previous_response_id=previous_id, - provider=response_store, - ) - with patch.object(ResponseContext, "get_input_items", new=AsyncMock(return_value=decisions)): - direct_events = [ - event async for event in server._handle_response(direct_request, direct_context, asyncio.Event()) - ] - assert any( - isinstance(event, Mapping) - and event.get("type") == "response.failed" - and "Pending MCP approvals cannot be mixed" in str(event) - for event in direct_events - ) - assert agent.run.call_count == 1 - referenced_id = "resolved-decision" - await response_store.create_response( - cast(ResponseObject, {**first.json(), "id": "reference-seed", "output": []}), - [cast(OutputItem, {**decisions[0], "id": referenced_id})], - [], - ) - continuation_id = IdGenerator.new_response_id(previous_id) - continuation = { - "input": [decisions[1], {"type": "item_reference", "id": referenced_id}], - "previous_response_id": previous_id, - "stream": stream, - } - async with httpx.AsyncClient(transport=httpx.ASGITransport(app=server), base_url="http://test") as client: - accepted = await client.post( - "/responses", headers={"x-agent-response-id": continuation_id}, json=continuation - ) - assert accepted.status_code == 200, accepted.text + assert resp.status_code == 200, resp.text if stream: - events = _parse_sse_events(accepted.text) - completed = next(event["data"]["response"] for event in events if event["event"] == "response.completed") + assert "response.failed" in _sse_event_types(_parse_sse_events(resp.text)) else: - completed = accepted.json() - assert completed["status"] == "completed" - assert completed["id"] == continuation_id - received = [ - content.approved - for message in agent.run.call_args.kwargs["messages"] - for content in message.contents - if content.type == "function_approval_response" - ] - assert received == [False, True] - replay = await _post_json(server, {"input": decisions, "previous_response_id": previous_id, "stream": stream}) - assert replay.status_code == 400 - async with httpx.AsyncClient(transport=httpx.ASGITransport(app=server), base_url="http://test") as client: - for id_in_header in (True, False): - payload = dict(continuation) - headers = {"x-agent-response-id": continuation_id} if id_in_header else {} - if not id_in_header: - payload["response_id"] = continuation_id - redelivery = await client.post("/responses", headers=headers, json=payload) - assert redelivery.status_code == 400 - assert redelivery.headers["content-type"].startswith("application/json") - assert "response.created" not in redelivery.text - assert agent.run.call_count == 2 - - @pytest.mark.parametrize("platform_error", [False, True]) - async def test_backend_value_error_is_not_mapped_to_invalid_approval( - self, platform_error: bool, tmp_path: Path - ) -> None: - from azure.ai.agentserver.responses.hosting._validation import tag_platform_error - - request = _make_function_approval_request_content() - agent = _make_agent(response=AgentResponse(messages=[Message(role="assistant", contents=[request])])) - store = SqliteSessionStore(tmp_path / "approvals.sqlite") - server = _make_server(agent, session_store=store) - first = await _post(server) - previous_id = first.json()["id"] - approval_id = next(item["id"] for item in first.json()["output"] if item["type"] == "mcp_approval_request") - session = await store.get(previous_id) - assert session is not None - error = ValueError(_SESSION_STORAGE_ERROR_DETAIL) - if platform_error: - tag_platform_error(error) - with ( - patch.object(store, "get", new=AsyncMock(return_value=session)), - patch.object(store, "get_with_revision", new=AsyncMock(side_effect=error)), - ): - response = await _post_json( - server, - { - "input": [{"type": "mcp_approval_response", "approval_request_id": approval_id, "approve": True}], - "previous_response_id": previous_id, - "stream": True, - }, - ) - assert response.status_code == 500 - assert response.headers["x-platform-error-source"] == ("platform" if platform_error else "upstream") - assert _SESSION_STORAGE_ERROR_DETAIL not in response.text - assert _SESSION_STORAGE_ERROR_DETAIL not in str(response.headers) - assert agent.run.call_count == 1 + assert resp.json()["status"] == "failed" + agent.run.assert_not_called() @pytest.mark.parametrize("stream", [False, True]) - async def test_session_lookup_approval_error_is_a_backend_failure(self, stream: bool, tmp_path: Path) -> None: - approval = _make_function_approval_request_content() - agent = _make_agent(response=AgentResponse(messages=[Message(role="assistant", contents=[approval])])) - store = SqliteSessionStore(tmp_path / "approvals.sqlite") - server = _make_server(agent, session_store=store) - first = await _post(server) - previous_id = first.json()["id"] - approval_id = next(item["id"] for item in first.json()["output"] if item["type"] == "mcp_approval_request") - - with patch.object(store, "get", new=AsyncMock(side_effect=_InvalidApproval(_SESSION_STORAGE_ERROR_DETAIL))): - response = await _post_json( - server, - { - "input": [{"type": "mcp_approval_response", "approval_request_id": approval_id, "approve": True}], - "previous_response_id": previous_id, - "stream": stream, - }, - ) - - assert response.status_code == 500 - assert response.headers["x-platform-error-source"] == "upstream" - assert _SESSION_STORAGE_ERROR_DETAIL not in response.text - assert agent.run.call_count == 1 - - @pytest.mark.parametrize("fail_alias", [False, True]) - async def test_approval_events_wait_for_authority_and_session_snapshots( - self, fail_alias: bool, tmp_path: Path - ) -> None: - approval = _make_function_approval_request_content() - agent = _make_agent(stream_updates=[AgentResponseUpdate(contents=[approval], role="assistant")]) - store = GatedApprovalStore(tmp_path / "gated.sqlite", fail_alias=fail_alias) - server = _make_server(agent, session_store=store) - context = ResponseContext(response_id="response-gated", mode_flags=MagicMock()) - events: list[Any] = [] - task = asyncio.create_task( - collect_host_events( - cast(AsyncIterator[Any], server._handle_response(CreateResponse(input="go"), context, asyncio.Event())), - events, - ) - ) - try: - await asyncio.wait_for(store.started.wait(), 5) - assert "mcp_approval_request" not in str(events) - assert await store.get("response-gated") is None - store.release.set() - await asyncio.wait_for(task, 5) - finally: - store.release.set() - if not task.done(): - task.cancel() - with suppress(asyncio.CancelledError): - await task - - if fail_alias: - assert "mcp_approval_request" not in str(events) - assert any(event.get("type") == "response.failed" for event in events) - else: - assert any( - event.get("type") == "response.output_item.added" and event["item"]["type"] == "mcp_approval_request" - for event in events - ) - assert await store.get("response-gated") is not None - - async def test_background_approval_checkpoint_waits_for_durable_authority(self, tmp_path: Path) -> None: - approval = _make_function_approval_request_content() - agent = _make_agent() - agent.client.STORES_BY_DEFAULT = True - agent.run = AsyncMock( - side_effect=[ - AgentResponse(messages=[], continuation_token=OpenAIContinuationToken(response_id="provider-token")), - AgentResponse(messages=[Message(role="assistant", contents=[approval])]), - ] - ) - store = GatedApprovalStore(tmp_path / "background-approval.sqlite") - server = _make_server( - agent, - session_store=store, - history_source="inference_service", - background_source="inference_service", - enable_background_recovery=True, - response_store=FileResponseStore(storage_dir=tmp_path), + async def test_unknown_approval_id_is_dropped_beside_other_input(self, stream: bool) -> None: + """An unknown wire ID beside other input is dropped; Core never sees an approval to authorize.""" + agent = _make_agent( + response=AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("ok")])]), + stream_updates=[AgentResponseUpdate(contents=[Content.from_text("ok")], role="assistant")], ) - context = ResponseContext(response_id="background-approval", mode_flags=MagicMock()) - request = CreateResponse(input="go", store=True, background=True) - events: list[Any] = [] - with ( - patch.object(ResponseContext, "get_input_items", new=AsyncMock(return_value=[])), - patch("agent_framework_foundry_hosting._responses_agent.asyncio.sleep", new=AsyncMock()), - ): - task = asyncio.create_task( - collect_host_events( - cast(AsyncIterator[Any], server._handle_response(request, context, asyncio.Event())), - events, - ) - ) - try: - await asyncio.wait_for(store.started.wait(), timeout=5) - assert "mcp_approval_request" not in str(events) - assert not any(isinstance(event, ResponseCheckpointEvent) for event in events) - private_snapshot = await store.get("background-approval") - assert private_snapshot is not None - assert private_snapshot.state["_foundry_provider_background"]["completed"] is True - store.release.set() - await asyncio.wait_for(task, timeout=5) - finally: - store.release.set() - if not task.done(): - task.cancel() - await asyncio.gather(task, return_exceptions=True) + server = _make_server(agent) - assert any(isinstance(event, ResponseCheckpointEvent) for event in events) - assert any( - isinstance(event, Mapping) - and event.get("type") == "response.output_item.added" - and event["item"]["type"] == "mcp_approval_request" - for event in events + resp = await _post_json( + server, + { + "model": "test-model", + "input": [ + {"type": "mcp_approval_response", "approval_request_id": "apr_unknown", "approve": True}, + {"type": "message", "role": "user", "content": "hello"}, + ], + "stream": stream, + }, ) - final_snapshot = await store.get("background-approval") - assert final_snapshot is not None - assert any("approval" in key for key in final_snapshot.state) - @pytest.mark.parametrize("stream", [False, True]) - async def test_concurrent_continuations_only_dispatch_one_claim(self, stream: bool, tmp_path: Path) -> None: - approval = _make_function_approval_request_content() - agent = _make_multi_response_agent([ - AgentResponse(messages=[Message(role="assistant", contents=[approval])]), - AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("done")])]), - ]) - store = GatedClaimStore(tmp_path / "race.sqlite") - server = _make_server(agent, session_store=store) - first = await _post(server) - approval_id = next(item["id"] for item in first.json()["output"] if item["type"] == "mcp_approval_request") - payload = { - "input": [{"type": "mcp_approval_response", "approval_request_id": approval_id, "approve": True}], - "previous_response_id": first.json()["id"], - "stream": stream, - } - tasks = [asyncio.create_task(_post_json(server, payload)) for _ in range(2)] - try: - await asyncio.wait_for(store.started.wait(), 5) - assert agent.run.call_count == 1 - store.release.set() - responses = await asyncio.wait_for(asyncio.gather(*tasks), 5) - finally: - store.release.set() - for task in tasks: - if not task.done(): - task.cancel() - await asyncio.gather(*tasks, return_exceptions=True) - - assert agent.run.call_count == 2 - if stream: - terminals = [ - next( - event["event"] - for event in _parse_sse_events(response.text) - if event["event"] in {"response.completed", "response.failed"} - ) - for response in responses - ] - assert sorted(terminals) == ["response.completed", "response.failed"] - else: - assert sorted(response.json()["status"] for response in responses) == ["completed", "failed"] - - @pytest.mark.parametrize("cancelled", [False, True]) - async def test_lost_claim_ack_does_not_dispatch_or_reopen_approval(self, cancelled: bool, tmp_path: Path) -> None: - approval = _make_function_approval_request_content() - agent = _make_agent(response=AgentResponse(messages=[Message(role="assistant", contents=[approval])])) - store = SqliteSessionStore(tmp_path / "lost-ack.sqlite") - server = _make_server(agent, session_store=store) - first = await _post(server) - approval_id = next(item["id"] for item in first.json()["output"] if item["type"] == "mcp_approval_request") - payload = { - "input": [{"type": "mcp_approval_response", "approval_request_id": approval_id, "approve": True}], - "previous_response_id": first.json()["id"], - } - store.error_after_commit = ( - asyncio.CancelledError() if cancelled else RuntimeError("claim acknowledged unsuccessfully") - ) - if cancelled: - with pytest.raises(asyncio.CancelledError): - await _post_json(server, payload) - else: - failed = await _post_json(server, payload) - assert failed.status_code == 200 - assert failed.json()["status"] == "failed" - assert agent.run.call_count == 1 - store.error_after_commit = None - replay = await _post_json(server, payload) - assert replay.status_code == 400 + assert resp.status_code == 200, resp.text assert agent.run.call_count == 1 + sent = [content for message in agent.run.call_args.kwargs["messages"] for content in message.contents] + assert not any(content.type.startswith("function_approval") for content in sent) + assert any(content.type == "text" and content.text == "hello" for content in sent) @pytest.mark.parametrize("stream", [False, True]) - async def test_approval_is_isolated_by_platform_user(self, stream: bool, tmp_path: Path) -> None: + async def test_approval_from_another_platform_user_is_dropped(self, stream: bool, tmp_path: Path) -> None: approval = _make_function_approval_request_content() agent = _make_multi_response_agent([ AgentResponse(messages=[Message(role="assistant", contents=[approval])]), + AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("other")])]), AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("done")])]), ]) stores = { @@ -9068,46 +8731,16 @@ async def test_approval_is_isolated_by_platform_user(self, stream: bool, tmp_pat "previous_response_id": first.json()["id"], "stream": stream, } - denied = await client.post("/responses", json=payload, headers={"x-agent-user-id": "other"}) - assert denied.status_code == 400, denied.text - assert denied.headers["content-type"].startswith("application/json") - assert agent.run.call_count == 1 + await client.post("/responses", json=payload, headers={"x-agent-user-id": "other"}) + if agent.run.call_count == 2: + sent = [c for m in agent.run.call_args.kwargs["messages"] for c in m.contents] + assert not any(content.type == "function_approval_response" for content in sent) + calls_before_owner = agent.run.call_count accepted = await client.post("/responses", json=payload, headers={"x-agent-user-id": "owner"}) assert accepted.status_code == 200, accepted.text - if stream: - assert "response.completed" in _sse_event_types(_parse_sse_events(accepted.text)) - else: - assert accepted.json()["status"] == "completed" - assert agent.run.call_count == 2 - - @pytest.mark.parametrize("stream", [False, True]) - async def test_conversation_and_response_aliases_share_approval_authority( - self, stream: bool, tmp_path: Path - ) -> None: - approval = _make_function_approval_request_content() - agent = _make_multi_response_agent([ - AgentResponse(messages=[Message(role="assistant", contents=[approval])]), - AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("done")])]), - ]) - server = _make_server(agent, session_store=SqliteSessionStore(tmp_path / "aliases.sqlite")) - conversation_id = IdGenerator.new_id("conv") - first = await _post_json(server, {"input": "go", "conversation": conversation_id}) - assert first.status_code == 200, first.text - previous_id = first.json()["id"] - approval_id = next(item["id"] for item in first.json()["output"] if item["type"] == "mcp_approval_request") - decision = [{"type": "mcp_approval_response", "approval_request_id": approval_id, "approve": True}] - - invalid = await _post_json(server, {"input": "continue", "conversation": conversation_id, "stream": stream}) - assert invalid.status_code == 400 - accepted = await _post_json(server, {"input": decision, "conversation": conversation_id, "stream": stream}) - assert accepted.status_code == 200, accepted.text - if stream: - assert "response.completed" in _sse_event_types(_parse_sse_events(accepted.text)) - else: - assert accepted.json()["status"] == "completed" - replay = await _post_json(server, {"input": decision, "previous_response_id": previous_id, "stream": stream}) - assert replay.status_code == 400 - assert agent.run.call_count == 2 + assert agent.run.call_count == calls_before_owner + 1 + sent = [c for m in agent.run.call_args.kwargs["messages"] for c in m.contents] + assert [content.approved for content in sent if content.type == "function_approval_response"] == [True] # endregion diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md index 8b1072e95e6..48b94922c29 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md @@ -2,9 +2,8 @@ This sample implements custom **MAF agent-session persistence**, including user and sandbox isolation and optimistic concurrency. The outer Responses store -remains host-managed. The same custom store also holds the host's agent -approval state, so it implements revision-based conditional writes (see -[Approval state](#approval-state-and-revisioned-writes)). This is not a +remains host-managed. Pending tool approvals are part of the saved +`AgentSession`, so the store needs only `get`/`set`/`delete`. This is not a workflow example. ## Identity and storage keys @@ -63,52 +62,6 @@ process exits. They are **single-user development only**: local headers and session selectors are not a trusted platform authentication boundary. Explicit local sessions have separate namespaces. -## Approval state and revisioned writes - -The host keeps agent tool-approval state in the configured session store, not -in a separate approval store. Each tool-approval request needs a single atomic -claim. A custom store that holds approval state must therefore add two async -methods next to `get`/`set`/`delete`: - -```python -async def get_with_revision(self, session_id: str) -> tuple[AgentSession | None, str | None]: ... -async def compare_and_set( - self, session_id: str, session: AgentSession, *, expected_revision: str | None -) -> str: ... -``` - -The host detects these methods structurally. Do not import or subclass a -private hosting type. The sample stores follow these rules: - -- `get_with_revision` returns an independent snapshot and an opaque, non-empty - revision for that exact stored version. An absent key returns - `(None, None)`. Revision reads do not change the per-request ETags that - `get`/`set` use. -- `expected_revision=None` is an atomic **create-only** write. A revision means - an update only when the stored version still matches. A conflict raises - `RuntimeError`. The store never falls back to an upsert or retries the write - on its own. On success it returns the new revision. -- Keys are opaque strings. They can differ from `AgentSession.session_id` and - can contain characters such as `/`. Cosmos item IDs hash the key. -- Cosmos uses `create_item` and `replace_item` with the ETag and - `MatchConditions.IfNotModified`. The service applies each condition in the - account's write region; see [Cosmos prerequisites](#cosmos-prerequisites). - The store accepts one quoted, strong ETag as a revision. It rejects wildcard - and list `If-Match` values before sending a write or delete. A missing or - invalid ETag in a read or write result fails. -- A write that fails or is cancelled may still have been committed. Reload the - state before you decide what to do next. Do not assume that the write did - not happen. - -The local store implements the same methods for development. Its conditional -write is atomic only among stores from the same provider in one event loop. -Use a store with server-side conditional writes, such as Cosmos, when separate -providers, workers, or processes can serve the same conversation. - -Without these methods, the host can still use the store for ordinary session -history. A non-hosted request that needs approval state fails with a -`RuntimeError` that names the missing methods. - ## Cosmos prerequisites Create the database/container separately and set: @@ -119,15 +72,6 @@ COSMOS_DATABASE_NAME= COSMOS_CONTAINER_NAME= ``` -For approval state, the user-managed Cosmos account configured for this sample -**must use one write region**. -Multi-write-region accounts can accept conditional updates independently in -different regions before resolving conflicts. This sample does not provide a -single global approval claim in that configuration. See -[Cosmos optimistic concurrency and global distribution](https://learn.microsoft.com/en-us/azure/cosmos-db/database-transactions-optimistic-concurrency#optimistic-concurrency-control-and-global-distribution). -This prerequisite applies to the sample's custom provider, not to the -Foundry-managed state store. - The hosted provider uses `azure.identity.aio.ManagedIdentityCredential`, with the platform-provided `FOUNDRY_AGENT_INSTANCE_CLIENT_ID` when present. Grant that managed identity **Cosmos DB Built-in Data Contributor** at the narrowest From 5806acced7e65917c7f0d5ca5b1afb2ce6f7a438 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 14:18:48 +0100 Subject: [PATCH 45/55] Python: Remove Responses legacy parser compatibility guard --- .../agent_framework_foundry_hosting/_responses_workflow.py | 2 -- .../foundry_hosting/tests/test_foundry_hosting_imports.py | 1 - 2 files changed, 3 deletions(-) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py index 5f1589ab408..8b54c548085 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py @@ -375,8 +375,6 @@ def __init__( ValueError: If a supported setting has an invalid value. """ reject_removed_host_settings(kwargs) - if "parse_response" in kwargs: - raise TypeError("parse_response was renamed to parse_input.") forbidden = { "agent", "agent_session_store_provider", diff --git a/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py b/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py index 6a32e94fe98..bdf730c6b8e 100644 --- a/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py +++ b/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py @@ -188,7 +188,6 @@ def test_legacy_responses_request_name_is_not_exported() -> None: @pytest.mark.parametrize( ("name", "legacy"), [ - ("ResponsesWorkflowHostServer", "parse_response"), ("InvocationsHostServer", "parse_request"), ("InvocationsWorkflowHostServer", "parse_request"), ], From 15adafd2b0e1784fa59dc6d1d81a181519c63097 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 14:33:29 +0100 Subject: [PATCH 46/55] Make caller generation options opt-in --- .../_invocations_agent.py | 17 +++-- .../_invocations_shared.py | 13 ++-- .../_invocations_workflow.py | 11 +-- .../_shared.py | 39 ++++------ .../foundry_hosting/test_host_options.py | 75 ++++++++++++------- .../tests/test_foundry_hosting_imports.py | 5 +- .../foundry_hosting/tests/test_invocations.py | 11 ++- 7 files changed, 87 insertions(+), 84 deletions(-) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py index 4ebf66e7dfa..ed03bd3187f 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py @@ -31,7 +31,7 @@ def __init__( prepare_options: InvocationOptionsHook | None = None, unsupported_options: UnsupportedOptions = "warn", sse_keep_alive_interval_seconds: int | None = None, - **kwargs: Any, + **agent_server_kwargs: Any, ) -> None: """Create an agent host with session-backed application turns. @@ -51,14 +51,17 @@ def __init__( parse_input: Sync or async parser returning `InvocationRun`. Without a parser, accept JSON `message`, optional `options`, and `stream`. prepare_options: Sync or async hook receiving the request and a copy of caller generation - options, for streaming and non-streaming requests. Return the replacement mapping. + options. Return the replacement mapping. Hosting validates protected fields after the hook and before resolving the factory, - unlike Responses factories which run before the hook. Removing a caller ``model`` - retains the agent/client inference default. Defaults are not mutated. + unlike Responses factories which run before the hook. Defaults are not mutated. unsupported_options: Policy for agents without runtime options: `"warn"`, `"ignore"`, or `"error"`. sse_keep_alive_interval_seconds: Positive streaming heartbeat interval. If omitted, use a positive `SSE_KEEPALIVE_INTERVAL`, otherwise disable heartbeats. Not a request/model timeout. - **kwargs: Additional AgentServer host settings forwarded to the SDK. + **agent_server_kwargs: Additional AgentServer SDK constructor arguments, such as + `asyncapi_spec_json` and `asyncapi_spec_yaml`. The host settings listed above (`agent`, + `openapi_spec`, `agent_session_store_provider`, `parse_input`, `prepare_options`, + `unsupported_options`, and `sse_keep_alive_interval_seconds`) are handled directly by this host. + Use `InvocationsWorkflowHostServer` for native workflow settings. Raises: TypeError: If the agent source, parser/hook, or heartbeat type is invalid, or removed, @@ -66,8 +69,6 @@ def __init__( ValueError: If the heartbeat interval is nonpositive, raw legacy output requests heartbeats, or an injected agent has unsupported background or transport defaults. """ - if {"workflow", "checkpoint_store_provider"}.intersection(kwargs): - raise TypeError("Use InvocationsWorkflowHostServer for native workflows and checkpoint storage.") super().__init__( agent=agent, openapi_spec=openapi_spec, @@ -76,5 +77,5 @@ def __init__( prepare_options=prepare_options, unsupported_options=unsupported_options, sse_keep_alive_interval_seconds=sse_keep_alive_interval_seconds, - **kwargs, + **agent_server_kwargs, ) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py index 164597f7dc0..a674e4fc8a6 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py @@ -59,7 +59,6 @@ WorkflowTurn, foreground_agent_run_kwargs, is_agent, - reject_removed_host_settings, resolve_agent, validate_agent_background_options, validate_agent_source, @@ -340,24 +339,21 @@ def __init__( prepare_options: InvocationOptionsHook | None = None, unsupported_options: UnsupportedOptions = "warn", sse_keep_alive_interval_seconds: int | None = None, - **kwargs: Any, + **agent_server_kwargs: Any, ) -> None: """Initialize shared protocol plumbing after the public host selects its execution model.""" - reject_removed_host_settings(kwargs) if forbidden := { "max_history_items", "history_source", "background_source", "enable_background_recovery", "shutdown_grace_period_seconds", - }.intersection(kwargs): + }.intersection(agent_server_kwargs): raise TypeError( f"Responses-only settings are not supported by Invocations: {', '.join(sorted(forbidden))}." ) validate_sse_keep_alive_interval(sse_keep_alive_interval_seconds) unsupported_options = validate_unsupported_options(unsupported_options) - if "parse_request" in kwargs: - raise TypeError("parse_request was renamed to parse_input.") if agent is not None and workflow is not None: raise TypeError("Provide exactly one of agent or workflow.") if agent is None and workflow is None: @@ -385,7 +381,7 @@ def __init__( self._workflow_resolver: WorkflowResolver[Request] | None = ( WorkflowResolver(workflow) if workflow is not None else None ) - super().__init__(openapi_spec=openapi_spec, **kwargs) + super().__init__(openapi_spec=openapi_spec, **agent_server_kwargs) if sse_keep_alive_interval_seconds is not None: self.config.sse_keepalive_interval = sse_keep_alive_interval_seconds self._agent = agent @@ -558,8 +554,9 @@ async def _parse(self, request: Request) -> InvocationRun | WorkflowTurn[Any]: ) async def _options(self, request: Request, parsed: InvocationRun) -> dict[str, Any]: - options = deepcopy(dict(parsed.options)) + options: dict[str, Any] = {} if self._prepare_options is not None: + options = deepcopy(dict(parsed.options)) result = self._prepare_options(request, options) if inspect.isawaitable(result): result = await result diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py index 6fd950f0454..c493a018706 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py @@ -26,7 +26,7 @@ def __init__( openapi_spec: dict[str, Any] | None = None, checkpoint_store_provider: ContextScopedStoreProvider[CheckpointStorage] | None = None, sse_keep_alive_interval_seconds: int | None = None, - **kwargs: Any, + **agent_server_kwargs: Any, ) -> None: """Create a native workflow host with explicit parsing and checkpoint ownership. @@ -44,8 +44,9 @@ def __init__( Native workflow history and pending replies are checkpoint-owned, not agent-session-owned. sse_keep_alive_interval_seconds: Positive streaming heartbeat interval. If omitted, use a positive `SSE_KEEPALIVE_INTERVAL`, otherwise disable heartbeats. Not a request/model timeout. - **kwargs: Additional AgentServer host settings forwarded to the SDK. Output uses JSON or framed - SSE workflow events. + **agent_server_kwargs: Additional AgentServer SDK constructor arguments, such as + `asyncapi_spec_json` and `asyncapi_spec_yaml`. Host-owned, removed, and agent-only settings are + rejected. Output uses JSON or framed SSE workflow events. Raises: TypeError: If the workflow is not a request-aware factory, the parser or heartbeat type is invalid, @@ -57,7 +58,7 @@ def __init__( "agent_session_store_provider", "prepare_options", "unsupported_options", - }.intersection(kwargs) + }.intersection(agent_server_kwargs) if forbidden: raise TypeError(f"Unsupported native workflow host settings: {', '.join(sorted(forbidden))}.") if not callable(parse_input): @@ -68,5 +69,5 @@ def __init__( openapi_spec=openapi_spec, checkpoint_store_provider=checkpoint_store_provider, sse_keep_alive_interval_seconds=sse_keep_alive_interval_seconds, - **kwargs, + **agent_server_kwargs, ) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py index e9e6c36b109..dbe4e203211 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py @@ -5,6 +5,7 @@ from __future__ import annotations import inspect +import warnings import weakref from collections import OrderedDict from collections.abc import Awaitable, Callable, Iterator, Mapping, Sequence @@ -48,23 +49,6 @@ UnsupportedOptions: TypeAlias = Literal["ignore", "warn", "error"] -def reject_removed_host_settings(settings: Mapping[str, Any]) -> None: - """Reject removed SDK settings before constructing a host or allocating resources.""" - replacements = { - "options": "Use the supported first-class host parameters instead of ResponsesServerOptions.", - "default_fetch_history_count": "Use max_history_items on a host-managed Responses agent.", - "default_model": "Configure inference defaults on the agent or client.", - "create_span_hook": "Use Agent Framework observability instead.", - "additional_server_version": "Custom server version stamping is not supported.", - "steerable_conversations": "Conversation steering is not supported.", - "resilient_background": "Use enable_background_recovery on a Responses host.", - "legacy_wire_format": "Invocations always use JSON responses and framed SSE events.", - } - for name, message in replacements.items(): - if name in settings: - raise TypeError(f"{name} is no longer a supported host setting. {message}") - - def validate_sse_keep_alive_interval(value: int | None) -> None: """Validate an explicit heartbeat interval without replacing SDK environment resolution.""" if value is not None: @@ -118,8 +102,13 @@ def build_response_server_options( if max_history_items <= 0: raise ValueError("max_history_items must be positive when supplied.") if is_workflow or history_source != "host_managed": - raise ValueError("max_history_items applies only to regular agents with history_source='host_managed'.") - kwargs["default_fetch_history_count"] = max_history_items + warnings.warn( + "max_history_items is ignored unless used with a regular agent and history_source='host_managed'.", + UserWarning, + stacklevel=2, + ) + else: + kwargs["default_fetch_history_count"] = max_history_items return ResponsesServerOptions( sse_keep_alive_interval_seconds=sse_keep_alive_interval_seconds, shutdown_grace_period_seconds=shutdown_grace_period_seconds, @@ -258,9 +247,7 @@ def response_run_options(request: CreateResponse) -> dict[str, Any]: raise TypeError("extra_body must be a mapping of model options.") if "extra_body" in value: raise ValueError("Nested extra_body is not supported; flatten provider options instead.") - if reserved := (_HOST_CONTROLLED_FIELDS | _RUN_CONTROLLED_FIELDS).intersection( - cast(Mapping[str, Any], value) - ): + if reserved := _HOST_CONTROLLED_FIELDS.intersection(cast(Mapping[str, Any], value)): raise ValueError(f"extra_body cannot set host-controlled fields: {', '.join(sorted(reserved))}.") nested_extra.update(cast(Mapping[str, Any], value)) elif name in _HOST_CONTROLLED_FIELDS: @@ -333,13 +320,13 @@ def _set_workflow_responses(self, loader: Callable[[], Awaitable[dict[str, Any]] async def prepare_response_options(request: ResponsesRequest, hook: OptionsHook | None) -> None: - """Apply a sync/async hook after factory resolution, without changing agent defaults. + """Apply a sync/async option selection hook without changing agent defaults. - Return replacement per-run options for both streaming and non-streaming requests. - Removing a caller ``model`` leaves the developer's agent/client default intact. - The host validates protected fields after this hook and before dispatch. + Caller options are omitted when no hook is configured. The host validates the + hook's replacement mapping before dispatch. """ if hook is None: + request.set_options({}) return result = hook(request, deepcopy(dict(request.options))) if inspect.isawaitable(result): diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py index f77a55a5a37..a05a0bd76e6 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py @@ -23,7 +23,7 @@ _NativeAgentOptions, build_response_server_options, prepare_response_options, - reject_removed_host_settings, + response_run_options, validate_agent_background_options, validate_request_options, ) @@ -58,8 +58,6 @@ def test_history_default_is_omitted_instead_of_forced_unlimited(monkeypatch: pyt ({"shutdown_grace_period_seconds": 0}, ValueError), ({"enable_background_recovery": 1}, TypeError), ({"enable_background_recovery": True}, ValueError), - ({"history_source": "inference_service", "max_history_items": 2}, ValueError), - ({"history_source": "agent_managed", "max_history_items": 2}, ValueError), ({"background_source": "inference_service"}, ValueError), ({"history_source": "wrong"}, ValueError), ({"background_source": "wrong"}, ValueError), @@ -81,36 +79,18 @@ def test_recovery_and_workflow_history_eligibility() -> None: enable_background_recovery=True, ).resilient_background assert build_response_server_options(is_workflow=True, enable_background_recovery=True).resilient_background - with pytest.raises(ValueError, match="regular agents"): - build_response_server_options(is_workflow=True, max_history_items=2) + with pytest.warns(UserWarning, match="max_history_items is ignored"): + workflow_options = build_response_server_options(is_workflow=True, max_history_items=2) + assert workflow_options.default_fetch_history_count == ResponsesServerOptions().default_fetch_history_count + with pytest.warns(UserWarning, match="max_history_items is ignored"): + agent_managed_options = build_response_server_options( + is_workflow=False, history_source="agent_managed", max_history_items=2 + ) + assert agent_managed_options.default_fetch_history_count == ResponsesServerOptions().default_fetch_history_count with pytest.raises(ValueError, match="regular agent"): build_response_server_options(is_workflow=True, background_source="inference_service") -@pytest.mark.parametrize( - "name", - [ - "options", - "default_fetch_history_count", - "default_model", - "create_span_hook", - "additional_server_version", - "steerable_conversations", - "resilient_background", - ], -) -def test_removed_host_settings_fail_even_when_none(name: str) -> None: - settings: dict[str, Any] = {name: None} - with pytest.raises(TypeError, match=name): - reject_removed_host_settings({name: None}) - with ( - patch("agent_framework_foundry_hosting._invocations_shared.InvocationAgentServerHost.__init__") as sdk, - pytest.raises(TypeError, match=name), - ): - InvocationsHostServer(Agent(client=OptionsClient()), **settings) - sdk.assert_not_called() - - @pytest.mark.parametrize( "name", [ @@ -197,6 +177,20 @@ async def test_invocations_hook_before_factory_preserves_developer_model(stream: assert callbacks.defaults == {"model": "developer", "temperature": 0.4} +@pytest.mark.parametrize("stream", [False, True]) +async def test_invocations_options_are_opt_in(stream: bool) -> None: + callbacks = OptionCallbacks(defaults={"model": "developer", "temperature": 0.4}) + host = InvocationsHostServer(callbacks.factory) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: + response = await client.post( + "/invocations?agent_session_id=options", + json={"message": "hi", "stream": stream, "options": {"model": "caller", "temperature": 0.8}}, + ) + assert response.status_code == 200 + assert callbacks.client.calls[0]["model"] == "developer" + assert callbacks.client.calls[0]["temperature"] == 0.4 + + @pytest.mark.parametrize("stream", [False, True]) async def test_invocations_rejects_factory_hidden_background_before_model_call( stream: bool, caplog: pytest.LogCaptureFixture @@ -300,3 +294,26 @@ async def test_response_hook_returns_independent_nested_options() -> None: assert request.options["metadata"] is not source["metadata"] with pytest.raises(TypeError, match="mapping"): await prepare_response_options(request, lambda request, options: cast(Any, {1: "not-string"})) + + +async def test_response_options_are_opt_in_and_hook_can_select_known_fields() -> None: + caller_options = response_run_options( + cast(Any, {"extra_body": {"messages": "not-a-generation-option", "temperature": 0.8}}) + ) + request = ResponsesRequest( + cast(Any, {}), + MagicMock(), + FoundryRequestScope("session", None, None, False), + caller_options, + ) + await prepare_response_options(request, None) + assert dict(request.options) == {} + + selected_request = ResponsesRequest( + cast(Any, {}), + MagicMock(), + FoundryRequestScope("session", None, None, False), + caller_options, + ) + await prepare_response_options(selected_request, lambda _request, options: {"temperature": options["temperature"]}) + assert dict(selected_request.options) == {"temperature": 0.8} diff --git a/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py b/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py index e3aa46d553f..b03a65d5cf9 100644 --- a/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py +++ b/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py @@ -150,7 +150,6 @@ def test_agent_hosts_reject_ambiguous_factories_before_sdk_construction(protocol ("Invocations", "agent_session_store_provider"), ("Invocations", "prepare_options"), ("Invocations", "unsupported_options"), - ("Invocations", "legacy_wire_format"), ], ) def test_workflow_hosts_reject_agent_settings_before_sdk_construction(protocol: str, setting: str) -> None: @@ -189,11 +188,9 @@ def test_legacy_responses_request_name_is_not_exported() -> None: ("name", "legacy"), [ ("ResponsesWorkflowHostServer", "parse_response"), - ("InvocationsHostServer", "parse_request"), - ("InvocationsWorkflowHostServer", "parse_request"), ], ) -def test_legacy_parser_names_are_not_silently_forwarded_to_sdk(name: str, legacy: str) -> None: +def test_legacy_parser_name_is_not_silently_forwarded_to_sdk(name: str, legacy: str) -> None: host = getattr(hosting, name) source = "workflow" if "Workflow" in name else "agent" values = {source: lambda _: None, "parse_input": lambda _: None, legacy: lambda _: None} diff --git a/python/packages/foundry_hosting/tests/test_invocations.py b/python/packages/foundry_hosting/tests/test_invocations.py index 1b39430d660..5a056a03394 100644 --- a/python/packages/foundry_hosting/tests/test_invocations.py +++ b/python/packages/foundry_hosting/tests/test_invocations.py @@ -667,7 +667,6 @@ def create_agent(request: Request, name: str) -> _FakeAgent: ("parse_input", 42, "parse_input must be a callable"), ("prepare_options", 42, "prepare_options must be a callable"), ("unsupported_options", "discard", "unsupported_options"), - ("legacy_wire_format", True, "legacy_wire_format is no longer a supported host setting"), ], ) def test_rejects_invalid_configuration(self, parameter: str, value: Any, error: str) -> None: @@ -827,7 +826,7 @@ def broken_parser(_request: Request) -> InvocationRun: ) async def test_reserved_options_are_rejected_before_agent_run(self, options: dict[str, Any]) -> None: agent = _make_agent(response_text="ok") - server = InvocationsHostServer(agent) + server = InvocationsHostServer(agent, prepare_options=lambda _request, options: options) with _request_context(session_id="options"): response = await server._handle_invoke( # pyright: ignore[reportPrivateUsage] _make_request({"message": "hi", "options": options}) @@ -870,7 +869,7 @@ def create_agent(*, request: Request) -> _FakeAgent: parse_input=(lambda _request: InvocationRun(messages="hi", options=options, stream=stream)) if source == "parser" else None, - prepare_options=(lambda _request, _options: options) if source == "hook" else None, + prepare_options=lambda _request, parsed_options: options if source == "hook" else parsed_options, ) with _request_context(session_id="unsafe-options"): response = await server._handle_invoke( # pyright: ignore[reportPrivateUsage] @@ -899,6 +898,7 @@ def create_host() -> InvocationsHostServer: agent, agent_session_store_provider=provider, unsupported_options=policy, + prepare_options=lambda _request, options: options, ) server = create_host() @@ -938,7 +938,9 @@ async def test_unsupported_options_policy( self, policy: Literal["ignore", "warn", "error"], stream: bool, caplog: pytest.LogCaptureFixture ) -> None: agent = _NoOptionsAgent() - server = InvocationsHostServer(agent, unsupported_options=policy) + server = InvocationsHostServer( + agent, unsupported_options=policy, prepare_options=lambda _request, options: options + ) with _request_context(session_id="unsupported"): response = await server._handle_invoke( # pyright: ignore[reportPrivateUsage] _make_request({"message": "hello", "options": {"temperature": 0.8}, "stream": stream}) @@ -960,6 +962,7 @@ async def test_factory_options_failure_is_framed_before_first_delta(self) -> Non lambda request: _NoOptionsAgent(), agent_session_store_provider=provider, unsupported_options="error", + prepare_options=lambda _request, options: options, ) with _request_context(session_id="factory-options"): response = await server._handle_invoke( # pyright: ignore[reportPrivateUsage] From bde8bbe9597752fb392be049ee490659572cb475 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 14:36:45 +0100 Subject: [PATCH 47/55] Fix stale Invocations host guard tests --- .../_invocations_agent.py | 10 ++++++---- .../_invocations_workflow.py | 4 ++-- .../tests/foundry_hosting/test_invocations_workflow.py | 10 ++-------- 3 files changed, 10 insertions(+), 14 deletions(-) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py index ed03bd3187f..389ff474ffc 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py @@ -64,11 +64,13 @@ def __init__( Use `InvocationsWorkflowHostServer` for native workflow settings. Raises: - TypeError: If the agent source, parser/hook, or heartbeat type is invalid, or removed, - Responses-only, or native workflow settings are supplied. - ValueError: If the heartbeat interval is nonpositive, raw legacy output requests heartbeats, - or an injected agent has unsupported background or transport defaults. + TypeError: If the agent source, parser/hook, or heartbeat type is invalid, or Responses-only + or native workflow settings are supplied. + ValueError: If the heartbeat interval is nonpositive or an injected agent has unsupported + background or transport defaults. """ + if {"workflow", "checkpoint_store_provider"}.intersection(agent_server_kwargs): + raise TypeError("Use InvocationsWorkflowHostServer for native workflows and checkpoint storage.") super().__init__( agent=agent, openapi_spec=openapi_spec, diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py index c493a018706..1d381f394b7 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py @@ -45,12 +45,12 @@ def __init__( sse_keep_alive_interval_seconds: Positive streaming heartbeat interval. If omitted, use a positive `SSE_KEEPALIVE_INTERVAL`, otherwise disable heartbeats. Not a request/model timeout. **agent_server_kwargs: Additional AgentServer SDK constructor arguments, such as - `asyncapi_spec_json` and `asyncapi_spec_yaml`. Host-owned, removed, and agent-only settings are + `asyncapi_spec_json` and `asyncapi_spec_yaml`. Responses-only and agent-only settings are rejected. Output uses JSON or framed SSE workflow events. Raises: TypeError: If the workflow is not a request-aware factory, the parser or heartbeat type is invalid, - or a removed, Responses-only, or agent-only setting is supplied. + or a Responses-only or agent-only setting is supplied. ValueError: If the heartbeat interval is nonpositive. """ forbidden = { diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_invocations_workflow.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_invocations_workflow.py index 27778381950..8d0de648aa4 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_invocations_workflow.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_invocations_workflow.py @@ -441,17 +441,11 @@ def create(_request: Request) -> Workflow: invalid_agent: Any = object() with pytest.raises(TypeError, match="InvocationsWorkflowHostServer"): InvocationsHostServer(agent=invalid_agent, workflow=create) + with pytest.raises(TypeError, match="InvocationsWorkflowHostServer"): + InvocationsHostServer(agent=invalid_agent, checkpoint_store_provider=lambda _context: None) with pytest.raises(TypeError, match="parse_input"): cast(Any, InvocationsWorkflowHostServer)(workflow=create) - def test_workflow_rejects_removed_legacy_wire_format_setting(self) -> None: - with pytest.raises(TypeError, match="legacy_wire_format is no longer a supported host setting"): - InvocationsWorkflowHostServer( - workflow=lambda _: WorkflowBuilder(name="tickets", start_executor=_TicketExecutor([])).build(), - parse_input=_parse_ticket, - legacy_wire_format=True, - ) - @pytest.mark.parametrize("stream", [False, True]) async def test_parser_must_return_workflow_turn_before_building_or_loading_state(self, stream: bool) -> None: created: list[Request] = [] From db4b065913cabc99b5f5f538a692a40721facc1b Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 14:42:05 +0100 Subject: [PATCH 48/55] Python: Opt in to caller options in Responses hosting --- .../0055-python-foundry-hosting-contracts.md | 7 ++ python/packages/foundry_hosting/README.md | 34 +++-- .../_responses_agent.py | 5 +- .../_responses_workflow.py | 5 +- .../foundry_hosting/test_native_responses.py | 26 +++- .../tests/test_foundry_hosting_imports.py | 9 -- .../foundry_hosting/tests/test_responses.py | 117 ++++++++---------- .../invocations/basic/README.md | 2 + .../responses/basic/README.md | 8 +- 9 files changed, 118 insertions(+), 95 deletions(-) diff --git a/docs/decisions/0055-python-foundry-hosting-contracts.md b/docs/decisions/0055-python-foundry-hosting-contracts.md index aa0022fa7b2..c79c3428ebb 100644 --- a/docs/decisions/0055-python-foundry-hosting-contracts.md +++ b/docs/decisions/0055-python-foundry-hosting-contracts.md @@ -74,6 +74,13 @@ before `prepare_options`. Invocations agent factories receive the Starlette `Req and option preparation. Preserve these protocol-specific timings rather than forcing identical signatures or inventing a shared options-precedence policy. +Caller model-run options are opt-in for Responses agents, Responses workflows, and Invocations agents. +Without `prepare_options`, do not forward caller generation settings; preserve developer defaults and +host-owned storage/background controls. With a hook, forward only its returned, validated mapping. +This does not prevent application code from inspecting the original request. Responses agent factories +see translated options before the hook. Native Responses workflow factories run after the hook and +see its selected options, or an empty option mapping when no hook is configured. + Native workflow factories are request-aware and must allocate fresh workflows, executors, agents, clients, providers, and mutable tools. A new graph wrapper around shared executors is not isolation. Reject known shared execution resources rather than cloning them. This guard cannot prove that arbitrary diff --git a/python/packages/foundry_hosting/README.md b/python/packages/foundry_hosting/README.md index 59d199b3784..864382d8f7f 100644 --- a/python/packages/foundry_hosting/README.md +++ b/python/packages/foundry_hosting/README.md @@ -25,6 +25,13 @@ Rename `HostedResponseRequest` imports and annotations to `ResponsesRequest`, in or a complete batch of pending replies; they are not limited to initial input or raw JSON deserialization. The old parser keywords and request-type name have no compatibility aliases. +**Caller-options migration:** caller model-run options are no longer forwarded by default. +For Responses agents, Responses workflows, and Invocations agents, configure `prepare_options` +to select the options the application accepts. Only the hook's returned, validated mapping is forwarded. +Without a hook, agent/client defaults still apply. Responses agent factories see translated caller +options before the hook; native Responses workflow factories see options after the hook. +The original request remains available to application code. + Agent history/background source literals also change without aliases: | Setting | Previous literal | New literal | @@ -76,7 +83,7 @@ server = ResponsesHostServer( ``` Explicit integer settings reject booleans and non-integers with `TypeError`, and nonpositive values with -`ValueError`. A positive history cap in another history mode raises `ValueError`. Workflow hosts reject +`ValueError`. A positive history cap in another agent history mode emits a warning and is ignored. Workflow hosts reject `max_history_items`, including explicit `None`; they do not use outer transcript history caps. Invocations hosts reject the Responses-only settings `history_source`, `background_source`, `max_history_items`, `shutdown_grace_period_seconds`, and `enable_background_recovery`, even when `None`. @@ -403,7 +410,11 @@ No future SDK version is assumed. Agent background polling without steering is u ### Preparing caller options -Native CreateResponse generation fields become MAF runtime options, notably `max_output_tokens` -> `max_tokens` +Caller model-run options are opt-in. Without `prepare_options`, the host clears the translated option mapping +and does not forward caller generation settings. Agent/client defaults and host-owned storage/background controls +still apply. Application factories can still inspect the original request; this default is not an access restriction. + +Native CreateResponse generation fields are translated to MAF runtime options, notably `max_output_tokens` -> `max_tokens` and `parallel_tool_calls` -> `allow_multiple_tool_calls`. Precedence, from lowest to highest, is: native generation fields, flattened unknown generation fields, generation fields inside a literal `extra_body` mapping, then the `prepare_options` replacement. The OpenAI client normally flattens its `extra_body` into the @@ -413,17 +424,21 @@ A sync or async `prepare_options(request: ResponsesRequest, options: dict[str, A deep copy of this turn's effective caller options. It must return a replacement mapping with string keys; the host deep-copies that result again. Mutating the argument without returning a mapping is invalid. Removing `"model"` lets the developer's unchanged agent/client model default apply, while other caller -settings such as `"temperature"` remain. This works for streaming and non-streaming requests. +settings such as `"temperature"` remain only if the hook returns them. Return an explicit allowlist to limit +caller control, or return the supplied mapping to opt in to all options that pass validation. +This works for streaming and non-streaming requests. Responses agent ordering is translation, factory resolution and configuration checks, hook, then protected-option validation before execution. The factory therefore sees translated options **before** the hook. Invocations agent ordering is parser, hook, protected-option validation, factory, then default validation before entering -the agent. Do not rely on identical HTTP error timing between protocols. Responses workflows retain their -hook before `parse_input`; Invocations workflows have no option hook. +the agent. Do not rely on identical HTTP error timing between protocols. Responses workflows run their hook +before factory resolution and `parse_input`; without a hook their factories see an empty `request.options`, +but can still inspect `request.request`. Invocations workflows have no option hook. Native request-envelope controls such as identity, storage, and continuation fields are not forwarded as -generation options. Putting those controls or agent execution controls inside `extra_body` raises `ValueError` -before the hook; the host does not silently strip them. Hook results also cannot contain host controls, +generation options. Putting those controls inside `extra_body` raises `ValueError` +before the hook; the host does not silently strip them. Agent execution controls can reach the hook for filtering, +but cannot be returned. Hook results also cannot contain host controls, `extra_body`, or execution controls such as `client_kwargs`, `middleware`, `session`, and tool-invocation kwargs. Responses native `instructions` and `tools` remain supported; Invocations agent options additionally reject both. Developer defaults cannot use nested transport controls to bypass storage or background policy. @@ -633,8 +648,9 @@ By default, `POST /invocations` accepts `{"message": "Hi", "options": {}, "strea a sync or async `parse_input(request)` returning a typed `InvocationRun(messages, options, stream)` to accept their own JSON shape and MAF `Message` inputs. A sync or async `prepare_options(request, options)` hook can filter or replace a **copy** of this turn's caller options without changing the agent's `default_options`. It must return a mapping -with string keys. The host rejects reserved platform/session fields, `store`, `extra_body`, and private continuation -fields after the hook; callers cannot select another sandbox or enable downstream service continuation through +with string keys; only the returned, validated options are forwarded. Without a hook, caller model-run options +are suppressed and developer defaults apply. The host rejects reserved platform/session fields, `store`, +`extra_body`, and private continuation fields after the hook; callers cannot select another sandbox or enable downstream service continuation through runtime options. It also rejects agent execution controls: `additional_function_arguments`, `function_invocation_kwargs`, `client_kwargs`, `middleware`, `session`, `tools`, `instructions`, `compaction_strategy`, and `tokenizer`. Trusted tool arguments belong in developer-configured agent defaults or middleware/factories, not in request options or hook output. diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py index 18d9369a6cc..9866b73dfcf 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py @@ -89,7 +89,6 @@ build_response_server_options, is_agent, prepare_response_options, - reject_removed_host_settings, resolve_agent, response_run_options, validate_agent_background_options, @@ -311,7 +310,8 @@ def __init__( DELETE waits for response persistence. Defaults to 10 seconds. enable_background_recovery: Allow eligible provider-background work to recover after shutdown. Defaults to `False`; it does not enable background execution or guarantee exactly-once effects. - prepare_options: Developer hook to remove or replace caller model options for an agent. + prepare_options: Developer hook selecting caller model options after factory resolution. + Only its returned, validated mapping is forwarded. Without a hook, caller options are omitted. unsupported_options: `"warn"` (default), `"error"`, or `"ignore"` when a custom agent cannot accept runtime model options. **kwargs: Additional keyword arguments. @@ -347,7 +347,6 @@ def __init__( ValueError: If the history, background, or unsupported-options policy is invalid. RuntimeError: If the agent configuration conflicts with the selected history or background source. """ - reject_removed_host_settings(kwargs) if "function_approval_store_provider" in kwargs: raise TypeError("Approval state is managed by agent_session_store_provider.") if "store" in kwargs: diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py index 8b54c548085..eb9d74884d0 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py @@ -66,7 +66,6 @@ build_response_server_options, prepare_response_options, prepare_workflow_kwargs, - reject_removed_host_settings, response_run_options, validate_request_options, validate_workflow_source, @@ -357,7 +356,8 @@ def __init__( checkpoint_store_provider: Scoped checkpoint storage. Defaults to `CheckpointStoreProvider`. Native workflow history and pending replies are checkpoint-owned, not agent-session-owned. prepare_options: Sync or async hook receiving the hosted request and a copy of caller model - options before parsing/execution. Return the replacement mapping; hosting validates it. + options before factory resolution and parsing. Return the replacement mapping; hosting validates it. + Without a hook, caller options are omitted. This does not enable inner provider background or service-owned history. allowed_oauth_consent_origins: Optional exact HTTPS origins for consent links. Omission retains safe-HTTPS validation; an empty sequence rejects all origins. @@ -374,7 +374,6 @@ def __init__( agent-only setting is supplied. ValueError: If a supported setting has an invalid value. """ - reject_removed_host_settings(kwargs) forbidden = { "agent", "agent_session_store_provider", diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py index 38f975760bf..8b7c51e1de7 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py @@ -898,7 +898,10 @@ async def start(self, message: str, ctx: WorkflowContext[str, Any]) -> None: assert message["content"][0]["annotations"] == [_expected_url_citation(start_index=4, end_index=10)] -async def test_native_agent_executor_applies_options_without_mutating_defaults_or_double_keywords() -> None: +@pytest.mark.parametrize("forward_options", [False, True]) +async def test_native_agent_executor_applies_options_without_mutating_defaults_or_double_keywords( + forward_options: bool, +) -> None: calls: list[dict[str, Any]] = [] lifecycle: list[str] = [] agents: list[Agent[Any]] = [] @@ -915,14 +918,21 @@ def create(request: ResponsesRequest) -> Workflow: async def parse(request: ResponsesRequest) -> WorkflowTurn[Any]: return WorkflowTurn(input=[Message("user", await request.get_input_text() or "")]) - server = _server(create, parser=parse) + server = _server( + create, + parser=parse, + prepare_options=(lambda _request, options: options) if forward_options else None, + ) first = await _post(server, "one", temperature=0.7, max_output_tokens=12, store=True) assert first["status"] == "completed", first second = await _post(server, "two", temperature=0.4, store=False, call="call-two") assert second["status"] == "completed", second assert [call["options"]["store"] for call in calls] == [False, False] - assert [call["options"]["temperature"] for call in calls] == [0.7, 0.4] - assert calls[0]["options"]["max_tokens"] == 12 + assert [call["options"]["temperature"] for call in calls] == ([0.7, 0.4] if forward_options else [0.2, 0.2]) + if forward_options: + assert calls[0]["options"]["max_tokens"] == 12 + else: + assert all("max_tokens" not in call["options"] for call in calls) assert all( agent.default_options["temperature"] == 0.2 and agent.default_options["store"] is True for agent in agents ) @@ -943,7 +953,11 @@ def create(request: ResponsesRequest) -> Workflow: ) return _build(_RegistryExecutor(agent)) - response = await _post(_server(create, parser=_parse_text), "hello", temperature=0.7) + response = await _post( + _server(create, parser=_parse_text, prepare_options=lambda _request, options: options), + "hello", + temperature=0.7, + ) assert response["status"] == "completed", response assert _texts(response) == ["safe"] @@ -1022,7 +1036,7 @@ def create(request: ResponsesRequest) -> Workflow: async def parse(request: ResponsesRequest) -> WorkflowTurn[Any]: return WorkflowTurn(input=[Message("user", await request.get_input_text() or "")]) - server = _server(create, parser=parse) + server = _server(create, parser=parse, prepare_options=lambda _request, options: options) async with httpx.AsyncClient(transport=httpx.ASGITransport(app=server), base_url="http://test") as client: response = await client.post( "/responses", diff --git a/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py b/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py index f3c9431ef94..0435061325d 100644 --- a/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py +++ b/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py @@ -184,15 +184,6 @@ def test_legacy_responses_request_name_is_not_exported() -> None: hosting.__getattr__("HostedResponseRequest") -def test_responses_workflow_host_rejects_removed_options() -> None: - with pytest.raises(TypeError, match="options is no longer a supported host setting"): - cast(Any, hosting.ResponsesWorkflowHostServer)( - workflow=lambda _: None, - parse_input=lambda _: None, - options=None, - ) - - def test_responses_workflow_host_rejects_agent_history_limit_even_when_none() -> None: with ( patch("azure.ai.agentserver.responses.hosting.ResponsesAgentServerHost.__init__") as initialize, diff --git a/python/packages/foundry_hosting/tests/test_responses.py b/python/packages/foundry_hosting/tests/test_responses.py index 8bdee7b7bce..68070069bed 100644 --- a/python/packages/foundry_hosting/tests/test_responses.py +++ b/python/packages/foundry_hosting/tests/test_responses.py @@ -17,7 +17,6 @@ import os import uuid from collections.abc import AsyncGenerator, AsyncIterator, Awaitable, Callable, Generator, Mapping, Sequence -from concurrent.futures import ThreadPoolExecutor from contextlib import suppress from dataclasses import dataclass from importlib import import_module @@ -1665,30 +1664,6 @@ def test_stringify_mcp_output_extracts_only_text_content_mappings(self) -> None: class TestResponsesHostServerInit: - @pytest.mark.parametrize( - "name", - [ - "options", - "default_fetch_history_count", - "default_model", - "create_span_hook", - "additional_server_version", - "steerable_conversations", - "resilient_background", - ], - ) - def test_removed_host_setting_fails_before_sdk_or_agent_mutation(self, name: str) -> None: - agent = _make_agent() - kwargs: dict[str, Any] = {name: None} - with ( - patch("azure.ai.agentserver.responses.hosting.ResponsesAgentServerHost.__init__") as initialize, - pytest.raises(TypeError, match=name), - ): - ResponsesHostServer(agent, **kwargs) - initialize.assert_not_called() - assert agent.context_providers == [] - assert agent.default_options == {} - @pytest.mark.parametrize( ("setting", "value", "error"), [ @@ -1720,8 +1695,11 @@ def test_history_limit_is_an_explicit_host_managed_override(self) -> None: ResponsesServerOptions().default_fetch_history_count ) assert limited._host_options.default_fetch_history_count == 3 # pyright: ignore[reportPrivateUsage] - with pytest.raises(ValueError, match="host_managed"): - _make_server(_make_agent(), history_source="agent_managed", max_history_items=3) + with pytest.warns(UserWarning, match="max_history_items is ignored"): + ignored = _make_server(_make_agent(), history_source="agent_managed", max_history_items=3) + assert ignored._host_options.default_fetch_history_count == ( # pyright: ignore[reportPrivateUsage] + ResponsesServerOptions().default_fetch_history_count + ) @pytest.mark.parametrize("env", [None, "0", "3"]) @pytest.mark.parametrize("explicit", [None, 5]) @@ -1892,30 +1870,6 @@ def test_init_rejects_resilient_background_for_non_workflow_agent(self, tmp_path enable_background_recovery=True, ) - def test_steering_rejected_before_enabling_task_manager_or_starting_host(self) -> None: - agent_factory = MagicMock() - - def construct(_turn: int) -> str: - with pytest.raises(TypeError, match="options is no longer a supported host setting") as error: - ResponsesHostServer( - agent=agent_factory, - options=ResponsesServerOptions(steerable_conversations=True), - ) - return str(error.value) - - with ( - patch("azure.ai.agentserver.core.tasks.set_resilient_tasks_enabled") as enable, - patch("agent_framework_foundry_hosting._responses_agent.ResponsesAgentServerHost.__init__") as base_init, - ThreadPoolExecutor(max_workers=12) as executor, - ): - failures = list(executor.map(construct, range(24))) - - assert len(failures) == 24 - assert all("options is no longer a supported host setting" in failure for failure in failures) - enable.assert_not_called() - base_init.assert_not_called() - agent_factory.assert_not_called() - async def test_non_steerable_background_still_uses_outer_response_id(self) -> None: agent = _make_agent( stream_updates=[AgentResponseUpdate(contents=[Content.from_text("finished")], role="assistant")] @@ -1937,17 +1891,10 @@ async def test_non_steerable_background_still_uses_outer_response_id(self) -> No assert final.json()["id"] == response_id assert "finished" in str(final.json()["output"]) - def test_provider_background_rejects_steering_and_wrong_history_source(self) -> None: + def test_provider_background_rejects_wrong_history_source(self) -> None: agent = Agent(client=_ServiceStorageRecordingClient()) with pytest.raises(ValueError, match="history_source='inference_service'"): _make_server(agent, background_source="inference_service") - with pytest.raises(TypeError, match="options is no longer a supported host setting"): - _make_server( - agent, - history_source="inference_service", - background_source="inference_service", - options=ResponsesServerOptions(steerable_conversations=True), - ) @pytest.mark.parametrize("old_store", [None, InMemoryResponseProvider()]) @pytest.mark.parametrize("with_response_store", [False, True]) @@ -2576,6 +2523,35 @@ async def test_store_false_agent_continuation_fails_instead_of_using_service_his assert "store=false cannot continue agent-managed downstream service history" in _failure_message(events) assert len(client.calls) == 1 + @pytest.mark.parametrize("stream", [False, True]) + async def test_caller_options_without_hook_preserve_agent_defaults(self, stream: bool) -> None: + client = _RecordingHistoryClient() + agent = Agent(client=client, default_options=OpenAIChatOptions(temperature=0.2, max_tokens=256)) + defaults = dict(agent.default_options) + server = _make_server(agent) + + response = await _post_json( + server, + { + "input": "hello", + "stream": stream, + "temperature": 0.8, + "max_output_tokens": 300, + "extra_body": {"top_p": 0.4}, + }, + ) + + assert response.status_code == 200 + if stream: + assert _sse_event_types(_parse_sse_events(response.text))[-1] == "response.completed" + else: + assert response.json()["status"] == "completed" + assert len(client.options) == 1 + assert client.options[0]["temperature"] == 0.2 + assert client.options[0]["max_tokens"] == 256 + assert "top_p" not in client.options[0] + assert agent.default_options == defaults + async def test_extra_options_overlay_then_developer_hook_preserves_defaults(self) -> None: client = _RecordingHistoryClient() agent = Agent(client=client, default_options=OpenAIChatOptions(temperature=0.2, max_tokens=256)) @@ -2670,7 +2646,7 @@ def handle_request(request: Any) -> Any: max_retries=0, ) as openai: agent = Agent(client=OpenAIChatClient(model="test-model", async_client=openai)) - server = _make_server(agent) + server = _make_server(agent, prepare_options=lambda _request, options: options) rejected = await _post_json( server, {"input": "unsafe", "store": False, "extra_body": {"extra_body": {"store": True}}}, @@ -2702,7 +2678,12 @@ def handle_request(request: Any) -> Any: async def test_unsupported_options_policy_rejects_custom_agent(self) -> None: agent = _StrictCustomAgent() - server = _make_server(agent, history_source="agent_managed", unsupported_options="error") + server = _make_server( + agent, + history_source="agent_managed", + unsupported_options="error", + prepare_options=lambda _request, options: options, + ) response = await _post_json(server, {"input": "hello", "temperature": 0.8}) assert response.json()["status"] == "failed" @@ -2714,7 +2695,12 @@ async def test_custom_agent_unsupported_options_warning_policy( self, policy: str, warn: bool, caplog: pytest.LogCaptureFixture ) -> None: agent = _StrictCustomAgent() - server = _make_server(agent, history_source="agent_managed", unsupported_options=policy) + server = _make_server( + agent, + history_source="agent_managed", + unsupported_options=policy, + prepare_options=lambda _request, options: options, + ) with caplog.at_level(logging.WARNING): response = await _post(server, temperature=0.5) @@ -2888,6 +2874,7 @@ async def run( background_source="inference_service", enable_background_recovery=True, response_store=FileResponseStore(storage_dir=tmp_path), + prepare_options=lambda _request, options: options, ) request = CreateResponse(input="hello", store=True, background=True, temperature=0.35) context = ResponseContext(response_id="outer-response", mode_flags=MagicMock()) @@ -3123,6 +3110,7 @@ def make_host() -> ResponsesHostServer: background_source="inference_service", enable_background_recovery=True, response_store=FileResponseStore(storage_dir=tmp_path), + prepare_options=lambda _request, options: options, ) request = CreateResponse(input="hello", store=True, background=True, temperature=0.25) @@ -3399,6 +3387,7 @@ async def set(self, session_id: str, session: AgentSession) -> None: background_source="inference_service", enable_background_recovery=True, response_store=FileResponseStore(storage_dir=tmp_path), + prepare_options=lambda _request, options: options, ) context = ResponseContext(response_id="outer-tool-response", mode_flags=MagicMock()) request = CreateResponse(input="email bob", store=True, background=True, temperature=0.42) @@ -5465,7 +5454,7 @@ async def test_chat_options_forwarded(self) -> None: response=AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("ok")])]), raw_agent=True, ) - server = _make_server(agent) + server = _make_server(agent, prepare_options=lambda _request, options: options) resp = await _post( server, stream=False, @@ -5507,7 +5496,7 @@ async def test_chat_options_forwarded(self) -> None: stream_updates=[AgentResponseUpdate(contents=[Content.from_text("ok")], role="assistant")], raw_agent=True, ) - server = _make_server(agent) + server = _make_server(agent, prepare_options=lambda _request, options: options) resp = await _post( server, stream=True, diff --git a/python/samples/04-hosting/foundry-hosted-agents/invocations/basic/README.md b/python/samples/04-hosting/foundry-hosted-agents/invocations/basic/README.md index 657ffaaea9c..ff1f08419d0 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/invocations/basic/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/invocations/basic/README.md @@ -7,6 +7,8 @@ Invocations protocol. The sample accepts application JSON with a `prompt` field rather than the host's default `message` field. Its `parse_input` callback returns `InvocationRun(messages, options, stream)`, and `prepare_options` allows only `temperature` and `max_tokens` from the caller. +Only the hook's returned, validated mapping is forwarded. Without a hook, caller +model-run options are suppressed and the agent/client defaults apply. The host also rejects platform IDs, `store`, and private continuation options even if a hook tries to return them. The agent keeps `store=False` as a developer default; caller options cannot enable service-managed history. diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/basic/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/basic/README.md index 6ed7d1a8730..33055b69bd7 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/basic/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/basic/README.md @@ -77,6 +77,10 @@ the existing thread may have changed even if its outer response did not complete ## Options and compatibility +Caller generation options are suppressed unless the host has a `prepare_options` hook. +Without a hook, the agent/client defaults apply. With a hook, only its returned, validated mapping +is forwarded. The options sample explicitly opts in; the other basic hosts do not. + Native CreateResponse generation fields become MAF run options (`max_output_tokens` becomes `max_tokens` and `parallel_tool_calls` becomes `allow_multiple_tool_calls`). Flattened unknown generation fields override those translated fields; generation fields inside a literal `extra_body` mapping override both. The developer's @@ -94,7 +98,9 @@ curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" The client uses the developer's model with `temperature=0.3` and `max_tokens=150`, not the caller's model. If the caller omits a token limit, the agent's `max_tokens=256` default applies. -Responses factories see translated caller options before the hook. Platform IDs, storage flags, and private +Responses agent factories see translated caller options before the hook. Native Responses workflow factories +run after the hook and see its selected options, or an empty mapping without a hook; the original request +is still available through `request.request`. Platform IDs, storage flags, and private continuation tokens are never caller model options; the hook cannot add them back. Host controls inside `extra_body` fail before the hook, rather than being silently stripped. See [explicit host configuration](../../../../../packages/foundry_hosting/README.md#explicit-host-configuration) From 7d92c286769bf8a90d252ef6426d04f0c5e9dc2a Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 14:44:50 +0100 Subject: [PATCH 49/55] Python: Keep Responses removed-setting guard with opt-in options --- .../_responses_agent.py | 2 + .../_responses_shared.py | 18 ++++++++ .../_responses_workflow.py | 2 + .../tests/test_foundry_hosting_imports.py | 14 ++++++ .../foundry_hosting/tests/test_responses.py | 45 ++++++++++++++++++- 5 files changed, 80 insertions(+), 1 deletion(-) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py index 9866b73dfcf..b3d5fcd3851 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py @@ -75,6 +75,7 @@ _OutputItemTracker, # pyright: ignore[reportPrivateUsage] _PublicResponseFailure, # pyright: ignore[reportPrivateUsage] _reject_busy_conversation, # pyright: ignore[reportPrivateUsage] + _reject_removed_host_settings, # pyright: ignore[reportPrivateUsage] _set_agent_session, # pyright: ignore[reportPrivateUsage] _SignalledIterator, # pyright: ignore[reportPrivateUsage] consent_url_from_error, @@ -347,6 +348,7 @@ def __init__( ValueError: If the history, background, or unsupported-options policy is invalid. RuntimeError: If the agent configuration conflicts with the selected history or background source. """ + _reject_removed_host_settings(kwargs) if "function_approval_store_provider" in kwargs: raise TypeError("Approval state is managed by agent_session_store_provider.") if "store" in kwargs: diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py index 29b29c4e166..40e7212eadd 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py @@ -356,6 +356,24 @@ def _openai_value(content: Content, key: str, *legacy_keys: str, default: Any = return default +_REMOVED_RESPONSES_HOST_SETTINGS = { + "options": "Use the supported first-class host parameters instead of ResponsesServerOptions.", + "default_fetch_history_count": "Use max_history_items on a host-managed Responses agent.", + "default_model": "Configure inference defaults on the agent or client.", + "create_span_hook": "Use Agent Framework observability instead.", + "additional_server_version": "Custom server version stamping is not supported.", + "steerable_conversations": "Conversation steering is not supported.", + "resilient_background": "Use enable_background_recovery on a Responses host.", +} + + +def _reject_removed_host_settings(settings: Mapping[str, Any]) -> None: # pyright: ignore[reportUnusedFunction] + """Reject SDK settings that the first-class Responses host parameters replace, before any side effects.""" + for name, message in _REMOVED_RESPONSES_HOST_SETTINGS.items(): + if name in settings: + raise TypeError(f"{name} is no longer a supported host setting. {message}") + + def _reject_busy_conversation(session: AgentSession) -> None: # pyright: ignore[reportUnusedFunction] if session.state.get(_HOSTED_CONVERSATION_CLAIM_KEY) is not None: raise _PublicResponseFailure( diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py index eb9d74884d0..c1e5a8348e4 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py @@ -53,6 +53,7 @@ _item_to_message, # pyright: ignore[reportPrivateUsage] _normalize_allowed_oauth_consent_origins, # pyright: ignore[reportPrivateUsage] _OutputItemTracker, # pyright: ignore[reportPrivateUsage] + _reject_removed_host_settings, # pyright: ignore[reportPrivateUsage] _request_without_reserved_metadata, # pyright: ignore[reportPrivateUsage] _SignalledIterator, # pyright: ignore[reportPrivateUsage] ) @@ -374,6 +375,7 @@ def __init__( agent-only setting is supplied. ValueError: If a supported setting has an invalid value. """ + _reject_removed_host_settings(kwargs) forbidden = { "agent", "agent_session_store_provider", diff --git a/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py b/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py index 0435061325d..ec67501c73b 100644 --- a/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py +++ b/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py @@ -184,6 +184,20 @@ def test_legacy_responses_request_name_is_not_exported() -> None: hosting.__getattr__("HostedResponseRequest") +@pytest.mark.parametrize("name", ["options", "resilient_background", "steerable_conversations"]) +def test_responses_workflow_host_rejects_removed_settings_before_sdk(name: str) -> None: + with ( + patch("azure.ai.agentserver.responses.hosting.ResponsesAgentServerHost.__init__") as initialize, + pytest.raises(TypeError, match=f"{name} is no longer a supported host setting"), + ): + cast(Any, hosting.ResponsesWorkflowHostServer)( + workflow=lambda _: None, + parse_input=lambda _: None, + **{name: None}, + ) + initialize.assert_not_called() + + def test_responses_workflow_host_rejects_agent_history_limit_even_when_none() -> None: with ( patch("azure.ai.agentserver.responses.hosting.ResponsesAgentServerHost.__init__") as initialize, diff --git a/python/packages/foundry_hosting/tests/test_responses.py b/python/packages/foundry_hosting/tests/test_responses.py index 68070069bed..25977bffb92 100644 --- a/python/packages/foundry_hosting/tests/test_responses.py +++ b/python/packages/foundry_hosting/tests/test_responses.py @@ -1664,6 +1664,42 @@ def test_stringify_mcp_output_extracts_only_text_content_mappings(self) -> None: class TestResponsesHostServerInit: + @pytest.mark.parametrize( + "name", + [ + "options", + "default_fetch_history_count", + "default_model", + "create_span_hook", + "additional_server_version", + "steerable_conversations", + "resilient_background", + ], + ) + def test_removed_host_setting_fails_before_sdk_or_agent_mutation(self, name: str) -> None: + agent = _make_agent() + kwargs: dict[str, Any] = {name: None} + with ( + patch("azure.ai.agentserver.responses.hosting.ResponsesAgentServerHost.__init__") as initialize, + pytest.raises(TypeError, match=name), + ): + ResponsesHostServer(agent, **kwargs) + initialize.assert_not_called() + assert agent.context_providers == [] + assert agent.default_options == {} + + def test_steering_rejected_before_enabling_task_manager_or_starting_host(self) -> None: + agent_factory = MagicMock() + with ( + patch("azure.ai.agentserver.core.tasks.set_resilient_tasks_enabled") as enable, + patch("agent_framework_foundry_hosting._responses_agent.ResponsesAgentServerHost.__init__") as base_init, + pytest.raises(TypeError, match="options is no longer a supported host setting"), + ): + ResponsesHostServer(agent=agent_factory, options=ResponsesServerOptions(steerable_conversations=True)) + enable.assert_not_called() + base_init.assert_not_called() + agent_factory.assert_not_called() + @pytest.mark.parametrize( ("setting", "value", "error"), [ @@ -1891,10 +1927,17 @@ async def test_non_steerable_background_still_uses_outer_response_id(self) -> No assert final.json()["id"] == response_id assert "finished" in str(final.json()["output"]) - def test_provider_background_rejects_wrong_history_source(self) -> None: + def test_provider_background_rejects_steering_and_wrong_history_source(self) -> None: agent = Agent(client=_ServiceStorageRecordingClient()) with pytest.raises(ValueError, match="history_source='inference_service'"): _make_server(agent, background_source="inference_service") + with pytest.raises(TypeError, match="options is no longer a supported host setting"): + _make_server( + agent, + history_source="inference_service", + background_source="inference_service", + options=ResponsesServerOptions(steerable_conversations=True), + ) @pytest.mark.parametrize("old_store", [None, InMemoryResponseProvider()]) @pytest.mark.parametrize("with_response_store", [False, True]) From df055c7100eccb0b42c89b56c179315c1b8fff5f Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 14:46:09 +0100 Subject: [PATCH 50/55] Revert "Python: Keep Responses removed-setting guard with opt-in options" This reverts commit 7d92c286769bf8a90d252ef6426d04f0c5e9dc2a. --- .../_responses_agent.py | 2 - .../_responses_shared.py | 18 -------- .../_responses_workflow.py | 2 - .../tests/test_foundry_hosting_imports.py | 14 ------ .../foundry_hosting/tests/test_responses.py | 45 +------------------ 5 files changed, 1 insertion(+), 80 deletions(-) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py index b3d5fcd3851..9866b73dfcf 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py @@ -75,7 +75,6 @@ _OutputItemTracker, # pyright: ignore[reportPrivateUsage] _PublicResponseFailure, # pyright: ignore[reportPrivateUsage] _reject_busy_conversation, # pyright: ignore[reportPrivateUsage] - _reject_removed_host_settings, # pyright: ignore[reportPrivateUsage] _set_agent_session, # pyright: ignore[reportPrivateUsage] _SignalledIterator, # pyright: ignore[reportPrivateUsage] consent_url_from_error, @@ -348,7 +347,6 @@ def __init__( ValueError: If the history, background, or unsupported-options policy is invalid. RuntimeError: If the agent configuration conflicts with the selected history or background source. """ - _reject_removed_host_settings(kwargs) if "function_approval_store_provider" in kwargs: raise TypeError("Approval state is managed by agent_session_store_provider.") if "store" in kwargs: diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py index 40e7212eadd..29b29c4e166 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py @@ -356,24 +356,6 @@ def _openai_value(content: Content, key: str, *legacy_keys: str, default: Any = return default -_REMOVED_RESPONSES_HOST_SETTINGS = { - "options": "Use the supported first-class host parameters instead of ResponsesServerOptions.", - "default_fetch_history_count": "Use max_history_items on a host-managed Responses agent.", - "default_model": "Configure inference defaults on the agent or client.", - "create_span_hook": "Use Agent Framework observability instead.", - "additional_server_version": "Custom server version stamping is not supported.", - "steerable_conversations": "Conversation steering is not supported.", - "resilient_background": "Use enable_background_recovery on a Responses host.", -} - - -def _reject_removed_host_settings(settings: Mapping[str, Any]) -> None: # pyright: ignore[reportUnusedFunction] - """Reject SDK settings that the first-class Responses host parameters replace, before any side effects.""" - for name, message in _REMOVED_RESPONSES_HOST_SETTINGS.items(): - if name in settings: - raise TypeError(f"{name} is no longer a supported host setting. {message}") - - def _reject_busy_conversation(session: AgentSession) -> None: # pyright: ignore[reportUnusedFunction] if session.state.get(_HOSTED_CONVERSATION_CLAIM_KEY) is not None: raise _PublicResponseFailure( diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py index c1e5a8348e4..eb9d74884d0 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py @@ -53,7 +53,6 @@ _item_to_message, # pyright: ignore[reportPrivateUsage] _normalize_allowed_oauth_consent_origins, # pyright: ignore[reportPrivateUsage] _OutputItemTracker, # pyright: ignore[reportPrivateUsage] - _reject_removed_host_settings, # pyright: ignore[reportPrivateUsage] _request_without_reserved_metadata, # pyright: ignore[reportPrivateUsage] _SignalledIterator, # pyright: ignore[reportPrivateUsage] ) @@ -375,7 +374,6 @@ def __init__( agent-only setting is supplied. ValueError: If a supported setting has an invalid value. """ - _reject_removed_host_settings(kwargs) forbidden = { "agent", "agent_session_store_provider", diff --git a/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py b/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py index ec67501c73b..0435061325d 100644 --- a/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py +++ b/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py @@ -184,20 +184,6 @@ def test_legacy_responses_request_name_is_not_exported() -> None: hosting.__getattr__("HostedResponseRequest") -@pytest.mark.parametrize("name", ["options", "resilient_background", "steerable_conversations"]) -def test_responses_workflow_host_rejects_removed_settings_before_sdk(name: str) -> None: - with ( - patch("azure.ai.agentserver.responses.hosting.ResponsesAgentServerHost.__init__") as initialize, - pytest.raises(TypeError, match=f"{name} is no longer a supported host setting"), - ): - cast(Any, hosting.ResponsesWorkflowHostServer)( - workflow=lambda _: None, - parse_input=lambda _: None, - **{name: None}, - ) - initialize.assert_not_called() - - def test_responses_workflow_host_rejects_agent_history_limit_even_when_none() -> None: with ( patch("azure.ai.agentserver.responses.hosting.ResponsesAgentServerHost.__init__") as initialize, diff --git a/python/packages/foundry_hosting/tests/test_responses.py b/python/packages/foundry_hosting/tests/test_responses.py index 25977bffb92..68070069bed 100644 --- a/python/packages/foundry_hosting/tests/test_responses.py +++ b/python/packages/foundry_hosting/tests/test_responses.py @@ -1664,42 +1664,6 @@ def test_stringify_mcp_output_extracts_only_text_content_mappings(self) -> None: class TestResponsesHostServerInit: - @pytest.mark.parametrize( - "name", - [ - "options", - "default_fetch_history_count", - "default_model", - "create_span_hook", - "additional_server_version", - "steerable_conversations", - "resilient_background", - ], - ) - def test_removed_host_setting_fails_before_sdk_or_agent_mutation(self, name: str) -> None: - agent = _make_agent() - kwargs: dict[str, Any] = {name: None} - with ( - patch("azure.ai.agentserver.responses.hosting.ResponsesAgentServerHost.__init__") as initialize, - pytest.raises(TypeError, match=name), - ): - ResponsesHostServer(agent, **kwargs) - initialize.assert_not_called() - assert agent.context_providers == [] - assert agent.default_options == {} - - def test_steering_rejected_before_enabling_task_manager_or_starting_host(self) -> None: - agent_factory = MagicMock() - with ( - patch("azure.ai.agentserver.core.tasks.set_resilient_tasks_enabled") as enable, - patch("agent_framework_foundry_hosting._responses_agent.ResponsesAgentServerHost.__init__") as base_init, - pytest.raises(TypeError, match="options is no longer a supported host setting"), - ): - ResponsesHostServer(agent=agent_factory, options=ResponsesServerOptions(steerable_conversations=True)) - enable.assert_not_called() - base_init.assert_not_called() - agent_factory.assert_not_called() - @pytest.mark.parametrize( ("setting", "value", "error"), [ @@ -1927,17 +1891,10 @@ async def test_non_steerable_background_still_uses_outer_response_id(self) -> No assert final.json()["id"] == response_id assert "finished" in str(final.json()["output"]) - def test_provider_background_rejects_steering_and_wrong_history_source(self) -> None: + def test_provider_background_rejects_wrong_history_source(self) -> None: agent = Agent(client=_ServiceStorageRecordingClient()) with pytest.raises(ValueError, match="history_source='inference_service'"): _make_server(agent, background_source="inference_service") - with pytest.raises(TypeError, match="options is no longer a supported host setting"): - _make_server( - agent, - history_source="inference_service", - background_source="inference_service", - options=ResponsesServerOptions(steerable_conversations=True), - ) @pytest.mark.parametrize("old_store", [None, InMemoryResponseProvider()]) @pytest.mark.parametrize("with_response_store", [False, True]) From e357eac1354380d679ab288ec461301717553323 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 15:25:13 +0100 Subject: [PATCH 51/55] Python: pass Invocations hook background through without middleware guard --- .../_invocations_agent.py | 2 + .../_invocations_shared.py | 7 +- .../_shared.py | 64 ++----------- .../foundry_hosting/background_helpers.py | 12 --- .../test_background_middleware.py | 92 +------------------ .../foundry_hosting/test_host_options.py | 29 ++++++ 6 files changed, 45 insertions(+), 161 deletions(-) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py index 389ff474ffc..83f6745feec 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py @@ -54,6 +54,8 @@ def __init__( options. Return the replacement mapping. Hosting validates protected fields after the hook and before resolving the factory, unlike Responses factories which run before the hook. Defaults are not mutated. + Invocations has no outer background mode, so hosting never sets `background`; + a `background` value returned by the hook is passed through as the application's choice. unsupported_options: Policy for agents without runtime options: `"warn"`, `"ignore"`, or `"error"`. sse_keep_alive_interval_seconds: Positive streaming heartbeat interval. If omitted, use a positive `SSE_KEEPALIVE_INTERVAL`, otherwise disable heartbeats. Not a request/model timeout. diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py index a674e4fc8a6..46b3be9c6f4 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py @@ -57,7 +57,6 @@ WorkflowResolver, WorkflowSource, WorkflowTurn, - foreground_agent_run_kwargs, is_agent, resolve_agent, validate_agent_background_options, @@ -566,7 +565,7 @@ async def _options(self, request: Request, parsed: InvocationRun) -> dict[str, A reserved = _AGENT_CONTROLLED_FIELDS.intersection(options) if reserved: raise ValueError(f"Invocations options cannot set agent-controlled fields: {', '.join(sorted(reserved))}.") - validate_request_options(options) + validate_request_options(options, allow_background=True) return options def _agent_kwargs(self, agent: SupportsAgentRun, options: dict[str, Any]) -> dict[str, Any]: @@ -629,7 +628,7 @@ async def stream_response() -> AsyncGenerator[str]: try: lock = self._session_locks.setdefault(partition_key, asyncio.Lock()) async with lock, self._request_agent(request) as agent: - run_kwargs = {**self._agent_kwargs(agent, options), **foreground_agent_run_kwargs(agent)} + run_kwargs = self._agent_kwargs(agent, options) async with self._request_session(partition_key, context, hosted_scope=hosted_scope) as session: stream = agent.run(parsed.messages, session=session, stream=True, **run_kwargs) completed = False @@ -678,7 +677,7 @@ async def stream_response() -> AsyncGenerator[str]: try: lock = self._session_locks.setdefault(partition_key, asyncio.Lock()) async with lock, self._request_agent(request) as agent: - run_kwargs = {**self._agent_kwargs(agent, options), **foreground_agent_run_kwargs(agent)} + run_kwargs = self._agent_kwargs(agent, options) async with self._request_session(partition_key, context, hosted_scope=hosted_scope) as session: response = await agent.run(parsed.messages, session=session, **run_kwargs) return JSONResponse({"response": response.text}) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py index dbe4e203211..9564fc7702b 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py @@ -20,12 +20,8 @@ AgentContext, AgentExecutor, AgentMiddleware, - AgentMiddlewareLayer, AgentResponse, AgentRunInputs, - ChatContext, - ChatMiddleware, - ChatMiddlewareLayer, Content, FunctionTool, HistoryProvider, @@ -348,11 +344,17 @@ async def response_input_messages(request: ResponsesRequest) -> list[Message]: return await _items_to_messages(await request.get_input_items(), approval_storage=None) -def validate_request_options(options: Mapping[str, Any]) -> None: - """Keep hosting identity, storage decisions, and private continuation out of model options.""" +def validate_request_options(options: Mapping[str, Any], *, allow_background: bool = False) -> None: + """Keep hosting identity, storage decisions, and private continuation out of model options. + + With ``allow_background``, a ``background`` value set by the application's + options hook is passed to the agent unchanged; the application owns that choice. + """ if not isinstance(options, Mapping) or any(not isinstance(key, str) for key in options): raise TypeError("Run options must be a mapping with string keys.") - reserved = (_HOST_CONTROLLED_FIELDS | _RUN_CONTROLLED_FIELDS).intersection(options) + reserved = set((_HOST_CONTROLLED_FIELDS | _RUN_CONTROLLED_FIELDS).intersection(options)) + if allow_background: + reserved.discard("background") if reserved: raise ValueError(f"prepare_options cannot set host-controlled fields: {', '.join(sorted(reserved))}.") @@ -391,50 +393,6 @@ def validate_provider_background_options(options: Mapping[str, Any], *, provider raise ValueError("Provider extra_body cannot set host-controlled fields: background.") -class _ForegroundChatOptions(ChatMiddleware): - async def process(self, context: ChatContext, call_next: Callable[[], Awaitable[None]]) -> None: - validate_provider_background_options(context.options or {}, provider_background=False) - validate_provider_background_options(context.kwargs, provider_background=False) - await call_next() - - -_FOREGROUND_CHAT_OPTIONS = _ForegroundChatOptions() - - -def _append_foreground_chat_options(agent: SupportsAgentRun, client_kwargs: dict[str, Any]) -> None: - if not isinstance(agent, RawAgent) or not isinstance(cast(RawAgent[Any], agent).client, ChatMiddlewareLayer): - return - middleware = client_kwargs.get("middleware", ()) - if not isinstance(middleware, Sequence) or isinstance(middleware, (str, bytes)): - raise TypeError("Client middleware must be a sequence.") - client_kwargs["middleware"] = [*middleware, _FOREGROUND_CHAT_OPTIONS] - - -class _ForegroundAgentOptions(AgentMiddleware): - async def process(self, context: AgentContext, call_next: Callable[[], Awaitable[None]]) -> None: - validate_agent_background_options(context.agent, provider_background=False) - validate_provider_background_options(context.options or {}, provider_background=False) - validate_provider_background_options(context.client_kwargs, provider_background=False) - _append_foreground_chat_options(context.agent, context.client_kwargs) - await call_next() - - -_FOREGROUND_AGENT_OPTIONS = _ForegroundAgentOptions() - - -def foreground_agent_run_kwargs(agent: SupportsAgentRun) -> dict[str, Any]: - """Guard ordinary agent and chat middleware using request-local run arguments. - - Custom clients and context-provider-contributed chat middleware must not - enable provider background internally; they have no final hosting hook. - """ - if isinstance(agent, AgentMiddlewareLayer): - return {"middleware": [_FOREGROUND_AGENT_OPTIONS]} - kwargs: dict[str, Any] = {} - _append_foreground_chat_options(agent, kwargs) - return {"client_kwargs": kwargs} if kwargs else {} - - def validate_default_transport_options(defaults: Mapping[str, Any], *, allow_agent_store: bool) -> None: """Reject transport overrides that would bypass the host's inner storage and identity decisions.""" extra_body = defaults.get("extra_body") @@ -608,7 +566,6 @@ async def process(self, context: AgentContext, call_next: Callable[[], Awaitable "user_id": self.scope.user_id, "call_id": self.scope.call_id, } - _append_foreground_chat_options(context.agent, context.client_kwargs) def check_result(result: AgentResponse[Any]) -> None: if context.session is not None and context.session.service_session_id is not None: @@ -723,9 +680,6 @@ def validate_values(value: Any) -> dict[str, Any]: "RawAgent workflow generation overrides must be materialized in the fresh factory defaults." ) values.pop("options", None) - if isinstance(agent.client, ChatMiddlewareLayer): - # Run kwargs are checkpointed; install policy on the fresh factory-owned client instead. - agent.client.chat_middleware = [*(agent.client.chat_middleware or ()), _FOREGROUND_CHAT_OPTIONS] global_functions = validate_values(functions.get("global_kwargs", {})) specific_functions = { key: validate_values(value) for key, value in cast(dict[str, Any], functions.get("executor_kwargs", {})).items() diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/background_helpers.py b/python/packages/foundry_hosting/tests/foundry_hosting/background_helpers.py index 193e859fe10..27cc68a7495 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/background_helpers.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/background_helpers.py @@ -66,15 +66,3 @@ def factory(self, *, request: Request) -> Agent[Any] | RawAgent[Any]: def workflow(self, request: Request) -> Workflow: return WorkflowBuilder(start_executor=self.agent).build() - - -class AgentChatCallbacks(BackgroundCallbacks): - def __init__(self) -> None: - super().__init__(source="none", location="options", injected={"background": True}) - self.agent = Agent(client=self.client, middleware=[self.inject_chat]) - - -class ReplacedMiddlewareCallbacks(BackgroundCallbacks): - async def inject_agent(self, context: AgentContext, call_next: Callable[[], Awaitable[None]]) -> None: - context.client_kwargs["middleware"] = (self.inject_chat,) - await call_next() diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_background_middleware.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_background_middleware.py index 8b16cbd4287..e78ac4f1449 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_background_middleware.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_background_middleware.py @@ -1,6 +1,6 @@ # Copyright (c) Microsoft. All rights reserved. -"""Check provider-background options after ordinary agent and chat middleware.""" +"""Check provider-background validators and native-workflow middleware boundaries.""" from __future__ import annotations @@ -8,16 +8,13 @@ import httpx import pytest -from agent_framework import RawAgent from agent_framework_foundry_hosting import InvocationsHostServer, InvocationsWorkflowHostServer, WorkflowTurn from agent_framework_foundry_hosting._shared import ( - foreground_agent_run_kwargs, validate_provider_background_options, ) -from .background_helpers import AgentChatCallbacks, BackgroundCallbacks, ReplacedMiddlewareCallbacks -from .options_helpers import OptionsClient +from .background_helpers import BackgroundCallbacks @pytest.mark.parametrize("provider_background", [False, True]) @@ -45,61 +42,6 @@ def test_pure_validator_rejects_all_nested_background(provider_background: bool, ) -@pytest.mark.parametrize("workflow", [False, True]) -@pytest.mark.parametrize("stream", [False, True]) -@pytest.mark.parametrize("source", ["agent", "chat"]) -@pytest.mark.parametrize("location", ["options", "kwargs"]) -@pytest.mark.parametrize("injected", [{"background": True}, {"extra_body": {"background": True}}]) -async def test_middleware_background_is_rejected_before_provider( - workflow: bool, stream: bool, source: str, location: str, injected: dict[str, Any], caplog: pytest.LogCaptureFixture -) -> None: - callbacks = BackgroundCallbacks(source=source, location=location, injected=injected) - original_middleware = None if callbacks.agent.middleware is None else list(callbacks.agent.middleware) - original_defaults = callbacks.agent.default_options.copy() - host = ( - InvocationsWorkflowHostServer( - callbacks.workflow, parse_input=lambda request: WorkflowTurn(input="hi", stream=stream) - ) - if workflow - else InvocationsHostServer(callbacks.agent) - ) - async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: - response = await client.post( - "/invocations?agent_session_id=background", json={"message": "hi", "stream": stream} - ) - assert response.status_code == (200 if stream else 500) - assert "invocation failed" in response.text.lower() - assert "background" in caplog.text or "transport controls" in caplog.text - assert callbacks.client.calls == [] - assert callbacks.agent.default_options == original_defaults - if not workflow: - assert callbacks.agent.middleware == original_middleware - - -@pytest.mark.parametrize("workflow", [False, True]) -@pytest.mark.parametrize("stream", [False, True]) -@pytest.mark.parametrize("location", ["options", "kwargs"]) -@pytest.mark.parametrize("injected", [{"background": True}, {"extra_body": {"background": True}}]) -async def test_raw_agent_client_middleware_background_is_rejected( - workflow: bool, stream: bool, location: str, injected: dict[str, Any], caplog: pytest.LogCaptureFixture -) -> None: - callbacks = BackgroundCallbacks(source="chat", location=location, injected=injected, raw=True) - host = ( - InvocationsWorkflowHostServer( - callbacks.workflow, parse_input=lambda request: WorkflowTurn(input="hi", stream=stream) - ) - if workflow - else InvocationsHostServer(callbacks.agent) - ) - async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: - response = await client.post( - "/invocations?agent_session_id=raw-background", json={"message": "hi", "stream": stream} - ) - assert response.status_code == (200 if stream else 500) - assert "background" in caplog.text - assert callbacks.client.calls == [] - - @pytest.mark.parametrize("stream", [False, True]) @pytest.mark.parametrize("shape", ["flat", "options"]) async def test_native_raw_agent_rejects_run_level_middleware(stream: bool, shape: str) -> None: @@ -120,32 +62,6 @@ async def test_native_raw_agent_rejects_run_level_middleware(stream: bool, shape assert callbacks.client.calls == [] -@pytest.mark.parametrize("workflow", [False, True]) -@pytest.mark.parametrize("stream", [False, True]) -@pytest.mark.parametrize("callbacks_type", [AgentChatCallbacks, ReplacedMiddlewareCallbacks]) -async def test_run_guard_survives_agent_chat_middleware_and_replaced_client_middleware( - workflow: bool, stream: bool, callbacks_type: type[BackgroundCallbacks] -) -> None: - callbacks = ( - AgentChatCallbacks() - if callbacks_type is AgentChatCallbacks - else callbacks_type(source="agent", location="options", injected={"background": True}) - ) - host = ( - InvocationsWorkflowHostServer( - callbacks.workflow, parse_input=lambda request: WorkflowTurn(input="hi", stream=stream) - ) - if workflow - else InvocationsHostServer(callbacks.agent) - ) - async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: - response = await client.post( - "/invocations?agent_session_id=background", json={"message": "hi", "stream": stream} - ) - assert "invocation failed" in response.text.lower() - assert callbacks.client.calls == [] - - @pytest.mark.parametrize("workflow", [False, True]) @pytest.mark.parametrize("raw", [False, True]) @pytest.mark.parametrize("stream", [False, True]) @@ -167,7 +83,3 @@ async def test_supported_middleware_preserves_foreground_generation(workflow: bo assert callbacks.client.calls[0]["temperature"] == 0.2 if not (workflow and raw): assert callbacks.client.chat_middleware == [callbacks.inject_chat] - - -def test_unlayered_client_receives_no_middleware_kwarg() -> None: - assert foreground_agent_run_kwargs(RawAgent(client=OptionsClient())) == {} diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py index a05a0bd76e6..4aee72d219c 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py @@ -11,6 +11,7 @@ import pytest from agent_framework import Agent, AgentContext, AgentSession, ChatOptions, RawAgent from azure.ai.agentserver.responses import ResponsesServerOptions +from starlette.requests import Request from agent_framework_foundry_hosting import ( InvocationsHostServer, @@ -191,6 +192,34 @@ async def test_invocations_options_are_opt_in(stream: bool) -> None: assert callbacks.client.calls[0]["temperature"] == 0.4 +@pytest.mark.parametrize("stream", [False, True]) +@pytest.mark.parametrize("background", [False, True]) +async def test_invocations_hook_background_is_passed_to_agent(stream: bool, background: bool) -> None: + callbacks = OptionCallbacks() + + def prepare(request: Request, options: dict[str, Any]) -> dict[str, Any]: + return {**options, "background": background} + + host = InvocationsHostServer(callbacks.factory, prepare_options=prepare) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: + response = await client.post("/invocations?agent_session_id=options", json={"message": "hi", "stream": stream}) + assert response.status_code == 200 + assert callbacks.client.calls[0]["background"] is background + + +@pytest.mark.parametrize("stream", [False, True]) +async def test_invocations_without_hook_passes_no_background(stream: bool) -> None: + callbacks = OptionCallbacks() + host = InvocationsHostServer(callbacks.factory) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=host), base_url="http://test") as client: + response = await client.post( + "/invocations?agent_session_id=options", + json={"message": "hi", "stream": stream, "options": {"background": True}}, + ) + assert response.status_code == 200 + assert "background" not in callbacks.client.calls[0] + + @pytest.mark.parametrize("stream", [False, True]) async def test_invocations_rejects_factory_hidden_background_before_model_call( stream: bool, caplog: pytest.LogCaptureFixture From 6949d939e96116ab4c276f3beb4739ba455dddb8 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 15:31:38 +0100 Subject: [PATCH 52/55] Python: remove stale Invocations setting guards --- .../_invocations_agent.py | 6 +----- .../_invocations_shared.py | 10 ---------- .../_invocations_workflow.py | 14 ++----------- .../_shared.py | 4 ++-- .../foundry_hosting/test_host_options.py | 20 ------------------- .../test_invocations_workflow.py | 6 ------ .../tests/test_foundry_hosting_imports.py | 4 ---- 7 files changed, 5 insertions(+), 59 deletions(-) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py index 83f6745feec..63c89c0503b 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py @@ -63,16 +63,12 @@ def __init__( `asyncapi_spec_json` and `asyncapi_spec_yaml`. The host settings listed above (`agent`, `openapi_spec`, `agent_session_store_provider`, `parse_input`, `prepare_options`, `unsupported_options`, and `sse_keep_alive_interval_seconds`) are handled directly by this host. - Use `InvocationsWorkflowHostServer` for native workflow settings. Raises: - TypeError: If the agent source, parser/hook, or heartbeat type is invalid, or Responses-only - or native workflow settings are supplied. + TypeError: If the agent source, parser/hook, or heartbeat type is invalid. ValueError: If the heartbeat interval is nonpositive or an injected agent has unsupported background or transport defaults. """ - if {"workflow", "checkpoint_store_provider"}.intersection(agent_server_kwargs): - raise TypeError("Use InvocationsWorkflowHostServer for native workflows and checkpoint storage.") super().__init__( agent=agent, openapi_spec=openapi_spec, diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py index 46b3be9c6f4..73a85476e4c 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py @@ -341,16 +341,6 @@ def __init__( **agent_server_kwargs: Any, ) -> None: """Initialize shared protocol plumbing after the public host selects its execution model.""" - if forbidden := { - "max_history_items", - "history_source", - "background_source", - "enable_background_recovery", - "shutdown_grace_period_seconds", - }.intersection(agent_server_kwargs): - raise TypeError( - f"Responses-only settings are not supported by Invocations: {', '.join(sorted(forbidden))}." - ) validate_sse_keep_alive_interval(sse_keep_alive_interval_seconds) unsupported_options = validate_unsupported_options(unsupported_options) if agent is not None and workflow is not None: diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py index 1d381f394b7..f5e33b163d4 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py @@ -45,22 +45,12 @@ def __init__( sse_keep_alive_interval_seconds: Positive streaming heartbeat interval. If omitted, use a positive `SSE_KEEPALIVE_INTERVAL`, otherwise disable heartbeats. Not a request/model timeout. **agent_server_kwargs: Additional AgentServer SDK constructor arguments, such as - `asyncapi_spec_json` and `asyncapi_spec_yaml`. Responses-only and agent-only settings are - rejected. Output uses JSON or framed SSE workflow events. + `asyncapi_spec_json` and `asyncapi_spec_yaml`. Output uses JSON or framed SSE workflow events. Raises: - TypeError: If the workflow is not a request-aware factory, the parser or heartbeat type is invalid, - or a Responses-only or agent-only setting is supplied. + TypeError: If the workflow is not a request-aware factory, or the parser or heartbeat type is invalid. ValueError: If the heartbeat interval is nonpositive. """ - forbidden = { - "agent", - "agent_session_store_provider", - "prepare_options", - "unsupported_options", - }.intersection(agent_server_kwargs) - if forbidden: - raise TypeError(f"Unsupported native workflow host settings: {', '.join(sorted(forbidden))}.") if not callable(parse_input): raise TypeError("parse_input must be a callable.") super().__init__( diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py index 9564fc7702b..97e2f2116c1 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py @@ -333,9 +333,9 @@ async def prepare_response_options(request: ResponsesRequest, hook: OptionsHook async def response_input_messages(request: ResponsesRequest) -> list[Message]: - """Convert only this Responses turn's input items to the legacy workflow message contract. + """Convert only this Responses turn's input items to `list[Message]` workflow input. - This explicit migration helper does not load outer history, restore checkpoints, + This explicit helper does not load outer history, restore checkpoints, or decode pending native workflow replies. Native workflows should prefer typed application inputs and use ``request.get_workflow_responses()`` for resumable pauses. """ diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py index 4aee72d219c..c5c948b6f15 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py @@ -92,26 +92,6 @@ def test_recovery_and_workflow_history_eligibility() -> None: build_response_server_options(is_workflow=True, background_source="inference_service") -@pytest.mark.parametrize( - "name", - [ - "max_history_items", - "history_source", - "background_source", - "enable_background_recovery", - "shutdown_grace_period_seconds", - ], -) -def test_invocations_rejects_responses_only_settings_before_sdk(name: str) -> None: - settings: dict[str, Any] = {name: None} - with ( - patch("agent_framework_foundry_hosting._invocations_shared.InvocationAgentServerHost.__init__") as sdk, - pytest.raises(TypeError, match="Responses-only"), - ): - InvocationsHostServer(Agent(client=OptionsClient()), **settings) - sdk.assert_not_called() - - @pytest.mark.parametrize("env", [None, "0", "-2", "3"]) @pytest.mark.parametrize("explicit", [None, 5]) def test_invocations_heartbeat_precedence_and_per_host_isolation( diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_invocations_workflow.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_invocations_workflow.py index 8d0de648aa4..b7a4737e77d 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_invocations_workflow.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_invocations_workflow.py @@ -55,7 +55,6 @@ from agent_framework_foundry_hosting import ( CheckpointStoreProvider, FoundryRequestScope, - InvocationsHostServer, InvocationsWorkflowHostServer, WorkflowSource, WorkflowTurn, @@ -438,11 +437,6 @@ def test_requires_one_source_and_an_explicit_parser(self) -> None: def create(_request: Request) -> Workflow: return WorkflowBuilder(name="tickets", start_executor=_TicketExecutor([])).build() - invalid_agent: Any = object() - with pytest.raises(TypeError, match="InvocationsWorkflowHostServer"): - InvocationsHostServer(agent=invalid_agent, workflow=create) - with pytest.raises(TypeError, match="InvocationsWorkflowHostServer"): - InvocationsHostServer(agent=invalid_agent, checkpoint_store_provider=lambda _context: None) with pytest.raises(TypeError, match="parse_input"): cast(Any, InvocationsWorkflowHostServer)(workflow=create) diff --git a/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py b/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py index b03a65d5cf9..a8d830bdadf 100644 --- a/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py +++ b/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py @@ -146,10 +146,6 @@ def test_agent_hosts_reject_ambiguous_factories_before_sdk_construction(protocol ("Responses", "background_source"), ("Responses", "unsupported_options"), ("Responses", "store"), - ("Invocations", "agent"), - ("Invocations", "agent_session_store_provider"), - ("Invocations", "prepare_options"), - ("Invocations", "unsupported_options"), ], ) def test_workflow_hosts_reject_agent_settings_before_sdk_construction(protocol: str, setting: str) -> None: From 46ffffafd17b12bbf03193f6d3600106276b8023 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 15:36:04 +0100 Subject: [PATCH 53/55] Python: preserve application background options without middleware guard --- .../0055-python-foundry-hosting-contracts.md | 25 ++-- python/packages/foundry_hosting/README.md | 36 +++--- .../_responses_agent.py | 11 +- .../foundry_hosting/responses_host_helpers.py | 5 + .../foundry_hosting/tests/test_responses.py | 111 +++++++----------- 5 files changed, 86 insertions(+), 102 deletions(-) diff --git a/docs/decisions/0055-python-foundry-hosting-contracts.md b/docs/decisions/0055-python-foundry-hosting-contracts.md index c79c3428ebb..9a6a1db5e46 100644 --- a/docs/decisions/0055-python-foundry-hosting-contracts.md +++ b/docs/decisions/0055-python-foundry-hosting-contracts.md @@ -117,22 +117,25 @@ including acceptance of `None`, without changing the wire flag or downstream sto Treat outer background execution, inner inference-service background execution, and recovery permission as separate controls. Use `background_source="host_managed"` by default. Retain `"inference_service"` for supported regular agents with inference-service history and outer-background passthrough. -Reject hidden provider background under an outer foreground request. +Validate hosting-visible agent and factory defaults against the selected background mode. Outer workflow background must not enable background on constituent agents. Native inner provider background is unsupported. Do not introduce a per-agent workflow-host background switch. Recovery permission neither selects an execution mode nor guarantees exactly-once external side effects. -Allow top-level `background` values of `False` or `None`, and reject nested `extra_body.background` in -every mode. Validate caller options, hook results, and developer defaults before execution. Also check the -effective options and client kwargs from ordinary agent middleware and client-level chat middleware before -the provider call. For a native `RawAgent`, install the check after existing client middleware on the fresh -client that the host owns. Make native `WorkflowTurn` reject client-level and run-level middleware. Report -middleware violations as execution failures, not as client input errors. - -Do not claim universal interception and do not change Core for this check. Core can append chat middleware -from context providers after the guard, so applications must not enable provider background there. Clients -that internally force provider background are unsupported. +For regular Responses and Invocations agents, allow an application options hook to select `background`; +the application owns that choice. Ordinary Responses agent runs preserve hook-selected values. When the host +explicitly selects provider background, retain `background=True` for submission and polling even if the hook +returns `False`. Hook-selected background alone does not enable host-managed polling or recovery. Invocations +does not inject an outer background value. + +Do not inject background-specific enforcement middleware or add a Core interception hook. Application agent/chat +middleware owns its changes to background options. Keep validation of caller envelope fields, hook results +other than the agent hook's background choice, and developer defaults before execution. Reject nested caller +`extra_body.background` before the Responses hook. Native workflow option hooks cannot select inner provider +background; make native `WorkflowTurn` reject client-level and run-level middleware. The existing native agent +options middleware still validates transport controls, storage, and unfinished provider responses to preserve +checkpoint ownership; it is not the removed background-specific guard. ### Supported host settings diff --git a/python/packages/foundry_hosting/README.md b/python/packages/foundry_hosting/README.md index 864382d8f7f..4ffd5bbf64b 100644 --- a/python/packages/foundry_hosting/README.md +++ b/python/packages/foundry_hosting/README.md @@ -372,9 +372,9 @@ next token is saved can still repeat the tool on recovery; use idempotent tools for side-effecting local tools. This mechanism does not provide exactly-once tool execution. Regular agent runs without this opt-in are not crash-replayable. -The supported regular-agent combinations are: +The supported regular-agent combinations for host-selected provider background are: -| `history_source` | `background_source` | Provider background | `enable_background_recovery=True` | +| `history_source` | `background_source` | Host-selected provider background | `enable_background_recovery=True` | | --- | --- | --- | --- | | `"host_managed"` | `"host_managed"` | No; outer background only | Rejected | | `"agent_managed"` | `"host_managed"` | No; outer background only | Rejected | @@ -386,20 +386,24 @@ require outer `store=true`. For checkpoint-backed native Responses workflow reco `enable_background_recovery=True` and enable the AgentServer resilient task subsystem; agent history/background source settings do not apply. This does not enable provider background on workflow agents. -Provider background is selected only by the host. A provider call may use `background=True` only for an outer -background request with both `history_source="inference_service"` and `background_source="inference_service"`. -A top-level `background` of `False` or `None` is allowed in every mode. A nested `extra_body["background"]` is -always rejected, even when it is `False`. The host checks these values in caller options, the `prepare_options` -result, and developer defaults before execution. It also checks the effective options and client kwargs that -ordinary agent middleware and client-level chat middleware produce, before the provider call. Invocations hosts -and native workflow constituent agents never use provider background, and an outer workflow `background=True` does -not enable it for those agents. A native `WorkflowTurn` rejects client-level and run-level `middleware`. - -This guard does not intercept every path. Agent Framework Core can append chat middleware that a context provider -contributes **after** the guard; that middleware must not enable provider background. Clients that internally -force provider background are unsupported. Invalid defaults and request options fail before execution. A -middleware violation is an application failure during execution: a non-streaming request returns HTTP 500, and a -stream ends with a terminal error event. +The host sets provider `background=True` only for an outer background request with both +`history_source="inference_service"` and `background_source="inference_service"`. In that selected mode, +submission and polling retain `background=True`, even if `prepare_options` returns `background=False`. +On ordinary agent runs, a hook-returned `background` value passes through unchanged. Without a hook-selected +value, inference-service background mode passes `False` for an outer foreground request; other modes omit it. +Invocations agents have no outer background mode and do not add a background option. + +An application that selects background in a Responses or Invocations agent hook owns that choice; it does not +enable host-managed provider polling or recovery. Hosting does not inject middleware to inspect or override +background values set by application agent/chat middleware, and adds no Core interception hook. +Factory and developer defaults still undergo background validation before execution. A nested +`extra_body["background"]` in caller options is rejected before the Responses hook, even when it is `False`. + +Native workflows keep a separate checkpoint contract: inner provider background is unsupported, and their +option hook cannot select it. Outer workflow `background=True` does not enable it for constituent agents. +A native `WorkflowTurn` rejects client-level and run-level `middleware`. +Its existing native agent options middleware validates transport controls, storage, and unfinished provider +responses to preserve checkpoint ownership; that multipurpose policy remains in place. **Steering is unavailable.** `steerable_conversations` and the other removed `ResponsesServerOptions` settings are not host parameters; passing them raises `TypeError` during host construction. The AgentServer SDK can retain diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py index 9866b73dfcf..05a56404222 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py @@ -85,7 +85,6 @@ OptionsHook, ResponsesRequest, UnsupportedOptions, - background_agent_run_kwargs, build_response_server_options, is_agent, prepare_response_options, @@ -312,6 +311,8 @@ def __init__( Defaults to `False`; it does not enable background execution or guarantee exactly-once effects. prepare_options: Developer hook selecting caller model options after factory resolution. Only its returned, validated mapping is forwarded. Without a hook, caller options are omitted. + A returned `background` value is application-owned on ordinary runs. Host-selected provider + background submission and polling retain `background=True`. unsupported_options: `"warn"` (default), `"error"`, or `"ignore"` when a custom agent cannot accept runtime model options. **kwargs: Additional keyword arguments. @@ -495,7 +496,7 @@ async def _handle_response( _initialize_agent_history(agent, configuration) await prepare_response_options(hosted_request, self._prepare_options) try: - validate_request_options(hosted_request.options) + validate_request_options(hosted_request.options, allow_background=True) _validate_agent_defaults( agent, provider_background=provider_background, @@ -1010,7 +1011,7 @@ async def _handle_inner_agent( chat_options = dict(hosted_request.options) are_options_set = bool(chat_options) if self._background_source == "inference_service": - chat_options["background"] = provider_background + chat_options.setdefault("background", provider_background) if configuration.agent_server_history: if configuration.client_stores_by_default: # The response provider already owns the transcript used for this run. Keep a @@ -1041,9 +1042,6 @@ async def _handle_inner_agent( if self._unsupported_options == "warn": logger.warning("Agent doesn't support runtime options. They will be ignored.") - if not provider_background: - run_kwargs.update(background_agent_run_kwargs(cast(SupportsAgentRun, agent), provider_background=False)) - if previous_response_id is not None and context.conversation_id is None and not context.is_recovery: if ( stored @@ -1311,7 +1309,6 @@ async def run_provider( input_messages, session=session, options=options, - **background_agent_run_kwargs(agent, provider_background=True), ) except Exception as exc: logger.warning("Inner provider background %s failed (%s).", phase, type(exc).__name__) diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/responses_host_helpers.py b/python/packages/foundry_hosting/tests/foundry_hosting/responses_host_helpers.py index 7fa95fbe1ca..dfecee7b2cf 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/responses_host_helpers.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/responses_host_helpers.py @@ -62,6 +62,11 @@ async def process(self, context: ChatContext, call_next: Callable[[], Awaitable[ await call_next() +class FailingAgentMiddleware(AgentMiddleware): + async def process(self, context: AgentContext, call_next: Callable[[], Awaitable[None]]) -> None: + raise RuntimeError("Application middleware failed.") + + class BackgroundPollingClient(ChatMiddlewareLayer[Any], BaseChatClient[Any]): STORES_BY_DEFAULT = True diff --git a/python/packages/foundry_hosting/tests/test_responses.py b/python/packages/foundry_hosting/tests/test_responses.py index 68070069bed..fb0cf673c1a 100644 --- a/python/packages/foundry_hosting/tests/test_responses.py +++ b/python/packages/foundry_hosting/tests/test_responses.py @@ -120,6 +120,7 @@ BackgroundAgentMiddleware, BackgroundChatMiddleware, BackgroundPollingClient, + FailingAgentMiddleware, GatedAgentStream, GatedRequestRead, GatedSessionLoadStore, @@ -1969,16 +1970,10 @@ async def test_previous_response_requires_existing_agent_session(self) -> None: @pytest.mark.parametrize("stream", [False, True]) @pytest.mark.parametrize("kind", ["agent", "chat"]) - @pytest.mark.parametrize("nested", [False, True]) - @pytest.mark.parametrize("in_kwargs", [False, True]) - async def test_middleware_cannot_enable_provider_background_on_foreground( - self, stream: bool, kind: str, nested: bool, in_kwargs: bool - ) -> None: + async def test_application_middleware_background_is_not_intercepted(self, stream: bool, kind: str) -> None: client = StatefulConsentClient(["tool"]) middleware = ( - BackgroundAgentMiddleware(nested=nested, in_kwargs=in_kwargs) - if kind == "agent" - else BackgroundChatMiddleware(nested=nested, in_kwargs=in_kwargs) + BackgroundAgentMiddleware(nested=False) if kind == "agent" else BackgroundChatMiddleware(nested=False) ) agent = Agent(client=client, middleware=[middleware]) server = _make_server(agent, history_source="inference_service") @@ -1987,69 +1982,48 @@ async def test_middleware_cannot_enable_provider_background_on_foreground( assert response.status_code == 200 if stream: - assert "response.failed" in _sse_event_types(_parse_sse_events(response.text)) + assert "response.completed" in _sse_event_types(_parse_sse_events(response.text)) else: - assert response.json()["status"] == "failed" - assert client.calls == [] + assert response.json()["status"] == "completed" + assert client.calls + assert client.options[0]["background"] is True + assert agent.middleware == [middleware] - @pytest.mark.parametrize("kind", ["agent", "chat"]) - @pytest.mark.parametrize("nested", [False, True]) - @pytest.mark.parametrize("in_kwargs", [False, True]) - async def test_middleware_cannot_disable_selected_provider_background( - self, kind: str, nested: bool, in_kwargs: bool + @pytest.mark.parametrize("stream", [False, True]) + @pytest.mark.parametrize("background_source", ["host_managed", "inference_service"]) + @pytest.mark.parametrize("hook_background", [None, False, True]) + async def test_hook_background_is_forwarded_on_ordinary_runs( + self, stream: bool, background_source: str, hook_background: bool | None ) -> None: client = StatefulConsentClient(["tool"]) - middleware = ( - BackgroundAgentMiddleware(nested=nested, value=False, in_kwargs=in_kwargs) - if kind == "agent" - else BackgroundChatMiddleware(nested=nested, value=False, in_kwargs=in_kwargs) - ) - agent = Agent(client=client, middleware=[middleware]) server = _make_server( - agent, - session_store=SessionStore(), + Agent(client=client), history_source="inference_service", - background_source="inference_service", + background_source=background_source, + prepare_options=( + (lambda _request, _options: {"background": hook_background}) if hook_background is not None else None + ), ) - request = CreateResponse(input="hello", store=True, background=True) - context = ResponseContext(response_id="outer-response", mode_flags=MagicMock()) - with patch.object(ResponseContext, "get_input_items", new=AsyncMock(return_value=[])): - events = [event async for event in server._handle_response(request, context, asyncio.Event())] - - assert any(isinstance(event, Mapping) and event.get("type") == "response.failed" for event in events) - assert client.calls == [] - @pytest.mark.parametrize("kind", ["agent", "chat"]) - @pytest.mark.parametrize("in_kwargs", [False, True]) - async def test_middleware_cannot_disable_provider_background_on_poll(self, kind: str, in_kwargs: bool) -> None: - client = BackgroundPollingClient() - middleware = ( - BackgroundAgentMiddleware(nested=False, value=False, in_kwargs=in_kwargs, on_poll=True) - if kind == "agent" - else BackgroundChatMiddleware(nested=False, value=False, in_kwargs=in_kwargs, on_poll=True) - ) - agent = Agent(client=client, middleware=[middleware]) - server = _make_server( - agent, - session_store=SessionStore(), - history_source="inference_service", - background_source="inference_service", - ) - request = CreateResponse(input="hello", store=True, background=True) - context = ResponseContext(response_id="outer-response", mode_flags=MagicMock()) - with ( - patch.object(ResponseContext, "get_input_items", new=AsyncMock(return_value=[])), - patch("agent_framework_foundry_hosting._responses_agent.asyncio.sleep", new=AsyncMock()), - ): - events = [event async for event in server._handle_response(request, context, asyncio.Event())] + response = await _post(server, stream=stream) - assert any(isinstance(event, Mapping) and event.get("type") == "response.failed" for event in events) + assert response.status_code == 200 + if stream: + assert "response.completed" in _sse_event_types(_parse_sse_events(response.text)) + else: + assert response.json()["status"] == "completed" assert len(client.calls) == 1 - assert client.calls[0]["background"] is True - assert agent.middleware == [middleware] - assert not client.chat_middleware + if hook_background is not None: + assert client.options[0]["background"] is hook_background + elif background_source == "inference_service": + assert client.options[0]["background"] is False + else: + assert "background" not in client.options[0] - async def test_provider_background_guard_allows_submit_and_poll_without_mutating_agent(self) -> None: + @pytest.mark.parametrize("conflicting_hook", [False, True]) + async def test_host_selected_provider_background_retains_submit_and_poll_precedence( + self, conflicting_hook: bool + ) -> None: client = BackgroundPollingClient() agent = Agent(client=client) server = _make_server( @@ -2057,6 +2031,7 @@ async def test_provider_background_guard_allows_submit_and_poll_without_mutating session_store=SessionStore(), history_source="inference_service", background_source="inference_service", + prepare_options=(lambda _request, _options: {"background": False}) if conflicting_hook else None, ) request = CreateResponse(input="hello", store=True, background=True) context = ResponseContext(response_id="outer-response", mode_flags=MagicMock()) @@ -2072,25 +2047,25 @@ async def test_provider_background_guard_allows_submit_and_poll_without_mutating assert not agent.middleware assert not client.chat_middleware - @pytest.mark.parametrize("provider_background", [False, True]) - async def test_raw_agent_client_chat_middleware_cannot_override_background(self, provider_background: bool) -> None: + async def test_raw_agent_client_chat_middleware_background_is_not_intercepted(self) -> None: client = StatefulConsentClient(["tool"]) - middleware = BackgroundChatMiddleware(nested=False, value=not provider_background) + middleware = BackgroundChatMiddleware(nested=False) client.chat_middleware.append(middleware) agent = RawAgent(client=client) server = _make_server( agent, session_store=SessionStore(), history_source="inference_service", - background_source="inference_service" if provider_background else "host_managed", + background_source="inference_service", ) - request = CreateResponse(input="hello", store=True, background=provider_background) + request = CreateResponse(input="hello", store=True, background=False) context = ResponseContext(response_id="outer-response", mode_flags=MagicMock()) with patch.object(ResponseContext, "get_input_items", new=AsyncMock(return_value=[])): events = [event async for event in server._handle_response(request, context, asyncio.Event())] - assert any(isinstance(event, Mapping) and event.get("type") == "response.failed" for event in events) - assert client.calls == [] + assert any(isinstance(event, Mapping) and event.get("type") == "response.completed" for event in events) + assert len(client.calls) == 1 + assert client.options[0]["background"] is True assert client.chat_middleware == [middleware] @pytest.mark.parametrize("stream", [False, True]) @@ -2102,7 +2077,7 @@ async def test_middleware_failure_on_approval_reply_leaves_parent_pending( server = _make_server(agent, session_store=SqliteSessionStore(tmp_path / "middleware-approval.sqlite")) first = await _post(server) approval_id = next(item["id"] for item in first.json()["output"] if item["type"] == "mcp_approval_request") - agent.middleware = [BackgroundAgentMiddleware(nested=False)] + agent.middleware = [FailingAgentMiddleware()] payload = { "input": [{"type": "mcp_approval_response", "approval_request_id": approval_id, "approve": True}], "previous_response_id": first.json()["id"], From a38be7b3093097a6bd37f57d053944a855814643 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 15:56:12 +0100 Subject: [PATCH 54/55] Python: split Foundry hosting into four concrete hosts Separate Invocations/Responses agent and workflow hosts. Agent hosts forward only caller messages by default; agent default_options apply and prepare_options is the explicit opt-in. Workflow hosts require a parser; workflow options come only from the parsed turn. --- .../0055-python-foundry-hosting-contracts.md | 33 +- python/packages/foundry_hosting/README.md | 127 +-- .../_invocations_agent.py | 344 ++++++- .../_invocations_shared.py | 848 ++---------------- .../_invocations_workflow.py | 483 +++++++++- .../_responses_agent.py | 55 +- .../_responses_workflow.py | 36 +- .../_shared.py | 161 ++-- .../foundry_hosting/test_host_options.py | 64 +- .../test_invocations_workflow.py | 6 +- .../foundry_hosting/test_native_responses.py | 23 +- .../foundry_hosting/test_workflow_state.py | 22 +- .../tests/test_foundry_hosting_imports.py | 58 +- .../foundry_hosting/tests/test_invocations.py | 53 +- .../foundry_hosting/tests/test_request.py | 11 - .../foundry_hosting/tests/test_responses.py | 116 +-- .../responses/basic/README.md | 2 +- .../declarative_customer_support/README.md | 7 +- .../declarative_customer_support/main.py | 2 +- .../resilient_long_running_workflow/README.md | 4 +- .../steerable_long_running_agent/README.md | 4 +- .../steerable_long_running_agent/main.py | 2 +- .../verify_steering.py | 6 +- 23 files changed, 1151 insertions(+), 1316 deletions(-) diff --git a/docs/decisions/0055-python-foundry-hosting-contracts.md b/docs/decisions/0055-python-foundry-hosting-contracts.md index 9a6a1db5e46..dffb392bc76 100644 --- a/docs/decisions/0055-python-foundry-hosting-contracts.md +++ b/docs/decisions/0055-python-foundry-hosting-contracts.md @@ -44,12 +44,13 @@ See the [Foundry Hosting README](../../python/packages/foundry_hosting/README.md Use `ResponsesHostServer` and `InvocationsHostServer` for agents, and `ResponsesWorkflowHostServer` and `InvocationsWorkflowHostServer` for native workflows. Agent hosts reject `WorkflowAgent`; workflow hosts require a factory returning a native `Workflow`. -Do not silently unwrap agents, migrate their state, or retain a combined-host compatibility shim. +Do not silently unwrap agents or migrate their state. Workflow hosts expose checkpoint storage rather than agent-session storage or agent history settings. -The Responses workflow host owns native execution directly. Share the Invocations engine between its -public hosts rather than duplicating it. Group each protocol into agent, workflow, and shared modules, -with cross-protocol request contracts and factory resolution in a central shared module. +Each of the four hosts owns its own construction, execution, and validation. Do not route agent and workflow +execution through a shared host with mode switches; that couples their validation rules. Group each protocol into +agent and workflow modules. Shared modules hold only protocol-neutral utilities, such as request contracts, +factory resolution, and SSE framing. Keep all hosts in one package. Responses is the initial stable-surface target; Invocations and Toolbox remain experimental. Separate classes do not require separate distribution packages. @@ -57,10 +58,10 @@ remain experimental. Separate classes do not require separate distribution packa ### Request adaptation and construction Use `parse_input` for custom input adaptation across both protocols. Agent parsers return `InvocationRun`; -workflow parsers return `WorkflowTurn` containing either typed start input or pending replies. +workflow parsers return `WorkflowTurn` containing either typed start input or pending replies. Workflow hosts +always require a parser; there is no default input conversion. Parsing does not replace the host's checkpoint binding or the workflow runtime's reply validation. Use `ResponsesRequest` for the Responses wrapper, including factory and option-hook inputs. -Do not retain aliases for the former parser keywords or request-type name. Agent hosts accept an instance or a sync/async factory implementing a named-request callable protocol. Factories must declare a required `request` parameter and are called as `factory(request=request)`. @@ -74,12 +75,12 @@ before `prepare_options`. Invocations agent factories receive the Starlette `Req and option preparation. Preserve these protocol-specific timings rather than forcing identical signatures or inventing a shared options-precedence policy. -Caller model-run options are opt-in for Responses agents, Responses workflows, and Invocations agents. -Without `prepare_options`, do not forward caller generation settings; preserve developer defaults and -host-owned storage/background controls. With a hook, forward only its returned, validated mapping. -This does not prevent application code from inspecting the original request. Responses agent factories -see translated options before the hook. Native Responses workflow factories run after the hook and -see its selected options, or an empty option mapping when no hook is configured. +By default, agent hosts forward only the caller's messages. Do not forward caller generation settings; the +agent's own `default_options` apply unchanged, together with host-owned storage/background controls. An +optional `prepare_options` callable on agent hosts is the opt-in customization path; forward only its returned, +validated mapping. This does not prevent application code from inspecting the original request. Responses +agent factories see translated options before the hook. Workflow hosts have no option hook: the parser forwards +model options explicitly through `WorkflowTurn` client kwargs. Native workflow factories are request-aware and must allocate fresh workflows, executors, agents, clients, providers, and mutable tools. A new graph wrapper around shared executors is not isolation. @@ -109,8 +110,8 @@ Keep three storage decisions distinct: Use `history_source="host_managed"` by default, with `"agent_managed"` and `"inference_service"` as explicit alternatives. `agent_managed` permits developer-owned history providers or downstream -service storage; it is not restricted to `HistoryProvider`. Remove the constructor `store=` alias, -including acceptance of `None`, without changing the wire flag or downstream storage controls. +service storage; it is not restricted to `HistoryProvider`. The constructor selects the backend only through +`response_store`; this does not change the wire flag or downstream storage controls. ### Background execution and recovery @@ -168,7 +169,7 @@ from that request, and consumes it. The host stores only a translation map from the original request in that session's state. This map does not authorize execution. Native workflows use `request_info` and their exact checkpoint; the host translates wire IDs to request IDs in its checkpoint binding. There is no separate public approval-store API, no conditional-write capability for custom session stores, and no -silent migration of old separate-store approvals. +import of approvals recorded outside session state. Do not preflight approval replies before the response starts. The host drops a reply with an unknown wire ID with a warning, and the framework does not execute a reply that matches no pending request. A turn whose input @@ -209,7 +210,7 @@ These decisions do not redesign Core, concurrency, checkpoints, retries, or exte - Public signatures identify execution models and their state owners. - Shared internals avoid duplicate engines without obscuring public contracts. - Request-aware factories support identity-dependent resources but require deliberate isolation and cleanup. -- The API migration breaks combined-host construction, wrapper hosting, unnamed or zero-argument agent factories, old parser/request names, source literals, and the storage-backend alias. +- Agent and workflow hosts have separate constructors and validation; wrapper hosting and unnamed or zero-argument agent factories are not supported. - Settings, authority, and consent changes require their own implementation and correctness validation; recording a decision does not establish that it has shipped. ## Validation diff --git a/python/packages/foundry_hosting/README.md b/python/packages/foundry_hosting/README.md index 4ffd5bbf64b..94d29719bbc 100644 --- a/python/packages/foundry_hosting/README.md +++ b/python/packages/foundry_hosting/README.md @@ -14,47 +14,34 @@ under `agent_framework.foundry`. The package is currently in beta, so its public experimental. Responses hosting is the target for an initial stable release, subject to qualification. Invocations hosting and `FoundryToolbox` remain experimental. -**Breaking migration:** replace `ResponsesHostServer(workflow=..., parse_response=...)` with -`ResponsesWorkflowHostServer(workflow=..., parse_input=...)`, and replace -`InvocationsHostServer(workflow=..., parse_request=...)` with -`InvocationsWorkflowHostServer(workflow=..., parse_input=...)`. -There is no combined-host compatibility shim. Agent host construction still uses `agent=`. -All custom parsers now use `parse_input`, including agent parsers on `InvocationsHostServer`. -Rename `HostedResponseRequest` imports and annotations to `ResponsesRequest`, including factories and option hooks. -`InvocationRun` and `WorkflowTurn` are unchanged. Workflow parsers still adapt either typed start input -or a complete batch of pending replies; they are not limited to initial input or raw JSON deserialization. -The old parser keywords and request-type name have no compatibility aliases. - -**Caller-options migration:** caller model-run options are no longer forwarded by default. -For Responses agents, Responses workflows, and Invocations agents, configure `prepare_options` -to select the options the application accepts. Only the hook's returned, validated mapping is forwarded. -Without a hook, agent/client defaults still apply. Responses agent factories see translated caller -options before the hook; native Responses workflow factories see options after the hook. -The original request remains available to application code. - -Agent history/background source literals also change without aliases: - -| Setting | Previous literal | New literal | +Agent hosts accept `agent=` and an optional `parse_input` (Invocations) or no parser (Responses). +Workflow hosts accept `workflow=` and a required `parse_input`. Agent parsers return `InvocationRun`; +workflow parsers return `WorkflowTurn`, with either typed start input or a complete batch of pending replies. +Factories and option hooks on Responses hosts receive a `ResponsesRequest`. + +**Caller options are opt-in.** By default an agent host forwards only the caller's messages. The agent's own +`default_options` and client defaults apply unchanged. To accept caller generation settings, configure +`prepare_options` on an agent host. Only the mapping that the hook returns, after validation, is forwarded. +Workflow hosts have no option hook: the parser forwards model options explicitly through +`WorkflowTurn(client_kwargs={"options": ...})`. The original request remains available to application code. + +Agent history and background sources use these literals: + +| Setting | Values | Default | | --- | --- | --- | -| `history_source` | `"agent_server"` | `"host_managed"` | -| `history_source` | `"agent"` | `"agent_managed"` | -| `history_source` | `"service"` | `"inference_service"` | -| `background_source` | `"agent_server"` | `"host_managed"` | -| `background_source` | `"provider"` | `"inference_service"` | - -These are terminology changes only. The default remains host-managed history and background execution. -`agent_managed` retains developer-owned provider **or** service storage, not just `HistoryProvider` storage. -`response_store=` and the wire-level `store` flag keep their existing meanings. -The deprecated constructor `store=` backend alias is removed. Replace it with `response_store=`; -even `store=None` is rejected. This does not rename the caller's per-request `store` flag. - -`WorkflowSource` now describes a factory only; passing a built workflow fails at construction, -including local one-shot use. Move graph and executor construction inside the factory; +| `history_source` | `"host_managed"`, `"agent_managed"`, `"inference_service"` | `"host_managed"` | +| `background_source` | `"host_managed"`, `"inference_service"` | `"host_managed"` | + +`agent_managed` covers developer-owned provider **or** service storage, not just `HistoryProvider` storage. +`response_store=` selects the response store backend; the caller's per-request `store` flag is separate. + +`WorkflowSource` is a factory; passing a built workflow fails at construction, +including local one-shot use. Build graphs and executors inside the factory; returning a new wrapper around shared executors does not isolate execution state. Workflow hosts expose checkpoint storage, not agent-session storage or agent history/background -policies. Responses workflows retain `prepare_options`; Invocations workflows use the parser's -explicit workflow kwargs instead. Agent approval persistence follows the +policies. Both workflow hosts take model options only from the parser's explicit `WorkflowTurn` +kwargs. Agent approval persistence follows the [session-store contract below](#function-approvals). Agent hosts reject `WorkflowAgent`, whether supplied directly or returned by a factory. `checkpoint_store_provider` is available only on workflow hosts. @@ -83,25 +70,18 @@ server = ResponsesHostServer( ``` Explicit integer settings reject booleans and non-integers with `TypeError`, and nonpositive values with -`ValueError`. A positive history cap in another agent history mode emits a warning and is ignored. Workflow hosts reject -`max_history_items`, including explicit `None`; they do not use outer transcript history caps. -Invocations hosts reject the Responses-only settings `history_source`, `background_source`, -`max_history_items`, `shutdown_grace_period_seconds`, and `enable_background_recovery`, even when `None`. -The existing upstream Invocations `graceful_shutdown_timeout` passthrough is a separate setting. +`ValueError`. A positive history cap in another agent history mode emits a warning and is ignored. +Each host accepts only the settings listed for it; any other keyword raises `TypeError` at construction. +The upstream Invocations `graceful_shutdown_timeout` passthrough is a separate setting. An explicit positive SSE interval takes precedence over a positive environment value. However, the SDK parses `SSE_KEEPALIVE_INTERVAL` before applying that override: malformed values, including an empty string, still raise `ValueError` even with an explicit interval. Heartbeats do not set a request timeout. -The public `ResponsesServerOptions` bag is no longer accepted through `options=`. Removed host settings -`default_fetch_history_count`, `default_model`, `create_span_hook`, `additional_server_version`, -`steerable_conversations`, and `resilient_background` also raise `TypeError`, including when `None`. -Use the first-class settings above, agent/client defaults, and Agent Framework observability instead. - | Host | Continuation state | `prepare_options` | Background recovery | | --- | --- | --- | --- | | `ResponsesHostServer` | Agent session plus the selected history source | Sync or async | Eligible inference-service background only | -| `ResponsesWorkflowHostServer` | Exact native workflow checkpoint | Sync or async, before `parse_input` | Checkpoint-backed outer recovery | +| `ResponsesWorkflowHostServer` | Exact native workflow checkpoint | Not supported; use `WorkflowTurn` kwargs | Checkpoint-backed outer recovery | | `InvocationsHostServer` | Agent session; application-owned model history | Sync or async | No provider-background recovery | | `InvocationsWorkflowHostServer` | Exact native workflow checkpoint | Not supported; use `WorkflowTurn` kwargs | No provider-background recovery | @@ -145,8 +125,8 @@ general-purpose MCP approval policy. `SupportsAgentRun`, and is invoked once for each request as `factory(request=request)`. Factories must declare a required parameter named `request`, either keyword-only or positional-or-keyword. Additional parameters may have defaults, and the factory may ignore the request. -Zero-argument factories and factories with only optional configuration parameters are rejected at construction; -add a required `request` parameter when migrating them. Responses factories receive a +Zero-argument factories and factories with only optional configuration parameters are rejected at construction. +Responses factories receive a `ResponsesRequest`, with trusted scope, current-turn input helpers, and translated caller options. They run before `prepare_options`; the hook can subsequently replace those options. Invocations factories receive the Starlette `Request` after parsing and option preparation. @@ -174,7 +154,7 @@ outside `AgentSession`. Agent hosts continue agents through their session stores instance fields persistent; state needed by later requests must remain in the supported stores. -### Migrate `WorkflowAgent` hosting +### Host workflows natively `ResponsesHostServer` and `InvocationsHostServer` reject `WorkflowAgent` instances and factory results. Host the workflow natively with a request-aware factory returning a built `Workflow`, not `workflow.as_agent()`. @@ -188,8 +168,8 @@ server = ResponsesWorkflowHostServer(workflow=build_workflow, parse_input=parse_ ``` Build fresh workflows, executors, and agents for every request. Keep the workflow name and executor IDs stable so -later requests can find and restore checkpoints. Existing wrapper history, context providers, and event semantics -are not automatically unwrapped or migrated. +later requests can find and restore checkpoints. Wrapper history, context providers, and event semantics +are not unwrapped. ## Native Responses workflows @@ -255,18 +235,18 @@ fresh factory when its model overrides are already materialized in unchanged defaults and a storing client explicitly defaults to `store=False`. Private provider continuation is rejected before output is paired or committed. -For legacy message-input workflows, `response_input_messages(request)` converts +For message-input workflows, `response_input_messages(request)` converts only the current Responses turn to `list[Message]`. It does not load outer -history or decode pending replies. `agent=workflow.as_agent()` is no longer supported. +history or decode pending replies. Agent hosts reject `workflow.as_agent()`. Wrapper context providers, history, event projection, and request-info translation are -not silently unwrapped. See [Migrate `WorkflowAgent` hosting](#migrate-workflowagent-hosting). +not silently unwrapped. See [Host workflows natively](#host-workflows-natively). With `enable_background_recovery=True`, the application must also enable the AgentServer resilient task subsystem. Host-owned checkpoint/output pairs recover emitted output and usage without selecting newer unpaired workflow state. This is not an exactly-once guarantee for external tools: make -side-effecting operations idempotent. Legacy unscoped workflow state is not -read; migration starts a fresh Responses chain. +side-effecting operations idempotent. Unscoped workflow state is not +read; start a fresh Responses chain. ### Factory resource lifecycle @@ -399,18 +379,13 @@ background values set by application agent/chat middleware, and adds no Core int Factory and developer defaults still undergo background validation before execution. A nested `extra_body["background"]` in caller options is rejected before the Responses hook, even when it is `False`. -Native workflows keep a separate checkpoint contract: inner provider background is unsupported, and their -option hook cannot select it. Outer workflow `background=True` does not enable it for constituent agents. +Native workflows keep a separate checkpoint contract: inner provider background is unsupported, and parser +options cannot select it. Outer workflow `background=True` does not enable it for constituent agents. A native `WorkflowTurn` rejects client-level and run-level `middleware`. Its existing native agent options middleware validates transport controls, storage, and unfinished provider responses to preserve checkpoint ownership; that multipurpose policy remains in place. -**Steering is unavailable.** `steerable_conversations` and the other removed `ResponsesServerOptions` settings are -not host parameters; passing them raises `TypeError` during host construction. The AgentServer SDK can retain -unbounded futures for rejected turns when its steering queue fills -([Azure/azure-sdk-for-python#49233](https://github.com/Azure/azure-sdk-for-python/pull/49233)). Any future -steering support needs a published SDK fix, a dependency update, and a concurrent queue-overflow regression. -No future SDK version is assumed. Agent background polling without steering is unchanged. +**Steering is unavailable.** The hosts do not enable AgentServer steerable conversations. ### Preparing caller options @@ -435,9 +410,9 @@ This works for streaming and non-streaming requests. Responses agent ordering is translation, factory resolution and configuration checks, hook, then protected-option validation before execution. The factory therefore sees translated options **before** the hook. Invocations agent ordering is parser, hook, protected-option validation, factory, then default validation before entering -the agent. Do not rely on identical HTTP error timing between protocols. Responses workflows run their hook -before factory resolution and `parse_input`; without a hook their factories see an empty `request.options`, -but can still inspect `request.request`. Invocations workflows have no option hook. +the agent. Do not rely on identical HTTP error timing between protocols. Workflow hosts have no option hook; +a Responses workflow parser can read translated caller options from `request.options` and forward the ones it +accepts through `WorkflowTurn(client_kwargs={"options": ...})`. Native request-envelope controls such as identity, storage, and continuation fields are not forwarded as generation options. Putting those controls inside `extra_body` raises `ValueError` @@ -724,17 +699,14 @@ workflow runtime rejects before its first superstep, such as an unknown request fails the turn and leaves the lineage head unchanged, so a valid reply can be retried. A failure after a superstep starts blocks that lineage. -**Migration/reset:** pending approvals from the old separate function-approval store are not -migrated. Start a fresh conversation without an old `previous_response_id` or conversation ID and -obtain fresh approvals. Do not copy legacy approval records into session state. -The public `FunctionApprovalStore`, `FoundryFunctionApprovalStore`, and `FunctionApprovalStoreProvider` -exports and the `function_approval_store_provider=` constructor setting are removed. +Pending approvals live in session state. Approvals recorded elsewhere cannot be resumed; start a fresh +conversation and obtain fresh approvals. ## Native Invocations workflows Host a native workflow with an explicit application parser rather than wrapping it with `workflow.as_agent()`, which agent hosts reject (see -[Migrate `WorkflowAgent` hosting](#migrate-workflowagent-hosting)): +[Host workflows natively](#host-workflows-natively)): ```python from agent_framework_foundry_hosting import CheckpointStoreProvider, InvocationsWorkflowHostServer @@ -822,9 +794,8 @@ including the verified `agent_session_id` query alternative when the platform does not configure `FOUNDRY_AGENT_SESSION_ID`. Body/header IDs cannot establish sandbox routing or select private checkpoints. The agent path still uses its separate `invocation_sessions` store, existing hooks/defaults and JSON/`delta` SSE -contract. Agent-only `prepare_options` and -`agent_session_store_provider` are rejected for native workflows rather than -silently reinterpreted. +contract. The workflow host does not accept agent-only settings such as +`prepare_options` or `agent_session_store_provider`. See the [typed Ticket/review example](../../samples/04-hosting/foundry-hosted-agents/invocations/basic/README.md#native-workflow-with-typed-tickets) for the parser, stable graph, checkpoint type allowlist, pending replies, diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py index 63c89c0503b..fb4fc81cc36 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py @@ -4,21 +4,75 @@ from __future__ import annotations -from collections.abc import Awaitable, Callable -from typing import Any +import asyncio +import inspect +import json +import logging +import sys +import weakref +from collections.abc import AsyncGenerator, Awaitable, Callable, Mapping +from contextlib import AbstractAsyncContextManager, AsyncExitStack, asynccontextmanager +from contextvars import Token +from copy import deepcopy +from typing import Any, cast -from agent_framework import SessionStore +from agent_framework import AgentSession, RawAgent, ResponseStream, SessionStore, SupportsAgentRun +from agent_framework._telemetry import mark_feature_used +from azure.ai.agentserver.core import ( + FoundryAgentRequestContext, + get_request_context, + reset_request_context, + set_request_context, +) +from azure.ai.agentserver.invocations import InvocationAgentServerHost from starlette.requests import Request +from starlette.responses import JSONResponse, Response +from ._feature_usage import FeatureIndex from ._invocations_shared import ( - InvocationOptionsHook, - _InvocationsHostServer, # pyright: ignore[reportPrivateUsage] + InvocationStreamingResponse, + hosted_scope, + invocation_failure, + partition_key, + sse_frame, +) +from ._scope import FoundryRequestScope +from ._shared import ( + AgentSource, + InvocationRun, + is_agent, + resolve_agent, + validate_agent_background_options, + validate_agent_source, + validate_default_transport_options, + validate_request_options, + validate_sse_keep_alive_interval, ) -from ._shared import AgentSource, InvocationRun, UnsupportedOptions -from ._state_store import StoreProvider +from ._state_store import AgentSessionStoreProvider, StoreProvider + +logger = logging.getLogger(__name__) + +InvocationParser = Callable[[Request], InvocationRun | Awaitable[InvocationRun]] +InvocationOptionsHook = Callable[[Request, dict[str, Any]], Mapping[str, Any] | Awaitable[Mapping[str, Any]]] +_AGENT_CONTROLLED_FIELDS = frozenset({ + "additional_function_arguments", + "client_kwargs", + "compaction_strategy", + "function_invocation_kwargs", + "instructions", + "middleware", + "session", + "tokenizer", + "tools", +}) -class InvocationsHostServer(_InvocationsHostServer): + +class _IncompatibleRunOptions(TypeError): + """The agent's run method cannot accept the options returned by prepare_options.""" + + +class InvocationsHostServer(InvocationAgentServerHost): """Host an agent with application-defined Invocations turns.""" def __init__( @@ -27,14 +81,17 @@ def __init__( *, openapi_spec: dict[str, Any] | None = None, agent_session_store_provider: StoreProvider[SessionStore] | None = None, - parse_input: Callable[[Request], InvocationRun | Awaitable[InvocationRun]] | None = None, + parse_input: InvocationParser | None = None, prepare_options: InvocationOptionsHook | None = None, - unsupported_options: UnsupportedOptions = "warn", sse_keep_alive_interval_seconds: int | None = None, **agent_server_kwargs: Any, ) -> None: """Create an agent host with session-backed application turns. + By default the host passes only the caller's message to the agent. The agent's own + `default_options` apply unchanged, and caller-supplied options are not forwarded. + Supply `prepare_options` to choose run options per request. + Args: agent: Agent instance or sync/async factory called once per request. Factories must declare a required parameter named `request`, accepting the Starlette `Request` passed by keyword. @@ -49,33 +106,260 @@ def __init__( agent_session_store_provider: Conversation session storage. Defaults to Foundry storage when hosted and file-backed storage locally. Default stores expire 30 days after the last write. parse_input: Sync or async parser returning `InvocationRun`. Without a parser, accept JSON - `message`, optional `options`, and `stream`. - prepare_options: Sync or async hook receiving the request and a copy of caller generation - options. Return the replacement mapping. - Hosting validates protected fields after the hook and before resolving the factory, - unlike Responses factories which run before the hook. Defaults are not mutated. - Invocations has no outer background mode, so hosting never sets `background`; - a `background` value returned by the hook is passed through as the application's choice. - unsupported_options: Policy for agents without runtime options: `"warn"`, `"ignore"`, or `"error"`. + `message`, `stream`, and optional `options`. Parsed options reach the agent only through + `prepare_options`. + prepare_options: Sync or async hook receiving the request and a copy of the parsed caller options. + Its returned mapping is passed to `agent.run(options=...)` and merges over the agent's + `default_options`. Hosting rejects session, tool, middleware, and storage fields after the + hook and before resolving the factory. A `background` value is the application's choice. + The agent's `run` must accept `options`; otherwise the request fails with HTTP 400. sse_keep_alive_interval_seconds: Positive streaming heartbeat interval. If omitted, use a positive `SSE_KEEPALIVE_INTERVAL`, otherwise disable heartbeats. Not a request/model timeout. **agent_server_kwargs: Additional AgentServer SDK constructor arguments, such as - `asyncapi_spec_json` and `asyncapi_spec_yaml`. The host settings listed above (`agent`, - `openapi_spec`, `agent_session_store_provider`, `parse_input`, `prepare_options`, - `unsupported_options`, and `sse_keep_alive_interval_seconds`) are handled directly by this host. + `asyncapi_spec_json` and `asyncapi_spec_yaml`. Raises: TypeError: If the agent source, parser/hook, or heartbeat type is invalid. ValueError: If the heartbeat interval is nonpositive or an injected agent has unsupported background or transport defaults. """ - super().__init__( - agent=agent, - openapi_spec=openapi_spec, - agent_session_store_provider=agent_session_store_provider, - parse_input=parse_input, - prepare_options=prepare_options, - unsupported_options=unsupported_options, - sse_keep_alive_interval_seconds=sse_keep_alive_interval_seconds, - **agent_server_kwargs, + validate_sse_keep_alive_interval(sse_keep_alive_interval_seconds) + validate_agent_source(agent) + if parse_input is not None and not callable(parse_input): + raise TypeError("parse_input must be a callable.") + if prepare_options is not None and not callable(prepare_options): + raise TypeError("prepare_options must be a callable.") + if is_agent(agent): + self._validate_agent_options(agent) + super().__init__(openapi_spec=openapi_spec, **agent_server_kwargs) + if sse_keep_alive_interval_seconds is not None: + self.config.sse_keepalive_interval = sse_keep_alive_interval_seconds + self._agent = agent + self._owns_request_agent = not is_agent(agent) + self._parse_input = parse_input + self._prepare_options = prepare_options + self._session_store_provider = ( + AgentSessionStoreProvider(store_name="invocation_sessions") + if agent_session_store_provider is None + else agent_session_store_provider + ) + self._session_locks: weakref.WeakValueDictionary[str | tuple[str, str], asyncio.Lock] = ( + weakref.WeakValueDictionary() + ) + self.invoke_handler(self._handle_invoke) + mark_feature_used(FeatureIndex.FOUNDRY_HOSTING) + + def _partition_key( + self, + *, + context: FoundryAgentRequestContext | None = None, + scope: FoundryRequestScope | None = None, + ) -> str | tuple[str, str]: + """Get the session partition key for the current request.""" + return partition_key(self.config, get_request_context() if context is None else context, scope) + + @asynccontextmanager + async def _request_agent(self, request: Request) -> AsyncGenerator[SupportsAgentRun]: + agent = await resolve_agent(self._agent, request) + self._validate_agent_options(agent) + async with AsyncExitStack() as resources: + if self._owns_request_agent and isinstance(agent, AbstractAsyncContextManager): + await resources.enter_async_context(agent) + yield agent + + @staticmethod + def _validate_agent_options(agent: SupportsAgentRun) -> None: + validate_agent_background_options(agent, provider_background=False) + if isinstance(agent, RawAgent): + validate_default_transport_options(agent.default_options, allow_agent_store=True) + + @asynccontextmanager + async def _request_session( + self, + partition_key: str | tuple[str, str], + context: FoundryAgentRequestContext, + *, + hosted_scope: FoundryRequestScope | None = None, + ) -> AsyncGenerator[AgentSession]: + session_id = ( + json.dumps(partition_key, separators=(",", ":")) if isinstance(partition_key, tuple) else partition_key + ) + try: + provider = self._session_store_provider + if hosted_scope is not None and not self.config.session_id and type(provider) is AgentSessionStoreProvider: + store = provider._get_scoped_store(context, hosted_scope) # pyright: ignore[reportPrivateUsage] + else: + store = provider.get_store(config=self.config, platform_context=context) + session = await store.get(session_id) + if session is None: + session = AgentSession(session_id=session_id) + except Exception: + logger.exception("Failed to load invocation session") + raise + try: + yield session + finally: + failure = sys.exc_info()[1] + try: + await store.set(session_id, session) + except Exception as exc: + logger.exception("Failed to persist invocation session") + if failure is None: + raise + if isinstance(failure, Exception): + raise RuntimeError( + f"Invocation failed: {str(failure) or type(failure).__name__}; " + f"session persistence also failed: {str(exc) or type(exc).__name__}" + ) from exc + + async def _parse(self, request: Request) -> InvocationRun: + if self._parse_input is not None: + result = self._parse_input(request) + parsed = await result if inspect.isawaitable(result) else result + if not isinstance(parsed, InvocationRun): + raise TypeError("parse_input must return InvocationRun.") + return parsed + + payload = await request.json() + if not isinstance(payload, dict): + raise ValueError("The invocation must be a JSON object.") + body = cast(Mapping[str, Any], payload) + message = body.get("message") + stream = body.get("stream", False) + options = body.get("options", {}) + if not isinstance(message, str): + raise ValueError("message must be a string.") + if not isinstance(stream, bool): + raise ValueError("stream must be a boolean.") + if not isinstance(options, dict): + raise ValueError("options must be an object.") + return InvocationRun( + messages=message if stream else [message], options=cast(Mapping[str, Any], options), stream=stream ) + + async def _options(self, request: Request, parsed: InvocationRun) -> dict[str, Any]: + if self._prepare_options is None: + return {} + result = self._prepare_options(request, deepcopy(dict(parsed.options))) + if inspect.isawaitable(result): + result = await result + if not isinstance(result, Mapping) or any(not isinstance(key, str) for key in result): + raise TypeError("prepare_options must return a mapping of MAF run options with string keys.") + options = deepcopy(dict(result)) + reserved = _AGENT_CONTROLLED_FIELDS.intersection(options) + if reserved: + raise ValueError(f"Invocations options cannot set agent-controlled fields: {', '.join(sorted(reserved))}.") + validate_request_options(options, allow_background=True) + return options + + @staticmethod + def _agent_kwargs(agent: SupportsAgentRun, options: dict[str, Any]) -> dict[str, Any]: + if not options: + return {} + try: + inspect.signature(agent.run).bind_partial(options=options) + except (TypeError, ValueError): + raise _IncompatibleRunOptions( + "The hosted agent does not accept the run options returned by prepare_options." + ) from None + return {"options": options} + + @staticmethod + async def _close_interrupted_stream(stream: object) -> None: + if isinstance(stream, ResponseStream): + close = getattr(cast(object, stream), "close", None) + if close is None: + logger.warning("The installed core cannot close an interrupted agent stream.") + return + else: + close = getattr(stream, "aclose", None) + if close is not None: + await close() + + async def _handle_invoke(self, request: Request) -> Response: + """Invoke the configured agent with a trusted request.""" + context = get_request_context() + try: + request_scope = hosted_scope(self.config, request, context) if self.config.is_hosted else None + key = partition_key(self.config, context, request_scope) + except RuntimeError as exc: + logger.error("Failed to resolve Invocations session: %s", exc) + return JSONResponse({"error": str(exc)}, status_code=500) + + try: + parsed = await self._parse(request) + options = await self._options(request, parsed) + if is_agent(self._agent): + self._agent_kwargs(self._agent, options) + except (TypeError, ValueError) as exc: + return JSONResponse({"error": str(exc)}, status_code=400) + except Exception: + logger.exception("Failed to prepare Invocations request") + return JSONResponse({"error": "Failed to prepare invocation request."}, status_code=500) + + if parsed.stream: + + async def stream_response() -> AsyncGenerator[str]: + token: Token[FoundryAgentRequestContext] | None = set_request_context(context) + try: + lock = self._session_locks.setdefault(key, asyncio.Lock()) + async with lock, self._request_agent(request) as agent: + run_kwargs = self._agent_kwargs(agent, options) + async with self._request_session(key, context, hosted_scope=request_scope) as session: + stream = agent.run(parsed.messages, session=session, stream=True, **run_kwargs) + completed = False + try: + async for update in stream: + if update.text: + # The SDK may close a suspended generator from another task. + reset_request_context(token) + token = None + yield sse_frame("delta", {"text": update.text}) + token = set_request_context(context) + if isinstance(stream, ResponseStream): + await stream.get_final_response() + completed = True + finally: + if not completed: + if token is None: + token = set_request_context(context) + try: + await self._close_interrupted_stream(stream) + except Exception: + logger.exception("Failed to close interrupted Invocations agent stream") + session_id = key[0] if isinstance(key, tuple) else key + if token is not None: + reset_request_context(token) + token = None + yield sse_frame("done", {"session_id": session_id}) + except _IncompatibleRunOptions as exc: + if token is not None: + reset_request_context(token) + token = None + yield sse_frame("error", {"message": str(exc), "code": "invalid_request", "status": 400}) + except Exception as exc: + logger.exception("Invocations agent stream failed") + message, status, code = invocation_failure(exc) + if token is not None: + reset_request_context(token) + token = None + yield sse_frame("error", {"message": message, "code": code, "status": status}) + finally: + if token is not None: + reset_request_context(token) + + return InvocationStreamingResponse(stream_response()) + + try: + lock = self._session_locks.setdefault(key, asyncio.Lock()) + async with lock, self._request_agent(request) as agent: + run_kwargs = self._agent_kwargs(agent, options) + async with self._request_session(key, context, hosted_scope=request_scope) as session: + response = await agent.run(parsed.messages, session=session, **run_kwargs) + return JSONResponse({"response": response.text}) + except _IncompatibleRunOptions as exc: + return JSONResponse({"error": str(exc)}, status_code=400) + except Exception as exc: + logger.exception("Invocations agent request failed") + message, status, _ = invocation_failure(exc) + return JSONResponse({"error": message}, status_code=status) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py index 73a85476e4c..4347c42169e 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py @@ -1,251 +1,27 @@ # Copyright (c) Microsoft. All rights reserved. -"""Share Invocations protocol, state, and execution plumbing between agent and workflow hosts.""" +"""Protocol-neutral Invocations helpers used by the agent and workflow hosts.""" from __future__ import annotations -import asyncio -import inspect import json -import logging -import math -import sys -import uuid -import weakref -from collections.abc import AsyncGenerator, Awaitable, Callable, Mapping, Sequence -from contextlib import AbstractAsyncContextManager, AsyncExitStack, asynccontextmanager -from contextvars import Token -from copy import deepcopy -from dataclasses import asdict, is_dataclass -from typing import Any, cast +from collections.abc import AsyncGenerator, Mapping +from typing import Any -from agent_framework import ( - AgentResponse, - AgentResponseUpdate, - AgentSession, - ChatResponse, - ChatResponseUpdate, - CheckpointStorage, - RawAgent, - ResponseStream, - SessionStore, - SupportsAgentRun, - WorkflowCheckpointException, - WorkflowEvent, -) -from agent_framework._telemetry import mark_feature_used -from anyio import CancelScope -from azure.ai.agentserver.core import ( - FoundryAgentRequestContext, - get_request_context, - reset_request_context, - set_request_context, -) +from azure.ai.agentserver.core import AgentConfig, FoundryAgentRequestContext from azure.ai.agentserver.core.storage import FoundryStorageConflictError, FoundryStoragePreconditionError -from azure.ai.agentserver.invocations import InvocationAgentServerHost -from pydantic import BaseModel from starlette.requests import Request -from starlette.responses import JSONResponse, Response, StreamingResponse +from starlette.responses import StreamingResponse from starlette.types import Receive, Scope, Send -from ._feature_usage import FeatureIndex from ._scope import FoundryRequestScope -from ._shared import ( - AgentSource, - InvocationRun, - UnsupportedOptions, - WorkflowResolver, - WorkflowSource, - WorkflowTurn, - is_agent, - resolve_agent, - validate_agent_background_options, - validate_agent_source, - validate_default_transport_options, - validate_request_options, - validate_sse_keep_alive_interval, - validate_unsupported_options, - workflow_agents, -) -from ._state_store import AgentSessionStoreProvider, CheckpointStoreProvider, ContextScopedStoreProvider, StoreProvider -from ._workflow_state import HostedWorkflowRun, WorkflowBlockedError, WorkflowConflictError -logger = logging.getLogger(__name__) -InvocationParser = Callable[[Request], InvocationRun | WorkflowTurn[Any] | Awaitable[InvocationRun | WorkflowTurn[Any]]] -InvocationOptionsHook = Callable[[Request, dict[str, Any]], Mapping[str, Any] | Awaitable[Mapping[str, Any]]] - -_AGENT_CONTROLLED_FIELDS = frozenset({ - "additional_function_arguments", - "client_kwargs", - "compaction_strategy", - "function_invocation_kwargs", - "instructions", - "middleware", - "session", - "tokenizer", - "tools", -}) -_MAX_WORKFLOW_SNAPSHOT_EVENTS = 4096 -_MAX_WORKFLOW_SNAPSHOT_BYTES = 4 * 1024 * 1024 - - -class _UnsupportedAgentOptions(TypeError): - """The agent cannot accept the caller's run options under the selected policy.""" - - -class _WorkflowOutputError(TypeError): - """Workflow application data cannot be represented as JSON.""" - - -class _WorkflowRequestError(ValueError): - """A validated application request cannot be dispatched to the workflow.""" - - -def _validate_workflow_mapping_keys(value: Any, path: str, active: set[int]) -> None: - if isinstance(value, Mapping): - mapping = cast(Mapping[object, Any], value) - identifier = id(mapping) - if identifier in active: - raise _WorkflowOutputError(f"Workflow output at {path} is not JSON-serializable: circular mapping.") - active.add(identifier) - try: - for index, (key, item) in enumerate(mapping.items()): - if not isinstance(key, str): - raise _WorkflowOutputError( - f"Workflow output at {path} is not JSON-serializable: " - f"mapping keys must be strings, found {type(key).__name__}." - ) - _validate_workflow_mapping_keys(item, f"{path}.value[{index}]", active) - finally: - active.remove(identifier) - elif isinstance(value, (list, tuple)): - sequence = cast(Sequence[Any], value) - identifier = id(sequence) - if identifier in active: - raise _WorkflowOutputError(f"Workflow output at {path} is not JSON-serializable: circular sequence.") - active.add(identifier) - try: - for index, item in enumerate(sequence): - _validate_workflow_mapping_keys(item, f"{path}[{index}]", active) - finally: - active.remove(identifier) - - -def _workflow_serialized_value(value: Any, path: str) -> Any: - if isinstance(value, (AgentResponse, AgentResponseUpdate, ChatResponse, ChatResponseUpdate)): - return value.to_dict(exclude={"continuation_token"}) - if isinstance(value, BaseModel): - _validate_workflow_mapping_keys(value.model_dump(mode="python"), f"{path}.model", set()) - return value.model_dump(mode="json") - if is_dataclass(value) and not isinstance(value, type): - return asdict(value) - to_dict = getattr(value, "to_dict", None) - if callable(to_dict): - return to_dict() - raise _WorkflowOutputError( - f"Workflow output at {path} is not JSON-serializable: unsupported type {type(value).__name__}." - ) - - -def _workflow_json_value(value: Any, path: str, active: set[int]) -> Any: - if value is None or isinstance(value, (str, int, bool)): - return value - if isinstance(value, float): - if not math.isfinite(value): - raise _WorkflowOutputError(f"Workflow output at {path} is not JSON-serializable: number must be finite.") - return value - if isinstance(value, Mapping): - mapping = cast(Mapping[object, Any], value) - identifier = id(mapping) - if identifier in active: - raise _WorkflowOutputError(f"Workflow output at {path} is not JSON-serializable: circular mapping.") - active.add(identifier) - try: - result: dict[str, Any] = {} - for index, (key, item) in enumerate(mapping.items()): - if not isinstance(key, str): - raise _WorkflowOutputError( - f"Workflow output at {path} is not JSON-serializable: " - f"mapping keys must be strings, found {type(key).__name__}." - ) - result[key] = _workflow_json_value(item, f"{path}.value[{index}]", active) - return result - finally: - active.remove(identifier) - if isinstance(value, (list, tuple)): - sequence = cast(Sequence[Any], value) - identifier = id(sequence) - if identifier in active: - raise _WorkflowOutputError(f"Workflow output at {path} is not JSON-serializable: circular sequence.") - active.add(identifier) - try: - return [_workflow_json_value(item, f"{path}[{index}]", active) for index, item in enumerate(sequence)] - finally: - active.remove(identifier) - identifier = id(value) - if identifier in active: - raise _WorkflowOutputError(f"Workflow output at {path} is not JSON-serializable: circular serialized value.") - active.add(identifier) - try: - serialized = _workflow_serialized_value(value, path) - return _workflow_json_value(serialized, f"{path}.serialized", active) - finally: - active.remove(identifier) - - -def _workflow_output(value: Any) -> Any: - """Normalize typed application data without text coercion or skipped values.""" - try: - normalized = _workflow_json_value(value, "$", set()) - return json.loads(json.dumps(normalized, allow_nan=False, ensure_ascii=False).encode("utf-8")) - except _WorkflowOutputError: - raise - except (TypeError, ValueError, RecursionError) as exc: - raise _WorkflowOutputError(f"Workflow output type {type(value).__name__} is not JSON-serializable.") from exc - - -def _workflow_frame(event: WorkflowEvent[Any]) -> dict[str, Any] | None: - if event.type not in ("output", "request_info"): - return None - frame: dict[str, Any] = {"type": event.type, "data": event.data} - if event.type == "request_info": - frame["request_id"] = event.request_id - frame["source_executor_id"] = event.source_executor_id - else: - frame["executor_id"] = event.executor_id - return cast(dict[str, Any], _workflow_output(frame)) - - -def _workflow_snapshot_frames(snapshot: Mapping[str, Any] | None) -> list[dict[str, Any]]: - if snapshot is None or set(snapshot) != {"output"} or not isinstance(snapshot["output"], list): - raise RuntimeError("The stored Invocations workflow output snapshot is invalid.") - frames: list[dict[str, Any]] = [] - for item in cast(list[Any], snapshot["output"]): - if not isinstance(item, Mapping): - raise RuntimeError("The stored Invocations workflow output snapshot is invalid.") - frame = cast(dict[str, Any], _workflow_output(item)) - if frame.get("type") == "output": - if set(frame) != {"type", "data", "executor_id"}: - raise RuntimeError("The stored Invocations workflow output snapshot is invalid.") - elif frame.get("type") == "request_info": - if set(frame) != {"type", "data", "request_id", "source_executor_id"}: - raise RuntimeError("The stored Invocations workflow output snapshot is invalid.") - else: - raise RuntimeError("The stored Invocations workflow output snapshot is invalid.") - frames.append(frame) - return frames - - -def _workflow_frame_size(frame: Mapping[str, Any]) -> int: - return len(json.dumps(frame, ensure_ascii=False, allow_nan=False, separators=(",", ":")).encode("utf-8")) - - -def _sse(event: str, data: Mapping[str, Any]) -> str: +def sse_frame(event: str, data: Mapping[str, Any]) -> str: return f"event: {event}\ndata: {json.dumps(data)}\n\n" -def _invocation_failure(exc: Exception) -> tuple[str, int, str]: +def invocation_failure(exc: Exception) -> tuple[str, int, str]: cause: BaseException | None = exc while cause is not None: if isinstance(cause, (FoundryStorageConflictError, FoundryStoragePreconditionError)): @@ -254,30 +30,7 @@ def _invocation_failure(exc: Exception) -> tuple[str, int, str]: return "Agent invocation failed.", 500, "invocation_failed" -def _workflow_failure(exc: Exception) -> tuple[str, int, str]: - if isinstance(exc, _WorkflowOutputError): - return str(exc), 500, "invalid_workflow_output" - cause: BaseException | None = exc - while cause is not None: - if isinstance(cause, WorkflowBlockedError): - return ( - "This workflow turn was interrupted or failed; start a new Foundry sandbox.", - 409, - "workflow_blocked", - ) - if isinstance(cause, WorkflowConflictError): - return str(cause), 409, "workflow_conflict" - cause = cause.__cause__ - if _invocation_failure(exc)[1] == 409: - return "Another request advanced this workflow; reload before retrying.", 409, "workflow_conflict" - if isinstance(exc, _WorkflowRequestError): - return str(exc), 400, "invalid_workflow_turn" - if isinstance(exc, PermissionError): - return "Workflow state is not available in this trusted scope.", 403, "workflow_scope" - return "Workflow invocation failed.", 500, "workflow_invocation_failed" - - -class _InvocationStreamingResponse(StreamingResponse): +class InvocationStreamingResponse(StreamingResponse): def __init__(self, content: AsyncGenerator[str]) -> None: super().__init__( content, @@ -300,548 +53,59 @@ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: await self._content.aclose() -class _WorkflowStreamingResponse(_InvocationStreamingResponse): - def __init__(self, content: AsyncGenerator[str], *, keep_alive: bool) -> None: - super().__init__(content) - self._keep_alive = keep_alive - - async def stream_response(self, send: Send) -> None: - try: - await super().stream_response(send) - finally: - with CancelScope(shield=True): - if self._keep_alive and self.body_iterator is not self._content: - close = getattr(self.body_iterator, "aclose", None) - if close is None: - raise TypeError("The Invocations SDK stream iterator must support aclose.") - await close() - try: - await self._content.aclose() - finally: - # Without the SDK pump, finish its wrapper in the task that created its context tokens. - async for _ in self.body_iterator: - pass - +def partition_key( + config: AgentConfig, + context: FoundryAgentRequestContext, + scope: FoundryRequestScope | None = None, +) -> str | tuple[str, str]: + """Get the isolation key for the current request. -class _InvocationsHostServer(InvocationAgentServerHost): # pyright: ignore[reportUnusedClass] - """Share protocol, scoped state, and execution plumbing between the public hosts.""" + Hosted keys are a ``(session_id, user_id)`` tuple, so one user cannot reach another user's + state. Locally, the key is the session ID. - def __init__( - self, - agent: AgentSource[Request] | None = None, - *, - workflow: WorkflowSource[Request] | None = None, - openapi_spec: dict[str, Any] | None = None, - agent_session_store_provider: StoreProvider[SessionStore] | None = None, - checkpoint_store_provider: ContextScopedStoreProvider[CheckpointStorage] | None = None, - parse_input: InvocationParser | None = None, - prepare_options: InvocationOptionsHook | None = None, - unsupported_options: UnsupportedOptions = "warn", - sse_keep_alive_interval_seconds: int | None = None, - **agent_server_kwargs: Any, - ) -> None: - """Initialize shared protocol plumbing after the public host selects its execution model.""" - validate_sse_keep_alive_interval(sse_keep_alive_interval_seconds) - unsupported_options = validate_unsupported_options(unsupported_options) - if agent is not None and workflow is not None: - raise TypeError("Provide exactly one of agent or workflow.") - if agent is None and workflow is None: - raise TypeError( - "Provide exactly one of agent or workflow; " - "agent must be an agent instance or a callable that creates one." - ) - if workflow is None: - validate_agent_source(agent) - elif parse_input is None: - raise TypeError("parse_input is required when hosting a native Workflow.") - if parse_input is not None and not callable(parse_input): - raise TypeError("parse_input must be a callable.") - if prepare_options is not None and not callable(prepare_options): - raise TypeError("prepare_options must be a callable.") - if is_agent(agent): - self._validate_agent_options(agent) - if workflow is not None: - if prepare_options is not None: - raise ValueError("prepare_options is agent-only; use the workflow parser's explicit client_kwargs.") - if agent_session_store_provider is not None: - raise ValueError( - "agent_session_store_provider is agent-only; use checkpoint_store_provider for workflows." - ) - self._workflow_resolver: WorkflowResolver[Request] | None = ( - WorkflowResolver(workflow) if workflow is not None else None - ) - super().__init__(openapi_spec=openapi_spec, **agent_server_kwargs) - if sse_keep_alive_interval_seconds is not None: - self.config.sse_keepalive_interval = sse_keep_alive_interval_seconds - self._agent = agent - self._owns_request_agent = agent is not None and not is_agent(agent) - self._parse_input = parse_input - self._prepare_options = prepare_options - self._unsupported_options = unsupported_options - self._session_store_provider = ( - AgentSessionStoreProvider(store_name="invocation_sessions") - if agent_session_store_provider is None - else agent_session_store_provider - ) - self._checkpoint_storage_provider = ( - CheckpointStoreProvider() if checkpoint_store_provider is None else checkpoint_store_provider - ) - self._session_locks: weakref.WeakValueDictionary[str | tuple[str, str], asyncio.Lock] = ( - weakref.WeakValueDictionary() - ) - self.invoke_handler(self._handle_invoke) - mark_feature_used(FeatureIndex.FOUNDRY_HOSTING) - - def _partition_key( - self, - *, - context: FoundryAgentRequestContext | None = None, - scope: FoundryRequestScope | None = None, - ) -> str | tuple[str, str]: - """Get the partition key for the current request. - - A hosted partition key is a tuple containing the session ID and user ID, - preserving their boundaries. Locally, the key is just the session ID. In the - Foundry hosted environment, the partition key is used to maintain isolation between - different sessions and users, such that one user cannot access another user's sessions. - - Returns: - The partition key for the current request. - - Exceptions: - RuntimeError: If the context doesn't contain the expected IDs. - """ - if context is None: - context = get_request_context() - - if self.config.is_hosted: - if not context.user_id: - raise RuntimeError( - "The hosted environment is missing user_id in the request context. " - "Please ensure that the request is coming from a valid Foundry platform service." - ) - hosted_scope = scope or FoundryRequestScope.from_context(self.config, context) - return hosted_scope.session_id, context.user_id - - if not context.session_id: - raise RuntimeError( - "The request context is missing session_id. Please ensure that the request is a valid request." - ) - - return context.session_id - - def _hosted_scope(self, request: Request, context: FoundryAgentRequestContext) -> FoundryRequestScope: - """Accept an unconfigured session only when the routed Invocations query identifies it.""" + Raises: + RuntimeError: If the context does not contain the expected IDs. + """ + if config.is_hosted: if not context.user_id: - raise RuntimeError("The hosted environment is missing user_id in the request context.") - - routed_session_ids = request.query_params.getlist("agent_session_id") - if len(routed_session_ids) > 1: - raise RuntimeError("Hosted Invocations requires exactly one agent_session_id query parameter.") - routed_session_id = routed_session_ids[0] if routed_session_ids else None - if self.config.session_id: - if routed_session_id is not None and routed_session_id != self.config.session_id: - raise RuntimeError("The request agent_session_id does not match the platform session ID.") - return FoundryRequestScope.from_context(self.config, context) - - if not routed_session_id or routed_session_id != context.session_id: raise RuntimeError( - "Hosted Invocations without FOUNDRY_AGENT_SESSION_ID require an explicit routed " - "agent_session_id query parameter matching the request context." + "The hosted environment is missing user_id in the request context. " + "Please ensure that the request is coming from a valid Foundry platform service." ) - if not context.call_id: - raise RuntimeError("Foundry hosted requests require a trusted user ID and call ID.") - return FoundryRequestScope( - session_id=routed_session_id, - user_id=context.user_id, - call_id=context.call_id, - is_hosted=True, - ) - - @asynccontextmanager - async def _request_agent(self, request: Request) -> AsyncGenerator[SupportsAgentRun]: - if self._agent is None: - raise RuntimeError("No agent is configured for Invocations.") - agent = await resolve_agent(self._agent, request) - self._validate_agent_options(agent) - async with AsyncExitStack() as resources: - if self._owns_request_agent and isinstance(agent, AbstractAsyncContextManager): - await resources.enter_async_context(agent) - yield agent + hosted = scope or FoundryRequestScope.from_context(config, context) + return hosted.session_id, context.user_id - @staticmethod - def _validate_agent_options(agent: SupportsAgentRun) -> None: - validate_agent_background_options(agent, provider_background=False) - if isinstance(agent, RawAgent): - validate_default_transport_options(agent.default_options, allow_agent_store=True) - - @asynccontextmanager - async def _request_session( - self, - partition_key: str | tuple[str, str], - context: FoundryAgentRequestContext, - *, - hosted_scope: FoundryRequestScope | None = None, - ) -> AsyncGenerator[AgentSession]: - session_id = ( - json.dumps(partition_key, separators=(",", ":")) if isinstance(partition_key, tuple) else partition_key + if not context.session_id: + raise RuntimeError( + "The request context is missing session_id. Please ensure that the request is a valid request." ) - try: - provider = self._session_store_provider - if hosted_scope is not None and not self.config.session_id and type(provider) is AgentSessionStoreProvider: - store = provider._get_scoped_store(context, hosted_scope) # pyright: ignore[reportPrivateUsage] - else: - store = provider.get_store(config=self.config, platform_context=context) - session = await store.get(session_id) - if session is None: - session = AgentSession(session_id=session_id) - except Exception: - logger.exception("Failed to load invocation session") - raise - try: - yield session - finally: - failure = sys.exc_info()[1] - try: - await store.set(session_id, session) - except Exception as exc: - logger.exception("Failed to persist invocation session") - if failure is None: - raise - if isinstance(failure, Exception): - raise RuntimeError( - f"Invocation failed: {str(failure) or type(failure).__name__}; " - f"session persistence also failed: {str(exc) or type(exc).__name__}" - ) from exc - - async def _parse(self, request: Request) -> InvocationRun | WorkflowTurn[Any]: - if self._parse_input is not None: - result = self._parse_input(request) - parsed = await result if inspect.isawaitable(result) else result - if self._workflow_resolver is not None: - if not isinstance(parsed, WorkflowTurn): - raise TypeError("parse_input must return WorkflowTurn.") - elif not isinstance(parsed, InvocationRun): - raise TypeError("parse_input must return InvocationRun.") - return parsed - - payload = await request.json() - if not isinstance(payload, dict): - raise ValueError("The invocation must be a JSON object.") - body = cast(Mapping[str, Any], payload) - message = body.get("message") - stream = body.get("stream", False) - options = body.get("options", {}) - if not isinstance(message, str): - raise ValueError("message must be a string.") - if not isinstance(stream, bool): - raise ValueError("stream must be a boolean.") - if not isinstance(options, dict): - raise ValueError("options must be an object.") - return InvocationRun( - messages=message if stream else [message], options=cast(Mapping[str, Any], options), stream=stream + return context.session_id + + +def hosted_scope(config: AgentConfig, request: Request, context: FoundryAgentRequestContext) -> FoundryRequestScope: + """Accept an unconfigured session only when the routed Invocations query identifies it.""" + if not context.user_id: + raise RuntimeError("The hosted environment is missing user_id in the request context.") + + routed_session_ids = request.query_params.getlist("agent_session_id") + if len(routed_session_ids) > 1: + raise RuntimeError("Hosted Invocations requires exactly one agent_session_id query parameter.") + routed_session_id = routed_session_ids[0] if routed_session_ids else None + if config.session_id: + if routed_session_id is not None and routed_session_id != config.session_id: + raise RuntimeError("The request agent_session_id does not match the platform session ID.") + return FoundryRequestScope.from_context(config, context) + + if not routed_session_id or routed_session_id != context.session_id: + raise RuntimeError( + "Hosted Invocations without FOUNDRY_AGENT_SESSION_ID require an explicit routed " + "agent_session_id query parameter matching the request context." ) - - async def _options(self, request: Request, parsed: InvocationRun) -> dict[str, Any]: - options: dict[str, Any] = {} - if self._prepare_options is not None: - options = deepcopy(dict(parsed.options)) - result = self._prepare_options(request, options) - if inspect.isawaitable(result): - result = await result - if not isinstance(result, Mapping) or any(not isinstance(key, str) for key in result): - raise TypeError("prepare_options must return a mapping of MAF run options with string keys.") - options = deepcopy(dict(result)) - reserved = _AGENT_CONTROLLED_FIELDS.intersection(options) - if reserved: - raise ValueError(f"Invocations options cannot set agent-controlled fields: {', '.join(sorted(reserved))}.") - validate_request_options(options, allow_background=True) - return options - - def _agent_kwargs(self, agent: SupportsAgentRun, options: dict[str, Any]) -> dict[str, Any]: - if not options: - return {} - try: - inspect.signature(agent.run).bind_partial(options=options) - except (TypeError, ValueError): - if self._unsupported_options == "error": - raise _UnsupportedAgentOptions("The hosted agent does not accept caller runtime options.") from None - if self._unsupported_options == "warn": - logger.warning("Agent doesn't support runtime options. They will be ignored.") - return {} - return {"options": options} - - @staticmethod - async def _close_interrupted_stream(stream: object) -> None: - if isinstance(stream, ResponseStream): - close = getattr(cast(object, stream), "close", None) - if close is None: - logger.warning("The installed core cannot close an interrupted agent stream.") - return - else: - close = getattr(stream, "aclose", None) - if close is not None: - await close() - - async def _handle_invoke(self, request: Request) -> Response: - """Invoke the configured agent or native workflow with a trusted request.""" - context = get_request_context() - try: - hosted_scope = self._hosted_scope(request, context) if self.config.is_hosted else None - partition_key = self._partition_key(context=context, scope=hosted_scope) - except RuntimeError as exc: - logger.error("Failed to resolve Invocations session: %s", exc) - return JSONResponse({"error": str(exc)}, status_code=500) - - try: - parsed = await self._parse(request) - options = await self._options(request, parsed) if isinstance(parsed, InvocationRun) else {} - except (TypeError, ValueError) as exc: - return JSONResponse({"error": str(exc)}, status_code=400) - except Exception: - logger.exception("Failed to prepare Invocations request") - return JSONResponse({"error": "Failed to prepare invocation request."}, status_code=500) - - if isinstance(parsed, WorkflowTurn): - scope = hosted_scope or FoundryRequestScope.from_context(self.config, context) - return await self._handle_workflow(request, parsed, scope, context, partition_key) - - if parsed.stream: - if options and self._unsupported_options == "error" and is_agent(self._agent): - try: - self._agent_kwargs(self._agent, options) - except _UnsupportedAgentOptions as exc: - return JSONResponse({"error": str(exc)}, status_code=400) - - async def stream_response() -> AsyncGenerator[str]: - token: Token[FoundryAgentRequestContext] | None = set_request_context(context) - try: - lock = self._session_locks.setdefault(partition_key, asyncio.Lock()) - async with lock, self._request_agent(request) as agent: - run_kwargs = self._agent_kwargs(agent, options) - async with self._request_session(partition_key, context, hosted_scope=hosted_scope) as session: - stream = agent.run(parsed.messages, session=session, stream=True, **run_kwargs) - completed = False - try: - async for update in stream: - if update.text: - # The SDK may close a suspended generator from another task. - reset_request_context(token) - token = None - yield _sse("delta", {"text": update.text}) - token = set_request_context(context) - if isinstance(stream, ResponseStream): - await stream.get_final_response() - completed = True - finally: - if not completed: - if token is None: - token = set_request_context(context) - try: - await self._close_interrupted_stream(stream) - except Exception: - logger.exception("Failed to close interrupted Invocations agent stream") - session_id = partition_key[0] if isinstance(partition_key, tuple) else partition_key - if token is not None: - reset_request_context(token) - token = None - yield _sse("done", {"session_id": session_id}) - except _UnsupportedAgentOptions as exc: - if token is not None: - reset_request_context(token) - token = None - yield _sse("error", {"message": str(exc), "code": "unsupported_options", "status": 400}) - except Exception as exc: - logger.exception("Invocations agent stream failed") - message, status, code = _invocation_failure(exc) - if token is not None: - reset_request_context(token) - token = None - yield _sse("error", {"message": message, "code": code, "status": status}) - finally: - if token is not None: - reset_request_context(token) - - return _InvocationStreamingResponse(stream_response()) - - try: - lock = self._session_locks.setdefault(partition_key, asyncio.Lock()) - async with lock, self._request_agent(request) as agent: - run_kwargs = self._agent_kwargs(agent, options) - async with self._request_session(partition_key, context, hosted_scope=hosted_scope) as session: - response = await agent.run(parsed.messages, session=session, **run_kwargs) - return JSONResponse({"response": response.text}) - except _UnsupportedAgentOptions as exc: - return JSONResponse({"error": str(exc)}, status_code=400) - except Exception as exc: - logger.exception("Invocations agent request failed") - message, status, _ = _invocation_failure(exc) - return JSONResponse({"error": message}, status_code=status) - - async def _handle_workflow( - self, - request: Request, - turn: WorkflowTurn[Any], - scope: FoundryRequestScope, - context: FoundryAgentRequestContext, - partition_key: str | tuple[str, str], - ) -> Response: - if turn.stream: - - async def stream_response() -> AsyncGenerator[str]: - token: Token[FoundryAgentRequestContext] | None = set_request_context(context) - events = self._workflow_events(request, turn, scope, context, partition_key) - try: - async for frame in events: - wire_frame = _sse(frame["type"], frame) - reset_request_context(token) - token = None - yield wire_frame - token = set_request_context(context) - reset_request_context(token) - token = None - yield _sse("done", {"session_id": scope.session_id}) - except Exception as exc: - logger.exception("Invocations workflow stream failed") - message, status, code = _workflow_failure(exc) - if token is not None: - reset_request_context(token) - token = None - yield _sse("error", {"message": message, "code": code, "status": status}) - finally: - if token is None: - token = set_request_context(context) - try: - with CancelScope(shield=True): - await events.aclose() - finally: - reset_request_context(token) - - return _WorkflowStreamingResponse(stream_response(), keep_alive=self.config.sse_keepalive_interval > 0) - - try: - frames = [frame async for frame in self._workflow_events(request, turn, scope, context, partition_key)] - return JSONResponse({"output": frames}) - except Exception as exc: - logger.exception("Invocations workflow request failed") - message, status, _ = _workflow_failure(exc) - return JSONResponse({"error": message}, status_code=status) - - async def _workflow_events( - self, - request: Request, - turn: WorkflowTurn[Any], - scope: FoundryRequestScope, - context: FoundryAgentRequestContext, - partition_key: str | tuple[str, str], - ) -> AsyncGenerator[dict[str, Any]]: - resolver = self._workflow_resolver - if resolver is None: - raise RuntimeError("No native workflow is configured for Invocations.") - frames: list[dict[str, Any]] = [] - snapshot_bytes = 0 - deferred: list[dict[str, Any]] = [] - defer = False - lock = self._session_locks.setdefault(partition_key, asyncio.Lock()) - async with lock: - workflow = await resolver.resolve(request) - run = await HostedWorkflowRun.prepare( - workflow, - scope=scope, - response_id=context.call_id or uuid.uuid4().hex, - config=self.config, - platform_context=context, - checkpoint_store_provider=self._checkpoint_storage_provider, - lineage_id="invocations", - stored=True, - replay_completed=True, - fresh_factory=True, - reclaim_superseded=True, - ) - if run.has_completed_output: - for frame in _workflow_snapshot_frames(run.snapshot): - yield frame - return - try: - turn = run.validate_turn(turn) - except (TypeError, ValueError) as exc: - raise _WorkflowRequestError(str(exc)) from exc - if ( - run.stored - and turn.input is not None - and isinstance(self._checkpoint_storage_provider, CheckpointStoreProvider) - ): - try: - self._checkpoint_storage_provider.validate_checkpoint_value(turn.input) - except WorkflowCheckpointException as exc: - raise _WorkflowRequestError( - "Stored native workflow input uses an application type that is not checkpoint-allowlisted. " - 'Configure CheckpointStoreProvider(allowed_checkpoint_types=["module:qualname"]).' - ) from exc - if ( - run.stored - and turn.responses is not None - and isinstance(self._checkpoint_storage_provider, CheckpointStoreProvider) - ): - try: - for reply in turn.responses.values(): - self._checkpoint_storage_provider.validate_checkpoint_value(reply) - except WorkflowCheckpointException as exc: - raise _WorkflowRequestError( - "Stored native workflow reply uses an application type that is not checkpoint-allowlisted. " - 'Configure CheckpointStoreProvider(allowed_checkpoint_types=["module:qualname"]).' - ) from exc - committed = False - resources = AsyncExitStack() - try: - await run.claim() - try: - entered: set[int] = set() - for agent in workflow_agents(workflow): - if id(agent) not in entered and isinstance(agent, AbstractAsyncContextManager): - entered.add(id(agent)) - await resources.enter_async_context(agent) - events = run.events(turn) - resources.push_async_callback(events.aclose) - async for event in events: - frame = _workflow_frame(event) - if frame is None: - continue - frame_size = _workflow_frame_size(frame) - if ( - len(frames) >= _MAX_WORKFLOW_SNAPSHOT_EVENTS - or snapshot_bytes + frame_size > _MAX_WORKFLOW_SNAPSHOT_BYTES - ): - raise _WorkflowOutputError( - "Workflow output exceeds the bounded Invocations snapshot limit." - ) - snapshot_bytes += frame_size - frames.append(frame) - defer = defer or event.type == "request_info" - if defer: - deferred.append(frame) - else: - yield frame - finally: - # Starlette cancellation must not interrupt core/resource cleanup. - with CancelScope(shield=True): - await resources.__aexit__(*sys.exc_info()) - await run.commit({"output": frames}) - committed = True - finally: - if not committed: - failure = sys.exc_info()[1] - try: - with CancelScope(shield=True): - await run.abort() - except Exception as exc: - logger.exception("Failed to persist interrupted Invocations workflow state") - if failure is None: - raise - if isinstance(failure, Exception): - raise RuntimeError( - "Workflow invocation failed and its interrupted state could not be persisted." - ) from exc - # Pending reply authority is durable, and a reply need not wait on this stream's lock. - for frame in deferred: - yield frame + if not context.call_id: + raise RuntimeError("Foundry hosted requests require a trusted user ID and call ID.") + return FoundryRequestScope( + session_id=routed_session_id, + user_id=context.user_id, + call_id=context.call_id, + is_hosted=True, + ) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py index f5e33b163d4..15f2b858250 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py @@ -4,25 +4,265 @@ from __future__ import annotations -from collections.abc import Awaitable, Callable -from typing import Any +import asyncio +import inspect +import json +import logging +import math +import sys +import uuid +import weakref +from collections.abc import AsyncGenerator, Awaitable, Callable, Mapping, Sequence +from contextlib import AbstractAsyncContextManager, AsyncExitStack +from contextvars import Token +from dataclasses import asdict, is_dataclass +from typing import Any, cast -from agent_framework import CheckpointStorage +from agent_framework import ( + AgentResponse, + AgentResponseUpdate, + ChatResponse, + ChatResponseUpdate, + CheckpointStorage, + WorkflowCheckpointException, + WorkflowEvent, +) +from agent_framework._telemetry import mark_feature_used +from anyio import CancelScope +from azure.ai.agentserver.core import ( + FoundryAgentRequestContext, + get_request_context, + reset_request_context, + set_request_context, +) +from azure.ai.agentserver.invocations import InvocationAgentServerHost +from pydantic import BaseModel from starlette.requests import Request +from starlette.responses import JSONResponse, Response +from starlette.types import Send -from ._invocations_shared import _InvocationsHostServer # pyright: ignore[reportPrivateUsage] -from ._shared import WorkflowSource, WorkflowTurn -from ._state_store import ContextScopedStoreProvider +from ._feature_usage import FeatureIndex +from ._invocations_shared import ( + InvocationStreamingResponse, + hosted_scope, + invocation_failure, + partition_key, + sse_frame, +) +from ._scope import FoundryRequestScope +from ._shared import WorkflowResolver, WorkflowSource, WorkflowTurn, validate_sse_keep_alive_interval, workflow_agents +from ._state_store import CheckpointStoreProvider, ContextScopedStoreProvider +from ._workflow_state import HostedWorkflowRun, WorkflowBlockedError, WorkflowConflictError +logger = logging.getLogger(__name__) -class InvocationsWorkflowHostServer(_InvocationsHostServer): +WorkflowParser = Callable[[Request], WorkflowTurn[Any] | Awaitable[WorkflowTurn[Any]]] + +_MAX_WORKFLOW_SNAPSHOT_EVENTS = 4096 +_MAX_WORKFLOW_SNAPSHOT_BYTES = 4 * 1024 * 1024 + + +class _WorkflowOutputError(TypeError): + """Workflow application data cannot be represented as JSON.""" + + +class _WorkflowRequestError(ValueError): + """A validated application request cannot be dispatched to the workflow.""" + + +def _validate_workflow_mapping_keys(value: Any, path: str, active: set[int]) -> None: + if isinstance(value, Mapping): + mapping = cast(Mapping[object, Any], value) + identifier = id(mapping) + if identifier in active: + raise _WorkflowOutputError(f"Workflow output at {path} is not JSON-serializable: circular mapping.") + active.add(identifier) + try: + for index, (key, item) in enumerate(mapping.items()): + if not isinstance(key, str): + raise _WorkflowOutputError( + f"Workflow output at {path} is not JSON-serializable: " + f"mapping keys must be strings, found {type(key).__name__}." + ) + _validate_workflow_mapping_keys(item, f"{path}.value[{index}]", active) + finally: + active.remove(identifier) + elif isinstance(value, (list, tuple)): + sequence = cast(Sequence[Any], value) + identifier = id(sequence) + if identifier in active: + raise _WorkflowOutputError(f"Workflow output at {path} is not JSON-serializable: circular sequence.") + active.add(identifier) + try: + for index, item in enumerate(sequence): + _validate_workflow_mapping_keys(item, f"{path}[{index}]", active) + finally: + active.remove(identifier) + + +def _workflow_serialized_value(value: Any, path: str) -> Any: + if isinstance(value, (AgentResponse, AgentResponseUpdate, ChatResponse, ChatResponseUpdate)): + return value.to_dict(exclude={"continuation_token"}) + if isinstance(value, BaseModel): + _validate_workflow_mapping_keys(value.model_dump(mode="python"), f"{path}.model", set()) + return value.model_dump(mode="json") + if is_dataclass(value) and not isinstance(value, type): + return asdict(value) + to_dict = getattr(value, "to_dict", None) + if callable(to_dict): + return to_dict() + raise _WorkflowOutputError( + f"Workflow output at {path} is not JSON-serializable: unsupported type {type(value).__name__}." + ) + + +def _workflow_json_value(value: Any, path: str, active: set[int]) -> Any: + if value is None or isinstance(value, (str, int, bool)): + return value + if isinstance(value, float): + if not math.isfinite(value): + raise _WorkflowOutputError(f"Workflow output at {path} is not JSON-serializable: number must be finite.") + return value + if isinstance(value, Mapping): + mapping = cast(Mapping[object, Any], value) + identifier = id(mapping) + if identifier in active: + raise _WorkflowOutputError(f"Workflow output at {path} is not JSON-serializable: circular mapping.") + active.add(identifier) + try: + result: dict[str, Any] = {} + for index, (key, item) in enumerate(mapping.items()): + if not isinstance(key, str): + raise _WorkflowOutputError( + f"Workflow output at {path} is not JSON-serializable: " + f"mapping keys must be strings, found {type(key).__name__}." + ) + result[key] = _workflow_json_value(item, f"{path}.value[{index}]", active) + return result + finally: + active.remove(identifier) + if isinstance(value, (list, tuple)): + sequence = cast(Sequence[Any], value) + identifier = id(sequence) + if identifier in active: + raise _WorkflowOutputError(f"Workflow output at {path} is not JSON-serializable: circular sequence.") + active.add(identifier) + try: + return [_workflow_json_value(item, f"{path}[{index}]", active) for index, item in enumerate(sequence)] + finally: + active.remove(identifier) + identifier = id(value) + if identifier in active: + raise _WorkflowOutputError(f"Workflow output at {path} is not JSON-serializable: circular serialized value.") + active.add(identifier) + try: + serialized = _workflow_serialized_value(value, path) + return _workflow_json_value(serialized, f"{path}.serialized", active) + finally: + active.remove(identifier) + + +def _workflow_output(value: Any) -> Any: + """Normalize typed application data without text coercion or skipped values.""" + try: + normalized = _workflow_json_value(value, "$", set()) + return json.loads(json.dumps(normalized, allow_nan=False, ensure_ascii=False).encode("utf-8")) + except _WorkflowOutputError: + raise + except (TypeError, ValueError, RecursionError) as exc: + raise _WorkflowOutputError(f"Workflow output type {type(value).__name__} is not JSON-serializable.") from exc + + +def _workflow_frame(event: WorkflowEvent[Any]) -> dict[str, Any] | None: + if event.type not in ("output", "request_info"): + return None + frame: dict[str, Any] = {"type": event.type, "data": event.data} + if event.type == "request_info": + frame["request_id"] = event.request_id + frame["source_executor_id"] = event.source_executor_id + else: + frame["executor_id"] = event.executor_id + return cast(dict[str, Any], _workflow_output(frame)) + + +def _workflow_snapshot_frames(snapshot: Mapping[str, Any] | None) -> list[dict[str, Any]]: + if snapshot is None or set(snapshot) != {"output"} or not isinstance(snapshot["output"], list): + raise RuntimeError("The stored Invocations workflow output snapshot is invalid.") + frames: list[dict[str, Any]] = [] + for item in cast(list[Any], snapshot["output"]): + if not isinstance(item, Mapping): + raise RuntimeError("The stored Invocations workflow output snapshot is invalid.") + frame = cast(dict[str, Any], _workflow_output(item)) + if frame.get("type") == "output": + if set(frame) != {"type", "data", "executor_id"}: + raise RuntimeError("The stored Invocations workflow output snapshot is invalid.") + elif frame.get("type") == "request_info": + if set(frame) != {"type", "data", "request_id", "source_executor_id"}: + raise RuntimeError("The stored Invocations workflow output snapshot is invalid.") + else: + raise RuntimeError("The stored Invocations workflow output snapshot is invalid.") + frames.append(frame) + return frames + + +def _workflow_frame_size(frame: Mapping[str, Any]) -> int: + return len(json.dumps(frame, ensure_ascii=False, allow_nan=False, separators=(",", ":")).encode("utf-8")) + + +def _workflow_failure(exc: Exception) -> tuple[str, int, str]: + if isinstance(exc, _WorkflowOutputError): + return str(exc), 500, "invalid_workflow_output" + cause: BaseException | None = exc + while cause is not None: + if isinstance(cause, WorkflowBlockedError): + return ( + "This workflow turn was interrupted or failed; start a new Foundry sandbox.", + 409, + "workflow_blocked", + ) + if isinstance(cause, WorkflowConflictError): + return str(cause), 409, "workflow_conflict" + cause = cause.__cause__ + if invocation_failure(exc)[1] == 409: + return "Another request advanced this workflow; reload before retrying.", 409, "workflow_conflict" + if isinstance(exc, _WorkflowRequestError): + return str(exc), 400, "invalid_workflow_turn" + if isinstance(exc, PermissionError): + return "Workflow state is not available in this trusted scope.", 403, "workflow_scope" + return "Workflow invocation failed.", 500, "workflow_invocation_failed" + + +class _WorkflowStreamingResponse(InvocationStreamingResponse): + def __init__(self, content: AsyncGenerator[str], *, keep_alive: bool) -> None: + super().__init__(content) + self._keep_alive = keep_alive + + async def stream_response(self, send: Send) -> None: + try: + await super().stream_response(send) + finally: + with CancelScope(shield=True): + if self._keep_alive and self.body_iterator is not self._content: + close = getattr(self.body_iterator, "aclose", None) + if close is None: + raise TypeError("The Invocations SDK stream iterator must support aclose.") + await close() + try: + await self._content.aclose() + finally: + # Without the SDK pump, finish its wrapper in the task that created its context tokens. + async for _ in self.body_iterator: + pass + + +class InvocationsWorkflowHostServer(InvocationAgentServerHost): """Host a native, checkpoint-owned workflow with application-defined Invocations turns.""" def __init__( self, workflow: WorkflowSource[Request], *, - parse_input: Callable[[Request], WorkflowTurn[Any] | Awaitable[WorkflowTurn[Any]]], + parse_input: WorkflowParser, openapi_spec: dict[str, Any] | None = None, checkpoint_store_provider: ContextScopedStoreProvider[CheckpointStorage] | None = None, sse_keep_alive_interval_seconds: int | None = None, @@ -37,27 +277,230 @@ def __init__( agents; applications own other resource cleanup. Known shared execution resources are rejected. Keyword Args: - parse_input: Sync or async parser returning typed `WorkflowTurn` input or a complete pending - reply batch. The application validates the request and explicitly supplies workflow kwargs. + parse_input: Required sync or async parser returning typed `WorkflowTurn` input or a complete + pending reply batch. The parser validates the request and explicitly supplies any workflow + kwargs; the host never converts the request body on its own. openapi_spec: Application OpenAPI specification forwarded to AgentServer. checkpoint_store_provider: Scoped checkpoint storage. Defaults to `CheckpointStoreProvider`. - Native workflow history and pending replies are checkpoint-owned, not agent-session-owned. + Native workflow history and pending replies are checkpoint-owned. sse_keep_alive_interval_seconds: Positive streaming heartbeat interval. If omitted, use a positive `SSE_KEEPALIVE_INTERVAL`, otherwise disable heartbeats. Not a request/model timeout. **agent_server_kwargs: Additional AgentServer SDK constructor arguments, such as `asyncapi_spec_json` and `asyncapi_spec_yaml`. Output uses JSON or framed SSE workflow events. Raises: - TypeError: If the workflow is not a request-aware factory, or the parser or heartbeat type is invalid. + TypeError: If the workflow is not a request-aware factory, the parser is not callable, or the + heartbeat type is invalid. ValueError: If the heartbeat interval is nonpositive. """ if not callable(parse_input): - raise TypeError("parse_input must be a callable.") - super().__init__( - workflow=workflow, - parse_input=parse_input, - openapi_spec=openapi_spec, - checkpoint_store_provider=checkpoint_store_provider, - sse_keep_alive_interval_seconds=sse_keep_alive_interval_seconds, - **agent_server_kwargs, + raise TypeError("parse_input must be a callable returning WorkflowTurn.") + validate_sse_keep_alive_interval(sse_keep_alive_interval_seconds) + self._workflow_resolver: WorkflowResolver[Request] = WorkflowResolver(workflow) + super().__init__(openapi_spec=openapi_spec, **agent_server_kwargs) + if sse_keep_alive_interval_seconds is not None: + self.config.sse_keepalive_interval = sse_keep_alive_interval_seconds + self._parse_input = parse_input + self._checkpoint_storage_provider = ( + CheckpointStoreProvider() if checkpoint_store_provider is None else checkpoint_store_provider + ) + self._session_locks: weakref.WeakValueDictionary[str | tuple[str, str], asyncio.Lock] = ( + weakref.WeakValueDictionary() ) + self.invoke_handler(self._handle_invoke) + mark_feature_used(FeatureIndex.FOUNDRY_HOSTING) + + async def _parse(self, request: Request) -> WorkflowTurn[Any]: + result = self._parse_input(request) + parsed = await result if inspect.isawaitable(result) else result + if not isinstance(parsed, WorkflowTurn): + raise TypeError("parse_input must return WorkflowTurn.") + return parsed + + async def _handle_invoke(self, request: Request) -> Response: + """Run the native workflow for one trusted request.""" + context = get_request_context() + try: + scope = hosted_scope(self.config, request, context) if self.config.is_hosted else None + key = partition_key(self.config, context, scope) + except RuntimeError as exc: + logger.error("Failed to resolve Invocations session: %s", exc) + return JSONResponse({"error": str(exc)}, status_code=500) + + try: + turn = await self._parse(request) + except (TypeError, ValueError) as exc: + return JSONResponse({"error": str(exc)}, status_code=400) + except Exception: + logger.exception("Failed to prepare Invocations request") + return JSONResponse({"error": "Failed to prepare invocation request."}, status_code=500) + + return await self._handle_workflow( + request, turn, scope or FoundryRequestScope.from_context(self.config, context), context, key + ) + + async def _handle_workflow( + self, + request: Request, + turn: WorkflowTurn[Any], + scope: FoundryRequestScope, + context: FoundryAgentRequestContext, + partition_key: str | tuple[str, str], + ) -> Response: + if turn.stream: + + async def stream_response() -> AsyncGenerator[str]: + token: Token[FoundryAgentRequestContext] | None = set_request_context(context) + events = self._workflow_events(request, turn, scope, context, partition_key) + try: + async for frame in events: + wire_frame = sse_frame(frame["type"], frame) + reset_request_context(token) + token = None + yield wire_frame + token = set_request_context(context) + reset_request_context(token) + token = None + yield sse_frame("done", {"session_id": scope.session_id}) + except Exception as exc: + logger.exception("Invocations workflow stream failed") + message, status, code = _workflow_failure(exc) + if token is not None: + reset_request_context(token) + token = None + yield sse_frame("error", {"message": message, "code": code, "status": status}) + finally: + if token is None: + token = set_request_context(context) + try: + with CancelScope(shield=True): + await events.aclose() + finally: + reset_request_context(token) + + return _WorkflowStreamingResponse(stream_response(), keep_alive=self.config.sse_keepalive_interval > 0) + + try: + frames = [frame async for frame in self._workflow_events(request, turn, scope, context, partition_key)] + return JSONResponse({"output": frames}) + except Exception as exc: + logger.exception("Invocations workflow request failed") + message, status, _ = _workflow_failure(exc) + return JSONResponse({"error": message}, status_code=status) + + async def _workflow_events( + self, + request: Request, + turn: WorkflowTurn[Any], + scope: FoundryRequestScope, + context: FoundryAgentRequestContext, + partition_key: str | tuple[str, str], + ) -> AsyncGenerator[dict[str, Any]]: + resolver = self._workflow_resolver + frames: list[dict[str, Any]] = [] + snapshot_bytes = 0 + deferred: list[dict[str, Any]] = [] + defer = False + lock = self._session_locks.setdefault(partition_key, asyncio.Lock()) + async with lock: + workflow = await resolver.resolve(request) + run = await HostedWorkflowRun.prepare( + workflow, + scope=scope, + response_id=context.call_id or uuid.uuid4().hex, + config=self.config, + platform_context=context, + checkpoint_store_provider=self._checkpoint_storage_provider, + lineage_id="invocations", + stored=True, + replay_completed=True, + fresh_factory=True, + reclaim_superseded=True, + ) + if run.has_completed_output: + for frame in _workflow_snapshot_frames(run.snapshot): + yield frame + return + try: + turn = run.validate_turn(turn) + except (TypeError, ValueError) as exc: + raise _WorkflowRequestError(str(exc)) from exc + if ( + run.stored + and turn.input is not None + and isinstance(self._checkpoint_storage_provider, CheckpointStoreProvider) + ): + try: + self._checkpoint_storage_provider.validate_checkpoint_value(turn.input) + except WorkflowCheckpointException as exc: + raise _WorkflowRequestError( + "Stored native workflow input uses an application type that is not checkpoint-allowlisted. " + 'Configure CheckpointStoreProvider(allowed_checkpoint_types=["module:qualname"]).' + ) from exc + if ( + run.stored + and turn.responses is not None + and isinstance(self._checkpoint_storage_provider, CheckpointStoreProvider) + ): + try: + for reply in turn.responses.values(): + self._checkpoint_storage_provider.validate_checkpoint_value(reply) + except WorkflowCheckpointException as exc: + raise _WorkflowRequestError( + "Stored native workflow reply uses an application type that is not checkpoint-allowlisted. " + 'Configure CheckpointStoreProvider(allowed_checkpoint_types=["module:qualname"]).' + ) from exc + committed = False + resources = AsyncExitStack() + try: + await run.claim() + try: + entered: set[int] = set() + for agent in workflow_agents(workflow): + if id(agent) not in entered and isinstance(agent, AbstractAsyncContextManager): + entered.add(id(agent)) + await resources.enter_async_context(agent) + events = run.events(turn) + resources.push_async_callback(events.aclose) + async for event in events: + frame = _workflow_frame(event) + if frame is None: + continue + frame_size = _workflow_frame_size(frame) + if ( + len(frames) >= _MAX_WORKFLOW_SNAPSHOT_EVENTS + or snapshot_bytes + frame_size > _MAX_WORKFLOW_SNAPSHOT_BYTES + ): + raise _WorkflowOutputError( + "Workflow output exceeds the bounded Invocations snapshot limit." + ) + snapshot_bytes += frame_size + frames.append(frame) + defer = defer or event.type == "request_info" + if defer: + deferred.append(frame) + else: + yield frame + finally: + # Starlette cancellation must not interrupt core/resource cleanup. + with CancelScope(shield=True): + await resources.__aexit__(*sys.exc_info()) + await run.commit({"output": frames}) + committed = True + finally: + if not committed: + failure = sys.exc_info()[1] + try: + with CancelScope(shield=True): + await run.abort() + except Exception as exc: + logger.exception("Failed to persist interrupted Invocations workflow state") + if failure is None: + raise + if isinstance(failure, Exception): + raise RuntimeError( + "Workflow invocation failed and its interrupted state could not be persisted." + ) from exc + # Pending reply authority is durable, and a reply need not wait on this stream's lock. + for frame in deferred: + yield frame diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py index 05a56404222..f012e8b8714 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py @@ -5,6 +5,7 @@ from __future__ import annotations import asyncio +import inspect import logging from collections.abc import ( AsyncGenerator, @@ -84,8 +85,7 @@ AgentSource, OptionsHook, ResponsesRequest, - UnsupportedOptions, - build_response_server_options, + build_agent_response_server_options, is_agent, prepare_response_options, resolve_agent, @@ -94,7 +94,6 @@ validate_agent_source, validate_default_transport_options, validate_request_options, - validate_unsupported_options, ) from ._state_store import ( AgentSessionStoreProvider, @@ -255,7 +254,6 @@ def __init__( shutdown_grace_period_seconds: int = 10, enable_background_recovery: bool = False, prepare_options: OptionsHook | None = None, - unsupported_options: UnsupportedOptions = "warn", **kwargs: Any, ) -> None: """Initialize a ResponsesHostServer. @@ -309,20 +307,20 @@ def __init__( DELETE waits for response persistence. Defaults to 10 seconds. enable_background_recovery: Allow eligible provider-background work to recover after shutdown. Defaults to `False`; it does not enable background execution or guarantee exactly-once effects. - prepare_options: Developer hook selecting caller model options after factory resolution. - Only its returned, validated mapping is forwarded. Without a hook, caller options are omitted. + prepare_options: Optional sync or async hook selecting run options after factory resolution. + Without a hook, only the caller's input messages reach the agent and the agent's own + `default_options` apply unchanged. With a hook, only its returned, validated mapping is + forwarded; an agent whose `run` cannot accept `options` fails the request. A returned `background` value is application-owned on ordinary runs. Host-selected provider background submission and polling retain `background=True`. - unsupported_options: `"warn"` (default), `"error"`, or `"ignore"` when a custom agent - cannot accept runtime model options. - **kwargs: Additional keyword arguments. + **kwargs: Additional AgentServer SDK constructor arguments. Note: The *caller* controls outer persistence with `POST /responses` `store=True/False`. `store=False` writes no host-managed session or approval state and forces supported inner clients not to store, regardless of `history_source`. The constructor's `response_store=` argument selects the outer response-store backend. - The former constructor `store=` alias is rejected. Outer `response.id` is the polling/continuation handle; + Outer `response.id` is the polling/continuation handle; any inner `service_session_id` is private and never replaces it. 1. Context providers must not keep required state only on their Python instances, @@ -337,29 +335,20 @@ def __init__( For provider background, only a saved private continuation token can be polled after a crash; a crash before the token is saved cannot be replayed safely. Other regular-agent runs are not crash-recoverable. - 4. Steering is unavailable. The upstream `options` bag and steering settings are not host parameters. - 5. A stored, named `"inference_service"` or `"agent_managed"` conversation is claimed in the scoped + 4. A stored, named `"inference_service"` or `"agent_managed"` conversation is claimed in the scoped session store before the agent runs. Conditional writes prevent a concurrent turn from mutating the same provider thread. If the turn fails or is cancelled, start a new conversation instead of reusing a potentially changed downstream thread. Raises: - TypeError: If the agent is a `WorkflowAgent`, or native workflow settings are supplied. - ValueError: If the history, background, or unsupported-options policy is invalid. + TypeError: If the agent is a `WorkflowAgent` or `prepare_options` is not callable. + ValueError: If the history or background settings are invalid. RuntimeError: If the agent configuration conflicts with the selected history or background source. """ - if "function_approval_store_provider" in kwargs: - raise TypeError("Approval state is managed by agent_session_store_provider.") - if "store" in kwargs: - raise TypeError("The constructor store= alias was removed; use response_store= instead.") - if {"workflow", "parse_input", "parse_response", "checkpoint_store_provider"}.intersection(kwargs): - raise TypeError("Use ResponsesWorkflowHostServer for native workflows and checkpoint storage.") validate_agent_source(agent) if prepare_options is not None and not callable(prepare_options): raise TypeError("prepare_options must be a callable.") - unsupported_options = validate_unsupported_options(unsupported_options) - options = build_response_server_options( - is_workflow=False, + options = build_agent_response_server_options( history_source=history_source, background_source=background_source, max_history_items=max_history_items, @@ -395,7 +384,6 @@ def __init__( self._history_source: _HistorySource = history_source self._background_source: Literal["host_managed", "inference_service"] = background_source self._prepare_options = prepare_options - self._unsupported_options = unsupported_options self._host_options = options self._uses_agent_server_history = ( configuration.agent_server_history if configuration is not None else history_source == "host_managed" @@ -497,6 +485,14 @@ async def _handle_response( await prepare_response_options(hosted_request, self._prepare_options) try: validate_request_options(hosted_request.options, allow_background=True) + run_method: Any = agent.run + if hosted_request.options and not isinstance(cast(object, agent), RawAgent): + try: + inspect.signature(run_method).bind_partial(options=hosted_request.options) + except TypeError: + raise TypeError( + "The hosted agent does not accept the run options returned by prepare_options." + ) from None _validate_agent_defaults( agent, provider_background=provider_background, @@ -1034,13 +1030,8 @@ async def _handle_inner_agent( ): chat_options["store"] = False - if isinstance(agent, RawAgent): + if isinstance(agent, RawAgent) or are_options_set: run_kwargs["options"] = chat_options - elif are_options_set: - if self._unsupported_options == "error": - raise _PublicResponseFailure(TypeError("The hosted agent does not accept caller runtime options.")) - if self._unsupported_options == "warn": - logger.warning("Agent doesn't support runtime options. They will be ignored.") if previous_response_id is not None and context.conversation_id is None and not context.is_recovery: if ( @@ -1219,9 +1210,6 @@ async def track_update( ) ) ) - superseded_by_steering = bool(self._host_options and self._host_options.steerable_conversations) and ( - cancellation_signal.is_set() and not context.client_cancelled and not context.shutdown.is_set() - ) if stored and session_storage is not None and not stored_output_violation and final_provider_state: if context.conversation_id is not None: session.state[_HOSTED_SOURCE_CONVERSATION_KEY] = context.conversation_id @@ -1229,7 +1217,6 @@ async def track_update( if ( context.conversation_id is not None and not conversation_already_committed - and not superseded_by_steering and not request_interrupted and request_failure is None and ( diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py index eb9d74884d0..58eb4746bad 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py @@ -58,16 +58,13 @@ ) from ._scope import FoundryRequestScope from ._shared import ( - OptionsHook, ResponsesRequest, WorkflowResolver, WorkflowSource, WorkflowTurn, - build_response_server_options, - prepare_response_options, + build_workflow_response_server_options, prepare_workflow_kwargs, response_run_options, - validate_request_options, validate_workflow_source, workflow_agents, ) @@ -333,7 +330,6 @@ def __init__( prefix: str = "", response_store: ResponseProviderProtocol | None = None, checkpoint_store_provider: ContextScopedStoreProvider[CheckpointStorage] | None = None, - prepare_options: OptionsHook | None = None, allowed_oauth_consent_origins: Sequence[str] | None = None, sse_keep_alive_interval_seconds: int | None = None, shutdown_grace_period_seconds: int = 10, @@ -355,10 +351,6 @@ def __init__( response_store: Backend for caller-facing Responses persistence, not the wire-level `store` flag. checkpoint_store_provider: Scoped checkpoint storage. Defaults to `CheckpointStoreProvider`. Native workflow history and pending replies are checkpoint-owned, not agent-session-owned. - prepare_options: Sync or async hook receiving the hosted request and a copy of caller model - options before factory resolution and parsing. Return the replacement mapping; hosting validates it. - Without a hook, caller options are omitted. - This does not enable inner provider background or service-owned history. allowed_oauth_consent_origins: Optional exact HTTPS origins for consent links. Omission retains safe-HTTPS validation; an empty sequence rejects all origins. sse_keep_alive_interval_seconds: Positive streaming heartbeat interval. If omitted, the SDK @@ -367,33 +359,17 @@ def __init__( for response persistence. Defaults to 10 seconds. enable_background_recovery: Allow checkpoint-backed outer workflow recovery. Defaults to `False`. Outer background execution does not enable provider background on workflow agents. - **kwargs: Additional AgentServer host settings forwarded to the SDK. + **kwargs: Additional AgentServer SDK constructor arguments. Raises: - TypeError: If the workflow is not a request-aware factory, the parser is not callable, or an - agent-only setting is supplied. + TypeError: If the workflow is not a request-aware factory or the parser is not callable. ValueError: If a supported setting has an invalid value. """ - forbidden = { - "agent", - "agent_session_store_provider", - "function_approval_store_provider", - "history_source", - "background_source", - "unsupported_options", - "max_history_items", - "store", - }.intersection(kwargs) - if forbidden: - raise TypeError(f"Unsupported native workflow host settings: {', '.join(sorted(forbidden))}.") validate_workflow_source(workflow) if not callable(parse_input): raise TypeError("parse_input must be a callable.") - if prepare_options is not None and not callable(prepare_options): - raise TypeError("prepare_options must be a callable.") allowed_origins = _normalize_allowed_oauth_consent_origins(allowed_oauth_consent_origins) - options = build_response_server_options( - is_workflow=True, + options = build_workflow_response_server_options( sse_keep_alive_interval_seconds=sse_keep_alive_interval_seconds, shutdown_grace_period_seconds=shutdown_grace_period_seconds, enable_background_recovery=enable_background_recovery, @@ -404,7 +380,6 @@ def __init__( self._checkpoint_store_provider = ( CheckpointStoreProvider() if checkpoint_store_provider is None else checkpoint_store_provider ) - self._prepare_options = prepare_options self._resilient_background = enable_background_recovery self._allowed_origins = allowed_origins self._bind_streaming_route( @@ -506,8 +481,6 @@ async def abort() -> bool: self.config, platform_context, local_session_id=context.response_id ) hosted = ResponsesRequest(request, context, scope, response_run_options(request)) - await prepare_response_options(hosted, self._prepare_options) - validate_request_options(hosted.options) workflow = await self._resolver.resolve(hosted) resources = AsyncExitStack() await resources.__aenter__() @@ -564,7 +537,6 @@ async def abort() -> bool: workflow, turn, scope, - options=hosted.options, stored=run.stored, fresh_factory=True, ) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py index 97e2f2116c1..023cdaefab2 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py @@ -42,8 +42,6 @@ from ._scope import FoundryRequestScope -UnsupportedOptions: TypeAlias = Literal["ignore", "warn", "error"] - def validate_sse_keep_alive_interval(value: int | None) -> None: """Validate an explicit heartbeat interval without replacing SDK environment resolution.""" @@ -54,23 +52,12 @@ def validate_sse_keep_alive_interval(value: int | None) -> None: raise ValueError("sse_keep_alive_interval_seconds must be positive when supplied.") -def build_response_server_options( +def _validate_shared_response_settings( *, - is_workflow: bool, - history_source: Literal["host_managed", "agent_managed", "inference_service"] = "host_managed", - background_source: Literal["host_managed", "inference_service"] = "host_managed", - max_history_items: int | None = None, - sse_keep_alive_interval_seconds: int | None = None, - shutdown_grace_period_seconds: int = 10, - enable_background_recovery: bool = False, -) -> ResponsesServerOptions: - """Validate supported settings and build SDK options without host initialization. - - Omit an unset history limit so the installed SDK supplies its own default. - Leave heartbeat environment resolution to the SDK: an explicit positive - interval wins over a positive ``SSE_KEEPALIVE_INTERVAL``, otherwise disabled. - Neither SDK ``from_env`` history overrides nor host model defaults are loaded. - """ + sse_keep_alive_interval_seconds: int | None, + shutdown_grace_period_seconds: int, + enable_background_recovery: bool, +) -> None: validate_sse_keep_alive_interval(sse_keep_alive_interval_seconds) if isinstance(shutdown_grace_period_seconds, bool) or not isinstance(shutdown_grace_period_seconds, int): raise TypeError("shutdown_grace_period_seconds must be an integer.") @@ -78,18 +65,38 @@ def build_response_server_options( raise ValueError("shutdown_grace_period_seconds must be positive.") if not isinstance(enable_background_recovery, bool): raise TypeError("enable_background_recovery must be a boolean.") + + +def build_agent_response_server_options( + *, + history_source: Literal["host_managed", "agent_managed", "inference_service"], + background_source: Literal["host_managed", "inference_service"], + max_history_items: int | None, + sse_keep_alive_interval_seconds: int | None, + shutdown_grace_period_seconds: int, + enable_background_recovery: bool, +) -> ResponsesServerOptions: + """Validate Responses agent host settings and build SDK options without host initialization. + + Omit an unset history limit so the installed SDK supplies its own default. + Leave heartbeat environment resolution to the SDK: an explicit positive + interval wins over a positive ``SSE_KEEPALIVE_INTERVAL``, otherwise disabled. + """ + _validate_shared_response_settings( + sse_keep_alive_interval_seconds=sse_keep_alive_interval_seconds, + shutdown_grace_period_seconds=shutdown_grace_period_seconds, + enable_background_recovery=enable_background_recovery, + ) if history_source not in ("host_managed", "agent_managed", "inference_service"): raise ValueError("history_source must be 'host_managed', 'agent_managed', or 'inference_service'.") if background_source not in ("host_managed", "inference_service"): raise ValueError("background_source must be 'host_managed' or 'inference_service'.") - if background_source == "inference_service" and (is_workflow or history_source != "inference_service"): - raise ValueError( - "Inference-service background requires a regular agent with history_source='inference_service'." - ) - if enable_background_recovery and not is_workflow and background_source != "inference_service": + if background_source == "inference_service" and history_source != "inference_service": + raise ValueError("background_source='inference_service' requires history_source='inference_service'.") + if enable_background_recovery and background_source != "inference_service": raise ValueError( "enable_background_recovery=True requires history_source='inference_service' and " - "background_source='inference_service' for regular agents." + "background_source='inference_service'." ) kwargs: dict[str, Any] = {} if max_history_items is not None: @@ -97,11 +104,11 @@ def build_response_server_options( raise TypeError("max_history_items must be an integer or None.") if max_history_items <= 0: raise ValueError("max_history_items must be positive when supplied.") - if is_workflow or history_source != "host_managed": + if history_source != "host_managed": warnings.warn( - "max_history_items is ignored unless used with a regular agent and history_source='host_managed'.", + "max_history_items is ignored unless history_source='host_managed'.", UserWarning, - stacklevel=2, + stacklevel=3, ) else: kwargs["default_fetch_history_count"] = max_history_items @@ -114,6 +121,26 @@ def build_response_server_options( ) +def build_workflow_response_server_options( + *, + sse_keep_alive_interval_seconds: int | None, + shutdown_grace_period_seconds: int, + enable_background_recovery: bool, +) -> ResponsesServerOptions: + """Validate Responses workflow host settings and build SDK options without host initialization.""" + _validate_shared_response_settings( + sse_keep_alive_interval_seconds=sse_keep_alive_interval_seconds, + shutdown_grace_period_seconds=shutdown_grace_period_seconds, + enable_background_recovery=enable_background_recovery, + ) + return ResponsesServerOptions( + sse_keep_alive_interval_seconds=sse_keep_alive_interval_seconds, + shutdown_grace_period_seconds=shutdown_grace_period_seconds, + resilient_background=enable_background_recovery, + steerable_conversations=False, + ) + + InputT = TypeVar("InputT", default=Any) @@ -412,13 +439,6 @@ def validate_default_transport_options(defaults: Mapping[str, Any], *, allow_age ) -def validate_unsupported_options(mode: str) -> UnsupportedOptions: - """Reject misspelled unsupported-options policies at host construction.""" - if mode not in ("ignore", "warn", "error"): - raise ValueError("unsupported_options must be 'ignore', 'warn', or 'error'.") - return mode - - RequestT = TypeVar("RequestT") AgentRequestT = TypeVar("AgentRequestT", contravariant=True) @@ -498,38 +518,41 @@ async def resolve_agent(source: AgentSource[RequestT], request: RequestT) -> Sup _MAX_STRONG_RESOURCE_IDENTITIES = 1024 -_CLIENT_CONTROLS = frozenset({ - "additional_function_arguments", - "agent", - "background", - "call_id", - "checkpoint_id", - "checkpoint_storage", - "client_kwargs", - "continuation_token", - "conversation", - "conversation_id", - "extra_body", - "function_invocation_kwargs", - "fresh_factory", - "input", - "instructions", - "messages", - "middleware", - "previous_response_id", - "response_id", - "responses", - "service_session_id", - "session", - "session_id", - "agent_session_id", - "store", - "stream", - "tokenizer", - "tools", - "user", - "user_id", -}) +_CLIENT_CONTROLS = ( + frozenset({ + "additional_function_arguments", + "agent", + "background", + "call_id", + "checkpoint_id", + "checkpoint_storage", + "client_kwargs", + "continuation_token", + "conversation", + "conversation_id", + "extra_body", + "function_invocation_kwargs", + "fresh_factory", + "input", + "instructions", + "messages", + "middleware", + "previous_response_id", + "response_id", + "responses", + "service_session_id", + "session", + "session_id", + "agent_session_id", + "store", + "stream", + "tokenizer", + "tools", + "user", + "user_id", + }) + | _RUN_CONTROLLED_FIELDS +) class _NativeAgentOptions(AgentMiddleware): @@ -585,7 +608,6 @@ def prepare_workflow_kwargs( turn: WorkflowTurn[Any], scope: FoundryRequestScope, *, - options: Mapping[str, Any] | None = None, stored: bool = True, fresh_factory: bool = False, ) -> tuple[WorkflowInvocationKwargs, WorkflowInvocationKwargs]: @@ -622,9 +644,6 @@ def validate_values(value: Any) -> dict[str, Any]: values["options"] = validate_values(values["options"]) if _CLIENT_CONTROLS.intersection(values["options"]): raise ValueError("Workflow model options cannot override hosting, agent, or transport controls.") - model_options = validate_values(options or {}) - if _CLIENT_CONTROLS.intersection(model_options): - raise ValueError("Workflow model options cannot override hosting, agent, or transport controls.") identity = {"session_id": scope.session_id, "user_id": scope.user_id, "call_id": scope.call_id} global_client["additional_function_arguments"] = identity @@ -656,7 +675,7 @@ def validate_values(value: Any) -> dict[str, Any]: ): raise ValueError("store=false cannot disable an external workflow HistoryProvider.") values = specific_client.setdefault(executor_id, {}) - effective = {**global_model_options, **values.get("options", {}), **model_options} + effective = {**global_model_options, **values.get("options", {})} values["additional_function_arguments"] = identity if isinstance(agent_value, Agent): if stores: diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py index c5c948b6f15..5d8013df22c 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py @@ -22,7 +22,8 @@ from agent_framework_foundry_hosting._scope import FoundryRequestScope from agent_framework_foundry_hosting._shared import ( _NativeAgentOptions, - build_response_server_options, + build_agent_response_server_options, + build_workflow_response_server_options, prepare_response_options, response_run_options, validate_agent_background_options, @@ -31,17 +32,35 @@ from .options_helpers import OptionCallbacks, OptionsClient +_AGENT_DEFAULTS: dict[str, Any] = { + "history_source": "host_managed", + "background_source": "host_managed", + "max_history_items": None, + "sse_keep_alive_interval_seconds": None, + "shutdown_grace_period_seconds": 10, + "enable_background_recovery": False, +} +_WORKFLOW_DEFAULTS: dict[str, Any] = { + "sse_keep_alive_interval_seconds": None, + "shutdown_grace_period_seconds": 10, + "enable_background_recovery": False, +} + + +def _agent_options(**settings: Any) -> ResponsesServerOptions: + return build_agent_response_server_options(**{**_AGENT_DEFAULTS, **settings}) + def test_history_default_is_omitted_instead_of_forced_unlimited(monkeypatch: pytest.MonkeyPatch) -> None: monkeypatch.setenv("DEFAULT_FETCH_HISTORY_ITEM_COUNT", "7") with patch("agent_framework_foundry_hosting._shared.ResponsesServerOptions", wraps=ResponsesServerOptions) as sdk: - result = build_response_server_options(is_workflow=False) + result = _agent_options() assert "default_fetch_history_count" not in sdk.call_args.kwargs assert result.default_fetch_history_count == ResponsesServerOptions().default_fetch_history_count assert result.default_model is None assert result.steerable_conversations is False assert result.resilient_background is False - assert build_response_server_options(is_workflow=False, max_history_items=7).default_fetch_history_count == 7 + assert _agent_options(max_history_items=7).default_fetch_history_count == 7 @pytest.mark.parametrize( @@ -64,32 +83,43 @@ def test_history_default_is_omitted_instead_of_forced_unlimited(monkeypatch: pyt ({"background_source": "wrong"}, ValueError), ], ) -def test_invalid_settings_fail_before_sdk_options_construction( +def test_invalid_agent_settings_fail_before_sdk_options_construction( settings: dict[str, Any], error: type[Exception] ) -> None: with patch("agent_framework_foundry_hosting._shared.ResponsesServerOptions") as sdk, pytest.raises(error): - build_response_server_options(is_workflow=False, **settings) + _agent_options(**settings) sdk.assert_not_called() -def test_recovery_and_workflow_history_eligibility() -> None: - assert build_response_server_options( - is_workflow=False, +@pytest.mark.parametrize( + ("settings", "error"), + [ + ({"sse_keep_alive_interval_seconds": 0}, ValueError), + ({"shutdown_grace_period_seconds": True}, TypeError), + ({"enable_background_recovery": 1}, TypeError), + ], +) +def test_invalid_workflow_settings_fail_before_sdk_options_construction( + settings: dict[str, Any], error: type[Exception] +) -> None: + with patch("agent_framework_foundry_hosting._shared.ResponsesServerOptions") as sdk, pytest.raises(error): + build_workflow_response_server_options(**{**_WORKFLOW_DEFAULTS, **settings}) + sdk.assert_not_called() + + +def test_recovery_and_history_limit_eligibility() -> None: + assert _agent_options( history_source="inference_service", background_source="inference_service", enable_background_recovery=True, ).resilient_background - assert build_response_server_options(is_workflow=True, enable_background_recovery=True).resilient_background + assert build_workflow_response_server_options(**{ + **_WORKFLOW_DEFAULTS, + "enable_background_recovery": True, + }).resilient_background with pytest.warns(UserWarning, match="max_history_items is ignored"): - workflow_options = build_response_server_options(is_workflow=True, max_history_items=2) - assert workflow_options.default_fetch_history_count == ResponsesServerOptions().default_fetch_history_count - with pytest.warns(UserWarning, match="max_history_items is ignored"): - agent_managed_options = build_response_server_options( - is_workflow=False, history_source="agent_managed", max_history_items=2 - ) + agent_managed_options = _agent_options(history_source="agent_managed", max_history_items=2) assert agent_managed_options.default_fetch_history_count == ResponsesServerOptions().default_fetch_history_count - with pytest.raises(ValueError, match="regular agent"): - build_response_server_options(is_workflow=True, background_source="inference_service") @pytest.mark.parametrize("env", [None, "0", "-2", "3"]) diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_invocations_workflow.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_invocations_workflow.py index d1409c8b41a..e0d5695fab6 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_invocations_workflow.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_invocations_workflow.py @@ -59,7 +59,7 @@ WorkflowSource, WorkflowTurn, ) -from agent_framework_foundry_hosting._invocations_shared import _workflow_output, _WorkflowOutputError +from agent_framework_foundry_hosting._invocations_workflow import _workflow_output, _WorkflowOutputError from agent_framework_foundry_hosting._state_store import FoundryCheckpointStore from agent_framework_foundry_hosting._workflow_state import FoundryWorkflowBindingStore, WorkflowHead @@ -1245,11 +1245,11 @@ async def handle(self, _: Ticket, ctx: WorkflowContext[None, str]) -> None: byte_limit = 4096 if limit_kind == "events" else 128 with ( patch( - "agent_framework_foundry_hosting._invocations_shared._MAX_WORKFLOW_SNAPSHOT_EVENTS", + "agent_framework_foundry_hosting._invocations_workflow._MAX_WORKFLOW_SNAPSHOT_EVENTS", event_limit, ), patch( - "agent_framework_foundry_hosting._invocations_shared._MAX_WORKFLOW_SNAPSHOT_BYTES", + "agent_framework_foundry_hosting._invocations_workflow._MAX_WORKFLOW_SNAPSHOT_BYTES", byte_limit, ), ): diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py index 8b7c51e1de7..7e946b99266 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py @@ -916,13 +916,12 @@ def create(request: ResponsesRequest) -> Workflow: return _build(AgentExecutor(agent, id="model")) async def parse(request: ResponsesRequest) -> WorkflowTurn[Any]: - return WorkflowTurn(input=[Message("user", await request.get_input_text() or "")]) + return WorkflowTurn( + input=[Message("user", await request.get_input_text() or "")], + client_kwargs={"options": dict(request.options)} if forward_options else None, + ) - server = _server( - create, - parser=parse, - prepare_options=(lambda _request, options: options) if forward_options else None, - ) + server = _server(create, parser=parse) first = await _post(server, "one", temperature=0.7, max_output_tokens=12, store=True) assert first["status"] == "completed", first second = await _post(server, "two", temperature=0.4, store=False, call="call-two") @@ -953,8 +952,11 @@ def create(request: ResponsesRequest) -> Workflow: ) return _build(_RegistryExecutor(agent)) + async def parse(request: ResponsesRequest) -> WorkflowTurn[Any]: + return WorkflowTurn(input=await request.get_input_text(), client_kwargs={"options": dict(request.options)}) + response = await _post( - _server(create, parser=_parse_text, prepare_options=lambda _request, options: options), + _server(create, parser=parse), "hello", temperature=0.7, ) @@ -1034,9 +1036,12 @@ def create(request: ResponsesRequest) -> Workflow: return _build(AgentExecutor(agent, id="raw")) async def parse(request: ResponsesRequest) -> WorkflowTurn[Any]: - return WorkflowTurn(input=[Message("user", await request.get_input_text() or "")]) + return WorkflowTurn( + input=[Message("user", await request.get_input_text() or "")], + client_kwargs={"options": dict(request.options)}, + ) - server = _server(create, parser=parse, prepare_options=lambda _request, options: options) + server = _server(create, parser=parse) async with httpx.AsyncClient(transport=httpx.ASGITransport(app=server), base_url="http://test") as client: response = await client.post( "/responses", diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py index 07e66d95c97..4e3b7a333a7 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py @@ -434,14 +434,10 @@ def create(request: object) -> Workflow: resolver = WorkflowResolver(create) workflow = await resolver.resolve(object()) run = await _prepare("model-turn", workflow=workflow, fresh_factory=True) - turn = run.validate_turn(WorkflowTurn(input=[Message("user", "hello")])) - clients, functions = prepare_workflow_kwargs( - workflow, - turn, - run.scope, - options={"temperature": 0.6}, - fresh_factory=True, + turn = run.validate_turn( + WorkflowTurn(input=[Message("user", "hello")], client_kwargs={"options": {"temperature": 0.6}}) ) + clients, functions = prepare_workflow_kwargs(workflow, turn, run.scope, fresh_factory=True) await run.claim() events = [event async for event in run.events(turn, client_kwargs=clients, function_invocation_kwargs=functions)] assert any(event.type == "output" for event in events) @@ -464,9 +460,8 @@ def create(request: object) -> Workflow: id="model", ) ), - WorkflowTurn(input=[Message("user", "hello")]), + WorkflowTurn(input=[Message("user", "hello")], client_kwargs={"options": {"temperature": 0.6}}), run.scope, - options={"temperature": 0.6}, fresh_factory=True, ) @@ -759,6 +754,8 @@ async def test_checkpoint_mutation_and_foreign_pairing_fail() -> None: {"session": "forged"}, {"additional_function_arguments": {"call_id": "forged"}}, {"options": {"extra_body": {"store": True}}}, + {"compaction_strategy": object()}, + {"options": {"compaction_strategy": object()}}, WorkflowInvocationKwargs(executor_kwargs={"counter": {"options": {"instructions": "forged"}}}), ], ) @@ -770,9 +767,12 @@ def test_client_kwargs_reject_controls_in_all_namespaces(kwargs: Any) -> None: def test_tool_context_stays_separate_from_model_options() -> None: clients, functions = prepare_workflow_kwargs( _workflow(), - WorkflowTurn(input=1, function_invocation_kwargs={"ticket": "application"}), + WorkflowTurn( + input=1, + client_kwargs={"options": {"temperature": 0.5}}, + function_invocation_kwargs={"ticket": "application"}, + ), _scope(), - options={"temperature": 0.5}, ) assert functions.global_kwargs == {"ticket": "application"} assert clients.global_kwargs["additional_function_arguments"] == { diff --git a/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py b/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py index cb37ba64fd0..1d503568a9c 100644 --- a/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py +++ b/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py @@ -6,7 +6,7 @@ import subprocess import sys import textwrap -from typing import Any, cast +from typing import Any from unittest.mock import patch import pytest @@ -94,17 +94,13 @@ def test_host_signatures_expose_only_the_selected_execution_model(protocol: str) assert workflow_parameters["workflow"].default is inspect.Parameter.empty assert workflow_parameters[parser].default is inspect.Parameter.empty assert workflow_parameters[parser].kind is inspect.Parameter.KEYWORD_ONLY - for legacy in ("parse_response", "parse_request"): - assert legacy not in agent_parameters - assert legacy not in workflow_parameters assert "checkpoint_store_provider" in workflow_parameters assert "checkpoint_store_provider" not in agent_parameters - for name in ("agent", "agent_session_store_provider", "history_source", "background_source", "unsupported_options"): + for name in ("agent", "agent_session_store_provider", "history_source", "background_source", "prepare_options"): assert name not in workflow_parameters - assert ("prepare_options" in workflow_parameters) is (protocol == "Responses") + assert "prepare_options" in agent_parameters if protocol == "Responses": assert "response_store" in agent_parameters - assert "store" not in agent_parameters @pytest.mark.parametrize("protocol", ["Responses", "Invocations"]) @@ -136,31 +132,15 @@ def test_agent_hosts_reject_ambiguous_factories_before_sdk_construction(protocol initialize.assert_not_called() +@pytest.mark.parametrize("protocol", ["Responses", "Invocations"]) @pytest.mark.parametrize( - ("protocol", "setting"), - [ - ("Responses", "agent"), - ("Responses", "agent_session_store_provider"), - ("Responses", "function_approval_store_provider"), - ("Responses", "history_source"), - ("Responses", "background_source"), - ("Responses", "unsupported_options"), - ("Responses", "store"), - ], + "setting", + ["agent_session_store_provider", "history_source", "background_source", "max_history_items", "prepare_options"], ) -def test_workflow_hosts_reject_agent_settings_before_sdk_construction(protocol: str, setting: str) -> None: +def test_workflow_hosts_do_not_accept_agent_settings(protocol: str, setting: str) -> None: workflow_host = getattr(hosting, f"{protocol}WorkflowHostServer") - parser = "parse_input" - values: dict[str, Any] = {parser: lambda _: None, setting: None} - base = ( - "azure.ai.agentserver.responses.hosting.ResponsesAgentServerHost" - if protocol == "Responses" - else "azure.ai.agentserver.invocations.InvocationAgentServerHost" - ) - with patch(f"{base}.__init__", return_value=None) as initialize: - with pytest.raises(TypeError, match=setting): - workflow_host(workflow=lambda _: None, **values) - initialize.assert_not_called() + with pytest.raises(TypeError, match=setting): + workflow_host(workflow=lambda request: None, parse_input=lambda _: None, **{setting: None}) @pytest.mark.parametrize("protocol", ["Responses", "Invocations"]) @@ -171,23 +151,3 @@ def test_workflow_hosts_validate_factories_and_parsers_at_construction(protocol: workflow_host(workflow=lambda _: None, **{parser: None}) with pytest.raises(TypeError, match="one request"): workflow_host(workflow=lambda: None, **{parser: lambda _: None}) - - -def test_legacy_responses_request_name_is_not_exported() -> None: - assert "HostedResponseRequest" not in hosting.__all__ - assert "HostedResponseRequest" not in dir(hosting) - with pytest.raises(AttributeError, match="HostedResponseRequest"): - hosting.__getattr__("HostedResponseRequest") - - -def test_responses_workflow_host_rejects_agent_history_limit_even_when_none() -> None: - with ( - patch("azure.ai.agentserver.responses.hosting.ResponsesAgentServerHost.__init__") as initialize, - pytest.raises(TypeError, match="max_history_items"), - ): - cast(Any, hosting.ResponsesWorkflowHostServer)( - workflow=lambda _: None, - parse_input=lambda _: None, - max_history_items=None, - ) - initialize.assert_not_called() diff --git a/python/packages/foundry_hosting/tests/test_invocations.py b/python/packages/foundry_hosting/tests/test_invocations.py index 5a056a03394..5f276d3dd83 100644 --- a/python/packages/foundry_hosting/tests/test_invocations.py +++ b/python/packages/foundry_hosting/tests/test_invocations.py @@ -18,7 +18,7 @@ from collections.abc import AsyncIterator, Awaitable, Callable, Generator, Mapping, Sequence from contextlib import contextmanager from itertools import product -from typing import Any, Literal, cast +from typing import Any, cast from unittest.mock import AsyncMock, MagicMock, patch import httpx @@ -301,7 +301,7 @@ async def echo(self, messages: list[Message], ctx: WorkflowContext[str, str]) -> def _make_workflow_agent() -> WorkflowAgent: - return WorkflowBuilder(name="legacy", start_executor=_EchoExecutor()).build().as_agent() + return WorkflowBuilder(name="wrapped", start_executor=_EchoExecutor()).build().as_agent() async def _invoke_text(server: InvocationsHostServer, message: str) -> str: @@ -666,7 +666,6 @@ def create_agent(request: Request, name: str) -> _FakeAgent: [ ("parse_input", 42, "parse_input must be a callable"), ("prepare_options", 42, "prepare_options must be a callable"), - ("unsupported_options", "discard", "unsupported_options"), ], ) def test_rejects_invalid_configuration(self, parameter: str, value: Any, error: str) -> None: @@ -885,10 +884,7 @@ def create_agent(*, request: Request) -> _FakeAgent: assert provider.contexts == [] @pytest.mark.parametrize("stream", [False, True]) - @pytest.mark.parametrize("policy", ["ignore", "warn", "error"]) - async def test_http_route_rejects_tool_context_options_under_every_options_policy( - self, stream: bool, policy: Literal["ignore", "warn", "error"] - ) -> None: + async def test_http_route_rejects_tool_context_options(self, stream: bool) -> None: agent = _make_agent(response_text="ok", stream_texts=["ok"]) provider = _SessionStoreProvider(_mock_session_store()) agent.default_options = {"additional_function_arguments": {"user_id": "trusted", "tenant_id": "trusted"}} @@ -897,7 +893,6 @@ def create_host() -> InvocationsHostServer: return InvocationsHostServer( agent, agent_session_store_provider=provider, - unsupported_options=policy, prepare_options=lambda _request, options: options, ) @@ -933,35 +928,35 @@ async def test_options_hook_must_return_safe_string_keyed_mapping(self, result: assert agent.calls == [] @pytest.mark.parametrize("stream", [False, True]) - @pytest.mark.parametrize("policy", ["ignore", "warn", "error"]) - async def test_unsupported_options_policy( - self, policy: Literal["ignore", "warn", "error"], stream: bool, caplog: pytest.LogCaptureFixture - ) -> None: + async def test_hook_options_for_agent_without_options_are_rejected_before_streaming(self, stream: bool) -> None: agent = _NoOptionsAgent() - server = InvocationsHostServer( - agent, unsupported_options=policy, prepare_options=lambda _request, options: options - ) - with _request_context(session_id="unsupported"): + server = InvocationsHostServer(agent, prepare_options=lambda _request, options: options) + with _request_context(session_id="no-options"): response = await server._handle_invoke( # pyright: ignore[reportPrivateUsage] _make_request({"message": "hello", "options": {"temperature": 0.8}, "stream": stream}) ) - if policy == "error": - assert response.status_code == 400 - assert not isinstance(response, StreamingResponse) - assert "does not accept" in json.loads(bytes(response.body))["error"] - assert agent.calls == [] - else: - assert await _success_text(response) == "ok" - assert agent.calls[-1]["options"] is None + assert response.status_code == 400 + assert not isinstance(response, StreamingResponse) + assert "does not accept" in json.loads(bytes(response.body))["error"] + assert agent.calls == [] - assert ("Agent doesn't support runtime options" in caplog.text) is (policy == "warn") + async def test_caller_options_are_not_forwarded_without_hook(self) -> None: + agent = _make_agent(response_text="ok") + agent.default_options = {"temperature": 0.1} + server = InvocationsHostServer(agent) + with _request_context(session_id="defaults-only"): + response = await server._handle_invoke( # pyright: ignore[reportPrivateUsage] + _make_request({"message": "hello", "options": {"temperature": 0.9, "model": "other"}}) + ) + assert await _success_text(response) == "ok" + assert agent.calls[-1]["options"] is None + assert agent.default_options == {"temperature": 0.1} async def test_factory_options_failure_is_framed_before_first_delta(self) -> None: provider = _SessionStoreProvider(_mock_session_store()) server = InvocationsHostServer( lambda request: _NoOptionsAgent(), agent_session_store_provider=provider, - unsupported_options="error", prepare_options=lambda _request, options: options, ) with _request_context(session_id="factory-options"): @@ -973,8 +968,8 @@ async def test_factory_options_failure_is_framed_before_first_delta(self) -> Non ( "error", { - "message": "The hosted agent does not accept caller runtime options.", - "code": "unsupported_options", + "message": "The hosted agent does not accept the run options returned by prepare_options.", + "code": "invalid_request", "status": 400, }, ) @@ -1895,7 +1890,7 @@ async def test_reusing_session_restores_identifier(self, hosted: bool, stream: b with ( _request_context(call_id="call-1", session_id="sess-1", user_id="user-1"), patch( - "agent_framework_foundry_hosting._invocations_shared.AgentSession", wraps=AgentSession + "agent_framework_foundry_hosting._invocations_agent.AgentSession", wraps=AgentSession ) as session_factory, ): for _ in range(2): diff --git a/python/packages/foundry_hosting/tests/test_request.py b/python/packages/foundry_hosting/tests/test_request.py index 16d514c69ca..740390d1eaa 100644 --- a/python/packages/foundry_hosting/tests/test_request.py +++ b/python/packages/foundry_hosting/tests/test_request.py @@ -18,7 +18,6 @@ response_run_options, validate_default_transport_options, validate_request_options, - validate_unsupported_options, ) @@ -153,16 +152,6 @@ def test_default_transport_cannot_override_host_storage_or_identity() -> None: validate_default_transport_options({"extra_body": {"temperature": 0.5}}, allow_agent_store=False) -@pytest.mark.parametrize("mode", ["ignore", "warn", "error"]) -def test_supported_unsupported_option_modes(mode: str) -> None: - assert validate_unsupported_options(mode) == mode - - -def test_unknown_unsupported_option_mode_fails_at_construction() -> None: - with pytest.raises(ValueError, match="unsupported_options"): - validate_unsupported_options("silent") - - def test_invocation_run_accepts_typed_messages_with_independent_defaults() -> None: first = InvocationRun(messages="hello") second = InvocationRun(messages="world", stream=True) diff --git a/python/packages/foundry_hosting/tests/test_responses.py b/python/packages/foundry_hosting/tests/test_responses.py index fb0cf673c1a..e21fef917ea 100644 --- a/python/packages/foundry_hosting/tests/test_responses.py +++ b/python/packages/foundry_hosting/tests/test_responses.py @@ -1897,29 +1897,12 @@ def test_provider_background_rejects_wrong_history_source(self) -> None: with pytest.raises(ValueError, match="history_source='inference_service'"): _make_server(agent, background_source="inference_service") - @pytest.mark.parametrize("old_store", [None, InMemoryResponseProvider()]) - @pytest.mark.parametrize("with_response_store", [False, True]) - def test_removed_store_alias_is_rejected_before_sdk_construction( - self, old_store: Any, with_response_store: bool - ) -> None: - agent = _make_agent() - kwargs: dict[str, Any] = {"store": old_store} - if with_response_store: - kwargs["response_store"] = InMemoryResponseProvider() - with patch("azure.ai.agentserver.responses.hosting.ResponsesAgentServerHost.__init__") as initialize: - with pytest.raises(TypeError, match="store= alias was removed; use response_store="): - ResponsesHostServer(agent, **kwargs) - initialize.assert_not_called() - assert agent.context_providers == [] - def test_history_and_background_sources_reject_invalid_values(self) -> None: agent = _make_agent() with pytest.raises(ValueError, match="history_source"): _make_server(agent, history_source="host") with pytest.raises(ValueError, match="background_source"): _make_server(agent, background_source="host") - with pytest.raises(ValueError, match="unsupported_options"): - _make_server(agent, unsupported_options="silent") @pytest.mark.parametrize( ("setting", "value"), @@ -1931,7 +1914,7 @@ def test_history_and_background_sources_reject_invalid_values(self) -> None: ("background_source", "provider"), ], ) - def test_legacy_source_literals_are_rejected(self, setting: str, value: str) -> None: + def test_unknown_source_literals_are_rejected(self, setting: str, value: str) -> None: with pytest.raises(ValueError, match=setting): _make_server(_make_agent(), **{setting: value}) @@ -2630,12 +2613,12 @@ def handle_request(request: Any) -> Any: assert "Nested extra_body" in rejected.json()["error"]["message"] assert outbound == [] - legacy_default = Agent( + default_store_agent = Agent( client=OpenAIChatClient(model="test-model", async_client=openai), default_options=cast(Any, {"extra_body": {"store": True}}), ) - legacy_server = _make_server(legacy_default, history_source="agent_managed") - rejected_default = await _post_json(legacy_server, {"input": "unsafe", "store": False}) + default_store_server = _make_server(default_store_agent, history_source="agent_managed") + rejected_default = await _post_json(default_store_server, {"input": "unsafe", "store": False}) assert rejected_default.json()["status"] == "failed" assert "default extra_body" in rejected_default.json()["error"]["message"] assert outbound == [] @@ -2651,37 +2634,27 @@ def handle_request(request: Any) -> Any: assert outbound[0]["temperature"] == 0.1 assert "extra_body" not in outbound[0] - async def test_unsupported_options_policy_rejects_custom_agent(self) -> None: + async def test_custom_agent_runs_messages_only_without_prepare_options(self) -> None: agent = _StrictCustomAgent() - server = _make_server( - agent, - history_source="agent_managed", - unsupported_options="error", - prepare_options=lambda _request, options: options, - ) - response = await _post_json(server, {"input": "hello", "temperature": 0.8}) + server = _make_server(agent, history_source="agent_managed") - assert response.json()["status"] == "failed" - assert "does not accept caller runtime options" in response.json()["error"]["message"] - assert agent.calls == [] + response = await _post(server, temperature=0.5) - @pytest.mark.parametrize(("policy", "warn"), [("warn", True), ("ignore", False)]) - async def test_custom_agent_unsupported_options_warning_policy( - self, policy: str, warn: bool, caplog: pytest.LogCaptureFixture - ) -> None: + assert response.json()["status"] == "completed" + assert len(agent.calls) == 1 + + async def test_prepare_options_fails_for_agent_without_options_parameter(self) -> None: agent = _StrictCustomAgent() server = _make_server( agent, history_source="agent_managed", - unsupported_options=policy, - prepare_options=lambda _request, options: options, + prepare_options=lambda _request, options: {**options, "temperature": 0.8}, ) + response = await _post_json(server, {"input": "hello"}) - with caplog.at_level(logging.WARNING): - response = await _post(server, temperature=0.5) - - assert response.json()["status"] == "completed" - assert ("Agent doesn't support runtime options" in caplog.text) is warn + assert response.json()["status"] == "failed" + assert "does not accept the run options returned by prepare_options" in response.json()["error"]["message"] + assert agent.calls == [] @pytest.mark.parametrize( ("finish_reason", "expected_status"), @@ -3829,63 +3802,6 @@ async def run( exception = record.exc_info[1] assert exception is not None and exception.__cause__ is None and exception.__context__ is None - async def test_steering_keeps_superseded_snapshot_without_replacing_conversation_head(self) -> None: - store = SessionStore() - await store.set("conversation-head", AgentSession()) - first_continues = asyncio.Event() - calls = 0 - agent = _make_agent() - - def run_with_state(*args: Any, **kwargs: Any) -> ResponseStream[AgentResponseUpdate, AgentResponse]: - nonlocal calls - del args - calls += 1 - turn = calls - kwargs["session"].state["turn"] = turn - - async def updates() -> AsyncIterator[AgentResponseUpdate]: - yield AgentResponseUpdate(contents=[Content.from_text(f"turn {turn}")], role="assistant") - if turn == 1: - await first_continues.wait() - yield AgentResponseUpdate(contents=[Content.from_text("stale")], role="assistant") - - return ResponseStream(updates(), finalizer=AgentResponse.from_updates) - - agent.run = MagicMock(side_effect=run_with_state) - server = _make_server(agent, session_store=store) - # Exercise the handler's superseded-turn snapshot invariant without starting SDK steering. - server._host_options = ResponsesServerOptions(steerable_conversations=True) # pyright: ignore[reportPrivateUsage] - first = ResponseContext( - response_id="first-response", conversation_id="conversation-head", mode_flags=MagicMock() - ) - second = ResponseContext( - response_id="second-response", conversation_id="conversation-head", mode_flags=MagicMock() - ) - first_signal = asyncio.Event() - with ( - patch.object(ResponseContext, "get_input_items", new=AsyncMock(return_value=[])), - patch.object(ResponseContext, "get_history", new=AsyncMock(return_value=[])), - ): - first_handler = server._handle_response(CreateResponse(input="first"), first, first_signal) - async for event in first_handler: - if isinstance(event, Mapping) and event.get("type") == "response.output_text.delta": - break - newer = [ - event - async for event in server._handle_response(CreateResponse(input="second"), second, asyncio.Event()) - ] - first_signal.set() - older = [event async for event in first_handler] - - assert isinstance(newer[-1], Mapping) and newer[-1]["type"] == "response.completed" - assert isinstance(older[-1], Mapping) and older[-1]["type"] == "response.completed" - first_snapshot = await store.get("first-response") - second_snapshot = await store.get("second-response") - conversation_head = await store.get("conversation-head") - assert first_snapshot is not None and first_snapshot.state["turn"] == 1 - assert second_snapshot is not None and second_snapshot.state["turn"] == 2 - assert conversation_head is not None and conversation_head.state["turn"] == 2 - @pytest.mark.parametrize("existing_head", [False, True]) async def test_service_conversation_claim_prevents_parallel_provider_dispatch(self, existing_head: bool) -> None: conversation_id = f"conversation-{uuid.uuid4().hex}" diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/basic/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/basic/README.md index 33055b69bd7..e01d992ef3d 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/basic/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/basic/README.md @@ -111,4 +111,4 @@ deprecation warning. For **stored** requests, `"agent_managed"` passes only new developer-owned defaults may choose either a HistoryProvider **or downstream service storage**. `history_source="inference_service"` explicitly requires service-managed history and overrides the agent's `store` default on stored requests. The constructor accepts `response_store=` for the outer storage -*backend*, not `store=`. The removed alias does not affect the caller's per-request `store` flag. +*backend*; the caller's per-request `store` flag is separate. diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/declarative_customer_support/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/declarative_customer_support/README.md index a42f6126995..de32bdfbc3a 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/declarative_customer_support/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/declarative_customer_support/README.md @@ -5,7 +5,7 @@ using `InvokeAzureAgent`, `ConditionGroup`, `SendActivity`, and Power Fx expressions. [`main.py`](main.py) hosts the built declarative `Workflow` directly through `ResponsesWorkflowHostServer(workflow=..., parse_input=...)`. -The parser uses the explicit `response_input_messages()` migration helper for +The parser uses the explicit `response_input_messages()` helper for the declarative workflow's `list[Message]` start contract. The host restores the exact scoped MAF checkpoint first; it does not silently unwrap a `WorkflowAgent`, rebuild outer Responses history as workflow state, or reuse a @@ -13,9 +13,8 @@ downstream service session. Every request-aware factory call creates fresh agents, Foundry clients, credentials, and a fresh graph while the stable IDs in `workflow.yaml` preserve -checkpoint compatibility. Start a fresh Responses chain when migrating from -the legacy `.as_agent()` hosting path because old unscoped checkpoints are not -safe across Foundry sandboxes. +checkpoint compatibility. Unscoped checkpoints are not safe across Foundry +sandboxes, so this host does not read them. Example: diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/declarative_customer_support/main.py b/python/samples/04-hosting/foundry-hosted-agents/responses/declarative_customer_support/main.py index 7a43d92bcb0..17dd061acb0 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/declarative_customer_support/main.py +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/declarative_customer_support/main.py @@ -106,7 +106,7 @@ def build_workflow(request: ResponsesRequest) -> Workflow: async def parse_input(request: ResponsesRequest) -> WorkflowTurn[list[Message]]: - """Use the explicit current-turn message migration helper; checkpoints retain prior workflow state.""" + """Use the explicit current-turn message helper; checkpoints retain prior workflow state.""" return WorkflowTurn(input=await response_input_messages(request)) diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/resilient_long_running_workflow/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/resilient_long_running_workflow/README.md index c9d44c19218..6e45d0fc884 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/resilient_long_running_workflow/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/resilient_long_running_workflow/README.md @@ -27,8 +27,8 @@ Do not delete shared state as part of a sample or test. Use an isolated `AGENTSERVER_STATE_ROOT` when experimenting with crashes. The Foundry sandbox, the Responses continuation, and the MAF checkpoint remain -separate identities. Existing legacy unscoped workflow sessions are not read; -start a fresh response chain when migrating from `agent=workflow.as_agent()`. +separate identities. Unscoped workflow sessions are not read; +start a fresh response chain for this host. For Foundry deployment instructions, see the [parent README](../../README.md#deploying-the-agent-to-foundry). diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/README.md index 77eb36bd912..477bf260513 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/README.md @@ -1,7 +1,7 @@ # Long-running Responses agent (steering temporarily unavailable) -**Steering is currently gated.** `ResponsesHostServer` rejects the removed -`steerable_conversations` setting with `TypeError` during construction rather than starting a +**Steering is currently gated.** `ResponsesHostServer` has no +`steerable_conversations` setting and raises `TypeError` during construction rather than starting a TaskManager that can retain unbounded futures after rejected steering requests. The upstream fix is [Azure/azure-sdk-for-python#49233](https://github.com/Azure/azure-sdk-for-python/pull/49233); steering will be re-enabled only after a patched official `azure-ai-agentserver-core` wheel is released, diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/main.py b/python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/main.py index 2f6be261903..c4eac32b065 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/main.py +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/main.py @@ -4,7 +4,7 @@ The agent is asked to count down from a target number, pacing its own output with a short remark before each number so a response takes a while to fully generate. This sample currently runs -without steering; the hosting layer rejects the removed ``steerable_conversations`` setting until a patched +without steering; the hosting layer does not accept a ``steerable_conversations`` setting until a patched AgentServer SDK is released and verified. Environment variables: diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/verify_steering.py b/python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/verify_steering.py index d63a93b04cc..852f46c67fd 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/verify_steering.py +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/verify_steering.py @@ -19,13 +19,13 @@ def _agent_factory(*, request: ResponsesRequest) -> SupportsAgentRun: def main() -> None: """Confirm that the constructor rejects steering before creating an agent or host.""" try: - ResponsesHostServer(agent=_agent_factory, steerable_conversations=True) + ResponsesHostServer(agent=_agent_factory, steerable_conversations=True) # type: ignore[call-arg] except TypeError as exc: - if "steerable_conversations is no longer a supported host setting" not in str(exc): + if "steerable_conversations" not in str(exc): raise print("Steering is temporarily unavailable; no agent or host was started.") return - raise RuntimeError("Steering guard was removed; restore end-to-end and queue-overflow verification.") + raise RuntimeError("The host accepted steering; restore end-to-end and queue-overflow verification.") if __name__ == "__main__": From cb8d8a7f2c4ce3d6c99422d2fe5be9a9c7937865 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 11 Nov 2026 15:58:41 +0100 Subject: [PATCH 55/55] Python: describe current Responses workflow options in sample --- .../agent_framework_foundry_hosting/_shared.py | 2 +- .../foundry-hosted-agents/responses/basic/README.md | 13 +++++++------ 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py index 023cdaefab2..604615c02aa 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py @@ -306,7 +306,7 @@ def __init__( @property def options(self) -> Mapping[str, Any]: - """Return this turn's effective caller options after the hook.""" + """Return this turn's caller options, replaced by the ``prepare_options`` result on agent hosts.""" return self._options def set_options(self, options: Mapping[str, Any]) -> None: diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/basic/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/basic/README.md index e01d992ef3d..d2c1e82886e 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/basic/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/basic/README.md @@ -75,7 +75,7 @@ turns fail rather than mutating the same service thread. An invalid input does n `previous_response_id` parent. If a named turn fails or is cancelled after dispatch, start a new conversation; the existing thread may have changed even if its outer response did not complete. -## Options and compatibility +## Options Caller generation options are suppressed unless the host has a `prepare_options` hook. Without a hook, the agent/client defaults apply. With a hook, only its returned, validated mapping @@ -98,16 +98,17 @@ curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" The client uses the developer's model with `temperature=0.3` and `max_tokens=150`, not the caller's model. If the caller omits a token limit, the agent's `max_tokens=256` default applies. -Responses agent factories see translated caller options before the hook. Native Responses workflow factories -run after the hook and see its selected options, or an empty mapping without a hook; the original request -is still available through `request.request`. Platform IDs, storage flags, and private +Responses agent factories see translated caller options before the hook. Native Responses workflow hosts have +no option hook: their factories and required parsers see the translated caller options through `request.options` +and the original request through `request.request`, and the workflow receives model options only from the +parser's `WorkflowTurn(client_kwargs={"options": ...})`. Platform IDs, storage flags, and private continuation tokens are never caller model options; the hook cannot add them back. Host controls inside `extra_body` fail before the hook, rather than being silently stripped. See [explicit host configuration](../../../../../packages/foundry_hosting/README.md#explicit-host-configuration) for history caps, heartbeat intervals, shutdown waiting, and eligible recovery modes. -`history_source="host_managed"` and `history_source="agent_managed"` retain their existing meaning without a -deprecation warning. For **stored** requests, `"agent_managed"` passes only new input to the agent, whose +`history_source="host_managed"` keeps outer history in the host. For **stored** requests, +`"agent_managed"` passes only new input to the agent, whose developer-owned defaults may choose either a HistoryProvider **or downstream service storage**. `history_source="inference_service"` explicitly requires service-managed history and overrides the agent's `store` default on stored requests. The constructor accepts `response_store=` for the outer storage