Compartir a través de

Puntos de Conexión OpenAI-Compatible

Agent Framework admite protocolos compatibles con OpenAI tanto para alojar agentes detrás de las API estándar como para conectar con cualquier punto de conexión compatible con OpenAI.

¿Qué son los protocolos openAI?

Se admiten dos protocolos OpenAI:

  • API de completaciones de chat: formato estándar de solicitud/respuesta sin estado para interacciones de chat
  • API de respuestas : formato avanzado que admite conversaciones, streaming y procesos de agente de larga duración

La API de respuestas es ahora el enfoque predeterminado y recomendado según la documentación de OpenAI. Proporciona una interfaz más completa y enriquecida para crear aplicaciones de inteligencia artificial con administración de conversaciones integrada, funcionalidades de streaming y compatibilidad con procesos de larga duración.

Use la API de respuestas cuando:

  • Compilación de aplicaciones nuevas (valor predeterminado recomendado)
  • Necesita administración de conversaciones del lado del servidor. Sin embargo, no es un requisito: todavía se puede utilizar el Responses API en modo sin estado.
  • Quieres un historial de conversaciones persistente
  • Está construyendo procesos de agente de larga duración
  • Necesita funcionalidades avanzadas de streaming con tipos de eventos detallados.
  • Quiere realizar un seguimiento y administrar respuestas individuales (por ejemplo, recuperar una respuesta específica por identificador, comprobar su estado o cancelar una respuesta en ejecución).

Use la API de finalizaciones de chat cuando:

  • Migración de aplicaciones existentes que dependen del formato de finalizaciones de chat
  • Necesita interacciones de solicitud/respuesta que sean sencillas y sin estado.
  • La administración de estado es gestionada completamente por su cliente.
  • Está integrándose con las herramientas existentes que solo soportan completaciones de chat.
  • Necesita la máxima compatibilidad con sistemas heredados.

Hospedar agentes como puntos de conexión de OpenAI (.NET)

La biblioteca Microsoft.Agents.AI.Hosting.OpenAI le permite exponer agentes de inteligencia artificial mediante puntos de conexión HTTP compatibles con OpenAI, que admiten tanto las API de completación de chat como de respuestas. Esto le permite integrar los agentes con cualquier cliente o herramienta compatible con OpenAI.

Paquete NuGet:

API de finalizaciones de chat

La API de finalizaciones de chat proporciona una interfaz sencilla y sin estado para interactuar con agentes mediante el formato estándar de chat de OpenAI.

Configuración de un agente en ASP.NET Core con la integración de ChatCompletions

Este es un ejemplo completo que muestra un agente a través de la api de completaciones de chat.

Prerrequisitos

1. Creación de un proyecto de API web de ASP.NET Core

Cree un nuevo proyecto de API web de ASP.NET Core o use uno existente.

2. Instalación de dependencias necesarias

Instale los siguientes paquetes:

Ejecute los siguientes comandos en el directorio del proyecto para instalar los paquetes NuGet necesarios:

# Hosting.A2A.AspNetCore for OpenAI ChatCompletions/Responses protocol(s) integration
dotnet add package Microsoft.Agents.AI.Hosting.OpenAI --prerelease

# Libraries to connect to Azure OpenAI
dotnet add package Azure.AI.OpenAI --prerelease
dotnet add package Azure.Identity
dotnet add package Microsoft.Extensions.AI
dotnet add package Microsoft.Extensions.AI.OpenAI --prerelease

# Swagger to test app
dotnet add package Microsoft.AspNetCore.OpenApi
dotnet add package Swashbuckle.AspNetCore

3. Configuración de la conexión de Azure OpenAI

La aplicación requiere una conexión de Azure OpenAI. Configure el punto de conexión y el nombre de implementación mediante dotnet user-secrets o variables de entorno. También puede simplemente editar el appsettings.json, pero eso no se recomienda para las aplicaciones implementadas en producción, ya que algunos de los datos se pueden considerar confidenciales.

dotnet user-secrets set "AZURE_OPENAI_ENDPOINT" "https://<your-openai-resource>.openai.azure.com/"
dotnet user-secrets set "AZURE_OPENAI_DEPLOYMENT_NAME" "gpt-4o-mini"

4. Agregar el código a Program.cs

Reemplace el contenido de Program.cs por el código siguiente:

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI.Hosting;
using Microsoft.Extensions.AI;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();
builder.Services.AddSwaggerGen();

string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"]
    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
string deploymentName = builder.Configuration["AZURE_OPENAI_DEPLOYMENT_NAME"]
    ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");

// Register the chat client
IChatClient chatClient = new AzureOpenAIClient(
        new Uri(endpoint),
        new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsIChatClient();
builder.Services.AddSingleton(chatClient);

builder.AddOpenAIChatCompletions();

// Register an agent
var pirateAgent = builder.AddAIAgent("pirate", instructions: "You are a pirate. Speak like a pirate.");

var app = builder.Build();

app.MapOpenApi();
app.UseSwagger();
app.UseSwaggerUI();

// Expose the agent via OpenAI ChatCompletions protocol
app.MapOpenAIChatCompletions(pirateAgent);

app.Run();

Probar el punto de conexión de finalizaciones de chat

Una vez que se ejecuta la aplicación, puede probar el agente mediante el SDK de OpenAI o las solicitudes HTTP:

Uso de la solicitud HTTP

POST {{baseAddress}}/pirate/v1/chat/completions
Content-Type: application/json
{
  "model": "pirate",
  "stream": false,
  "messages": [
    {
      "role": "user",
      "content": "Hey mate!"
    }
  ]
}

Nota: Reemplace por {{baseAddress}} el punto de conexión del servidor.

Esta es una respuesta de ejemplo:

{
	"id": "chatcmpl-nxAZsM6SNI2BRPMbzgjFyvWWULTFr",
	"object": "chat.completion",
	"created": 1762280028,
	"model": "gpt-5",
	"choices": [
		{
			"index": 0,
			"finish_reason": "stop",
			"message": {
				"role": "assistant",
				"content": "Ahoy there, matey! How be ye farin' on this fine day?"
			}
		}
	],
	"usage": {
		"completion_tokens": 18,
		"prompt_tokens": 22,
		"total_tokens": 40,
		"completion_tokens_details": {
			"accepted_prediction_tokens": 0,
			"audio_tokens": 0,
			"reasoning_tokens": 0,
			"rejected_prediction_tokens": 0
		},
		"prompt_tokens_details": {
			"audio_tokens": 0,
			"cached_tokens": 0
		}
	},
	"service_tier": "default"
}

La respuesta incluye el identificador de mensaje, el contenido y las estadísticas de uso.

Las finalizaciones de chat también admiten streaming, donde la salida se devuelve en fragmentos tan pronto como esté disponible el contenido. Esta funcionalidad permite mostrar la salida progresivamente. Puede habilitar el streaming especificando "stream": true. El formato de salida consta de fragmentos de eventos enviados por el servidor (SSE), tal como se define en la especificación OpenAI de finalizaciones de chat.

POST {{baseAddress}}/pirate/v1/chat/completions
Content-Type: application/json
{
  "model": "pirate",
  "stream": true,
  "messages": [
    {
      "role": "user",
      "content": "Hey mate!"
    }
  ]
}

Y la salida que obtenemos es un conjunto de fragmentos de ChatCompletions:

data: {"id":"chatcmpl-xwKgBbFtSEQ3OtMf21ctMS2Q8lo93","choices":[],"object":"chat.completion.chunk","created":0,"model":"gpt-5"}

data: {"id":"chatcmpl-xwKgBbFtSEQ3OtMf21ctMS2Q8lo93","choices":[{"index":0,"finish_reason":"stop","delta":{"content":"","role":"assistant"}}],"object":"chat.completion.chunk","created":0,"model":"gpt-5"}

...

data: {"id":"chatcmpl-xwKgBbFtSEQ3OtMf21ctMS2Q8lo93","choices":[],"object":"chat.completion.chunk","created":0,"model":"gpt-5","usage":{"completion_tokens":34,"prompt_tokens":23,"total_tokens":57,"completion_tokens_details":{"accepted_prediction_tokens":0,"audio_tokens":0,"reasoning_tokens":0,"rejected_prediction_tokens":0},"prompt_tokens_details":{"audio_tokens":0,"cached_tokens":0}}}

La respuesta de streaming contiene información similar, pero transmitida como Server-Sent Events.

API de respuestas

La API de respuestas proporciona características avanzadas, como la administración de conversaciones, el streaming y la compatibilidad con procesos de agente de larga duración.

Configuración de un agente en ASP.NET Core con la integración de la API de respuestas

Este es un ejemplo completo mediante la API de respuestas:

Prerrequisitos

Siga los mismos requisitos previos que el ejemplo de Completaciones de Chat (pasos 1-3).

4. Agregar el código a Program.cs

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI.Hosting;
using Microsoft.Extensions.AI;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();
builder.Services.AddSwaggerGen();

string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"]
    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
string deploymentName = builder.Configuration["AZURE_OPENAI_DEPLOYMENT_NAME"]
    ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");

// Register the chat client
IChatClient chatClient = new AzureOpenAIClient(
        new Uri(endpoint),
        new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsIChatClient();
builder.Services.AddSingleton(chatClient);

builder.AddOpenAIResponses();
builder.AddOpenAIConversations();

// Register an agent
var pirateAgent = builder.AddAIAgent("pirate", instructions: "You are a pirate. Speak like a pirate.");

var app = builder.Build();

app.MapOpenApi();
app.UseSwagger();
app.UseSwaggerUI();

// Expose the agent via OpenAI Responses protocol
app.MapOpenAIResponses(pirateAgent);
app.MapOpenAIConversations();

app.Run();

Prueba de la API de respuestas

La API de respuestas es similar a las completaciones de chat, pero es con estado, lo que le permite pasar un parámetro conversation. Al igual que las finalizaciones de chat, admite el stream parámetro , que controla el formato de salida: una única respuesta JSON o una secuencia de eventos. La API de respuestas define sus propios tipos de eventos de streaming, incluidos response.created, response.output_item.addedresponse.output_item.done, , response.completedy otros.

Crear una conversación y una respuesta

Puede enviar una solicitud de respuestas directamente, o puede crear primero una conversación mediante conversations API y, a continuación, vincular las solicitudes posteriores a esa conversación.

Para empezar, cree una conversación:

POST http://localhost:5209/v1/conversations
Content-Type: application/json
{
  "items": [
    {
        "type": "message",
        "role": "user",
        "content": "Hello!"
      }
  ]
}

La respuesta incluye el identificador de conversación:

{
  "id": "conv_E9Ma6nQpRzYxRHxRRqoOWWsDjZVyZfKxlHhfCf02Yxyy9N2y",
  "object": "conversation",
  "created_at": 1762881679,
  "metadata": {}
}

A continuación, envíe una solicitud y especifique el parámetro conversation. (Para recibir la respuesta como eventos de streaming, establezca "stream": true en la solicitud).

POST http://localhost:5209/pirate/v1/responses
Content-Type: application/json
{
  "stream": false,
  "conversation": "conv_E9Ma6nQpRzYxRHxRRqoOWWsDjZVyZfKxlHhfCf02Yxyy9N2y",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {
            "type": "input_text",
            "text": "are you a feminist?"
        }
      ]
    }
  ]
}

El agente devuelve la respuesta y guarda los elementos de conversación en el almacenamiento para su recuperación posterior:

{
  "id": "resp_FP01K4bnMsyQydQhUpovK6ysJJroZMs1pnYCUvEqCZqGCkac",
  "conversation": "conv_E9Ma6nQpRzYxRHxRRqoOWWsDjZVyZfKxlHhfCf02Yxyy9N2y",
  "object": "response",
  "created_at": 1762881518,
  "status": "completed",
  "incomplete_details": null,
  "output": [
    {
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Arrr, matey! As a pirate, I be all about respect for the crew, no matter their gender! We sail these seas together, and every hand on deck be valuable. A true buccaneer knows that fairness and equality be what keeps the ship afloat. So, in me own way, I’d say I be supportin’ all hearty souls who seek what be right! What say ye?"
        }
      ],
      "type": "message",
      "status": "completed",
      "id": "msg_1FAQyZcWgsBdmgJgiXmDyavWimUs8irClHhfCf02Yxyy9N2y"
    }
  ],
  "usage": {
    "input_tokens": 26,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 85,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 111
  },
  "tool_choice": null,
  "temperature": 1,
  "top_p": 1  
}

La respuesta incluye identificadores de conversación y mensajes, contenido y estadísticas de uso.

Para recuperar los elementos de conversación, envíe esta solicitud:

GET http://localhost:5209/v1/conversations/conv_E9Ma6nQpRzYxRHxRRqoOWWsDjZVyZfKxlHhfCf02Yxyy9N2y/items?include=string

Esto devuelve una respuesta JSON que contiene mensajes de entrada y salida:

{
  "object": "list",
  "data": [
    {
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Arrr, matey! As a pirate, I be all about respect for the crew, no matter their gender! We sail these seas together, and every hand on deck be valuable. A true buccaneer knows that fairness and equality be what keeps the ship afloat. So, in me own way, I’d say I be supportin’ all hearty souls who seek what be right! What say ye?",
          "annotations": [],
          "logprobs": []
        }
      ],
      "type": "message",
      "status": "completed",
      "id": "msg_1FAQyZcWgsBdmgJgiXmDyavWimUs8irClHhfCf02Yxyy9N2y"
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "are you a feminist?"
        }
      ],
      "type": "message",
      "status": "completed",
      "id": "msg_iLVtSEJL0Nd2b3ayr9sJWeV9VyEASMlilHhfCf02Yxyy9N2y"
    }
  ],
  "first_id": "msg_1FAQyZcWgsBdmgJgiXmDyavWimUs8irClHhfCf02Yxyy9N2y",
  "last_id": "msg_lUpquo0Hisvo6cLdFXMKdYACqFRWcFDrlHhfCf02Yxyy9N2y",
  "has_more": false
}

Exposición de varios agentes

Puede exponer varios agentes simultáneamente mediante ambos protocolos:

var mathAgent = builder.AddAIAgent("math", instructions: "You are a math expert.");
var scienceAgent = builder.AddAIAgent("science", instructions: "You are a science expert.");

// Add both protocols
builder.AddOpenAIChatCompletions();
builder.AddOpenAIResponses();

var app = builder.Build();

// Expose both agents via Chat Completions
app.MapOpenAIChatCompletions(mathAgent);
app.MapOpenAIChatCompletions(scienceAgent);

// Expose both agents via Responses
app.MapOpenAIResponses(mathAgent);
app.MapOpenAIResponses(scienceAgent);

Los agentes estarán disponibles en:

  • Finalizaciones de chat: /math/v1/chat/completions y /science/v1/chat/completions
  • Respuestas: /math/v1/responses y /science/v1/responses

Puntos de conexión personalizados

Puede personalizar las rutas de acceso del punto de conexión:

// Custom path for Chat Completions
app.MapOpenAIChatCompletions(mathAgent, path: "/api/chat");

// Custom path for Responses
app.MapOpenAIResponses(scienceAgent, responsesPath: "/api/responses");

Conexión a endpoints compatibles con OpenAI (Python)

Python OpenAIChatClient y OpenAIResponsesClient ambos admiten un base_url parámetro, lo que permite conectarse a cualquier punto de conexión compatible con OpenAI, incluidos agentes autohospedados, servidores de inferencia local (Ollama, LM Studio, vLLM) o API compatibles con OpenAI de terceros.

pip install agent-framework --pre

Cliente de finalizaciones de chat

Use OpenAIChatClient con base_url para apuntar a cualquier servidor compatible con Completions de Chat:

import asyncio
from agent_framework import tool
from agent_framework.openai import OpenAIChatClient

@tool(approval_mode="never_require")
def get_weather(location: str) -> str:
    """Get the weather for a location."""
    return f"Weather in {location}: sunny, 22°C"

async def main():
    # Point to any OpenAI-compatible endpoint
    agent = OpenAIChatClient(
        base_url="http://localhost:11434/v1/",  # e.g. Ollama
        api_key="not-needed",                   # placeholder for local servers
        model_id="llama3.2",
    ).as_agent(
        name="WeatherAgent",
        instructions="You are a helpful weather assistant.",
        tools=get_weather,
    )

    response = await agent.run("What's the weather in Seattle?")
    print(response)

asyncio.run(main())

Cliente de respuestas

Use OpenAIResponsesClient con base_url para los puntos de conexión que admiten la API de respuestas:

import asyncio
from agent_framework.openai import OpenAIResponsesClient

async def main():
    agent = OpenAIResponsesClient(
        base_url="https://your-hosted-agent.example.com/v1/",
        api_key="your-api-key",
        model_id="gpt-4o-mini",
    ).as_agent(
        name="Assistant",
        instructions="You are a helpful assistant.",
    )

    # Non-streaming
    response = await agent.run("Hello!")
    print(response)

    # Streaming
    async for chunk in agent.run("Tell me a joke", stream=True):
        if chunk.text:
            print(chunk.text, end="", flush=True)

asyncio.run(main())

Servidores comunes compatibles con OpenAI

El base_url enfoque funciona con cualquier servidor que exponga el formato de finalizaciones de chat de OpenAI:

Servidor Dirección URL base Notas
Ollama http://localhost:11434/v1/ Inferencia local, no se necesita ninguna clave de API
LM Studio http://localhost:1234/v1/ Inferencia local con GUI
vLLM http://localhost:8000/v1/ Servicio de alto rendimiento
Azure AI Foundry El punto de conexión de implementación Uso de credenciales de Azure
Agentes del framework de agentes hospedados Punto de conexión del agente Agentes de .NET expuestos a través de MapOpenAIChatCompletions

Nota:

También puede establecer la OPENAI_BASE_URL variable de entorno en lugar de pasar base_url directamente. El cliente lo usará automáticamente.

Uso de clientes openAI de Azure

Las variantes de Azure OpenAI (AzureOpenAIChatClient, AzureOpenAIResponsesClient) se conectan a los puntos de conexión de Azure OpenAI mediante credenciales de Azure; no base_url es necesario:

from agent_framework.azure import AzureOpenAIResponsesClient

agent = AzureOpenAIResponsesClient().as_agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
)

Configure mediante variables de entorno:

export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
export AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME="gpt-4o-mini"

Véase también

Pasos siguientes

Purview

  • Last updated on