Boîte à outils Microsoft Foundry

Une boîte à outils Microsoft Foundry est un ensemble nommé et versionné côté serveur de configurations d’outils hébergés, comme l’interpréteur de code, la recherche de fichiers, la génération d’images, MCP et la recherche web. Les boîtes à outils vous permettent de gérer la configuration des outils une fois dans Foundry et de les réutiliser entre les agents.

Agent Framework prend en charge l’utilisation de Toolbox. Créez et mettez à jour des versions de boîte à outils via le portail Foundry ou le azure-ai-projects Kit de développement logiciel (SDK).

Important

FoundryToolbox est fourni par le package bêta agent-framework-foundry-hosting et peut changer avant la version stable.

Pour un service géré FoundryAgent, attachez la boîte à outils à la définition de l’agent dans Foundry.

Pour un agent hébergé créé avec Microsoft Agent Framework, utilisez AddFoundryToolboxes de Microsoft.Agents.AI.Foundry.Hosting, comme illustré dans l’exemple suivant.

Utilisez un projet web .NET 10 avec les directives using implicites activées, des versions correspondantes de Microsoft.Agents.AI.Foundry et de Microsoft.Agents.AI.Foundry.Hosting, ainsi que DotNetEnv. Affectez TOOLBOX_NAME à une boîte à outils existante et AZURE_AI_MODEL_DEPLOYMENT_NAME à votre déploiement de modèle. Foundry fournit FOUNDRY_PROJECT_ENDPOINT à l’hôte déployé. Pour l’accès au modèle local, définissez AZURE_AI_PROJECT_ENDPOINT et connectez-vous avec Azure CLI. L’intégration d’hébergement charge les outils de la boîte à outils lorsque FOUNDRY_PROJECT_ENDPOINT est disponible.

using Azure.AI.Projects;
using Azure.Identity;
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")
    ?? System.Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException(
        "Neither FOUNDRY_PROJECT_ENDPOINT (platform-injected in hosted runtime) " +
        "nor AZURE_AI_PROJECT_ENDPOINT (local-dev convention) is set.");
string deploymentName = FirstNonBlank(
    System.Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME"),
    System.Environment.GetEnvironmentVariable("FOUNDRY_MODEL"),
    "gpt-4o")!;
string toolboxName = FirstNonBlank(
    System.Environment.GetEnvironmentVariable("TOOLBOX_NAME"),
    "my-toolset")!;

var credential = new DefaultAzureCredential();

AIAgent agent = new AIProjectClient(new Uri(endpoint), credential)
    .AsAIAgent(
        model: deploymentName,
        instructions: """
            You are a helpful assistant with access to tools provided by the Foundry Toolbox.
            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");

var builder = WebApplication.CreateBuilder(args);

// Register the agent and response handler
builder.Services.AddFoundryResponses(agent);

builder.Services.AddFoundryToolboxes(credential, toolboxName);

var app = builder.Build();
app.MapFoundryResponses();


app.Run();

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

Le même enregistrement d’hébergement prend en charge les outils configurés pour le consentement OAuth par utilisateur pour leurs connexions à la boîte à outils. Les utilisateurs ont toujours besoin des autorisations requises et du consentement ; aucun bloc d’inscription d’hôte distinct n’est nécessaire.

Pour obtenir les instructions de déploiement et de fichiers projet, consultez Hosted-Toolbox. Pour la configuration du consentement par utilisateur, consultez Hosted-Toolbox-AuthPaths.

Installer les packages

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

FoundryToolbox est importé depuis agent_framework.foundry et fourni par agent-framework-foundry-hosting.

Configurer la boîte à outils

Définissez un point de terminaison MCP de boîte à outils explicite :

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

Ou laissez FoundryToolbox construire le point de terminaison :

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

Les exemples d’agents hébergés utilisent également AZURE_AI_MODEL_DEPLOYMENT_NAME pour FoundryChatClient.

Utiliser `FoundryToolbox` avec un agent hébergé

FoundryToolboxrésout son point de terminaison, authentifie chaque demande MCP avec les informations d'identification Azure fournies, transfère l'ID d'appel Foundry par demande et participe au cycle de vie de connexion de l'agent. Dans un agent réponses hébergé, créez la boîte à outils, son client et ses informations d’identification à l’intérieur de la fabrique d’agents délimitée par la requête. L’enregistreur MCP capture le contexte de requête lorsqu’il se connecte. Ne partagez donc pas une boîte à outils connectée entre les appelants.

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 tools inside this request so the MCP writer captures its call ID."""
    endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    model = 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()

Afficher les compétences de la boîte à outils

Une boîte à outils peut exposer les compétences de l’agent via MCP. Définissez load_tools=False quand seules les compétences doivent être visibles par modèle, puis ajoutez la boîte à outils en tant qu’outil afin que sa session MCP se connecte et utilise as_skills_provider() en tant que fournisseur de contexte.

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 writer within this request."""
    endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    model = 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()

L’approbation reste activée par défaut pour les opérations de compétence. Désactivez les approbations individuelles uniquement pour les scénarios de confiance sans surveillance. Conservez la boîte à outils et le fournisseur de compétences dans la même fabrique de requêtes afin qu’ils utilisent tous deux la même session MCP et soient libérés ensemble.

Utiliser une boîte à outils avec `FoundryAgent`

Joignez la Toolbox à la définition du prompt ou de l’agent hébergé dans Foundry. FoundryAgent utilise cette configuration d’outil stockée ; le passage d’une boîte à outils côté client ne l’ajoute pas à l’agent managé.

Se connecter via MCP avec `FoundryToolbox`

Utilisez FoundryToolbox avec ResponsesHostServer pour connecter un agent hébergé au point de terminaison MCP Toolbox. Le composant d’encapsulation authentifie les requêtes MCP et transmet le contexte de l’appelant de la requête hébergée en cours afin de permettre la transmission de l’identité de chaque utilisateur. Créez la connexion dans la fabrique agent afin que chaque requête reçoive son propre contexte d’appel.

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 tools inside this request so the MCP writer captures its call ID."""
    endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    model = 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()

Définissez TOOLBOX_ENDPOINT, ou définissez les deux FOUNDRY_PROJECT_ENDPOINT et TOOLBOX_NAME, comme décrit dans Configurer la boîte à outils. L’exemple utilise AZURE_AI_MODEL_DEPLOYMENT_NAME pour le déploiement du modèle.

Limites

Les outils MCP à l’intérieur d’une boîte à outils utilisent l’authentification côté serveur par le biais d’une instance Foundry project_connection_id; le client Agent Framework ne contient pas le jeton du porteur MCP en amont.
L’utilisation de la boîte à outil comme serveur MCP nécessite une authentification Entra ID côté client pour le point de terminaison de la boîte à outils.
Les réponses de flux de consentement telles que CONSENT_REQUIRED sont gérées pendant l’exécution de l’agent, et non pendant la création de la connexion de boîte à outils.

Samples

Sample	Description
foundry_toolbox/main.py	`FoundryToolbox` avec un agent Responses hébergé
foundry_toolbox_mcp_skills/main.py	Compétences de l’agent soutenu par la boîte à outils
foundry_chat_client_with_toolbox.py	Consommation MCP de boîte à outils avec `MCPStreamableHTTPTool`
foundry_chat_client_with_toolbox_skills.py	Configuration des compétences soutenues par la boîte à outils
invoke_foundry_toolbox_mcp	Consommation MCP côté flux de travail

Go ne fournit pas actuellement de fonction utilitaire Foundry Toolbox. Configurez les boîtes à outils via Foundry et utilisez les déclarations d’outils locales ou hébergées prises en charge pour les agents Go.

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-10-01

Boîte à outils Microsoft Foundry

Installer les packages

Configurer la boîte à outils

Utiliser FoundryToolbox avec un agent hébergé

Afficher les compétences de la boîte à outils

Utiliser une boîte à outils avec FoundryAgent

Se connecter via MCP avec FoundryToolbox