Freigeben über

OpenAI-Compatible Endpunkte

Das Agent Framework unterstützt OpenAI-kompatible Protokolle sowohl für Hosting-Agents hinter Standard-APIs als auch für die Verbindung mit jedem openAI-kompatiblen Endpunkt.

Was sind OpenAI-Protokolle?

Zwei OpenAI-Protokolle werden unterstützt:

  • API für Chatabschlusse – Standardformat für statuslose Anforderungs-/Antwortformate für Chatinteraktionen
  • Responses-API – Erweitertes Format, das Konversationen, Streaming und lang andauernde Agentprozesse unterstützt

Die Antwort-API ist nun der Standard- und empfohlene Ansatz gemäß der Dokumentation von OpenAI. Es bietet eine umfassendere und funktionsreiche Schnittstelle zum Erstellen von KI-Anwendungen mit integrierter Unterhaltungsverwaltung, Streaming-Funktionen und Unterstützung für lange laufende Prozesse.

Verwenden Sie die Antwort-API , wenn:

  • Erstellen neuer Anwendungen (empfohlener Standard)
  • Sie benötigen die Gesprächsverwaltung auf Serverseite. Dies ist jedoch keine Voraussetzung: Sie können die Responses-API weiterhin im zustandslosen Modus verwenden.
  • Sie möchten einen dauerhaften Chatverlauf
  • Sie erstellen lang laufende Agentenprozesse
  • Sie benötigen erweiterte Streamingfunktionen mit detaillierten Ereignistypen
  • Sie möchten einzelne Antworten nachverfolgen und verwalten (z. B. eine bestimmte Antwort nach ID abrufen, den Status überprüfen oder eine laufende Antwort abbrechen)

Verwenden Sie die Chatabschluss-API , wenn:

  • Migrieren vorhandener Anwendungen, die auf dem Format "Chatabschluss" basieren
  • Sie benötigen einfache, zustandslose Anforderungs-/Antwortinteraktionen
  • Die Zustandsverwaltung wird vollständig von Ihrem Client verarbeitet.
  • Sie integrieren sich mit bestehenden Tools, die nur Chat Completions unterstützen.
  • Sie benötigen maximale Kompatibilität mit älteren Systemen

Hosting-Agents als OpenAI-Endpunkte (.NET)

Mit der Microsoft.Agents.AI.Hosting.OpenAI Bibliothek können Sie KI-Agenten über OpenAI-kompatible HTTP-Endpunkte exponieren, die sowohl die APIs für Chatabschlüsse als auch Antworten unterstützen. Auf diese Weise können Sie Ihre Agents mit jedem openAI-kompatiblen Client oder Tool integrieren.

NuGet-Paket:

Chatvervollständigungs-API

Die Chat-Vervollständigungs-API stellt eine einfache, zustandslose Schnittstelle für die Interaktion mit Agents mithilfe des standardmäßigen OpenAI-Chatformats bereit.

Einrichten eines Agents in ASP.NET Core mit ChatCompletions-Integration

Hier ist ein vollständiges Beispiel, in dem ein Agent über die Chat Completions API bereitgestellt wird.

Voraussetzungen

1. Erstellen eines ASP.NET Core Web API-Projekts

Erstellen Sie ein neues ASP.NET Core Web API-Projekt, oder verwenden Sie ein vorhandenes.

2. Installieren erforderlicher Abhängigkeiten

Installieren Sie die folgenden Pakete:

Führen Sie die folgenden Befehle in Ihrem Projektverzeichnis aus, um die erforderlichen NuGet-Pakete zu installieren:

# 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. Konfigurieren der Azure OpenAI-Verbindung

Die Anwendung erfordert eine Azure OpenAI-Verbindung. Konfigurieren Sie den Endpunkt und den Bereitstellungsnamen mithilfe von dotnet user-secrets oder Umgebungsvariablen. Sie können auch einfach die appsettings.json bearbeiten, jedoch wird dies für Apps, die in der Produktion bereitgestellt werden, nicht empfohlen, da einige der Daten als geheim eingestuft werden können.

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. Hinzufügen des Codes zu Program.cs

Ersetzen Sie den Inhalt von Program.cs durch den folgenden Code.

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

Testen des Chat-Completion-Endpunkts

Sobald die Anwendung ausgeführt wird, können Sie den Agent mit dem OpenAI SDK oder http-Anforderungen testen:

Verwenden der HTTP-Anforderung

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

Hinweis: Ersetzen Sie den Serverendpunkt {{baseAddress}} durch Ihren Serverendpunkt.

Hier ist eine Beispielantwort:

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

Die Antwort enthält die Nachrichten-ID, den Inhalt und die Nutzungsstatistiken.

Chat-Abschlüsse unterstützen auch das Streaming, bei dem die Daten in Teilstücken ausgegeben werden, sobald diese verfügbar sind. Diese Funktion ermöglicht die progressive Anzeige der Ausgabe. Sie können Streaming aktivieren, indem Sie angeben "stream": true. Das Ausgabeformat besteht aus Server-Sent Events (SSE)-Blöcken, wie in der OpenAI Chat Completions-Spezifikation definiert.

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

Und die ausgabe, die wir erhalten, ist eine Reihe von ChatCompletions-Blöcken:

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

Die Streamingantwort enthält ähnliche Informationen, die jedoch als Server-Sent Events übermittelt werden.

Antwort-API

Die Responses-API bietet erweiterte Funktionen, einschließlich Unterhaltungsverwaltung, Streaming und Unterstützung für Langzeitprozesse von Agenten.

Einrichten eines Agents in ASP.NET Core with Responses API Integration

Hier ist ein vollständiges Beispiel mit der Antwort-API:

Voraussetzungen

Befolgen Sie die gleichen Anforderungen wie im Beispiel "Chat-Vervollständigungen" (Schritte 1-3).

4. Hinzufügen des Codes zu 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();

Testen der Antwort-API

Die Antwort-API ähnelt Chatabschlussen, ist aber statusbehaftet, sodass Sie einen conversation Parameter übergeben können. Wie Chatabschlusse unterstützt sie den stream Parameter, der das Ausgabeformat steuert: entweder eine einzelne JSON-Antwort oder einen Datenstrom von Ereignissen. Die Antwort-API definiert ihre eigenen Streamingereignistypen, einschließlich response.created, response.output_item.added, response.output_item.done, response.completedund andere.

Erstellen einer Unterhaltung und Antwort

Sie können eine Antwortanforderung direkt senden, oder Sie können zuerst eine Unterhaltung mithilfe der Unterhaltungs-API erstellen und dann nachfolgende Anforderungen mit dieser Unterhaltung verknüpfen.

Erstellen Sie zunächst eine neue Unterhaltung:

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

Die Antwort enthält die Unterhaltungs-ID:

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

Senden Sie als Nächstes eine Anfrage, und geben Sie den Unterhaltungsparameter an. (Um die Antwort als Streamingereignisse zu empfangen, legen Sie dies in der Anforderung fest "stream": true .)

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

Der Agent gibt die Antwort zurück und speichert die Unterhaltungselemente zum späteren Abruf:

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

Die Antwort umfasst Unterhaltungs- und Nachrichtenkennungen, Inhalte und Nutzungsstatistiken.

Um die Unterhaltungselemente abzurufen, senden Sie diese Anforderung:

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

Dadurch wird eine JSON-Antwort zurückgegeben, die sowohl Eingabe- als auch Ausgabemeldungen enthält:

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

Offenlegung mehrerer Agenten

Sie können mehrere Agents gleichzeitig mit beiden Protokollen verfügbar machen:

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

Agents sind verfügbar unter:

  • Chatabschluss: /math/v1/chat/completions und /science/v1/chat/completions
  • Antworten: /math/v1/responses und /science/v1/responses

Benutzerdefinierte Endpunkte

Sie können die Endpunktpfade anpassen:

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

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

Herstellen einer Verbindung mit OpenAI-Compatible Endpunkten (Python)

OpenAIChatClient Python und OpenAIResponsesClient beide unterstützen einen base_url Parameter, mit dem Sie eine Verbindung mit jedem openAI-kompatiblen Endpunkt herstellen können, einschließlich selbst gehosteter Agents, lokaler Rückschlussserver (Ollama, LM Studio, vLLM) oder openAI-kompatiblen APIs von Drittanbietern.

pip install agent-framework --pre

Chat-Abschluss-Client

Verwenden Sie OpenAIChatClient mit base_url, um auf einen beliebigen mit Chat Completions kompatiblen Server zu verweisen:

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

Antworten-Client

Verwenden Sie OpenAIResponsesClient gemeinsam mit base_url für Endpunkte, die die Antwort-API unterstützen.

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

Allgemeine OpenAI-kompatible Server

Der base_url Ansatz funktioniert mit jedem Server, auf dem das OpenAI Chat Completions-Format verfügbar ist:

Server Stamm-URL Hinweise
Ollama http://localhost:11434/v1/ Lokale Ableitung, kein API-Schlüssel erforderlich
LM Studio http://localhost:1234/v1/ Lokale Ableitung mit GUI
vLLM http://localhost:8000/v1/ Dienste mit hohem Durchsatz
Azure AI Foundry Ihr Bereitstellungsendpunkt Verwendet Azure-Anmeldeinformationen
Gehostete Agenten des Frameworks Ihr Agenten-Endpunkt .NET-Agents, die über MapOpenAIChatCompletions exposed werden

Hinweis

Sie können auch die OPENAI_BASE_URL Umgebungsvariable festlegen, anstatt base_url direkt zu übergeben. Der Client verwendet ihn automatisch.

Verwenden von Azure OpenAI-Clients

Die Azure OpenAI-Varianten (AzureOpenAIChatClient, AzureOpenAIResponsesClient) stellen eine Verbindung mit Azure OpenAI-Endpunkten mithilfe von Azure-Anmeldeinformationen her – nicht base_url erforderlich:

from agent_framework.azure import AzureOpenAIResponsesClient

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

Konfigurieren mit Umgebungsvariablen:

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

Siehe auch

Nächste Schritte

Zuständigkeitsbereich

  • Last updated on