Sdílet prostřednictvím

Koncové body kompatibilní s OpenAI

Rozhraní Agent Framework podporuje protokoly kompatibilní s OpenAI pro hostování agentů za standardními rozhraními API a připojení k libovolnému koncovému bodu kompatibilnímu s OpenAI.

Co jsou protokoly OpenAI?

Podporují se dva protokoly OpenAI:

  • Rozhraní API pro dokončování chatu – standardní bezstavové formáty požadavků a odpovědí pro interakce chatu
  • Rozhraní API pro odpovědi – rozšířený formát, který podporuje konverzace, streamování a dlouhotrvající procesy agenta

Rozhraní API pro odpovědi je teď výchozím a doporučeným přístupem podle dokumentace OpenAI. Poskytuje komplexnější a plnohodnotné rozhraní pro vytváření aplikací AI s integrovanou správou konverzací, možnostmi streamování a podporou dlouhotrvajících procesů.

Rozhraní API pro odpovědi použijte v následujících případech:

  • Vytváření nových aplikací (doporučeno jako výchozí)
  • Potřebujete správu konverzací na straně serveru. To ale není požadavek: Rozhraní API pro odpovědi můžete dál používat v bezstavovém režimu.
  • Chcete trvalou historii konverzací.
  • Vytváříte procesy agentů běžící po dlouhou dobu.
  • Potřebujete pokročilé možnosti streamování s podrobnými typy událostí.
  • Chcete sledovat a spravovat jednotlivé odpovědi (např. načíst konkrétní odpověď podle ID, zkontrolovat její stav nebo zrušit spuštěnou odpověď).

Rozhraní API pro dokončování chatu použijte v následujících případech:

  • Migrace existujících aplikací, které spoléhají na formát Dokončování chatu
  • Potřebujete jednoduché bezstavové interakce požadavků a odpovědí.
  • Správa stavu je zcela v rukou vašeho klienta.
  • Integrujete se se stávajícími nástroji, které podporují pouze dokončování chatu.
  • Potřebujete maximální kompatibilitu se staršími systémy.

Hostování agentů jako koncových bodů OpenAI (.NET)

Knihovna Microsoft.Agents.AI.Hosting.OpenAI umožňuje zpřístupnit agenty AI prostřednictvím koncových bodů HTTP, které jsou kompatibilní s OpenAI, a podporují rozhraní API pro dokončování chatu i odpovědi. To vám umožní integrovat agenty s libovolným klientem nebo nástrojem kompatibilním s OpenAI.

Balíček NuGet:

Rozhraní API pro dokončení chatu

Rozhraní API pro dokončování chatu poskytuje jednoduché bezstavové rozhraní pro interakci s agenty pomocí standardního formátu chatu OpenAI.

Nastavení agenta v ASP.NET Core s integrací ChatCompletions

Tady je úplný příklad zveřejnění agenta prostřednictvím rozhraní API pro dokončování chatu:

Požadavky

1. Vytvoření projektu webového rozhraní API ASP.NET Core

Vytvořte nový projekt webového rozhraní API ASP.NET Core nebo použijte existující projekt.

2. Instalace požadovaných závislostí

Nainstalujte následující balíčky:

Spuštěním následujících příkazů v adresáři projektu nainstalujte požadované balíčky NuGet:

# 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. Konfigurace připojení Azure OpenAI

Aplikace vyžaduje připojení Azure OpenAI. Nakonfigurujte koncový bod a název nasazení pomocí dotnet user-secrets nebo proměnných prostředí. Můžete také jednoduše upravit appsettings.json, ale to se nedoporučuje pro aplikace nasazené v produkčním prostředí, protože některá data se dají považovat za tajná.

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. Přidejte kód do Program.cs

Obsah Program.cs nahraďte následujícím kódem:

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

Testování koncového bodu dokončení chatu

Po spuštění aplikace můžete agenta otestovat pomocí sady OpenAI SDK nebo požadavků HTTP:

Použití požadavku HTTP

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

Poznámka: Nahraďte {{baseAddress}} koncovým bodem serveru.

Tady je ukázková odpověď:

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

Odpověď zahrnuje ID zprávy, obsah a statistiku využití.

Dokončování chatu také podporuje streamování, kde se výstup vrátí v blocích, jakmile bude obsah k dispozici. Tato funkce umožňuje postupně zobrazovat výstup. Streamování můžete povolit zadáním "stream": true. Výstupní formát se skládá z bloků Server-Sent Events (SSE), jak je definováno ve specifikaci Chat Completions od OpenAI.

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

Výstupem, který získáme, je sada bloků 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}}}

Odpověď streamování obsahuje podobné informace, ale doručované ve formě událostí Server-Sent.

API rozhraní pro odpovědí

Rozhraní API pro odpovědi poskytuje pokročilé funkce, včetně správy konverzací, streamování a podpory pro dlouhotrvající procesy agentů.

Nastavení agenta v ASP.NET Core s integrací rozhraní API pro odpovědi

Tady je úplný příklad použití rozhraní API pro odpovědi:

Požadavky

Postupujte podle stejných požadavků jako v příkladu dokončení chatu (kroky 1 až 3).

4. Přidejte kód do 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();

Testování rozhraní API pro odpovědi

Rozhraní API pro odpovědi se podobá procesu dokončování chatu, ale je stavové, což vám umožňuje předat parametr conversation. Podobně jako u dokončování chatu podporuje parametr stream, který řídí výstupní formát: buď jednu odpověď JSON, nebo datový proud událostí. Rozhraní API pro odpovědi definuje vlastní typy událostí streamování, včetně response.created, response.output_item.added, response.output_item.done, response.completed a dalších.

Vytvoření konverzace a odpovědi

Žádost o odpovědi můžete odeslat přímo, nebo můžete napřed vytvořit konverzaci pomocí rozhraní API pro konverzace a pak propojit další žádosti s danou konverzací.

Začněte vytvořením nové konverzace:

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

Odpověď obsahuje ID konverzace:

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

Dále odešlete požadavek a zadejte parametr konverzace. (Pokud chcete přijmout odpověď jako události streamování, nastavte "stream": true v požadavku.)

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

Agent vrátí odpověď a uloží položky konverzace do úložiště pro pozdější načtení:

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

Odpověď zahrnuje identifikátory konverzací a zpráv, obsah a statistiky využití.

Pokud chcete načíst položky konverzace, odešlete tento požadavek:

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

Vrátí odpověď JSON obsahující vstupní i výstupní zprávy:

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

Zpřístupnění více agentů

Pomocí obou protokolů můžete současně vystavit více agentů:

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

Agenti budou k dispozici na adrese:

  • Dokončení chatu: /math/v1/chat/completions a /science/v1/chat/completions
  • Odpovědi: /math/v1/responses a /science/v1/responses

Vlastní koncové body

Cesty ke koncovému bodu můžete přizpůsobit:

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

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

Připojení ke koncovým bodům OpenAI-Compatible (Python)

Python OpenAIChatClient i OpenAIResponsesClient oba podporují base_url parametr, který umožňuje připojení k libovolnému koncovému bodu kompatibilnímu s OpenAI – včetně místních agentů, místních serverů odvozování (Ollama, LM Studio, vLLM) nebo rozhraní API kompatibilních s OpenAI třetích stran.

pip install agent-framework --pre

Klient dokončení chatu

Použijte OpenAIChatClient s base_url k odkazování na jakýkoli server kompatibilní s dokončováním chatu.

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

Odpovědní klient

Použijte OpenAIResponsesClient s base_url pro koncové body, které podporují API odpovědí:

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

Běžné OpenAI-kompatibilní servery

Tento base_url přístup funguje s libovolným serverem, který využívá formát dokončování konverzací OpenAI.

počítačový server Základní adresa URL Poznámky
Ollama http://localhost:11434/v1/ Místní odvození, nevyžaduje se žádný klíč rozhraní API.
LM Studio http://localhost:1234/v1/ Místní odvození s grafickým uživatelským rozhraním
vLLM http://localhost:8000/v1/ Obsluha s vysokou propustností
Azure AI Foundry Váš koncový bod nasazení Používá přihlašovací údaje Azure.
Agenti hostovaného agenta Framework Koncový bod vašeho agenta Agenti .NET vystavení prostřednictvím MapOpenAIChatCompletions

Poznámka:

Proměnnou OPENAI_BASE_URL prostředí můžete nastavit také místo přímého předávání base_url . Klient ho použije automaticky.

Použití klientů Azure OpenAI

Varianty Azure OpenAI (AzureOpenAIChatClient, AzureOpenAIResponsesClient) se připojují ke koncovým bodům Azure OpenAI pomocí přihlašovacích údajů Azure – bez base_url nutnosti:

from agent_framework.azure import AzureOpenAIResponsesClient

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

Nakonfigurujte pomocí proměnných prostředí:

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

Viz také

Další kroky

Rozsah působnosti

  • Last updated on