proveedor de modelos de Microsoft Foundry

Microsoft Agent Framework admite la inferencia directa del modelo desde Microsoft puntos de conexión del proyecto Foundry, mientras que la aplicación posee la definición, las herramientas y la orquestación del agente.

Para los agentes hospedados y la solicitud administrada por el servicio, consulte Microsoft servicio del agente foundry.

Getting Started

Agregue los paquetes NuGet necesarios al proyecto.

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

Dos patrones de integración

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

Pattern Tipo producido Description 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 foundry (preguntar o hospedado) FoundryAgent Administrado por el servidor: los agentes de solicitud tienen definiciones con nombre y versiones; Los agentes hospedados se implementan aplicaciones a través de un punto de conexión específico del agente. Foundry posee la definición del agente o el entorno de ejecución hospedado. Consulte Microsoft Servicio del agente foundry.

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."));

Warning

DefaultAzureCredential es conveniente para el desarrollo, pero requiere una consideración cuidadosa en producción. En producción, considere usar una credencial específica (por ejemplo, ManagedIdentityCredential) para evitar problemas de latencia, sondeos de credenciales no deseados y posibles riesgos de seguridad de los mecanismos de respaldo.

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

Uso del agente

El Agente de respuestas es un estándar AIAgent y admite sesiones, herramientas, middleware y 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.

Tools

Los agentes de respuestas de foundry creados a partir de AIProjectClient.AsAIAgent(...) admiten la superficie de herramientas estándar de Agent Framework. Consulte la introducción a las herramientas para obtener la matriz de características completa.

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

Foundry 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.

Importante

En esta página se tratan Microsoft los puntos de conexión de proyecto y modelos de Foundry. Para el servicio foundry Agent, consulte Microsoft Foundry Agent Service. Si tiene un punto de conexión de recursos de Azure OpenAI independiente (https://<your-resource>.openai.azure.com), use la guía de Python en la página del proveedor de OpenAI. Si desea ejecutar modelos compatibles localmente, consulte la página Proveedor local de Foundry.

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

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

Configuration

FoundryChatClient

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

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 usa 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
el 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.
Representaciones vectoriales de los modelos de Microsoft Foundry en los puntos finales 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.

Tools

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=[...]). Para ver las herramientas del agente administrado por el servicio, consulte Microsoft Servicio de agente foundry.

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.

Herramienta Fábrica en FoundryChatClient Situación Detail
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 — usa MCPStreamableHTTPTool / MCPStdioTool GA Se ejecuta en el proceso; funciona con cualquier cliente.
Cuadro de herramientas de Microsoft Foundry MCPStreamableHTTPTool o FoundryToolbox Beta Consumido mediante MCP de FoundryChatClient; adjunto del lado del servidor en FoundryAgent.
Conexión a tierra Bing get_bing_grounding_tool Habilitación de características 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 Habilitación de características 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.

Note

Las fábricas experimentales encapsulan los tipos de SDK de GA Foundry, pero los propios contenedores pueden cambiar antes de la disponibilidad general. Las fábricas de versión preliminar encapsulan los tipos del SDK de Foundry cuya funcionalidad subyacente está en versión preliminar y pueden cambiar o quitarse. Ambos emiten ExperimentalWarning una primera vez que se usan en un proceso.

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

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

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

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 obtener instrucciones generales sobre detección, sesiones y streaming de A2A, consulte el servicio del agente A2A.

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)

Uso del agente

FoundryChatClientse integra con la experiencia estándar de PythonAgent, 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.

Para ver agrupaciones con versiones con nombre de configuraciones de herramientas hospedadas, consulte Microsoft Foundry Toolbox.

Foundry in Go

El SDK de Go proporciona los agentes de Microsoft Foundry a través de github.com/microsoft/agent-framework-go/provider/foundryprovider.

Consulte los ejemplos de Foundry Go para obtener inferencia directa, herramientas de funciones, herramientas hospedadas, MCP y ejemplos de agente de servidor.

El paquete admite dos destinos de agente:

Objetivo Forma de Go Se utiliza cuando
implementación del modelo respaldado por Project foundryprovider.ModelDeployment("gpt-4o-mini") Tu aplicación posee instrucciones, herramientas y flujo de conversación.
Agente de Foundry del servidor existente foundryprovider.ServerAgent("my-agent") La definición del agente ya está configurada en Foundry.

Configuration

Configure el endpoint de su proyecto de Foundry y la implementación del modelo:

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

agente de Foundry con el respaldo de Project

Use ModelDeployment cuando desee crear un agente de Agent Framework en el código y pasar instrucciones, herramientas, middleware y proveedores de contexto desde la aplicación Go.

import (
    "context"
    "os"

    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/provider/foundryprovider"
)

endpoint := os.Getenv("FOUNDRY_PROJECT_ENDPOINT")
model := os.Getenv("FOUNDRY_MODEL")

token, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
    panic(err)
}

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "You are good at telling jokes.",
        Config: agent.Config{
            Name: "Joker",
        },
    },
)

resp, err := a.RunText(context.Background(), "Tell me a joke about a pirate.").Collect()

Agente de Foundry del servidor existente

Use ServerAgent cuando quiera invocar un agente ya configurado en Foundry. El agente del lado servidor posee sus instrucciones y herramientas, por lo que AgentConfig.Instructions se omite para este destino.

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ServerAgent("my-agent"),
    foundryprovider.AgentConfig{
        Config: agent.Config{
            Name: "my-agent",
        },
    },
)

resp, err := a.RunText(ctx, "Summarize the current project status.").Collect()

Tools

Los agentes de Foundry respaldados por proyectos admiten la interfaz estándar de herramientas de Go Agent Framework para herramientas locales y declaraciones compatibles de herramientas hospedadas.

Herramienta Situación Notas
Herramientas de funciones Soportado Las funciones se ejecutan en tu proceso de Go.
Aprobación de herramientas Soportado Funciona con herramientas de funciones locales a través del bucle de llamada automática de herramientas.
Intérprete de código Soportado Utilice &hostedtool.CodeInterpreter{}.
Búsqueda web Soportado Utilice &hostedtool.WebSearch{}.
Herramientas de MCP locales Soportado Use tool/mcptool para conectarse a un servidor MCP y exponer sus herramientas localmente.
Herramientas de MCP hospedadas No está documentado actualmente para Go Foundry Use herramientas de MCP locales cuando necesite servidores MCP con agentes de Go Foundry.
Cuadro de herramientas de Microsoft Foundry Actualmente no se expone a través de un asistente de Go.

Para las herramientas de función local, agregue valores a tool.Tool hasta agent.Config.Tools:

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "You are a helpful assistant.",
        Config: agent.Config{
            Tools: []tool.Tool{weatherTool},
        },
    },
)

Para la ejecución del código hospedado, pase la declaración de herramienta hospedada:

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "You solve problems with code.",
        Config: agent.Config{
            Tools: []tool.Tool{&hostedtool.CodeInterpreter{}},
        },
    },
)

Encabezados de cliente y modelo servido

Foundry acepta encabezados x-client-* por ejecución. Agréguelos con foundryprovider.WithClientHeader o foundryprovider.WithClientHeaders:

resp, err := a.RunText(
    ctx,
    "Hello!",
    foundryprovider.WithClientHeader("x-client-scenario", "docs"),
).Collect()

Cuando Foundry devuelve la cabecera de respuesta x-ms-served-model, el proveedor de Go la agrega a las propiedades adicionales de respuesta o de actualización como ServedModel.

if servedModel, ok := resp.AdditionalProperties["ServedModel"].(string); ok {
    fmt.Println(servedModel)
}

Proveedor de memoria de fundición

Use foundryprovider.NewMemoryProvider cuando desee que un agente de Agent Framework recupere y actualice un almacén de memoria administrado por Foundry en torno a cada ejecución.

import (
    "log/slog"

    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/provider/foundryprovider"
)

memoryProvider := foundryprovider.NewMemoryProvider(
    endpoint,
    tokenCredential,
    "memory-store-sample",
    func(*agent.Session) string { return "user-123" },
    foundryprovider.MemoryProviderConfig{
        Logger: slog.Default(),
    },
)

a := foundryprovider.NewAgent(
    endpoint,
    tokenCredential,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "Use known memories about the user when responding.",
        Config: agent.Config{
            Name:             "FoundryMemoryAgent",
            ContextProviders: []agent.ContextProvider{memoryProvider},
        },
    },
)

El punto de conexión debe ser un punto de conexión de Microsoft Foundry con ámbito de proyecto, y el almacén de memoria ya debe existir en ese proyecto. La función de callback del ámbito debe devolver una clave de partición estable de usuario, inquilino o conversación.

Tip

Consulte el ejemplo de memoria de Foundry para Go para ver un ejemplo completo y ejecutable.

Brechas actuales de Go

La compatibilidad con Go no incluye actualmente las API de implementación o ciclo de vida o administración hospedadas en Foundry, los clientes de inserción o los asistentes específicos de Go para Microsoft Foundry Toolbox. Utilice el portal de Foundry o los SDK de servicio para esas operaciones.

Pasos siguientes

Foundry Local

  • Last updated on