Agen OpenAI

Microsoft Agent Framework mendukung beberapa jenis klien OpenAI. Dalam C#, ini mencakup Penyelesaian Obrolan, Respons, dan Asisten. Di Python, penyedia terdepan OpenAI memiliki fitur Penyelesaian Obrolan dan Respons.

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

Ketersediaan bahasa bervariasi. Python menggunakan klien Chat Completion dan Responses di halaman ini; cakupan Asistensi di bawah ini hanya untuk C#.

Memulai Langkah Awal

Tambahkan paket NuGet yang diperlukan ke proyek Anda.

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

Klien Penyelesaian Percakapan

Klien Penyelesaian Obrolan menyediakan cara mudah untuk membuat agen menggunakan ChatCompletion API.

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.

Respons Klien

Klien Respons 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 Asisten

Klien Asisten membuat agen yang dikelola server dengan penerjemah kode bawaan dan pencarian file.

using Microsoft.Agents.AI;
using OpenAI;

OpenAIClient client = new OpenAIClient("<your_api_key>");
var assistantsClient = client.GetAssistantClient();

// Assistants are managed server-side
AIAgent agent = assistantsClient.AsAIAgent(
    instructions: "You are a data analysis assistant.",
    name: "DataHelper");

Console.WriteLine(await agent.RunAsync("Analyze trends in the uploaded data."));

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

Petunjuk / Saran

Lihat sampel .NET untuk contoh lengkap yang dapat dijalankan.

Menggunakan Agen

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

Untuk informasi selengkapnya, lihat tutorial Memulai.

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:

Penyelesaian Percakapan

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

Responses

OPENAI_API_KEY="your-openai-api-key"
OPENAI_CHAT_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

Penyelesaian Percakapan

OpenAIChatCompletionClient menggunakan API Penyelesaian Obrolan — opsi paling sederhana dengan dukungan model yang luas.

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)

Responses

OpenAIChatClient menggunakan API Respons — opsi paling kaya fitur dengan 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)

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.

Langkah selanjutnya

Microsoft Foundry