agent-framework-foundry 1.2.1__tar.gz → 1.3.0__tar.gz

{agent_framework_foundry-1.2.1 → agent_framework_foundry-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-framework-foundry
-Version: 1.2.1
+Version: 1.3.0
 Summary: Microsoft Foundry integrations for Microsoft Agent Framework.
 Author-email: Microsoft <af-support@microsoft.com>
 Requires-Python: >=3.10
@@ -16,8 +16,8 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 License-File: LICENSE
-Requires-Dist: agent-framework-core>=1.2.1,<2
-Requires-Dist: agent-framework-openai>=1.1.0,<2
+Requires-Dist: agent-framework-core>=1.3.0,<2
+Requires-Dist: agent-framework-openai>=1.3.0,<2
 Requires-Dist: azure-ai-inference>=1.0.0b9,<1.0.0b10
 Requires-Dist: azure-ai-projects>=2.1.0,<3.0
 Project-URL: homepage, https://aka.ms/agent-framework
@@ -48,32 +48,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

{agent_framework_foundry-1.2.1 → agent_framework_foundry-1.3.0}/README.md

@@ -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

{agent_framework_foundry-1.2.1 → agent_framework_foundry-1.3.0}/agent_framework_foundry/__init__.py

@@ -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",
 ]

{agent_framework_foundry-1.2.1 → agent_framework_foundry-1.3.0}/agent_framework_foundry/_agent.py

@@ -135,6 +135,18 @@ def _uses_foundry_agent_session(conversation_id: Any) -> bool:
     )
 
 
+def _build_agent_reference(agent_name: str, agent_version: str | None) -> dict[str, str]:
+    """Build the Responses API ``agent_reference`` payload for non-preview Foundry agent calls.
+
+    Used for both Prompt Agents and HostedAgents on the ``allow_preview=False`` code path —
+    the preview branch instead injects identity via ``project_client.get_openai_client(agent_name=...)``.
+    """
+    ref: dict[str, str] = {"name": agent_name, "type": "agent_reference"}
+    if agent_version:
+        ref["version"] = agent_version
+    return ref
+
+
 class RawFoundryAgentChatClient(  # type: ignore[misc]
     RawOpenAIChatClient[FoundryAgentOptionsT],
     Generic[FoundryAgentOptionsT],
@@ -342,6 +354,12 @@ class RawFoundryAgentChatClient(  # type: ignore[misc]
             run_options.pop("previous_response_id", None)
             run_options.pop("conversation", None)
             extra_body["agent_session_id"] = conversation_id
+        # Non-preview Prompt/Hosted Agent calls need agent_reference in the request body to
+        # tell the Responses API which Foundry agent (and version) is in use, since ``model``
+        # is stripped below. The preview path injects the reference via the OpenAI client kwarg
+        # ``agent_name`` instead, so skip there. See issue #5582.
+        if not self.allow_preview:
+            extra_body.setdefault("agent_reference", _build_agent_reference(self.agent_name, self.agent_version))
         if extra_body:
             run_options["extra_body"] = extra_body
 
@@ -400,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]
 

{agent_framework_foundry-1.2.1 → agent_framework_foundry-1.3.0}/agent_framework_foundry/_chat_client.py

@@ -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],

agent_framework_foundry-1.3.0/agent_framework_foundry/_tools.py

@@ -0,0 +1,72 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Shared tool helpers for Foundry chat clients.
+
+Includes Responses-API payload sanitization for Foundry hosted tools.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, cast
+
+from azure.ai.projects.models import MCPTool as FoundryMCPTool
+
+
+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 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'. "
+            "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'. "
+            "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 hosted tool definitions and the Responses API:
+
+    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 tool definition.
+    """
+    if isinstance(tool_item, FoundryMCPTool):
+        sanitized: dict[str, Any] = dict(cast("Mapping[str, Any]", tool_item))
+        sanitized.pop("name", None)
+        sanitized.pop("description", None)
+        _validate_hosted_tool_payload(sanitized)
+        return sanitized
+
+    if isinstance(tool_item, Mapping):
+        mapping = cast("Mapping[str, Any]", tool_item)
+        if "type" in mapping and mapping.get("type") not in {"function", "custom"}:
+            sanitized = dict(mapping)
+            sanitized.pop("name", None)
+            sanitized.pop("description", None)
+            if sanitized.get("type") == "code_interpreter" and "container" not in sanitized:
+                sanitized["container"] = {"type": "auto"}
+            _validate_hosted_tool_payload(sanitized)
+            return sanitized
+
+    return cast(Any, tool_item)

{agent_framework_foundry-1.2.1 → agent_framework_foundry-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ description = "Microsoft Foundry integrations for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.2.1"
+version = "1.3.0"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,8 +23,8 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.2.1,<2",
-    "agent-framework-openai>=1.1.0,<2",
+    "agent-framework-core>=1.3.0,<2",
+    "agent-framework-openai>=1.3.0,<2",
     "azure-ai-inference>=1.0.0b9,<1.0.0b10",
     "azure-ai-projects>=2.1.0,<3.0",
 ]

agent_framework_foundry-1.2.1/agent_framework_foundry/_tools.py

@@ -1,197 +0,0 @@
-# Copyright (c) Microsoft. All rights reserved.
-
-"""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.
-"""
-
-from __future__ import annotations
-
-from collections.abc import Callable, Collection, Mapping, Sequence
-from typing import TYPE_CHECKING, Any, Literal, TypeAlias, 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
-    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."
-        )
-    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."
-        )
-
-
-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:
-
-    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
-       ``{"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.
-    """
-    if isinstance(tool_item, FoundryMCPTool):
-        sanitized: dict[str, Any] = dict(cast("Mapping[str, Any]", tool_item))
-        sanitized.pop("name", None)
-        sanitized.pop("description", None)
-        _validate_hosted_tool_payload(sanitized)
-        return sanitized
-
-    if isinstance(tool_item, Mapping):
-        mapping = cast("Mapping[str, Any]", tool_item)
-        if "type" in mapping and mapping.get("type") not in {"function", "custom"}:
-            sanitized = dict(mapping)
-            sanitized.pop("name", None)
-            sanitized.pop("description", None)
-            if sanitized.get("type") == "code_interpreter" and "container" not in sanitized:
-                sanitized["container"] = {"type": "auto"}
-            _validate_hosted_tool_payload(sanitized)
-            return sanitized
-
-    return cast(Any, tool_item)