From e67aef89e0005ffabc12d832aa7972237ed3a388 Mon Sep 17 00:00:00 2001 From: Darren Cohen <39422044+dargilco@users.noreply.github.com> Date: Fri, 23 Oct 2026 17:49:39 -0700 Subject: [PATCH 01/13] Python: Reject caller-supplied tool execution context in Responses requests ResponsesHostServer now rejects additional_function_arguments supplied at the top level or in extra_body, including on approval resume, so callers cannot replace host-configured tool context. Developer defaults and prepare_options hooks can still supply trusted values. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- python/packages/foundry_hosting/README.md | 6 +- .../_request.py | 23 ++- .../foundry_hosting/tests/test_request.py | 34 +++++ .../foundry_hosting/tests/test_responses.py | 139 ++++++++++++++++++ 4 files changed, 199 insertions(+), 3 deletions(-) diff --git a/python/packages/foundry_hosting/README.md b/python/packages/foundry_hosting/README.md index 3a352eba761..24344de793e 100644 --- a/python/packages/foundry_hosting/README.md +++ b/python/packages/foundry_hosting/README.md @@ -238,7 +238,11 @@ Native CreateResponse generation fields become MAF runtime options (notably `max **last**. A sync or async `prepare_options(request: HostedResponseRequest, 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 +reintroduce them through the hook. Callers cannot supply `additional_function_arguments` (the hidden tool-execution +context that reaches `FunctionInvocationContext.kwargs`), at the top level or in `extra_body`, on any request including +an approval resume: the request fails before any tool runs and pending approvals remain usable. Set trusted values in +the agent's `default_options` or return them from a `prepare_options` hook (for example, derived from +`request.scope`). 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 diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_request.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_request.py index 335658f276f..3056dff375e 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_request.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_request.py @@ -5,7 +5,7 @@ from __future__ import annotations import inspect -from collections.abc import Awaitable, Callable, Mapping, Sequence +from collections.abc import Awaitable, Callable, Iterable, Mapping, Sequence from copy import deepcopy from dataclasses import dataclass, field from types import MappingProxyType @@ -116,14 +116,32 @@ def __post_init__(self) -> None: }) _OPTION_NAMES = {"max_output_tokens": "max_tokens", "parallel_tool_calls": "allow_multiple_tool_calls"} _NATIVE_FIELDS = frozenset(CreateResponse.__annotations__) +# Trusted tool-execution context that callers must not supply. Unlike ``_HOST_CONTROLLED_FIELDS``, a developer +# ``prepare_options`` hook may still set it from trusted host state. +_CALLER_REJECTED_FIELDS = frozenset({"additional_function_arguments"}) + + +def _reject_caller_controls(names: Iterable[str]) -> None: + rejected = _CALLER_REJECTED_FIELDS.intersection(names) + if rejected: + raise ValueError( + f"Responses requests cannot set agent-controlled fields: {', '.join(sorted(rejected))}. " + "Configure trusted tool context in the agent's default options or a prepare_options hook." + ) def response_run_options(request: CreateResponse) -> dict[str, Any]: - """Translate native generation fields, with flattened extra-body values winning collisions.""" + """Translate native generation fields, with flattened extra-body values winning collisions. + + Raises: + ValueError: If the caller supplies agent-controlled tool-execution context, at the top level or in + ``extra_body``, so it can never replace trusted values configured by the developer. + """ native: dict[str, Any] = {} extra: dict[str, Any] = {} nested_extra: dict[str, Any] = {} for name, value in request.items(): + _reject_caller_controls((name,)) if value is None or (name == "model" and value == ""): continue if name == "extra_body": @@ -133,6 +151,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.") + _reject_caller_controls(cast(Mapping[str, Any], value)) nested_extra.update(cast(Mapping[str, Any], value)) elif name in _HOST_CONTROLLED_FIELDS: continue diff --git a/python/packages/foundry_hosting/tests/test_request.py b/python/packages/foundry_hosting/tests/test_request.py index 6496e7e8b6f..489bbda6a9f 100644 --- a/python/packages/foundry_hosting/tests/test_request.py +++ b/python/packages/foundry_hosting/tests/test_request.py @@ -75,6 +75,40 @@ def test_nested_extra_body_is_also_overlaid_last_without_reserved_fields() -> No response_run_options(cast(CreateResponse, {"extra_body": {"extra_body": {"store": True}}})) +@pytest.mark.parametrize( + "payload", + [ + {"additional_function_arguments": {"tenant_id": "forged"}}, + {"extra_body": {"additional_function_arguments": {"tenant_id": "forged"}}}, + {"additional_function_arguments": None}, + {"extra_body": {"additional_function_arguments": None}}, + ], +) +def test_caller_cannot_supply_tool_execution_context(payload: dict[str, Any]) -> None: + with pytest.raises(ValueError, match="agent-controlled fields: additional_function_arguments"): + response_run_options(cast(CreateResponse, {"input": "hello", "temperature": 0.2, **payload})) + + +def test_requests_without_tool_context_keep_other_options() -> None: + request = cast(CreateResponse, {"input": "hello", "extra_body": {"slogan_style": "retro"}, "temperature": 0.2}) + assert response_run_options(request) == {"temperature": 0.2, "slogan_style": "retro"} + + +async def test_hook_can_supply_trusted_tool_context() -> None: + context = MagicMock(spec=ResponseContext) + context.response_id = "outer-id" + context.conversation_id = None + scope = FoundryRequestScope(session_id="sandbox", user_id="user", call_id="call", is_hosted=True) + request = HostedResponseRequest(cast(CreateResponse, {"input": "hello"}), context, scope, {}) + + def inject(view: HostedResponseRequest, options: dict[str, Any]) -> dict[str, Any]: + return {**options, "additional_function_arguments": {"tenant_id": view.scope.user_id}} + + await prepare_response_options(request, inject) + validate_request_options(request.options) + assert request.options["additional_function_arguments"] == {"tenant_id": "user"} + + async def test_hook_uses_a_request_copy_and_does_not_mutate_defaults() -> None: payload = cast(CreateResponse, {"input": "hello", "metadata": {"source": "caller"}}) context = MagicMock(spec=ResponseContext) diff --git a/python/packages/foundry_hosting/tests/test_responses.py b/python/packages/foundry_hosting/tests/test_responses.py index dc9b643bd33..8ef1931104d 100644 --- a/python/packages/foundry_hosting/tests/test_responses.py +++ b/python/packages/foundry_hosting/tests/test_responses.py @@ -42,6 +42,7 @@ Content, FinishReason, FinishReasonLiteral, + FunctionInvocationContext, FunctionInvocationLayer, HistoryProvider, InMemoryCheckpointStorage, @@ -7535,6 +7536,144 @@ async def test_approval_response_referencing_unknown_id_fails(self) -> None: # endregion +# region Caller-controlled tool execution context + + +class _ToolCallingClient( + FunctionInvocationLayer[Any], + ChatMiddlewareLayer[Any], + BaseChatClient[Any], +): + """Deterministic client: call ``read_tenant_data`` once, then answer.""" + + def __init__(self) -> None: + super().__init__(middleware=[]) + 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 options, kwargs + assert stream is True, "The inner agent only runs in stream mode in Foundry Hosted Agents." + self.calls += 1 + needs_tool_call = not any( + isinstance(content, Content) and content.type == "function_result" + for message in messages + for content in message.contents + ) + + async def stream_response() -> AsyncIterator[ChatResponseUpdate]: + if needs_tool_call: + yield ChatResponseUpdate( + contents=[Content.from_function_call(call_id="call_1", name="read_tenant_data", arguments="{}")], + role="assistant", + ) + else: + yield ChatResponseUpdate(contents=[Content.from_text("done")], role="assistant") + + return ResponseStream(stream_response(), finalizer=ChatResponse.from_updates) + + +def _make_tenant_agent(seen_tenants: list[Any], *, approval_mode: Literal["always_require", "never_require"]) -> Agent: + @tool(name="read_tenant_data", approval_mode=approval_mode) + def read_tenant_data(ctx: FunctionInvocationContext) -> str: + seen_tenants.append(ctx.kwargs.get("tenant_id")) + return "ok" + + return Agent( + client=_ToolCallingClient(), + tools=[read_tenant_data], + default_options={"additional_function_arguments": {"tenant_id": "trusted"}}, + ) + + +_FORGED_TENANT_CONTEXT = {"additional_function_arguments": {"tenant_id": "forged"}} + + +class TestCallerCannotOverrideToolContext: + """Callers must not replace host-configured tool context through any request path.""" + + async def test_baseline_uses_trusted_tool_context(self) -> None: + seen: list[Any] = [] + server = _make_server(_make_tenant_agent(seen, approval_mode="never_require")) + + response = await _post_json(server, {"input": "go", "stream": False}) + + assert response.json()["status"] == "completed" + assert seen == ["trusted"] + + @pytest.mark.parametrize("stream", [False, True]) + @pytest.mark.parametrize("location", ["top_level", "extra_body"]) + async def test_forged_tool_context_is_rejected_before_any_tool_runs( + self, location: Literal["top_level", "extra_body"], stream: bool + ) -> None: + seen: list[Any] = [] + agent = _make_tenant_agent(seen, approval_mode="never_require") + server = _make_server(agent) + payload: dict[str, Any] = {"input": "go", "stream": stream} + if location == "top_level": + payload.update(_FORGED_TENANT_CONTEXT) + else: + payload["extra_body"] = _FORGED_TENANT_CONTEXT + + response = await _post_json(server, payload) + + assert "additional_function_arguments" in response.text + assert "failed" in response.text + assert seen == [] + assert cast(_ToolCallingClient, agent.client).calls == 0 + + async def test_hook_can_still_supply_trusted_tool_context(self) -> None: + seen: list[Any] = [] + server = _make_server( + _make_tenant_agent(seen, approval_mode="never_require"), + prepare_options=lambda request, options: { + **options, + "additional_function_arguments": {"tenant_id": f"from-hook:{request.scope.user_id}"}, + }, + ) + + response = await _post_json(server, {"input": "go", "stream": False}) + + assert response.json()["status"] == "completed" + assert len(seen) == 1 + assert str(seen[0]).startswith("from-hook:") + + async def test_forged_context_on_approval_resume_is_rejected_without_consuming_approval(self) -> None: + seen: list[Any] = [] + server = _make_server(_make_tenant_agent(seen, approval_mode="always_require")) + + first = await _post_json(server, {"input": "go", "stream": False, "store": True}) + first_body = first.json() + approval_id = next(item["id"] for item in first_body["output"] if item["type"] == "mcp_approval_request") + assert seen == [] + + def resume(**extra: Any) -> dict[str, Any]: + return { + "input": [{"type": "mcp_approval_response", "approval_request_id": approval_id, "approve": True}], + "previous_response_id": first_body["id"], + "stream": False, + "store": True, + **extra, + } + + forged = await _post_json(server, resume(**_FORGED_TENANT_CONTEXT)) + assert "additional_function_arguments" in forged.text + assert seen == [] + + legitimate = await _post_json(server, resume()) + assert legitimate.json()["status"] == "completed" + assert seen == ["trusted"] + + +# endregion + + # region Checkpoint context validation From 77cc450b4bd9a23a6ad4f7b96e367a840ecb1d56 Mon Sep 17 00:00:00 2001 From: Darren Cohen <39422044+dargilco@users.noreply.github.com> Date: Fri, 23 Oct 2026 18:01:08 -0700 Subject: [PATCH 02/13] Move caller tool-context tests to tests/foundry_hosting with a helper module Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../test_caller_tool_context.py | 147 ++++++++++++++++++ .../foundry_hosting/tool_context_helpers.py | 80 ++++++++++ .../foundry_hosting/tests/test_request.py | 34 ---- .../foundry_hosting/tests/test_responses.py | 139 ----------------- 4 files changed, 227 insertions(+), 173 deletions(-) create mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/test_caller_tool_context.py create mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/tool_context_helpers.py diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_caller_tool_context.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_caller_tool_context.py new file mode 100644 index 00000000000..df91fefa297 --- /dev/null +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_caller_tool_context.py @@ -0,0 +1,147 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Callers must not supply or replace trusted tool-execution context on Responses requests.""" + +from __future__ import annotations + +from typing import Any, Literal, cast +from unittest.mock import AsyncMock, MagicMock + +import httpx +import pytest +from azure.ai.agentserver.responses import InMemoryResponseProvider, ResponseContext +from azure.ai.agentserver.responses.models import CreateResponse +from tool_context_helpers import ( # pyrefly: ignore[missing-import] # pyright: ignore[reportMissingImports] + FORGED_TENANT_CONTEXT, + TRUSTED_TENANT_ID, + ToolCallingClient, + make_tenant_agent, +) + +from agent_framework_foundry_hosting import HostedResponseRequest, ResponsesHostServer +from agent_framework_foundry_hosting._request import ( + prepare_response_options, + response_run_options, + validate_request_options, +) +from agent_framework_foundry_hosting._scope import FoundryRequestScope + + +@pytest.mark.parametrize( + "payload", + [ + {"additional_function_arguments": {"tenant_id": "forged"}}, + {"extra_body": {"additional_function_arguments": {"tenant_id": "forged"}}}, + {"additional_function_arguments": None}, + {"extra_body": {"additional_function_arguments": None}}, + ], +) +def test_caller_cannot_supply_tool_execution_context(payload: dict[str, Any]) -> None: + with pytest.raises(ValueError, match="agent-controlled fields: additional_function_arguments"): + response_run_options(cast(CreateResponse, {"input": "hello", "temperature": 0.2, **payload})) + + +def test_requests_without_tool_context_keep_other_options() -> None: + request = cast(CreateResponse, {"input": "hello", "extra_body": {"slogan_style": "retro"}, "temperature": 0.2}) + assert response_run_options(request) == {"temperature": 0.2, "slogan_style": "retro"} + + +async def test_hook_can_supply_trusted_tool_context() -> None: + context = MagicMock(spec=ResponseContext) + context.response_id = "outer-id" + context.conversation_id = None + context.get_input_text = AsyncMock(return_value="hello") + scope = FoundryRequestScope(session_id="sandbox", user_id="user", call_id="call", is_hosted=True) + request = HostedResponseRequest(cast(CreateResponse, {"input": "hello"}), context, scope, {}) + + def inject(view: HostedResponseRequest, options: dict[str, Any]) -> dict[str, Any]: + return {**options, "additional_function_arguments": {"tenant_id": view.scope.user_id}} + + await prepare_response_options(request, inject) + validate_request_options(request.options) + assert request.options["additional_function_arguments"] == {"tenant_id": "user"} + + +async def _post_json(server: ResponsesHostServer, payload: dict[str, Any]) -> httpx.Response: + transport = httpx.ASGITransport(app=server) + async with httpx.AsyncClient(transport=transport, base_url="http://test") as client: + return await client.post("/responses", json=payload) + + +def _make_server(agent: Any, **kwargs: Any) -> ResponsesHostServer: + return ResponsesHostServer(agent, response_store=InMemoryResponseProvider(), **kwargs) + + +@pytest.mark.xdist_group("session_isolation") +class TestCallerCannotOverrideToolContext: + async def test_baseline_uses_trusted_tool_context(self) -> None: + seen: list[Any] = [] + server = _make_server(make_tenant_agent(seen, approval_mode="never_require")) + + response = await _post_json(server, {"input": "go", "stream": False}) + + assert response.json()["status"] == "completed" + assert seen == [TRUSTED_TENANT_ID] + + @pytest.mark.parametrize("stream", [False, True]) + @pytest.mark.parametrize("location", ["top_level", "extra_body"]) + async def test_forged_tool_context_is_rejected_before_any_tool_runs( + self, location: Literal["top_level", "extra_body"], stream: bool + ) -> None: + seen: list[Any] = [] + agent = make_tenant_agent(seen, approval_mode="never_require") + server = _make_server(agent) + payload: dict[str, Any] = {"input": "go", "stream": stream} + if location == "top_level": + payload.update(FORGED_TENANT_CONTEXT) + else: + payload["extra_body"] = FORGED_TENANT_CONTEXT + + response = await _post_json(server, payload) + + assert "additional_function_arguments" in response.text + assert "failed" in response.text + assert seen == [] + assert cast(ToolCallingClient, agent.client).calls == 0 + + async def test_hook_can_still_supply_trusted_tool_context(self) -> None: + seen: list[Any] = [] + server = _make_server( + make_tenant_agent(seen, approval_mode="never_require"), + prepare_options=lambda request, options: { + **options, + "additional_function_arguments": {"tenant_id": f"from-hook:{request.scope.user_id}"}, + }, + ) + + response = await _post_json(server, {"input": "go", "stream": False}) + + assert response.json()["status"] == "completed" + assert len(seen) == 1 + assert str(seen[0]).startswith("from-hook:") + + async def test_forged_context_on_approval_resume_is_rejected_without_consuming_approval(self) -> None: + seen: list[Any] = [] + server = _make_server(make_tenant_agent(seen, approval_mode="always_require")) + + first = await _post_json(server, {"input": "go", "stream": False, "store": True}) + first_body = first.json() + approval_id = next(item["id"] for item in first_body["output"] if item["type"] == "mcp_approval_request") + assert seen == [] + + def resume(**extra: Any) -> dict[str, Any]: + return { + "input": [{"type": "mcp_approval_response", "approval_request_id": approval_id, "approve": True}], + "previous_response_id": first_body["id"], + "stream": False, + "store": True, + **extra, + } + + forged = await _post_json(server, resume(**FORGED_TENANT_CONTEXT)) + assert "additional_function_arguments" in forged.text + assert seen == [] + + legitimate = await _post_json(server, resume()) + assert legitimate.json()["status"] == "completed" + assert seen == [TRUSTED_TENANT_ID] diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/tool_context_helpers.py b/python/packages/foundry_hosting/tests/foundry_hosting/tool_context_helpers.py new file mode 100644 index 00000000000..6135b679615 --- /dev/null +++ b/python/packages/foundry_hosting/tests/foundry_hosting/tool_context_helpers.py @@ -0,0 +1,80 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Deterministic agent helpers for hosted tool-execution-context tests.""" + +from __future__ import annotations + +from collections.abc import AsyncIterator, Awaitable, Mapping, Sequence +from typing import Any, Literal + +from agent_framework import ( + Agent, + BaseChatClient, + ChatMiddlewareLayer, + ChatResponse, + ChatResponseUpdate, + Content, + FunctionInvocationContext, + FunctionInvocationLayer, + Message, + ResponseStream, + tool, +) + +TRUSTED_TENANT_ID = "trusted" +FORGED_TENANT_CONTEXT: dict[str, Any] = {"additional_function_arguments": {"tenant_id": "forged"}} + + +class ToolCallingClient( + FunctionInvocationLayer[Any], + ChatMiddlewareLayer[Any], + BaseChatClient[Any], +): + """Call ``read_tenant_data`` once, then answer.""" + + def __init__(self) -> None: + super().__init__(middleware=[]) + 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 options, kwargs + assert stream is True, "The inner agent only runs in stream mode in Foundry Hosted Agents." + self.calls += 1 + needs_tool_call = not any( + content.type == "function_result" for message in messages for content in message.contents + ) + + async def stream_response() -> AsyncIterator[ChatResponseUpdate]: + if needs_tool_call: + yield ChatResponseUpdate( + contents=[Content.from_function_call(call_id="call_1", name="read_tenant_data", arguments="{}")], + role="assistant", + ) + else: + yield ChatResponseUpdate(contents=[Content.from_text("done")], role="assistant") + + return ResponseStream(stream_response(), finalizer=ChatResponse.from_updates) + + +def make_tenant_agent( + seen_tenants: list[Any], *, approval_mode: Literal["always_require", "never_require"] +) -> Agent[Any]: + """Create an agent whose tool records the tenant it receives from hidden runtime context.""" + + @tool(name="read_tenant_data", approval_mode=approval_mode) + def read_tenant_data(ctx: FunctionInvocationContext) -> str: + seen_tenants.append(ctx.kwargs.get("tenant_id")) + return "ok" + + return Agent( + client=ToolCallingClient(), + tools=[read_tenant_data], + default_options={"additional_function_arguments": {"tenant_id": TRUSTED_TENANT_ID}}, + ) diff --git a/python/packages/foundry_hosting/tests/test_request.py b/python/packages/foundry_hosting/tests/test_request.py index 489bbda6a9f..6496e7e8b6f 100644 --- a/python/packages/foundry_hosting/tests/test_request.py +++ b/python/packages/foundry_hosting/tests/test_request.py @@ -75,40 +75,6 @@ def test_nested_extra_body_is_also_overlaid_last_without_reserved_fields() -> No response_run_options(cast(CreateResponse, {"extra_body": {"extra_body": {"store": True}}})) -@pytest.mark.parametrize( - "payload", - [ - {"additional_function_arguments": {"tenant_id": "forged"}}, - {"extra_body": {"additional_function_arguments": {"tenant_id": "forged"}}}, - {"additional_function_arguments": None}, - {"extra_body": {"additional_function_arguments": None}}, - ], -) -def test_caller_cannot_supply_tool_execution_context(payload: dict[str, Any]) -> None: - with pytest.raises(ValueError, match="agent-controlled fields: additional_function_arguments"): - response_run_options(cast(CreateResponse, {"input": "hello", "temperature": 0.2, **payload})) - - -def test_requests_without_tool_context_keep_other_options() -> None: - request = cast(CreateResponse, {"input": "hello", "extra_body": {"slogan_style": "retro"}, "temperature": 0.2}) - assert response_run_options(request) == {"temperature": 0.2, "slogan_style": "retro"} - - -async def test_hook_can_supply_trusted_tool_context() -> None: - context = MagicMock(spec=ResponseContext) - context.response_id = "outer-id" - context.conversation_id = None - scope = FoundryRequestScope(session_id="sandbox", user_id="user", call_id="call", is_hosted=True) - request = HostedResponseRequest(cast(CreateResponse, {"input": "hello"}), context, scope, {}) - - def inject(view: HostedResponseRequest, options: dict[str, Any]) -> dict[str, Any]: - return {**options, "additional_function_arguments": {"tenant_id": view.scope.user_id}} - - await prepare_response_options(request, inject) - validate_request_options(request.options) - assert request.options["additional_function_arguments"] == {"tenant_id": "user"} - - async def test_hook_uses_a_request_copy_and_does_not_mutate_defaults() -> None: payload = cast(CreateResponse, {"input": "hello", "metadata": {"source": "caller"}}) context = MagicMock(spec=ResponseContext) diff --git a/python/packages/foundry_hosting/tests/test_responses.py b/python/packages/foundry_hosting/tests/test_responses.py index 8ef1931104d..dc9b643bd33 100644 --- a/python/packages/foundry_hosting/tests/test_responses.py +++ b/python/packages/foundry_hosting/tests/test_responses.py @@ -42,7 +42,6 @@ Content, FinishReason, FinishReasonLiteral, - FunctionInvocationContext, FunctionInvocationLayer, HistoryProvider, InMemoryCheckpointStorage, @@ -7536,144 +7535,6 @@ async def test_approval_response_referencing_unknown_id_fails(self) -> None: # endregion -# region Caller-controlled tool execution context - - -class _ToolCallingClient( - FunctionInvocationLayer[Any], - ChatMiddlewareLayer[Any], - BaseChatClient[Any], -): - """Deterministic client: call ``read_tenant_data`` once, then answer.""" - - def __init__(self) -> None: - super().__init__(middleware=[]) - 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 options, kwargs - assert stream is True, "The inner agent only runs in stream mode in Foundry Hosted Agents." - self.calls += 1 - needs_tool_call = not any( - isinstance(content, Content) and content.type == "function_result" - for message in messages - for content in message.contents - ) - - async def stream_response() -> AsyncIterator[ChatResponseUpdate]: - if needs_tool_call: - yield ChatResponseUpdate( - contents=[Content.from_function_call(call_id="call_1", name="read_tenant_data", arguments="{}")], - role="assistant", - ) - else: - yield ChatResponseUpdate(contents=[Content.from_text("done")], role="assistant") - - return ResponseStream(stream_response(), finalizer=ChatResponse.from_updates) - - -def _make_tenant_agent(seen_tenants: list[Any], *, approval_mode: Literal["always_require", "never_require"]) -> Agent: - @tool(name="read_tenant_data", approval_mode=approval_mode) - def read_tenant_data(ctx: FunctionInvocationContext) -> str: - seen_tenants.append(ctx.kwargs.get("tenant_id")) - return "ok" - - return Agent( - client=_ToolCallingClient(), - tools=[read_tenant_data], - default_options={"additional_function_arguments": {"tenant_id": "trusted"}}, - ) - - -_FORGED_TENANT_CONTEXT = {"additional_function_arguments": {"tenant_id": "forged"}} - - -class TestCallerCannotOverrideToolContext: - """Callers must not replace host-configured tool context through any request path.""" - - async def test_baseline_uses_trusted_tool_context(self) -> None: - seen: list[Any] = [] - server = _make_server(_make_tenant_agent(seen, approval_mode="never_require")) - - response = await _post_json(server, {"input": "go", "stream": False}) - - assert response.json()["status"] == "completed" - assert seen == ["trusted"] - - @pytest.mark.parametrize("stream", [False, True]) - @pytest.mark.parametrize("location", ["top_level", "extra_body"]) - async def test_forged_tool_context_is_rejected_before_any_tool_runs( - self, location: Literal["top_level", "extra_body"], stream: bool - ) -> None: - seen: list[Any] = [] - agent = _make_tenant_agent(seen, approval_mode="never_require") - server = _make_server(agent) - payload: dict[str, Any] = {"input": "go", "stream": stream} - if location == "top_level": - payload.update(_FORGED_TENANT_CONTEXT) - else: - payload["extra_body"] = _FORGED_TENANT_CONTEXT - - response = await _post_json(server, payload) - - assert "additional_function_arguments" in response.text - assert "failed" in response.text - assert seen == [] - assert cast(_ToolCallingClient, agent.client).calls == 0 - - async def test_hook_can_still_supply_trusted_tool_context(self) -> None: - seen: list[Any] = [] - server = _make_server( - _make_tenant_agent(seen, approval_mode="never_require"), - prepare_options=lambda request, options: { - **options, - "additional_function_arguments": {"tenant_id": f"from-hook:{request.scope.user_id}"}, - }, - ) - - response = await _post_json(server, {"input": "go", "stream": False}) - - assert response.json()["status"] == "completed" - assert len(seen) == 1 - assert str(seen[0]).startswith("from-hook:") - - async def test_forged_context_on_approval_resume_is_rejected_without_consuming_approval(self) -> None: - seen: list[Any] = [] - server = _make_server(_make_tenant_agent(seen, approval_mode="always_require")) - - first = await _post_json(server, {"input": "go", "stream": False, "store": True}) - first_body = first.json() - approval_id = next(item["id"] for item in first_body["output"] if item["type"] == "mcp_approval_request") - assert seen == [] - - def resume(**extra: Any) -> dict[str, Any]: - return { - "input": [{"type": "mcp_approval_response", "approval_request_id": approval_id, "approve": True}], - "previous_response_id": first_body["id"], - "stream": False, - "store": True, - **extra, - } - - forged = await _post_json(server, resume(**_FORGED_TENANT_CONTEXT)) - assert "additional_function_arguments" in forged.text - assert seen == [] - - legitimate = await _post_json(server, resume()) - assert legitimate.json()["status"] == "completed" - assert seen == ["trusted"] - - -# endregion - - # region Checkpoint context validation From 5ace1879457dd72e87d78d55287fcb99dd28d130 Mon Sep 17 00:00:00 2001 From: Darren Cohen <39422044+dargilco@users.noreply.github.com> Date: Fri, 23 Oct 2026 18:04:13 -0700 Subject: [PATCH 03/13] Apply caller tool-context rejection to legacy WorkflowAgent Responses requests Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../_request.py | 21 ++++++++++--- .../_responses.py | 5 ++++ .../test_caller_tool_context.py | 30 +++++++++++++++++++ .../foundry_hosting/tool_context_helpers.py | 17 +++++++++++ 4 files changed, 69 insertions(+), 4 deletions(-) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_request.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_request.py index 3056dff375e..277bca76344 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_request.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_request.py @@ -130,18 +130,32 @@ def _reject_caller_controls(names: Iterable[str]) -> None: ) +def reject_caller_tool_context(request: CreateResponse) -> None: + """Reject caller-supplied agent-controlled tool context, at the top level or in ``extra_body``. + + This applies to every hosted Responses request, whichever agent or workflow shape serves it, so callers can + never replace trusted values configured by the developer. + + Raises: + ValueError: If the request sets an agent-controlled field. + """ + _reject_caller_controls(cast(Mapping[str, Any], request)) + extra_body = request.get("extra_body") + if isinstance(extra_body, Mapping): + _reject_caller_controls(cast(Mapping[str, Any], extra_body)) + + def response_run_options(request: CreateResponse) -> dict[str, Any]: """Translate native generation fields, with flattened extra-body values winning collisions. Raises: - ValueError: If the caller supplies agent-controlled tool-execution context, at the top level or in - ``extra_body``, so it can never replace trusted values configured by the developer. + ValueError: If the caller supplies agent-controlled tool-execution context. """ + reject_caller_tool_context(request) native: dict[str, Any] = {} extra: dict[str, Any] = {} nested_extra: dict[str, Any] = {} for name, value in request.items(): - _reject_caller_controls((name,)) if value is None or (name == "model" and value == ""): continue if name == "extra_body": @@ -151,7 +165,6 @@ 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.") - _reject_caller_controls(cast(Mapping[str, Any], value)) nested_extra.update(cast(Mapping[str, Any], value)) elif name in _HOST_CONTROLLED_FIELDS: continue diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses.py index 09692723734..0fce25cb093 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses.py @@ -110,6 +110,7 @@ UnsupportedOptions, WorkflowTurn, prepare_response_options, + reject_caller_tool_context, response_run_options, validate_default_transport_options, validate_request_options, @@ -1154,6 +1155,10 @@ async def _handle_response( _initialize_agent_history(agent, configuration) if configuration.workflow: self._warn_legacy_workflow() + try: + reject_caller_tool_context(request) + except ValueError as exc: + raise _PublicResponseFailure(exc) from None hosted_request: HostedResponseRequest | None = None if configuration.workflow: if self._prepare_options is not None: diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_caller_tool_context.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_caller_tool_context.py index df91fefa297..d0b74669027 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_caller_tool_context.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_caller_tool_context.py @@ -16,6 +16,7 @@ TRUSTED_TENANT_ID, ToolCallingClient, make_tenant_agent, + make_tenant_workflow_agent, ) from agent_framework_foundry_hosting import HostedResponseRequest, ResponsesHostServer @@ -104,6 +105,35 @@ async def test_forged_tool_context_is_rejected_before_any_tool_runs( assert seen == [] assert cast(ToolCallingClient, agent.client).calls == 0 + @pytest.mark.filterwarnings("ignore:Hosting WorkflowAgent through agent=.*:DeprecationWarning") + @pytest.mark.parametrize("location", ["top_level", "extra_body"]) + async def test_forged_tool_context_is_rejected_for_legacy_workflow_agents( + self, location: Literal["top_level", "extra_body"] + ) -> None: + seen: list[Any] = [] + server = _make_server(make_tenant_workflow_agent(seen)) + payload: dict[str, Any] = {"input": "go", "stream": False} + if location == "top_level": + payload.update(FORGED_TENANT_CONTEXT) + else: + payload["extra_body"] = FORGED_TENANT_CONTEXT + + response = await _post_json(server, payload) + + assert "additional_function_arguments" in response.text + assert response.json()["status"] == "failed" + assert seen == [] + + @pytest.mark.filterwarnings("ignore:Hosting WorkflowAgent through agent=.*:DeprecationWarning") + async def test_legacy_workflow_agent_without_forged_context_still_runs(self) -> None: + seen: list[Any] = [] + server = _make_server(make_tenant_workflow_agent(seen)) + + response = await _post_json(server, {"input": "go", "stream": False}) + + assert response.json()["status"] == "completed" + assert seen == [TRUSTED_TENANT_ID] + async def test_hook_can_still_supply_trusted_tool_context(self) -> None: seen: list[Any] = [] server = _make_server( diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/tool_context_helpers.py b/python/packages/foundry_hosting/tests/foundry_hosting/tool_context_helpers.py index 6135b679615..f6356ea08d3 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/tool_context_helpers.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/tool_context_helpers.py @@ -9,6 +9,7 @@ from agent_framework import ( Agent, + AgentExecutorRequest, BaseChatClient, ChatMiddlewareLayer, ChatResponse, @@ -18,6 +19,10 @@ FunctionInvocationLayer, Message, ResponseStream, + WorkflowAgent, + WorkflowBuilder, + WorkflowContext, + executor, tool, ) @@ -78,3 +83,15 @@ def read_tenant_data(ctx: FunctionInvocationContext) -> str: tools=[read_tenant_data], default_options={"additional_function_arguments": {"tenant_id": TRUSTED_TENANT_ID}}, ) + + +def make_tenant_workflow_agent(seen_tenants: list[Any]) -> WorkflowAgent: + """Wrap the tenant agent in a legacy ``WorkflowAgent`` so the workflow hosting path can be exercised.""" + + @executor + async def start(messages: list[Message], ctx: WorkflowContext[AgentExecutorRequest]) -> None: + await ctx.send_message(AgentExecutorRequest(messages=messages, should_respond=True)) + + inner = make_tenant_agent(seen_tenants, approval_mode="never_require") + workflow = WorkflowBuilder(start_executor=start).add_edge(start, inner).build() + return WorkflowAgent(workflow=workflow, name="Tenant Workflow Agent") From 07ac9b2ce651e272ca3b39dafedf164f644a98cb Mon Sep 17 00:00:00 2001 From: Darren Cohen <39422044+dargilco@users.noreply.github.com> Date: Fri, 23 Oct 2026 18:17:46 -0700 Subject: [PATCH 04/13] Fix pyright error in tool-context test helper default_options Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../tests/foundry_hosting/tool_context_helpers.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/tool_context_helpers.py b/python/packages/foundry_hosting/tests/foundry_hosting/tool_context_helpers.py index f6356ea08d3..f842ab5e0d8 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/tool_context_helpers.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/tool_context_helpers.py @@ -5,7 +5,7 @@ from __future__ import annotations from collections.abc import AsyncIterator, Awaitable, Mapping, Sequence -from typing import Any, Literal +from typing import Any, Literal, cast from agent_framework import ( Agent, @@ -81,7 +81,7 @@ def read_tenant_data(ctx: FunctionInvocationContext) -> str: return Agent( client=ToolCallingClient(), tools=[read_tenant_data], - default_options={"additional_function_arguments": {"tenant_id": TRUSTED_TENANT_ID}}, + default_options=cast(Any, {"additional_function_arguments": {"tenant_id": TRUSTED_TENANT_ID}}), ) From 86e90d1a4c185e94797c9a2a50b84d659d921396 Mon Sep 17 00:00:00 2001 From: Darren Cohen <39422044+dargilco@users.noreply.github.com> Date: Fri, 23 Oct 2026 20:02:19 -0700 Subject: [PATCH 05/13] Make foundry_hosting test helpers importable under --import-mode=importlib Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../tests/foundry_hosting/conftest.py | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/conftest.py diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/conftest.py b/python/packages/foundry_hosting/tests/foundry_hosting/conftest.py new file mode 100644 index 00000000000..61818a7e62b --- /dev/null +++ b/python/packages/foundry_hosting/tests/foundry_hosting/conftest.py @@ -0,0 +1,13 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Make helper modules in this directory importable by name under any pytest import mode.""" + +import sys +from pathlib import Path + + +def pytest_configure() -> None: + """Put this directory on sys.path; the workspace test sweep uses --import-mode=importlib.""" + test_dir = str(Path(__file__).resolve().parent) + if test_dir not in sys.path: + sys.path.insert(0, test_dir) From 307b7b9e969beb830cbd0a7bc4088c3c06b5109f Mon Sep 17 00:00:00 2001 From: Darren Cohen <39422044+dargilco@users.noreply.github.com> Date: Fri, 23 Oct 2026 20:15:48 -0700 Subject: [PATCH 06/13] Replace sys.path test helper with fixtures to avoid shadowing other packages' conftest Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../tests/foundry_hosting/conftest.py | 109 ++++++++++++++++-- .../test_caller_tool_context.py | 41 +++---- .../foundry_hosting/tool_context_helpers.py | 97 ---------------- 3 files changed, 122 insertions(+), 125 deletions(-) delete mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/tool_context_helpers.py diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/conftest.py b/python/packages/foundry_hosting/tests/foundry_hosting/conftest.py index 61818a7e62b..744e9505e86 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/conftest.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/conftest.py @@ -1,13 +1,106 @@ # Copyright (c) Microsoft. All rights reserved. -"""Make helper modules in this directory importable by name under any pytest import mode.""" +"""Fixtures for hosted tool-execution-context tests.""" -import sys -from pathlib import Path +from __future__ import annotations +from collections.abc import AsyncIterator, Awaitable, Callable, Mapping, Sequence +from typing import Any, Literal, cast -def pytest_configure() -> None: - """Put this directory on sys.path; the workspace test sweep uses --import-mode=importlib.""" - test_dir = str(Path(__file__).resolve().parent) - if test_dir not in sys.path: - sys.path.insert(0, test_dir) +import pytest +from agent_framework import ( + Agent, + AgentExecutorRequest, + BaseChatClient, + ChatMiddlewareLayer, + ChatResponse, + ChatResponseUpdate, + Content, + FunctionInvocationContext, + FunctionInvocationLayer, + Message, + ResponseStream, + WorkflowAgent, + WorkflowBuilder, + WorkflowContext, + executor, + tool, +) + +TRUSTED_TENANT_ID = "trusted" + +TenantAgentFactory = Callable[..., Agent[Any]] +TenantWorkflowAgentFactory = Callable[[list[Any]], WorkflowAgent] + + +class _ToolCallingClient( + FunctionInvocationLayer[Any], + ChatMiddlewareLayer[Any], + BaseChatClient[Any], +): + """Call ``read_tenant_data`` once, then answer.""" + + def __init__(self) -> None: + super().__init__(middleware=[]) + 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 options, kwargs + assert stream is True, "The inner agent only runs in stream mode in Foundry Hosted Agents." + self.calls += 1 + needs_tool_call = not any( + content.type == "function_result" for message in messages for content in message.contents + ) + + async def stream_response() -> AsyncIterator[ChatResponseUpdate]: + if needs_tool_call: + yield ChatResponseUpdate( + contents=[Content.from_function_call(call_id="call_1", name="read_tenant_data", arguments="{}")], + role="assistant", + ) + else: + yield ChatResponseUpdate(contents=[Content.from_text("done")], role="assistant") + + return ResponseStream(stream_response(), finalizer=ChatResponse.from_updates) + + +@pytest.fixture +def tenant_agent_factory() -> TenantAgentFactory: + """Create agents whose tool records the tenant it receives from hidden runtime context.""" + + def factory(seen_tenants: list[Any], *, approval_mode: Literal["always_require", "never_require"]) -> Agent[Any]: + @tool(name="read_tenant_data", approval_mode=approval_mode) + def read_tenant_data(ctx: FunctionInvocationContext) -> str: + seen_tenants.append(ctx.kwargs.get("tenant_id")) + return "ok" + + return Agent( + client=_ToolCallingClient(), + tools=[read_tenant_data], + default_options=cast(Any, {"additional_function_arguments": {"tenant_id": TRUSTED_TENANT_ID}}), + ) + + return factory + + +@pytest.fixture +def tenant_workflow_agent_factory(tenant_agent_factory: TenantAgentFactory) -> TenantWorkflowAgentFactory: + """Wrap the tenant agent in a legacy ``WorkflowAgent`` so the workflow hosting path can be exercised.""" + + def factory(seen_tenants: list[Any]) -> WorkflowAgent: + @executor + async def start(messages: list[Message], ctx: WorkflowContext[AgentExecutorRequest]) -> None: + await ctx.send_message(AgentExecutorRequest(messages=messages, should_respond=True)) + + inner = tenant_agent_factory(seen_tenants, approval_mode="never_require") + workflow = WorkflowBuilder(start_executor=start).add_edge(start, inner).build() + return WorkflowAgent(workflow=workflow, name="Tenant Workflow Agent") + + return factory diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_caller_tool_context.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_caller_tool_context.py index d0b74669027..71e69a4a767 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_caller_tool_context.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_caller_tool_context.py @@ -4,6 +4,7 @@ from __future__ import annotations +from collections.abc import Callable from typing import Any, Literal, cast from unittest.mock import AsyncMock, MagicMock @@ -11,13 +12,6 @@ import pytest from azure.ai.agentserver.responses import InMemoryResponseProvider, ResponseContext from azure.ai.agentserver.responses.models import CreateResponse -from tool_context_helpers import ( # pyrefly: ignore[missing-import] # pyright: ignore[reportMissingImports] - FORGED_TENANT_CONTEXT, - TRUSTED_TENANT_ID, - ToolCallingClient, - make_tenant_agent, - make_tenant_workflow_agent, -) from agent_framework_foundry_hosting import HostedResponseRequest, ResponsesHostServer from agent_framework_foundry_hosting._request import ( @@ -27,6 +21,9 @@ ) from agent_framework_foundry_hosting._scope import FoundryRequestScope +TRUSTED_TENANT_ID = "trusted" +FORGED_TENANT_CONTEXT: dict[str, Any] = {"additional_function_arguments": {"tenant_id": "forged"}} + @pytest.mark.parametrize( "payload", @@ -75,9 +72,9 @@ def _make_server(agent: Any, **kwargs: Any) -> ResponsesHostServer: @pytest.mark.xdist_group("session_isolation") class TestCallerCannotOverrideToolContext: - async def test_baseline_uses_trusted_tool_context(self) -> None: + async def test_baseline_uses_trusted_tool_context(self, tenant_agent_factory: Callable[..., Any]) -> None: seen: list[Any] = [] - server = _make_server(make_tenant_agent(seen, approval_mode="never_require")) + server = _make_server(tenant_agent_factory(seen, approval_mode="never_require")) response = await _post_json(server, {"input": "go", "stream": False}) @@ -87,10 +84,10 @@ async def test_baseline_uses_trusted_tool_context(self) -> None: @pytest.mark.parametrize("stream", [False, True]) @pytest.mark.parametrize("location", ["top_level", "extra_body"]) async def test_forged_tool_context_is_rejected_before_any_tool_runs( - self, location: Literal["top_level", "extra_body"], stream: bool + self, tenant_agent_factory: Callable[..., Any], location: Literal["top_level", "extra_body"], stream: bool ) -> None: seen: list[Any] = [] - agent = make_tenant_agent(seen, approval_mode="never_require") + agent = tenant_agent_factory(seen, approval_mode="never_require") server = _make_server(agent) payload: dict[str, Any] = {"input": "go", "stream": stream} if location == "top_level": @@ -103,15 +100,15 @@ async def test_forged_tool_context_is_rejected_before_any_tool_runs( assert "additional_function_arguments" in response.text assert "failed" in response.text assert seen == [] - assert cast(ToolCallingClient, agent.client).calls == 0 + assert cast(Any, agent.client).calls == 0 @pytest.mark.filterwarnings("ignore:Hosting WorkflowAgent through agent=.*:DeprecationWarning") @pytest.mark.parametrize("location", ["top_level", "extra_body"]) async def test_forged_tool_context_is_rejected_for_legacy_workflow_agents( - self, location: Literal["top_level", "extra_body"] + self, tenant_workflow_agent_factory: Callable[..., Any], location: Literal["top_level", "extra_body"] ) -> None: seen: list[Any] = [] - server = _make_server(make_tenant_workflow_agent(seen)) + server = _make_server(tenant_workflow_agent_factory(seen)) payload: dict[str, Any] = {"input": "go", "stream": False} if location == "top_level": payload.update(FORGED_TENANT_CONTEXT) @@ -125,19 +122,21 @@ async def test_forged_tool_context_is_rejected_for_legacy_workflow_agents( assert seen == [] @pytest.mark.filterwarnings("ignore:Hosting WorkflowAgent through agent=.*:DeprecationWarning") - async def test_legacy_workflow_agent_without_forged_context_still_runs(self) -> None: + async def test_legacy_workflow_agent_without_forged_context_still_runs( + self, tenant_workflow_agent_factory: Callable[..., Any] + ) -> None: seen: list[Any] = [] - server = _make_server(make_tenant_workflow_agent(seen)) + server = _make_server(tenant_workflow_agent_factory(seen)) response = await _post_json(server, {"input": "go", "stream": False}) assert response.json()["status"] == "completed" assert seen == [TRUSTED_TENANT_ID] - async def test_hook_can_still_supply_trusted_tool_context(self) -> None: + async def test_hook_can_still_supply_trusted_tool_context(self, tenant_agent_factory: Callable[..., Any]) -> None: seen: list[Any] = [] server = _make_server( - make_tenant_agent(seen, approval_mode="never_require"), + tenant_agent_factory(seen, approval_mode="never_require"), prepare_options=lambda request, options: { **options, "additional_function_arguments": {"tenant_id": f"from-hook:{request.scope.user_id}"}, @@ -150,9 +149,11 @@ async def test_hook_can_still_supply_trusted_tool_context(self) -> None: assert len(seen) == 1 assert str(seen[0]).startswith("from-hook:") - async def test_forged_context_on_approval_resume_is_rejected_without_consuming_approval(self) -> None: + async def test_forged_context_on_approval_resume_is_rejected_without_consuming_approval( + self, tenant_agent_factory: Callable[..., Any] + ) -> None: seen: list[Any] = [] - server = _make_server(make_tenant_agent(seen, approval_mode="always_require")) + server = _make_server(tenant_agent_factory(seen, approval_mode="always_require")) first = await _post_json(server, {"input": "go", "stream": False, "store": True}) first_body = first.json() diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/tool_context_helpers.py b/python/packages/foundry_hosting/tests/foundry_hosting/tool_context_helpers.py deleted file mode 100644 index f842ab5e0d8..00000000000 --- a/python/packages/foundry_hosting/tests/foundry_hosting/tool_context_helpers.py +++ /dev/null @@ -1,97 +0,0 @@ -# Copyright (c) Microsoft. All rights reserved. - -"""Deterministic agent helpers for hosted tool-execution-context tests.""" - -from __future__ import annotations - -from collections.abc import AsyncIterator, Awaitable, Mapping, Sequence -from typing import Any, Literal, cast - -from agent_framework import ( - Agent, - AgentExecutorRequest, - BaseChatClient, - ChatMiddlewareLayer, - ChatResponse, - ChatResponseUpdate, - Content, - FunctionInvocationContext, - FunctionInvocationLayer, - Message, - ResponseStream, - WorkflowAgent, - WorkflowBuilder, - WorkflowContext, - executor, - tool, -) - -TRUSTED_TENANT_ID = "trusted" -FORGED_TENANT_CONTEXT: dict[str, Any] = {"additional_function_arguments": {"tenant_id": "forged"}} - - -class ToolCallingClient( - FunctionInvocationLayer[Any], - ChatMiddlewareLayer[Any], - BaseChatClient[Any], -): - """Call ``read_tenant_data`` once, then answer.""" - - def __init__(self) -> None: - super().__init__(middleware=[]) - 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 options, kwargs - assert stream is True, "The inner agent only runs in stream mode in Foundry Hosted Agents." - self.calls += 1 - needs_tool_call = not any( - content.type == "function_result" for message in messages for content in message.contents - ) - - async def stream_response() -> AsyncIterator[ChatResponseUpdate]: - if needs_tool_call: - yield ChatResponseUpdate( - contents=[Content.from_function_call(call_id="call_1", name="read_tenant_data", arguments="{}")], - role="assistant", - ) - else: - yield ChatResponseUpdate(contents=[Content.from_text("done")], role="assistant") - - return ResponseStream(stream_response(), finalizer=ChatResponse.from_updates) - - -def make_tenant_agent( - seen_tenants: list[Any], *, approval_mode: Literal["always_require", "never_require"] -) -> Agent[Any]: - """Create an agent whose tool records the tenant it receives from hidden runtime context.""" - - @tool(name="read_tenant_data", approval_mode=approval_mode) - def read_tenant_data(ctx: FunctionInvocationContext) -> str: - seen_tenants.append(ctx.kwargs.get("tenant_id")) - return "ok" - - return Agent( - client=ToolCallingClient(), - tools=[read_tenant_data], - default_options=cast(Any, {"additional_function_arguments": {"tenant_id": TRUSTED_TENANT_ID}}), - ) - - -def make_tenant_workflow_agent(seen_tenants: list[Any]) -> WorkflowAgent: - """Wrap the tenant agent in a legacy ``WorkflowAgent`` so the workflow hosting path can be exercised.""" - - @executor - async def start(messages: list[Message], ctx: WorkflowContext[AgentExecutorRequest]) -> None: - await ctx.send_message(AgentExecutorRequest(messages=messages, should_respond=True)) - - inner = make_tenant_agent(seen_tenants, approval_mode="never_require") - workflow = WorkflowBuilder(start_executor=start).add_edge(start, inner).build() - return WorkflowAgent(workflow=workflow, name="Tenant Workflow Agent") From 1bb4b33c2cde16f355e91df1beebeaaf1b377920 Mon Sep 17 00:00:00 2001 From: Darren Cohen <39422044+dargilco@users.noreply.github.com> Date: Fri, 23 Oct 2026 20:39:22 -0700 Subject: [PATCH 07/13] Remove redundant cast flagged by ty in tool-context test Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../tests/foundry_hosting/test_caller_tool_context.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_caller_tool_context.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_caller_tool_context.py index 71e69a4a767..bc4682d8500 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_caller_tool_context.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_caller_tool_context.py @@ -100,7 +100,7 @@ async def test_forged_tool_context_is_rejected_before_any_tool_runs( assert "additional_function_arguments" in response.text assert "failed" in response.text assert seen == [] - assert cast(Any, agent.client).calls == 0 + assert agent.client.calls == 0 @pytest.mark.filterwarnings("ignore:Hosting WorkflowAgent through agent=.*:DeprecationWarning") @pytest.mark.parametrize("location", ["top_level", "extra_body"]) From 4784b7cdb775d6ede5d38342b60d629d4c0728d2 Mon Sep 17 00:00:00 2001 From: Darren Cohen <39422044+dargilco@users.noreply.github.com> Date: Mon, 9 Nov 2026 17:48:52 -0800 Subject: [PATCH 08/13] clarify you need to run commands in the python folder --- python/DEV_SETUP.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/python/DEV_SETUP.md b/python/DEV_SETUP.md index 6d06fb025a0..5ebb1544923 100644 --- a/python/DEV_SETUP.md +++ b/python/DEV_SETUP.md @@ -2,7 +2,7 @@ This document describes how to setup your environment with Python and uv, if you're working on new features or a bug fix for Agent Framework, or simply -want to run the tests included. +want to run the tests included. All commands shown here assume your terminal is opened in the "python" folder of your clone, where this file is located. For coding standards and conventions, see [CODING_STANDARD.md](CODING_STANDARD.md). @@ -61,7 +61,7 @@ The exact supported uv version is declared by `required-version` in `pyproject.toml`. uv will stop with an actionable error when the installed version does not match. -You can then run the following commands manually: +You can then run the following commands manually in a terminal opened in the "python" folder of your clone: ```bash # Install every Python version covered by CI From 058e8392a13d1c3b4f96d0a8524b17e294fd0ab8 Mon Sep 17 00:00:00 2001 From: Darren Cohen <39422044+dargilco@users.noreply.github.com> Date: Thu, 12 Nov 2026 08:46:00 -0800 Subject: [PATCH 09/13] Update doc --- python/DEV_SETUP.md | 1 + 1 file changed, 1 insertion(+) diff --git a/python/DEV_SETUP.md b/python/DEV_SETUP.md index 5ebb1544923..824f5406058 100644 --- a/python/DEV_SETUP.md +++ b/python/DEV_SETUP.md @@ -69,6 +69,7 @@ uv python install 3.11 3.12 3.13 3.14 3.15 # Use Python 3.11 through 3.14 for a full-workspace development environment PYTHON_VERSION="3.13" uv venv --python $PYTHON_VERSION +# Activate your virtual environment per console instructions # Install AF and all workspace dependencies uv run poe install # Install prek hooks From 75d4012d258d39af9f305c4d49ef31fcc86c84fa Mon Sep 17 00:00:00 2001 From: Darren Cohen <39422044+dargilco@users.noreply.github.com> Date: Thu, 12 Nov 2026 11:19:33 -0800 Subject: [PATCH 10/13] more --- .../_request.py | 95 ++++++---- .../_responses.py | 15 +- .../_workflow_responses.py | 2 + .../tests/foundry_hosting/conftest.py | 106 ----------- .../test_caller_tool_context.py | 178 ------------------ .../foundry_hosting/test_native_responses.py | 11 +- .../foundry_hosting/tests/test_request.py | 66 +++++-- .../foundry_hosting/tests/test_responses.py | 67 ++++++- 8 files changed, 196 insertions(+), 344 deletions(-) delete mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/conftest.py delete mode 100644 python/packages/foundry_hosting/tests/foundry_hosting/test_caller_tool_context.py diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_request.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_request.py index 277bca76344..c22771ac6e2 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_request.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_request.py @@ -5,7 +5,7 @@ from __future__ import annotations import inspect -from collections.abc import Awaitable, Callable, Iterable, Mapping, Sequence +from collections.abc import Awaitable, Callable, Mapping, Sequence from copy import deepcopy from dataclasses import dataclass, field from types import MappingProxyType @@ -116,44 +116,72 @@ def __post_init__(self) -> None: }) _OPTION_NAMES = {"max_output_tokens": "max_tokens", "parallel_tool_calls": "allow_multiple_tool_calls"} _NATIVE_FIELDS = frozenset(CreateResponse.__annotations__) -# Trusted tool-execution context that callers must not supply. Unlike ``_HOST_CONTROLLED_FIELDS``, a developer -# ``prepare_options`` hook may still set it from trusted host state. -_CALLER_REJECTED_FIELDS = frozenset({"additional_function_arguments"}) - - -def _reject_caller_controls(names: Iterable[str]) -> None: - rejected = _CALLER_REJECTED_FIELDS.intersection(names) - if rejected: - raise ValueError( - f"Responses requests cannot set agent-controlled fields: {', '.join(sorted(rejected))}. " - "Configure trusted tool context in the agent's default options or a prepare_options hook." - ) +_CALLER_ALLOWED_FIELDS = frozenset({ + "agent_session_id", + "agent_reference", + "background", + "conversation", + "extra_body", + "include", + "input", + "max_output_tokens", + "metadata", + "model", + "parallel_tool_calls", + "previous_response_id", + "reasoning", + "store", + "stream", + "temperature", + "text", + "top_p", + "user", +}) +_CALLER_ALLOWED_EXTRA_BODY_FIELDS = frozenset({ + "allow_multiple_tool_calls", + "max_output_tokens", + "max_tokens", + "model", + "parallel_tool_calls", + "reasoning", + "temperature", + "text", + "top_p", +}) -def reject_caller_tool_context(request: CreateResponse) -> None: - """Reject caller-supplied agent-controlled tool context, at the top level or in ``extra_body``. +def reject_disallowed_caller_fields(request: CreateResponse, options: Mapping[str, Any]) -> None: + """Reject caller fields not allowed by the default policy or explicitly returned by the developer hook. - This applies to every hosted Responses request, whichever agent or workflow shape serves it, so callers can - never replace trusted values configured by the developer. + The hook can opt an individual caller field into the run options by returning it. Host-controlled + fields remain protected by ``validate_request_options``. Raises: - ValueError: If the request sets an agent-controlled field. + TypeError: If ``extra_body`` is not a mapping of string keys. + ValueError: If a caller field is not allowed. """ - _reject_caller_controls(cast(Mapping[str, Any], request)) + returned_fields = set(options) + rejected = set(request).difference(_CALLER_ALLOWED_FIELDS).difference(returned_fields) extra_body = request.get("extra_body") - if isinstance(extra_body, Mapping): - _reject_caller_controls(cast(Mapping[str, Any], extra_body)) + if extra_body is not None: + if not isinstance(extra_body, Mapping) or any( + not isinstance(key, str) for key in cast(Mapping[object, object], extra_body) + ): + raise TypeError("extra_body must be a mapping of model options.") + rejected.update( + f"extra_body.{name}" + for name in cast(Mapping[str, Any], extra_body) + if name not in _CALLER_ALLOWED_EXTRA_BODY_FIELDS and name not in returned_fields + ) + if rejected: + raise ValueError( + f"Responses requests cannot set fields that are not in the caller allowlist: {', '.join(sorted(rejected))}." + ) def response_run_options(request: CreateResponse) -> dict[str, Any]: - """Translate native generation fields, with flattened extra-body values winning collisions. - - Raises: - ValueError: If the caller supplies agent-controlled tool-execution context. - """ - reject_caller_tool_context(request) + """Translate allowed native generation fields, with flattened extra-body values winning collisions.""" native: dict[str, Any] = {} - extra: dict[str, Any] = {} nested_extra: dict[str, Any] = {} for name, value in request.items(): if value is None or (name == "model" and value == ""): @@ -165,16 +193,17 @@ 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.") - nested_extra.update(cast(Mapping[str, Any], value)) + nested_extra.update({ + _OPTION_NAMES.get(name, name): item + for name, item in cast(Mapping[str, Any], value).items() + if name in _CALLER_ALLOWED_EXTRA_BODY_FIELDS + }) elif name in _HOST_CONTROLLED_FIELDS: continue - elif name in _NATIVE_FIELDS: + elif name in _CALLER_ALLOWED_FIELDS and name in _NATIVE_FIELDS: native[_OPTION_NAMES.get(name, name)] = value - else: - extra[name] = value 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}, } diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses.py index bb240c3ad54..7a66a6f99a9 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses.py @@ -120,7 +120,7 @@ UnsupportedOptions, WorkflowTurn, prepare_response_options, - reject_caller_tool_context, + reject_disallowed_caller_fields, response_run_options, validate_default_transport_options, validate_request_options, @@ -1046,7 +1046,9 @@ def __init__( client into provider background polling and requires `history_source="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. - prepare_options: Developer hook to remove or replace caller model options for an agent. + prepare_options: Developer hook to remove or replace caller model options. Returning a caller field + not included in the default allowlist explicitly opts that field into this request; host-controlled + fields remain forbidden. unsupported_options: `"warn"` (default), `"error"`, or `"ignore"` when a custom agent cannot accept runtime model options. **kwargs: Additional keyword arguments. @@ -1302,14 +1304,14 @@ async def _handle_response( _initialize_agent_history(agent, configuration) if configuration.workflow: self._warn_legacy_workflow() - try: - reject_caller_tool_context(request) - except ValueError as exc: - raise _PublicResponseFailure(exc) from None hosted_request: HostedResponseRequest | None = None if configuration.workflow: if self._prepare_options is not None: raise _PublicResponseFailure(ValueError("prepare_options is only supported for regular agents.")) + try: + reject_disallowed_caller_fields(request, response_run_options(request)) + except (TypeError, ValueError) as exc: + raise _PublicResponseFailure(exc) from None else: try: hosted_request = HostedResponseRequest(request, context, scope, response_run_options(request)) @@ -1317,6 +1319,7 @@ async def _handle_response( raise _PublicResponseFailure(exc) from None await prepare_response_options(hosted_request, self._prepare_options) try: + reject_disallowed_caller_fields(request, hosted_request.options) validate_request_options(hosted_request.options) except (TypeError, ValueError) as exc: raise _PublicResponseFailure(exc) from None diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_workflow_responses.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_workflow_responses.py index 2df89e5ecb7..0e7a967a7a4 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_workflow_responses.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_workflow_responses.py @@ -47,6 +47,7 @@ OptionsHook, WorkflowTurn, prepare_response_options, + reject_disallowed_caller_fields, response_run_options, validate_request_options, ) @@ -429,6 +430,7 @@ async def abort() -> bool: ) hosted = HostedResponseRequest(request, context, scope, response_run_options(request)) await prepare_response_options(hosted, self.options_hook) + reject_disallowed_caller_fields(request, hosted.options) validate_request_options(hosted.options) workflow = await self.resolver.resolve(hosted) resources = AsyncExitStack() diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/conftest.py b/python/packages/foundry_hosting/tests/foundry_hosting/conftest.py deleted file mode 100644 index 744e9505e86..00000000000 --- a/python/packages/foundry_hosting/tests/foundry_hosting/conftest.py +++ /dev/null @@ -1,106 +0,0 @@ -# Copyright (c) Microsoft. All rights reserved. - -"""Fixtures for hosted tool-execution-context tests.""" - -from __future__ import annotations - -from collections.abc import AsyncIterator, Awaitable, Callable, Mapping, Sequence -from typing import Any, Literal, cast - -import pytest -from agent_framework import ( - Agent, - AgentExecutorRequest, - BaseChatClient, - ChatMiddlewareLayer, - ChatResponse, - ChatResponseUpdate, - Content, - FunctionInvocationContext, - FunctionInvocationLayer, - Message, - ResponseStream, - WorkflowAgent, - WorkflowBuilder, - WorkflowContext, - executor, - tool, -) - -TRUSTED_TENANT_ID = "trusted" - -TenantAgentFactory = Callable[..., Agent[Any]] -TenantWorkflowAgentFactory = Callable[[list[Any]], WorkflowAgent] - - -class _ToolCallingClient( - FunctionInvocationLayer[Any], - ChatMiddlewareLayer[Any], - BaseChatClient[Any], -): - """Call ``read_tenant_data`` once, then answer.""" - - def __init__(self) -> None: - super().__init__(middleware=[]) - 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 options, kwargs - assert stream is True, "The inner agent only runs in stream mode in Foundry Hosted Agents." - self.calls += 1 - needs_tool_call = not any( - content.type == "function_result" for message in messages for content in message.contents - ) - - async def stream_response() -> AsyncIterator[ChatResponseUpdate]: - if needs_tool_call: - yield ChatResponseUpdate( - contents=[Content.from_function_call(call_id="call_1", name="read_tenant_data", arguments="{}")], - role="assistant", - ) - else: - yield ChatResponseUpdate(contents=[Content.from_text("done")], role="assistant") - - return ResponseStream(stream_response(), finalizer=ChatResponse.from_updates) - - -@pytest.fixture -def tenant_agent_factory() -> TenantAgentFactory: - """Create agents whose tool records the tenant it receives from hidden runtime context.""" - - def factory(seen_tenants: list[Any], *, approval_mode: Literal["always_require", "never_require"]) -> Agent[Any]: - @tool(name="read_tenant_data", approval_mode=approval_mode) - def read_tenant_data(ctx: FunctionInvocationContext) -> str: - seen_tenants.append(ctx.kwargs.get("tenant_id")) - return "ok" - - return Agent( - client=_ToolCallingClient(), - tools=[read_tenant_data], - default_options=cast(Any, {"additional_function_arguments": {"tenant_id": TRUSTED_TENANT_ID}}), - ) - - return factory - - -@pytest.fixture -def tenant_workflow_agent_factory(tenant_agent_factory: TenantAgentFactory) -> TenantWorkflowAgentFactory: - """Wrap the tenant agent in a legacy ``WorkflowAgent`` so the workflow hosting path can be exercised.""" - - def factory(seen_tenants: list[Any]) -> WorkflowAgent: - @executor - async def start(messages: list[Message], ctx: WorkflowContext[AgentExecutorRequest]) -> None: - await ctx.send_message(AgentExecutorRequest(messages=messages, should_respond=True)) - - inner = tenant_agent_factory(seen_tenants, approval_mode="never_require") - workflow = WorkflowBuilder(start_executor=start).add_edge(start, inner).build() - return WorkflowAgent(workflow=workflow, name="Tenant Workflow Agent") - - return factory diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_caller_tool_context.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_caller_tool_context.py deleted file mode 100644 index bc4682d8500..00000000000 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_caller_tool_context.py +++ /dev/null @@ -1,178 +0,0 @@ -# Copyright (c) Microsoft. All rights reserved. - -"""Callers must not supply or replace trusted tool-execution context on Responses requests.""" - -from __future__ import annotations - -from collections.abc import Callable -from typing import Any, Literal, cast -from unittest.mock import AsyncMock, MagicMock - -import httpx -import pytest -from azure.ai.agentserver.responses import InMemoryResponseProvider, ResponseContext -from azure.ai.agentserver.responses.models import CreateResponse - -from agent_framework_foundry_hosting import HostedResponseRequest, ResponsesHostServer -from agent_framework_foundry_hosting._request import ( - prepare_response_options, - response_run_options, - validate_request_options, -) -from agent_framework_foundry_hosting._scope import FoundryRequestScope - -TRUSTED_TENANT_ID = "trusted" -FORGED_TENANT_CONTEXT: dict[str, Any] = {"additional_function_arguments": {"tenant_id": "forged"}} - - -@pytest.mark.parametrize( - "payload", - [ - {"additional_function_arguments": {"tenant_id": "forged"}}, - {"extra_body": {"additional_function_arguments": {"tenant_id": "forged"}}}, - {"additional_function_arguments": None}, - {"extra_body": {"additional_function_arguments": None}}, - ], -) -def test_caller_cannot_supply_tool_execution_context(payload: dict[str, Any]) -> None: - with pytest.raises(ValueError, match="agent-controlled fields: additional_function_arguments"): - response_run_options(cast(CreateResponse, {"input": "hello", "temperature": 0.2, **payload})) - - -def test_requests_without_tool_context_keep_other_options() -> None: - request = cast(CreateResponse, {"input": "hello", "extra_body": {"slogan_style": "retro"}, "temperature": 0.2}) - assert response_run_options(request) == {"temperature": 0.2, "slogan_style": "retro"} - - -async def test_hook_can_supply_trusted_tool_context() -> None: - context = MagicMock(spec=ResponseContext) - context.response_id = "outer-id" - context.conversation_id = None - context.get_input_text = AsyncMock(return_value="hello") - scope = FoundryRequestScope(session_id="sandbox", user_id="user", call_id="call", is_hosted=True) - request = HostedResponseRequest(cast(CreateResponse, {"input": "hello"}), context, scope, {}) - - def inject(view: HostedResponseRequest, options: dict[str, Any]) -> dict[str, Any]: - return {**options, "additional_function_arguments": {"tenant_id": view.scope.user_id}} - - await prepare_response_options(request, inject) - validate_request_options(request.options) - assert request.options["additional_function_arguments"] == {"tenant_id": "user"} - - -async def _post_json(server: ResponsesHostServer, payload: dict[str, Any]) -> httpx.Response: - transport = httpx.ASGITransport(app=server) - async with httpx.AsyncClient(transport=transport, base_url="http://test") as client: - return await client.post("/responses", json=payload) - - -def _make_server(agent: Any, **kwargs: Any) -> ResponsesHostServer: - return ResponsesHostServer(agent, response_store=InMemoryResponseProvider(), **kwargs) - - -@pytest.mark.xdist_group("session_isolation") -class TestCallerCannotOverrideToolContext: - async def test_baseline_uses_trusted_tool_context(self, tenant_agent_factory: Callable[..., Any]) -> None: - seen: list[Any] = [] - server = _make_server(tenant_agent_factory(seen, approval_mode="never_require")) - - response = await _post_json(server, {"input": "go", "stream": False}) - - assert response.json()["status"] == "completed" - assert seen == [TRUSTED_TENANT_ID] - - @pytest.mark.parametrize("stream", [False, True]) - @pytest.mark.parametrize("location", ["top_level", "extra_body"]) - async def test_forged_tool_context_is_rejected_before_any_tool_runs( - self, tenant_agent_factory: Callable[..., Any], location: Literal["top_level", "extra_body"], stream: bool - ) -> None: - seen: list[Any] = [] - agent = tenant_agent_factory(seen, approval_mode="never_require") - server = _make_server(agent) - payload: dict[str, Any] = {"input": "go", "stream": stream} - if location == "top_level": - payload.update(FORGED_TENANT_CONTEXT) - else: - payload["extra_body"] = FORGED_TENANT_CONTEXT - - response = await _post_json(server, payload) - - assert "additional_function_arguments" in response.text - assert "failed" in response.text - assert seen == [] - assert agent.client.calls == 0 - - @pytest.mark.filterwarnings("ignore:Hosting WorkflowAgent through agent=.*:DeprecationWarning") - @pytest.mark.parametrize("location", ["top_level", "extra_body"]) - async def test_forged_tool_context_is_rejected_for_legacy_workflow_agents( - self, tenant_workflow_agent_factory: Callable[..., Any], location: Literal["top_level", "extra_body"] - ) -> None: - seen: list[Any] = [] - server = _make_server(tenant_workflow_agent_factory(seen)) - payload: dict[str, Any] = {"input": "go", "stream": False} - if location == "top_level": - payload.update(FORGED_TENANT_CONTEXT) - else: - payload["extra_body"] = FORGED_TENANT_CONTEXT - - response = await _post_json(server, payload) - - assert "additional_function_arguments" in response.text - assert response.json()["status"] == "failed" - assert seen == [] - - @pytest.mark.filterwarnings("ignore:Hosting WorkflowAgent through agent=.*:DeprecationWarning") - async def test_legacy_workflow_agent_without_forged_context_still_runs( - self, tenant_workflow_agent_factory: Callable[..., Any] - ) -> None: - seen: list[Any] = [] - server = _make_server(tenant_workflow_agent_factory(seen)) - - response = await _post_json(server, {"input": "go", "stream": False}) - - assert response.json()["status"] == "completed" - assert seen == [TRUSTED_TENANT_ID] - - async def test_hook_can_still_supply_trusted_tool_context(self, tenant_agent_factory: Callable[..., Any]) -> None: - seen: list[Any] = [] - server = _make_server( - tenant_agent_factory(seen, approval_mode="never_require"), - prepare_options=lambda request, options: { - **options, - "additional_function_arguments": {"tenant_id": f"from-hook:{request.scope.user_id}"}, - }, - ) - - response = await _post_json(server, {"input": "go", "stream": False}) - - assert response.json()["status"] == "completed" - assert len(seen) == 1 - assert str(seen[0]).startswith("from-hook:") - - async def test_forged_context_on_approval_resume_is_rejected_without_consuming_approval( - self, tenant_agent_factory: Callable[..., Any] - ) -> None: - seen: list[Any] = [] - server = _make_server(tenant_agent_factory(seen, approval_mode="always_require")) - - first = await _post_json(server, {"input": "go", "stream": False, "store": True}) - first_body = first.json() - approval_id = next(item["id"] for item in first_body["output"] if item["type"] == "mcp_approval_request") - assert seen == [] - - def resume(**extra: Any) -> dict[str, Any]: - return { - "input": [{"type": "mcp_approval_response", "approval_request_id": approval_id, "approve": True}], - "previous_response_id": first_body["id"], - "stream": False, - "store": True, - **extra, - } - - forged = await _post_json(server, resume(**FORGED_TENANT_CONTEXT)) - assert "additional_function_arguments" in forged.text - assert seen == [] - - legitimate = await _post_json(server, resume()) - assert legitimate.json()["status"] == "completed" - assert seen == [TRUSTED_TENANT_ID] 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 bd90420d6a0..cf4f99f8cc8 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 @@ -621,13 +621,18 @@ def create(request: HostedResponseRequest) -> Workflow: async def parse(request: HostedResponseRequest) -> WorkflowTurn[Any]: return WorkflowTurn(input=[Message("user", await request.get_input_text() or "")]) - server = _server(create, parser=parse) - first = await _post(server, "one", temperature=0.7, max_output_tokens=12, store=True) + def prepare_options(request: HostedResponseRequest, options: dict[str, Any]) -> dict[str, Any]: + options["vendor_option"] = request.request["vendor_option"] + return options + + server = _server(create, parser=parse, prepare_options=prepare_options) + first = await _post(server, "one", temperature=0.7, max_output_tokens=12, store=True, vendor_option="first") assert first["status"] == "completed", first - second = await _post(server, "two", temperature=0.4, store=False, call="call-two") + second = await _post(server, "two", temperature=0.4, store=False, call="call-two", vendor_option="second") 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 [call["options"]["vendor_option"] for call in calls] == ["first", "second"] assert calls[0]["options"]["max_tokens"] == 12 assert all( agent.default_options["temperature"] == 0.2 and agent.default_options["store"] is True for agent in agents diff --git a/python/packages/foundry_hosting/tests/test_request.py b/python/packages/foundry_hosting/tests/test_request.py index 6496e7e8b6f..253add42c18 100644 --- a/python/packages/foundry_hosting/tests/test_request.py +++ b/python/packages/foundry_hosting/tests/test_request.py @@ -14,6 +14,7 @@ from agent_framework_foundry_hosting import HostedResponseRequest, InvocationRun, response_input_messages from agent_framework_foundry_hosting._request import ( prepare_response_options, + reject_disallowed_caller_fields, response_run_options, validate_default_transport_options, validate_request_options, @@ -31,19 +32,11 @@ def test_native_options_are_translated_before_flattened_extra_body() -> None: "store": True, "background": False, "conversation": "outer-conversation", - "agent_session_id": "forged-sandbox", - "session_id": "caller-session", "user": "forged-user", - "user_id": "forged-user", - "call_id": "forged-call", - "conversation_id": "inner-conversation", - "service_session_id": "private-session", - "continuation_token": {"response_id": "private"}, "max_output_tokens": 300, - "max_tokens": 150, "parallel_tool_calls": False, "reasoning": {"effort": "high"}, - "slogan_style": "retro", + "extra_body": {"max_tokens": 150, "temperature": 0.4}, }, ) @@ -52,10 +45,31 @@ def test_native_options_are_translated_before_flattened_extra_body() -> None: "max_tokens": 150, "allow_multiple_tool_calls": False, "reasoning": {"effort": "high"}, - "slogan_style": "retro", + "temperature": 0.4, } +@pytest.mark.parametrize( + ("payload", "field_name"), + [ + ({"instructions": None}, "instructions"), + ({"extra_body": {"vendor_option": None}}, "extra_body.vendor_option"), + ({"additional_function_arguments": {"tenant_id": "forged"}}, "additional_function_arguments"), + ( + {"extra_body": {"additional_function_arguments": {"tenant_id": "forged"}}}, + "extra_body.additional_function_arguments", + ), + ], +) +def test_unlisted_request_fields_are_rejected(payload: dict[str, Any], field_name: str) -> None: + request = cast(CreateResponse, {"input": "hello", **payload}) + options = response_run_options(request) + + with pytest.raises(ValueError) as exc_info: + reject_disallowed_caller_fields(request, options) + assert field_name in str(exc_info.value) + + def test_nested_extra_body_is_also_overlaid_last_without_reserved_fields() -> None: request = cast( CreateResponse, @@ -63,12 +77,15 @@ def test_nested_extra_body_is_also_overlaid_last_without_reserved_fields() -> No "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="extra_body.session_id"): + reject_disallowed_caller_fields( + cast(CreateResponse, {"extra_body": {"session_id": "forged"}}), + {}, + ) 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"): @@ -139,6 +156,31 @@ async def test_hook_rejects_reserved_fields_and_non_mapping_result() -> None: await prepare_response_options(request, lambda _view, _options: cast(Any, None)) +async def test_options_hook_can_opt_a_request_field_into_the_allowlist() -> None: + payload = cast( + CreateResponse, + {"input": "hello", "vendor_option": "caller-value", "extra_body": {"provider_option": "nested-value"}}, + ) + context = MagicMock(spec=ResponseContext) + context.response_id = "outer-id" + context.conversation_id = None + scope = FoundryRequestScope(session_id="sandbox", user_id="user", call_id="call", is_hosted=False) + request = HostedResponseRequest(payload, context, scope, response_run_options(payload)) + + def allow_request_fields(view: HostedResponseRequest, options: dict[str, Any]) -> dict[str, Any]: + return { + **options, + "vendor_option": view.request["vendor_option"], + "provider_option": view.request["extra_body"]["provider_option"], + } + + await prepare_response_options(request, allow_request_fields) + reject_disallowed_caller_fields(payload, request.options) + + assert request.options["vendor_option"] == "caller-value" + assert request.options["provider_option"] == "nested-value" + + def test_default_transport_cannot_override_host_storage_or_identity() -> None: with pytest.raises(ValueError, match="store"): validate_default_transport_options({"extra_body": {"store": True}}, allow_agent_store=False) diff --git a/python/packages/foundry_hosting/tests/test_responses.py b/python/packages/foundry_hosting/tests/test_responses.py index 6022b6c9467..6bdba5e5eda 100644 --- a/python/packages/foundry_hosting/tests/test_responses.py +++ b/python/packages/foundry_hosting/tests/test_responses.py @@ -2241,8 +2241,9 @@ async def test_extra_options_overlay_then_developer_hook_preserves_defaults(self agent = Agent(client=client, default_options=OpenAIChatOptions(temperature=0.2, max_tokens=256)) defaults = dict(agent.default_options) - def prepare_options(_request: Any, options: dict[str, Any]) -> dict[str, Any]: + def prepare_options(request: Any, options: dict[str, Any]) -> dict[str, Any]: options.pop("temperature") + options["vendor_option"] = request.request["vendor_option"] return options server = _make_server(agent, prepare_options=prepare_options) @@ -2253,19 +2254,46 @@ def prepare_options(_request: Any, options: dict[str, Any]) -> dict[str, Any]: "model": "test-model", "temperature": 0.8, "max_output_tokens": 300, - "max_tokens": 150, - "session_id": "forged-sandbox", - "call_id": "forged-call", + "extra_body": {"max_tokens": 150}, + "vendor_option": "caller-value", }, ) assert response.json()["status"] == "completed" assert client.options[0]["temperature"] == 0.2 assert client.options[0]["max_tokens"] == 150 - assert "session_id" not in client.options[0] - assert "call_id" not in client.options[0] + assert client.options[0]["vendor_option"] == "caller-value" assert agent.default_options == defaults + @pytest.mark.parametrize( + ("location", "field_name"), + [ + ("top_level", "additional_function_arguments"), + ("extra_body", "extra_body.additional_function_arguments"), + ], + ) + @pytest.mark.parametrize("stream", [False, True]) + async def test_unlisted_caller_option_fails_before_agent_run( + self, location: Literal["top_level", "extra_body"], field_name: str, stream: bool + ) -> None: + agent = _make_agent() + server = _make_server(agent) + payload: dict[str, Any] = {"input": "one shot", "stream": stream} + if location == "top_level": + payload["additional_function_arguments"] = {"tenant_id": "forged"} + else: + payload["extra_body"] = {"additional_function_arguments": {"tenant_id": "forged"}} + + response = await _post_json(server, payload) + + if stream: + assert "response.failed" in response.text + assert field_name in response.text + else: + assert response.json()["status"] == "failed" + assert field_name in response.json()["error"]["message"] + agent.run.assert_not_called() + async def test_hook_cannot_reintroduce_host_owned_storage_or_identity(self) -> None: agent = _make_agent() server = _make_server( @@ -9971,6 +9999,24 @@ class TestWorkflowAgentHosting: relative to the regular agent path. """ + @pytest.mark.parametrize("location", ["top_level", "extra_body"]) + async def test_unlisted_caller_option_fails_before_workflow_run( + self, location: Literal["top_level", "extra_body"] + ) -> None: + workflow_agent, inner = _build_multi_update_workflow_agent(["done"]) + server = _make_server(workflow_agent) + payload: dict[str, Any] = {"input": "one shot", "stream": False} + if location == "top_level": + payload["additional_function_arguments"] = {"tenant_id": "forged"} + else: + payload["extra_body"] = {"additional_function_arguments": {"tenant_id": "forged"}} + + response = await _post_json(server, payload) + + assert response.json()["status"] == "failed" + assert "additional_function_arguments" in response.json()["error"]["message"] + assert inner.run_count == 0 + async def test_async_factory_creates_workflow_agent_for_each_request(self) -> None: created: list[tuple[WorkflowAgent, _MultiUpdateWorkflowAgentMock]] = [] @@ -10352,6 +10398,15 @@ async def test_round_trip_approval_response_resumes_workflow_agent(self) -> None "stream": False, "previous_response_id": first_response_id, } + rejected_payload = { + **second_payload, + "additional_function_arguments": {"tenant_id": "forged"}, + } + rejected = await _post_json(server, rejected_payload) + assert rejected.json()["status"] == "failed" + assert "additional_function_arguments" in rejected.json()["error"]["message"] + assert mock_agent.run_count == 1 + second = await _post_json(server, second_payload) assert second.status_code == 200 second_body = second.json() From d98fa4dba68e314c623f5adca0427ead5c6924e5 Mon Sep 17 00:00:00 2001 From: Darren Cohen <39422044+dargilco@users.noreply.github.com> Date: Thu, 12 Nov 2026 13:34:06 -0800 Subject: [PATCH 11/13] update --- python/packages/foundry_hosting/README.md | 29 ++++++++++++------- .../_request.py | 20 +++++++++---- .../foundry_hosting/tests/test_request.py | 12 +++++++- .../foundry_hosting/tests/test_responses.py | 7 +++-- 4 files changed, 48 insertions(+), 20 deletions(-) diff --git a/python/packages/foundry_hosting/README.md b/python/packages/foundry_hosting/README.md index 3cb694c97df..ed01e46f6eb 100644 --- a/python/packages/foundry_hosting/README.md +++ b/python/packages/foundry_hosting/README.md @@ -256,17 +256,24 @@ official `azure-ai-agentserver-core` wheel, the minimum dependency and `uv.lock` concurrent queue-overflow regression proves rejected turns leave no pending futures. No future SDK version is assumed. Non-steerable background polling and legacy `WorkflowAgent` dispatch are 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: HostedResponseRequest, 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. Callers cannot supply `additional_function_arguments` (the hidden tool-execution -context that reaches `FunctionInvocationContext.kwargs`), at the top level or in `extra_body`, on any request including -an approval resume: the request fails before any tool runs and pending approvals remain usable. Set trusted values in -the agent's `default_options` or return them from a `prepare_options` hook (for example, derived from -`request.scope`). 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 +Allowed native CreateResponse generation fields become MAF runtime options (notably `max_output_tokens` -> +`max_tokens` and `parallel_tool_calls` -> `allow_multiple_tool_calls`). Caller-supplied top-level fields and +`extra_body` keys are checked against separate, hard-coded +[default allowlists](./agent_framework_foundry_hosting/_request.py). Unlisted fields are rejected even when their +value is `null`, unless an author explicitly opts them in through `prepare_options`. These allowlists check field +names, not arbitrary values or nested contents of allowed fields. Allowed, flattened `extra_body` options overlay +translated keys **last**, before the hook. + +A sync or async `prepare_options(request: HostedResponseRequest, options: dict)` hook can inspect a copy of the original +request, remove or replace caller options, or opt an unlisted caller field in by returning it as a run option. Validate +any caller-derived value before returning it; use trusted application or platform data for trusted context. Removed +options fall back to the developer's unchanged agent defaults. The hook is supported for regular agents and native +workflows, but not for legacy `WorkflowAgent` hosting. Requests rejected by this field policy do not run the agent or +workflow; a rejected approval resume leaves the pending approval usable. + +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 diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_request.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_request.py index c22771ac6e2..2391c204039 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_request.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_request.py @@ -183,6 +183,13 @@ def response_run_options(request: CreateResponse) -> dict[str, Any]: """Translate allowed native generation fields, with flattened extra-body values winning collisions.""" native: dict[str, Any] = {} nested_extra: dict[str, Any] = {} + unlisted_option_names = set(request).difference(_CALLER_ALLOWED_FIELDS) + extra_body = request.get("extra_body") + if isinstance(extra_body, Mapping): + for field_name in cast(Mapping[object, object], extra_body): + if isinstance(field_name, str) and field_name not in _CALLER_ALLOWED_EXTRA_BODY_FIELDS: + unlisted_option_names.add(field_name) + for name, value in request.items(): if value is None or (name == "model" and value == ""): continue @@ -193,15 +200,16 @@ 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.") - nested_extra.update({ - _OPTION_NAMES.get(name, name): item - for name, item in cast(Mapping[str, Any], value).items() - if name in _CALLER_ALLOWED_EXTRA_BODY_FIELDS - }) + for name, item in cast(Mapping[str, Any], value).items(): + option_name = _OPTION_NAMES.get(name, name) + if name in _CALLER_ALLOWED_EXTRA_BODY_FIELDS and option_name not in unlisted_option_names: + nested_extra[option_name] = item elif name in _HOST_CONTROLLED_FIELDS: continue elif name in _CALLER_ALLOWED_FIELDS and name in _NATIVE_FIELDS: - native[_OPTION_NAMES.get(name, name)] = value + option_name = _OPTION_NAMES.get(name, name) + if option_name not in unlisted_option_names: + native[option_name] = value return { **native, **{name: value for name, value in nested_extra.items() if name not in _HOST_CONTROLLED_FIELDS}, diff --git a/python/packages/foundry_hosting/tests/test_request.py b/python/packages/foundry_hosting/tests/test_request.py index 253add42c18..172033a4fe3 100644 --- a/python/packages/foundry_hosting/tests/test_request.py +++ b/python/packages/foundry_hosting/tests/test_request.py @@ -55,6 +55,8 @@ def test_native_options_are_translated_before_flattened_extra_body() -> None: ({"instructions": None}, "instructions"), ({"extra_body": {"vendor_option": None}}, "extra_body.vendor_option"), ({"additional_function_arguments": {"tenant_id": "forged"}}, "additional_function_arguments"), + ({"max_output_tokens": 30, "max_tokens": 999}, "max_tokens"), + ({"parallel_tool_calls": False, "allow_multiple_tool_calls": True}, "allow_multiple_tool_calls"), ( {"extra_body": {"additional_function_arguments": {"tenant_id": "forged"}}}, "extra_body.additional_function_arguments", @@ -159,7 +161,13 @@ async def test_hook_rejects_reserved_fields_and_non_mapping_result() -> None: async def test_options_hook_can_opt_a_request_field_into_the_allowlist() -> None: payload = cast( CreateResponse, - {"input": "hello", "vendor_option": "caller-value", "extra_body": {"provider_option": "nested-value"}}, + { + "input": "hello", + "vendor_option": "caller-value", + "max_output_tokens": 30, + "max_tokens": 999, + "extra_body": {"provider_option": "nested-value"}, + }, ) context = MagicMock(spec=ResponseContext) context.response_id = "outer-id" @@ -171,6 +179,7 @@ def allow_request_fields(view: HostedResponseRequest, options: dict[str, Any]) - return { **options, "vendor_option": view.request["vendor_option"], + "max_tokens": view.request["max_tokens"], "provider_option": view.request["extra_body"]["provider_option"], } @@ -178,6 +187,7 @@ def allow_request_fields(view: HostedResponseRequest, options: dict[str, Any]) - reject_disallowed_caller_fields(payload, request.options) assert request.options["vendor_option"] == "caller-value" + assert request.options["max_tokens"] == 999 assert request.options["provider_option"] == "nested-value" diff --git a/python/packages/foundry_hosting/tests/test_responses.py b/python/packages/foundry_hosting/tests/test_responses.py index 6bdba5e5eda..e86b3cd6b3c 100644 --- a/python/packages/foundry_hosting/tests/test_responses.py +++ b/python/packages/foundry_hosting/tests/test_responses.py @@ -2270,19 +2270,22 @@ def prepare_options(request: Any, options: dict[str, Any]) -> dict[str, Any]: [ ("top_level", "additional_function_arguments"), ("extra_body", "extra_body.additional_function_arguments"), + ("alias_collision", "max_tokens"), ], ) @pytest.mark.parametrize("stream", [False, True]) async def test_unlisted_caller_option_fails_before_agent_run( - self, location: Literal["top_level", "extra_body"], field_name: str, stream: bool + self, location: Literal["top_level", "extra_body", "alias_collision"], field_name: str, stream: bool ) -> None: agent = _make_agent() server = _make_server(agent) payload: dict[str, Any] = {"input": "one shot", "stream": stream} if location == "top_level": payload["additional_function_arguments"] = {"tenant_id": "forged"} - else: + elif location == "extra_body": payload["extra_body"] = {"additional_function_arguments": {"tenant_id": "forged"}} + else: + payload.update({"max_output_tokens": 30, "max_tokens": 999}) response = await _post_json(server, payload) From 60ba4553512ea3533263afa0b5ef630d4906204e Mon Sep 17 00:00:00 2001 From: Darren Cohen <39422044+dargilco@users.noreply.github.com> Date: Thu, 12 Nov 2026 13:59:07 -0800 Subject: [PATCH 12/13] update --- python/packages/foundry_hosting/README.md | 11 +-- .../__init__.py | 13 +++- .../_request.py | 74 +++++++++++-------- 3 files changed, 61 insertions(+), 37 deletions(-) diff --git a/python/packages/foundry_hosting/README.md b/python/packages/foundry_hosting/README.md index ed01e46f6eb..6e8cea3c65a 100644 --- a/python/packages/foundry_hosting/README.md +++ b/python/packages/foundry_hosting/README.md @@ -258,11 +258,12 @@ version is assumed. Non-steerable background polling and legacy `WorkflowAgent` Allowed native CreateResponse generation fields become MAF runtime options (notably `max_output_tokens` -> `max_tokens` and `parallel_tool_calls` -> `allow_multiple_tool_calls`). Caller-supplied top-level fields and -`extra_body` keys are checked against separate, hard-coded -[default allowlists](./agent_framework_foundry_hosting/_request.py). Unlisted fields are rejected even when their -value is `null`, unless an author explicitly opts them in through `prepare_options`. These allowlists check field -names, not arbitrary values or nested contents of allowed fields. Allowed, flattened `extra_body` options overlay -translated keys **last**, before the hook. +`extra_body` keys are checked against separate, hard-coded default allowlists, exposed as the read-only +`DEFAULT_CALLER_ALLOWED_FIELDS` and `DEFAULT_CALLER_ALLOWED_EXTRA_BODY_FIELDS` constants. Unlisted fields are rejected +even when their value is `null`, unless an author explicitly opts them in through `prepare_options`, so the constants +describe the default policy rather than every field an application accepts. Future releases may add fields; removing +one is a breaking change. These allowlists check field names, not arbitrary values or nested contents of allowed +fields. Allowed, flattened `extra_body` options overlay translated keys **last**, before the hook. A sync or async `prepare_options(request: HostedResponseRequest, options: dict)` hook can inspect a copy of the original request, remove or replace caller options, or opt an unlisted caller field in by returning it as a run option. Validate 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 cd37bfcf691..deb8efc99c5 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/__init__.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/__init__.py @@ -5,7 +5,14 @@ if TYPE_CHECKING: from ._invocations import InvocationsHostServer - from ._request import HostedResponseRequest, InvocationRun, WorkflowTurn, response_input_messages + from ._request import ( + DEFAULT_CALLER_ALLOWED_EXTRA_BODY_FIELDS, + DEFAULT_CALLER_ALLOWED_FIELDS, + HostedResponseRequest, + InvocationRun, + WorkflowTurn, + response_input_messages, + ) from ._responses import ResponsesHostServer from ._scope import FoundryRequestScope from ._state_store import ( @@ -31,6 +38,8 @@ "AgentSessionStoreProvider": "._state_store", "CheckpointStoreProvider": "._state_store", "ContextScopedStoreProvider": "._state_store", + "DEFAULT_CALLER_ALLOWED_EXTRA_BODY_FIELDS": "._request", + "DEFAULT_CALLER_ALLOWED_FIELDS": "._request", "FoundryAgentSessionStore": "._state_store", "FoundryCheckpointStore": "._state_store", "FoundryFunctionApprovalStore": "._state_store", @@ -49,6 +58,8 @@ } __all__ = [ + "DEFAULT_CALLER_ALLOWED_EXTRA_BODY_FIELDS", + "DEFAULT_CALLER_ALLOWED_FIELDS", "AgentSessionStoreProvider", "CheckpointStoreProvider", "ContextScopedStoreProvider", diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_request.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_request.py index 2391c204039..b4278dbdb15 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_request.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_request.py @@ -9,7 +9,7 @@ from copy import deepcopy from dataclasses import dataclass, field from types import MappingProxyType -from typing import Any, Generic, Literal, TypeAlias, cast +from typing import Any, Final, Generic, Literal, TypeAlias, cast from agent_framework import AgentRunInputs, Content, Message, WorkflowInvocationKwargs from azure.ai.agentserver.responses import ResponseContext @@ -94,29 +94,7 @@ def __post_init__(self) -> None: raise TypeError("InvocationRun.stream must be a boolean.") -_HOST_CONTROLLED_FIELDS = frozenset({ - "agent", - "agent_reference", - "agent_session_id", - "background", - "call_id", - "continuation_token", - "conversation", - "conversation_id", - "extra_body", - "input", - "previous_response_id", - "response_id", - "service_session_id", - "session_id", - "store", - "stream", - "user", - "user_id", -}) -_OPTION_NAMES = {"max_output_tokens": "max_tokens", "parallel_tool_calls": "allow_multiple_tool_calls"} -_NATIVE_FIELDS = frozenset(CreateResponse.__annotations__) -_CALLER_ALLOWED_FIELDS = frozenset({ +DEFAULT_CALLER_ALLOWED_FIELDS: Final[frozenset[str]] = frozenset({ "agent_session_id", "agent_reference", "background", @@ -137,7 +115,13 @@ def __post_init__(self) -> None: "top_p", "user", }) -_CALLER_ALLOWED_EXTRA_BODY_FIELDS = frozenset({ +"""Top-level Responses request fields callers may set by default. + +``prepare_options`` can opt in additional fields per request, so this set describes the default policy rather than +every field an application accepts. Future releases may add fields; removing one is a breaking change. +""" + +DEFAULT_CALLER_ALLOWED_EXTRA_BODY_FIELDS: Final[frozenset[str]] = frozenset({ "allow_multiple_tool_calls", "max_output_tokens", "max_tokens", @@ -148,6 +132,34 @@ def __post_init__(self) -> None: "text", "top_p", }) +"""Keys callers may set inside a Responses request's ``extra_body`` by default. + +``prepare_options`` can opt in additional keys per request, so this set describes the default policy rather than +every key an application accepts. Future releases may add keys; removing one is a breaking change. +""" + +_HOST_CONTROLLED_FIELDS = frozenset({ + "agent", + "agent_reference", + "agent_session_id", + "background", + "call_id", + "continuation_token", + "conversation", + "conversation_id", + "extra_body", + "input", + "previous_response_id", + "response_id", + "service_session_id", + "session_id", + "store", + "stream", + "user", + "user_id", +}) +_OPTION_NAMES = {"max_output_tokens": "max_tokens", "parallel_tool_calls": "allow_multiple_tool_calls"} +_NATIVE_FIELDS = frozenset(CreateResponse.__annotations__) def reject_disallowed_caller_fields(request: CreateResponse, options: Mapping[str, Any]) -> None: @@ -161,7 +173,7 @@ def reject_disallowed_caller_fields(request: CreateResponse, options: Mapping[st ValueError: If a caller field is not allowed. """ returned_fields = set(options) - rejected = set(request).difference(_CALLER_ALLOWED_FIELDS).difference(returned_fields) + rejected = set(request).difference(DEFAULT_CALLER_ALLOWED_FIELDS).difference(returned_fields) extra_body = request.get("extra_body") if extra_body is not None: if not isinstance(extra_body, Mapping) or any( @@ -171,7 +183,7 @@ def reject_disallowed_caller_fields(request: CreateResponse, options: Mapping[st rejected.update( f"extra_body.{name}" for name in cast(Mapping[str, Any], extra_body) - if name not in _CALLER_ALLOWED_EXTRA_BODY_FIELDS and name not in returned_fields + if name not in DEFAULT_CALLER_ALLOWED_EXTRA_BODY_FIELDS and name not in returned_fields ) if rejected: raise ValueError( @@ -183,11 +195,11 @@ def response_run_options(request: CreateResponse) -> dict[str, Any]: """Translate allowed native generation fields, with flattened extra-body values winning collisions.""" native: dict[str, Any] = {} nested_extra: dict[str, Any] = {} - unlisted_option_names = set(request).difference(_CALLER_ALLOWED_FIELDS) + unlisted_option_names = set(request).difference(DEFAULT_CALLER_ALLOWED_FIELDS) extra_body = request.get("extra_body") if isinstance(extra_body, Mapping): for field_name in cast(Mapping[object, object], extra_body): - if isinstance(field_name, str) and field_name not in _CALLER_ALLOWED_EXTRA_BODY_FIELDS: + if isinstance(field_name, str) and field_name not in DEFAULT_CALLER_ALLOWED_EXTRA_BODY_FIELDS: unlisted_option_names.add(field_name) for name, value in request.items(): @@ -202,11 +214,11 @@ def response_run_options(request: CreateResponse) -> dict[str, Any]: raise ValueError("Nested extra_body is not supported; flatten provider options instead.") for name, item in cast(Mapping[str, Any], value).items(): option_name = _OPTION_NAMES.get(name, name) - if name in _CALLER_ALLOWED_EXTRA_BODY_FIELDS and option_name not in unlisted_option_names: + if name in DEFAULT_CALLER_ALLOWED_EXTRA_BODY_FIELDS and option_name not in unlisted_option_names: nested_extra[option_name] = item elif name in _HOST_CONTROLLED_FIELDS: continue - elif name in _CALLER_ALLOWED_FIELDS and name in _NATIVE_FIELDS: + elif name in DEFAULT_CALLER_ALLOWED_FIELDS and name in _NATIVE_FIELDS: option_name = _OPTION_NAMES.get(name, name) if option_name not in unlisted_option_names: native[option_name] = value From 232d511ba7d5243dfdeea23563b416977ebe73c9 Mon Sep 17 00:00:00 2001 From: Darren Cohen <39422044+dargilco@users.noreply.github.com> Date: Thu, 12 Nov 2026 14:48:18 -0800 Subject: [PATCH 13/13] update doc string --- .../agent_framework_foundry_hosting/_request.py | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_request.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_request.py index b4278dbdb15..73fc1dc7769 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_request.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_request.py @@ -158,7 +158,18 @@ def __post_init__(self) -> None: "user", "user_id", }) +"""Fields protected at caller-option and agent-default transport boundaries. + +Some are allowed in outer requests but are not forwarded as caller options; hooks cannot return them. +The agent-default ``extra_body`` check also uses this set; it may permit ``store`` for agent-managed storage. +""" + _OPTION_NAMES = {"max_output_tokens": "max_tokens", "parallel_tool_calls": "allow_multiple_tool_calls"} +"""Map Responses request names to Agent Framework run-option names. + +Applied to allowed top-level and ``extra_body`` fields before the latter take precedence. +""" + _NATIVE_FIELDS = frozenset(CreateResponse.__annotations__)