Condividi tramite

Endpoint Compatibile con OpenAI

Agent Framework supporta protocolli compatibili con OpenAI sia per gli agenti di hosting dietro le API standard che per la connessione a qualsiasi endpoint compatibile con OpenAI.

Che cosa sono i protocolli OpenAI?

Sono supportati due protocolli OpenAI:

  • API Completamento Chat — Formato di richiesta/risposta standard e senza stato per le interazioni con la chat
  • API Risposte : formato avanzato che supporta conversazioni, streaming e processi di agenti a lunga durata

L'API Risposte è ora l'approccio predefinito e consigliato in base alla documentazione di OpenAI. Offre un'interfaccia più completa e completa per la creazione di applicazioni di intelligenza artificiale con funzionalità predefinite di gestione delle conversazioni, funzionalità di streaming e supporto per i processi a esecuzione prolungata.

Usare l'API Risposte quando:

  • Creazione di nuove applicazioni (impostazione predefinita consigliata)
  • È necessaria la gestione delle conversazioni sul lato server. Tuttavia, questo non è un requisito: è comunque possibile usare l'API Risposte in modalità senza stato.
  • Si vuole la cronologia delle conversazioni persistenti
  • Stai costruendo processi dell'agente a lunga durata
  • Sono necessarie funzionalità di streaming avanzate con tipi di eventi dettagliati
  • Si vuole tenere traccia e gestire le singole risposte( ad esempio, recuperare una risposta specifica in base all'ID, controllarne lo stato o annullare una risposta in esecuzione)

Utilizzare l'API Chat Completions quando:

  • Migrazione di applicazioni esistenti che si basano sul formato Completamento Chat
  • Sono necessarie interazioni semplici e senza stato tra richiesta e risposta
  • La gestione dello stato è interamente affidata al client
  • Stai integrando con gli strumenti esistenti che supportano solo i completamenti delle chat
  • È necessaria la massima compatibilità con i sistemi legacy

Hosting di agenti come endpoint OpenAI (.NET)

La Microsoft.Agents.AI.Hosting.OpenAI libreria consente di esporre gli agenti di intelligenza artificiale tramite endpoint HTTP compatibili con OpenAI, supportando sia le API di completamento della chat che le risposte. In questo modo è possibile integrare gli agenti con qualsiasi client o strumento compatibile con OpenAI.

Pacchetto NuGet:

API di completamento per chat

L'API per i completamenti della chat offre un'interfaccia semplice e senza mantenere lo stato per interagire con agenti utilizzando il formato di chat standard di OpenAI.

Configurazione di un agente in ASP.NET Core con l'integrazione di ChatCompletions

Ecco un esempio completo che presenta un agente tramite la Chat Completions API.

Prerequisiti

1. Creare un progetto API Web di base ASP.NET

Creare un nuovo progetto api Web core ASP.NET o usarne uno esistente.

2. Installare le dipendenze necessarie

Installare i pacchetti seguenti:

Eseguire i comandi seguenti nella directory del progetto per installare i pacchetti NuGet necessari:

# 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. Configurare la connessione OpenAI di Azure

L'applicazione richiede una connessione OpenAI di Azure. Configurare l'endpoint e il nome della distribuzione usando dotnet user-secrets o le variabili di ambiente. È anche possibile modificare semplicemente , appsettings.jsonma non è consigliabile per le app distribuite nell'ambiente di produzione perché alcuni dei dati possono essere considerati segreti.

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. Aggiungere il codice a Program.cs

Sostituire il contenuto di Program.cs con il codice seguente:

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();

Test dell'endpoint di completamento della chat

Dopo l'esecuzione dell'applicazione, è possibile testare l'agente usando OpenAI SDK o le richieste HTTP:

Uso della richiesta HTTP

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

Nota: sostituire {{baseAddress}} con l'endpoint server.

Ecco una risposta di esempio:

{
	"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 risposta include l'ID del messaggio, il contenuto e le statistiche di utilizzo.

I completamenti della chat supportano anche lo streaming, in cui l'output viene restituito in blocchi non appena il contenuto è disponibile. Questa funzionalità consente di visualizzare progressivamente l'output. È possibile abilitare lo streaming specificando "stream": true. Il formato di output è costituito da blocchi di Eventi Inviati dal Server (SSE) come definiti nella specifica OpenAI Chat Completions.

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

L'output che si ottiene è un set di blocchi 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 risposta di streaming contiene informazioni simili, ma recapitate come eventi Server-Sent.

API delle risposte

L'API Risposte offre funzionalità avanzate, tra cui la gestione delle conversazioni, lo streaming e il supporto per i processi dell'agente a esecuzione prolungata.

Configurazione di un agente in ASP.NET Core con l'integrazione dell'API Risposte

Ecco un esempio completo che usa l'API Risposte:

Prerequisiti

Seguire gli stessi prerequisiti dell'esempio di completamento della chat (passaggi da 1 a 3).

4. Aggiungere il codice 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();

Test dell'API di Risposte

L'API Risposte è simile ai completamenti della chat, ma è con stato, consentendo di passare un conversation parametro. Analogamente ai completamenti della chat, supporta il stream parametro , che controlla il formato di output: una singola risposta JSON o un flusso di eventi. L'API Risposte definisce i propri tipi di eventi di streaming, tra cui response.created, response.output_item.addedresponse.output_item.done, response.completed, e altri.

Creare una conversazione e una risposta

È possibile inviare direttamente una richiesta di risposte oppure creare prima una conversazione usando l'API Conversazioni e quindi collegare le richieste successive a tale conversazione.

Per iniziare, creare una nuova conversazione:

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

La risposta include l'identificativo della conversazione:

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

Inviare quindi una richiesta e specificare il parametro di conversazione. Per ricevere la risposta come eventi di streaming, impostare "stream": true nella richiesta.

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?"
        }
      ]
    }
  ]
}

L'agente restituisce la risposta e salva gli elementi della conversazione nell'archivio per il recupero successivo:

{
  "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 risposta include identificatori di conversazione e messaggi, contenuto e statistiche di utilizzo.

Per recuperare gli elementi della conversazione, inviare questa richiesta:

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

Viene restituita una risposta JSON contenente messaggi di input e output:

{
  "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
}

Esposizione di più agenti

È possibile esporre più agenti contemporaneamente usando entrambi i protocolli:

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

Gli agenti saranno disponibili all'indirizzo:

  • Completamento chat: /math/v1/chat/completions e /science/v1/chat/completions
  • Risposte: /math/v1/responses e /science/v1/responses

Endpoint personalizzati

È possibile personalizzare i percorsi degli endpoint:

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

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

Connessione a endpoint compatibili con OpenAI (Python)

Python OpenAIChatClient e OpenAIResponsesClient entrambi supportano un base_url parametro, consentendo di connettersi a qualsiasi endpoint compatibile con OpenAI, inclusi agenti self-hosted, server di inferenza locali (Ollama, LM Studio, vLLM) o API compatibili con OpenAI di terze parti.

pip install agent-framework --pre

Client di completamento chat

Usare OpenAIChatClient con base_url per puntare a qualsiasi server compatibile con il completamento della 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())

Risposte del cliente

Usare OpenAIResponsesClient con base_url per gli endpoint che supportano l'API Risposte:

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

Server comuni compatibili con OpenAI

L'approccio base_url funziona con qualsiasi server che espone il formato di completamento della chat OpenAI:

Servidor URL di base Note
Ollama http://localhost:11434/v1/ Inferenza locale, nessuna chiave API necessaria
LM Studio http://localhost:1234/v1/ Inferenza locale con GUI
vLLM http://localhost:8000/v1/ Servizio ad alta capacità di elaborazione
Azure IA Foundry L'endpoint di distribuzione Usa le credenziali di Azure
Agenti del Framework Agente Ospitato Endpoint dell'agente Agenti .NET esposti tramite MapOpenAIChatCompletions

Annotazioni

È anche possibile impostare la OPENAI_BASE_URL variabile di ambiente anziché passare base_url direttamente. Il client lo userà automaticamente.

Uso dei client OpenAI di Azure

Le varianti OpenAI di Azure (AzureOpenAIChatClient, AzureOpenAIResponsesClient) si connettono agli endpoint OpenAI di Azure usando le credenziali di Azure, senza base_url bisogno di:

from agent_framework.azure import AzureOpenAIResponsesClient

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

Configurare con le variabili di ambiente:

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

Vedere anche

Passaggi successivi

Ambito

  • Last updated on