OpenAI

Microsoft Agent Framework prend en charge les agents OpenAI en C#, Python et Go. C# et Python prennent en charge deux types de clients OpenAI — Responses et Chat Completions —, tandis que Go utilise actuellement le fournisseur Chat Completions. Les réponses sont le client principal recommandé lorsqu’il est disponible : il cible l’API Réponses OpenAI plus récente et prend en charge l’ensemble complet d’outils hébergés (interpréteur de code, recherche de fichiers, recherche web, mcP hébergé, génération d’images). Utilisez Chat Completion lorsque vous avez besoin d’une large compatibilité entre les modèles, de la prise en charge de Go, ou que vous disposez déjà d’une intégration Chat Completions à conserver.

Type de client API Idéal pour
Réponses (recommandées) API Réponses Agents complets avec des outils hébergés (interpréteur de code, recherche de fichiers, recherche web, MCP hébergé)
Complétion des conversations API de complétion de chat Agents simples, prise en charge étendue des modèles

Note

L’API Assistants OpenAI est déconseillée par OpenAI. Le nouveau code doit utiliser le client Réponses. Si vous effectuez une migration à partir d’une application basée sur Assistants existante, consultez le guide de migration Noyau sémantique.

Getting Started

Ajoutez les packages NuGet requis à votre projet.

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

Réponses du client

Le client Réponses est le client principal recommandé et fournit la prise en charge des outils les plus riches, notamment l’interpréteur de code, la recherche de fichiers, la recherche web et le MCP hébergé.

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

Outils pris en charge : Outils de fonction, approbation des outils, interpréteur de code, recherche de fichiers, recherche web, mcP hébergé, outils MCP locaux.

Client d’achèvement de conversation

Le client Chat Completion offre un moyen simple de créer des agents à l’aide de l’API Chat Completions. Utilisez-le lorsque vous avez besoin d’une large compatibilité avec les modèles ou que vous disposez déjà d’une intégration 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."));

Outils pris en charge : Outils de fonction, recherche web, outils MCP locaux.

Assistants du Client

Note

L’API Assistants OpenAI est déconseillée par OpenAI. Agent Framework ne documente plus un client Assistants : utilisez le client Réponses ci-dessus pour le nouveau code. Pour migrer une application existante, consultez le guide de migration Noyau sémantique.

Utilisation de l’agent

Les deux types de clients produisent une norme AIAgent qui prend en charge les mêmes opérations d’agent (streaming, threads, middleware).

Pour plus d’informations, consultez les didacticiels De prise en main.

Tools

Les clients OpenAI .NET exposent différentes surfaces d’outils en fonction de l’API qu’ils ciblent. La même matrice s’applique aux Azure clients OpenAI correspondants sur la page du fournisseur OpenAI Azure.

Tool Réponses Fin de la conversation
Outils de fonction ✅ ✅
Approbation de l’outil ✅ ✅
Interpréteur de code ✅ ❌
Recherche de fichiers ✅ ❌
Recherche web ✅ ✅
Outils MCP hébergés ✅ ❌
Outils MCP locaux ✅ ✅

Note

Approbation de l’outil est fournie par le client de chat d’invocation de fonctions du framework, de sorte qu’elle fonctionne avec tout appel à un outil de fonction, quelle que soit l’API sous-jacente.

Note

L’API Assistants OpenAI est déconseillée par OpenAI et Python n’envoie plus de client/fournisseur de compatibilité Assistants. Utilisez OpenAIChatClient pour les Réponses ou OpenAIChatCompletionClient pour les Chat Completions. Si vous effectuez une migration à partir d’une version précédente d’Agent Framework Python, consultez le Python guide des modifications importantes. Si vous effectuez une migration à partir de Noyau sémantique, consultez le guide de migration Noyau sémantique.

Tip

Dans Python, Azure OpenAI utilise désormais les mêmes agent_framework.openai clients présentés ici. Transmettez des entrées de routage Azure explicites telles que credential ou azure_endpoint lorsque vous souhaitez un routage Azure, puis définissez api_version la surface d’API Azure que vous souhaitez utiliser. S’il OPENAI_API_KEY est configuré, les clients génériques restent sur OpenAI même lorsque les variables AZURE_OPENAI_* sont également présentes. Si vous disposez déjà d'une URL complète .../openai/v1, utilisez base_url plutôt que azure_endpoint. Pour les points de terminaison de projet Microsoft Foundry et le service Foundry Agent, consultez la page du fournisseur Microsoft Foundry. Pour les runtimes locaux, consultez Foundry Local.

Installation

pip install agent-framework-openai

agent-framework-openai est le package de fournisseur Python facultatif pour l’utilisation directe d’OpenAI et d’Azure OpenAI.

Configuration

Les clients de conversation Python OpenAI utilisent ces modèles de variables d’environnement :

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

Fonctionnalités courantes

Ces types de clients prennent en charge ces fonctionnalités d’agent standard :

Outils de fonction

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)

Conversations à plusieurs tours

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"

Diffusion en continu

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

Mise en cache de prompt

Sur les modèles qui prennent en charge les points d’arrêt explicites du cache d’invite, OpenAIChatClient peuvent utiliser prompt_cache_key, prompt_cache_optionset Content.additional_properties["prompt_cache_breakpoint"] pour contrôler le préfixe réutilisable. Les écritures de cache peuvent être facturées séparément sur les modèles pris en charge.

L’utilisation du cache OpenAI est normalisée dans response.usage_details:

  • cache_creation_input_token_count - Jetons d’entrée écrits dans le cache géré par le fournisseur.
  • cache_read_input_token_count - Jetons d’entrée servis à partir du cache.

Lorsque OpenTelemetry est activé, ces valeurs sont mappées à gen_ai.usage.cache_creation.input_tokens et 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.")

Utilisation de l’agent

Tous les types de clients produisent une norme Agent qui prend en charge les mêmes opérations.

Pour plus d’informations, consultez les didacticiels De prise en main.

Tools

Les clients OpenAI Python exposent différentes surfaces d’outils en fonction de l’API sous-jacente. OpenAIChatClient (Réponses) propose des fabriques d’outils hébergées via client.get_*_tool(...) — get_code_interpreter_tool, get_file_search_tool, get_web_search_tool, get_image_generation_tool, get_shell_tool et get_mcp_tool. OpenAIChatCompletionClient n’expose que get_web_search_tool. Les deux fonctionnent avec les outils de fonction et les serveurs MCP locaux.

La même matrice s’applique lorsque vous pointez ces clients à Azure OpenAI . Consultez Azure OpenAI.

Tool OpenAIChatClient (Réponses) OpenAIChatCompletionClient (Complétion de chat)
Outils de fonction ✅ ✅
Approbation de l’outil ✅ ✅
Interpréteur de code ✅ ❌
Recherche de fichiers ✅ ❌
Recherche web ✅ ✅
Génération d’images ✅ (get_image_generation_tool) ❌
Shell hébergé ✅ (get_shell_tool) ❌
Outils MCP hébergés ✅ ❌
Outils MCP locaux ✅ ✅

Note

Approbation de l’outil est gérée par le client de chat avec appel de fonctions du framework, de sorte qu’elle fonctionne avec tout appel à un outil de type fonction, quelle que soit l’API sous-jacente.

Complétions de conversation OpenAI

Le openaiprovider package crée des agents à l’aide de l’API OpenAI Chat Completions.

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

Utilisez le même openaiprovider package avec des informations d’identification 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 est pratique pour le développement, mais nécessite une considération minutieuse en production. En production, envisagez d’utiliser des informations d’identification spécifiques, telles que azidentity.NewManagedIdentityCredential, pour éviter les problèmes de latence, la détection involontaire des informations d’identification et les risques de sécurité potentiels liés aux mécanismes de secours.

Options personnalisées

Transmettez des options spécifiques au fournisseur en utilisant openaiprovider.ChatCompletionNewParams :

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

Outils pris en charge : Outils de fonction, recherche web, outils MCP locaux.

Tip

Consultez l’exemple de fournisseur OpenAI et Azure exemple OpenAI pour obtenir des exemples complets.

Étapes suivantes

Microsoft Foundry

  • Last updated on