Microsoft Foundry-verktygslåda

För en tjänsthanterad FoundryAgent kopplar du verktygslådan till agentdefinitionen i Foundry.

För en värdbaserad agent som skapats med Microsoft Agent Framework använder du AddFoundryToolboxes från Microsoft.Agents.AI.Foundry.Hosting, som du ser i följande exempel.

Använd ett .NET 10-webbprojekt med implicita användningar aktiverade, matchande versioner av Microsoft.Agents.AI.Foundry och Microsoft.Agents.AI.Foundry.Hosting, och DotNetEnv. Ställ in TOOLBOX_NAME på en befintlig verktygslåda och FOUNDRY_MODEL på din modellimplementering. Foundry levererar FOUNDRY_PROJECT_ENDPOINT till den driftsatta värddatorn. För lokal modellåtkomst anger du FOUNDRY_PROJECT_ENDPOINT och loggar in med Azure CLI. Värdbaserade distributioner använder azd-managed AZURE_AI_MODEL_DEPLOYMENT_NAME som fallback. Värdintegrationen läser in verktyg i verktygslådan när FOUNDRY_PROJECT_ENDPOINT är tillgänglig.

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

Samma värdregistrering stöder verktyg som har konfigurerats för OAuth-samtycke för varje användare på sina verktygslådeanslutningar. Användarna behöver fortfarande de behörigheter och medgivande som krävs. inget separat block för värdregistrering behövs.

Information om projektfiler och distributionsinstruktioner finns i Hosted-Toolbox. Information om konfiguration av medgivande per användare finns i Hosted-Toolbox-AuthPaths.

Installera programvarupaketen

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

FoundryToolbox importeras från agent_framework.foundry och tillhandahålls av agent-framework-foundry-hosting.

Konfigurera verktygslådan

Ange en explicit MCP-slutpunkt för verktygslådan:

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

Eller låt FoundryToolbox konstruera ändpunkten:

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

Hosted-agent-exemplen föredrar FOUNDRY_MODEL lokalt och faller tillbaka på azd-managed AZURE_AI_MODEL_DEPLOYMENT_NAME när de körs hostat.

Använda FoundryToolbox med en värdbaserad agent

FoundryToolbox fastställer sin slutpunkt, autentiserar varje MCP-begäran med de angivna Azure-autentiseringsuppgifterna, vidarebefordrar Foundrys anrops-ID per begäran och deltar i agentens anslutnings livscykel. Den löser plattformsheaders vid varje åtgärdsgräns och återansluter sin MCP-session när den effektiva identiteten för begäran ändras. En långlivad verktygslåda behåller därför inte ett tidigare anroparens samtals-ID.

Exemplet skapar Toolbox, klienten och autentiseringsuppgifterna i den begäransbegränsade agentfabriken för deterministiskt ägarskap och rensning. Använd det här fabriksmönstret när relaterade resurser ägs av begäran, men det krävs inte enbart för att hålla Toolbox-anrops-ID:t aktuellt.

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

När Toolbox Code Interpreter skapar en fil och assistentens svar nämner den filen, genererar den värdbaserade Responses-adaptern en intern container_file_citation-anteckning med container- och fil-ID:t. Klienter för Responses kan använda dessa ID:n för att hitta och ladda ned den genererade filen via API:et för containerfiler.

Exponera Toolbox-färdigheter

En verktygslåda kan exponera agentkunskaper över MCP. Ange load_tools=False när endast färdigheter ska vara modellsynliga, lägg sedan till Toolbox som ett verktyg så att dess MCP-session ansluter, och använd as_skills_provider() som en kontextleverantör.

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

Godkännande är fortfarande aktiverat som standard för kompetensåtgärder. Inaktivera endast enskilda godkännanden för betrodda, obevakade scenarier. Håll ihop verktygslådan och dess skills provider så att båda använder samma MCP-session. För en långlivad Toolbox ersätts cachen för identifiering av färdigheter när plattformshuvudets identitet ändras. En anpassad header_provider som används med färdigheter måste lösas från det omgivande tillståndet, till exempel en closure eller ContextVar, eftersom läsningar av färdigheter och resurser inte tar emot argument för funktionskörning.

Använd verktygslådan med FoundryAgent

Anslut Toolbox till Prompt- eller Hosted Agent-definitionen i Foundry. FoundryAgent använder den sparade verktygskonfigurationen; att skicka Toolbox på klientsidan lägger inte till den i den hanterade agenten.

Ansluta via MCP med FoundryToolbox

Använd FoundryToolbox med ResponsesHostServer för att ansluta en värdbaserad agent till TOOLBOX MCP-slutpunkten. Omslutningen autentiserar MCP-begäranden och vidarebefordrar den aktuella värdbaserade begärandens samtalskontext för identitetsgenomströmning per användare. Den begäransomfattande agent-fabriken är fortfarande det enklaste alternativet när klienten, autentiseringsuppgifterna och verktygslådan behöver en gemensam gräns för resursrensning. En långlivad Toolbox stöds också och återansluts före en åtgärd när platform-header-identiteten ändras.

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

Ange TOOLBOX_ENDPOINT, eller ange både FOUNDRY_PROJECT_ENDPOINT och TOOLBOX_NAME, enligt beskrivningen i Konfigurera verktygslådan. Ange FOUNDRY_MODEL för lokala körningar. Hostade distributioner faller tillbaka på den azd-hanterade AZURE_AI_MODEL_DEPLOYMENT_NAME.

Limitations

• MCP-verktyg i en verktygslåda använder autentisering på serversidan via en Foundry project_connection_id. Agent Framework-klienten innehåller inte den överordnade MCP-ägartoken.
• Att använda en verktygslåda som en MCP-server kräver klientbaserad Entra ID-autentisering för Toolbox-slutpunkten.
• Medgivandeflödessvar som CONSENT_REQUIRED hanteras medan agenten körs, inte när toolbox-anslutningen skapas.

Samples

Go tillhandahåller för närvarande ingen hjälpfunktion för Foundry Toolbox. Konfigurera verktygslådor via Foundry och använd lokala eller värdbaserade verktygsdeklarationer som stöds för Go-agenter.