Agen OpenAI

Microsoft Agent Framework mendukung dua jenis klien OpenAI — Respons dan Penyelesaian Obrolan — baik di C# maupun Python. Respons adalah klien utama yang direkomendasikan: menargetkan OPENAI Responses API yang lebih baru dan mendukung serangkaian lengkap alat yang dihosting (penerjemah kode, pencarian file, pencarian web, MCP yang dihosting, pembuatan gambar). Gunakan Chat Completion saat Anda memerlukan kompatibilitas model yang luas atau memiliki integrasi Chat Completion yang ingin dipertahankan.

Tipe Klien	API	Terbaik untuk
Respons (disarankan )	API Respons	Agen berfitur lengkap dengan alat yang dihosting (penerjemah kode, pencarian file, pencarian web, MCP yang dihosting)
Penyelesaian Percakapan	API Penyelesaian Obrolan	Agen sederhana, dukungan model luas

Nota

OpenAI Assistants API tidak digunakan lagi oleh OpenAI. Kode baru harus menggunakan klien Respons. Jika Anda bermigrasi dari aplikasi berbasis Asisten yang ada, lihat panduan migrasi Kernel Semantik.

Memulai Langkah Awal

Tambahkan paket NuGet yang diperlukan ke proyek Anda.

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

Respons Klien

Klien Respons adalah klien utama yang direkomendasikan dan menyediakan dukungan alat terkaya termasuk penerjemah kode, pencarian file, pencarian web, dan MCP yang dihosting.

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

Alat yang didukung: Alat fungsi, persetujuan alat, penerjemah kode, pencarian file, pencarian web, MCP yang dihosting, alat MCP lokal.

Klien Penyelesaian Percakapan

Klien Penyelesaian Obrolan menyediakan cara mudah untuk membuat agen menggunakan API Penyelesaian Obrolan. Gunakan ini saat Anda memerlukan kompatibilitas model yang luas atau sudah memiliki integrasi Chat Completions yang sudah ada.

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

Alat yang didukung: Alat fungsi, pencarian web, alat MCP lokal.

Klien Asisten

Nota

OpenAI Assistants API tidak digunakan lagi oleh OpenAI. Agent Framework tidak lagi mendokumentasikan klien Assistants — gunakan klien Responses di atas untuk kode baru. Untuk memigrasikan aplikasi yang sudah ada, lihat panduan migrasi Kernel Semantik.

Menggunakan Agen

Kedua jenis klien menghasilkan AIAgent standar yang mendukung operasi agen yang sama (streaming, thread, middleware).

Untuk informasi selengkapnya, lihat tutorial Memulai.

Alat

Klien OpenAI .NET mengekspos permukaan alat yang berbeda tergantung pada API mana yang mereka targetkan. Matriks yang sama berlaku untuk klien OpenAI Azure yang cocok di halaman penyedia Azure OpenAI.

Tool	Responses	Penyelesaian Percakapan
Peralatan Fungsional	✅	✅
Persetujuan Alat	✅	✅
Penerjemah Kode	✅	❌
Pencarian File	✅	❌
Pencarian Web	✅	✅
Alat MCP yang Dihosting	✅	❌
Alat MCP Lokal	✅	✅

Nota

Persetujuan Tool disediakan oleh klien chat pemanggil fungsi dari framework, sehingga dapat bekerja dengan pemanggilan function tool apa pun, terlepas dari API yang digunakan di bawahnya.

Nota

OpenAI Assistants API tidak digunakan lagi oleh OpenAI, dan Python tidak lagi mengirimkan klien/penyedia kompatibilitas Asisten. Gunakan OpenAIChatClient untuk Respons atau OpenAIChatCompletionClient untuk Penyelesaian Obrolan. Jika Anda beralih dari rilis Python Agent Framework versi sebelumnya, lihat panduan perubahan signifikan Python. Jika Anda bermigrasi dari Kernel Semantik, lihat panduan migrasi Kernel Semantik.

Petunjuk / Saran

Dalam Python, Azure OpenAI sekarang menggunakan klien yang sama agent_framework.openai ditampilkan di sini. Teruskan input perutean Azure eksplisit seperti credential atau azure_endpoint ketika Anda menginginkan perutean Azure, lalu tetapkan api_version untuk antarmuka API Azure yang ingin Anda gunakan. Jika OPENAI_API_KEY dikonfigurasi, klien generik tetap berada di OpenAI bahkan ketika AZURE_OPENAI_* variabel juga ada. Jika Anda sudah memiliki URL lengkap .../openai/v1 , gunakan base_url alih-alih azure_endpoint. Untuk titik akhir proyek Microsoft Foundry dan Foundry Agent Service, lihat halaman penyedia Microsoft Foundry. Untuk runtime lokal, lihat Foundry Local.

Penginstalan

pip install agent-framework-openai

agent-framework-openai adalah paket penyedia Python opsional untuk penggunaan OpenAI langsung dan Azure OpenAI.

Konfigurasi

Klien obrolan Python OpenAI menggunakan pola variabel lingkungan ini:

Responses

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

Penyelesaian Percakapan

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

Azure OpenAI dengan klien yang sama

Azure OpenAI sekarang menggunakan klien Python OpenAI yang sama dengan OpenAI langsung. Pola Azure yang paling diinginkan dan jelas adalah meneruskan input perutean Azure secara eksplisit seperti credential atau azure_endpoint, lalu mengatur api_version untuk Azure setelah perutean dipilih. Jika OPENAI_API_KEY disetel, klien generik tetap berada di OpenAI kecuali Anda meneruskan input perutean Azure tersebut. Jika Anda hanya memiliki pengaturan AZURE_OPENAI_*, fallback lingkungan Azure masih berfungsi. OpenAIChatClient mengutamakan AZURE_OPENAI_CHAT_MODEL, OpenAIChatCompletionClient mengutamakan AZURE_OPENAI_CHAT_COMPLETION_MODEL, dan keduanya menggunakan AZURE_OPENAI_MODEL.

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

Jika Anda sudah memiliki URL Azure OpenAI lengkap yang diakhir dengan /openai/v1, teruskan sebagai base_url alih-alih azure_endpoint. Tetap api_version selaras dengan antarmuka Azure OpenAI API yang Anda gunakan. Jika OPENAI_API_KEY juga diatur di lingkungan Anda, input Azure eksplisit ini menyimpan klien di Azure.

Nota

Gunakan OpenAIChatClient untuk API Respons. Untuk autentikasi kunci Azure, Anda masih dapat meneruskan api_key, tetapi credential= sekarang menjadi permukaan autentikasi Azure pilihan.

Penyematan Azure dengan keluarga klien yang sama

OpenAIEmbeddingClient mengikuti aturan perutean yang sama dengan klien obrolan. Untuk embedding Azure, teruskan deployment embedding sebagai model dan lebih mengutamakan input Azure eksplisit.

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

Membuat Agen OpenAI

Responses

OpenAIChatClient menggunakan Responses API — klien utama yang direkomendasikan dengan dukungan untuk alat yang dihosting.

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

Alat yang didukung: Alat fungsi, persetujuan alat, penerjemah kode, pencarian file, pencarian web, MCP yang dihosting, alat MCP lokal.

Alat yang Dihosting dengan Respons Klien

Klien Respons menyediakan get_*_tool() metode untuk setiap jenis alat yang dihosting:

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)

Penyelesaian Percakapan

OpenAIChatCompletionClient menggunakan Chat Completions API — gunakan saat Anda memerlukan kompatibilitas model yang luas atau jika Anda sudah memiliki integrasi Chat Completions.

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

Alat yang didukung: Alat fungsi, pencarian web, alat MCP lokal.

Pencarian Web dengan Penyelesaian Percakapan

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)

Penting

Python tidak lagi mengirimkan klien/penyedia kompatibilitas Asisten. Untuk kode Python saat ini, gunakan OpenAIChatClient untuk skenario API Respons atau OpenAIChatCompletionClient untuk Penyelesaian Obrolan. Jika Anda memerlukan agen yang dikelola layanan di Microsoft Foundry, lihat halaman penyedia Microsoft Foundry.

Fitur Umum

Jenis klien ini mendukung fitur agen standar ini:

Perangkat Fungsional

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)

Percakapan dengan Banyak Putaran

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"

Siaran Langsung

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

Menggunakan Agen

Semua jenis klien menghasilkan standar Agent yang mendukung operasi yang sama.

Untuk informasi selengkapnya, lihat tutorial Memulai.

Alat

Klien OpenAI Python mengekspos permukaan alat yang berbeda tergantung pada API yang mendasarinya. OpenAIChatClient(Respons) mengirimkan pabrik alat yang dihosting melalui client.get_*_tool(...) — get_code_interpreter_tool, , get_file_search_tool, get_web_search_toolget_image_generation_tool, get_shell_tool, dan get_mcp_tool. OpenAIChatCompletionClient hanya menampilkan get_web_search_tool. Keduanya bekerja dengan alat fungsi dan server MCP lokal.

Matriks yang sama berlaku saat Anda mengarahkan klien ini ke Azure OpenAI — lihat Azure OpenAI.

Tool	OpenAIChatClient (Tanggapan)	OpenAIChatCompletionClient (Penyelesaian Obrolan)
Peralatan Fungsional	✅	✅
Persetujuan Alat	✅	✅
Penerjemah Kode	✅	❌
Pencarian File	✅	❌
Pencarian Web	✅	✅
Pembuatan Gambar	✅(get_image_generation_tool)	❌
Shell yang Di-hosting	✅(get_shell_tool)	❌
Alat MCP yang Dihosting	✅	❌
Alat MCP Lokal	✅	✅

Nota

Persetujuan Alat ditangani oleh klien chat pemanggil fungsi dari framework, sehingga dapat berfungsi dengan pemanggilan alat-fungsi apa pun, apa pun API yang mendasarinya.

Langkah selanjutnya

Microsoft Foundry