diff --git a/python/packages/core/AGENTS.md b/python/packages/core/AGENTS.md index b66484a40ec..9712920c760 100644 --- a/python/packages/core/AGENTS.md +++ b/python/packages/core/AGENTS.md @@ -272,7 +272,13 @@ The vector store API is experimental under the shared `VECTOR_STORES` feature ID emits a `FutureWarning` because that fallback may change in a future release. A name list given as a bare string is one name, not a substring pattern. `default` is local-only: hosted MCP helpers (`get_mcp_tool`) do not read it. Tools and prompts discovered later (for example after `tools/list_changed`) use the policy at discovery time; retained - functions keep their resolved mode. + functions keep their resolved mode under static policies. Alternatively, pass a synchronous callable receiving + the discovered `mcp.types.Tool` or `mcp.types.Prompt` and returning `"always_require"` or `"never_require"` + for every item, including its default decision. Callback results of `None` are invalid; constructor-level + `None` keeps its default behavior. Callable policies run on each discovery refresh for new and retained functions; + results are validated and staged across all pages before publication. Exceptions preserve the previous + snapshot. `FoundryToolbox` supplies its metadata parser as this callable when no explicit caller policy is + configured; ordinary MCP servers do not interpret Foundry metadata. - **Progressive MCP disclosure** (`use_progressive_disclosure`, `always_load`) - When enabled on any `MCPTool` subclass, the initial model-facing surface is loader tools (`list_mcp_tools` / `load_tool` / `unload_tool`, prefixed by `tool_name_prefix` when configured) plus allowed tools selected by `always_load` and tools loaded earlier on the same `MCPTool` instance. `list_mcp_tools` only reports tools that pass `allowed_tools`; filtered tools are not listed or loadable. Loader tool names are reserved in progressive mode: remote MCP tools whose local generated name collides with a loader name are omitted from the initial/listed surface, and explicit `load_tool` calls return a model-visible message pointing callers to `tool_name_prefix` or excluding the colliding tool. `load_tool` accepts one tool name or a list of tool names and uses `FunctionInvocationContext.add_tools(...)` so the selected generated MCP `FunctionTool`s become available on the next function-calling iteration while keeping existing approval mode, argument filtering, header-provider runtime kwargs, result parsing, and OTel. `unload_tool` accepts one dynamically loaded tool name or a list of names and removes them from the live tool list and persisted progressive surface, but it does not remove tools configured in `always_load`. Invalid `always_load` entries are ignored like unmatched `allowed_tools` entries. - **Tool discovery refresh** - Validate the complete current tool snapshot alongside retained non-tool functions, not stale tool wrappers. Successful refreshes atomically replace the previous tool set and metadata, including diff --git a/python/packages/core/agent_framework/_mcp.py b/python/packages/core/agent_framework/_mcp.py index 4a80154f55b..32b5bbdc3b2 100644 --- a/python/packages/core/agent_framework/_mcp.py +++ b/python/packages/core/agent_framework/_mcp.py @@ -1163,7 +1163,12 @@ def __init__( self, name: str, description: str | None = None, - approval_mode: (Literal["always_require", "never_require"] | MCPSpecificApproval | None) = None, + approval_mode: ( + Literal["always_require", "never_require"] + | MCPSpecificApproval + | Callable[[types.Tool | types.Prompt], Literal["always_require", "never_require"]] + | None + ) = None, allowed_tools: Collection[str] | None = None, tool_name_prefix: str | None = None, load_tools: bool = True, @@ -1228,7 +1233,7 @@ def __init__( raise ValueError( f"tool_result_content must be one of {sorted(allowed_modes)}, got {tool_result_content!r}." ) - if isinstance(approval_mode, dict): + if not callable(approval_mode) and isinstance(approval_mode, dict): _mcp_approval_default(approval_mode, warn_stacklevel=_mcp_constructor_stacklevel(self)) self.name = name self.description = description or "" @@ -1677,7 +1682,7 @@ def _filtered_functions(self) -> list[FunctionTool]: def _validate_config_names(self, functions: Sequence[FunctionTool]) -> None: """Reject configured names that identify more than one raw remote name.""" configured_names = set(self.allowed_tools or ()) - if isinstance(self.approval_mode, dict): + if not callable(self.approval_mode) and isinstance(self.approval_mode, dict): configured_names.update(_mcp_approval_names(self.approval_mode.get("always_require_approval"))) configured_names.update(_mcp_approval_names(self.approval_mode.get("never_require_approval"))) if not configured_names: @@ -2571,6 +2576,10 @@ async def _connect_on_owner( elif connection.client is None: raise RuntimeError("MCP connection has neither a Client nor a ClientSession.") functions_before_discovery = self._functions.copy() + approval_modes_before_discovery = [ + (function, function.approval_mode) for function in functions_before_discovery + ] + progressive_loaded_names_before_discovery = self._progressive_loaded_tool_names.copy() call_meta_before_discovery = self._tool_call_meta_by_name param_names_before_discovery = self._tool_param_names_by_name annotations_before_discovery = self._tool_annotations_by_name @@ -2606,10 +2615,14 @@ async def _connect_on_owner( try: await self._close_on_owner() finally: + for function, approval_mode in approval_modes_before_discovery: + function.approval_mode = approval_mode self._functions[:] = functions_before_discovery self._tool_call_meta_by_name = call_meta_before_discovery self._tool_param_names_by_name = param_names_before_discovery self._tool_annotations_by_name = annotations_before_discovery + self._progressive_loaded_tool_names.clear() + self._progressive_loaded_tool_names.update(progressive_loaded_names_before_discovery) raise async def _prepare_for_run(self, kwargs: Mapping[str, Any]) -> None: @@ -2948,8 +2961,23 @@ async def _safe_reload() -> None: def _determine_approval_mode( self, *candidate_names: str, + item: types.Tool | types.Prompt | None = None, + is_retained: bool = False, ) -> Literal["always_require", "never_require"] | None: + """Resolve discovery policy, preserving retained functions under static policies.""" approval_mode = self.approval_mode + if callable(approval_mode): + if item is None: + raise ValueError("A discovered MCP tool or prompt is required for callable approval_mode.") + resolved_mode = approval_mode(item) + if resolved_mode not in _MCP_APPROVAL_MODES: + raise ToolExecutionException( + f"approval_mode callable for MCP item {item.name!r} must return " + "'always_require' or 'never_require', including its default decision." + ) + return resolved_mode + if is_retained: + return None if not isinstance(approval_mode, dict): return approval_mode # type: ignore[return-value] always_require = _mcp_approval_names(approval_mode.get("always_require_approval")) @@ -3003,6 +3031,7 @@ async def _load_prompts_locked(self) -> None: prompt_functions: list[FunctionTool] = [] retained_prompt_names: set[str] = set() new_functions: list[FunctionTool] = [] + prompt_approval_updates: dict[str, Literal["always_require", "never_require"]] = {} items_loaded = 0 def stage_prompt_page(prompt_list: types.ListPromptsResult) -> None: @@ -3029,7 +3058,8 @@ def stage_prompt_page(prompt_list: types.ListPromptsResult) -> None: local_name=local_name, normalized_name=normalized_name, remote_name=prompt.name, - ) + ), + item=prompt, ) func: FunctionTool = FunctionTool( func=_make_mcp_prompt_caller(self, prompt.name), @@ -3055,6 +3085,8 @@ def stage_prompt_page(prompt_list: types.ListPromptsResult) -> None: and existing_prompt.parameters() == func.parameters() ): # Keep the unchanged prompt function so local customizations survive a refresh. + if callable(self.approval_mode) and approval_mode is not None: + prompt_approval_updates[local_name] = approval_mode prompt_functions.append(existing_prompt) continue prompt_functions.append(func) @@ -3096,6 +3128,9 @@ def stage_prompt_page(prompt_list: types.ListPromptsResult) -> None: if self._function_load_callback is not None: for function in new_functions: self._function_load_callback(function, None) + for function in prompt_functions: + if function.name in prompt_approval_updates: + function.approval_mode = prompt_approval_updates[function.name] self._functions[:] = current_functions # Only prompts that keep the same remote identity retain their progressive-load state; a # different remote prompt that normalizes to the same local name must start unloaded. @@ -3209,6 +3244,7 @@ async def _load_tools_locked(self) -> None: tool_call_meta_by_name: dict[str, dict[str, Any]] = {} tool_param_names_by_name: dict[str, set[str]] = {} tool_annotations_by_name: dict[str, Any] = {} + tool_approval_updates: dict[str, Literal["always_require", "never_require"]] = {} items_loaded = 0 def stage_tool_page(tool_list: types.ListToolsResult) -> None: @@ -3270,19 +3306,26 @@ def stage_tool_page(tool_list: types.ListToolsResult) -> None: existing_tool = existing_tools.get(local_name) if ( existing_tool is not None - and (existing_tool.additional_properties or {}).get(_MCP_REMOTE_NAME_KEY) == tool.name + and (existing_tool.additional_properties or {}).get(_MCP_REMOTE_NAME_KEY) != tool.name ): - reused_tool_names.add(local_name) - continue + existing_tool = None approval_mode = self._determine_approval_mode( *_mcp_config_candidate_names( local_name=local_name, normalized_name=normalized_name, remote_name=tool.name, - ) + ), + item=tool, + is_retained=existing_tool is not None, ) + if existing_tool is not None: + reused_tool_names.add(local_name) + if approval_mode is not None: + tool_approval_updates[local_name] = approval_mode + continue + # Create FunctionTools out of each tool func: FunctionTool = FunctionTool( func=_make_mcp_tool_caller(self, tool.name), @@ -3346,6 +3389,9 @@ def stage_tool_page(tool_list: types.ListToolsResult) -> None: and self._function_load_callback is not None ): self._function_load_callback(function, tool_annotations_by_name[remote_name]) + for function in current_functions: + if function.name in tool_approval_updates: + function.approval_mode = tool_approval_updates[function.name] self._functions[:] = current_functions self._tool_call_meta_by_name = tool_call_meta_by_name self._tool_param_names_by_name = tool_param_names_by_name @@ -3808,7 +3854,12 @@ def __init__( mcp_client: Client | None = None, session: ClientSession | None = None, description: str | None = None, - approval_mode: (Literal["always_require", "never_require"] | MCPSpecificApproval | None) = None, + approval_mode: ( + Literal["always_require", "never_require"] + | MCPSpecificApproval + | Callable[[types.Tool | types.Prompt], Literal["always_require", "never_require"]] + | None + ) = None, allowed_tools: Collection[str] | None = None, use_progressive_disclosure: bool = False, always_load: Collection[str] | None = None, @@ -3880,6 +3931,11 @@ def __init__( "never_require") for tools and prompts named in neither list. Without `default`, those tools and prompts do not require approval, and setting `never_require_approval` without `default` emits a ``FutureWarning``. + - A synchronous callable receiving the discovered ``mcp.types.Tool`` or ``mcp.types.Prompt`` + and returning "always_require" or "never_require", including its default decision. It runs once + per item on each discovery refresh, including retained functions, before publication. + Invalid results raise ``ToolExecutionException``; callback exceptions propagate. + Callbacks should not mutate the discovery item or perform side effects. A tool listed in both lists requires approval. ``None`` (the default) does not require approval. allowed_tools: Optional allow-list of MCP tool names to expose as functions. ``None`` (the default) exposes every tool advertised by the MCP server. @@ -4079,7 +4135,12 @@ def __init__( mcp_client: Client | None = None, session: ClientSession | None = None, description: str | None = None, - approval_mode: (Literal["always_require", "never_require"] | MCPSpecificApproval | None) = None, + approval_mode: ( + Literal["always_require", "never_require"] + | MCPSpecificApproval + | Callable[[types.Tool | types.Prompt], Literal["always_require", "never_require"]] + | None + ) = None, allowed_tools: Collection[str] | None = None, use_progressive_disclosure: bool = False, always_load: Collection[str] | None = None, @@ -4154,6 +4215,11 @@ def __init__( "never_require") for tools and prompts named in neither list. Without `default`, those tools and prompts do not require approval, and setting `never_require_approval` without `default` emits a ``FutureWarning``. + - A synchronous callable receiving the discovered ``mcp.types.Tool`` or ``mcp.types.Prompt`` + and returning "always_require" or "never_require", including its default decision. It runs once + per item on each discovery refresh, including retained functions, before publication. + Invalid results raise ``ToolExecutionException``; callback exceptions propagate. + Callbacks should not mutate the discovery item or perform side effects. A tool listed in both lists requires approval. ``None`` (the default) does not require approval. allowed_tools: Optional allow-list of MCP tool names to expose as functions. ``None`` (the default) exposes every tool advertised by the MCP server. @@ -4762,7 +4828,12 @@ def __init__( request_timeout: int | None = _MCP_DEFAULT_READ_TIMEOUT_SECONDS, session: ClientSession | None = None, description: str | None = None, - approval_mode: (Literal["always_require", "never_require"] | MCPSpecificApproval | None) = None, + approval_mode: ( + Literal["always_require", "never_require"] + | MCPSpecificApproval + | Callable[[types.Tool | types.Prompt], Literal["always_require", "never_require"]] + | None + ) = None, allowed_tools: Collection[str] | None = None, use_progressive_disclosure: bool = False, always_load: Collection[str] | None = None, @@ -4819,6 +4890,11 @@ def __init__( "never_require") for tools and prompts named in neither list. Without `default`, those tools and prompts do not require approval, and setting `never_require_approval` without `default` emits a ``FutureWarning``. + - A synchronous callable receiving the discovered ``mcp.types.Tool`` or ``mcp.types.Prompt`` + and returning "always_require" or "never_require", including its default decision. It runs once + per item on each discovery refresh, including retained functions, before publication. + Invalid results raise ``ToolExecutionException``; callback exceptions propagate. + Callbacks should not mutate the discovery item or perform side effects. A tool listed in both lists requires approval. ``None`` (the default) does not require approval. allowed_tools: Optional allow-list of MCP tool names to expose as functions. ``None`` (the default) exposes every tool advertised by the MCP server. diff --git a/python/packages/foundry_hosting/README.md b/python/packages/foundry_hosting/README.md index 05a3f97379b..068188eb61f 100644 --- a/python/packages/foundry_hosting/README.md +++ b/python/packages/foundry_hosting/README.md @@ -2,6 +2,29 @@ This package provides the integration of Agent Framework agents and workflows with the Foundry Agent Server, which can be hosted on Foundry infrastructure. +## Toolbox tool approvals + +`FoundryToolbox` uses each discovered tool's `_meta.tool_configuration.require_approval` when +`approval_mode` is omitted or `None`. See the +[Foundry approval configuration](https://learn.microsoft.com/python/api/azure-ai-projects/azure.ai.projects.models.mcptoolrequireapproval) +for supported metadata shapes. + +Unlike regular MCP tools, Toolbox `approval_mode=None` does not mean no approval. +Use `"never_require"` to disable local approval or `"always_require"` to require it for every function. +Any explicit non-`None` policy, including a dictionary or callable, replaces metadata handling entirely. +Missing metadata defaults to no approval; malformed metadata raises `ToolExecutionException`. + +Metadata filters use remote/original tool names, not local prefixes. Filter criteria must all match; +`always` wins overlaps and unmatched filter-policy tools require approval. Discovery refreshes and reconnects +reapply the policy; failed refreshes preserve the previous complete snapshot and approval modes. + +**Trust boundary:** This Foundry-specific integration trusts the supplied `annotations.readOnlyHint` +when evaluating `read_only` filters, including rules that skip approval. It does not independently +verify that classification or enforce read-only behavior. Applications must trust the classifications +supplied through their configured Toolbox. The private metadata parser is intended only for Foundry +Toolbox; reusing it elsewhere provides no security or compatibility guarantees. It is not a +general-purpose MCP approval policy. + ## Agent instances and factories `ResponsesHostServer` and `InvocationsHostServer` accept an agent instance or a zero-argument callable through the diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_toolbox.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_toolbox.py index 294afbbe9db..51172446aa8 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_toolbox.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_toolbox.py @@ -9,7 +9,7 @@ from collections.abc import Callable, Mapping, Sequence from contextlib import _AsyncGeneratorContextManager # pyright: ignore[reportPrivateUsage] from contextvars import ContextVar -from typing import TYPE_CHECKING, Any, cast +from typing import TYPE_CHECKING, Any, Literal, cast from urllib.parse import urlsplit import httpx2 as httpx @@ -25,6 +25,7 @@ from agent_framework._telemetry import mark_feature_used from agent_framework.exceptions import ToolExecutionException from azure.ai.agentserver.core import get_request_context +from mcp.types import Tool from typing_extensions import override from ._feature_usage import FeatureIndex @@ -34,10 +35,11 @@ from datetime import timedelta from agent_framework import Content, Skill + from agent_framework._mcp import MCPSpecificApproval from azure.core.credentials import AccessToken, TokenCredential from azure.core.credentials_async import AsyncTokenCredential from mcp.client.session import ClientSession - from mcp.types import ReadResourceResult + from mcp.types import Prompt, ReadResourceResult from pydantic import AnyUrl AzureCredentialTypes = TokenCredential | AsyncTokenCredential @@ -48,6 +50,7 @@ DEFAULT_TOOLBOX_SCOPE = "https://ai.azure.com/.default" # Default timeout (seconds) for toolbox MCP requests. _DEFAULT_TIMEOUT = 120.0 +_DEFAULT_APPROVAL_MODE: Literal["always_require", "never_require"] = "never_require" # Environment variable used to inject platform-provided toolbox feature flags. _TOOLSET_FEATURES_ENV_VAR = "FOUNDRY_AGENT_TOOLSET_FEATURES" # Mandatory preview feature flag for Foundry toolbox requests. @@ -158,6 +161,67 @@ async def async_auth_flow(self, request: httpx.Request) -> AsyncGenerator[httpx. yield request +def _toolbox_approval_filter_matches(value: Any, tool: Tool, server_label: Any) -> bool: + """Validate a Foundry MCP approval filter and match its remote identity and annotations.""" + error = f"Invalid Foundry Toolbox approval filter for tool {tool.name!r}." + if not isinstance(value, dict) or value.keys() - {"tool_names", "read_only"}: + raise ToolExecutionException(error) + approval_filter = cast(dict[str, Any], value) + names = approval_filter.get("tool_names") + if names is not None and ( + not isinstance(names, list) or any(not isinstance(name, str) or not name for name in cast(list[object], names)) + ): + raise ToolExecutionException(error) + read_only = approval_filter.get("read_only") + if read_only is not None and not isinstance(read_only, bool): + raise ToolExecutionException(error) + + candidate_names = {tool.name} + if isinstance(server_label, str) and server_label: + prefix = f"{server_label}___" + if tool.name.startswith(prefix): + candidate_names.add(tool.name[len(prefix) :]) + is_read_only = tool.annotations is not None and tool.annotations.read_only_hint is True + return (names is None or bool(candidate_names.intersection(cast(list[str], names)))) and ( + read_only is None or read_only == is_read_only + ) + + +def _toolbox_approval_mode(item: Tool | Prompt) -> Literal["always_require", "never_require"]: + """Resolve Foundry approval metadata for a discovered tool. + + This Foundry-only parser trusts the supplied readOnlyHint for read-only filters; + it does not verify tool behavior. Reuse elsewhere carries no security or + compatibility guarantees. + """ + if not isinstance(item, Tool): + return _DEFAULT_APPROVAL_MODE + meta = item.meta + if meta is None or "tool_configuration" not in meta: + return _DEFAULT_APPROVAL_MODE + configuration = meta["tool_configuration"] + if not isinstance(configuration, dict): + raise ToolExecutionException(f"Invalid Foundry Toolbox tool_configuration for tool {item.name!r}.") + configuration = cast(dict[str, Any], configuration) + if "require_approval" not in configuration: + return _DEFAULT_APPROVAL_MODE + approval = configuration["require_approval"] + if approval == "always": + return "always_require" + if approval == "never": + return "never_require" + if not isinstance(approval, dict) or not approval or approval.keys() - {"always", "never"}: + raise ToolExecutionException(f"Invalid Foundry Toolbox require_approval for tool {item.name!r}.") + approval = cast(dict[str, Any], approval) + matches = { + policy: _toolbox_approval_filter_matches(value, item, configuration.get("server_label")) + for policy, value in approval.items() + } + if matches.get("always") or not matches.get("never"): + return "always_require" + return "never_require" + + class FoundryToolbox(MCPStreamableHTTPTool): """A Foundry toolbox exposed as an MCP tool, with hosting wired in. @@ -181,6 +245,25 @@ class FoundryToolbox(MCPStreamableHTTPTool): Because the toolbox endpoint is a first-party Foundry service, forwarding the opaque caller token to it is safe. + When ``approval_mode`` is omitted or ``None``, discovered functions honor + ``_meta.tool_configuration.require_approval``. Supported policies are ``"always"``, + ``"never"``, and ``always``/``never`` filters with ``tool_names`` and/or ``read_only``. + Names match the remote name or its name without the Toolbox server-label prefix; + local ``tool_name_prefix`` values do not affect metadata matching. Filter criteria + are combined, ``always`` wins overlaps, and unmatched tools require approval. + Missing configuration preserves the no-approval default. Invalid metadata raises + :class:`~agent_framework.exceptions.ToolExecutionException` during discovery. + Refreshes, including reconnects, reapply metadata to retained functions. + The metadata parser is supplied as an ``approval_mode`` callable. An explicit caller + policy (including a per-tool dict or callable) replaces the metadata policy. + + This Foundry-specific integration trusts the supplied ``annotations.readOnlyHint`` + when evaluating ``read_only`` filters, including rules that skip approval. It does + not independently verify the classification or enforce read-only behavior. + Applications must trust the classifications supplied through their configured Toolbox. + The private metadata parser provides no security or compatibility guarantees when + reused outside Foundry Toolbox; it is not a general-purpose MCP approval policy. + Like any MCP tool, the connection lifecycle is driven by the agent: the hosting server enters a factory-created agent for its request and closes its toolbox and owned HTTP client afterward. A long-lived Toolbox is also supported: it @@ -218,6 +301,12 @@ def __init__( *, url: str | None = None, name: str | None = None, + approval_mode: ( + Literal["always_require", "never_require"] + | MCPSpecificApproval + | Callable[[Tool | Prompt], Literal["always_require", "never_require"]] + | None + ) = None, token_scope: str = DEFAULT_TOOLBOX_SCOPE, load_prompts: bool = False, load_tools: bool = True, @@ -238,6 +327,17 @@ def __init__( ``TOOLBOX_NAME``. name: The local tool name. When ``None``, it is taken from ``TOOLBOX_NAME`` or derived from the endpoint path. + approval_mode: Local execution approval policy. ``None`` (the default) selects the + Foundry metadata policy, which honors each tool's + ``_meta.tool_configuration.require_approval`` and uses the no-approval default + when configuration is absent. Unlike regular MCP tools, ``None`` does not + unconditionally mean no approval. Supply ``"never_require"`` to disable local + approval, ``"always_require"`` to require it for every function, an + ``MCPSpecificApproval`` dictionary for per-name rules, or a synchronous callable + receiving a discovered ``mcp.types.Tool`` or ``mcp.types.Prompt``. The callable + must return ``"always_require"`` or ``"never_require"`` for every item, + including its default decision. Every non-``None`` policy replaces the metadata + policy entirely; dictionary name-matching and defaults follow regular MCP rules. token_scope: The token scope to request. Defaults to the Foundry data-plane scope. load_prompts: Whether to load prompts from the toolbox. Defaults to ``False`` @@ -286,6 +386,7 @@ def toolbox_header_provider(runtime_kwargs: dict[str, Any]) -> dict[str, str]: super().__init__( name=tool_name, url=endpoint, + approval_mode=_toolbox_approval_mode if approval_mode is None else approval_mode, http_client=http_client, header_provider=toolbox_header_provider, load_prompts=load_prompts, diff --git a/python/packages/foundry_hosting/pyproject.toml b/python/packages/foundry_hosting/pyproject.toml index 0cfdbad878e..c2191c8dfc7 100644 --- a/python/packages/foundry_hosting/pyproject.toml +++ b/python/packages/foundry_hosting/pyproject.toml @@ -52,7 +52,7 @@ fallback-version = "0.0.0" [tool.pytest.ini_options] testpaths = 'tests' -addopts = "-ra -q -r fEX" +addopts = "-ra -q -r fEX --import-mode=importlib" asyncio_mode = "auto" asyncio_default_fixture_loop_scope = "function" filterwarnings = [] diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/toolbox_approval_helpers.py b/python/packages/foundry_hosting/tests/foundry_hosting/toolbox_approval_helpers.py new file mode 100644 index 00000000000..81fd0550e76 --- /dev/null +++ b/python/packages/foundry_hosting/tests/foundry_hosting/toolbox_approval_helpers.py @@ -0,0 +1,152 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Offline protocol boundaries for Toolbox approval regressions.""" + +from __future__ import annotations + +import json +from collections.abc import AsyncGenerator, AsyncIterator, Awaitable, Mapping, Sequence +from contextlib import asynccontextmanager +from typing import Any + +import httpx2 as httpx +from agent_framework import ( + BaseChatClient, + ChatResponse, + ChatResponseUpdate, + Content, + FunctionInvocationLayer, + Message, + ResponseStream, +) +from azure.core.credentials import AccessToken + +from agent_framework_foundry_hosting import FoundryToolbox + + +class ToolboxCredential: + def get_token(self, *scopes: str, **kwargs: Any) -> AccessToken: + return AccessToken("offline-token", 9999999999) + + +class ToolboxApprovalServer: + def __init__(self) -> None: + self.tools: list[dict[str, Any]] = [] + self.prompts: list[dict[str, Any]] = [] + self.calls: list[dict[str, Any]] = [] + self.initializations = 0 + self.page_size: int | None = None + + async def handle(self, request: httpx.Request) -> httpx.Response: + if request.method == "GET": + return httpx.Response(405) + if request.method == "DELETE": + return httpx.Response(200) + payload = json.loads(request.content) + method = payload.get("method") + if "id" not in payload: + return httpx.Response(202) + result: dict[str, Any] + if method == "server/discover": + return httpx.Response( + 200, + json={ + "jsonrpc": "2.0", + "id": payload["id"], + "error": {"code": -32601, "message": "Method not found"}, + }, + ) + if method == "initialize": + self.initializations += 1 + result = { + "protocolVersion": payload["params"]["protocolVersion"], + "capabilities": {"tools": {}, "prompts": {}}, + "serverInfo": {"name": "toolbox-approval", "version": "1"}, + } + elif method == "tools/list": + start = int(payload.get("params", {}).get("cursor", "0")) + end = len(self.tools) if self.page_size is None else start + self.page_size + result = {"tools": self.tools[start:end]} + if end < len(self.tools): + result["nextCursor"] = str(end) + elif method == "tools/call": + self.calls.append(payload["params"]) + result = {"content": [{"type": "text", "text": "search-result"}]} + elif method == "prompts/list": + result = {"prompts": self.prompts} + elif method == "ping": + result = {} + else: + raise AssertionError(f"Unexpected MCP method: {method}") + return httpx.Response(200, json={"jsonrpc": "2.0", "id": payload["id"], "result": result}) + + +@asynccontextmanager +async def toolbox_connection( + server: ToolboxApprovalServer, *, connect: bool = True, **kwargs: Any +) -> AsyncGenerator[FoundryToolbox]: + toolbox = FoundryToolbox(ToolboxCredential(), url="https://toolbox.invalid/mcp", **kwargs) + original = toolbox._httpx_client + assert original is not None + await original.aclose() + toolbox._httpx_client = httpx.AsyncClient(transport=httpx.MockTransport(server.handle)) + try: + if connect: + await toolbox.connect() + yield toolbox + finally: + await toolbox.close() + + +def toolbox_tool( + approval: Any = "always", + *, + name: str = "learn___microsoft_docs_search", + read_only: bool | None = None, +) -> dict[str, Any]: + tool: dict[str, Any] = { + "name": name, + "inputSchema": {"type": "object", "properties": {}}, + "_meta": { + "tool_configuration": { + "type": "mcp", + "server_label": "learn", + "server_url": "https://learn.microsoft.com/api/mcp", + "require_approval": approval, + "original_type": "mcp", + } + }, + } + if read_only is not None: + tool["annotations"] = {"readOnlyHint": read_only} + return tool + + +class ToolboxApprovalClient(FunctionInvocationLayer[Any], BaseChatClient[Any]): + def __init__(self, tool_name: str) -> None: + super().__init__() + self.tool_name = tool_name + self.calls: list[list[Message]] = [] + + def _inner_get_response( + self, + *, + messages: Sequence[Message], + stream: bool, + options: Mapping[str, Any], + **kwargs: Any, + ) -> Awaitable[ChatResponse] | ResponseStream[ChatResponseUpdate, ChatResponse]: + self.calls.append(list(messages)) + contents = ( + [Content.from_function_call(call_id="call-search", name=self.tool_name, arguments="{}")] + if len(self.calls) == 1 + else [Content.from_text("done")] + ) + + async def updates() -> AsyncIterator[ChatResponseUpdate]: + yield ChatResponseUpdate(role="assistant", contents=contents) + + async def complete() -> ChatResponse: + return ChatResponse(messages=[Message("assistant", contents=contents)]) + + return ResponseStream(updates(), finalizer=ChatResponse.from_updates) if stream else complete() diff --git a/python/packages/foundry_hosting/tests/test_toolbox.py b/python/packages/foundry_hosting/tests/test_toolbox.py index 324bc0cb01b..52a04d34b1b 100644 --- a/python/packages/foundry_hosting/tests/test_toolbox.py +++ b/python/packages/foundry_hosting/tests/test_toolbox.py @@ -11,11 +11,20 @@ from datetime import datetime, timedelta, timezone from types import SimpleNamespace from typing import Any, cast -from unittest.mock import AsyncMock, patch +from unittest.mock import AsyncMock, Mock, patch +import httpx as host_httpx import httpx2 as httpx import pytest -from agent_framework import MCPStreamableHTTPTool, SkillsProvider, SkillsSourceContext, SupportsAgentRun +from agent_framework import ( + Agent, + FunctionInvocationContext, + MCPStreamableHTTPTool, + Message, + SkillsProvider, + SkillsSourceContext, + SupportsAgentRun, +) from agent_framework.exceptions import ToolException, ToolExecutionException from azure.ai.agentserver.core import ( FoundryAgentRequestContext, @@ -23,9 +32,10 @@ set_request_context, ) from mcp.client.session import ClientSession +from mcp.types import Prompt, Tool from pydantic import AnyUrl -from agent_framework_foundry_hosting import FoundryToolbox +from agent_framework_foundry_hosting import FoundryToolbox, ResponsesHostServer from agent_framework_foundry_hosting._feature_usage import FeatureIndex from agent_framework_foundry_hosting._toolbox import ( _FoundryToolboxSkillsSource, @@ -34,6 +44,13 @@ _ToolboxAuth, ) +from .foundry_hosting.toolbox_approval_helpers import ( # pyrefly: ignore[missing-import] - pytest's importlib namespace + ToolboxApprovalClient, + ToolboxApprovalServer, + toolbox_connection, + toolbox_tool, +) + class _StubAgent: """Minimal stand-in for a ``SupportsAgentRun`` used to build a source context.""" @@ -934,3 +951,451 @@ async def test_close_idempotent_with_reconnection(self) -> None: assert isinstance(toolbox._httpx_client.auth, _ToolboxAuth) await toolbox.close() + + +@pytest.mark.parametrize("prefix", [None, "guarded"]) +@pytest.mark.parametrize( + ("approval", "expected"), + [ + ("always", "always_require"), + ("never", "never_require"), + ({"always": {"tool_names": ["microsoft_docs_search"]}}, "always_require"), + ({"never": {"tool_names": ["microsoft_docs_search"]}}, "never_require"), + ({"never": {"tool_names": ["learn___microsoft_docs_search"]}}, "never_require"), + ({"never": {"tool_names": ["guarded_learn___microsoft_docs_search"]}}, "always_require"), + ({"never": {"tool_names": ["other"]}}, "always_require"), + ({"always": {"tool_names": ["other"]}}, "always_require"), + ({"never": {"tool_names": []}}, "always_require"), + ({"never": {}}, "never_require"), + ({"always": {}, "never": {}}, "always_require"), + ( + {"always": {"tool_names": ["microsoft_docs_search"]}, "never": {"tool_names": ["microsoft_docs_search"]}}, + "always_require", + ), + ], +) +async def test_discovered_tool_honors_metadata(approval: Any, expected: str, prefix: str | None) -> None: + server = ToolboxApprovalServer() + server.tools = [toolbox_tool(approval)] + async with toolbox_connection(server, tool_name_prefix=prefix) as toolbox: + assert toolbox.functions[0].approval_mode == expected + + +@pytest.mark.parametrize("read_only", [None, False, True]) +@pytest.mark.parametrize("filter_read_only", [False, True]) +@pytest.mark.parametrize("names", [None, ["microsoft_docs_search"], ["other"]]) +async def test_metadata_filters_match_names_and_read_only( + read_only: bool | None, filter_read_only: bool, names: list[str] | None +) -> None: + server = ToolboxApprovalServer() + server.tools = [toolbox_tool({"never": {"read_only": filter_read_only, "tool_names": names}}, read_only=read_only)] + async with toolbox_connection(server) as toolbox: + matches = (names is None or names == ["microsoft_docs_search"]) and filter_read_only == (read_only is True) + assert toolbox.functions[0].approval_mode == ("never_require" if matches else "always_require") + + +@pytest.mark.parametrize("metadata_policy", ["always", "never", None]) +@pytest.mark.parametrize( + ("policy", "expected"), + [ + ("never_require", "never_require"), + ("always_require", "always_require"), + ({"always_require_approval": ["learn___microsoft_docs_search"]}, "always_require"), + ( + {"never_require_approval": ["guarded_learn___microsoft_docs_search"], "default": "always_require"}, + "never_require", + ), + ({"default": "never_require"}, "never_require"), + ({}, "never_require"), + ], +) +async def test_explicit_caller_policy_replaces_metadata(policy: Any, expected: str, metadata_policy: Any) -> None: + server = ToolboxApprovalServer() + server.tools = [toolbox_tool(metadata_policy)] + async with toolbox_connection(server, tool_name_prefix="guarded", approval_mode=policy) as toolbox: + assert toolbox.functions[0].approval_mode == expected + + +@pytest.mark.parametrize("meta", [None, {}, {"tool_configuration": {}}, {"unrelated": "always"}]) +@pytest.mark.parametrize("default_mode", ["never_require", "always_require"]) +async def test_missing_approval_metadata_preserves_default( + meta: Any, default_mode: str, monkeypatch: pytest.MonkeyPatch +) -> None: + monkeypatch.setattr("agent_framework_foundry_hosting._toolbox._DEFAULT_APPROVAL_MODE", default_mode) + server = ToolboxApprovalServer() + server.tools = [toolbox_tool()] + server.tools[0]["_meta"] = meta + server.prompts = [{"name": "summarize"}] + async with toolbox_connection(server, load_prompts=True) as toolbox: + assert len(toolbox.functions) == 2 + assert {function.approval_mode for function in toolbox.functions} == {default_mode} + + +async def test_explicit_none_approval_mode_selects_toolbox_metadata_policy() -> None: + server = ToolboxApprovalServer() + server.tools = [toolbox_tool("always")] + async with toolbox_connection(server, approval_mode=None) as toolbox: + assert toolbox.functions[0].approval_mode == "always_require" + + +@pytest.mark.parametrize( + "approval", + [ + None, + False, + 1, + [], + "", + "ALWAYS", + "unknown", + {}, + {"unexpected": {}}, + {"never": None}, + {"never": []}, + {"never": {"tool_names": "microsoft_docs_search"}}, + {"never": {"tool_names": [1]}}, + {"never": {"tool_names": [""]}}, + {"never": {"read_only": "true"}}, + {"never": {"unknown": True}}, + {"always": {}, "never": {"tool_names": False}}, + ], +) +async def test_malformed_approval_fails_discovery(approval: Any) -> None: + server = ToolboxApprovalServer() + server.tools = [toolbox_tool(approval)] + async with toolbox_connection(server, connect=False) as toolbox: + with pytest.raises(ToolExecutionException, match="Foundry Toolbox"): + await toolbox.connect() + assert toolbox.functions == [] + assert server.calls == [] + + +@pytest.mark.parametrize("configuration", [None, [], "never", False]) +async def test_malformed_tool_configuration_fails_discovery(configuration: Any) -> None: + server = ToolboxApprovalServer() + server.tools = [toolbox_tool()] + server.tools[0]["_meta"]["tool_configuration"] = configuration + async with toolbox_connection(server, connect=False) as toolbox: + with pytest.raises(ToolExecutionException, match="tool_configuration"): + await toolbox.connect() + + +async def test_ordinary_mcp_does_not_interpret_foundry_metadata_or_replace_custom_approval() -> None: + server = ToolboxApprovalServer() + server.tools = [toolbox_tool()] + async with ( + httpx.AsyncClient(transport=httpx.MockTransport(server.handle)) as transport, + MCPStreamableHTTPTool( + name="ordinary", url="https://toolbox.invalid/mcp", http_client=transport, approval_mode=None + ) as toolbox, + ): + function = toolbox.functions[0] + assert function.approval_mode == "never_require" + function.approval_mode = "always_require" + await toolbox.load_tools() + assert toolbox.functions[0] is function + assert function.approval_mode == "always_require" + + +async def test_metadata_refresh_is_atomic_and_updates_retained_functions() -> None: + server = ToolboxApprovalServer() + server.page_size = 1 + server.tools = [toolbox_tool("never")] + async with toolbox_connection(server) as toolbox: + function = toolbox.functions[0] + server.tools = [toolbox_tool("always"), toolbox_tool(None, name="learn___invalid")] + with pytest.raises(ToolExecutionException, match="require_approval"): + await toolbox.load_tools() + assert toolbox.functions == [function] + assert function.approval_mode == "never_require" + server.tools = [toolbox_tool("always")] + await toolbox.load_tools() + assert toolbox.functions[0] is function + assert function.approval_mode == "always_require" + server.tools = [toolbox_tool("never")] + await toolbox.connect(reset=True) + assert toolbox.functions[0].approval_mode == "never_require" + assert server.initializations == 2 + del server.tools[0]["_meta"] + await toolbox.load_tools() + assert toolbox.functions[0].approval_mode == "never_require" + + +@pytest.mark.parametrize( + ("initial_policy", "refreshed_policy"), + [("always", "never"), ("never", "always")], +) +async def test_reconnect_restores_approval_modes_when_prompt_discovery_fails( + initial_policy: str, refreshed_policy: str +) -> None: + server = ToolboxApprovalServer() + server.tools = [toolbox_tool(initial_policy)] + server.prompts = [{"name": "summarize"}] + async with toolbox_connection(server, load_prompts=True) as toolbox: + functions = list(toolbox.functions) + original_modes = [function.approval_mode for function in functions] + server.tools = [toolbox_tool(refreshed_policy)] + server.prompts = [{"name": "summarize", "arguments": "invalid"}] + + with pytest.raises(ValueError, match="arguments"): + await toolbox.connect(reset=True) + + assert server.initializations == 2 + assert not toolbox.is_connected + assert all(current is previous for current, previous in zip(toolbox.functions, functions, strict=True)) + assert [function.approval_mode for function in toolbox.functions] == original_modes + + server.prompts = [{"name": "summarize"}] + await toolbox.connect() + assert toolbox.functions[0] is functions[0] + assert toolbox.functions[0].approval_mode == f"{refreshed_policy}_require" + + +async def test_reconnect_restores_progressive_tools_when_prompt_discovery_fails() -> None: + server = ToolboxApprovalServer() + server.tools = [toolbox_tool(name="learn___removed"), toolbox_tool(name="learn___kept")] + server.prompts = [{"name": "summarize"}] + async with toolbox_connection(server, load_prompts=True, use_progressive_disclosure=True) as toolbox: + loader = next(function for function in toolbox.functions if function.name == "load_tool") + arguments = {"tool": ["learn___removed", "learn___kept"]} + context = FunctionInvocationContext(function=loader, arguments=arguments, tools=list(toolbox.functions)) + await loader.invoke(arguments=arguments, context=context) + functions = list(toolbox.functions) + assert {function.name for function in functions} >= {"learn___removed", "learn___kept"} + + server.tools = [toolbox_tool(name="learn___kept")] + server.prompts = [{"name": "summarize", "arguments": "invalid"}] + with pytest.raises(ValueError, match="arguments"): + await toolbox.connect(reset=True) + + assert server.initializations == 2 + assert not toolbox.is_connected + assert all(current is previous for current, previous in zip(toolbox.functions, functions, strict=True)) + assert toolbox._progressive_loaded_tool_names == {"learn___removed", "learn___kept"} + + server.prompts = [{"name": "summarize"}] + await toolbox.connect() + names = {function.name for function in toolbox.functions} + assert "learn___kept" in names + assert "learn___removed" not in names + assert toolbox._progressive_loaded_tool_names == {"learn___kept"} + + +async def test_each_tool_uses_its_own_metadata_and_exact_server_prefix() -> None: + server = ToolboxApprovalServer() + server.tools = [ + toolbox_tool("always", name="learn___guarded"), + toolbox_tool("never", name="learn___safe"), + toolbox_tool({"never": {"tool_names": ["safe"]}}, name="other___safe"), + toolbox_tool({"never": {"tool_names": ["learn___safe"]}}, name="learn___learn___safe"), + ] + async with toolbox_connection( + server, tool_name_prefix="local", allowed_tools=["learn___guarded", "learn___safe"] + ) as toolbox: + assert {function.name: function.approval_mode for function in toolbox.functions} == { + "local_learn___guarded": "always_require", + "local_learn___safe": "never_require", + } + toolbox.allowed_tools = None + assert {function.name: function.approval_mode for function in toolbox.functions} == { + "local_learn___guarded": "always_require", + "local_learn___safe": "never_require", + "local_other___safe": "always_require", + "local_learn___learn___safe": "never_require", + } + + +@pytest.mark.parametrize("stream", [False, True]) +@pytest.mark.parametrize("approved", [False, True]) +async def test_metadata_approval_pauses_and_resumes_once(stream: bool, approved: bool) -> None: + server = ToolboxApprovalServer() + server.tools = [toolbox_tool()] + client = ToolboxApprovalClient("guarded_learn___microsoft_docs_search") + async with toolbox_connection(server, tool_name_prefix="guarded") as toolbox: + agent = Agent(client=client, tools=toolbox) + session = agent.create_session() + if stream: + paused_stream = agent.run("Search the docs", session=session, stream=True) + paused_updates = [update async for update in paused_stream] + paused = await paused_stream.get_final_response() + assert any( + content.type == "function_approval_request" for update in paused_updates for content in update.contents + ) + else: + paused = await agent.run("Search the docs", session=session) + approvals = [ + content + for message in paused.messages + for content in message.contents + if content.type == "function_approval_request" + ] + assert len(approvals) == 1 + assert not any(content.type == "function_result" for message in paused.messages for content in message.contents) + assert server.calls == [] + assert len(client.calls) == 1 + decision = Message("user", [approvals[0].to_function_approval_response(approved=approved)]) + if stream: + resumed_stream = agent.run(decision, session=session, stream=True) + resumed_updates = [update async for update in resumed_stream] + resumed = await resumed_stream.get_final_response() + assert any(content.type == "function_result" for update in resumed_updates for content in update.contents) + else: + resumed = await agent.run(decision, session=session) + assert resumed.text == "done" + assert len(server.calls) == int(approved) + returned = [content for message in resumed.messages for content in message.contents] + assert sum(content.type == "function_result" for content in returned) == 1 + model_history = [content for message in client.calls[-1] for content in message.contents] + assert sum(content.type == "function_call" for content in model_history) == 1 + assert sum(content.type == "function_result" for content in model_history) == 1 + assert not any(content.type.startswith("function_approval") for content in model_history) + await agent.run("Continue", session=session) + assert len(server.calls) == int(approved) + + +@pytest.mark.parametrize("stream", [False, True]) +async def test_responses_host_returns_metadata_approval_before_tool_execution(stream: bool) -> None: + mcp_server = ToolboxApprovalServer() + mcp_server.tools = [toolbox_tool()] + model = ToolboxApprovalClient("learn___microsoft_docs_search") + async with toolbox_connection(mcp_server) as toolbox: + host = ResponsesHostServer(agent=Agent(client=model, tools=toolbox)) + async with host_httpx.AsyncClient( + transport=host_httpx.ASGITransport(app=host), base_url="http://test" + ) as client: + first = await client.post( + "/responses", json={"model": "test-model", "input": "Search the docs", "stream": stream} + ) + assert first.status_code == 200 + if stream: + first_events = [ + json.loads(line[6:]) + for line in first.text.splitlines() + if line.startswith("data: ") and line != "data: [DONE]" + ] + first_body = next(event["response"] for event in first_events if event["type"] == "response.completed") + else: + first_body = first.json() + approvals = [item for item in first_body["output"] if item["type"] == "mcp_approval_request"] + assert len(approvals) == 1 + assert not any(item["type"] == "function_call_output" for item in first_body["output"]) + assert mcp_server.calls == [] + second = await client.post( + "/responses", + json={ + "model": "test-model", + "input": [ + {"type": "mcp_approval_response", "approval_request_id": approvals[0]["id"], "approve": True} + ], + "previous_response_id": first_body["id"], + "stream": stream, + }, + ) + assert second.status_code == 200 + if stream: + second_events = [ + json.loads(line[6:]) + for line in second.text.splitlines() + if line.startswith("data: ") and line != "data: [DONE]" + ] + second_body = next( + event["response"] for event in second_events if event["type"] == "response.completed" + ) + else: + second_body = second.json() + assert sum(item["type"] == "function_call_output" for item in second_body["output"]) == 1 + assert len(mcp_server.calls) == 1 + + +async def test_callable_approval_policy_is_composable_without_a_subclass() -> None: + server = ToolboxApprovalServer() + server.tools = [toolbox_tool()] + server.prompts = [{"name": "summarize", "description": "Summarize the result"}] + policy = Mock(return_value="always_require") + async with ( + httpx.AsyncClient(transport=httpx.MockTransport(server.handle)) as transport, + MCPStreamableHTTPTool( + name="ordinary", + url="https://toolbox.invalid/mcp", + http_client=transport, + tool_name_prefix="local", + approval_mode=policy, + ) as toolbox, + ): + assert {function.approval_mode for function in toolbox.functions} == {"always_require"} + items = [call.args[0] for call in policy.call_args_list] + assert len(items) == 2 + assert any(isinstance(item, Tool) and item.name == "learn___microsoft_docs_search" for item in items) + assert any(isinstance(item, Prompt) and item.name == "summarize" for item in items) + functions = list(toolbox.functions) + policy.return_value = "never_require" + await toolbox.load_tools() + await toolbox.load_prompts() + assert toolbox.functions == functions + assert all(current is previous for current, previous in zip(toolbox.functions, functions, strict=True)) + assert {function.approval_mode for function in toolbox.functions} == {"never_require"} + assert policy.call_count == 4 + + +@pytest.mark.parametrize("kind", ["tool", "prompt"]) +async def test_callable_approval_requires_an_explicit_initial_decision(kind: str) -> None: + server = ToolboxApprovalServer() + server.tools = [toolbox_tool()] + server.prompts = [{"name": "summarize"}] + with pytest.raises(ToolExecutionException, match="'always_require' or 'never_require'"): + async with toolbox_connection( + server, + approval_mode=Mock(return_value=None), + load_tools=kind == "tool", + load_prompts=kind == "prompt", + ): + pytest.fail("A callback without an explicit decision must fail discovery.") + + +@pytest.mark.parametrize("kind", ["tool", "prompt"]) +@pytest.mark.parametrize("invalid", [None, "always", "", True, False, 1, [], {}]) +async def test_callable_approval_rejects_invalid_results_atomically(kind: str, invalid: Any) -> None: + server = ToolboxApprovalServer() + server.tools = [toolbox_tool(), toolbox_tool(name="learn___second")] + server.prompts = [{"name": "summarize"}, {"name": "translate"}] + policy = Mock(return_value="always_require") + async with toolbox_connection(server, approval_mode=policy, load_prompts=True) as toolbox: + functions = list(toolbox.functions) + policy.side_effect = ["never_require", invalid] + with pytest.raises(ToolExecutionException, match="approval_mode callable"): + await (toolbox.load_tools() if kind == "tool" else toolbox.load_prompts()) + assert all(current is previous for current, previous in zip(toolbox.functions, functions, strict=True)) + assert {function.approval_mode for function in toolbox.functions} == {"always_require"} + + +@pytest.mark.parametrize("kind", ["tool", "prompt"]) +async def test_callable_approval_errors_preserve_previous_snapshot(kind: str) -> None: + server = ToolboxApprovalServer() + server.tools = [toolbox_tool(), toolbox_tool(name="learn___second")] + server.prompts = [{"name": "summarize"}, {"name": "translate"}] + policy = Mock(return_value="never_require") + async with toolbox_connection(server, approval_mode=policy, load_prompts=True) as toolbox: + functions = list(toolbox.functions) + policy.side_effect = ["always_require", ValueError("policy failed")] + with pytest.raises(ValueError, match="policy failed"): + await (toolbox.load_tools() if kind == "tool" else toolbox.load_prompts()) + assert toolbox.functions == functions + assert {function.approval_mode for function in toolbox.functions} == {"never_require"} + + +async def test_caller_can_wrap_the_foundry_metadata_policy() -> None: + server = ToolboxApprovalServer() + server.tools = [toolbox_tool("never")] + server.prompts = [{"name": "summarize"}] + async with toolbox_connection(server, load_prompts=True) as toolbox: + assert {function.approval_mode for function in toolbox.functions} == {"never_require"} + metadata_policy = toolbox.approval_mode + assert callable(metadata_policy) + caller_policy = Mock(side_effect=metadata_policy) + toolbox.approval_mode = caller_policy + await toolbox.load_tools() + assert toolbox.functions[0].approval_mode == "never_require" + caller_policy.side_effect = None + caller_policy.return_value = "always_require" + await toolbox.load_tools() + assert toolbox.functions[0].approval_mode == "always_require" diff --git a/skills/agent-framework-builder-python/references/hosting-and-deployment.md b/skills/agent-framework-builder-python/references/hosting-and-deployment.md index 6d0e942ba0e..bf6c87344ae 100644 --- a/skills/agent-framework-builder-python/references/hosting-and-deployment.md +++ b/skills/agent-framework-builder-python/references/hosting-and-deployment.md @@ -28,6 +28,15 @@ into application code. factory. - Make session, checkpoint, response, identity, approval, storage, and cleanup ownership explicit. +MCP `approval_mode` supports a synchronous callable so server-specific policies can be composed without +subclassing a transport. It receives a discovered `mcp.types.Tool` or `mcp.types.Prompt` and must return +`"always_require"` or `"never_require"` for every item, including its default decision. It runs on discovery +and refresh, not invocation; invalid results fail discovery. Ordinary MCP `approval_mode=None` means no approval. + +`FoundryToolbox` instead uses `None` to select its metadata policy. See +[Toolbox approvals and trust boundary](https://github.com/microsoft/agent-framework/blob/main/python/packages/foundry_hosting/README.md#toolbox-tool-approvals) +for vendor-specific configuration, caller overrides, and the trust placed in read-only labels. + For MCP agent tools, `AgentMCPTool.call_tool(...)` validates the generated input schema before execution or session-store access. Applications using `mcp_to_run(...)` directly must validate their own schema before conversion. Keep schemas in trusted application configuration. Regex validation is synchronous and has no execution timeout;