Casella degli strumenti Microsoft Foundry

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.
builder.Services.AddFoundryToolboxes(credential, toolboxName);

app.Run();

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

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

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.

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.

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

Go non espone attualmente un helper di Toolbox in Foundry. Configurare Toolbox tramite Foundry e usare dichiarazioni di strumenti locali o ospitate supportate per gli agenti Go.