Casella degli strumenti Microsoft Foundry

Un Microsoft Foundry Toolbox è un pacchetto lato server denominato e con versione, composto da configurazioni ospitate di strumenti quali interprete di codice, ricerca file, generazione di immagini, MCP e ricerca sul Web. Le caselle degli strumenti consentono di gestire la configurazione degli strumenti una sola volta in Foundry e riutilizzarla tra gli agenti.

Agent Framework copre l'utilizzo di Toolbox. Crea e aggiorna le versioni di Toolbox tramite il portale Foundry o il azure-ai-projects SDK.

Importante

FoundryToolbox viene fornito dal pacchetto beta agent-framework-foundry-hosting e può cambiare prima del rilascio stabile.

Per un FoundryAgent gestito dal servizio, collegare Toolbox alla definizione dell'agente in Foundry.

Per un agente ospitato compilato con Microsoft Agent Framework, usare AddFoundryToolboxes da Microsoft.Agents.AI.Foundry.Hosting, come illustrato nell'esempio seguente.

Usare un progetto web .NET 10 con usi impliciti abilitati, versioni corrispondenti di Microsoft.Agents.AI.Foundry, Microsoft.Agents.AI.Foundry.Hosting e DotNetEnv. Impostare TOOLBOX_NAME su una casella degli strumenti esistente e FOUNDRY_MODEL sulla distribuzione modello. Foundry fornisce FOUNDRY_PROJECT_ENDPOINT all'host distribuito. Per l'accesso al modello locale, impostare FOUNDRY_PROJECT_ENDPOINT e accedere con interfaccia della riga di comando di Azure. Le distribuzioni ospitate eseguono il fallback in azd-managed AZURE_AI_MODEL_DEPLOYMENT_NAME. L'integrazione di hosting carica gli strumenti del toolbox quando FOUNDRY_PROJECT_ENDPOINT è disponibile.

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.
#if USE_LOCAL_AGENT_FRAMEWORK_SOURCE
#endif

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


app.Run();

La stessa registrazione dell'hosting supporta gli strumenti configurati per il consenso OAuth per utente nelle connessioni della casella degli strumenti. Gli utenti hanno ancora bisogno delle autorizzazioni e del consenso necessari; non è necessario alcun blocco di registrazione host separato.

Per i file di progetto e le istruzioni di distribuzione, vedere Hosted-Toolbox. Per la configurazione del consenso per utente, vedere Hosted-Toolbox-AuthPaths.

Installare i pacchetti

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

FoundryToolbox viene importato da agent_framework.foundry e fornito da agent-framework-foundry-hosting.

Configurare la casella degli strumenti

Impostare un endpoint MCP esplicito per Toolbox:

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

In alternativa, lasciare FoundryToolbox costruire l'endpoint:

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

Gli esempi dell'agente ospitato preferiscono FOUNDRY_MODEL localmente ed eseguono il fallback a azd-managed AZURE_AI_MODEL_DEPLOYMENT_NAME quando ospitati.

Distribuisci l'esempio con Azure Developer CLI

L'esempio di Python corrente usa uno azure.yaml per definire l'agente ospitato, le connessioni, la casella degli strumenti e il mapping delle variabili di ambiente. Usare Azure Developer CLI 1.34.2 o versione successiva con l'estensione unificatamicrosoft.foundry:

azd ext install microsoft.foundry
azd provision
azd deploy --all

Effettuare il provisioning in modo che l'identità gestita del progetto Foundry esista prima che un amministratore conceda i ruoli necessari alle risorse di Azure connesse. Eseguire i comandi successivi dalla directory di progetto inizializzata che contiene azure.yaml.

Per gli strumenti configurati con entra pass-through, Foundry inoltra l'identità del chiamante corrente. Il chiamante deve comunque accedere alla risorsa di destinazione e l'applicazione ospitata deve inoltrare il contesto di chiamata della piattaforma anziché riutilizzare le intestazioni di una richiesta precedente.

Per l'ambiente completo, l'assegnazione di ruoli, l'esecuzione locale, la distribuzione e la sequenza di chiamata, vedere l'esempio di Python Foundry Toolbox.

Abilitare la ricerca degli strumenti di Toolbox

La ricerca strumenti di Toolbox mantiene ridotto l'elenco iniziale degli strumenti del modello. Aggiungere ToolSearchToolboxTool a una versione di Toolbox con i relativi strumenti MCP. Il modello vede tool_search inizialmente e call_tool, quindi individua gli strumenti MCP sottostanti in base alle esigenze.

Aggiornare Foundry SDK prima di eseguire questo esempio:

pip install --upgrade "azure-ai-projects>=2.4.0"

L'esempio di Python usa azure-ai-projects la versione 2.4.0 o successiva per creare una nuova versione della Toolbox contenente sia MCPToolboxTool che ToolSearchToolboxTool. Si connette a tale versione esatta e non elimina le versioni esistenti. Rimuovere la voce di ricerca degli strumenti quando si desidera che l'elenco completo degli strumenti sottostante sia esposto all'inizio dell'esecuzione.

Vedere Foundry Chat Client with Toolbox tool search per il modello di creazione della versione e di connessione MCP.

Usare FoundryToolbox con un agente ospitato

FoundryToolboxrisolve il relativo endpoint, autentica ogni richiesta MCP con la credenziale Azure fornita, inoltra l'ID di chiamata foundry per richiesta e partecipa al ciclo di vita della connessione dell'agente. Risolve le intestazioni della piattaforma al confine di ogni operazione e riconnette la sessione MCP quando cambia l'identità effettiva della richiesta. Una Toolbox di lunga durata non mantiene quindi l'ID di chiamata di un chiamante precedente.

L'esempio crea la casella degli strumenti, il client e le credenziali all'interno della factory dell'agente con ambito di richiesta per la titolarità e la pulizia deterministica. Usare questo modello di factory quando le risorse correlate sono di proprietà della richiesta, ma non è necessario mantenere aggiornati gli ID delle chiamate della casella degli strumenti.

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

Quando Toolbox Code Interpreter produce un file e la risposta dell'assistente nomina tale file, l'adattatore Responses ospitato genera un'annotazione nativa container_file_citation con gli ID del contenitore e del file. I client delle risposte possono usare questi ID per individuare e scaricare il file generato tramite l'API dei file del contenitore.

Mostra le abilità di Toolbox

Una casella degli strumenti può esporre le competenze dell'agente tramite MCP. Imposta load_tools=False quando solo le skill devono essere visibili al modello, quindi aggiungi Toolbox come strumento in modo che la relativa sessione MCP si connetta e usa as_skills_provider() come fornitore di contesto.

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

L'approvazione rimane abilitata per impostazione predefinita per le operazioni delle competenze. Disabilitare le approvazioni individuali solo per scenari attendibili non presidiati. Mantenere insieme la Toolbox e il provider di competenze in modo che entrambi usino la stessa sessione MCP. Per una casella degli strumenti di lunga durata, la cache di individuazione delle competenze viene sostituita quando cambia l'identità effettiva dell'intestazione della piattaforma. Un oggetto personalizzato header_provider usato con competenze deve essere risolto dallo stato di ambiente, ad esempio una chiusura o ContextVar, perché le letture di competenze e risorse non ricevono argomenti di runtime della funzione.

Usare Toolbox con FoundryAgent

Collega la Toolbox alla definizione del prompt o dell'agente ospitato in Foundry. FoundryAgent utilizza la configurazione dello strumento memorizzata; passando Toolbox lato client non lo si aggiunge all'agente gestito.

Connettersi tramite MCP con FoundryToolbox

Usare FoundryToolbox con ResponsesHostServer per connettere un agente ospitato all'endpoint MCP della casella degli strumenti. Il wrapper autentica le richieste MCP e inoltra il contesto del chiamante della richiesta ospitata corrente per il pass-through di identità per utente. La factory agent con ambito di richiesta rimane l'opzione più semplice quando il client, le credenziali e la casella degli strumenti richiedono un unico limite di pulizia. È supportata anche una Toolbox di lunga durata e viene riconnessa prima di un'operazione quando cambia l'identità dell'header della piattaforma.

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

Impostare TOOLBOX_ENDPOINT, o impostare sia FOUNDRY_PROJECT_ENDPOINT che TOOLBOX_NAME, come descritto in Configurare la casella degli strumenti. Impostare FOUNDRY_MODEL per le esecuzioni locali; le distribuzioni ospitate ripiegano su AZURE_AI_MODEL_DEPLOYMENT_NAME gestito da azd.

Gestire le richieste di consenso OAuth

Quando un'operazione Toolbox o MCP richiede il consenso OAuth, le chiamate in streaming e non in streaming FoundryAgent e FoundryChatClient restituiscono Content(type="oauth_consent_request") con il collegamento di consenso anziché un messaggio assistente vuoto. Gestire questo contenuto come richiesta di input dell'utente e presentarne il consent_link all'utente.

Il client espone solo i collegamenti con uno schema HTTPS e un host valido. I collegamenti mancanti o non validi vengono omessi e registrati.

Limitations

• Gli strumenti MCP in Toolbox usano l'autenticazione lato server tramite un project_connection_id di Foundry; il client di Agent Framework non detiene il token di connessione dell'MCP upstream.
• L'utilizzo di Toolbox come server MCP richiede l'autenticazione Entra ID lato client per l'endpoint di Toolbox.
• Le risposte del flusso di consenso, come CONSENT_REQUIRED, vengono gestite durante l'esecuzione dell'agente, non durante la creazione della connessione a Toolbox.

Samples

Sample	Descrizione
foundry_toolbox/main.py	FoundryToolbox con un agente di risposta ospitato
foundry_toolbox_mcp_skills/main.py	Competenze dell'agente supportate dalla casella degli strumenti
foundry_chat_client_with_toolbox.py	Individuazione di Toolbox su richiesta tramite tool_search e call_tool su MCP
foundry_chat_client_with_toolbox_skills.py	Configurazione delle competenze supportate dalla casella degli strumenti
invoke_foundry_toolbox_mcp	Utilizzo di MCP lato flusso di lavoro

Go può richiamare un agente gestito dal servizio con una Toolbox collegata o utilizzare l'endpoint della Toolbox tramite l'integrazione MCP standard. Non fornisce gli helper dedicati FoundryToolbox o AddFoundryToolboxes visualizzati nelle altre schede.

Usare una cassetta degli strumenti con un agente gestito dal servizio

Collegare la Toolbox alla definizione dell'agente in Foundry, quindi richiamare l'agente esistente con foundryprovider.NewAgent e foundryprovider.ServerAgent("<agent-name>"). Il servizio è proprietario della configurazione Toolbox archiviata.

Il passaggio di singole dichiarazioni di strumenti locali o ospitati a un agente di distribuzione del modello non collega una casella degli strumenti. Per la configurazione della connessione, vedere Agente Foundry sul lato server esistente.

Connettersi tramite MCP

Per usare gli strumenti di Toolbox da un agente Go gestito dall'applicazione:

1. Ottenere l'endpoint MCP di una Toolbox esistente.
2. Configurare un client HTTP di proprietà dell'applicazione per autenticare le richieste di casella degli strumenti con una credenziale di Azure per https://ai.azure.com/.default. Aggiornare il token in base alle esigenze e limitare l'inoltro delle credenziali all'endpoint Toolbox desiderato.
3. Passare il client tramite mcp.StreamableClientTransport.HTTPClient, con l'endpoint della casella degli strumenti in Endpoint.
4. Chiamare mcptool.Connect, quindi mcptool.ListToolse registrare gli strumenti restituiti in agent.Config.Tools.
5. Mantenere aperta la sessione MCP mentre l'agente usa gli strumenti e chiuderla al termine di tali operazioni.

Questo segue lo stesso modello discover-and-invoke degli strumenti MCP locali. Vedere Connettersi a un server MCP per le API Go per il trasporto e la registrazione degli strumenti.

Limiti di integrazione di Go

L'integrazione MCP Go generica non fornisce il ciclo di vita della casella degli strumenti ospitata, l'inoltro delle identità con intestazione della piattaforma o l'adattatore di capacità supportato dalla casella degli strumenti descritto negli esempi di .NET e Python. Configurare l'autenticazione e la proprietà delle risorse nell'applicazione invece di presupporre che tali helper vengano eseguiti automaticamente.

Guida correlata

• Fornitore di modelli Microsoft Foundry
• Servizio Microsoft Foundry Agent
• Strumenti MCP locali