OpenAI Aracıları

Microsoft Agent Framework, hem C# hem de Python iki OpenAI istemci türünü destekler: Yanıtlar ve Sohbet Tamamlama. Yanıtlar ö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 ihtiyaç duyduğunuzda veya korumak istediğiniz mevcut bir Sohbet Tamamlama entegrasyonunuz varsa Sohbet Tamamlama’yı kullanın.

İstemci Türü	API	En Uygun
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.

Başlangıç Yapmak

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.GetResponseClient("gpt-4o-mini");

AIAgent agent = responsesClient.AsAIAgent(
    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.

Araçlar

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.

Tip

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.

Konfigürasyon

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

Yanıt

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

Sohbet Tamamlama

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

Aynı istemcilerle Azure OpenAI

Azure OpenAI artık doğrudan OpenAI ile aynı Python OpenAI istemcilerini kullanıyor. Tercih edilen ve en net Azure deseni, credential veya azure_endpoint gibi açık Azure yönlendirme girişlerini geçmek, ardından yönlendirme seçildikten sonra Azure için api_version ayarlamaktır. OPENAI_API_KEY ayarlanırsa, bu Azure yönlendirme verilerini geçirmediğiniz sürece genel istemciler OpenAI'de kalır. Sadece AZURE_OPENAI_* ayarlarınız varsa, Azure ortamı geri dönüş çalışmaya devam eder. OpenAIChatClient tercihler AZURE_OPENAI_CHAT_MODEL, OpenAIChatCompletionClient tercihler AZURE_OPENAI_CHAT_COMPLETION_MODEL ve her ikisi de AZURE_OPENAI_MODEL geri döner.

AZURE_OPENAI_ENDPOINT="https://<resource>.openai.azure.com"
AZURE_OPENAI_CHAT_MODEL="gpt-4o-mini"
# Optional shared fallback:
# AZURE_OPENAI_MODEL="gpt-4o-mini"
AZURE_OPENAI_API_VERSION="your-api-version"

import asyncio
import os
from agent_framework.openai import OpenAIChatClient
from azure.identity import AzureCliCredential

async def main():
    agent = 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(),
    ).as_agent(
        name="AzureOpenAIResponsesAgent",
        instructions="You are a helpful assistant.",
    )

    result = await agent.run("Hello!")
    print(result)

asyncio.run(main())

/openai/v1 ile biten tam bir Azure OpenAI URL'niz zaten varsa, URL'yi base_url yerine azure_endpoint olarak kullanın. Kullandığınız Azure OpenAI API yüzeyiyle uyumlu tutun api_version . Ortamınızda da ayarlandıysa OPENAI_API_KEY , bu açık Azure girişleri istemciyi Azure'da tutar.

Uyarı

Yanıtlar API'sinde kullanın OpenAIChatClient . Azure anahtar kimliği doğrulama için yine de api_key kullanabilirsiniz, ancak credential= artık tercih edilen Azure kimlik doğrulama yöntemidir.

Aynı istemci ailesi ile Azure eklemeleri

OpenAIEmbeddingClient , sohbet istemcileri ile aynı yönlendirme kurallarını izler. Azure gömme işlemleri için gömme dağıtımını model olarak iletin ve belirgin Azure girişlerini tercih edin.

import os
from agent_framework.openai import OpenAIEmbeddingClient
from azure.identity import AzureCliCredential

client = OpenAIEmbeddingClient(
    model=os.environ["AZURE_OPENAI_EMBEDDING_MODEL"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
    credential=AzureCliCredential(),
)

OpenAI Aracıları Oluşturma

Yanıt

OpenAIChatClient , barındırılan araç desteğine sahip önerilen birincil istemci olan Yanıtlar API'sini kullanır.

import asyncio
from agent_framework.openai import OpenAIChatClient

async def main():
    agent = OpenAIChatClient().as_agent(
        name="FullFeaturedAgent",
        instructions="You are a helpful assistant with access to many tools.",
    )
    result = await agent.run("Write and run a Python script that calculates fibonacci numbers.")
    print(result)

asyncio.run(main())

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

Yanıt İstemcisi ile Barındırılan Araçlar

Yanıtlar istemcisi barındırılan get_*_tool() her araç türü için yöntemler sağlar:

async def hosted_tools_example():
    client = OpenAIChatClient()

    # Each tool is created via a client method
    code_interpreter = client.get_code_interpreter_tool()
    web_search = client.get_web_search_tool()
    file_search = client.get_file_search_tool(vector_store_ids=["vs_abc123"])
    mcp_tool = client.get_mcp_tool(
        name="GitHub",
        url="https://api.githubcopilot.com/mcp/",
        approval_mode="never_require",
    )

    agent = client.as_agent(
        name="PowerAgent",
        instructions="You have access to code execution, web search, files, and GitHub.",
        tools=[code_interpreter, web_search, file_search, mcp_tool],
    )
    result = await agent.run("Search the web for Python best practices, then write a summary.")
    print(result)

Sohbet Tamamlama

OpenAIChatCompletionClient Sohbet Tamamlamaları API'sini kullanır; geniş bir model uyumluluğuna ihtiyacınız olduğunda veya mevcut bir Sohbet Tamamlamaları tümleştirmesine sahip olduğunuzda bu api'yi kullanın.

import asyncio
from agent_framework.openai import OpenAIChatCompletionClient

async def main():
    agent = OpenAIChatCompletionClient().as_agent(
        name="HelpfulAssistant",
        instructions="You are a helpful assistant.",
    )
    result = await agent.run("Hello, how can you help me?")
    print(result)

asyncio.run(main())

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

Sohbet Tamamlama ile Web Araması

async def web_search_example():
    client = OpenAIChatCompletionClient()
    web_search = client.get_web_search_tool()

    agent = client.as_agent(
        name="SearchBot",
        instructions="You can search the web for current information.",
        tools=web_search,
    )
    result = await agent.run("What are the latest developments in AI?")
    print(result)

Önemli

Python artık bir Yardımcılar uyumluluk istemcisi/sağlayıcısı içermez. Geçerli Python kodunda Yanıtlar API senaryoları için OpenAIChatClient veya Sohbet Tamamlamaları için OpenAIChatCompletionClient kullanın. Microsoft Foundry'de hizmet tarafından yönetilen bir aracıya ihtiyacınız varsa Microsoft Foundry sağlayıcısı sayfasına bakın.

Ortak Özellikler

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

İşlev Araçları

from agent_framework import 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 = OpenAIChatClient().as_agent(
        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

async def thread_example():
    agent = OpenAIChatClient().as_agent(
        instructions="You are a helpful assistant.",
    )
    session = await 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"

Yayın

async def streaming_example():
    agent = OpenAIChatClient().as_agent(
        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()

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.

Araçlar

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.

Sonraki Adımlar

Microsoft Foundry