Microsoft Foundry Toolbox

Fügen Sie für eine vom Dienst verwaltete FoundryAgentToolbox die Toolbox an die Agentdefinition in Foundry an. Clientseitige .NET-Toolbox-Verbrauchsleitfaden sind derzeit nicht dokumentiert.

Installieren der Pakete

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

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

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 Agent verwenden AZURE_AI_MODEL_DEPLOYMENT_NAME auch für FoundryChatClient.

Verwenden FoundryToolbox mit einem gehosteten Agent

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. Legen Sie fest load_tools=False , wann nur Fähigkeiten modell sichtbar sein sollten, und fügen Sie die Toolbox als Tool hinzu, damit die MCP-Sitzung eine Verbindung herstellt und als Kontextanbieter verwendet wird as_skills_provider() .

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 einer Toolbox mit FoundryAgent

Fügen Sie die Toolbox an die Definition "Eingabeaufforderung" oder "Gehosteter Agent" in Foundry an. 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. Stellen Sie den Toolbox-Endpunkt und ein Entra ID Bearertoken ü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 auf niedrigerer Ebene verwendet FOUNDRY_TOOLBOX_ENDPOINT. Im Beispiel "Toolbox-Fähigkeiten" werden diese Beispiele verwendet FOUNDRY_TOOLBOX_MCP_SERVER_URL. Diese Namen gehören zu diesen Beispielen und sind von den FoundryToolbox Klassen TOOLBOX_ENDPOINT und TOOLBOX_NAME Einstellungen getrennt.

Einschränkungen

• MCP-Tools in einer Toolbox verwenden die serverseitige Authentifizierung über einen Foundry project_connection_id. Der Agent Framework-Client enthält nicht das upstream-MCP-Bearertoken.
• Die Verwendung einer Toolbox als MCP-Server erfordert clientseitige Entra ID Authentifizierung für den Toolboxendpunkt.
• Zustimmungsflussantworten, z CONSENT_REQUIRED . B. werden während der Ausführung des Agents behandelt, nicht während die Toolboxverbindung erstellt wird.

Samples

Go macht derzeit keine Findry Toolbox-Hilfsprogramm verfügbar. Konfigurieren Sie Toolboxen über Foundry und verwenden Sie unterstützte lokale oder gehostete Tooldeklarationen für Go-Agents.