Casella degli strumenti Microsoft Foundry

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 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 utilizzano anch'essi AZURE_AI_MODEL_DEPLOYMENT_NAME 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()

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 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 approvazioni individuali solo per scenari attendibili non presidiati.

Usare una casella degli strumenti con FoundryAgent

Collega la Toolbox alla definizione del prompt o dell'agente ospitato in Foundry. FoundryAgent utilizza la configurazione dello strumento memorizzata; passare una Toolbox lato client non la 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 di Toolbox e un token bearer di 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 delle abilità di Toolbox usa FOUNDRY_TOOLBOX_MCP_SERVER_URL; questi nomi appartengono a tali esempi e sono distinti dalle impostazioni TOOLBOX_ENDPOINT e TOOLBOX_NAME della classe FoundryToolbox.

Limitations

• Gli strumenti MCP in una Toolbox usano l'autenticazione lato server tramite un Foundry project_connection_id; il client di Agent Framework non detiene il token bearer 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 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.