Delen via

OpenAI-compatibele eindpunten

Het Agent Framework ondersteunt openAI-compatibele protocollen voor zowel hostingagenten achter standaard-API's als verbinding maken met elk openAI-compatibel eindpunt.

Wat zijn OpenAI-protocollen?

Er worden twee OpenAI-protocollen ondersteund:

  • API voor chatvoltooiing — standaard stateless aanvraag/antwoordindeling voor chatinteracties
  • Antwoord-API : geavanceerde indeling die ondersteuning biedt voor gesprekken, streaming en langlopende agentprocessen

De Response-API is nu de standaard- en aanbevolen benadering volgens de documentatie van OpenAI. Het biedt een uitgebreidere en uitgebreidere interface voor het bouwen van AI-toepassingen met ingebouwd gespreksbeheer, streamingmogelijkheden en ondersteuning voor langlopende processen.

Gebruik de antwoorden-API wanneer:

  • Nieuwe toepassingen bouwen (aanbevolen standaard)
  • U hebt gespreksbeheer aan de serverzijde nodig. Dat is echter geen vereiste: u kunt ook de Responses-API gebruiken in een stateless modus.
  • U wilt permanente gespreksgeschiedenis
  • U bouwt langlopende agentprocessen
  • U hebt geavanceerde streamingmogelijkheden met gedetailleerde gebeurtenistypen nodig
  • U wilt afzonderlijke antwoorden bijhouden en beheren (bijvoorbeeld een specifiek antwoord ophalen op basis van id, de status ervan controleren of een actief antwoord annuleren)

Gebruik de API voor chatvoltooiing wanneer:

  • Bestaande applicaties migreren die afhankelijk zijn van het Chat Completions-formaat
  • Je hebt eenvoudige, toestandloze aanvraag-/antwoordinteracties nodig
  • Statusbeheer wordt volledig verwerkt door uw client
  • U integreert met bestaande hulpprogramma's die alleen ondersteuning bieden voor chatvoltooiingen
  • U hebt maximale compatibiliteit met verouderde systemen nodig

Het verwerken van agents als OpenAI-eindpunten (.NET)

Met de Microsoft.Agents.AI.Hosting.OpenAI bibliotheek kunt u AI-agents beschikbaar maken via HTTP-eindpunten die compatibel zijn met OpenAI, waardoor zowel de API's voor chatvoltooiingen als antwoorden worden ondersteund. Hierdoor kunt u uw agents integreren met elke openAI-compatibele client of elk hulpprogramma dat compatibel is met OpenAI.

NuGet-pakket:

API voor voltooiing van chat

De API voor chatvoltooiing biedt een eenvoudige, staatloze interface voor interactie met agents met behulp van de standaard OpenAI-chatindeling.

Een agent instellen in ASP.NET Core met ChatCompletions-integratie

Hier volgt een volledig voorbeeld van het weergeven van een agent via de API voor chatvoltooiing:

Vereiste voorwaarden

1. Een ASP.NET Core Web API-project maken

Maak een nieuw ASP.NET Core Web API-project of gebruik een bestaand web-API-project.

2. Vereiste afhankelijkheden installeren

Installeer de volgende pakketten:

Voer de volgende opdrachten uit in uw projectmap om de vereiste NuGet-pakketten te installeren:

# 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. Azure OpenAI-verbinding configureren

Voor de toepassing is een Azure OpenAI-verbinding vereist. Configureer de eindpunt- en implementatienaam met behulp van dotnet user-secrets of omgevingsvariabelen. U kunt ook gewoon de appsettings.json bewerken, maar dat wordt niet aanbevolen voor de apps die in productie zijn, aangezien sommige gegevens als vertrouwelijk worden beschouwd.

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. Voeg de code toe aan Program.cs

Vervang de inhoud van Program.cs met de volgende 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();

Het testen van het eindpunt voor chatvoltooiingen

Zodra de toepassing wordt uitgevoerd, kunt u de agent testen met behulp van de OpenAI SDK of HTTP-aanvragen:

HTTP-aanvraag gebruiken

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

Opmerking: Vervang {{baseAddress}} door uw servereindpunt.

Hier volgt een voorbeeldantwoord:

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

Het antwoord bevat de bericht-id, inhoud en gebruiksstatistieken.

Chatvoltooiingen ondersteunen ook streaming, waarbij uitvoer wordt geretourneerd in segmenten zodra inhoud beschikbaar is. Met deze mogelijkheid kunt u de uitvoer progressief weergeven. U kunt streaming inschakelen door de waarde "stream": true op te geven. De uitvoerindeling bestaat uit Server-Sent Events (SSE)-segmenten zoals gedefinieerd in de OpenAI Chat Completions-specificatie.

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

En de uitvoer die we krijgen is een set ChatCompletions-segmenten.

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

Het streaming-antwoord bevat vergelijkbare informatie, maar geleverd als Server-Sent Events.

Antwoord-API

De Antwoorden-API biedt geavanceerde functies, waaronder gespreksbeheer, streaming en ondersteuning voor langlopende agentprocessen.

Een agent instellen in ASP.NET Core met antwoord-API-integratie

Hier volgt een volledig voorbeeld met behulp van de Antwoorden-API:

Vereiste voorwaarden

Volg dezelfde voorvereisten als het voorbeeld van chat-completies (stappen 1-3).

4. Voeg de code toe aan 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();

De antwoorden-API testen

De Antwoorden-API is vergelijkbaar met chatvoltooiingen, maar is stateful, zodat u een conversation parameter kunt doorgeven. Net als chatvoltooiingen ondersteunt het de stream parameter, waarmee de uitvoerindeling wordt beheerd: één JSON-antwoord of een stroom gebeurtenissen. De Antwoorden-API definieert zijn eigen typen streaming-gebeurtenissen, waaronder response.created, response.output_item.added, response.output_item.doneen response.completedandere.

Een gesprek en antwoord maken

U kunt een aanvraag voor antwoorden rechtstreeks verzenden of u kunt eerst een gesprek maken met behulp van de Conversations-API en vervolgens volgende aanvragen aan dat gesprek koppelen.

Maak eerst een nieuw gesprek:

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

Het antwoord bevat de gespreks-id:

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

Verzend vervolgens een aanvraag en geef de gespreksparameter op. (Als u het antwoord wilt ontvangen als streaming-gebeurtenissen, stelt u "stream": true deze in de aanvraag in.)

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

De agent retourneert het antwoord en slaat de gespreksitems op in de opslag voor later ophalen:

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

Het antwoord bevat gespreks- en bericht-id's, inhoud en gebruiksstatistieken.

Als u de gespreksitems wilt ophalen, verzendt u deze aanvraag:

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

Hiermee wordt een JSON-antwoord geretourneerd dat zowel invoer- als uitvoerberichten bevat:

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

Meerdere agents exposeren

U kunt meerdere agents tegelijk beschikbaar maken met behulp van beide protocollen:

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 zijn beschikbaar op:

  • Chatvoltooiingen: /math/v1/chat/completions en /science/v1/chat/completions
  • Antwoorden: /math/v1/responses en /science/v1/responses

Aangepaste eindpunten

U kunt de eindpuntpaden aanpassen:

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

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

Verbinding maken met OpenAI-Compatible-eindpunten (Python)

Python OpenAIChatClient en OpenAIResponsesClient beide ondersteunen een base_url parameter, zodat u verbinding kunt maken met elk openAI-compatibel eindpunt, waaronder zelf-hostende agents, lokale deductieservers (Ollama, LM Studio, vLLM) of openAI-compatibele API's van derden.

pip install agent-framework --pre

Client voor voltooiing van chat

Gebruik OpenAIChatClient met base_url om naar een Chat Completions-compatibele server te verwijzen:

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

Antwoordclient

Gebruik OpenAIResponsesClient met base_url voor eindpunten die ondersteuning bieden voor de Antwoorden-API:

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

Veelvoorkomende OpenAI-compatibele servers

De base_url benadering werkt met elke server die het OpenAI Chat-completieformaat beschikbaar maakt.

Server Basis-URL Opmerkingen
Ollama http://localhost:11434/v1/ Lokale deductie, geen API-sleutel nodig
LM Studio http://localhost:1234/v1/ Lokale deductie met GUI
vLLM http://localhost:8000/v1/ Server met hoge doorvoer
Azure AI Foundry Uw implementatie-eindpunt Maakt gebruik van Azure-referenties
Gehoste Agent Framework-agents Uw agenteindpunt .NET-agents beschikbaar gesteld via MapOpenAIChatCompletions

Opmerking

U kunt ook de OPENAI_BASE_URL omgevingsvariabele instellen in plaats van rechtstreeks door te geven base_url . De client gebruikt deze automatisch.

Azure OpenAI-clients gebruiken

De Azure OpenAI-varianten (AzureOpenAIChatClient, AzureOpenAIResponsesClient) maken verbinding met Azure OpenAI-eindpunten met behulp van Azure-referenties — geen base_url nodig:

from agent_framework.azure import AzureOpenAIResponsesClient

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

Configureren met omgevingsvariabelen:

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

Zie ook

Volgende stappen

Purview

  • Last updated on