Cuadro de herramientas de Microsoft Foundry

Un Microsoft Foundry Toolbox es un conjunto con versiones con nombre de configuraciones de herramientas hospedadas, como el intérprete de código, la búsqueda de archivos, la generación de imágenes, MCP y la búsqueda web. Los cuadros de herramientas le permiten administrar la configuración de herramientas una vez en Foundry y reutilizarla entre agentes.

Agent Framework cubre el consumo del cuadro de herramientas. Cree y actualice las versiones del Cuadro de herramientas a través del portal de Foundry o del azure-ai-projects SDK.

Importante

FoundryToolbox lo proporciona el paquete beta agent-framework-foundry-hosting y puede cambiar antes de la versión estable.

Para un servicio administrado FoundryAgent, adjunte el Cuadro de herramientas a la definición del agente en Foundry. Actualmente no se documenta la guía de consumo del cuadro de herramientas de .NET del lado cliente.

Instalación de los paquetes

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

FoundryToolbox se importa desde agent_framework.foundry y se proporciona mediante agent-framework-foundry-hosting.

Configurar el cuadro de herramientas

Establezca un punto de conexión mcP explícito del cuadro de herramientas:

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

O bien, vamos a FoundryToolbox construir el punto de conexión:

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

Los ejemplos del agente hospedado también se usan AZURE_AI_MODEL_DEPLOYMENT_NAME para FoundryChatClient.

Uso FoundryToolbox con un agente hospedado

FoundryToolboxresuelve su punto de conexión, autentica cada solicitud de MCP con la credencial de Azure proporcionada, reenvía el identificador de llamada por solicitud de Foundry y participa en el ciclo de vida de conexión del 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()

Exponer aptitudes del cuadro de herramientas

Un cuadro de herramientas puede exponer aptitudes del agente a través de MCP. Establezca load_tools=False cuando solo las aptitudes sean visibles para el modelo y agregue el Cuadro de herramientas como una herramienta para que su sesión de MCP se conecte y use as_skills_provider() como proveedor de contextos.

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

La aprobación permanece habilitada de forma predeterminada para las operaciones de aptitud. Deshabilite las aprobaciones individuales solo para escenarios de confianza y desatendidos.

Uso de un cuadro de herramientas con FoundryAgent

Adjunte el cuadro de herramientas a la definición Del agente hospedado o de solicitud en Foundry. FoundryAgent utiliza esa configuración de herramienta almacenada; Pasar un lado cliente del Cuadro de herramientas no lo agrega al agente administrado.

Conexión a través de MCP sin procesar

Use MCPStreamableHTTPTool directamente cuando la aplicación no use el FoundryToolbox contenedor de hospedaje. Proporcione el punto de conexión del cuadro de herramientas y un token de portador de Entra ID a través header_providerde .

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}")

En el ejemplo de nivel inferior se usa FOUNDRY_TOOLBOX_ENDPOINT. El ejemplo de aptitudes del cuadro de herramientas usa FOUNDRY_TOOLBOX_MCP_SERVER_URL; estos nombres pertenecen a esos ejemplos y son independientes de la configuración y TOOLBOX_NAME de TOOLBOX_ENDPOINT la FoundryToolbox clase .

Limitations

  • Las herramientas de MCP dentro de un cuadro de herramientas usan la autenticación del lado servidor a través de foundry project_connection_id; el cliente de Agent Framework no contiene el token de portador mcP ascendente.
  • El consumo de un cuadro de herramientas como servidor MCP requiere la autenticación del lado cliente Entra ID para el punto de conexión del cuadro de herramientas.
  • Las respuestas de flujo de consentimiento, como CONSENT_REQUIRED , por ejemplo, se controlan mientras se ejecuta el agente, no mientras se crea la conexión del Cuadro de herramientas.

Samples

Sample Description
foundry_toolbox/main.py FoundryToolbox con un agente de respuestas hospedado
foundry_toolbox_mcp_skills/main.py Aptitudes del agente respaldadas por el cuadro de herramientas
foundry_chat_client_with_toolbox.py Consumo de MCP del cuadro de herramientas con MCPStreamableHTTPTool
foundry_chat_client_with_toolbox_skills.py Configuración de habilidades basada en la caja de herramientas
invoke_foundry_toolbox_mcp Consumo de MCP en el lado del flujo de trabajo

Go no expone actualmente un asistente de Foundry Toolbox. Configure cuadros de herramientas a través de Foundry y use declaraciones de herramientas locales o hospedadas admitidas para agentes de Go.

  • Last updated on