Microsoft Foundry

Introducción

Agregue los paquetes NuGet necesarios al proyecto.

dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.Foundry --prerelease

Dos tipos de agente

La integración de Microsoft Foundry expone dos patrones de uso distintos:

Tipo	Tipo producido	Descripción	Se utiliza cuando
Agente de respuestas	ChatClientAgent	La aplicación proporciona mediante programación un modelo, instrucciones y herramientas en tiempo de ejecución a través de AIProjectClient.AsAIAgent(...). No se crea ningún recurso de agente del lado servidor.	Posee la definición del agente y desea una configuración sencilla y flexible. Este es el patrón que se usa en la mayoría de los ejemplos.
Agente de fundición (versionado)	FoundryAgent	Administrado por el servidor: las definiciones de agente se crean y versionan a través del portal de Foundry o mediante programación a través de AIProjectClient.AgentAdministrationClient. Pase ProjectsAgentVersion o ProjectsAgentRecord o AgentReference a AIProjectClient.AsAIAgent(...).	Necesita definiciones de agente estrictas y con versiones administradas en el portal de Foundry, a través de las API de servicio.

Agente de respuestas (inferencia directa)

Use AsAIAgent en AIProjectClient directamente con un modelo e instrucciones. Este es el punto de partida recomendado para la mayoría de los escenarios.

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

AIAgent agent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
        .AsAIAgent(
            model: "gpt-4o-mini",
            name: "Joker",
            instructions: "You are good at telling jokes.");

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

Esta ruta de acceso es code-first y no crea un recurso de agente administrado por el servidor.

Agente de Foundry (con versiones)

Use las API nativas AIProjectClient.AgentAdministrationClient del SDK de proyectos de IA para recuperar los recursos del agente con versiones y, a continuación, encapsularlas con AsAIAgent. Los agentes se pueden crear y configurar directamente en el portal de Foundry o mediante programación a través de AIProjectClient.AgentAdministrationClient.

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry;

var aiProjectClient = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential());

// Retrieve an existing agent by name (uses the latest version automatically)
ProjectsAgentRecord jokerRecord = await aiProjectClient.AgentAdministrationClient.GetAgentAsync("Joker");
FoundryAgent agent = aiProjectClient.AsAIAgent(jokerRecord);

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

Uso del agente

Tanto ChatClientAgent (Respuestas) como FoundryAgent (versionadas) son instancias estándar AIAgent, y admiten todas las operaciones estándar, incluidas las sesiones, las herramientas, el middleware y el streaming.

AgentSession session = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("Tell me a joke.", session));
Console.WriteLine(await agent.RunAsync("Now make it funnier.", session));

Para obtener más información sobre cómo ejecutar e interactuar con agentes, consulte los tutoriales de introducción al agente.

Herramientas

Los agentes de Foundry creados desde AIProjectClient.AsAIAgent(...) (la vía Responses) admiten el conjunto estándar de herramientas de Agent Framework — consulte la descripción general de las herramientas para obtener la lista completa y la matriz de características compatibles. Para los agentes de Foundry cargados desde una definición versionada del agente (FoundryAgent), las herramientas del agente pertenecen a la definición del agente de Foundry, no al cliente.

Herramienta	Notas
Herramientas de funciones	Supported.
Aprobación de herramientas	Supported. Proporcionado por el cliente de chat de invocación de funciones del marco.
Intérprete de código	Supported.
Búsqueda de archivos	Supported.
Herramientas de MCP hospedadas	Supported.
Herramientas de MCP locales	Supported.
Cajas de herramientas de Foundry	Supported.

Cajas de herramientas

Fundición en Python

En Python, todos los clientes específicos de Foundry ahora residen en agent_framework.foundry.

• agent-framework-foundry proporciona los conectores de Cloud Foundry: FoundryChatClient, FoundryAgent, FoundryEmbeddingClienty FoundryMemoryProvider.
• agent-framework-foundry-local proporciona FoundryLocalClient para la ejecución del modelo local.

Patrones de chat y agentes de Foundry en Python

Escenario	Python forma	Se utiliza cuando
Inferencia sin formato con el punto de conexión de respuestas de Foundry	Agent(client=FoundryChatClient(...))	Su aplicación posee la definición del agente, las herramientas y el ciclo de conversación, y desea desplegar un modelo en un proyecto de Foundry.
Agentes administrados por el servicio de agente de Foundry	FoundryAgent(...)	Quiere conectarse a un PromptAgent o HostedAgent creado y configurado en el portal de Foundry o a través de las API de servicios.

Instalación

pip install agent-framework-foundry
pip install azure-identity

El mismo agent-framework-foundry paquete también incluye FoundryEmbeddingClient para las incrustaciones de modelos de Foundry-endpoint.

Configuración

FoundryChatClient

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_MODEL="gpt-4o-mini"

FoundryAgent

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_AGENT_NAME="my-agent"
FOUNDRY_AGENT_VERSION="1.0"

Usa FOUNDRY_AGENT_VERSION para agentes de entrada. Los agentes hospedados pueden omitirlo.

FoundryEmbeddingClient

FOUNDRY_MODELS_ENDPOINT="https://<apim-instance>.azure-api.net/<foundry-instance>/models"
FOUNDRY_MODELS_API_KEY="<api-key>"
FOUNDRY_EMBEDDING_MODEL="text-embedding-3-small"
FOUNDRY_IMAGE_EMBEDDING_MODEL="Cohere-embed-v3-english"  # optional

FoundryChatClient y FoundryAgent usan el punto de conexión del proyecto. FoundryEmbeddingClient usa el punto de conexión de modelos separados.

Elegir el cliente Python adecuado

Escenario	Cliente preferido	Notas
Recurso de Azure OpenAI	OpenAIChatCompletionClient / OpenAIChatClient	Usa la página del proveedor de OpenAI.
inferencia del proyecto Foundry de Microsoft	Agent(client=FoundryChatClient(...))	Usa el endpoint de Foundry Responses.
Agente administrado del servicio Foundry de Microsoft	FoundryAgent	Recomendado para Prompt Agents y HostedAgents.
vectores de inserción de puntos finales de modelos de Microsoft Foundry	FoundryEmbeddingClient	Usa FOUNDRY_MODELS_ENDPOINT más FOUNDRY_EMBEDDING_MODEL / FOUNDRY_IMAGE_EMBEDDING_MODEL.
Tiempo de ejecución local de Foundry	Agent(client=FoundryLocalClient(...))	Consulte Foundry Local.

Creación de un agente con FoundryChatClient

FoundryChatClient se conecta a un modelo implementado en un proyecto Foundry y usa el endpoint Responses. Combínalo con un estándar Agent cuando tu aplicación deba gestionar instrucciones, herramientas y el manejo de sesiones.

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

agent = Agent(
    client=FoundryChatClient(
        project_endpoint="https://your-project.services.ai.azure.com",
        model="gpt-4o-mini",
        credential=AzureCliCredential(),
    ),
    name="FoundryWeatherAgent",
    instructions="You are a helpful assistant.",
)

FoundryChatClient es la ruta de acceso de Python foundry-first para la inferencia directa y admite herramientas, salidas estructuradas y streaming.

Herramientas

FoundryChatClient envía métodos de fábrica estáticos para cada herramienta foundry hospedada. Las factorías devuelven objetos de herramienta del SDK que se pasan a tools= en Agent o directamente a client.get_response(..., tools=[...]). En el caso de FoundryAgent, las herramientas del agente se encuentran en la propia definición del agente de Foundry — consulta Qué funciona y qué no con FoundryAgent.

Los generadores son métodos de clase, por lo que no necesita una instancia para crear una herramienta:

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

agent = Agent(
    client=FoundryChatClient(credential=AzureCliCredential()),
    instructions="You can search the web and run code.",
    tools=[
        FoundryChatClient.get_web_search_tool(),
        FoundryChatClient.get_code_interpreter_tool(),
    ],
)

Soporte técnico de herramientas

En la tabla siguiente se enumeran todas las herramientas que expone hoy en día la Python FoundryChatClient. FoundryAgent funciona con las mismas herramientas, pero deben configurarse en la definición del agente Foundry en lugar de pasar código.

Herramienta	Fábrica en FoundryChatClient	Situación	Detalle
Herramientas de funciones	n/a — pase cualquier función invocable de Python o @ai_function	GA	Se invoca localmente en el proceso de Python.
Aprobación de herramientas	n/a — envuelve las herramientas existentes	GA	Funciona con las herramientas de funciones y MCP hospedadas.
Intérprete de código	get_code_interpreter_tool	GA	Ejecución de código en entorno aislado en Foundry.
Búsqueda de archivos	get_file_search_tool	GA	Buscar archivos cargados en los almacenes vectoriales de Foundry.
Búsqueda web	get_web_search_tool	GA	Fundamentación web respaldada por Bing y administrada por Microsoft. Solo modelos de Azure OpenAI.
Generación de imágenes	get_image_generation_tool	GA	Generación de imágenes hospedada en Foundry.
MCP hospedado	get_mcp_tool	GA	Servidor MCP remoto invocado por Foundry.
Local MCP	n/a — use MCPStreamableHTTPTool / MCPStdioTool	GA	Se ejecuta en el proceso; funciona con cualquier cliente.
Cajas de herramientas de Foundry	MCPStreamableHTTPTool al punto de conexión mcP del cuadro de herramientas	GA	Consumido mediante MCP de FoundryChatClient; adjunto del lado del servidor en FoundryAgent.
Conexión a tierra Bing	get_bing_grounding_tool	Experimental	Traiga su propio elemento Grounding con el recurso bing Search.
Bing Custom Search	get_bing_custom_search_tool	Preview	Fundamentación de Bing limitada a una lista de dominios seleccionada.
Búsqueda de Azure AI	get_azure_ai_search_tool	Experimental	Busque un índice Búsqueda de Azure AI a través de una conexión Foundry.
SharePoint	get_sharepoint_tool	Preview	Base las respuestas en el contenido de SharePoint.
Microsoft Fabric	get_fabric_tool	Preview	Consultar un agente de datos de Fabric.
Búsqueda de memoria	get_memory_search_tool	Preview	Busque un almacén de memoria administrado por Foundry.
Uso del ordenador	get_computer_use_tool	Preview	Deje que el agente impulse un entorno de escritorio o explorador.
Automatización del explorador	get_browser_automation_tool	Preview	Conduce un explorador a través de una conexión Azure Playwright.
Agente a Agente (A2A)	get_a2a_tool	Preview	Llame a otro agente de A2A como herramienta.

Variantes de búsqueda web

Foundry ofrece tres opciones de fundamentación respaldadas por Bing. Elija el que coincida con su escenario:

• get_web_search_tool (GA): valor predeterminado de configuración cero; Recurso de Bing administrado por Microsoft. Solo modelos de Azure OpenAI. Limitado a user_location y search_context_size.
• get_bing_grounding_tool (experimental) — use su propio recurso de Grounding con Bing Search de Azure. Admite count, freshness, market, set_lang y modelos Foundry que no son de OpenAI.
• get_bing_custom_search_tool (versión preliminar) — use su propia instancia de Bing Custom Search para restringir la fundamentación a un conjunto seleccionado de dominios.

Los tres envían datos de búsqueda fuera del límite de cumplimiento de Azure. Consulte la descripción general de web grounding para ver la comparación completa.

client = FoundryChatClient(credential=AzureCliCredential())

# Default (GA): minimal configuration
web_search = client.get_web_search_tool(
    user_location={"city": "Amsterdam", "country": "NL"},
    search_context_size="medium",
)

Generación de imágenes

get_image_generation_tool configura la herramienta de generación de imágenes hospedada de Foundry. El modelo genera contenido de imagen en la respuesta: no hay archivos adicionales que administrar.

image_gen = FoundryChatClient.get_image_generation_tool(
    model="gpt-image-1",
    size="1024x1024",
    output_format="png",
    quality="high",
)

Fundamentación de Bing

get_bing_grounding_tool integra la herramienta Grounding with Bing Search Foundry. Usted mismo crea el recurso Grounding with Bing Search y lo agrega como conexión del proyecto de Foundry; a continuación, proporciona el identificador de la conexión.

bing = FoundryChatClient.get_bing_grounding_tool(
    connection_id="/subscriptions/.../connections/my-bing",
    market="en-US",
    freshness="Day",
    count=10,
)

Búsqueda personalizada de Bing

get_bing_custom_search_tool restringe la fundamentación a la lista de elementos permitidos definida en un recurso de Bing Custom Search.

bing_custom = FoundryChatClient.get_bing_custom_search_tool(
    connection_id="/subscriptions/.../connections/my-bing-custom",
    instance_name="docs-only",
    market="en-US",
)

Búsqueda de Azure AI

get_azure_ai_search_tool permite al agente consultar un índice Búsqueda de Azure AI a través de una conexión de proyecto Foundry.

ai_search = FoundryChatClient.get_azure_ai_search_tool(
    index_connection_id="/subscriptions/.../connections/my-search",
    index_name="product-docs",
    query_type="vector_semantic_hybrid",
    top_k=5,
)

SharePoint

get_sharepoint_tool basa las respuestas en contenido de SharePoint accesible a través de una conexión de SharePoint de Foundry.

sharepoint = FoundryChatClient.get_sharepoint_tool(
    connection_id="/subscriptions/.../connections/my-sharepoint",
)

Microsoft Fabric

get_fabric_tool conecta el agente a un agente de datos de Microsoft Fabric mediante una conexión de Foundry para que el agente pueda responder a preguntas sobre tus datos de Fabric.

fabric = FoundryChatClient.get_fabric_tool(
    connection_id="/subscriptions/.../connections/my-fabric",
)

Búsqueda de memoria

get_memory_search_tool permite que el agente busque en un almacén de memoria administrado por Foundry, opcionalmente limitado a un usuario o inquilino.

memory = FoundryChatClient.get_memory_search_tool(
    memory_store_name="user-preferences",
    scope="{{$userId}}",
)

Uso del equipo

get_computer_use_tool configura la herramienta de vista previa «Uso del ordenador»: el modelo puede controlar un entorno de escritorio o navegador mediante acciones de puntero y teclado.

computer = FoundryChatClient.get_computer_use_tool(
    environment="browser",
    display_width=1280,
    display_height=800,
)

Automatización de explorador

get_browser_automation_tool conectan el agente a un recurso Azure Playwright Testing a través de una conexión Foundry. El agente puede controlar un navegador real mediante Playwright.

browser = FoundryChatClient.get_browser_automation_tool(
    connection_id="/subscriptions/.../connections/my-playwright",
)

Agente a Agente (A2A)

get_a2a_tool expone un agente A2A remoto como herramienta para que un agente Foundry pueda invocarlo. Proporcione una base_url (y opcionalmente agent_card_path) o una project_connection_id para una conexión A2A almacenada.

a2a = FoundryChatClient.get_a2a_tool(
    base_url="https://remote-agent.example.com",
    agent_card_path="/.well-known/agent-card.json",
)

Para consultar la guía general de A2A — descubrimiento, sesiones y transmisión —, consulte la página del proveedor Agent-to-Agent.

Creación de incrustaciones con FoundryEmbeddingClient

Use FoundryEmbeddingClient cuando desee usar incrustaciones de texto o imagen desde un punto de conexión de modelos de Foundry.

from agent_framework.foundry import FoundryEmbeddingClient

async with FoundryEmbeddingClient() as client:
    result = await client.get_embeddings(["hello from Agent Framework"])
    print(result[0].dimensions)

Conéctate a un agente gestionado por el servicio con FoundryAgent

Use FoundryAgent cuando la definición del agente resida en Foundry. Esta es la API de Python recomendada para Prompt Agents y HostedAgents.

from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential

agent = FoundryAgent(
    project_endpoint="https://your-project.services.ai.azure.com",
    agent_name="my-prompt-agent",
    agent_version="1.0",
    credential=AzureCliCredential(),
)

En el caso de HostedAgent, omita agent_version y use el nombre del agente hospedado en su lugar.

Lo que funciona y lo que no funciona con FoundryAgent

FoundryAgent se conecta a un agente que ya existe en Foundry (un Prompt Agent o un agente alojado). La definición del agente (sus instrucciones y su configuración de herramientas) reside en Foundry, no en el código de Python. Esto significa que varias características de nivel Agent se comportan de forma distinta a como lo hacen con Agent(client=FoundryChatClient(...)) u otros agentes basados en clientes de chat.

Herramientas

Tipo de herramienta pasado a FoundryAgent(...)	Comportamiento
FunctionTool (un elemento invocable local de Python)	Se admite, pero solo si la definición de la función correspondiente ya está definida en el agente de Foundry. El entorno de ejecución de Foundry decide qué herramientas exponer al modelo en función de la definición del agente. Cuando el modelo llama a una función, Foundry devuelve una llamada a una herramienta al cliente y el framework invoca el elemento invocable local de Python en tu proceso (no en Foundry) y luego envía el resultado de vuelta. Pasar un FunctionTool del lado del cliente solo proporciona esa implementación local: si la función no está declarada en el agente Foundry, el modelo nunca la llamará.
Herramientas hospedadas (búsqueda web, intérprete de código, búsqueda de archivos, MCP, generación de imágenes, etc.)	Ignorado. Deben configurarse en la propia definición del agente foundry, ya sea en el portal de Foundry o a través de las API de servicio. Pasarlas del lado del cliente no tiene ningún efecto porque el entorno de ejecución de Foundry solo conoce las herramientas adjuntas a la definición del agente.

En resumen: no puede agregar nuevas herramientas en tiempo de construcción. Todas las herramientas a las que puede llamar el modelo (incluidas las funciones Python locales) ya deben formar parte de la definición del agente en Foundry. Pasar un FunctionTool a FoundryAgent(...) solo proporciona la implementación local que se ejecuta en el proceso de Python cuando se llama a la función definida por Foundry; no registra una nueva herramienta con el agente.

Proveedores de contexto

context_providers=[...] tiene compatibilidad parcial. Si un proveedor de contexto funciona depende de lo que intenta hacer el proveedor:

Comportamiento del proveedor de contexto	Funciona con FoundryAgent?
Agrega contexto adicional como mensajes (por ejemplo, memoria recuperada, fragmentos de código RAG, información de perfil de usuario)	Yes. El contexto inyectado se reenvía con la solicitud.
Persiste u observa la conversación (por ejemplo, escribiendo las intervenciones en un almacenamiento externo)	Yes. Se ejecuta localmente alrededor de la solicitud o respuesta.
Agrega herramientas dinámicamente (por ejemplo, SkillsProvider, o cualquier proveedor que devuelva herramientas de invoking())	No, a menos que las herramientas ya formen parte de la definición del agente de Foundry. El tiempo de ejecución de Foundry ejecuta el modelo en las herramientas asociadas al agente en Foundry; Las herramientas que solo existen localmente no se exponen al modelo y no se invocarán.

Si necesita selección dinámica de herramientas, carga de habilidades o cualquier otro comportamiento que dependa de que se añadan herramientas en tiempo de ejecución, utilice Agent(client=FoundryChatClient(...)) en su lugar; esa vía gestiona el bucle del modelo localmente y admite el conjunto completo de tipos de herramientas y proveedores de contexto con capacidad para añadir herramientas.

Opciones de ejecución (default_options y agent.run(...) opciones)

Las opciones que pases a FoundryAgent(default_options=...) o a agent.run(..., **options) (como temperature, top_p, max_tokens, instructions, tool_choice, response_format, metadata, etc.) no se aplican todas. Dado que la definición del agente en Foundry es la fuente de la verdad, muchas opciones se omiten silenciosamente.

Para Prompt Agents, el marco de trabajo elimina o reemplaza explícitamente lo siguiente antes de enviar la solicitud a la API de respuestas de Foundry:

Opción	Comportamiento con FoundryAgent
model	Ignorado. El modelo se obtiene de la definición del agente de Foundry.
tools, , tool_choice, parallel_tool_calls	Se ha eliminado del cuerpo de la solicitud. Las herramientas deben declararse en la definición del agente Foundry (consulte la sección anterior). FunctionTool los elementos invocables siguen vinculados localmente para invocar funciones, pero la lista de herramientas en sí no se envía al servicio.
instructions y mensajes del sistema o del desarrollador	Ignorado. Las instrucciones propias del agente de Foundry son autoritativas. Los mensajes del sistema o del desarrollador se quitan de la lista de mensajes antes de enviar la solicitud.
conversation_id	Se usa, y se asocia con la sesión del agente de Foundry cuando se refiere a una.
extra_body	Reenviado, fusionado con la carga útil del conjunto de frameworks agent_reference.
Parámetros de muestreo (temperature, top_p, max_tokens, seed, frequency_penalty, presence_penalty, stop...), metadata, user, store, response_format, etc.	Reenviado a la API de respuestas. Que Foundry las aplique realmente depende de la configuración del agente y del modelo —la definición del agente puede sobrescribirlas o restringirlas—, así que no des por hecho que surtirán efecto en un Prompt Agent.

En el caso de los agentes hospedados, se aplica la misma eliminación del lado cliente, pero todo lo que va más allá de eso depende de lo que implementa el agente hospedado específico. Un agente hospedado puede aceptar, omitir o reinterpretar cualquier opción que se reenvíe. Considere las opciones en tiempo de ejecución como orientativas y verifique el comportamiento real con el agente hospedado al que está llamando.

Conexión a un agente de Foundry desplegado (hospedado)

Para HostedAgents que ejecutan sesiones en el servicio (/agents/{name}/sessions), use FoundryAgent con allow_preview=True para habilitar la superficie de Responses en vista previa:

from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential

agent = FoundryAgent(
    agent_name="my-hosted-agent",
    credential=AzureCliCredential(),
    allow_preview=True,
)

Cuando necesite administrar la sesión de servicio subyacente usted mismo (por ejemplo, para enlazar una sesión a un inquilino o usuario específico), cree la sesión a través de la API de vista previa AIProjectClient y encapsularla con agent.get_session(...):

from azure.ai.projects.aio import AIProjectClient
from azure.ai.projects.models import VersionRefIndicator

service_session = await project_client.beta.agents.create_session(
    agent_name="my-hosted-agent",
    isolation_key="user-123",
    version_indicator=VersionRefIndicator(agent_version="1.0"),
)
session = agent.get_session(service_session.agent_session_id)

response = await agent.run("Hello!", session=session)

Uso del agente

Tanto FoundryChatClient como FoundryAgent se integran con la experiencia estándar de Python Agent, incluidas las llamadas a herramientas, las sesiones y las respuestas de streaming. En el caso de los entornos de ejecución locales, use la página del proveedor local de Foundry independiente.

Cajas de herramientas

Un cuadro de herramientas Foundry es un paquete con nombre y versión que contiene configuraciones de herramientas hospedadas (intérprete de código, búsqueda de archivos, generación de imágenes, MCP, búsqueda web) configurado en un proyecto de Microsoft Foundry. Los cuadros de herramientas le permiten administrar la configuración de herramientas una vez en el portal de Foundry y reutilizarla entre agentes.

Agent Framework solo cubre el consumo — la creación y actualización de versiones del kit de herramientas se realiza a través del portal Foundry o del SDK en bruto azure-ai-projects (azure-ai-projects>=2.1.0).

FoundryAgent frente a FoundryChatClient

Tipo de agente	Comportamiento del cuadro de herramientas
FoundryAgent (hospedado)	La conexión del cuadro de herramientas se realiza en el lado del servidor. No se requiere cableado del lado cliente.
FoundryChatClient (inferencia directa)	Capture el cuadro de herramientas con get_toolbox() y páselo como tools=.

Dos patrones de consumo

Pattern	Descripción
Nativo (herramientas hospedadas)	Las configuraciones de herramientas se ejecutan en el entorno de ejecución de Foundry. Pase el cuadro de herramientas directamente como tools=.
MCP	Use MCPStreamableHTTPTool contra el extremo MCP del cuadro de herramientas. Funciona con cualquier cliente de chat, no solo FoundryChatClient.

Obtener una caja de herramientas

Use FoundryChatClient.get_toolbox() para recuperar un cuadro de herramientas:

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import AzureCliCredential

async with AzureCliCredential() as credential:
    client = FoundryChatClient(credential=credential)
    toolbox = await client.get_toolbox("research_toolbox")

    async with Agent(client=client, name="ResearchAgent", tools=toolbox) as agent:
        result = await agent.run("Summarize recent findings.")
        print(result.text)

Cuando version se omite, get_toolbox resuelve la versión predeterminada en dos solicitudes. Ancle una versión específica para evitar el recorrido de ida y vuelta adicional:

toolbox = await client.get_toolbox("research_toolbox", version="v3")

Aplanamiento implícito

No es necesario escribir toolbox.tools. El marco normalize_tools reconoce ToolboxVersionObject y lo aplana automáticamente. Todo esto funciona:

# Single toolbox
agent = Agent(client=client, tools=toolbox)

# Toolbox in a list
agent = Agent(client=client, tools=[toolbox])

# Mix local function tools with a toolbox
agent = Agent(client=client, tools=[get_internal_metrics, toolbox])

# Combine multiple toolboxes
agent = Agent(client=client, tools=[toolbox_a, toolbox_b])

Herramientas de filtrado con select_toolbox_tools

Si el cuadro de herramientas agrupa varias herramientas, pero un agente solo necesita un subconjunto, use select_toolbox_tools para restringir el conjunto después de la captura. Esto evita el envío de definiciones de herramientas innecesarias al modelo, lo que reduce el uso de tokens y evita que el modelo invoque las herramientas que no pretende exponer:

from agent_framework.foundry import select_toolbox_tools, get_toolbox_tool_name

# Filter by tool name
tools = select_toolbox_tools(toolbox, include_names=["web_search", "code_interpreter"])

# Filter by tool type
tools = select_toolbox_tools(toolbox, include_types=["mcp", "web_search"])

# Filter with a custom predicate
tools = select_toolbox_tools(toolbox, predicate=lambda t: "search" in (get_toolbox_tool_name(t) or ""))

Las funciones auxiliares get_toolbox_tool_name(tool) y get_toolbox_tool_type(tool) devuelven respectivamente el nombre de la selección y el tipo sin formato de una entrada de herramienta. FoundryHostedToolType es un TypeAlias (Literal["code_interpreter", "file_search", "image_generation", "mcp", "web_search"] | str) para la finalización guiada por IDE en include_types / exclude_types.

Ruta de consumo de MCP

También puede consumir un conjunto de herramientas como servidor MCP apuntando MCPStreamableHTTPTool a la URL del punto de conexión MCP del conjunto de herramientas.

La dirección URL del punto de conexión de MCP se muestra en el Portal de Foundry o sigue el formato:

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

Dado que el cliente se conecta directamente al punto de conexión de las herramientas de Foundry, debe autenticarse con un token de portador de Entra ID a través de header_provider.

from azure.identity.aio import DefaultAzureCredential
from azure.identity.aio import get_bearer_token_provider
from agent_framework import Agent, MCPStreamableHTTPTool

credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(credential, "https://ai.azure.com/.default")

mcp_tool = MCPStreamableHTTPTool(
    name="research_mcp",
    url="https://<your-toolbox-mcp-endpoint>",
    header_provider=lambda: {"Authorization": f"Bearer {token_provider()}"},
)

async with Agent(client=client, name="MCPAgent", tools=[mcp_tool]) as agent:
    result = await agent.run("Search for recent papers on LLM agents.")
    print(result.text)

Limitaciones

• Las herramientas de MCP dentro de un cuadro de herramientas usan la autenticación del lado servidor. La autenticación en el servidor MCP ascendente se controla a través de project_connection_id (una conexión de OAuth configurada en el proyecto Foundry). El cliente nunca contiene tokens portadores para el servidor upstream.
• El consumo de un kit de herramientas como servidor MCP requiere la autenticación del cliente. Al apuntar MCPStreamableHTTPTool al punto de conexión MCP de un cuadro de herramientas, debe proporcionar un token de portador de Entra ID (por ejemplo, a través de get_bearer_token_provider(credential, "https://ai.azure.com/.default")) mediante header_provider.
• El control del flujo de consentimiento es un problema en tiempo de ejecución. Si una herramienta MCP del cuadro de herramientas se desencadena en CONSENT_REQUIRED durante agent.run(), se controla en tiempo de ejecución, no durante la captura del cuadro de herramientas.

Samples

Ejemplo	Descripción
foundry_chat_client_with_toolbox.py	Captura básica del cuadro de herramientas, anclaje de versiones, combinación de cuadros de herramientas y filtrado
foundry_chat_client_with_toolbox_mcp.py	Ruta de acceso de consumo de MCP con MCPStreamableHTTPTool
foundry_toolbox_context_provider.py	Selección dinámica de herramientas por cada turno a través de un proveedor de contexto