Megjegyzés
Az oldalhoz való hozzáféréshez engedély szükséges. Megpróbálhat bejelentkezni vagy módosítani a címtárat.
Az oldalhoz való hozzáféréshez engedély szükséges. Megpróbálhatja módosítani a címtárat.
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:
Prerequisites
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:
Prerequisites
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.
Válasz folytatása
A Válaszok protokoll két egymást kölcsönösen kizáró módszert kínál a folytatásra:
- Állítsa a(z)
previous_response_idértékét az előző válasz által visszaadottresp_*azonosítóra. Ez az azonosító minden egyes fordulóval megváltozik, és azt a válaszláncot követi. - Állítsa a(z)
conversationelemetconv_*azonosítóra. A beszélgetés azonosítója több fordulóban is stabil marad, és a bemenetek és kimenetek hozzá lesznek adva a beszélgetéshez.
MapOpenAIResponses kezeli a Responses API-tárolót a végpontjaihoz. Ha az alkalmazás ehelyett kezeli az útvonalat, és a OpenAIResponses segédeket egy AgentSessionStore elemmel használja, a OpenAIResponses.GetSessionStoreId(...) a previous_response_id értéket adja vissza, ha van ilyen, ellenkező esetben pedig a beszélgetésazonosítót. Válaszlánc esetén töltse be a korábbi pillanatképet, és mentse a továbbfejlesztett munkamenetet az új válaszazonosító alatt. Beszélgetés esetén töltse be és mentse a munkamenetet ugyanabban a beszélgetési azonosítóban.
Important
A válasz- és beszélgetésazonosítókat nem engedélyezési hitelesítő adatokként, hanem átlátszatlan folytatási adatokként kezelheti. Mielőtt elfogadná a(z) previous_response_id vagy conversation értéket egy ügyféltől, ellenőrizze, hogy a hitelesített felhasználó vagy bérlő annak az azonosítónak a tulajdonosa-e. Az alkalmazás tulajdonában lévő, a AgentSessionStore elemet használó útvonal esetében engedélyezze a munkamenet-elkülönítést.
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 OpenAIChatCompletionClient és OpenAIChatClient 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
Csevegés befejezési kliens
OpenAIChatCompletionClient és base_url használata bármely Chat Completions-kompatibilis szerverre mutatáshoz:
import asyncio
from agent_framework import Agent, tool
from agent_framework.openai import OpenAIChatCompletionClient
@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 = Agent(
client=OpenAIChatCompletionClient(
base_url="http://localhost:11434/v1/", # e.g. Ollama
api_key="not-needed", # placeholder for local servers
model="llama3.2",
),
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álaszkliens
Használja OpenAIChatClient és base_url azokon a végpontokon, amelyek támogatják a Responses API-t.
import asyncio
from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient
async def main():
agent = Agent(
client=OpenAIChatClient(
base_url="https://your-hosted-agent.example.com/v1/",
api_key="your-api-key",
model="gpt-4o-mini",
),
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 | Megjegyzések: |
|---|---|---|
| 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 |
| Microsoft 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
Használja ugyanazokat az általános OpenAI-ügyfeleket az Azure OpenAI-hoz, ha explicit Azure-útválasztási bemeneteket ad át a következő base_urlhelyett:
import os
from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient
from azure.identity import AzureCliCredential
agent = Agent(
client=OpenAIChatClient(
model=os.environ["AZURE_OPENAI_CHAT_MODEL"],
azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
credential=AzureCliCredential(),
),
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_CHAT_MODEL="gpt-4o-mini"
export AZURE_OPENAI_API_VERSION="your-api-version"
OpenAIChatClient előnyben részesíti a AZURE_OPENAI_CHAT_MODEL-t; a AZURE_OPENAI_MODEL továbbra is a megosztott tartalék, ha szüksége van egyre.
Go a csomagot a provider/openaiprovider hivatalos OpenAI Go-ügyféllel használja. Használja a(z) openaiprovider.NewChatCompletionsAgent elemet a Chat Completions-kompatibilis végpontokhoz, és konfigurálja az Azure OpenAI-t az OpenAI-ügyfélprogram Azure-beállításaival.
import (
"github.com/microsoft/agent-framework-go/provider/openaiprovider"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/azure"
)
a := openaiprovider.NewChatCompletionsAgent(
openai.NewClient(
azure.WithEndpoint(endpoint, apiVersion),
azure.WithTokenCredential(token),
),
openaiprovider.AgentConfig{
Model: deployment,
Instructions: "You are a helpful assistant.",
},
)
Tip
A teljes futtatható példákért tekintse meg az OpenAI-szolgáltató mintáját, és Azure OpenAI-szolgáltatói mintát.
Lásd még
- Integrációk áttekintése
- A2A-hosztolás
- OpenAI Chat Completions API-referencia
- OpenAI Válaszok API referencia