Bagikan melalui

Endpoint yang Kompatibel dengan OpenAI

Agent Framework mendukung protokol yang kompatibel dengan OpenAI untuk menghosting agen di belakang API standar dan menyambungkan ke titik akhir yang kompatibel dengan OpenAI.

Apa itu Protokol OpenAI?

Dua protokol OpenAI didukung:

  • CHAT Completions API — Format permintaan/respons stateless standar untuk interaksi obrolan
  • RESPONS API — Format tingkat lanjut yang mendukung percakapan, streaming, dan proses agen yang berjalan lama

API Respons kini menjadi pendekatan bawaan dan yang direkomendasikan sesuai dengan dokumentasi OpenAI. Ini menyediakan antarmuka yang lebih komprehensif dan kaya fitur untuk membangun aplikasi AI dengan manajemen percakapan bawaan, kemampuan streaming, dan dukungan untuk proses yang berjalan lama.

Gunakan API Respons saat:

  • Membangun aplikasi baru (default yang disarankan)
  • Anda memerlukan manajemen percakapan sisi server. Namun, itu bukan persyaratan: Anda masih dapat menggunakan API Respons dalam modus stateless.
  • Anda ingin riwayat percakapan persisten
  • Anda sedang membangun proses agen yang beroperasi dalam jangka waktu lama
  • Anda memerlukan kemampuan streaming tingkat lanjut dengan jenis peristiwa terperinci
  • Anda ingin melacak dan mengelola respons individual (misalnya, mengambil respons tertentu berdasarkan ID, memeriksa statusnya, atau membatalkan respons yang sedang berjalan)

Gunakan API Penyelesaian Obrolan saat:

  • Memigrasikan aplikasi yang ada yang mengandalkan format Penyelesaian Obrolan
  • Anda memerlukan interaksi permintaan/respons yang sederhana dan tanpa status
  • Pengelolaan status sepenuhnya ditangani oleh klien Anda
  • Anda mengintegrasikan dengan alat yang ada yang hanya mendukung Penyelesaian Obrolan
  • Anda memerlukan kompatibilitas maksimum dengan sistem warisan

Agen Hosting sebagai Titik Akhir OpenAI (.NET)

Microsoft.Agents.AI.Hosting.OpenAI Pustaka memungkinkan Anda mengekspos agen AI melalui titik akhir HTTP yang kompatibel dengan OpenAI, mendukung API Penyelesaian Obrolan dan Respons. Ini memungkinkan Anda untuk mengintegrasikan agen Anda dengan klien atau alat yang kompatibel dengan OpenAI.

Paket NuGet:

API Penyelesaian Percakapan

API Penyelesaian Obrolan menyediakan antarmuka tanpa status sederhana untuk berinteraksi dengan agen menggunakan format obrolan OpenAI standar.

Menyiapkan agen di ASP.NET Core dengan integrasi ChatCompletions

Berikut adalah contoh lengkap yang mengekspos agen melalui API Penyelesaian Percakapan:

Prasyarat

1. Buat proyek ASP.NET Core Web API

Buat proyek ASP.NET Core Web API baru atau gunakan yang sudah ada.

2. Pasang dependensi yang diperlukan

Instal paket berikut:

Jalankan perintah berikut di direktori proyek Anda untuk menginstal paket NuGet yang diperlukan:

# 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. Mengonfigurasi koneksi Azure OpenAI

Aplikasi ini memerlukan koneksi Azure OpenAI. Konfigurasikan titik akhir dan nama penyebaran menggunakan dotnet user-secrets atau variabel lingkungan. Anda juga dapat mengedit appsettings.json, tetapi hal ini tidak disarankan untuk aplikasi yang disebarkan dalam lingkungan produksi karena beberapa data dapat dianggap rahasia.

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. Tambahkan kode ke Program.cs

Ganti isi Program.cs dengan kode berikut:

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

Menguji Titik Akhir Penyelesaian Obrolan

Setelah aplikasi berjalan, Anda dapat menguji agen menggunakan permintaan OpenAI SDK atau HTTP:

Menggunakan Permintaan HTTP

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

Catatan: Ganti {{baseAddress}} dengan titik akhir server Anda.

Berikut adalah contoh respons:

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

Respons mencakup ID pesan, konten, dan statistik penggunaan.

Chat Completion juga mendukung streaming, di mana output dikembalikan dalam potongan segera saat konten tersedia. Kemampuan ini memungkinkan menampilkan output secara progresif. Anda dapat mengaktifkan streaming dengan menentukan "stream": true. Format output terdiri dari potongan Server-Sent Events (SSE) seperti yang didefinisikan dalam spesifikasi OpenAI Chat Completions.

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

Dan output yang kita dapatkan adalah sekumpulan potongan 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}}}

Respons streaming berisi informasi serupa, tetapi dikirimkan sebagai peristiwa yang dikirim oleh server.

Respons API

API Respons menyediakan fitur lanjutan termasuk manajemen percakapan, streaming, dan dukungan untuk proses agen yang berjalan lama.

Menyiapkan agen di ASP.NET Core dengan integrasi Responses API

Berikut adalah contoh lengkap menggunakan API Respons:

Prasyarat

Ikuti prasyarat yang sama dengan contoh Penyelesaian Obrolan (langkah 1-3).

4. Tambahkan kode ke 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();

Menguji API Respons

API Respons mirip dengan Penyelesaian Percakapan tetapi memiliki status, memungkinkan Anda untuk meneruskan parameter conversation. Seperti fitur Penyelesaian Obrolan, fitur ini mendukung parameter stream, yang mengontrol format output: baik berupa respons JSON tunggal ataupun aliran peristiwa. API Respons mendefinisikan jenis peristiwa streamingnya sendiri, termasuk response.created, , response.output_item.addedresponse.output_item.done, response.completed, dan lainnya.

Membuat Percakapan dan Respons

Anda dapat mengirim permintaan Respons secara langsung, atau Anda dapat terlebih dahulu membuat percakapan menggunakan API Percakapan lalu menautkan permintaan berikutnya ke percakapan tersebut.

Untuk memulai, buat percakapan baru:

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

Respons mencakup ID percakapan:

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

Selanjutnya, kirim permintaan dan tentukan parameter percakapan. (Untuk menerima respons sebagai peristiwa streaming, atur "stream": true dalam permintaan.)

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

Agen mengembalikan respons dan menyimpan item percakapan ke penyimpanan untuk diambil nanti:

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

Responsnya mencakup pengidentifikasi percakapan dan pesan, konten, dan statistik penggunaan.

Untuk mengambil item percakapan, kirim permintaan ini:

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

Ini mengembalikan respons JSON yang berisi pesan input dan output:

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

Mengekspos Beberapa Agen

Anda dapat mengekspos beberapa agen secara bersamaan menggunakan kedua protokol:

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

Agen akan tersedia di:

  • Penyelesaian Obrolan: /math/v1/chat/completions dan /science/v1/chat/completions
  • Respons: /math/v1/responses dan /science/v1/responses

Titik Akhir Kustom

Anda dapat menyesuaikan jalur titik akhir:

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

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

Menghubungkan ke Endpoint yang Kompatibel dengan OpenAI (Python)

Python OpenAIChatClient dan OpenAIResponsesClient keduanya mendukung parameter base_url, memungkinkan Anda untuk terhubung ke endpoint yang kompatibel dengan OpenAI — termasuk agen yang dihost sendiri, server inferensi lokal (Ollama, LM Studio, vLLM), atau API pihak ketiga yang kompatibel dengan OpenAI.

pip install agent-framework --pre

Antarmuka Penyelesaian Obrolan

Gunakan OpenAIChatClient dengan base_url untuk menunjuk ke server yang kompatibel dengan Penyelesaian Obrolan:

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

Respons Klien

Gunakan OpenAIResponsesClient dengan base_url untuk titik akhir yang mendukung API Respons:

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

Server Umum yang Kompatibel dengan OpenAI

Pendekatan ini base_url berfungsi dengan server apa pun yang mengekspos format Penyelesaian Obrolan OpenAI:

pelayan URL Dasar Catatan
Ollama http://localhost:11434/v1/ Inferensi lokal, tidak ada kunci API yang diperlukan
LM Studio http://localhost:1234/v1/ Inferensi lokal dengan GUI
vLLM http://localhost:8000/v1/ Pelayanan dengan throughput tinggi
Azure AI Foundry Titik akhir penyebaran Anda Menggunakan kredensial Azure
Agen Kerangka Kerja yang Dihosting Titik akhir agen Anda Agen .NET diekspos melalui MapOpenAIChatCompletions

Nota

Anda juga dapat mengatur variabel lingkungan OPENAI_BASE_URL daripada meneruskan base_url secara langsung. Klien akan menggunakannya secara otomatis.

Menggunakan Klien Azure OpenAI

Varian Azure OpenAI (AzureOpenAIChatClient, AzureOpenAIResponsesClient) terhubung ke titik akhir Azure OpenAI menggunakan kredensial Azure — tidak base_url diperlukan:

from agent_framework.azure import AzureOpenAIResponsesClient

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

Konfigurasikan dengan variabel lingkungan:

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

Lihat Juga

Langkah selanjutnya

Cakupan

  • Last updated on