OpenAI

使用者入門

將必要的 NuGet 套件新增至您的專案。

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

Responses 用戶端

Responses 用戶端是推薦的主要用戶端，提供最豐富的工具支援，包括程式碼直譯器、檔案搜尋、網頁搜尋及託管 MCP。

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

支援工具： 功能工具、工具審核、程式碼解譯器、檔案搜尋、網頁搜尋、託管 MCP、本地 MCP 工具。

聊天完成客戶端

聊天完成客戶端提供了一種直接使用聊天完成 API 來建立代理的方式。 當你需要廣泛的模型相容性或已有 Chat Completions 整合時，可以使用它。

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

支援工具： 功能工具、網頁搜尋、本地 MCP 工具。

助理用戶端

使用代理程式

兩種用戶端類型都會產生一個標準的 AIAgent，支援相同的代理程式操作（串流、執行緒、中介軟體）。

更多資訊請參閱 入門教學。

Tools

OpenAI .NET 用戶端會根據目標 API 暴露不同的工具表面。 同樣的對照表也適用於 Azure OpenAI 提供者頁面 上相對應的 Azure OpenAI 用戶端。

Installation

pip install agent-framework-openai

agent-framework-openai 是可選的 Python 提供者套件，適用於直接使用 OpenAI 和 Azure OpenAI。

傳送 MP3 或 WAV 音訊

兩個 Python OpenAI 聊天客戶端都接受支援音訊輸入的模型所提供的音訊輸入。 MP3 內容請使用註冊的 audio/wav 媒體類型，WAV 內容請使用 audio/mpeg：

from agent_framework import Content, Message

with open("question.mp3", "rb") as audio_file:
    message = Message(
        role="user",
        contents=[
            Content.from_text("Transcribe this audio."),
            Content.from_data(
                data=audio_file.read(),
                media_type="audio/mpeg",
            ),
        ],
    )

response = await agent.run(message)
print(response.text)

OpenAIChatClient 同時 OpenAIChatCompletionClient 也接受常見的舊有 MP3 媒體別名，包括 audio/mp3。 新程式碼請使用 audio/mpeg。 其他音訊格式需要供應商支援，且不會轉換成 OpenAI MP3 或 WAV 輸入。

並行重複使用 Responses 用戶端

一個 OpenAIChatClient 實例可以在同一事件迴圈上同時提供非同步通話，包括重疊的串流與非串流通話。 此保證不適用於 OpenAIChatCompletionClient。

為每個並行執行個體建立個別的 Agent 和 AgentSession，並分別傳遞訊息和選項。 使用者提供的中介軟體、工具與回調也必須支援並行性。 不要在作業系統執行緒或事件迴圈間共享客戶端，或在呼叫進行時改變設定。

Configuration

Python OpenAI 聊天客戶端使用以下環境變數模式：

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

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

pip install azure-identity

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 import Agent
from agent_framework.openai import OpenAIChatClient
from azure.identity import AzureCliCredential

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

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

asyncio.run(main())

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

import asyncio
from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient

async def main():
    agent = Agent(
        client=OpenAIChatClient(),
        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())

from agent_framework import Agent

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 = Agent(
        client=client,
        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)

import asyncio
from agent_framework import Agent
from agent_framework.openai import OpenAIChatCompletionClient

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

asyncio.run(main())

from typing import Any

from agent_framework import Content, Message
from agent_framework.openai import OpenAIChatCompletionClient

_REASONING_FIELD = "_source_reasoning_field"


def parse_vllm_reasoning(
    response_message: Any,
    contents: list[Content],
) -> list[Content]:
    reasoning = getattr(response_message, "reasoning", None)
    if not isinstance(reasoning, str) or not reasoning:
        return contents

    return [
        *contents,
        Content.from_text_reasoning(
            text=reasoning,
            additional_properties={_REASONING_FIELD: "reasoning"},
        ),
    ]


def prepare_vllm_reasoning(
    message: Message,
    request_messages: list[dict[str, Any]],
) -> list[dict[str, Any]]:
    surfaced = [
        (content.additional_properties[_REASONING_FIELD], content.text)
        for content in message.contents
        if content.type == "text_reasoning"
        and _REASONING_FIELD in content.additional_properties
        and content.text
    ]
    if not surfaced:
        return request_messages

    prepared = list(request_messages)
    fields: dict[str, str] = {}
    for field_name, text in surfaced:
        for index, item in enumerate(prepared):
            if (
                item.get("role") == "assistant"
                and "tool_calls" not in item
                and item.get("content") == text
            ):
                prepared.pop(index)
                break
        fields[field_name] = fields.get(field_name, "") + text

    if prepared:
        prepared[-1].update(fields)
    return prepared


client = OpenAIChatCompletionClient(
    model="<model-name>",
    base_url="https://<provider-endpoint>/v1",
    response_parser=parse_vllm_reasoning,
    message_preparer=prepare_vllm_reasoning,
)

from agent_framework import Agent

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

    agent = Agent(
        client=client,
        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)

共同特徵

這些客戶端類型支援以下標準客服專員功能：

功能工具

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)

多回合交談

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

提示快取

在支援明確提示快取斷點的模型上，OpenAIChatClient 可以使用 prompt_cache_key、prompt_cache_options 和 Content.additional_properties["prompt_cache_breakpoint"] 來控制可重複使用的前綴。 在支援的模型上，快取寫入可另行計費。

OpenAI 快取使用量會在 response.usage_details 中標準化：

• cache_creation_input_token_count - 寫入提供者受控快取的輸入權杖。
• cache_read_input_token_count - 從快取中提供的輸入權杖。

啟用 OpenTelemetry 時，這些值會對應到 gen_ai.usage.cache_creation.input_tokens 和 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.")

使用代理程式

所有客戶端類型都會產生一個標準Agent，支援相同的操作。

更多資訊請參閱 入門教學。

Tools

Python OpenAI 用戶端會根據底層 API 暴露不同的工具表面。 OpenAIChatClient (Responses) 透過 client.get_*_tool(...) 發佈託管工具工廠 — get_code_interpreter_tool、get_file_search_tool、get_web_search_tool、get_image_generation_tool、get_shell_tool 和 get_mcp_tool。 OpenAIChatCompletionClient 只暴露 get_web_search_tool。 兩者都能搭配函式工具和本地 MCP 伺服器運作。

當你將這些客戶端指向 OpenAI Azure，也同樣適用這個矩陣——參見 Azure OpenAI。

OpenAI 對話完成

該 openaiprovider 套件使用 OpenAI 聊天完成 API 來建立代理。

Installation

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

直接使用 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

使用相同的 openaiprovider 套件，搭配 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{
        },
    },
)

自訂選項

使用 openaiprovider.ChatCompletionNewParams 傳遞提供者專屬選項：

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

支援工具： 功能工具、網頁搜尋、本地 MCP 工具。