Sada nástrojů Microsoft Foundry

Microsoft Foundry Toolbox je pojmenovaný, verzovaný serverový balíček konfigurací hostovaných nástrojů, jako jsou interpret kódu, vyhledávání souborů, generování obrázků, MCP a vyhledávání na webu. Sady nástrojů umožňují spravovat konfiguraci nástrojů jednou v Foundry a opakovaně ji používat napříč agenty.

Agent Framework pokrývá spotřebu sady nástrojů. Vytvářejte a aktualizujte verze sady nástrojů prostřednictvím portálu azure-ai-projects Foundry nebo sady SDK.

Důležité

FoundryToolbox je poskytována beta agent-framework-foundry-hosting balíčkem a může se změnit před stabilním vydáním.

U služby spravované FoundryAgent připojte Toolbox k definici agenta ve Foundry.

Pro hostovaného agenta sestaveného pomocí Microsoft Agent Framework použijte AddFoundryToolboxes z Microsoft.Agents.AI.Foundry.Hosting, jak je znázorněno v následujícím příkladu.

Použijte webový projekt .NET 10 s implicitními použitími povolenými, odpovídajícími verzemi Microsoft.Agents.AI.Foundry a Microsoft.Agents.AI.Foundry.Hostinga DotNetEnv. Nastavte TOOLBOX_NAME na existující sadu nástrojů a FOUNDRY_MODEL na nasazení modelu. Foundry dodává FOUNDRY_PROJECT_ENDPOINT nasazenému hostiteli. Pokud chcete získat přístup k místnímu modelu, nastavte FOUNDRY_PROJECT_ENDPOINT a přihlaste se pomocí Azure CLI. Hostovaná nasazení se vrátí k AZURE_AI_MODEL_DEPLOYMENT_NAME spravovanému službou azd. Integrace hostování načte nástroje sady nástrojů, když je k dispozici FOUNDRY_PROJECT_ENDPOINT.

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

Stejná registrace hostitele podporuje nástroje nakonfigurované pro souhlas OAuth udělovaný jednotlivými uživateli v jejich připojeních k sadě nástrojů. Uživatelé stále potřebují požadovaná oprávnění a souhlas; Není potřeba žádný samostatný blok registrace hostitele.

Pokyny k souborům projektu a nasazení najdete v tématu Hostovaná sada nástrojů. Informace o nastavení souhlasu pro jednotlivé uživatele najdete v tématu Hosted-Toolbox-AuthPaths.

Instalace balíčků

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

FoundryToolbox je importován z agent_framework.foundry a dodáván pomocí agent-framework-foundry-hosting.

Konfigurace sady nástrojů

Nastavení explicitního koncového bodu MCP sady nástrojů:

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

Nebo nechte FoundryToolbox vytvořit koncový bod:

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

Ukázky hostovaného agenta dávají přednost FOUNDRY_MODEL lokálně a při hostování přejdou na AZURE_AI_MODEL_DEPLOYMENT_NAME spravované nástrojem azd.

Použijte FoundryToolbox s hostovaným agentem

FoundryToolbox určuje svůj koncový bod, ověřuje každý požadavek MCP pomocí poskytnutých přihlašovacích údajů Azure, předává ID volání Foundry pro každý požadavek a podílí se na životním cyklu připojení agenta. Určuje hlavičky platformy na každé hranici operace a při změně efektivní identity požadavku znovu připojí svou relaci MCP. Dlouhodobý Toolbox proto nezachová ID volání dřívějšího volajícího.

Ukázka vytvoří Toolbox, klienta a přihlašovací údaje uvnitř fabriky agentů s rozsahem požadavku pro deterministické vlastnictví a vyčištění. Tento factory pattern použijte, pokud jsou související prostředky patřící požadavku, ale není vyžadován pouze k tomu, aby ID volání Toolbox zůstala aktuální.

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

Když Toolbox Code Interpreter vytvoří soubor a odpověď asistenta tento soubor pojmenuje, adaptér Responses v hostovaném prostředí vygeneruje nativní anotaci container_file_citation s ID kontejneru a ID souboru. Klienti mohou pomocí těchto ID zjistit a stáhnout vygenerovaný soubor prostřednictvím rozhraní API pro soubory kontejneru.

Zpřístupněte dovednosti Toolboxu

Sada nástrojů může zpřístupnit dovednosti agenta přes MCP. Nastavte load_tools=False, když mají být pro model viditelné pouze dovednosti, potom přidejte Toolbox jako nástroj, aby se jeho relace MCP připojila a aby používal as_skills_provider() jako poskytovatele kontextu.

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

Schválení zůstává pro operace se schopnostmi ve výchozím nastavení povoleno. Zakažte jednotlivá schválení pouze pro důvěryhodné a bezobslužné scénáře. Nechte sadu nástrojů a jejího poskytovatele dovedností pohromadě, aby oba používali stejnou relaci MCP. V případě dlouhodobé Toolbox se mezipaměť zjišťování dovedností nahradí, když se změní efektivní identita hlavičky platformy. Vlastní header_provider použitý se skills se musí vyhodnotit z okolního stavu, jako je uzávěr nebo ContextVar, protože operace čtení ve skills a resources nepřijímají argumenty modulu runtime funkce.

Použití panelu nástrojů s FoundryAgent

Připojte panel nástrojů k definici promptu nebo hostovaného agenta ve Foundry. FoundryAgent používá uloženou konfiguraci nástroje; Předání sady nástrojů na straně klienta ho nepřidá do spravovaného agenta.

Připojení přes MCP pomocí FoundryToolbox

Použijte ResponsesHostServer s FoundryToolbox k připojení hostovaného agenta ke koncovému bodu Toolbox MCP. Wrapper autentizuje požadavky MCP a předává kontext volajícího aktuálně hostovaného požadavku pro předávání identity jednotlivých uživatelů. Factory s rozsahem požadavku agent zůstává nejjednodušší možností, pokud klient, přihlašovací údaje a Toolbox potřebují jednu hranici čištění. Podporován je také dlouho běžící Toolbox, který se před operací znovu připojí, když se změní identita hlavičky platformy.

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

Nastavte TOOLBOX_ENDPOINT, nebo nastavte obě možnosti FOUNDRY_PROJECT_ENDPOINT a TOOLBOX_NAME, jak je popsáno v části Konfigurace sady nástrojů. Nastavit FOUNDRY_MODEL pro místní spuštění; hostovaná nasazení přejdou na spravovaný AZURE_AI_MODEL_DEPLOYMENT_NAME azd.

Zpracování žádostí o souhlas OAuth

Pokud operace sady nástrojů nebo MCP vyžaduje souhlas OAuth, streamovaná i nestreamovaná volání FoundryAgent a FoundryChatClient vrátí Content(type="oauth_consent_request") s odkazem na souhlas místo prázdné zprávy asistenta. Tento obsah zpracujete jako požadavek zadaný uživatelem a předložíte jeho consent_link uživateli.

Klient zobrazí pouze propojení se schématem HTTPS a platným hostitelem. Chybějící nebo neplatné odkazy jsou vynechány a zaprotokolovány.

Limitations

• Nástroje MCP v sadě nástrojů používají ověřování na straně serveru prostřednictvím Foundry project_connection_id. Klient rozhraní agenta neudržuje nadřazený nosný token MCP.
• Použití Toolboxu jako serveru MCP vyžaduje ověřování klienta pomocí Entra ID pro koncový bod Toolboxu.
• Odpovědi v rámci procesu udělení souhlasu, jako CONSENT_REQUIRED, se zpracovávají za běhu agenta, nikoli během vytváření připojení k Toolboxu.

Samples

Sample	Description
foundry_toolbox/main.py	FoundryToolbox s hostovaným agentem pro odpovědi
foundry_toolbox_mcp_skills/main.py	Dovednosti agenta podporované sadou nástrojů
foundry_chat_client_with_toolbox.py	Spotřeba MCP v sadě nástrojů s využitím MCPStreamableHTTPTool
foundry_chat_client_with_toolbox_skills.py	Konfigurace dovedností podporovaných sadou nástrojů
invoke_foundry_toolbox_mcp	Spotřeba MCP na straně pracovního postupu

Go momentálně nezpřístupňuje pomocníka sady nástrojů Foundry. Nakonfigurujte sady nástrojů prostřednictvím Foundry a použijte podporované místní nebo hostované deklarace nástrojů pro agenty Go.

Související informace

• poskytovatel modelu Microsoft Foundry
• Služba agenta Microsoft Foundry
• Místní nástroje MCP