Python: Remove bespoke Foundry toolbox helpers; standardize on MCP for toolbox consumption (#5671)

* Remove Foundry toolbox helpers; standardize on MCP for toolbox consumption

- Remove RawFoundryChatClient.get_toolbox() and its fetch_toolbox import
- Remove fetch_toolbox, select_toolbox_tools, get_toolbox_tool_name,
  get_toolbox_tool_type, FoundryHostedToolType, ToolboxToolSelectionInput
  from agent_framework_foundry._tools
- Remove ExperimentalFeature.TOOLBOXES from _feature_stage.py (no consumers)
- Drop toolbox re-exports from agent_framework_foundry/__init__.py and
  agent_framework.foundry namespace
- Update _sanitize_foundry_response_tool docstring to remove toolbox framing;
  sanitization logic itself is unchanged
- Update _agent.py docstring: 'toolbox-fetched MCP' → 'hosted MCP'
- Delete tests/test_toolbox.py (all tests covered removed helpers)
- Update test_foundry_chat_client.py: rename/redoc tests that mentioned
  toolbox but test sanitization that remains
- Delete foundry_chat_client_with_toolbox.py (bespoke toolbox API sample)
- Delete foundry_toolbox_context_provider.py (relied on select_toolbox_tools)
- Rename foundry_chat_client_with_toolbox_mcp.py →
  foundry_chat_client_with_toolbox.py (canonical MCP pattern)
- Rewrite 04_foundry_toolbox/main.py to use MCPStreamableHTTPTool
- Update provider/README, context_providers/README, 04_foundry_toolbox/README

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

* fix(samples): update 06_files sample to consume toolbox via MCP (#5670)

Replace removed get_toolbox/select_toolbox_tools APIs with
MCPStreamableHTTPTool, using allowed_tools=["code_interpreter"] to
select only the code interpreter from the toolbox endpoint.

Update .env.example and README to use FOUNDRY_TOOLBOX_ENDPOINT
instead of TOOLBOX_NAME.

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

* fix(foundry): remove non-existent toolbox helper APIs from README (#5670)

Remove the 'fetch, optionally filter, and pass tools directly' pattern
from the FoundryChatClient toolbox documentation, as select_toolbox_tools
and get_toolbox were removed. Only the MCP endpoint pattern is documented.

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

* fix(foundry): remove residual toolbox docstring references and reproduction report

Remove REPRODUCTION_REPORT.md (workflow artifact that should not be committed),
and update two remaining docstring references that still said 'toolbox reads'
/'toolbox definition' after the toolbox helpers were removed.

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

* Python: Remove bespoke Foundry toolbox helpers; standardize on MCP for toolbox consumption

Fixes #5670

* fix(#5670): resolve toolbox endpoint from TOOLBOX_NAME fallback; add namespace regression tests

- Add _resolve_toolbox_endpoint() helper in 04_foundry_toolbox/main.py and
  06_files/main.py that prefers FOUNDRY_TOOLBOX_ENDPOINT but falls back to
  deriving the MCP URL from FOUNDRY_PROJECT_ENDPOINT + TOOLBOX_NAME — fixing
  the startup KeyError when agents are deployed via azd provision (which injects
  TOOLBOX_NAME, not FOUNDRY_TOOLBOX_ENDPOINT).
- Update 04_foundry_toolbox/.env.example to use FOUNDRY_TOOLBOX_ENDPOINT
  (consistent with 06_files).
- Add TOOLBOX_NAME env var to 06_files/agent.yaml so deployed agents have it
  available for the fallback derivation.
- Update both READMEs to document the two ways to supply the toolbox endpoint.
- Add test_foundry_namespace_no_longer_exposes_toolbox_helpers() with negative
  assertions for FoundryHostedToolType, get_toolbox_tool_name,
  get_toolbox_tool_type, and select_toolbox_tools — guarding against accidental
  re-introduction of removed symbols.

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

* fix(samples): fail fast on empty FOUNDRY_TOOLBOX_ENDPOINT; add unit tests

Addresses review feedback for #5670:

- In _resolve_toolbox_endpoint() (04_foundry_toolbox/main.py and
  06_files/main.py) change the walrus-operator check from a truthy
  test to an explicit 'is not None' guard.  An explicitly set empty
  string now raises ValueError immediately with a clear message
  instead of silently falling through to the fallback URL
  construction.

- Add tests/samples/hosting/test_toolbox_endpoint.py covering both
  sample modules:
    (a) FOUNDRY_TOOLBOX_ENDPOINT set → returned as-is
    (b) FOUNDRY_TOOLBOX_ENDPOINT set to empty string → ValueError
    (c) fallback constructs URL from FOUNDRY_PROJECT_ENDPOINT + TOOLBOX_NAME,
        stripping trailing slashes
    (d) neither variable group set → KeyError

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

* Address review feedback: remove extraneous test and docstring content

- Remove test_foundry_namespace_no_longer_exposes_toolbox_helpers (no longer warranted)
- Remove docstring from _agent.py _prepare_tools_for_openai (extraneous)
- Trim _chat_client.py _prepare_tools_for_openai docstring to one-liner (toolbox references no longer relevant)

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

* fix: remove remaining extraneous docstring from RawFoundryChatClient._prepare_tools_for_openai

Address review comment on PR #5671: reviewer noted the description
isn't warranted now that toolbox helpers have been removed. Matches
the pattern in RawFoundryAgentChatClient which has no docstring.

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

---------

Co-authored-by: Copilot <copilot@github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Evan Mattson
2026-05-07 08:56:16 +09:00
committed by GitHub
Unverified
parent 51ad460d5f
commit e56e6dad4d
26 changed files with 314 additions and 1161 deletions
@@ -139,7 +139,6 @@ def test_prepare_options_tool_choice_required_includes_any() -> None:
assert request["toolConfig"]["toolChoice"] == {"any": {}}
def test_prepare_options_tool_choice_auto_without_tools_omits_tool_config() -> None:
"""When tool_choice='auto' but no tools are provided, toolConfig must be omitted.
@@ -52,7 +52,6 @@ class ExperimentalFeature(str, Enum):
FUNCTIONAL_WORKFLOWS = "FUNCTIONAL_WORKFLOWS"
HARNESS = "HARNESS"
SKILLS = "SKILLS"
TOOLBOXES = "TOOLBOXES"
class ReleaseCandidateFeature(str, Enum):
@@ -30,7 +30,6 @@ _IMPORTS: dict[str, tuple[str, str]] = {
"FoundryEmbeddingOptions": ("agent_framework_foundry", "agent-framework-foundry"),
"FoundryEmbeddingSettings": ("agent_framework_foundry", "agent-framework-foundry"),
"FoundryEvals": ("agent_framework_foundry", "agent-framework-foundry"),
"FoundryHostedToolType": ("agent_framework_foundry", "agent-framework-foundry"),
"FoundryMemoryProvider": ("agent_framework_foundry", "agent-framework-foundry"),
"FoundryLocalChatOptions": ("agent_framework_foundry_local", "agent-framework-foundry-local"),
"FoundryLocalClient": ("agent_framework_foundry_local", "agent-framework-foundry-local"),
@@ -42,9 +41,6 @@ _IMPORTS: dict[str, tuple[str, str]] = {
"RawFoundryEmbeddingClient": ("agent_framework_foundry", "agent-framework-foundry"),
"evaluate_foundry_target": ("agent_framework_foundry", "agent-framework-foundry"),
"evaluate_traces": ("agent_framework_foundry", "agent-framework-foundry"),
"get_toolbox_tool_name": ("agent_framework_foundry", "agent-framework-foundry"),
"get_toolbox_tool_type": ("agent_framework_foundry", "agent-framework-foundry"),
"select_toolbox_tools": ("agent_framework_foundry", "agent-framework-foundry"),
}
@@ -19,7 +19,6 @@ from agent_framework_foundry import (
FoundryEmbeddingOptions,
FoundryEmbeddingSettings,
FoundryEvals,
FoundryHostedToolType,
FoundryMemoryProvider,
RawFoundryAgent,
RawFoundryAgentChatClient,
@@ -27,9 +26,6 @@ from agent_framework_foundry import (
RawFoundryEmbeddingClient,
evaluate_foundry_target,
evaluate_traces,
get_toolbox_tool_name,
get_toolbox_tool_type,
select_toolbox_tools,
)
from agent_framework_foundry_local import (
FoundryLocalChatOptions,
@@ -51,7 +47,6 @@ __all__ = [
"FoundryEmbeddingOptions",
"FoundryEmbeddingSettings",
"FoundryEvals",
"FoundryHostedToolType",
"FoundryLocalChatOptions",
"FoundryLocalClient",
"FoundryLocalSettings",
@@ -63,7 +58,4 @@ __all__ = [
"RawFoundryEmbeddingClient",
"evaluate_foundry_target",
"evaluate_traces",
"get_toolbox_tool_name",
"get_toolbox_tool_type",
"select_toolbox_tools",
]
+1 -26
View File
@@ -21,32 +21,7 @@ For hosted `FoundryAgent`, the toolbox must already be attached to the agent in
### Using toolboxes with `FoundryChatClient`
There are two patterns for wiring a toolbox into a `FoundryChatClient`-backed agent.
**1. Fetch, optionally filter, and pass the tools directly**
Load the toolbox from the Microsoft Foundry project, optionally select a subset of its tools, and hand them to an `Agent` alongside any other tools you own:
```python
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient, select_toolbox_tools
client = FoundryChatClient(...)
toolbox = await client.get_toolbox("my-toolbox", version="3")
# Pass the whole toolbox:
agent = Agent(client=client, tools=toolbox)
# Or filter to a subset first:
selected = select_toolbox_tools(toolbox, include_types=["code_interpreter", "mcp"])
agent = Agent(client=client, tools=selected)
```
See [`foundry_chat_client_with_toolbox.py`](../../samples/02-agents/providers/foundry/foundry_chat_client_with_toolbox.py) for a full example, including combining multiple toolboxes.
**2. Connect to the toolbox's MCP endpoint with `MCPStreamableHTTPTool`**
Each toolbox is reachable as an MCP server. Instead of fetching and fanning out its individual tool definitions, you can point a MAF `MCPStreamableHTTPTool` at the toolbox's MCP endpoint — the agent then discovers and calls its tools over MCP at runtime:
Each toolbox is reachable as an MCP server. Connect to the toolbox's MCP endpoint with `MCPStreamableHTTPTool` — the agent then discovers and calls its tools over MCP at runtime:
```python
from agent_framework import Agent, MCPStreamableHTTPTool
@@ -16,7 +16,6 @@ from ._foundry_evals import (
evaluate_traces,
)
from ._memory_provider import FoundryMemoryProvider
from ._tools import FoundryHostedToolType, get_toolbox_tool_name, get_toolbox_tool_type, select_toolbox_tools
try:
__version__ = importlib.metadata.version(__name__)
@@ -32,7 +31,6 @@ __all__ = [
"FoundryEmbeddingOptions",
"FoundryEmbeddingSettings",
"FoundryEvals",
"FoundryHostedToolType",
"FoundryMemoryProvider",
"RawFoundryAgent",
"RawFoundryAgentChatClient",
@@ -41,7 +39,4 @@ __all__ = [
"__version__",
"evaluate_foundry_target",
"evaluate_traces",
"get_toolbox_tool_name",
"get_toolbox_tool_type",
"select_toolbox_tools",
]
@@ -418,12 +418,6 @@ class RawFoundryAgentChatClient( # type: ignore[misc]
self,
tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None,
) -> list[Any]:
"""Prepare tools for Foundry agent Responses API calls.
Mirrors ``RawFoundryChatClient`` sanitization so toolbox-fetched MCP
tools with extra read-model fields continue to work through the agent
surface.
"""
response_tools = super()._prepare_tools_for_openai(tools)
return [_sanitize_foundry_response_tool(tool_item) for tool_item in response_tools]
@@ -16,7 +16,6 @@ from agent_framework import (
load_settings,
)
from agent_framework._compaction import CompactionStrategy, TokenizerProtocol
from agent_framework._feature_stage import ExperimentalFeature, experimental
from agent_framework._telemetry import get_user_agent
from agent_framework.observability import ChatTelemetryLayer
from agent_framework_openai._chat_client import OpenAIChatOptions, RawOpenAIChatClient
@@ -36,7 +35,7 @@ from azure.core.credentials_async import AsyncTokenCredential
from agent_framework_foundry._oauth_helpers import try_parse_oauth_consent_event
from ._tools import _sanitize_foundry_response_tool, fetch_toolbox # pyright: ignore[reportPrivateUsage]
from ._tools import _sanitize_foundry_response_tool # pyright: ignore[reportPrivateUsage]
if sys.version_info >= (3, 13):
from typing import TypeVar # type: ignore # pragma: no cover
@@ -53,7 +52,6 @@ else:
if TYPE_CHECKING:
from agent_framework import ChatAndFunctionMiddlewareTypes, ToolTypes
from azure.ai.projects.models import ToolboxVersionObject
logger: logging.Logger = logging.getLogger("agent_framework.foundry")
@@ -234,13 +232,6 @@ class RawFoundryChatClient( # type: ignore[misc]
self,
tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None,
) -> list[Any]:
"""Prepare tools for Foundry Responses API calls.
Foundry toolbox reads can surface MCP tool objects with extra fields
(for example ``name``) that are accepted by the toolbox API but rejected
by the Responses API. Sanitize those hosted-tool payloads before sending
them downstream.
"""
response_tools = super()._prepare_tools_for_openai(tools)
return [_sanitize_foundry_response_tool(tool_item) for tool_item in response_tools]
@@ -510,37 +501,6 @@ class RawFoundryChatClient( # type: ignore[misc]
# endregion
# region Toolbox methods (instance methods — these hit the network)
@experimental(feature_id=ExperimentalFeature.TOOLBOXES)
async def get_toolbox(
self,
name: str,
*,
version: str | None = None,
) -> ToolboxVersionObject:
"""Fetch a Foundry toolbox by name.
If ``version`` is omitted, resolves the toolbox's current default version
(two requests). If ``version`` is specified, fetches that version directly
(single request).
Args:
name: The name of the toolbox.
Keyword Args:
version: Optional immutable version identifier to pin to.
Returns:
A ``ToolboxVersionObject``. Pass its ``tools`` attribute to
``Agent(tools=toolbox.tools)``.
Raises:
azure.core.exceptions.ResourceNotFoundError: If the toolbox or
the requested version does not exist.
"""
return await fetch_toolbox(self.project_client, name, version)
class FoundryChatClient( # type: ignore[misc]
FunctionInvocationLayer[FoundryChatOptionsT],
@@ -2,179 +2,54 @@
"""Shared tool helpers for Foundry chat clients.
Includes:
* *Toolbox* helpers — a *toolbox* is a named, versioned bundle of tool
definitions stored in an Azure AI Foundry project.
* Responses-API payload sanitization for Foundry hosted tools.
Includes Responses-API payload sanitization for Foundry hosted tools.
"""
from __future__ import annotations
from collections.abc import Callable, Collection, Mapping, Sequence
from typing import TYPE_CHECKING, Any, Literal, TypeAlias, cast
from collections.abc import Mapping
from typing import Any, cast
from agent_framework._feature_stage import ExperimentalFeature, experimental
from azure.ai.projects.models import MCPTool as FoundryMCPTool
if TYPE_CHECKING:
from azure.ai.projects.aio import AIProjectClient
from azure.ai.projects.models import Tool, ToolboxVersionObject
FoundryHostedToolType: TypeAlias = (
Literal[
"code_interpreter",
"file_search",
"image_generation",
"mcp",
"web_search",
]
| str
)
ToolboxToolSelectionInput: TypeAlias = "ToolboxVersionObject | Sequence[Tool | dict[str, Any]]"
@experimental(feature_id=ExperimentalFeature.TOOLBOXES)
async def fetch_toolbox(
project_client: AIProjectClient,
name: str,
version: str | None = None,
) -> ToolboxVersionObject:
"""Fetch a toolbox version via an ``AIProjectClient``.
If ``version`` is omitted, resolves the toolbox's current default
version (two requests: one to ``.get(name)`` for the default version
pointer, one to ``.get_version(name, version)`` for the tools). If
``version`` is specified, fetches that version directly (single request).
"""
if version is None:
handle = await project_client.beta.toolboxes.get(name)
version = handle.default_version
return await project_client.beta.toolboxes.get_version(name, version)
@experimental(feature_id=ExperimentalFeature.TOOLBOXES)
def get_toolbox_tool_name(tool: Tool | dict[str, Any]) -> str | None:
"""Return the best-effort display/selection name for a toolbox tool.
Selection precedence:
1. MCP ``server_label``
2. Generic tool ``name``
3. Tool ``type``
"""
if isinstance(tool, dict):
if server_label := tool.get("server_label"):
return str(server_label)
if name := tool.get("name"):
return str(name)
if tool_type := tool.get("type"):
return str(tool_type)
return None
if server_label := getattr(tool, "server_label", None):
return str(server_label)
if name := getattr(tool, "name", None):
return str(name)
if tool_type := getattr(tool, "type", None):
return str(tool_type)
return None
@experimental(feature_id=ExperimentalFeature.TOOLBOXES)
def get_toolbox_tool_type(tool: Tool | dict[str, Any]) -> str | None:
"""Return the raw tool ``type`` if present."""
tool_type = tool.get("type") if isinstance(tool, dict) else getattr(tool, "type", None)
return str(tool_type) if tool_type is not None else None
@experimental(feature_id=ExperimentalFeature.TOOLBOXES)
def select_toolbox_tools(
tools: ToolboxToolSelectionInput,
*,
include_names: Collection[str] | None = None,
exclude_names: Collection[str] | None = None,
include_types: Collection[FoundryHostedToolType] | None = None,
exclude_types: Collection[FoundryHostedToolType] | None = None,
predicate: Callable[[Tool | dict[str, Any]], bool] | None = None,
) -> list[Tool | dict[str, Any]]:
"""Filter toolbox tools by normalized name, raw type, and/or predicate.
Normalized name precedence:
1. ``server_label`` for MCP tools
2. ``name``
3. ``type``
"""
tool_items: Sequence[Tool | dict[str, Any]] = (
tools if isinstance(tools, Sequence) else cast("Sequence[Tool | dict[str, Any]]", tools.tools)
)
include_name_set = {str(item) for item in include_names} if include_names is not None else None
exclude_name_set = {str(item) for item in exclude_names} if exclude_names is not None else None
include_type_set = {str(item) for item in include_types} if include_types is not None else None
exclude_type_set = {str(item) for item in exclude_types} if exclude_types is not None else None
selected: list[Tool | dict[str, Any]] = []
for tool in tool_items:
tool_name = get_toolbox_tool_name(tool)
tool_type = get_toolbox_tool_type(tool)
if include_name_set is not None and tool_name not in include_name_set:
continue
if exclude_name_set is not None and tool_name in exclude_name_set:
continue
if include_type_set is not None and tool_type not in include_type_set:
continue
if exclude_type_set is not None and tool_type in exclude_type_set:
continue
if predicate is not None and not predicate(tool):
continue
selected.append(tool)
return selected
def _validate_hosted_tool_payload(sanitized: Mapping[str, Any]) -> None:
"""Fail fast on hosted tool payloads that would always be rejected by the Responses API.
These mismatches are not injectable defaults — the caller must supply the
missing information — so surfacing a clear error here points at the toolbox
missing information — so surfacing a clear error here points at the tool
definition instead of letting the API return a generic 400.
"""
tool_type = sanitized.get("type")
if tool_type == "file_search" and not sanitized.get("vector_store_ids"):
raise ValueError(
"'file_search' tool is missing required 'vector_store_ids'. "
"If this came from a Foundry toolbox, update the toolbox definition "
"to include at least one vector store ID."
"Update the tool definition to include at least one vector store ID."
)
if tool_type == "mcp" and not sanitized.get("server_url") and not sanitized.get("project_connection_id"):
raise ValueError(
"'mcp' tool is missing both 'server_url' and 'project_connection_id'. "
"If this came from a Foundry toolbox, update the toolbox definition "
"to include one of these."
"Update the tool definition to include one of these."
)
def _sanitize_foundry_response_tool(tool_item: Any) -> Any: # pyright: ignore[reportUnusedFunction]
"""Return a Responses-API-safe tool payload for Foundry hosted tools.
Reconciles known mismatches between toolbox reads and the Responses API:
Reconciles known mismatches between hosted tool definitions and the Responses API:
1. Toolbox reads can return hosted tool objects decorated with read-model
fields such as top-level ``name`` and ``description``. The Responses API
rejects at least ``name`` with ``Unknown parameter: 'tools[0].name'``.
These fields are stripped from non-function hosted tool payloads.
2. ``code_interpreter`` tools stored in a toolbox without a ``container``
field (the Azure SDK treats it as optional) are rejected by the Responses
API with ``Missing required parameter: 'tools[N].container'``. A default
1. Hosted tool objects may carry read-model fields such as top-level ``name``
and ``description``. The Responses API rejects at least ``name`` with
``Unknown parameter: 'tools[0].name'``. These fields are stripped from
non-function hosted tool payloads.
2. ``code_interpreter`` tools without a ``container`` field (the Azure SDK
treats it as optional) are rejected by the Responses API with
``Missing required parameter: 'tools[N].container'``. A default
``{"type": "auto"}`` container is injected when absent.
3. Hosted tools that are structurally incomplete in ways that cannot be
defaulted (``file_search`` without ``vector_store_ids``, ``mcp`` without
either ``server_url`` or ``project_connection_id``) raise ``ValueError``
with a message that points at the toolbox definition.
These are workarounds until the toolbox/Responses proxy normalizes payloads
server-side.
with a message that points at the tool definition.
"""
if isinstance(tool_item, FoundryMCPTool):
sanitized: dict[str, Any] = dict(cast("Mapping[str, Any]", tool_item))
@@ -641,8 +641,8 @@ def test_prepare_tools_for_openai_strips_extraneous_name_from_foundry_mcp_tool()
assert "name" not in prepared
def test_prepare_tools_for_openai_strips_read_model_fields_from_toolbox_code_interpreter() -> None:
"""Toolbox-returned code interpreter tools may carry read-model-only name/description."""
def test_prepare_tools_for_openai_strips_read_model_fields_from_hosted_code_interpreter() -> None:
"""Hosted code interpreter tools may carry read-model-only name/description."""
project_client = MagicMock()
project_client.get_openai_client.return_value = _make_mock_openai_client()
client = FoundryChatClient(project_client=project_client, model="test-model")
@@ -650,7 +650,7 @@ def test_prepare_tools_for_openai_strips_read_model_fields_from_toolbox_code_int
tool = {
"type": "code_interpreter",
"name": "code_interpreter_t6bbtm",
"description": "Toolbox read model description",
"description": "Hosted tool read model description",
"container": {"file_ids": [], "type": "auto"},
}
@@ -665,7 +665,7 @@ def test_prepare_tools_for_openai_strips_read_model_fields_from_toolbox_code_int
def test_prepare_tools_for_openai_injects_default_container_for_code_interpreter_dict() -> None:
"""Toolbox-returned code_interpreter without a container must get a default injected.
"""Hosted code_interpreter without a container must get a default injected.
The Azure SDK treats ``container`` as optional, but the Responses API rejects
``code_interpreter`` entries without one. The sanitizer backfills ``{"type": "auto"}``.
@@ -691,7 +691,7 @@ def test_prepare_tools_for_openai_injects_default_container_for_code_interpreter
def test_prepare_tools_for_openai_injects_default_container_for_code_interpreter_sdk_instance() -> None:
"""SDK ``CodeInterpreterTool`` instances without a container must also be backfilled.
Reproduces the toolbox creation path that calls
Reproduces the hosted tool creation path that calls
``CodeInterpreterTool(name="code_interpreter")`` without a container.
"""
from azure.ai.projects.models import CodeInterpreterTool
@@ -771,13 +771,13 @@ def test_prepare_tools_for_openai_strips_name_from_non_function_hosted_tool_dict
{
"type": "file_search",
"name": "file_search_tool_123",
"description": "toolbox decoration",
"description": "hosted tool decoration",
"vector_store_ids": ["vs_123"],
},
{
"type": "web_search",
"name": "web_search_tool_456",
"description": "toolbox decoration",
"description": "hosted tool decoration",
},
])
@@ -1,435 +0,0 @@
# Copyright (c) Microsoft. All rights reserved.
"""Unit tests for toolbox helpers on FoundryChatClient.
Return types are the raw azure-ai-projects SDK models (ToolboxVersionObject,
ToolboxObject) — no custom wrapper. Tests verify the chat-client get path and
tool-selection ergonomics.
"""
from __future__ import annotations
import datetime as dt
import os
from typing import Any
from unittest.mock import AsyncMock, MagicMock
import pytest
try:
from azure.ai.projects.models import (
AutoCodeInterpreterToolParam,
CodeInterpreterTool,
Tool,
ToolboxObject,
ToolboxVersionObject,
)
except ImportError:
pytest.skip(
"Toolbox types require azure-ai-projects>=2.1.0 (unreleased).",
allow_module_level=True,
)
from azure.core.exceptions import ResourceNotFoundError
from azure.identity import AzureCliCredential
# --------------------------------------------------------------------------- #
# Helpers #
# --------------------------------------------------------------------------- #
class _AsyncIter:
"""Minimal async-iterable for mocking ``AsyncItemPaged`` in tests."""
def __init__(self, items: list[Any]) -> None:
self._items = items
def __aiter__(self) -> _AsyncIter:
self._iter = iter(self._items)
return self
async def __anext__(self) -> Any:
try:
return next(self._iter)
except StopIteration:
raise StopAsyncIteration from None
def _make_code_interpreter() -> CodeInterpreterTool:
return CodeInterpreterTool(container=AutoCodeInterpreterToolParam())
def _make_version_object(
*,
name: str = "research_tools",
version: str = "v1",
tools: list[Tool] | None = None,
description: str | None = None,
) -> ToolboxVersionObject:
return ToolboxVersionObject(
id=f"tbv_{name}_{version}",
name=name,
version=version,
metadata={},
created_at=dt.datetime(2026, 4, 10, tzinfo=dt.timezone.utc),
tools=tools if tools is not None else [_make_code_interpreter()],
description=description,
)
def _make_mock_foundry_client(*, project_client: MagicMock) -> Any:
"""Build a FoundryChatClient wired to a mock project_client."""
from agent_framework_foundry import FoundryChatClient
project_client.get_openai_client = MagicMock(return_value=MagicMock())
return FoundryChatClient(project_client=project_client, model="test-model")
# --------------------------------------------------------------------------- #
# get_toolbox — explicit version path #
# --------------------------------------------------------------------------- #
async def test_get_toolbox_with_explicit_version_makes_single_request() -> None:
project_client = MagicMock()
version_obj = _make_version_object(name="research_tools", version="v3")
project_client.beta.toolboxes.get_version = AsyncMock(return_value=version_obj)
project_client.beta.toolboxes.get = AsyncMock(
side_effect=AssertionError("get() must not be called when version is explicit")
)
client = _make_mock_foundry_client(project_client=project_client)
toolbox = await client.get_toolbox("research_tools", version="v3")
assert isinstance(toolbox, ToolboxVersionObject)
assert toolbox.name == "research_tools"
assert toolbox.version == "v3"
project_client.beta.toolboxes.get_version.assert_awaited_once_with("research_tools", "v3")
project_client.beta.toolboxes.get.assert_not_called()
# --------------------------------------------------------------------------- #
# get_toolbox — default-version path + error + passthrough + smoke #
# --------------------------------------------------------------------------- #
async def test_get_toolbox_default_version_resolves_then_fetches() -> None:
project_client = MagicMock()
handle = ToolboxObject(id="tb_1", name="research_tools", default_version="v5")
version_obj = _make_version_object(name="research_tools", version="v5")
project_client.beta.toolboxes.get = AsyncMock(return_value=handle)
project_client.beta.toolboxes.get_version = AsyncMock(return_value=version_obj)
client = _make_mock_foundry_client(project_client=project_client)
toolbox = await client.get_toolbox("research_tools")
assert toolbox.version == "v5"
project_client.beta.toolboxes.get.assert_awaited_once_with("research_tools")
project_client.beta.toolboxes.get_version.assert_awaited_once_with("research_tools", "v5")
async def test_get_toolbox_propagates_resource_not_found() -> None:
project_client = MagicMock()
project_client.beta.toolboxes.get = AsyncMock(side_effect=ResourceNotFoundError("no such toolbox"))
client = _make_mock_foundry_client(project_client=project_client)
with pytest.raises(ResourceNotFoundError):
await client.get_toolbox("missing_toolbox")
async def test_get_toolbox_tool_passthrough_preserves_heterogeneous_types() -> None:
"""Ensure all Tool subclasses pass through unchanged — critical for MCP tools
with project_connection_id, which must reach the runtime untouched."""
from azure.ai.projects.models import MCPTool as FoundryMCPTool
mcp_tool = FoundryMCPTool(
server_label="github_oauth",
server_url="https://api.githubcopilot.com/mcp",
)
mcp_tool["project_connection_id"] = "conn_abc"
project_client = MagicMock()
version_obj = _make_version_object(
name="mixed",
version="v1",
tools=[_make_code_interpreter(), mcp_tool],
)
project_client.beta.toolboxes.get_version = AsyncMock(return_value=version_obj)
client = _make_mock_foundry_client(project_client=project_client)
toolbox = await client.get_toolbox("mixed", version="v1")
assert len(toolbox.tools) == 2
assert isinstance(toolbox.tools[0], CodeInterpreterTool)
assert isinstance(toolbox.tools[1], FoundryMCPTool)
assert toolbox.tools[1]["project_connection_id"] == "conn_abc"
async def test_toolbox_tools_can_be_passed_to_agent() -> None:
"""Integration smoke: toolbox.tools can be passed directly to Agent(tools=...) ."""
from agent_framework import Agent
project_client = MagicMock()
version_obj = _make_version_object(name="research_tools", version="v1", tools=[_make_code_interpreter()])
project_client.beta.toolboxes.get_version = AsyncMock(return_value=version_obj)
client = _make_mock_foundry_client(project_client=project_client)
toolbox = await client.get_toolbox("research_tools", version="v1")
agent = Agent(
client=client,
instructions="You are a test agent.",
tools=toolbox.tools,
)
agent_tools = agent.default_options["tools"]
assert len(agent_tools) == 1
assert agent_tools[0]["type"] == "code_interpreter"
async def test_multiple_toolbox_tool_lists_can_be_combined_in_agent() -> None:
"""Nested toolbox ``.tools`` lists flatten into one tool list on Agent construction."""
from agent_framework import Agent
project_client = MagicMock()
project_client.get_openai_client = MagicMock(return_value=MagicMock())
client = _make_mock_foundry_client(project_client=project_client)
toolbox_a = _make_version_object(name="research_tools", version="v1", tools=[_make_code_interpreter()])
toolbox_b = _make_version_object(name="some_other_tools", version="v3", tools=[_make_code_interpreter()])
agent = Agent(
client=client,
instructions="You are a test agent.",
tools=[toolbox_a.tools, toolbox_b.tools],
)
agent_tools = agent.default_options["tools"]
assert len(agent_tools) == 2
assert agent_tools[0]["type"] == "code_interpreter"
assert agent_tools[1]["type"] == "code_interpreter"
# --------------------------------------------------------------------------- #
# toolbox tool selection helpers #
# --------------------------------------------------------------------------- #
def test_get_toolbox_tool_name_prefers_server_label_then_name_then_type() -> None:
from azure.ai.projects.models import MCPTool as FoundryMCPTool
from agent_framework_foundry import get_toolbox_tool_name
mcp_tool = FoundryMCPTool(
server_label="githubmcp",
server_url="https://api.githubcopilot.com/mcp",
)
assert get_toolbox_tool_name(mcp_tool) == "githubmcp"
named_tool = {"type": "code_interpreter", "name": "ci_tool"}
assert get_toolbox_tool_name(named_tool) == "ci_tool"
unnamed_tool = {"type": "web_search"}
assert get_toolbox_tool_name(unnamed_tool) == "web_search"
def test_select_toolbox_tools_filters_by_names() -> None:
from azure.ai.projects.models import MCPTool as FoundryMCPTool
from agent_framework_foundry import select_toolbox_tools
tools: list[Tool | dict[str, Any]] = [
FoundryMCPTool(server_label="githubmcp", server_url="https://api.githubcopilot.com/mcp"),
{"type": "code_interpreter", "name": "python_runner"},
{"type": "web_search"},
]
selected = select_toolbox_tools(tools, include_names=["githubmcp", "python_runner"])
assert len(selected) == 2
assert selected[0] is tools[0]
assert selected[1] is tools[1]
def test_select_toolbox_tools_filters_by_typed_tool_types() -> None:
from agent_framework_foundry import select_toolbox_tools
tools: list[Tool | dict[str, Any]] = [
{"type": "mcp", "server_label": "githubmcp"},
{"type": "code_interpreter", "name": "python_runner"},
{"type": "web_search"},
]
selected = select_toolbox_tools(tools, include_types=["mcp", "code_interpreter"])
assert len(selected) == 2
assert selected[0]["type"] == "mcp"
assert selected[1]["type"] == "code_interpreter"
def test_select_toolbox_tools_accepts_toolbox_object_directly() -> None:
from agent_framework_foundry import select_toolbox_tools
toolbox = _make_version_object(
name="research_tools",
version="v1",
tools=[
{"type": "mcp", "server_label": "githubmcp"}, # type: ignore[list-item]
{"type": "code_interpreter", "name": "python_runner"}, # type: ignore[list-item]
{"type": "web_search"}, # type: ignore[list-item]
],
)
selected = select_toolbox_tools(toolbox, include_types=["mcp", "code_interpreter"])
assert len(selected) == 2
assert selected[0]["type"] == "mcp"
assert selected[1]["type"] == "code_interpreter"
async def test_fetched_toolbox_can_be_combined_with_function_tool() -> None:
from agent_framework import Agent, FunctionTool, tool
project_client = MagicMock()
version_obj = _make_version_object(name="research_tools", version="v1", tools=[_make_code_interpreter()])
project_client.beta.toolboxes.get_version = AsyncMock(return_value=version_obj)
client = _make_mock_foundry_client(project_client=project_client)
toolbox = await client.get_toolbox("research_tools", version="v1")
@tool(name="local_lookup", description="A local helper tool")
def local_lookup(query: str) -> str:
return query
agent = Agent(
client=client,
instructions="You are a test agent.",
tools=[toolbox, local_lookup],
)
agent_tools = agent.default_options["tools"]
assert len(agent_tools) == 2
assert agent_tools[0]["type"] == "code_interpreter"
assert isinstance(agent_tools[1], FunctionTool)
assert agent_tools[1].name == "local_lookup"
def test_select_toolbox_tools_supports_excludes_and_predicate() -> None:
from agent_framework_foundry import select_toolbox_tools
tools: list[Tool | dict[str, Any]] = [
{"type": "mcp", "server_label": "githubmcp"},
{"type": "mcp", "server_label": "learnmcp"},
{"type": "web_search"},
]
selected = select_toolbox_tools(
tools,
exclude_names=["learnmcp"],
predicate=lambda tool: tool.get("type") == "mcp", # type: ignore[union-attr]
)
assert len(selected) == 1
assert selected[0]["server_label"] == "githubmcp"
async def test_selected_toolbox_subset_can_be_combined_with_function_tool() -> None:
from agent_framework import Agent, FunctionTool, tool
from agent_framework_foundry import select_toolbox_tools
project_client = MagicMock()
version_obj = _make_version_object(
name="research_tools",
version="v1",
tools=[
{"type": "mcp", "server_label": "githubmcp"}, # type: ignore[list-item]
{"type": "code_interpreter", "name": "python_runner"}, # type: ignore[list-item]
{"type": "web_search"}, # type: ignore[list-item]
],
)
project_client.beta.toolboxes.get_version = AsyncMock(return_value=version_obj)
client = _make_mock_foundry_client(project_client=project_client)
toolbox = await client.get_toolbox("research_tools", version="v1")
selected_tools = select_toolbox_tools(toolbox, include_types=["mcp", "code_interpreter"])
@tool(name="local_lookup", description="A local helper tool")
def local_lookup(query: str) -> str:
return query
agent = Agent(
client=client,
instructions="You are a test agent.",
tools=[selected_tools, local_lookup],
)
agent_tools = agent.default_options["tools"]
assert len(agent_tools) == 3
assert agent_tools[0]["type"] == "mcp"
assert agent_tools[1]["type"] == "code_interpreter"
assert isinstance(agent_tools[2], FunctionTool)
assert agent_tools[2].name == "local_lookup"
# --------------------------------------------------------------------------- #
# Integration #
# --------------------------------------------------------------------------- #
skip_if_foundry_integration_tests_disabled = pytest.mark.skipif(
os.getenv("FOUNDRY_PROJECT_ENDPOINT", "") in ("", "https://test-project.services.ai.azure.com/")
or os.getenv("FOUNDRY_MODEL", "") == "",
reason="No real FOUNDRY_PROJECT_ENDPOINT or FOUNDRY_MODEL provided; skipping integration tests.",
)
@pytest.mark.flaky
@pytest.mark.integration
@skip_if_foundry_integration_tests_disabled
async def test_integration_get_toolbox_round_trip_against_real_project() -> None:
"""Create a toolbox via the raw SDK, fetch via FoundryChatClient, then delete.
Self-contained to avoid depending on toolboxes that may be cleaned up
externally. Exercises both the default-version resolution path
(``get`` + ``get_version``) and the explicit-version path.
"""
from uuid import uuid4
from agent_framework import Agent
from agent_framework_foundry import FoundryChatClient
client = FoundryChatClient(credential=AzureCliCredential())
project_client = client.project_client
toolbox_name = f"af-int-toolbox-{uuid4().hex[:12]}"
created = await project_client.beta.toolboxes.create_version(
name=toolbox_name,
tools=[CodeInterpreterTool()],
description=f"{toolbox_name} integration test",
)
assert isinstance(created, ToolboxVersionObject)
try:
toolbox_default = await client.get_toolbox(toolbox_name)
assert toolbox_default.name == toolbox_name
assert toolbox_default.tools, "Default-version fetch returned no tools"
toolbox_pinned = await client.get_toolbox(toolbox_name, version=created.version)
assert toolbox_pinned.version == created.version
assert toolbox_pinned.tools
agent = Agent(
client=client,
instructions="You are a test agent.",
tools=toolbox_pinned.tools,
)
assert len(agent.default_options["tools"]) == len(toolbox_pinned.tools)
finally:
await project_client.beta.toolboxes.delete(toolbox_name)