Agentes de Azure OpenAI

Microsoft Agent Framework admite dos tipos de cliente de OpenAI Azure, cada uno de los cuales tiene como destino una superficie de API diferente con distintas funcionalidades de herramientas. Las respuestas son el cliente principal recomendado: admite el conjunto completo de herramientas hospedadas. Usa Chat Completion cuando necesites compatibilidad con una amplia gama de modelos o ya tengas una integración con Chat Completions que quieras conservar.

Tipo de cliente:	API	Mejor para
Respuestas (recomendadas)	API de respuestas	Agentes completos con herramientas hospedadas (intérprete de código, búsqueda de archivos, búsqueda web, MCP hospedado)
Finalización del chat	API de finalizaciones de chat	Agentes simples, compatibilidad amplia con modelos

Sugerencia

Para obtener equivalentes directos de OpenAI (OpenAIChatClient, OpenAIChatCompletionClient), consulte la página del proveedor de OpenAI. El soporte de herramientas es idéntico.

Note

La API de asistentes de OpenAI de Azure está en desuso. El nuevo código debe usar el cliente de respuestas. Si va a migrar desde una aplicación basada en asistentes existente, consulte la guía de migración Kernel semántico.

Introducción

Agregue los paquetes NuGet necesarios al proyecto.

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

Todos los tipos de cliente de Azure OpenAI comienzan creando un AzureOpenAIClient:

using System;
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;

AzureOpenAIClient client = new AzureOpenAIClient(
    new Uri("https://<myresource>.openai.azure.com"),
    new DefaultAzureCredential());

Advertencia

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.

Cliente de respuestas

El cliente de respuestas es el cliente principal recomendado y proporciona la compatibilidad con herramientas más ricas, como el intérprete de código, la búsqueda de archivos, la búsqueda web y el MCP hospedado.

var responsesClient = client.GetResponseClient("gpt-4o-mini");

AIAgent agent = responsesClient.AsAIAgent(
    instructions: "You are a helpful coding assistant.",
    name: "CodeHelper");

Console.WriteLine(await agent.RunAsync("Write a Python function to sort a list."));

Herramientas admitidas: Herramientas de funciones, aprobación de herramientas, intérprete de código, búsqueda de archivos, búsqueda web, MCP hospedado, herramientas de MCP locales.

Cliente de finalización de chat

El cliente de finalización de chat proporciona una manera sencilla de crear agentes mediante la API de finalizaciones de chat. Úselo cuando necesite compatibilidad con una amplia gama de modelos o tenga una integración existente con Chat Completions.

var chatClient = client.GetChatClient("gpt-4o-mini");

AIAgent agent = chatClient.AsAIAgent(
    instructions: "You are good at telling jokes.",
    name: "Joker");

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

Herramientas admitidas: Herramientas de funciones, búsqueda web, herramientas de MCP locales.

Cliente de asistentes

Note

La API de asistentes de OpenAI de Azure está en desuso. El Agent Framework ya no incluye documentación sobre un cliente de Assistants; use el cliente Responses anterior para el código nuevo. Para migrar una aplicación existente, consulte la guía de migración Kernel semántico.

Herramientas de funciones

Puede proporcionar herramientas de función personalizadas a cualquier agente de Azure OpenAI:

using System.ComponentModel;
using Microsoft.Extensions.AI;

[Description("Get the weather for a given location.")]
static string GetWeather([Description("The location to get the weather for.")] string location)
    => $"The weather in {location} is cloudy with a high of 15°C.";

AIAgent agent = new AzureOpenAIClient(
    new Uri(endpoint),
    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(instructions: "You are a helpful assistant", tools: [AIFunctionFactory.Create(GetWeather)]);

Console.WriteLine(await agent.RunAsync("What is the weather like in Amsterdam?"));

Respuestas de streaming

await foreach (var update in agent.RunStreamingAsync("Tell me a joke about a pirate."))
{
    Console.Write(update);
}

Sugerencia

Consulte los ejemplos de .NET para obtener ejemplos completos de ejecución.

Uso del agente

Ambos tipos de cliente generan un estándar AIAgent que admite las mismas operaciones del agente (streaming, subprocesos, middleware).

Para obtener más información, consulte los tutoriales de introducción.

Herramientas

Los clientes de Azure OpenAI .NET comparten su conjunto de herramientas con los correspondientes clientes de OpenAI. Consulte la página del proveedor de OpenAI para obtener la matriz completa por cliente — las variantes de Azure de Responses y Chat Completions reflejan sus equivalentes directos de OpenAI.

Herramienta	Respuestas	Finalización del chat
Herramientas de funciones	✅	✅
Aprobación de herramientas	✅	✅
Intérprete de código	✅	❌
Búsqueda de archivos	✅	❌
Búsqueda web	✅	✅
Herramientas de MCP hospedadas	✅	❌
Herramientas de MCP locales	✅	✅

Note

La aprobación de herramientas la proporciona el cliente de chat de invocación de funciones del marco, por lo que funciona con cualquier llamada a función-herramienta independientemente de la API subyacente.

Guía de Python

Importante

Las instrucciones de Azure OpenAI de Python ahora se encuentran en la página del proveedor de OpenAI. Use esa página para OpenAIChatCompletionClient, OpenAIChatClient y OpenAIEmbeddingClient, mapeo de nombre de implementación a model, entradas explícitas de enrutamiento de Azure como credential o azure_endpoint, configuración de api_version después de seleccionar Azure, además de base_url guía para URLs completas .../openai/v1. Si OPENAI_API_KEY también está presente, los clientes genéricos se quedan en OpenAI a menos que se proporcionen entradas explícitas de enrutamiento de Azure. Si solo están presentes las configuraciones AZURE_OPENAI_*, la reserva del entorno de Azure sigue funcionando. Las clases de compatibilidad de Python AzureOpenAI* antiguas se quitaron del espacio de nombres actual agent_framework.azure , por lo que migre código anterior a agent_framework.openai. Para las nuevas soluciones de Python, se recomienda implementar modelos con Microsoft Foundry y conectarse a ellos en FoundryChatClient lugar de permanecer en la ruta de acceso específica de Azure OpenAI. Si necesita endpoints del proyecto de Foundry o el servicio del agente Foundry, consulte la página del proveedor de Foundry. Para obtener una lista de comprobación de migración más amplia, consulte la guía de cambios significativos de Python.

Herramientas

Python Azure OpenAI usa los mismos clientes de agent_framework.openai que OpenAI directamente, por lo que la interfaz de herramientas es idéntica. Consulte la sección Herramientas de la página proveedor de OpenAI para obtener la matriz completa por cliente.

Pasos siguientes

Proveedor OpenAI