OpenAI

Microsoft Agent Framework stöder OpenAI-agenter i C#, Python och Go. C# och Python stöder två OpenAI-klienttyper – svar och slutförande av chatt – medan Go för närvarande använder providern För slutförande av chatt. Svar är den rekommenderade primära klienten när den är tillgänglig: den riktar sig till det nyare OpenAI-svars-API:et och stöder hela uppsättningen värdbaserade verktyg (kodtolk, filsökning, webbsökning, värdbaserad MCP, bildgenerering). Använd Chat Completion när du behöver bred modellkompatibilitet, stöd för Go eller har en befintlig Chat Completions-integrering som du vill behålla.

Klienttyp API Bäst för
Svar (rekommenderas) Api för svar Fullständiga agenter med värdbaserade verktyg (kodtolkare, filsökning, webbsökning, värdbaserad MCP)
Chatten har slutförts API för chattens slutförande Enkla agenter, brett modellstöd

Anmärkning

OpenAI:s Assistants API är föråldrat enligt OpenAI. Ny kod bör använda svarsklienten. Om du migrerar från en befintlig assistentbaserad app kan du läsa migreringsguiden Semantic Kernel.

Getting Started

Lägg till nödvändiga NuGet-paket i projektet.

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

Svarsklient

Responses-klienten är den rekommenderade primära klienten och erbjuder det mest omfattande verktygsstödet, inklusive kodtolkning, filsökning, webbsökning och hostad 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."));

Verktyg som stöds: Funktionsverktyg, verktygsgodkännande, kodtolkare, filsökning, webbsökning, värdbaserad MCP, lokala MCP-verktyg.

Klient för chattens slutförande

Klienten för Chat Completion är ett enkelt sätt att skapa agenter med hjälp av Chat Completions-API:et. Använd den när du behöver bred modellkompatibilitet eller har en befintlig Chat Completions-integrering.

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

Verktyg som stöds: Funktionsverktyg, webbsökning, lokala MCP-verktyg.

Assistentklient

Anmärkning

OpenAI Assistants-API:et är inaktuellt av OpenAI. Agent Framework dokumenterar inte längre en Assistants-klient – använd svarsklienten ovan för ny kod. Information om hur du migrerar en befintlig app finns i migreringsguiden Semantic Kernel.

Använda agenten

Båda klienttyperna skapar en standard AIAgent som stöder samma agentåtgärder (direktuppspelning, trådar, mellanprogram).

Mer information finns i kom igång-handledningarna.

Tools

OpenAI-.NET klienter exponerar olika verktygsytor beroende på vilket API de riktar in sig på. Samma matris gäller för matchande Azure OpenAI-klienter på sidan Azure OpenAI-provider.

Verktyg Responses Chatten har slutförts
Funktionsverktyg ✅ ✅
Godkännande av verktyg ✅ ✅
Kodtolkare ✅ ❌
Filsökning ✅ ❌
Webbsökning ✅ ✅
Värdhanterade MCP-verktyg ✅ ❌
Lokala MCP-verktyg ✅ ✅

Anmärkning

Godkännande av verktyg tillhandahålls av ramverkets funktionsanropande chattklient, så det fungerar med alla funktionsverktygsanrop oavsett det underliggande API:et.

Anmärkning

OpenAI Assistants-API:et är inaktuellt av OpenAI och Python inte längre levererar en assistentkompatibilitetsklient/provider. Används OpenAIChatClient för svar eller OpenAIChatCompletionClient för chattavslutningar. Om du migrerar från en tidigare Version av Agent Framework Python läser du guiden Python betydande ändringar. Om du migrerar från Semantic Kernel kan du läsa migreringsguiden Semantic Kernel.

Tips/Råd

I Python använder Azure OpenAI nu samma agent_framework.openai klienter som visas här. Skicka explicita Azure-routningsindata, till exempel credential eller azure_endpoint när du vill ha Azure-routning, och ange api_version sedan för den Azure API-yta som du vill använda. Om OPENAI_API_KEY har konfigurerats finns de allmänna klienterna kvar på OpenAI även när AZURE_OPENAI_* variabler också finns. Om du redan har en fullständig .../openai/v1 URL använder du base_url i stället för azure_endpoint. För Microsoft Foundry-projektslutpunkter och Foundry Agent Service, se sidan Microsoft Foundry-provider. För lokala körningar, se Foundry Local.

Installation

pip install agent-framework-openai

agent-framework-openai är det valfria Python-providerpaketet för både direkt OpenAI- och Azure OpenAI-användning.

Configuration

Python OpenAI-chattklienter använder följande miljövariabelmönster:

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

Vanliga funktioner

Dessa klienttyper stöder dessa standardagentfunktioner:

Funktionsverktyg

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)

Konversationer med flera turer

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

Snabb cachelagring

På modeller som stöder explicita brytpunkter OpenAIChatClient för prompt-cache kan du använda prompt_cache_key, prompt_cache_optionsoch Content.additional_properties["prompt_cache_breakpoint"] för att styra det återanvändbara prefixet. Cacheskrivningar kan faktureras separat på modeller som stöds.

OpenAI-cacheanvändning normaliseras i response.usage_details:

  • cache_creation_input_token_count – Indatatoken skrivs till providerhanterad cache.
  • cache_read_input_token_count – Indatatoken som hanteras från cacheminnet.

När OpenTelemetry är aktiverat mappas dessa värden till gen_ai.usage.cache_creation.input_tokens och 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.")

Använda agenten

Alla klienttyper skapar en standard Agent som stöder samma åtgärder.

Mer information finns i kom igång-handledningarna.

Tools

De Python OpenAI-klienterna exponerar olika verktygsytor beroende på det underliggande API:et. OpenAIChatClient (Svar) skickar värdbaserade verktygsfabriker via client.get_*_tool(...) – get_code_interpreter_tool, get_file_search_tool, get_web_search_tool, get_image_generation_tool, get_shell_tooloch get_mcp_tool. OpenAIChatCompletionClient exponerar endast get_web_search_tool. Båda fungerar med funktionsverktyg och lokala MCP-servrar.

Samma matris gäller när du pekar dessa klienter på Azure OpenAI – se Azure OpenAI.

Verktyg OpenAIChatClient (Svar) OpenAIChatCompletionClient (Chatten har slutförts)
Funktionsverktyg ✅ ✅
Godkännande av verktyg ✅ ✅
Kodtolkare ✅ ❌
Filsökning ✅ ❌
Webbsökning ✅ ✅
Bildgenerering ✅ (get_image_generation_tool) ❌
Värdbaserat gränssnitt ✅ (get_shell_tool) ❌
Värdhanterade MCP-verktyg ✅ ❌
Lokala MCP-verktyg ✅ ✅

Anmärkning

Godkännande av verktyg hanteras av ramverkets funktionsanropande chattklient, så det fungerar med alla funktionsverktygsanrop oavsett det underliggande API:et.

OpenAI-chatten har slutförts

Paketet openaiprovider skapar agenter med hjälp av API:et för slutförande av OpenAI-chatt.

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

Använd samma openaiprovider paket med Azure autentiseringsuppgifter:

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{
        },
    },
)

Varning

azidentity.NewDefaultAzureCredential är praktiskt för utveckling men kräver noggrant övervägande i produktion. I produktion bör du överväga att använda en specifik autentiseringsuppgift, till exempel azidentity.NewManagedIdentityCredential, för att undvika problem med svarstid, oavsiktlig avsökning av autentiseringsuppgifter och potentiella säkerhetsrisker från reservmekanismer.

Anpassade alternativ

Ange leverantörsspecifika alternativ med openaiprovider.ChatCompletionNewParams:

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

Verktyg som stöds: Funktionsverktyg, webbsökning, lokala MCP-verktyg.

Tips/Råd

Se OpenAI-providerexemplet och Azure OpenAI-exempel för fullständiga exempel.

Nästa steg

Microsoft Foundry

  • Last updated on