Microsoft Foundry Toolbox

Verknüpfen Sie bei einer dienstverwalteten FoundryAgent die Toolbox mit der Agentdefinition in Foundry.

Verwenden Sie für einen gehosteten Agent, der mit Microsoft Agent Framework erstellt wurde, AddFoundryToolboxes aus Microsoft.Agents.AI.Foundry.Hosting, wie im folgenden Beispiel dargestellt.

Verwenden Sie ein .NET 10-Webprojekt mit aktivierten impliziten Usings sowie übereinstimmenden Versionen von Microsoft.Agents.AI.Foundry, Microsoft.Agents.AI.Foundry.Hosting und DotNetEnv. Setzen Sie TOOLBOX_NAME auf eine vorhandene Toolbox und FOUNDRY_MODEL auf Ihre Modellbereitstellung. Foundry liefert FOUNDRY_PROJECT_ENDPOINT an den bereitgestellten Host. Für den lokalen Modellzugriff FOUNDRY_PROJECT_ENDPOINT festlegen und sich mit Azure CLI anmelden. Gehostete Deployments greifen auf das von azd verwaltete AZURE_AI_MODEL_DEPLOYMENT_NAME zurück. Die Hosting-Integration lädt Toolbox-Tools, wenn FOUNDRY_PROJECT_ENDPOINT verfügbar ist.

using DotNetEnv;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;

// Load .env file if present (for local development)
Env.TraversePath().Load();

string endpoint = System.Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string deploymentName = FirstNonBlank(
    System.Environment.GetEnvironmentVariable("FOUNDRY_MODEL"),
    System.Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME"),
    "gpt-4o")!;
string toolboxName = FirstNonBlank(
    System.Environment.GetEnvironmentVariable("TOOLBOX_NAME"),
    "my-toolset")!;

// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
// Use a chained credential: try a temporary dev token first (for local Docker debugging),
// then fall back to DefaultAzureCredential (for local dev via dotnet run / managed identity in production).
    .AsAIAgent(
        model: deploymentName,
            Use the available tools to answer user questions.
            If a tool is not available for a request, let the user know clearly.
            """,
        name: System.Environment.GetEnvironmentVariable("AGENT_NAME") ?? "hosted-toolbox-agent",
        description: "Hosted agent backed by Foundry Toolbox MCP tools");

// ── Build the host ────────────────────────────────────────────────────────────

var builder = WebApplication.CreateBuilder(args);

// Register the agent and response handler
// Register Foundry Toolbox: connects to the MCP proxy at startup and makes tools available.
// The toolbox name must match a toolbox registered in your Foundry project.
// When FOUNDRY_PROJECT_ENDPOINT is absent (e.g., in local development without Foundry
// infrastructure), startup succeeds without error and no toolbox tools are loaded.
builder.Services.AddFoundryToolboxes(credential, toolboxName);

app.Run();

static string? FirstNonBlank(params string?[] candidates) =>
    Array.Find(candidates, candidate => !string.IsNullOrWhiteSpace(candidate));

// ── DevTemporaryTokenCredential ───────────────────────────────────────────────

Die gleiche Hostingregistrierung unterstützt Tools, die für die OAuth-Zustimmung pro Benutzer für ihre Toolboxverbindungen konfiguriert sind. Benutzer benötigen weiterhin die erforderlichen Berechtigungen und Zustimmungen; Es ist kein separater Hostregistrierungsblock erforderlich.

Die Projektdateien und Bereitstellungsanweisungen finden Sie unter Hosted-Toolbox. Informationen zum Einrichten der Zustimmung pro Benutzer finden Sie unter Hosted-Toolbox-AuthPaths.

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 Hosted-Agent-Beispiele bevorzugen die lokale Variante FOUNDRY_MODEL und greifen bei einer gehosteten Bereitstellung auf den von azd verwalteten AZURE_AI_MODEL_DEPLOYMENT_NAME zurück.

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. Er löst Plattformheader an jeder Vorgangsgrenze auf und verbindet seine MCP-Sitzung erneut, wenn sich die effektive Anfrageidentität ändert. Eine langlebige Toolbox behält daher die Anruf-ID eines früheren Anrufers nicht bei.

Das Beispiel erstellt die Toolbox, den Client und die Anmeldedaten innerhalb der auf die Anfrage beschränkten Agentenfabrik, um eine deterministische Zuständigkeit und Bereinigung zu gewährleisten. Verwenden Sie dieses Factory-Muster, wenn zugehörige Ressourcen an eine Anfrage gebunden sind, dies jedoch nicht ausschließlich dazu dient, die Toolbox-Aufruf-IDs auf dem neuesten Stand zu halten.

import asyncio
import os
from contextlib import AsyncExitStack
from types import TracebackType

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient, FoundryToolbox
from agent_framework_foundry_hosting import ResponsesHostServer
from azure.ai.agentserver.core import AgentConfig, get_request_context
from azure.identity.aio import AzureCliCredential, ManagedIdentityCredential
from dotenv import load_dotenv


def create_agent() -> Agent:
    """Create request-owned SDK resources and close them with the agent."""
    endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    model = os.environ.get("FOUNDRY_MODEL") or os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
    credential = (
        ManagedIdentityCredential(client_id=os.environ.get("FOUNDRY_AGENT_INSTANCE_CLIENT_ID"))
        if AgentConfig.from_env().is_hosted
        else AzureCliCredential()
    )

    class RequestClient(FoundryChatClient):
        async def __aenter__(self) -> RequestClient:
            return self

        async def __aexit__(
            self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None
        ) -> None:
            async with AsyncExitStack() as cleanup:
                cleanup.push_async_callback(credential.close)
                cleanup.push_async_callback(self.project_client.close)
                cleanup.push_async_callback(self.client.close)

    toolbox = FoundryToolbox(credential)
    client = RequestClient(
        project_endpoint=endpoint,
        model=model,
        credential=credential,
        default_headers=get_request_context().platform_headers(),
    )
    return Agent(
        client=client,
        instructions="You are a friendly assistant. Keep your answers brief.",
        tools=toolbox,
    )


async def main() -> None:
    load_dotenv()
    server = ResponsesHostServer(agent=create_agent, history_source="agent_server")
    await server.run_async()

Wenn der „Toolbox Code Interpreter“ eine Datei erzeugt und die Assistentenantwort diese Datei benennt, gibt der gehostete „Responses“-Adapter eine native container_file_citation-Annotation mit den Container- und Datei-IDs aus. Responses-Clients können diese IDs verwenden, um die generierte Datei über die Containerdateien-API zu ermitteln und herunterzuladen.

Toolbox-Fähigkeiten verfügbar machen

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 contextlib import AsyncExitStack
from types import TracebackType

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient, FoundryToolbox
from agent_framework_foundry_hosting import ResponsesHostServer
from azure.ai.agentserver.core import AgentConfig, get_request_context
from azure.identity.aio import AzureCliCredential, ManagedIdentityCredential
from dotenv import load_dotenv


def create_agent() -> Agent:
    """Keep skill caches, credentials and the MCP lifecycle request-owned."""
    endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    model = os.environ.get("FOUNDRY_MODEL") or os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
    credential = (
        ManagedIdentityCredential(client_id=os.environ.get("FOUNDRY_AGENT_INSTANCE_CLIENT_ID"))
        if AgentConfig.from_env().is_hosted
        else AzureCliCredential()
    )

    class RequestClient(FoundryChatClient):
        async def __aenter__(self) -> RequestClient:
            return self

        async def __aexit__(
            self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None
        ) -> None:
            async with AsyncExitStack() as cleanup:
                cleanup.push_async_callback(credential.close)
                cleanup.push_async_callback(self.project_client.close)
                cleanup.push_async_callback(self.client.close)

    # tools= connects the MCP session; context_providers= reads skills from that same session.
    toolbox = FoundryToolbox(credential, load_tools=False)
    skills_provider = toolbox.as_skills_provider(disable_load_skill_approval=True)
    client = RequestClient(
        project_endpoint=endpoint,
        model=model,
        credential=credential,
        default_headers=get_request_context().platform_headers(),
    )
    return 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],
    )


async def main() -> None:
    load_dotenv()
    server = ResponsesHostServer(agent=create_agent, history_source="agent_server")
    await server.run_async()

Die Genehmigung bleibt standardmäßig für Skill-Vorgänge aktiviert. Deaktivieren Sie einzelne Genehmigungen nur für vertrauenswürdige, unbeaufsichtigte Szenarien. Halten Sie die Toolbox und deren Skillanbieter zusammen, sodass beide dieselbe MCP-Sitzung verwenden. Bei einer langlebigen Toolbox wird der Cache für die Fähigkeitserkennung ersetzt, wenn sich die effektive Platform-Header-Identität ändert. Ein benutzerdefinierter header_provider, der mit Skills verwendet wird, muss aus dem Umgebungszustand aufgelöst werden, z. B. aus einer Schließung oder ContextVar, da Lesezugriffe auf Skills und Ressourcen keine Funktionslaufzeitargumente erhalten.

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.

Verbinden über MCP mit FoundryToolbox

Verwenden Sie FoundryToolbox mit ResponsesHostServer, um einen gehosteten Agenten mit dem Toolbox-MCP-Endpunkt zu verbinden. Der Wrapper authentifiziert MCP-Anfragen und leitet den Aufruferkontext der aktuellen gehosteten Anfrage zur benutzerspezifischen Identitätsweitergabe weiter. Die anforderungsbezogene agent Factory bleibt die einfachste Option, wenn der Client, die Anmeldeinformationen und die Toolbox eine Bereinigungsgrenze benötigen. Eine langlebige Toolbox wird ebenfalls unterstützt und stellt vor einer Operation erneut eine Verbindung her, wenn sich die Identität des Plattform-Headers ändert.

import asyncio
import os
from contextlib import AsyncExitStack
from types import TracebackType

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient, FoundryToolbox
from agent_framework_foundry_hosting import ResponsesHostServer
from azure.ai.agentserver.core import AgentConfig, get_request_context
from azure.identity.aio import AzureCliCredential, ManagedIdentityCredential
from dotenv import load_dotenv


def create_agent() -> Agent:
    """Create request-owned SDK resources and close them with the agent."""
    endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    model = os.environ.get("FOUNDRY_MODEL") or os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
    credential = (
        ManagedIdentityCredential(client_id=os.environ.get("FOUNDRY_AGENT_INSTANCE_CLIENT_ID"))
        if AgentConfig.from_env().is_hosted
        else AzureCliCredential()
    )

    class RequestClient(FoundryChatClient):
        async def __aenter__(self) -> RequestClient:
            return self

        async def __aexit__(
            self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None
        ) -> None:
            async with AsyncExitStack() as cleanup:
                cleanup.push_async_callback(credential.close)
                cleanup.push_async_callback(self.project_client.close)
                cleanup.push_async_callback(self.client.close)

    toolbox = FoundryToolbox(credential)
    client = RequestClient(
        project_endpoint=endpoint,
        model=model,
        credential=credential,
        default_headers=get_request_context().platform_headers(),
    )
    return Agent(
        client=client,
        instructions="You are a friendly assistant. Keep your answers brief.",
        tools=toolbox,
    )


async def main() -> None:
    load_dotenv()
    server = ResponsesHostServer(agent=create_agent, history_source="agent_server")
    await server.run_async()

Legen Sie TOOLBOX_ENDPOINT fest oder legen Sie sowohl FOUNDRY_PROJECT_ENDPOINT als auch fest, wie in TOOLBOX_NAME beschrieben. Legen Sie FOUNDRY_MODEL für lokale Ausführungen fest; gehostete Bereitstellungen greifen auf die azd-verwalteten AZURE_AI_MODEL_DEPLOYMENT_NAME zurück.

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.