Casella degli strumenti Microsoft Foundry

Una casella degli strumenti Microsoft Foundry è un bundle lato server denominato e con controllo delle versioni di configurazioni degli strumenti ospitate, ad esempio interprete del codice, ricerca di file, generazione di immagini, MCP e ricerca 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 della casella degli strumenti. Creare e aggiornare le versioni della casella degli strumenti tramite il portale foundry o l'SDK azure-ai-projects .

Importante

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

Per un servizio gestito FoundryAgent, collegare la casella degli strumenti alla definizione dell'agente in Foundry. Le linee guida per l'utilizzo della casella degli strumenti sul lato client .NET non sono attualmente documentate.

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 della casella degli strumenti esplicito:

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 usano AZURE_AI_MODEL_DEPLOYMENT_NAME anche per FoundryChatClient.

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.

import asyncio
import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient, FoundryToolbox, ResponsesHostServer
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()


async def main():
    credential = DefaultAzureCredential()

    # FoundryToolbox resolves the toolbox endpoint from the environment
    # (TOOLBOX_ENDPOINT, or FOUNDRY_PROJECT_ENDPOINT + TOOLBOX_NAME), authenticates
    # every request with the credential, and transparently forwards the platform
    # per-request call-id to the toolbox. The hosting server enters the agent, which
    # connects the toolbox on first use and closes it at shutdown.
    toolbox = FoundryToolbox(credential)

    # Create the chat client
    client = FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
        credential=credential,
    )

    agent = Agent(
        client=client,
        instructions="You are a friendly assistant. Keep your answers brief.",
        tools=toolbox,
        # History will be managed by the hosting infrastructure, thus there
        # is no need to store history by the service. Learn more at:
        # https://developers.openai.com/api/reference/resources/responses/methods/create
        default_options={"store": False},
    )

    server = ResponsesHostServer(agent)
    await server.run_async()

Esporre le competenze della casella degli strumenti

Una casella degli strumenti può esporre le competenze dell'agente tramite MCP. Impostare load_tools=False quando devono essere visibili solo le competenze, quindi aggiungere la casella degli strumenti come strumento in modo che la sessione MCP si connetta e usi as_skills_provider() come provider di contesto.

import asyncio
import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient, FoundryToolbox, ResponsesHostServer
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()


async def main() -> None:
    credential = DefaultAzureCredential()

    # FoundryToolbox resolves the toolbox endpoint from the environment
    # (TOOLBOX_ENDPOINT, or FOUNDRY_PROJECT_ENDPOINT + TOOLBOX_NAME), authenticates
    # every request with the credential, and forwards the platform per-request
    # call-id. ``load_tools=False`` keeps the toolbox's tools hidden so only its
    # Agent Skills (SEP-2640) are surfaced; passing it via ``tools=`` connects the
    # MCP session that ``as_skills_provider()`` reads from.
    toolbox = FoundryToolbox(credential, load_tools=False)

    # as_skills_provider() discovers skills from skill://index.json on the toolbox
    # MCP session and exposes them as an agent context provider; SKILL.md bodies are
    # fetched on demand via resources/read. disable_load_skill_approval=True registers
    # the load_skill tool with approval_mode="never_require" so this unattended agent
    # can load skills without an approval round-trip -- the Responses host runs the
    # agent without an AgentSession, which the default approval flow requires.
    skills_provider = toolbox.as_skills_provider(disable_load_skill_approval=True)

    client = FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
        credential=credential,
    )

    agent = 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],
        # History will be managed by the hosting infrastructure, thus there
        # is no need to store history by the service. Learn more at:
        # https://developers.openai.com/api/reference/resources/responses/methods/create
        default_options={"store": False},
    )

    server = ResponsesHostServer(agent)
    await server.run_async()

L'approvazione rimane abilitata per impostazione predefinita per le operazioni delle competenze. Disabilitare le singole approvazioni solo per scenari automatici attendibili.

Usare una casella degli strumenti con `FoundryAgent`

Collegare la casella degli strumenti alla definizione prompt o agente ospitato in Foundry. FoundryAgent utilizza la configurazione dello strumento archiviato; il passaggio di un lato client della casella degli strumenti non lo aggiunge all'agente gestito.

Connettersi tramite MCP non elaborato

Usare MCPStreamableHTTPTool direttamente quando l'applicazione non usa il FoundryToolbox wrapper di hosting. Specificare l'endpoint della casella degli strumenti e un token di connessione Entra ID tramite header_provider.

import asyncio
import os
from collections.abc import Callable
from typing import Any, cast

from agent_framework import Agent, MCPStreamableHTTPTool
from agent_framework.foundry import FoundryChatClient
from azure.core.credentials import TokenCredential
from azure.identity import AzureCliCredential, DefaultAzureCredential, get_bearer_token_provider
from dotenv import load_dotenv
def make_toolbox_header_provider(credential: TokenCredential) -> Callable[[dict[str, Any]], dict[str, str]]:
    """Build a header_provider that injects a fresh Azure AI bearer token on every MCP request."""
    get_token = get_bearer_token_provider(credential, "https://ai.azure.com/.default")

    def provide(_kwargs: dict[str, Any]) -> dict[str, str]:
        return {
            "Authorization": f"Bearer {get_token()}",
        }

    return provide


async def main() -> None:
    credential = DefaultAzureCredential()

    toolbox_tool = MCPStreamableHTTPTool(
        name="foundry_toolbox",
        description="Tools exposed by the configured Foundry toolbox",
        url=os.environ["FOUNDRY_TOOLBOX_ENDPOINT"],
        header_provider=make_toolbox_header_provider(credential),
        load_prompts=False,
    )

    async with Agent(
        client=FoundryChatClient(
            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            model=os.environ["FOUNDRY_MODEL"],
            credential=credential,
        ),
        instructions="You are a helpful assistant. Use the available toolbox tools to answer the user.",
        tools=toolbox_tool,
    ) as agent:
        query = "What tools do you have access to?"
        print(f"User: {query}")
        result = await agent.run(query)
        print(f"Assistant: {result}")

L'esempio di livello inferiore usa FOUNDRY_TOOLBOX_ENDPOINT. L'esempio di competenze della casella degli strumenti usa FOUNDRY_TOOLBOX_MCP_SERVER_URL; questi nomi appartengono a tali esempi e sono separati dalle FoundryToolbox impostazioni e TOOLBOX_NAME della TOOLBOX_ENDPOINT classe.

Limitations

Gli strumenti MCP all'interno di una casella degli strumenti usano l'autenticazione lato server tramite un foundry project_connection_id. Il client di Agent Framework non contiene il token di connessione MCP upstream.
L'utilizzo di una casella degli strumenti come server MCP richiede l'autenticazione lato client Entra ID per l'endpoint della casella degli strumenti.
Le risposte del flusso di consenso, CONSENT_REQUIRED ad esempio vengono gestite durante l'esecuzione dell'agente, non mentre viene creata la connessione casella degli strumenti.

Samples

Sample	Description
foundry_toolbox/main.py	`FoundryToolbox` con un agente risposte ospitato
foundry_toolbox_mcp_skills/main.py	Competenze dell'agente supportate dalla casella degli strumenti
foundry_chat_client_with_toolbox.py	Utilizzo di MCP con Toolbox `MCPStreamableHTTPTool`
foundry_chat_client_with_toolbox_skills.py	Configurazione delle competenze supportate dalla casella degli strumenti
invoke_foundry_toolbox_mcp	Consumo mcp sul lato flusso di lavoro

Go non espone attualmente un helper della casella degli strumenti Foundry. Configurare le caselle degli strumenti tramite Foundry e usare dichiarazioni di strumenti locali o ospitate supportate per gli agenti Go.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-08-13