Microsoft Foundry Toolbox

Een Microsoft Foundry Toolbox is een benoemde, geversioneerde bundel aan serverzijde van gehoste toolconfiguraties, zoals code-interpreter, bestandszoekfunctie, afbeeldingsgeneratie, MCP en zoeken op het web. Met werksets kunt u de configuratie van hulpprogramma's eenmaal beheren in Foundry en deze opnieuw gebruiken tussen agents.

Agent Framework ondersteunt het gebruik van Toolbox. Werksetversies maken en bijwerken via de Foundry-portal of de azure-ai-projects SDK.

Belangrijk

FoundryToolbox wordt geleverd door het bètapakket agent-framework-foundry-hosting en kan worden gewijzigd vóór stabiele release.

Voor een door een service beheerde FoundryAgent, koppelt u de Toolbox aan de agentdefinitie in Foundry.

Gebruik AddFoundryToolboxes van Microsoft.Agents.AI.Foundry.Hosting voor een gehoste agent die is gebouwd met Microsoft Agent Framework, zoals in het volgende voorbeeld.

Gebruik een .NET 10-webproject met impliciet gebruik ingeschakeld, overeenkomende versies van Microsoft.Agents.AI.Foundry en Microsoft.Agents.AI.Foundry.Hostingen DotNetEnv. Stel TOOLBOX_NAME in op een bestaande toolbox en FOUNDRY_MODEL op uw modelimplementatie. Foundry levert FOUNDRY_PROJECT_ENDPOINT aan de geïmplementeerde host. Stel FOUNDRY_PROJECT_ENDPOINT in en meld u aan met Azure CLI voor lokale modeltoegang. Gehoste implementaties vallen terug op de door azd beheerde AZURE_AI_MODEL_DEPLOYMENT_NAME. De hostintegratie laadt de hulpmiddelen in de toolbox wanneer FOUNDRY_PROJECT_ENDPOINT beschikbaar is.

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

Dezelfde hostingregistratie ondersteunt hulpprogramma's die zijn geconfigureerd voor OAuth-toestemming per gebruiker voor hun werksetverbindingen. Gebruikers hebben nog steeds de vereiste machtigingen en toestemming nodig; er is geen afzonderlijk hostregistratieblok nodig.

Zie Hosted-Toolbox voor de projectbestanden en implementatie-instructies. Zie Hosted-Toolbox-AuthPaths voor het instellen van toestemming per gebruiker.

De pakketten installeren

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

FoundryToolbox wordt geïmporteerd uit agent_framework.foundry en geleverd door agent-framework-foundry-hosting.

Toolbox configureren

Stel een expliciet Toolbox MCP-eindpunt in:

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

Of laat FoundryToolbox het eindpunt samenstellen:

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

De voorbeelden van gehoste agents geven de voorkeur FOUNDRY_MODEL aan lokaal en vallen terug op de azd-managed AZURE_AI_MODEL_DEPLOYMENT_NAME wanneer deze worden gehost.

Gebruik `FoundryToolbox` met een gehoste agent

FoundryToolboxlost het eindpunt op, verifieert elke MCP-aanvraag met de opgegeven Azure-referentie, stuurt de aanroep-id van Foundry per aanvraag door en neemt deel aan de levenscyclus van de verbinding van de agent. Het lost platformheaders op bij elke operatiegrens en verbindt de MCP-sessie opnieuw wanneer de effectieve aanvraagidentiteit verandert. Een Toolbox met een lange levensduur behoudt daarom de oproep-id van een eerdere beller niet.

In het voorbeeld worden de Toolbox, client en referenties gemaakt in de agentfactory met aanvraagbereik voor deterministische eigendom en opschoning. Gebruik dit factory-patroon wanneer gerelateerde resources eigendom zijn van de aanvraag, maar het is niet alleen vereist om de Toolbox-aanroep-ID's actueel te houden.

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()

Wanneer Toolbox Code Interpreter een bestand produceert en het antwoord van de assistent dat bestand noemt, verzendt de gehoste antwoordadapter een systeemeigen container_file_citation aantekening met de container- en bestands-id's. Responses-clients kunnen deze id's gebruiken om het gegenereerde bestand te vinden en te downloaden via de API voor containerbestanden.

Toolbox-vaardigheden weergeven

Een werkset kan agentvaardigheden beschikbaar maken via MCP. Stel load_tools=False in wanneer alleen vaardigheden zichtbaar moeten zijn voor het model, voeg vervolgens de Toolbox toe als hulpprogramma zodat de MCP-sessie verbinding maakt, en gebruik as_skills_provider() als contextprovider.

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()

Goedkeuring blijft standaard ingeschakeld voor vaardigheidsbewerkingen. Schakel afzonderlijke goedkeuringen alleen uit voor vertrouwde, onbeheerde scenario's. Houd de Toolbox en de bijbehorende vaardighedenprovider bij elkaar, zodat beide dezelfde MCP-sessie gebruiken. Voor een langlevende Toolbox wordt de skill discovery-cache vervangen wanneer de effectieve identiteit van de platform-header verandert. Een aangepaste header_provider functie die wordt gebruikt met vaardigheden, moet worden opgehaald uit de omgevingscontext, zoals een closure of ContextVar, omdat vaardigheids- en resourceleesbewerkingen geen functieruntimeargumenten ontvangen.

Een Toolbox gebruiken met `FoundryAgent`

Koppel de Toolbox aan de definitie van de prompt of gehoste agent in Foundry. FoundryAgent gebruikt die opgeslagen toolconfiguratie; het doorgeven van een Toolbox aan clientzijde voegt deze niet toe aan de beheerde agent.

Verbinding maken via MCP met `FoundryToolbox`

Gebruik FoundryToolbox met ResponsesHostServer om een gehoste agent te verbinden met het Toolbox MCP-eindpunt. De wrapper authenticeert MCP-verzoeken en stuurt de bellercontext van het huidige gehoste verzoek door voor identiteitsdoorgifte per gebruiker. De request-scoped agent factory blijft de eenvoudigste optie wanneer de client, inloggegevens en Toolbox één opschoongrens nodig hebben. Een Toolbox met een lange levensduur wordt ook ondersteund en wordt opnieuw verbonden voordat een bewerking wordt uitgevoerd wanneer de identiteit van de platformheader verandert.

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()

Stel TOOLBOX_ENDPOINT in, of stel zowel FOUNDRY_PROJECT_ENDPOINT als TOOLBOX_NAME in, zoals beschreven in De Toolbox configureren. Stel FOUNDRY_MODEL in voor lokale uitvoeringen; gehoste implementaties vallen terug op de door azd beheerde AZURE_AI_MODEL_DEPLOYMENT_NAME.

Limitations

MCP-hulpprogramma's in een werkset maken gebruik van verificatie aan de serverzijde via een Foundry project_connection_id. De Agent Framework-client bevat het upstream MCP Bearer-token niet.
Voor het gebruiken van Toolbox als een MCP-server is Entra ID-authenticatie aan clientzijde vereist voor het Toolbox-eindpunt.
Reacties in toestemmingsstromen, zoals CONSENT_REQUIRED, worden afgehandeld wanneer de agent actief is, niet wanneer de Toolbox-verbinding tot stand wordt gebracht.

Samples

Sample	Beschrijving
foundry_toolbox/main.py	`FoundryToolbox` met een gehoste Responses-agent
foundry_toolbox_mcp_skills/main.py	Door werkset ondersteunde agentvaardigheden
foundry_chat_client_with_toolbox.py	McP-verbruik van werkset met `MCPStreamableHTTPTool`
foundry_chat_client_with_toolbox_skills.py	Op toolbox gebaseerde vaardighedenconfiguratie
invoke_foundry_toolbox_mcp	MCP-verbruik aan de werkstroomzijde

Go maakt momenteel geen Foundry Toolbox-helper beschikbaar. Configureer toolboxes via Foundry en gebruik ondersteunde tooldeclaraties voor lokale of gehoste tools voor Go-agents.

Feedback

Is deze pagina nuttig?

Laatst bijgewerkt om 2026-10-06

Microsoft Foundry Toolbox

De pakketten installeren

Toolbox configureren

Gebruik FoundryToolbox met een gehoste agent

Toolbox-vaardigheden weergeven

Een Toolbox gebruiken met FoundryAgent

Verbinding maken via MCP met FoundryToolbox