Microsoft Foundry Toolbox

Verknüpfen Sie bei einer dienstverwalteten FoundryAgent die Toolbox mit der Agentdefinition in Foundry. Anleitungen zur clientseitigen Verwendung der .NET-Toolbox sind derzeit nicht dokumentiert.

Installieren der Pakete

pip install agent-framework-foundry-hosting agent-framework-foundry --pre

FoundryToolbox wird aus agent_framework.foundry importiert und von agent-framework-foundry-hosting bereitgestellt.

Konfigurieren der Toolbox

Festlegen eines expliziten Toolbox-MCP-Endpunkts:

TOOLBOX_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<name>/mcp?api-version=v1"

Oder lassen Sie FoundryToolbox den Endpunkt erstellen:

FOUNDRY_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
TOOLBOX_NAME="<toolbox-name>"

Die Beispiele für gehostete Agents verwenden ebenfalls AZURE_AI_MODEL_DEPLOYMENT_NAME für FoundryChatClient.

Verwenden Sie FoundryToolbox mit einem gehosteten Agenten

FoundryToolboxlöst seinen Endpunkt auf, authentifiziert jede MCP-Anforderung mit den bereitgestellten Azure Anmeldeinformationen, leitet die Foundry-Anruf-ID pro Anforderung weiter und nimmt am Verbindungslebenszyklus des Agents teil.

import asyncio
import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient, FoundryToolbox, ResponsesHostServer
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()


async def main():
    credential = DefaultAzureCredential()

    # FoundryToolbox resolves the toolbox endpoint from the environment
    # (TOOLBOX_ENDPOINT, or FOUNDRY_PROJECT_ENDPOINT + TOOLBOX_NAME), authenticates
    # every request with the credential, and transparently forwards the platform
    # per-request call-id to the toolbox. The hosting server enters the agent, which
    # connects the toolbox on first use and closes it at shutdown.
    toolbox = FoundryToolbox(credential)

    # Create the chat client
    client = FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
        credential=credential,
    )

    agent = Agent(
        client=client,
        instructions="You are a friendly assistant. Keep your answers brief.",
        tools=toolbox,
        # History will be managed by the hosting infrastructure, thus there
        # is no need to store history by the service. Learn more at:
        # https://developers.openai.com/api/reference/resources/responses/methods/create
        default_options={"store": False},
    )

    server = ResponsesHostServer(agent)
    await server.run_async()

Verfügbarmachen von Toolbox-Fähigkeiten

Eine Toolbox kann Agent-Fähigkeiten über MCP verfügbar machen. Setzen Sie load_tools=False, wenn nur Fähigkeiten für das Modell sichtbar sein sollen, fügen Sie dann die Toolbox als Tool hinzu, damit die MCP-Sitzung verbunden wird, und verwenden Sie as_skills_provider() als Kontextanbieter.

import asyncio
import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient, FoundryToolbox, ResponsesHostServer
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()


async def main() -> None:
    credential = DefaultAzureCredential()

    # FoundryToolbox resolves the toolbox endpoint from the environment
    # (TOOLBOX_ENDPOINT, or FOUNDRY_PROJECT_ENDPOINT + TOOLBOX_NAME), authenticates
    # every request with the credential, and forwards the platform per-request
    # call-id. ``load_tools=False`` keeps the toolbox's tools hidden so only its
    # Agent Skills (SEP-2640) are surfaced; passing it via ``tools=`` connects the
    # MCP session that ``as_skills_provider()`` reads from.
    toolbox = FoundryToolbox(credential, load_tools=False)

    # as_skills_provider() discovers skills from skill://index.json on the toolbox
    # MCP session and exposes them as an agent context provider; SKILL.md bodies are
    # fetched on demand via resources/read. disable_load_skill_approval=True registers
    # the load_skill tool with approval_mode="never_require" so this unattended agent
    # can load skills without an approval round-trip -- the Responses host runs the
    # agent without an AgentSession, which the default approval flow requires.
    skills_provider = toolbox.as_skills_provider(disable_load_skill_approval=True)

    client = FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
        credential=credential,
    )

    agent = Agent(
        client=client,
        name=os.environ.get("AGENT_NAME", "hosted-toolbox-mcp-skills"),
        instructions="You are a helpful assistant.",
        tools=toolbox,
        context_providers=[skills_provider],
        # History will be managed by the hosting infrastructure, thus there
        # is no need to store history by the service. Learn more at:
        # https://developers.openai.com/api/reference/resources/responses/methods/create
        default_options={"store": False},
    )

    server = ResponsesHostServer(agent)
    await server.run_async()

Die Genehmigung bleibt standardmäßig für Qualifikationsvorgänge aktiviert. Deaktivieren Sie einzelne Genehmigungen nur für vertrauenswürdige, unbeaufsichtigte Szenarien.

Verwenden Sie eine Toolbox mit FoundryAgent

Fügen Sie die Toolbox zur Prompt- oder Hosted-Agent-Definition in Foundry hinzu. FoundryAgent verwendet diese gespeicherte Toolkonfiguration; Das Übergeben einer clientseitigen Toolbox fügt sie nicht zum verwalteten Agent hinzu.

Herstellen einer Verbindung über unformatierte MCP

Verwenden Sie MCPStreamableHTTPTool direkt, wenn die Anwendung den FoundryToolbox Hostwrapper nicht verwendet. Übergeben Sie den Toolbox-Endpunkt und ein Entra ID-Bearer-Token über header_provider.

import asyncio
import os
from collections.abc import Callable
from typing import Any, cast

from agent_framework import Agent, MCPStreamableHTTPTool
from agent_framework.foundry import FoundryChatClient
from azure.core.credentials import TokenCredential
from azure.identity import AzureCliCredential, DefaultAzureCredential, get_bearer_token_provider
from dotenv import load_dotenv
def make_toolbox_header_provider(credential: TokenCredential) -> Callable[[dict[str, Any]], dict[str, str]]:
    """Build a header_provider that injects a fresh Azure AI bearer token on every MCP request."""
    get_token = get_bearer_token_provider(credential, "https://ai.azure.com/.default")

    def provide(_kwargs: dict[str, Any]) -> dict[str, str]:
        return {
            "Authorization": f"Bearer {get_token()}",
        }

    return provide


async def main() -> None:
    credential = DefaultAzureCredential()

    toolbox_tool = MCPStreamableHTTPTool(
        name="foundry_toolbox",
        description="Tools exposed by the configured Foundry toolbox",
        url=os.environ["FOUNDRY_TOOLBOX_ENDPOINT"],
        header_provider=make_toolbox_header_provider(credential),
        load_prompts=False,
    )

    async with Agent(
        client=FoundryChatClient(
            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            model=os.environ["FOUNDRY_MODEL"],
            credential=credential,
        ),
        instructions="You are a helpful assistant. Use the available toolbox tools to answer the user.",
        tools=toolbox_tool,
    ) as agent:
        query = "What tools do you have access to?"
        print(f"User: {query}")
        result = await agent.run(query)
        print(f"Assistant: {result}")

Das Beispiel der unteren Ebene verwendet FOUNDRY_TOOLBOX_ENDPOINT. Das Beispiel für Toolbox-Funktionen verwendet FOUNDRY_TOOLBOX_MCP_SERVER_URL; diese Namen gehören zu diesen Beispielen und sind von den Einstellungen TOOLBOX_ENDPOINT und TOOLBOX_NAME der Klasse FoundryToolbox getrennt.

Einschränkungen

• MCP-Tools innerhalb einer Toolbox verwenden die serverseitige Authentifizierung über eine Foundry project_connection_id; der Agent-Framework-Client verfügt nicht über das Upstream-MCP-Bearer-Token.
• Die Nutzung einer Toolbox als MCP-Server erfordert eine clientseitige Entra-ID-Authentifizierung für den Toolbox-Endpunkt.
• Antworten im Zustimmungsablauf wie z. B. CONSENT_REQUIRED werden verarbeitet, während der Agent ausgeführt wird, nicht beim Erstellen der Toolbox-Verbindung.

Samples

Go stellt derzeit keine Hilfsfunktion für die Foundry Toolbox bereit. Konfigurieren Sie Toolboxen über Foundry und verwenden Sie unterstützte lokale oder gehostete Tooldeklarationen für Go-Agents.