proveedor de modelos de Microsoft 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:

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.

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.

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.

Patrones de chat y agentes de Foundry en Python

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

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.

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

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.

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.

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.