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:

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.

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

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

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.

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.

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

Para HostedAgents que ejecutan sesiones del lado del servicio (/agents/{name}/sessions), use FoundryAgent con allow_preview=True para participar en la superficie de Respuestas en versión preliminar y pasar version="v2":

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

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

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

Dos patrones de consumo

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