Megosztás:

OpenAI-Compatible végpontok

Az Agent Framework támogatja az OpenAI-kompatibilis protokollokat mind a standard API-k mögötti üzemeltetési ügynökökhöz, mind pedig bármely OpenAI-kompatibilis végponthoz való csatlakozáshoz .

Mik azok az OpenAI-protokollok?

Két OpenAI-protokoll támogatott:

  • Csevegés befejezései API – Normál állapot nélküli kérés-/válaszformátum csevegési interakciókhoz
  • Responses API – Speciális formátum, amely támogatja a beszélgetéseket, a streamelést és a hosszan futó ügynökfolyamatokat

Az OpenAI dokumentációja szerint a Válasz API az alapértelmezett és ajánlott megközelítés. Átfogóbb és funkciógazdagabb felületet biztosít az AI-alkalmazások létrehozásához beépített beszélgetéskezeléssel, streamelési képességekkel és a hosszú ideig futó folyamatok támogatásával.

Használja a Responses API-t a következő esetekben:

  • Új alkalmazások létrehozása (ajánlott alapértelmezett)
  • Kiszolgálóoldali beszélgetéskezelésre van szükség. Ez azonban nem követelmény: állapot nélküli módban továbbra is használhatja a Responses API-t.
  • Állandó beszélgetési előzményeket szeretne
  • Hosszú ideig futó ügynök-folyamatokat készít
  • Speciális streamelési képességekre van szüksége részletes eseménytípusokkal
  • Nyomon szeretné követni és kezelni szeretné az egyes válaszokat (például lekérhet egy adott választ azonosító alapján, ellenőrizheti annak állapotát, vagy megszakíthatja a futó választ)

Használja a Csevegés befejezése API-t a következő esetekben:

  • Meglévő alkalmazások migrálása, amelyek a Csevegés befejezések formátumra támaszkodnak
  • Egyszerű, állapot nélküli kérés-válasz interakciókra van szüksége
  • Az állapotkezelést teljes egészében a kliens kezeli
  • Olyan meglévő eszközökkel integrál, amelyek csak a csevegés befejezését támogatják
  • Az örökölt rendszerekkel való maximális kompatibilitásra van szükség

Ügynökök üzemeltetése OpenAI-végpontként (.NET)

A Microsoft.Agents.AI.Hosting.OpenAI kódtár lehetővé teszi az AI-ügynökök közzétételét OpenAI-kompatibilis HTTP-végpontokon keresztül, amelyek támogatják a csevegés befejezését és a Válaszok API-kat is. Ez lehetővé teszi az ügynökök integrálását bármely OpenAI-kompatibilis ügyféllel vagy eszközzel.

NuGet-csomag:

Csevegés kiegészítések API

A Chat Completions API egy egyszerű, állapot nélküli felületet biztosít az ügynökökkel való kommunikációhoz a standard OpenAI csevegési formátum használatával.

Ügynök beállítása a ASP.NET Core-ban a ChatCompletions integrációjával

Íme egy teljes példa, amely egy ügynököt mutat be a Csevegés befejezése API-val:

Előfeltételek

1. ASP.NET Core Web API-projekt létrehozása

Hozzon létre egy új ASP.NET Core Web API-projektet, vagy használjon egy meglévőt.

2. A szükséges függőségek telepítése

Telepítse a következő csomagokat:

Futtassa a következő parancsokat a projektkönyvtárban a szükséges NuGet-csomagok telepítéséhez:

# 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-kapcsolat konfigurálása

Az alkalmazáshoz Azure OpenAI-kapcsolat szükséges. Konfigurálja a végpontot és az üzembe helyezés nevét a dotnet user-secrets vagy a környezeti változók használatával. Egyszerűen szerkesztheti is a appsettings.jsondokumentumot, de az éles környezetben üzembe helyezett alkalmazások esetében ez nem ajánlott, mivel egyes adatok titkosnak tekinthetők.

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. Adja hozzá a kódot a Program.cs

Cserélje le a Program.cs tartalmát a következő kódra:

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

A csevegés befejezésének végpontjának tesztelése

Az alkalmazás futtatása után az Ügynök tesztelése az OpenAI SDK-val vagy HTTP-kérésekkel lehetséges:

HTTP-kérés használata

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

Megjegyzés: Cserélje le a {{baseAddress}} kifejezést a kiszolgáló végpontjával.

Íme egy mintaválasz:

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

A válasz tartalmazza az üzenetazonosítót, a tartalmat és a használati statisztikákat.

A csevegés befejezései a streamelést is támogatják, ahol a kimenetet a tartalom rendelkezésre állása után, adattömbökben adja vissza. Ez a funkció lehetővé teszi a kimenet fokozatos megjelenítését. A streamelést a megadásával "stream": trueengedélyezheti. A kimeneti formátum Server-Sent Események (SSE) adattömbökből áll, az OpenAI csevegéskimenetek specifikációjában meghatározottak szerint.

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

A kapott kimenet, egy ChatCompletions adattömb-készlet:

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

A streamelési válasz hasonló információkat tartalmaz, de Server-Sent eseményekként kézbesítve.

Responses API (Válaszok API)

A Responses API speciális funkciókat biztosít, beleértve a beszélgetések kezelését, a streamelést és a hosszú ideig futó ügynökfolyamatok támogatását.

Ügynök beállítása a ASP.NET Core-ban a Responses API-integrációval

Íme egy teljes példa a Responses API használatával:

Előfeltételek

Kövesse ugyanazokat az előfeltételeket, mint a Csevegés befejezése példa (1–3. lépés).

4. Adja hozzá a kódot 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();

A Responses API tesztelése

A Responses API hasonló a csevegés befejezéséhez, de állapotalapú, lehetővé téve egy paraméter átadását conversation . A csevegés befejezéséhez hasonlóan a paramétert is támogatja stream , amely a kimeneti formátumot vezérli: egyetlen JSON-választ vagy eseményfolyamot. A Responses API saját streamelési eseménytípusokat határoz meg, beleértve a response.created, response.output_item.added, response.output_item.done, response.completedés egyéb eseményeket.

Beszélgetés és válasz létrehozása

Közvetlenül is küldhet válaszkérést, vagy először létrehozhat egy beszélgetést a Beszélgetések API-val, majd összekapcsolhatja a további kéréseket a beszélgetéshez.

Először hozzon létre egy új beszélgetést:

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

A válasz tartalmazza a beszélgetés azonosítóját:

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

Ezután küldjön egy kérést, és adja meg a beszélgetési paramétert. (A válasz streamelési eseményként való fogadásához állítsa be "stream": true a kérést.)

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

Az ügynök visszaadja a választ, és menti a beszélgetési elemeket a tárolóba későbbi lekérés céljából:

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

A válasz tartalmazza a beszélgetési és üzenetazonosítókat, a tartalmakat és a használati statisztikákat.

A beszélgetési elemek lekéréséhez küldje el ezt a kérést:

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

Ez egy JSON-választ ad vissza, amely mind a bemeneti, mind a kimeneti üzeneteket tartalmazza:

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

Több ügynök leleplezése

Egyszerre több ügynököt is közzétehet mindkét protokoll használatával:

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

Az ügynökök a következő címen lesznek elérhetők:

  • Csevegés befejezése: /math/v1/chat/completions és /science/v1/chat/completions
  • Válaszok: /math/v1/responses és /science/v1/responses

Egyéni végpontok

A végpont elérési útjai testre szabhatók:

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

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

Csatlakozás OpenAI-Compatible végpontokhoz (Python)

A Python OpenAIChatClient és OpenAIResponsesClient mindkettő támogat egy paramétert base_url , amely lehetővé teszi, hogy bármilyen OpenAI-kompatibilis végponthoz csatlakozzon – beleértve a saját üzemeltetésű ügynököket, a helyi következtetési kiszolgálókat (Ollama, LM Studio, vLLM) vagy a külső OpenAI-kompatibilis API-kat.

pip install agent-framework --pre

Csevegés befejezési kliens

OpenAIChatClient és base_url használata bármely Chat Completions-kompatibilis szerverre mutatáshoz:

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

Válaszügyfél

Használja OpenAIResponsesClient és base_url azokon a végpontokon, amelyek támogatják a Responses API-t.

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

Gyakori OpenAI-Compatible-kiszolgálók

A base_url megközelítés az OpenAI-csevegés befejezései formátumot tartalmazó bármely kiszolgálóval működik:

Server Alap URL-cím Jegyzetek
Ollama http://localhost:11434/v1/ Helyi következtetés, nincs szükség API-kulcsra
LM Studio http://localhost:1234/v1/ Helyi következtetés grafikus felhasználói felülettel
vLLM http://localhost:8000/v1/ Nagy áteresztőképességű kiszolgálás
Azure AI Foundry Az üzembehelyezési végpont Azure-hitelesítő adatok használata
Üzemeltetett ügynökkeretrendszer ügynökei Az ügynökvégpont .NET-ügynökök közzétéve a MapOpenAIChatCompletions által

Megjegyzés:

A OPENAI_BASE_URL környezeti változót is beállíthatja ahelyett, hogy közvetlenül átadná a base_url-t. Az ügyfél automatikusan használja.

Azure OpenAI-ügyfelek használata

Az Azure OpenAI-variánsok (AzureOpenAIChatClient, AzureOpenAIResponsesClient) Azure-beli hitelesítő adatokkal csatlakoznak az Azure OpenAI-végpontokhoz – nem base_url szükséges:

from agent_framework.azure import AzureOpenAIResponsesClient

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

Konfigurálás környezeti változókkal:

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

Lásd még:

Következő lépések

Hatáskör, terjedelem

  • Last updated on