Zestaw narzędzi Microsoft Foundry

W przypadku zarządzanej przez FoundryAgentusługę dołącz przybornik do definicji agenta w narzędziu Foundry.

W przypadku agenta hostowanego utworzonego za pomocą platformy Microsoft Agent Framework użyj AddFoundryToolboxes z Microsoft.Agents.AI.Foundry.Hosting, jak pokazano w poniższym przykładzie.

Użyj projektu internetowego .NET 10 z włączoną funkcją implicit usings oraz zgodnymi wersjami Microsoft.Agents.AI.Foundry, Microsoft.Agents.AI.Foundry.Hosting i DotNetEnv. Ustaw TOOLBOX_NAME na istniejący przybornik, a FOUNDRY_MODEL na wdrożenie modelu. Usługa Foundry dostarcza FOUNDRY_PROJECT_ENDPOINT do wdrożonego hosta. Aby uzyskać dostęp do modelu lokalnego, ustaw FOUNDRY_PROJECT_ENDPOINT i zaloguj się przy użyciu Azure CLI. Hostowane wdrożenia przechodzą na zarządzane przez usługę azd AZURE_AI_MODEL_DEPLOYMENT_NAME. Integracja hostingu ładuje narzędzia przybornika, gdy FOUNDRY_PROJECT_ENDPOINT jest dostępny.

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

Ta sama rejestracja hosta obsługuje narzędzia skonfigurowane do korzystania ze zgody OAuth udzielanej oddzielnie przez każdego użytkownika dla swoich połączeń z przybornikiem. Użytkownicy nadal potrzebują wymaganych uprawnień i zgody; nie jest wymagany żaden oddzielny blok rejestracji hosta.

Informacje o plikach projektu i instrukcje wdrażania znajdziesz w Hosted-Toolbox. Aby uzyskać informacje o konfiguracji zgody dla użytkownika, zobacz Hosted-Toolbox-AuthPaths.

Instalowanie pakietów

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

FoundryToolbox jest importowany z agent_framework.foundry i dostarczany przez agent-framework-foundry-hosting.

Skonfiguruj przybornik

Ustaw jawnie adres punktu końcowego MCP dla Toolbox:

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

Lub pozwól, aby FoundryToolbox skonstruował punkt końcowy:

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

Przykłady hostowanego agenta preferują FOUNDRY_MODEL lokalnie i przechodzą na AZURE_AI_MODEL_DEPLOYMENT_NAME zarządzane przez azd, gdy są hostowane.

Użyj FoundryToolbox z hostowanym agentem

FoundryToolbox ustala adres swojego punktu końcowego, uwierzytelnia każde żądanie MCP przy użyciu podanego poświadczenia platformy Azure, przekazuje identyfikator wywołania usługi Foundry dla danego żądania i uczestniczy w cyklu życia połączenia agenta. Ustala nagłówki platformy na granicy każdej operacji i ponownie łączy swoją sesję MCP po zmianie efektywnej tożsamości żądania. W związku z tym długotrwale działający Toolbox nie zachowuje identyfikatora wywołania poprzedniego wywołującego.

Przykład tworzy Toolbox, klienta i poświadczenia wewnątrz fabryki agentów o zakresie żądania, aby zapewnić deterministyczną własność i czyszczenie. Użyj tego wzorca Factory, gdy powiązane zasoby należą do żądania, ale nie jest on wymagany wyłącznie do zachowania bieżących identyfikatorów wywołań Toolbox.

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

Gdy Toolbox Code Interpreter tworzy plik, a odpowiedź asystenta wymienia ten plik, hostowany adapter Responses emituje natywną adnotację container_file_citation z identyfikatorami kontenera i pliku. Klienci mogą używać tych identyfikatorów do odnajdywania i pobierania wygenerowanego pliku za pośrednictwem interfejsu API plików kontenera.

Wyświetl umiejętności Toolbox

Zestaw narzędzi może udostępniać umiejętności agenta za pośrednictwem MCP. Ustaw load_tools=False, gdy tylko umiejętności powinny być widoczne dla modelu, a następnie dodaj Toolbox jako narzędzie, aby jego sesja MCP mogła się połączyć, i użyj as_skills_provider() jako dostawcy kontekstu.

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

Zatwierdzanie pozostaje domyślnie włączone dla operacji dotyczących umiejętności. Wyłącz indywidualne zatwierdzenia tylko w zaufanych, nienadzorowanych scenariuszach. Zachowaj Toolbox i jego dostawcę umiejętności, aby oba korzystały z tej samej sesji MCP. W przypadku Toolbox o długim czasie życia pamięć podręczna odnajdywania umiejętności jest zastępowana po zmianie obowiązującej tożsamości nagłówka platformy. Niestandardowe header_provider używane ze skills muszą być ustalane na podstawie stanu otoczenia, takiego jak domknięcie lub ContextVar, ponieważ odczyty skills i zasobów nie otrzymują argumentów przekazywanych do funkcji w czasie wykonywania.

Używanie Przybornika z FoundryAgent

Dołącz Toolbox do definicji promptu lub agenta hostowanego w Foundry. FoundryAgent używa zapisanej konfiguracji narzędzia; przekazanie obiektu Toolbox po stronie klienta nie powoduje dodania go do agenta zarządzanego.

Połącz przez MCP za pomocą FoundryToolbox

Aby połączyć hostowanego agenta z punktem końcowym Toolbox MCP, użyj FoundryToolbox z ResponsesHostServer. Warstwa pośrednia uwierzytelnia żądania MCP i przekazuje kontekst wywołującego bieżącego hostowanego żądania, aby umożliwić przekazywanie tożsamości poszczególnych użytkowników. Fabryka o zasięgu żądania agent pozostaje najprostszą opcją, gdy klient, poświadczenia i Toolbox potrzebują jednej granicy zwalniania zasobów. Toolbox z długim czasem działania jest również obsługiwany i ponownie łączy się przed operacją, gdy zmienia się tożsamość nagłówka 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()

Ustaw TOOLBOX_ENDPOINT, albo ustaw zarówno FOUNDRY_PROJECT_ENDPOINT, jak i TOOLBOX_NAME, zgodnie z opisem w sekcji Konfigurowanie przybornika. Ustaw FOUNDRY_MODEL dla przebiegów lokalnych; hostowane wdrożenia domyślnie korzystają z zarządzanego przez usługę azd AZURE_AI_MODEL_DEPLOYMENT_NAME.

Obsługa żądań zgody OAuth

Gdy operacja Toolbox lub MCP wymaga zgody OAuth, wywołania FoundryAgent oraz FoundryChatClient w trybie strumieniowym i niestreamingowym zwracają Content(type="oauth_consent_request") z linkiem do wyrażenia zgody zamiast pustego komunikatu asystenta. Obsłuż tę zawartość jako żądanie danych wejściowych użytkownika i przedstawij jej consent_link użytkownikowi.

Klient wyświetla tylko łącza ze schematem HTTPS i prawidłowym hostem. Brakujące lub nieprawidłowe linki są pomijane i rejestrowane.

Limitations

• Narzędzia MCP w przyborniku używają uwierzytelniania po stronie serwera za pośrednictwem rozwiązania Foundry project_connection_id; klient programu Agent Framework nie przechowuje nadrzędnego tokenu elementu nośnego MCP.
• Korzystanie z Przybornika jako z serwera MCP wymaga uwierzytelniania Entra ID po stronie klienta na potrzeby punktu końcowego Przybornika.
• Odpowiedzi w przepływie zgody, takie jak CONSENT_REQUIRED, są obsługiwane podczas działania agenta, a nie podczas tworzenia połączenia z Toolbox.

Samples

Go obecnie nie udostępnia pomocnika Foundry Toolbox. Skonfiguruj zestawy narzędzi w Foundry i używaj obsługiwanych lokalnych lub hostowanych deklaracji narzędzi dla agentów Go.