Cuadro de herramientas de Microsoft Foundry

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 una caja de herramientas existente y FOUNDRY_MODEL en la implementación del modelo. Foundry proporciona FOUNDRY_PROJECT_ENDPOINT al host implementado. Para el acceso al modelo local, establezca FOUNDRY_PROJECT_ENDPOINT e inicie sesión con CLI de Azure. Las implementaciones hospedadas recurren al AZURE_AI_MODEL_DEPLOYMENT_NAME administrado por azd. La integración de alojamiento carga las herramientas de la caja de herramientas cuando FOUNDRY_PROJECT_ENDPOINT está disponible.

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

El mismo registro de alojamiento admite herramientas configuradas para el consentimiento OAuth por usuario en las conexiones a la caja 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 de agente hospedado dan prioridad al FOUNDRY_MODEL localmente y recurren al AZURE_AI_MODEL_DEPLOYMENT_NAME administrado por azd cuando están hospedados.

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. Resuelve los encabezados de la plataforma en cada límite de la operación y vuelve a conectar su sesión de MCP cuando cambia la identidad de solicitud efectiva. Por lo tanto, una Toolbox de larga duración no conserva el ID de llamada de un llamante anterior.

En el ejemplo se crea el Toolbox, el cliente y las credenciales dentro de la fábrica de agentes con ámbito de solicitud para garantizar una propiedad y limpieza deterministas. Utilice este patrón de fábrica cuando los recursos relacionados sean propiedad de la solicitud, pero no es necesario únicamente para mantener actualizados los ID de llamada de 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()

Cuando Toolbox Code Interpreter genera un archivo y la respuesta del asistente nombra ese archivo, el adaptador Responses alojado emite una anotación nativa container_file_citation con los identificadores del contenedor y del archivo. Los clientes de respuestas pueden utilizar esos ID para detectar y descargar el archivo generado a través de la API de archivos del contenedor.

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

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 Toolbox y su proveedor de habilidades juntos para que ambos usen la misma sesión de MCP. Para un Toolbox de larga duración, la caché de detección de habilidades se reemplaza cuando cambia la identidad efectiva del encabezado de plataforma. Un header_provider personalizado utilizado con habilidades debe resolverse a partir del estado ambiental, como un cierre o ContextVar, ya que las lecturas de habilidades y recursos no reciben argumentos de tiempo de ejecución de la función.

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 envoltorio autentica las solicitudes MCP y reenvía el contexto del solicitante de la solicitud hospedada actual para el paso de identidad por usuario. La fábrica agent con ámbito de solicitud sigue siendo la opción más sencilla cuando el cliente, las credenciales y Toolbox necesitan un único límite de limpieza. También se admite una Toolbox de larga duración, que se vuelve a conectar antes de una operación cuando cambia la identidad del encabezado de la plataforma.

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

Establezca TOOLBOX_ENDPOINT, o establezca ambos FOUNDRY_PROJECT_ENDPOINT y TOOLBOX_NAME, como se describe en Configurar la caja de herramientas. Establece FOUNDRY_MODEL para ejecuciones locales; las implementaciones hospedadas recurren a la opción AZURE_AI_MODEL_DEPLOYMENT_NAME administrada por azd.

Control de solicitudes de consentimiento de OAuth

Cuando una operación de Toolbox o MCP requiere el consentimiento de OAuth, las llamadas FoundryAgent y FoundryChatClient con y sin streaming devuelven Content(type="oauth_consent_request") con el vínculo de consentimiento en lugar de un mensaje de asistente vacío. Gestiona este contenido como una solicitud de entrada de usuario y presentar su consent_link al usuario.

El cliente solo muestra vínculos con un esquema HTTPS y un host válido. Los vínculos que faltan o no son válidos se omiten y registran.

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

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.