OpenAI

Microsoft Agent Framework podporuje agenty OpenAI v C#, Python a Go. C# a Python podporují dva typy klientů OpenAI – Odpovědi a dokončování chatu – zatímco Go aktuálně používá poskytovatele dokončení chatu. Odpovědi jsou doporučeným primárním klientem, pokud jsou k dispozici: cílí na novější rozhraní OPENAI Responses API a podporuje úplnou sadu hostovaných nástrojů (interpret kódu, vyhledávání souborů, webové vyhledávání, hostované MCP, generování imagí). Použijte Chat Completions, když potřebujete širokou kompatibilitu s modely, podporu pro Go nebo chcete zachovat stávající integraci Chat Completions.

Typ klienta API Nejvhodnější pro
Odpovědi (doporučeno) Rozhraní API pro odpovědi Plnohodnotní agenti s hostovanými nástroji (interpret kódu, vyhledávání souborů, vyhledávání na webu, hostovaný MCP)
Dokončení chatu Rozhraní API pro dokončování chatu Jednoduchí agenti, široká podpora modelů

Note

OpenAI označilo API asistentů za zastaralé. Nový kód by měl používat klienta Odpovědi. Pokud migrujete z existující aplikace založené na asistentech, přečtěte si průvodce migrací Sémantické jádro.

Začínáme

Přidejte do projektu požadované balíčky NuGet.

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

Klient pro odpovědi

Klient Odpovědi je doporučeným primárním klientem a poskytuje bohatší podporu nástrojů, včetně interpretu kódu, vyhledávání souborů, vyhledávání na webu a hostovaného 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."));

Podporované nástroje: Nástroje funkcí, schválení nástroje, interpret kódu, vyhledávání souborů, vyhledávání na webu, hostované MCP, místní nástroje MCP.

Klient pro dokončování chatu

Klient pro dokončování chatu poskytuje jednoduchý způsob, jak vytvářet agenty pomocí rozhraní API pro dokončování chatu. Použijte ho, pokud potřebujete širokou kompatibilitu s modely nebo máte existující integraci rozhraní 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."));

Podporované nástroje: Nástroje funkcí, vyhledávání na webu, místní nástroje MCP.

Klient asistentů

Note

API asistentů OpenAI je společností OpenAI označeno jako zastaralé. Framework Agent již nedokumentuje klienta Assistants — pro nový kód použijte výše uvedeného klienta Responses. Informace o migraci existující aplikace najdete v průvodci migrací Sémantické jádro.

Použití agenta

Oba typy klientů vytvářejí standard AIAgent , který podporuje stejné operace agenta (streamování, vlákna, middleware).

Další informace najdete v kurzech Začínáme.

Tools

Klienti OpenAI .NET zpřístupňují různé oblasti nástrojů v závislosti na tom, na jakém rozhraní API cílí. Stejná matice platí pro odpovídající klienty Azure OpenAI na stránce poskytovatele Azure OpenAI.

nástroj Odpovědi Dokončení chatu
Funkční nástroje ✅ ✅
Schválení nástroje ✅ ✅
Interpretér kódu ✅ ❌
Hledání souborů ✅ ❌
Vyhledávání na webu ✅ ✅
Hostované nástroje MCP ✅ ❌
Místní nástroje MCP ✅ ✅

Note

Schválení nástrojů poskytuje chatovací klient frameworku pro volání funkcí, takže funguje s jakýmkoli voláním funkce‑nástroje bez ohledu na podkladové API.

Note

OpenAI označilo rozhraní Assistants API za zastaralé a Python již nedodává klienta ani poskytovatele kompatibilního s Assistants. Slouží OpenAIChatClient pro odpovědi nebo OpenAIChatCompletionClient pro dokončování chatu. Pokud migrujete z předchozí verze agenta Framework Python, přečtěte si Python průvodce významnými změnami. Pokud migrujete z Sémantické jádro, přečtěte si průvodce migrací Sémantické jádro.

Tip

V Pythonu teď Azure OpenAI používá stejné agent_framework.openai klienty jako tady. Předejte explicitní vstupy směrování Azure, jako credential nebo azure_endpoint když chcete směrování Azure, a pak nastavte api_version pro rozhraní Azure API, které chcete použít. Pokud je nakonfigurováno OPENAI_API_KEY, zůstanou obecní klienti u OpenAI i když jsou k dispozici proměnné AZURE_OPENAI_*. Pokud už máte úplnou .../openai/v1 adresu URL, použijte base_url místo azure_endpoint. Informace o koncových bodech projektu Microsoft Foundry a službě Foundry Agent naleznete na stránce zprostředkovatele Microsoft Foundry. Místní moduly runtime naleznete v tématu Foundry Local.

Instalace

pip install agent-framework-openai

agent-framework-openai je volitelný balíček poskytovatele Pythonu pro přímé použití s OpenAI a Azure OpenAI.

Configuration

Klienti chatu Python OpenAI používají tyto vzory proměnných prostředí:

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

Běžné funkce

Tyto typy klientů podporují tyto standardní funkce agenta:

Funkční nástroje

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)

Konverzace s více výměnami

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

Ukládání promptů do mezipaměti

U modelů, které podporují explicitní zarážky mezipaměti prompt-cache, OpenAIChatClient mohou používat prompt_cache_keyprompt_cache_optionsa Content.additional_properties["prompt_cache_breakpoint"] řídit opakovaně použitelnou předponu. Zápisy do mezipaměti se dají fakturovat samostatně na podporovaných modelech.

Využití mezipaměti OpenAI je normalizováno v response.usage_details:

  • cache_creation_input_token_count – Vstupní tokeny zapsané do mezipaměti spravované zprostředkovatelem.
  • cache_read_input_token_count – Vstupní tokeny obsluhované z mezipaměti.

Pokud je povolena openTelemetry, tyto hodnoty se mapují na gen_ai.usage.cache_creation.input_tokens a 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.")

Použití agenta

Všechny typy klientů vytvářejí standard Agent , který podporuje stejné operace.

Další informace najdete v kurzech Začínáme.

Tools

Klienti OpenAI Python zpřístupňují různé plochy nástrojů v závislosti na podkladovém rozhraní API. OpenAIChatClient (Odpovědi) dodává hostované továrny nástrojů prostřednictvím client.get_*_tool(...) — get_code_interpreter_tool, get_file_search_tool, get_web_search_tool, get_image_generation_tool, get_shell_tool a get_mcp_tool. OpenAIChatCompletionClient zpřístupňuje pouze get_web_search_tool. Oba pracují s nástroji funkcí a místními servery MCP.

Stejná matice platí, když nasměrujete tyto klienty na Azure OpenAI – viz Azure OpenAI.

nástroj OpenAIChatClient (Odpovědi) OpenAIChatCompletionClient (Dokončení chatu)
Funkční nástroje ✅ ✅
Schválení nástroje ✅ ✅
Interpretér kódu ✅ ❌
Hledání souborů ✅ ❌
Vyhledávání na webu ✅ ✅
Generování obrázků ✅ (get_image_generation_tool) ❌
Hostované prostředí ✅ (get_shell_tool) ❌
Hostované nástroje MCP ✅ ❌
Místní nástroje MCP ✅ ✅

Note

Schválení nástrojů zajišťuje chatovací klient frameworku pro volání funkcí, takže funguje s libovolným voláním funkce nástroje bez ohledu na použité podkladové rozhraní API.

Dokončení chatu OpenAI

Balíček openaiprovider vytvoří agenty pomocí rozhraní API pro dokončování chatu OpenAI.

Instalace

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

Použijte stejný openaiprovider balíček s přihlašovacími údaji 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 je vhodný pro vývoj, ale vyžaduje pečlivé zvážení v produkčním prostředí. V produkčním prostředí zvažte použití konkrétních přihlašovacích údajů, například azidentity.NewManagedIdentityCredential, abyste se vyhnuli problémům s latencí, neúmyslnému testování přihlašovacích údajů a potenciálním bezpečnostním rizikům z náhradních mechanismů.

Vlastní možnosti

Předejte možnosti specifické pro poskytovatele pomocí openaiprovider.ChatCompletionNewParams:

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

Podporované nástroje: Nástroje funkcí, vyhledávání na webu, místní nástroje MCP.

Tip

Kompletní příklady najdete v ukázce poskytovatele OpenAI a ukázce Azure OpenAI.

Další kroky

Microsoft Foundry

  • Last updated on