OpenAI

Microsoft Agent Framework, C#, Python ve Go'da OpenAI aracılarını destekler. C# ve Python iki OpenAI istemci türünü (Yanıtlar ve Sohbet Tamamlama) desteklerken Go şu anda Sohbet Tamamlamaları sağlayıcısını kullanır. Yanıtlar, kullanılabilir olduğunda önerilen birincil istemcidir: Daha yeni OpenAI Yanıtları API'sini hedefler ve barındırılan araçların tamamını destekler (kod yorumlayıcı, dosya arama, web araması, barındırılan MCP, görüntü oluşturma). Geniş model uyumluluğuna, Go desteğine ihtiyaç duyduğunuzda veya korumak istediğiniz mevcut bir Chat Completions entegrasyonunuz varsa Chat Completion kullanın.

İstemci Türü API İdeal Kullanım Alanı
Yanıtlar (önerilen) Yanıtlar API'si Barındırılan araçlarla (kod yorumlayıcı, dosya arama, web araması, barındırılan MCP) tam özellikli aracılar
Sohbet Tamamlama Sohbet Tamamlamaları API'si Basit aracılar, geniş model desteği

Uyarı

OpenAI Yardımcıları API'si OpenAI tarafından kullanım dışı bırakılmıştır. Yeni kod Yanıtlar istemcisini kullanmalıdır. Mevcut Yardımcılar tabanlı bir uygulamadan geçiş gerçekleştiriyorsanız Semantik Çekirdek geçiş kılavuzuna bakın.

Getting Started

Projenize gerekli NuGet paketlerini ekleyin.

dotnet add package Microsoft.Agents.AI.OpenAI --prerelease

Yanıt İstemcisi

Yanıtlar istemcisi önerilen birincil istemcidir ve kod yorumlayıcı, dosya arama, web araması ve barındırılan MCP gibi en zengin araç desteğini sağlar.

using Microsoft.Agents.AI;
using OpenAI;

OpenAIClient client = new OpenAIClient("<your_api_key>");
var responsesClient = client.GetResponsesClient();

AIAgent agent = responsesClient.AsAIAgent(
    model: "gpt-4o-mini",
    instructions: "You are a helpful coding assistant.",
    name: "CodeHelper");

Console.WriteLine(await agent.RunAsync("Write a Python function to sort a list."));

Desteklenen araçlar: İşlev araçları, araç onayı, kod yorumlayıcı, dosya arama, web araması, barındırılan MCP, yerel MCP araçları.

Sohbet Tamamlama İstemcisi

Sohbet Tamamlama istemcisi, Sohbet Tamamlamaları API'sini kullanarak aracılar oluşturmak için basit bir yol sağlar. Geniş model uyumluluğuna ihtiyaç duyduğunuzda veya mevcut bir Chat Completions entegrasyonunuz olduğunda bunu kullanın.

using Microsoft.Agents.AI;
using OpenAI;

OpenAIClient client = new OpenAIClient("<your_api_key>");
var chatClient = client.GetChatClient("gpt-4o-mini");

AIAgent agent = chatClient.AsAIAgent(
    instructions: "You are good at telling jokes.",
    name: "Joker");

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

Desteklenen araçlar: İşlev araçları, web araması, yerel MCP araçları.

Asistanlar İstemcisi

Uyarı

OpenAI Yardımcıları API'si OpenAI tarafından kullanım dışı bırakılmıştır. Agent Framework artık bir Asistanlar istemcisini belgelemiyor — yeni kodlar için yukarıdaki Yanıtlar istemcisini kullanın. Mevcut bir uygulamayı geçirmek için bkz. Semantik Çekirdek geçiş kılavuzu.

Ajanı Kullanma

Her iki istemci türü de aynı aracı işlemlerini (akış, iş parçacıkları, ara yazılım) destekleyen bir standart AIAgent oluşturur.

Daha fazla bilgi için Başlangıç öğreticilerine bakın.

Tools

OpenAI .NET istemcileri, hedefledikleri API'ye bağlı olarak farklı araç yüzeylerini kullanıma sunar. Aynı matris, Azure OpenAI sağlayıcı sayfasındaki eşleşen Azure OpenAI istemcileri için de geçerlidir.

Araç Yanıtlar Sohbet Tamamlama
İşlev Araçları ✅ ✅
Araç Onayı ✅ ✅
Kod Yorumlayıcısı ✅ ❌
Dosya Arama ✅ ❌
Web Araması ✅ ✅
Barındırılan MCP Araçları ✅ ❌
Yerel MCP Araçları ✅ ✅

Uyarı

Araç Onayı , çerçevenin işlev çağrılı sohbet istemcisi tarafından sağlanır, bu nedenle temel alınan API'den bağımsız olarak herhangi bir işlev aracı çağrısıyla çalışır.

Uyarı

OpenAI Yardımcıları API'si OpenAI tarafından kullanım dışı bırakılmıştır ve Python artık Yardımcılar uyumluluk istemcisi/sağlayıcısını iletmez. Yanıtlar için OpenAIChatClient veya Sohbet Tamamlamaları için OpenAIChatCompletionClient kullanın. Önceki bir Agent Framework Python sürümünden geçiş gerçekleştiriyorsanız bkz. Python önemli değişiklikler kılavuzu. Semantik Çekirdek’dan geçiş yapıyorsanız Semantik Çekirdek geçiş kılavuzuna bakın.

İpucu

Python'da Azure OpenAI artık burada gösterilen istemcilerin aynısını agent_framework.openai kullanıyor. Azure yönlendirmesi istediğinizde credential veya azure_endpoint gibi açık Azure yönlendirme girişlerini geçirin, ardından kullanmak istediğiniz Azure API yüzeyini ayarlamak için api_version ayarlayın. Eğer OPENAI_API_KEY yapılandırıldıysa, AZURE_OPENAI_* değişkenlerinin olmasına rağmen genel istemciler OpenAI'de kalır. Zaten tam bir .../openai/v1 URL'niz varsa, base_url yerine azure_endpoint kullanın. Microsoft Foundry proje uç noktaları ve Foundry Aracısı Hizmeti için Microsoft Foundry sağlayıcısı sayfasına bakın. Yerel çalışma zamanları için bkz. Foundry Local.

Kurulum

pip install agent-framework-openai

agent-framework-openai hem doğrudan OpenAI hem de Azure OpenAI kullanımı için isteğe bağlı Python sağlayıcı paketidir.

Configuration

Python OpenAI sohbet istemcileri şu ortam değişkeni desenlerini kullanır:

OPENAI_API_KEY="your-openai-api-key"
OPENAI_CHAT_MODEL="gpt-4o-mini"
# Optional shared fallback:
# OPENAI_MODEL="gpt-4o-mini"

Ortak Özellikler

Bu istemci türleri şu standart aracı özelliklerini destekler:

İşlev Araçları

from agent_framework import Agent, tool

@tool
def get_weather(location: str) -> str:
    """Get the weather for a given location."""
    return f"The weather in {location} is sunny, 25°C."

async def example():
    agent = Agent(
        client=OpenAIChatClient(),
        instructions="You are a weather assistant.",
        tools=get_weather,
    )
    result = await agent.run("What's the weather in Tokyo?")
    print(result)

Çok Aşamalı Konuşmalar

from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient

async def thread_example():
    agent = Agent(
        client=OpenAIChatClient(),
        instructions="You are a helpful assistant.",
    )
    session = agent.create_session()

    result1 = await agent.run("My name is Alice", session=session)
    print(result1)
    result2 = await agent.run("What's my name?", session=session)
    print(result2)  # Remembers "Alice"

Streaming

from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient

async def streaming_example():
    agent = Agent(
        client=OpenAIChatClient(),
        instructions="You are a creative storyteller.",
    )
    print("Agent: ", end="", flush=True)
    async for chunk in agent.run("Tell me a short story about AI.", stream=True):
        if chunk.text:
            print(chunk.text, end="", flush=True)
    print()

Komut önbelleğe alma

Açık istem önbelleği kesme noktalarını destekleyen modellerde, OpenAIChatClient yeniden kullanılabilir ön eki denetlemek için , prompt_cache_optionsve Content.additional_properties["prompt_cache_breakpoint"] kullanabilirprompt_cache_key. Önbellek yazma işlemleri desteklenen modellerde ayrı olarak faturalandırılabilir.

OpenAI önbellek kullanımı içinde response.usage_detailsnormalleştirilir:

  • cache_creation_input_token_count - Sağlayıcı tarafından yönetilen önbelleğe yazılan giriş belirteçleri.
  • cache_read_input_token_count - Önbellekten sunulan giriş belirteçleri.

OpenTelemetry etkinleştirildiğinde, bu değerler ve gen_ai.usage.cache_read.input_tokensile gen_ai.usage.cache_creation.input_tokens eşler.

import asyncio
import time

from agent_framework import Content, Message
from agent_framework.openai import OpenAIChatClient, OpenAIChatOptions
from dotenv import load_dotenv

load_dotenv()
# A stable block of context that is reused across requests, for example a product
# catalog, a policy document, or long system guidance. Repeated here to clear the
# 1024-token minimum a cache breakpoint requires.
STABLE_CONTEXT = (
    "You are a support assistant for the Contoso appliance store. "
    "Always answer briefly, quote the relevant catalog section, and never invent "
    "model numbers. If a question is out of scope, say so and point the customer "
    "to support@contoso.example. "
) * 40


def build_messages(question: str) -> list[Message]:
    """Build a request with a cache breakpoint at the end of the stable prefix."""
    return [
        Message(
            role="user",
            contents=[
                Content.from_text(
                    STABLE_CONTEXT,
                    additional_properties={"prompt_cache_breakpoint": {"mode": "explicit"}},
                )
            ],
        ),
        Message(role="user", contents=[Content.from_text(question)]),
    ]


async def main() -> None:
    print("\033[92m=== OpenAI Chat Client Prompt Caching Example ===\033[0m\n")

    client = OpenAIChatClient[OpenAIChatOptions](model="gpt-5.6-luna")
    options: OpenAIChatOptions = {
        "prompt_cache_options": {"mode": "explicit"},
        "prompt_cache_key": f"contoso_appliance_store-{time.time()}",
    }

    questions = ["Do you sell refrigerators?", "What is the return policy contact?"]
    for turn, question in enumerate(questions, start=1):
        response = await client.get_response(build_messages(question), options=options)
        usage = response.usage_details or {}
        cached = usage.get("cache_read_input_token_count", 0)
        cached_write = usage.get("cache_creation_input_token_count", 0)
        print(f"Turn {turn}: {question}")
        print(f"  Answer: {response.text}")
        print(f"  Cached input tokens (read): {cached}\n")
        print(f"  Cached input tokens (created): {cached_write}\n")
        if turn < len(questions):
            # A freshly written cache entry becomes readable shortly after the request
            # completes; the brief pause keeps the next turn from racing this one.
            await asyncio.sleep(2)

    print("The first turn writes the prefix to the cache; later turns read it back.")

Ajanı Kullanma

Tüm istemci türleri aynı işlemleri destekleyen bir standart Agent oluşturur.

Daha fazla bilgi için Başlangıç öğreticilerine bakın.

Tools

Python OpenAI istemcileri, temel alınan API'ye bağlı olarak farklı araç yüzeylerini kullanıma sunar. OpenAIChatClient (Yanıtlar), client.get_*_tool(...) üzerinden barındırılan araç fabrikaları sunar — get_code_interpreter_tool, get_file_search_tool, get_web_search_tool, get_image_generation_tool, get_shell_tool ve get_mcp_tool. OpenAIChatCompletionClient yalnızca get_web_search_tool öğesini sunar. Her ikisi de işlev araçları ve yerel MCP sunucularıyla çalışır.

Aynı matris, bu istemcileri Azure OpenAI'ye işaret ettiğinizde de geçerlidir; bkz. Azure OpenAI.

Araç OpenAIChatClient (Yanıtlar) OpenAIChatCompletionClient (Sohbet Tamamlama)
İşlev Araçları ✅ ✅
Araç Onayı ✅ ✅
Kod Yorumlayıcısı ✅ ❌
Dosya Arama ✅ ❌
Web Araması ✅ ✅
Görüntü Üretimi ✅ (get_image_generation_tool) ❌
Barındırılan Kabuk ✅ (get_shell_tool) ❌
Barındırılan MCP Araçları ✅ ❌
Yerel MCP Araçları ✅ ✅

Uyarı

Araç Onayı , çerçevenin işlev çağrılı sohbet istemcisi tarafından işlenir, bu nedenle temel alınan API'den bağımsız olarak herhangi bir işlev aracı çağrısıyla çalışır.

OpenAI Konuşma Tamamlamaları

Paket, openaiprovider OpenAI Sohbet Tamamlamaları API'sini kullanarak aracılar oluşturur.

Kurulum

go get github.com/microsoft/agent-framework-go

Doğrudan OpenAI

import (
    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/provider/openaiprovider"

    "github.com/openai/openai-go/v3"
)

a := openaiprovider.NewChatCompletionsAgent(
    openai.NewClient(), // uses OPENAI_API_KEY env var
    openaiprovider.AgentConfig{
        Model: "gpt-4o-mini",
        Instructions: "You are a helpful assistant.",
        Config: agent.Config{
            Name:         "MyAgent",
        },
    },
)

resp, err := a.RunText(ctx, "Tell me a joke.").Collect()

Azure OpenAI

Azure kimlik bilgileriyle aynı openaiprovider paketi kullanın:

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    openai "github.com/openai/openai-go/v3"
    "github.com/openai/openai-go/v3/azure"
)

token, _ := azidentity.NewDefaultAzureCredential(nil)

a := openaiprovider.NewChatCompletionsAgent(
    openai.NewClient(
        azure.WithEndpoint(endpoint, apiVersion),
        azure.WithTokenCredential(token),
    ),
    openaiprovider.AgentConfig{
        Model: deployment,
        Instructions: "You are a helpful assistant.",
        Config: agent.Config{
        },
    },
)

Warning

azidentity.NewDefaultAzureCredential geliştirme için uygundur ancak üretimde dikkatli bir şekilde dikkate alınması gerekir. Üretimde, gecikme sorunlarından, istenmeyen kimlik bilgisi denemelerinden ve geri dönüş mekanizmalarından kaynaklanabilecek olası güvenlik risklerinden kaçınmak için azidentity.NewManagedIdentityCredential gibi belirli bir kimlik bilgisi kullanmayı göz önünde bulundurun.

Özel seçenekler

openaiprovider.ChatCompletionNewParams kullanarak sağlayıcıya özgü seçenekleri iletin:

resp, err := a.RunText(ctx, "Hello!",
    openaiprovider.ChatCompletionNewParams(openai.ChatCompletionNewParams{
        Temperature: openai.Float(0.7),
    }),
).Collect()

Desteklenen araçlar: İşlev araçları, web araması, yerel MCP araçları.

İpucu

Tam örnekler için OpenAI sağlayıcı örneğine ve Azure OpenAI örneğine bakın.

Sonraki Adımlar

Microsoft Dökümhanesi

  • Last updated on