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:

• Microsoft.Agents.AI.Hosting.OpenAI

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:

Předpoklady

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:

rozhraní příkazového řádku .NET

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á.

Tajné kódy uživatele

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"

Windows ENV

$env:AZURE_OPENAI_ENDPOINT = "https://<your-openai-resource>.openai.azure.com/"
$env:AZURE_OPENAI_DEPLOYMENT_NAME = "gpt-4o-mini"

ENV unix

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

appsettings

  "AZURE_OPENAI_ENDPOINT": "https://<your-openai-resource>.openai.azure.com/",
  "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.

Rozhraní API pro odpovědi

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:

Předpoklady

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.

Important

Odpověď OpenAI a ID konverzací jsou neprůhlená ID na straně služby. OpenAI ve výchozím nastavení omezuje ID resp_* a conv_* na příslušný klíč rozhraní API nebo projekt, takže bývají obvykle omezená, když tato hranice odpovídá hranici vaší aplikace nebo tenanta. Riziko vzniká, když hostovaný agent používá jeden podkladový klíč nebo projekt pro více koncových uživatelů, vrací klientům nezpracovaná ID OpenAI a přijímá tato ID zpět, aniž by ověřoval jejich vlastnictví. Uložte je na serveru, namapujte je podle svých vlastních ID klientských relací a před jejich předáním jako previous_response_id nebo conversation ověřte autentizovaného uživatele nebo tenanta.

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 OpenAIChatCompletionClient i OpenAIChatClient 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

Klient dokončení chatu

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

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

Klient pro odpovědi

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

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

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.

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í
Microsoft 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

Note

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

Stejné obecné klienty OpenAI pro Azure OpenAI použijte tak, že předáte explicitní vstupy směrování Azure místo base_url:

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.",
)

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

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 preferuje AZURE_OPENAI_CHAT_MODEL; AZURE_OPENAI_MODEL zůstává sdíleným záložním řešením, pokud ho potřebujete.

Go používá provider/openaiprovider balíček s oficiálním klientem OpenAI Go. Použijte openaiprovider.NewChatCompletionsAgent pro koncové body kompatibilní s rozhraním Chat Completions a nakonfigurujte Azure OpenAI pomocí možností Azure klienta OpenAI.

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

Podívejte se na ukázku poskytovatele OpenAI a ukázku poskytovatele Azure OpenAI, kde najdete úplné spustitelné příklady.

Viz taky

• Přehled integrací
• Hostování A2A
• Referenční informace k rozhraní API pro dokončování chatu OpenAI
• Referenční informace k rozhraní API odpovědí OpenAI

Další kroky

Hyperlight CodeAct