OpenAI

Microsoft Agent Framework mendukung agen OpenAI di C#, Python, dan Go. C# dan Python mendukung dua jenis klien OpenAI — Respons dan Penyelesaian Obrolan — sementara Go saat ini menggunakan penyedia Penyelesaian Obrolan. Respons adalah klien utama yang direkomendasikan jika tersedia: ia menargetkan OPENAI Responses API yang lebih baru dan mendukung set lengkap alat yang dihosting (penerjemah kode, pencarian file, pencarian web, MCP yang dihosting, pembuatan gambar). Gunakan Chat Completion saat Anda memerlukan kompatibilitas dengan berbagai model, dukungan untuk Go, atau sudah memiliki integrasi Chat Completions yang ingin dipertahankan.

Jenis Klien API Terbaik Untuk
Respons (disarankan ) Response API Agen berfitur lengkap dengan alat yang dihosting (penerjemah kode, pencarian file, pencarian web, MCP yang dihosting)
Penyelesaian Percakapan API Penyelesaian Chat 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.

Getting Started

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

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.

Tools

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.

Alat Respons 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.

Tip

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.

Configuration

Klien obrolan Python OpenAI menggunakan pola variabel lingkungan ini:

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

Fitur Umum

Jenis klien ini mendukung fitur agen standar ini:

Perangkat Fungsional

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)

Percakapan dengan Banyak Putaran

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

Penyimpanan sementara prompt

Pada model yang mendukung titik henti prompt-cache eksplisit, OpenAIChatClient dapat menggunakan prompt_cache_key, prompt_cache_options, dan Content.additional_properties["prompt_cache_breakpoint"] untuk mengontrol awalan yang dapat digunakan kembali. Penulisan cache dapat ditagih secara terpisah pada model yang didukung.

Penggunaan cache OpenAI dinormalisasi dalam response.usage_details:

  • cache_creation_input_token_count - Token input yang ditulis ke cache yang dikelola penyedia.
  • cache_read_input_token_count - Token input dilayani dari cache.

Ketika OpenTelemetry diaktifkan, nilai-nilai ini memetakan ke gen_ai.usage.cache_creation.input_tokens dan gen_ai.usage.cache_read.input_tokens.

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

Menggunakan Agen

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

Untuk informasi selengkapnya, lihat tutorial Memulai.

Tools

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.

Alat 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.

Penyelesaian Percakapan OpenAI

Paket openaiprovider membuat agen menggunakan OpenAI Chat Completions API.

Penginstalan

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

Akses Langsung ke 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

Gunakan paket yang sama openaiprovider dengan kredensial Azure:

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 nyaman untuk pengembangan tetapi membutuhkan pertimbangan yang cermat dalam produksi. Dalam produksi, pertimbangkan untuk menggunakan kredensial tertentu, seperti azidentity.NewManagedIdentityCredential, untuk menghindari masalah latensi, pemeriksaan kredensial yang tidak diinginkan, dan potensi risiko keamanan dari mekanisme fallback.

Opsi khusus

Berikan opsi khusus penyedia menggunakan openaiprovider.ChatCompletionNewParams:

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

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

Tip

Lihat sampel penyedia OpenAI dan sampel OpenAI Azure untuk contoh lengkap.

Langkah berikutnya

Microsoft Foundry

  • Last updated on