OpenAI ile Uyumluluklu Uç Noktalar

Agent Framework, standart API'lerin arkasındaki aracıları barındırmak ve OpenAI uyumlu herhangi bir uç noktaya bağlanmak için OpenAI uyumlu protokolleri destekler.

OpenAI Protokolleri Nedir?

İki OpenAI protokolü desteklenir:

• Sohbet Tamamlama API'si — Sohbet etkileşimleri için standart durum bilgisi olmayan istek/yanıt biçimi
• Yanıtlar API'si, konuşmaları, yayın akışını ve uzun süreli çalışan aracı işlemlerini destekleyen gelişmiş biçim

Yanıtlar API'si artık OpenAI belgelerine göre varsayılan ve önerilen yaklaşımdır . Yerleşik konuşma yönetimi, akış özellikleri ve uzun süre çalışan işlemler için destek ile yapay zeka uygulamaları oluşturmaya yönelik daha kapsamlı ve özellik açısından zengin bir arabirim sağlar.

Yanıtlar API'sini şu durumlarda kullanın:

• Yeni uygulamalar oluşturma (önerilen varsayılan)
• Sunucu tarafı konuşma yönetimine ihtiyacınız vardır. Ancak bu bir gereksinim değildir: Yanıtlar API'sini durum bilgisi olmayan modda kullanmaya devam edebilirsiniz.
• Kalıcı konuşma geçmişi istiyorsunuz
• Uzun süre çalışan aracı işlemleri oluşturuyorsunuz
• Ayrıntılı olay türleriyle gelişmiş akış özelliklerine ihtiyacınız var
• Tek tek yanıtları izlemek ve yönetmek istiyorsunuz (örneğin, kimliğe göre belirli bir yanıtı almak, durumunu denetlemek veya çalışan yanıtı iptal etmek)

Aşağıdaki durumlarda Sohbet Tamamlamaları API'sini kullanın:

• Sohbet Tamamlamaları formatını kullanan mevcut uygulamaları taşımak
• Basit, durum bilgisi olmayan istek/yanıt etkileşimlerine ihtiyacınız var
• Durum yönetimi tamamen istemciniz tarafından yönetilir
• Yalnızca Sohbet Tamamlamalarını destekleyen mevcut araçlarla tümleştirme yapıyorsunuz
• Eski sistemlerle maksimum uyumluluk gerekir

Aracıları OpenAI Uç Noktaları Olarak Barındırma (.NET)

Kitaplık, Microsoft.Agents.AI.Hosting.OpenAI Hem Sohbet Tamamlamalarını hem de Yanıtlar API'lerini destekleyen OpenAI uyumlu HTTP uç noktaları aracılığıyla yapay zeka aracılarını kullanıma sunmanızı sağlar. Bu, aracılarınızı OpenAI uyumlu herhangi bir istemci veya araçla tümleştirmenize olanak tanır.

NuGet Paketi:

• Microsoft.Agents.AI.Hosting.OpenAI

Sohbet Tamamlamaları API'si

Sohbet Tamamlamaları API'si, standart OpenAI sohbet biçimini kullanarak aracılarla etkileşime geçmek için basit, durum bilgisi olmayan bir arabirim sağlar.

ChatCompletions tümleştirmesi ile ASP.NET Core'da aracı ayarlama

Sohbet Tamamlamaları API'sini kullanarak bir aracıyı ortaya çıkarmanın tam bir örneği aşağıda verilmiştir:

Önkoşullar

1. ASP.NET Core Web API projesi oluşturma

Yeni bir ASP.NET Core Web API projesi oluşturun veya var olan bir projeyi kullanın.

2. Gerekli bağımlılıkları yükleme

Aşağıdaki paketleri yükleyin:

.NET CLI

Gerekli NuGet paketlerini yüklemek için proje dizininizde aşağıdaki komutları çalıştırın:

# 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

Paket Referansı

Aşağıdaki <PackageReference> öğeleri .csproj dosyanızın içindeki <ItemGroup>'e ekleyin:

<ItemGroup>
  <!-- Hosting.OpenAI for OpenAI ChatCompletions/Responses protocol(s) integration -->
  <PackageReference Include="Microsoft.Agents.AI.Hosting.OpenAI" Version="1.0.0-alpha.251110.2" />

  <!-- Libraries to connect to Azure OpenAI -->
  <PackageReference Include="Azure.AI.OpenAI" Version="2.5.0-beta.1" />
  <PackageReference Include="Azure.Identity" Version="1.17.0" />
  <PackageReference Include="Microsoft.Extensions.AI" Version="9.10.2" />
  <PackageReference Include="Microsoft.Extensions.AI.OpenAI" Version="9.10.2-preview.1.25552.1" />

  <!-- Swagger to test app -->
  <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.0" />
  <PackageReference Include="Swashbuckle.AspNetCore" Version="6.8.1" />
</ItemGroup>

3. Azure OpenAI bağlantısını yapılandırma

Uygulama bir Azure OpenAI bağlantısı gerektirir. veya ortam değişkenlerini kullanarak dotnet user-secrets uç nokta ve dağıtım adını yapılandırın. Ayrıca, yalnızca öğesini düzenleyebilirsiniz appsettings.json, ancak verilerin bir kısmı gizli olarak değerlendirilebileceği için üretimde dağıtılan uygulamalar için bu önerilmez.

Kullanıcı Sırları

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"

ENV Windows

$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. Kodu Program.cs'ye ekleyin

Program.cs içeriğini aşağıdaki kodla değiştirin:

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

Sohbet Tamamlama Uç Noktasını Test Etme

Uygulama çalıştırıldıktan sonra OpenAI SDK'sını veya HTTP isteklerini kullanarak aracıyı test edebilirsiniz:

HTTP İsteğiNi Kullanma

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

Not: {{baseAddress}} ile sunucu uç noktanızı değiştirin.

Örnek bir yanıt aşağıda verilmiştir:

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

Yanıt ileti kimliğini, içeriği ve kullanım istatistiklerini içerir.

Sohbet Tamamlamaları, içeriğin kullanılabilir olduğu anda çıktının parçalara ayrılarak döndürüldüğü yayın akışını da destekler. Bu özellik, çıkışın aşamalı olarak görüntülenmesini sağlar. Belirterek "stream": true akışı etkinleştirebilirsiniz. Çıkış biçimi, OpenAI Sohbet Tamamlamaları belirtiminde tanımlanan Sunucu Tarafından Gönderilen Olaylar (SSE) parçalarından oluşur.

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

Aldığımız çıkış ise bir dizi ChatCompletions öbekleridir:

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

Akış yanıtı benzer bilgiler içerir, ancak Server-Sent Events olarak sunulur.

Yanıtlar API'si

Yanıtlar API'si konuşma yönetimi, akış ve uzun süre çalışan aracı işlemleri için destek gibi gelişmiş özellikler sağlar.

ASP.NET Core'da Yanıtlar API entegrasyonu ile aracı yapılandırma

Yanıtlar API'sini kullanan tam bir örnek aşağıda verilmiştir:

Önkoşullar

Sohbet Tamamlamaları örneğiyle aynı önkoşulları izleyin (1-3 arası adımlar).

4. Kodu Program.cs'ye ekleyin

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

Yanıtlar API'sini test etme

Yanıtlar API'si Sohbet Tamamlamaları'na benzer ancak durum bilgisi vardır ve bir conversation parametre geçirmenize olanak sağlar. Sohbet Tamamlamaları gibi, stream parametresini destekler; bu, çıkış formatını kontrol eder: tek bir JSON yanıtı veya olay akışı. Yanıtlar API'si, , response.created, response.output_item.added, response.output_item.doneve diğerleri gibi response.completedkendi akış olay türlerini tanımlar.

Konuşma ve Yanıt Oluşturma

Doğrudan yanıt isteği gönderebilir veya önce Konuşmalar API'sini kullanarak bir konuşma oluşturabilir ve ardından sonraki istekleri bu konuşmaya bağlayabilirsiniz.

Başlamak için yeni bir konuşma oluşturun:

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

Yanıt konuşma kimliğini içerir:

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

Ardından bir istek gönderin ve konuşma parametresini belirtin. (Yanıtı akış olayları olarak almak için "stream": true'yi istekte ayarlayın.)

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

Ajan yanıtı iletir ve konuşma öğelerini daha sonra alınmak üzere depolamaya kaydeder.

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

Yanıt konuşma ve ileti tanımlayıcılarını, içeriği ve kullanım istatistiklerini içerir.

Konuşma öğelerini almak için şu isteği gönderin:

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

Bu, hem giriş hem de çıkış iletilerini içeren bir JSON yanıtı döndürür:

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

Birden Çok Aracıyı Açığa Çıkarma

Her iki protokolü de kullanarak birden çok aracıyı aynı anda kullanıma salayabilirsiniz:

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

Temsilciler şu konumda mevcut olacak:

• Sohbet Tamamlamaları: /math/v1/chat/completions ve /science/v1/chat/completions
• Yanıtlar: /math/v1/responses ve /science/v1/responses

Özel Uç Noktalar

Uç nokta yollarını özelleştirebilirsiniz:

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

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

OpenAI-Compatible Uç Noktalarına Bağlanma (Python)

Python OpenAIChatClient ve OpenAIResponsesClient her ikisi de bir parametreyi destekleyerek şirket içinde barındırılan aracılar, yerel çıkarım sunucuları (Ollama, LM Studio, vLLM) veya üçüncü taraf OpenAI uyumlu API'ler dahil olmak üzere OpenAI uyumlu base_url uç noktaya bağlanmanızı sağlar.

pip install agent-framework --pre

Sohbet Tamamlama İstemcisi

Sohbet Tamamlamaları ile uyumlu herhangi bir sunucuya işaret etmek için OpenAIChatClient ve base_url kullanın.

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

Yanıt İstemcisi

Yanıtlar API'sini destekleyen uç noktalar için OpenAIResponsesClient ile base_url kullanın.

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

Ortak OpenAI-Compatible Sunucuları

Bu yaklaşım, base_url OpenAI Sohbet Tamamlamaları biçimini ortaya çıkaran tüm sunucularla çalışır:

Server	Temel URL	Notes
Ollama	http://localhost:11434/v1/	Yerel çıkarım, API anahtarı gerekmez
LM Studio	http://localhost:1234/v1/	GUI ile yerel çıkarım
vLLM	http://localhost:8000/v1/	Yüksek aktarım hızı sunan
Azure AI Foundry	Dağıtım uç noktanız	Azure kimlik bilgilerini kullanır
Barındırılan Aracı Yapısı ajanları	Aracı uç noktanız	.NET ajanları MapOpenAIChatCompletions aracılığıyla açığa çıkartıldı

Uyarı

OPENAI_BASE_URL ortam değişkenini doğrudan geçirmek yerine base_url ayarlayabilirsiniz. İstemci bunu otomatik olarak kullanır.

Azure OpenAI İstemcilerini Kullanma

Azure OpenAI varyantları (AzureOpenAIChatClient, AzureOpenAIResponsesClient) Azure kimlik bilgilerini kullanarak Azure OpenAI uç noktalarına bağlanır; gerekli değildir base_url :

from agent_framework.azure import AzureOpenAIResponsesClient

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

Ortam değişkenleriyle yapılandırma:

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

Ayrıca Bkz.

• Tümleştirmelere Genel Bakış
• A2A Tümleştirmesi
• OpenAI Sohbet Tamamlamaları API Başvurusu
• OpenAI Yanıtları API Referansı

Sonraki Adımlar

Kapsam