Cuadro de herramientas de Microsoft Foundry

Un Microsoft Foundry Toolbox es un paquete del lado del servidor con nombre y versión 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 en la 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 uso de Toolbox. Cree y actualice las versiones del Cuadro de herramientas a través del portal de Foundry o del azure-ai-projects SDK.

Important

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

Para un FoundryAgent administrado por el servicio, adjunta Toolbox a la definición del agente en Foundry.

Para un agente alojado creado con Microsoft Agent Framework, use AddFoundryToolboxes de Microsoft.Agents.AI.Foundry.Hosting, como se muestra en el ejemplo siguiente.

Use un proyecto web de .NET 10 con usos implícitos habilitados, versiones coincidentes de Microsoft.Agents.AI.Foundry y Microsoft.Agents.AI.Foundry.Hostingy DotNetEnv. Establezca TOOLBOX_NAME en un cuadro de herramientas existente y AZURE_AI_MODEL_DEPLOYMENT_NAME en la implementación del modelo. Foundry proporciona FOUNDRY_PROJECT_ENDPOINT al host implementado. Para el acceso al modelo local, establezca AZURE_AI_PROJECT_ENDPOINT e inicie sesión con CLI de Azure. La integración de alojamiento carga las herramientas de la caja de herramientas cuando FOUNDRY_PROJECT_ENDPOINT está disponible.

using Azure.AI.Projects;
using Azure.Identity;
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")
    ?? System.Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException(
        "Neither FOUNDRY_PROJECT_ENDPOINT (platform-injected in hosted runtime) " +
        "nor AZURE_AI_PROJECT_ENDPOINT (local-dev convention) is set.");
string deploymentName = FirstNonBlank(
    System.Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME"),
    System.Environment.GetEnvironmentVariable("FOUNDRY_MODEL"),
    "gpt-4o")!;
string toolboxName = FirstNonBlank(
    System.Environment.GetEnvironmentVariable("TOOLBOX_NAME"),
    "my-toolset")!;

var credential = new DefaultAzureCredential();

AIAgent agent = new AIProjectClient(new Uri(endpoint), credential)
    .AsAIAgent(
        model: deploymentName,
        instructions: """
            You are a helpful assistant with access to tools provided by the Foundry Toolbox.
            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");

var builder = WebApplication.CreateBuilder(args);

// Register the agent and response handler
builder.Services.AddFoundryResponses(agent);

builder.Services.AddFoundryToolboxes(credential, toolboxName);

var app = builder.Build();
app.MapFoundryResponses();


app.Run();

static string? FirstNonBlank(params string?[] candidates) =>
    Array.Find(candidates, candidate => !string.IsNullOrWhiteSpace(candidate));

El mismo registro de alojamiento admite herramientas configuradas para el consentimiento de OAuth por cada usuario en sus conexiones del conjunto de herramientas. Los usuarios siguen necesitando los permisos y el consentimiento necesarios; no se necesita ningún bloque de registro de host independiente.

Para ver los archivos de proyecto e instrucciones de implementación, consulte Hosted-Toolbox. Para la configuración del consentimiento por usuario, consulte Hosted-Toolbox-AuthPaths.

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

Establecer un punto de conexión MCP explícito de Toolbox:

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

O deja que FoundryToolbox construya el extremo:

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

Los ejemplos del agente hospedado también 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. En un agente de respuestas hospedado, cree el Cuadro de herramientas, su cliente y su credencial dentro del generador de agentes con ámbito de solicitud. El escritor de MCP captura el contexto de solicitud cuando se conecta, por lo que no comparta un cuadro de herramientas conectado entre autores de llamadas.

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 tools inside this request so the MCP writer captures its call ID."""
    endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    model = 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()

Exponer las habilidades de Toolbox

Una caja de herramientas puede poner las capacidades del agente a disposición 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 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 writer within this request."""
    endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    model = 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()

La aprobación permanece habilitada de forma predeterminada para las operaciones de las habilidades. Desactive las aprobaciones individuales solo en escenarios de confianza y sin supervisión. Mantenga el cuadro de herramientas y el proveedor de aptitudes en el mismo generador de solicitudes, por lo que ambos usan la misma sesión de MCP y se eliminan juntos.

Uso de un cuadro de herramientas con FoundryAgent

Adjunte Toolbox a la definición de Prompt o Hosted Agent en Foundry. FoundryAgent utiliza esa configuración de herramientas almacenada; pasar un Toolbox del lado del cliente no lo añade al agente administrado.

Conéctate a través de MCP con FoundryToolbox

Usa FoundryToolbox con ResponsesHostServer para conectar un agente alojado al punto de conexión MCP de Toolbox. El contenedor autentica las solicitudes MCP y reenvía el contexto del autor de llamada de la solicitud hospedada actual para el paso de identidad por usuario. Crear la conexión dentro de la agent factoría para que cada solicitud reciba su propio contexto de invocación.

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 tools inside this request so the MCP writer captures its call ID."""
    endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    model = 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()

Establezca TOOLBOX_ENDPOINT, o establezca ambos FOUNDRY_PROJECT_ENDPOINT y TOOLBOX_NAME, como se describe en Configurar la caja de herramientas. El ejemplo usa AZURE_AI_MODEL_DEPLOYMENT_NAME para la implementación del modelo.

Limitations

  • Las herramientas MCP dentro de un Toolbox utilizan la autenticación del lado del servidor a través de un Foundry project_connection_id; el cliente de Agent Framework no conserva el token de portador MCP de origen.
  • Para utilizar un Toolbox como servidor MCP, se requiere la autenticación de Entra ID del lado del cliente para el punto de conexión de Toolbox.
  • 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 Habilidades del agente respaldadas por la caja 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 ofrece actualmente una utilidad de Foundry Toolbox. Configure conjuntos de herramientas a través de Foundry y use declaraciones de herramientas locales o alojadas compatibles para agentes de Go.

  • Last updated on