OpenAI

Microsoft Agent Framework unterstützt OpenAI-Agents in C#, Python und Go. C# und Python unterstützen zwei OpenAI-Clienttypen – Antworten und Chatabschluss – während Go derzeit den Anbieter "Chatabschluss" verwendet. Responses ist der empfohlene primäre Client, sofern verfügbar: Er ist auf die neuere OpenAI Responses API ausgelegt und unterstützt die vollständige Palette gehosteter Tools (Code-Interpreter, Dateisuche, Websuche, gehostetes MCP, Bildgenerierung). Verwenden Sie Chat Completions, wenn Sie breite Modellkompatibilität oder Go-Unterstützung benötigen oder bereits über eine Chat-Completions-Integration verfügen, die Sie beibehalten möchten.

Clienttyp API Optimal für
Antworten (empfohlen) Antwort-API Umfassende Agents mit gehosteten Tools (Codedolmetscher, Dateisuche, Websuche, gehostete MCP)
Chatabschluss API für Chatabschlusse Einfache Agents, umfassende Modellunterstützung

Note

Die OpenAI-Assistenten-API ist von OpenAI veraltet. Neuer Code sollte den Antwortclient verwenden. Wenn Sie von einer vorhandenen Assistenten-basierten App migrieren, lesen Sie den Migrationsleitfaden Semantischer Kernel.

Getting Started

Fügen Sie dem Projekt die erforderlichen NuGet-Pakete hinzu.

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

Antwort-Client

Der Antwortclient ist der empfohlene primäre Client und bietet die reichhaltigeste Toolunterstützung, einschließlich Codedolmetscher, Dateisuche, Websuche und gehosteter 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."));

Unterstützte Tools: Funktionstools, Toolgenehmigung, Codedolmetscher, Dateisuche, Websuche, gehostete MCP, lokale MCP-Tools.

Chat-Vervollständigungs-Client

Der Client für Chatabschlüsse bietet eine einfache Möglichkeit, Agenten mithilfe der API für Chatabschlüsse zu erstellen. Verwenden Sie sie, wenn Sie eine breite Modellkompatibilität benötigen oder bereits über eine Chat Completions-Integration verfügen.

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

Unterstützte Tools: Funktionstools, Websuche, lokale MCP-Tools.

Assistent-Klient

Note

Die OpenAI-Assistenten-API ist von OpenAI veraltet. Das Agent-Framework dokumentiert keinen Assistenten-Client mehr – verwenden Sie für neuen Code den oben genannten Responses-Client. Informationen zum Migrieren einer vorhandenen App finden Sie im Migrationshandbuch Semantischer Kernel.

Den Agent verwenden

Beide Clienttypen erzeugen einen Standard AIAgent , der dieselben Agent-Vorgänge unterstützt (Streaming, Threads, Middleware).

Weitere Informationen finden Sie in den Lernprogrammen "Erste Schritte".

Tools

Die OpenAI-.NET Clients stellen unterschiedliche Tooloberflächen bereit, je nachdem, auf welche API sie abzielen. Dieselbe Matrix gilt für die übereinstimmenden Azure OpenAI-Clients auf der Azure OpenAI-Anbieterseite.

Werkzeug Antworten Chat-Vervollständigung
Funktionswerkzeuge ✅ ✅
Toolgenehmigung ✅ ✅
Codedolmetscher ✅ ❌
Dateisuche ✅ ❌
Websuche ✅ ✅
Gehostete MCP-Tools ✅ ❌
Lokale MCP-Tools ✅ ✅

Note

Die Toolfreigabe wird vom Funktionsaufrufe unterstützenden Chatclient des Frameworks bereitgestellt und funktioniert daher bei jedem Aufruf eines Funktions-Tools unabhängig von der zugrunde liegenden API.

Note

Die OpenAI-Assistenten-API ist von OpenAI veraltet und Python enthält keinen Assistentenkompatibilitätsclient/-anbieter mehr. Verwenden Sie OpenAIChatClient für Responses oder OpenAIChatCompletionClient für Chat Completions. Wenn Sie von einer früheren Agent Framework-Python-Version migrieren, lesen Sie den Leitfaden Python erhebliche Änderungen. Wenn Sie von Semantischer Kernel migrieren, lesen Sie den Migrationsleitfaden Semantischer Kernel.

Tip

In Python verwendet Azure OpenAI jetzt dieselben agent_framework.openai hier gezeigten Clients. Übergeben Sie explizite Azure-Routingeingaben wie credential oder azure_endpoint für das Azure-Routing und legen Sie api_version für die Azure-API-Oberfläche fest, die Sie verwenden möchten. Wenn OPENAI_API_KEY es konfiguriert ist, verbleiben die generischen Clients bei OpenAI, auch wenn AZURE_OPENAI_* Variablen vorhanden sind. Wenn Sie bereits über eine vollständige .../openai/v1 URL verfügen, verwenden Sie base_url anstelle von azure_endpoint. Informationen zu Microsoft Foundry-Projektendpunkten und dem Foundry Agent Service finden Sie auf der Microsoft Foundry-Anbieterseite. Lokale Laufzeiten finden Sie unter Foundry Local.

Installation

pip install agent-framework-openai

agent-framework-openai ist das optionale Python-Anbieterpaket für die direkte OpenAI- und Azure OpenAI-Nutzung.

Configuration

Die Python OpenAI-Chatclients verwenden diese Umgebungsvariablenmuster:

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

Allgemeine Features

Diese Clienttypen unterstützen diese Standard-Agent-Features:

Funktionstools

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)

Multi-Turn-Unterhaltungen

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

Promptzwischenspeicherung

Auf Modellen, die explizite Eingabeaufforderungscache-Haltepunkte unterstützen, OpenAIChatClient können sie verwenden prompt_cache_keyprompt_cache_optionsund Content.additional_properties["prompt_cache_breakpoint"] das wiederverwendbare Präfix steuern. Cache-Schreibvorgänge können separat für unterstützte Modelle abgerechnet werden.

Die OpenAI-Cachenutzung wird in response.usage_details:

  • cache_creation_input_token_count – Eingabetoken, die in den vom Anbieter verwalteten Cache geschrieben wurden.
  • cache_read_input_token_count – Vom Cache bereitgestellte Eingabetoken.

Wenn OpenTelemetry aktiviert ist, werden diese Werte zugeordnet gen_ai.usage.cache_creation.input_tokens und 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.")

Den Agent verwenden

Alle Clienttypen erzeugen einen Standard Agent , der dieselben Vorgänge unterstützt.

Weitere Informationen finden Sie in den Lernprogrammen "Erste Schritte".

Tools

Die Python OpenAI-Clients machen abhängig von der zugrunde liegenden API unterschiedliche Tooloberflächen verfügbar. OpenAIChatClient (Antworten) liefert gehostete Tool-Factories über client.get_*_tool(...) — get_code_interpreter_tool, get_file_search_tool, get_web_search_tool, get_image_generation_tool, get_shell_tool und get_mcp_tool. OpenAIChatCompletionClient zeigt nur get_web_search_tool. Beide arbeiten mit Funktionstools und lokalen MCP-Servern.

Dieselbe Matrix gilt, wenn Sie diese Clients auf Azure OpenAI verweisen – siehe Azure OpenAI.

Werkzeug OpenAIChatClient (Antworten) OpenAIChatCompletionClient (Chatabschluss)
Funktionswerkzeuge ✅ ✅
Toolgenehmigung ✅ ✅
Codedolmetscher ✅ ❌
Dateisuche ✅ ❌
Websuche ✅ ✅
Bildgenerierung ✅ (get_image_generation_tool) ❌
Gehostete Shell ✅ (get_shell_tool) ❌
Gehostete MCP-Tools ✅ ❌
Lokale MCP-Tools ✅ ✅

Note

Die Tool-Freigabe wird vom funktionsaufrufenden Chatclient des Frameworks übernommen und funktioniert daher unabhängig von der zugrunde liegenden API mit jedem Funktions-Toolaufruf.

Abschluss des OpenAI-Chats

Das Paket openaiprovider erstellt Agenten mithilfe der OpenAI-API für Chat-Vervollständigungen.

Installation

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

Direct 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

Verwenden Sie dasselbe openaiprovider Paket mit Azure Anmeldeinformationen:

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 ist praktisch für die Entwicklung, erfordert aber sorgfältige Überlegungen in der Produktion. Berücksichtigen Sie in Produktionsumgebungen die Verwendung einer bestimmten Anmeldeinformation, wie azidentity.NewManagedIdentityCredential, um Latenzprobleme, unbeabsichtigtes Ausprobieren von Anmeldeinformationen und potenzielle Sicherheitsrisiken durch Fallbackmechanismen zu vermeiden.

Benutzerdefinierte Optionen

Übergeben Sie anbieterspezifische Optionen mithilfe von openaiprovider.ChatCompletionNewParams:

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

Unterstützte Tools: Funktionstools, Websuche, lokale MCP-Tools.

Tip

Im OpenAI-Anbieterbeispiel und Azure OpenAI-Beispiel finden Sie vollständige Beispiele.

Nächste Schritte

Microsoft Foundry

  • Last updated on