OpenAI

Microsoft Agent Framework admite agentes de OpenAI en C#, Python y Go. C# y Python admiten dos tipos de cliente openAI ( Respuestas y finalización de chat), mientras que Go usa actualmente el proveedor de finalizaciones de chat. Las respuestas son el cliente principal recomendado cuando está disponible: tiene como destino la API de respuestas de OpenAI más reciente y admite el conjunto completo de herramientas hospedadas (intérprete de código, búsqueda de archivos, búsqueda web, MCP hospedado, generación de imágenes). Utiliza Chat Completion cuando necesites una amplia compatibilidad con modelos, soporte para Go o si quieres mantener una integración existente de Chat Completions.

Tipo de cliente API Óptimo para
Respuestas (recomendadas) API de respuestas Agentes completos con herramientas hospedadas (intérprete de código, búsqueda de archivos, búsqueda web, MCP hospedado)
Finalización del chat API de finalizaciones de chat Agentes simples, compatibilidad amplia con modelos

Note

La API de OpenAI Assistants ha sido declarada obsoleta por OpenAI. El nuevo código debe usar el cliente de respuestas. Si va a migrar desde una aplicación basada en asistentes existente, consulte la guía de migración Kernel semántico.

Getting Started

Agregue los paquetes NuGet necesarios al proyecto.

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

Cliente de respuestas

El cliente de respuestas es el cliente principal recomendado y proporciona la compatibilidad con herramientas más ricas, como el intérprete de código, la búsqueda de archivos, la búsqueda web y el MCP hospedado.

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

Herramientas admitidas: Herramientas de funciones, aprobación de herramientas, intérprete de código, búsqueda de archivos, búsqueda web, MCP hospedado, herramientas de MCP locales.

Cliente de finalización de chat

El cliente de finalización de chat proporciona una manera sencilla de crear agentes mediante la API de finalizaciones de chat. Úselo cuando necesite compatibilidad con una amplia gama de modelos o tenga una integración existente con 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."));

Herramientas admitidas: Herramientas de funciones, búsqueda web, herramientas de MCP locales.

Cliente de asistentes

Note

OpenAI Assistants API está en desuso por OpenAI. El Agent Framework ya no incluye documentación sobre un cliente de Assistants; use el cliente Responses anterior para el código nuevo. Para migrar una aplicación existente, consulte la guía de migración Kernel semántico.

Uso del agente

Ambos tipos de cliente generan un estándar AIAgent que admite las mismas operaciones del agente (streaming, subprocesos, middleware).

Para obtener más información, consulte los tutoriales de introducción.

Tools

Los clientes de OpenAI .NET exponen diferentes superficies de herramientas en función de la API que tienen como destino. La misma matriz se aplica a los clientes correspondientes de Azure OpenAI en la página del proveedor de Azure OpenAI.

Herramienta Respuestas Finalización del chat
Herramientas de funciones ✅ ✅
Aprobación de herramientas ✅ ✅
Intérprete de código ✅ ❌
Búsqueda de archivos ✅ ❌
Búsqueda web ✅ ✅
Herramientas de MCP hospedadas ✅ ❌
Herramientas de MCP locales ✅ ✅

Note

La aprobación de herramientas la proporciona el cliente de chat de invocación de funciones del marco, por lo que funciona con cualquier llamada a función-herramienta independientemente de la API subyacente.

Note

OpenAI Assistants API está en desuso por OpenAI y Python ya no incluye un cliente o proveedor de compatibilidad de Assistants. Use OpenAIChatClient para respuestas o OpenAIChatCompletionClient para finalizaciones de chat. Si va a migrar desde una versión anterior de Agent Framework Python, consulte la guía Python cambios significativos. Si va a migrar desde Kernel semántico, consulte la guía de migración Kernel semántico.

Tip

En Python, Azure OpenAI ahora usa los mismos agent_framework.openai clientes que se muestran aquí. Pase entradas de enrutamiento explícitas de Azure, como credential o azure_endpoint, cuando desee el enrutamiento de Azure, y luego establezca api_version para la superficie de API de Azure que quiera usar. Si OPENAI_API_KEY está configurado, los clientes genéricos permanecen en OpenAI incluso cuando las variables AZURE_OPENAI_* también están presentes. Si ya tiene una dirección URL completa .../openai/v1 , use base_url en lugar de azure_endpoint. Para los puntos de conexión del proyecto de Microsoft Foundry y el servicio Foundry Agent, consulte la página proveedor de Microsoft Foundry. Para los entornos de ejecución locales, consulte Foundry Local.

Instalación

pip install agent-framework-openai

agent-framework-openai es el paquete de proveedor de Python opcional para el uso directo de OpenAI y Azure OpenAI.

Configuration

Los clientes de chat de OpenAI de Python usan estos patrones de variables de entorno:

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

Características comunes

Estos tipos de cliente admiten estas características de agente estándar:

Herramientas de funciones

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)

Conversaciones multiturno

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

Almacenamiento en caché de avisos

En los modelos que admiten puntos de interrupción explícitos de la caché de mensajes, OpenAIChatClient puede usar prompt_cache_key, prompt_cache_optionsy Content.additional_properties["prompt_cache_breakpoint"] para controlar el prefijo reutilizable. Las escrituras de caché se pueden facturar por separado en los modelos admitidos.

El uso de la caché de OpenAI se normaliza en response.usage_details:

  • cache_creation_input_token_count - Tokens de entrada escritos en la caché administrada por el proveedor.
  • cache_read_input_token_count - Tokens de entrada servidos desde la memoria caché.

Cuando OpenTelemetry está habilitado, estos valores se asignan a gen_ai.usage.cache_creation.input_tokens y 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.")

Uso del agente

Todos los tipos de cliente generan un estándar Agent que admite las mismas operaciones.

Para obtener más información, consulte los tutoriales de introducción.

Tools

Los clientes de OpenAI para Python exponen diferentes interfaces de herramientas en función de la API subyacente. OpenAIChatClient (Respuestas) ofrece factorías de herramientas alojadas a través de client.get_*_tool(...): get_code_interpreter_tool, get_file_search_tool, get_web_search_tool, get_image_generation_tool, get_shell_tool y get_mcp_tool. OpenAIChatCompletionClient solo expone get_web_search_tool. Ambos funcionan con herramientas de función y servidores MCP locales.

La misma matriz se aplica cuando dirige estos clientes a Azure OpenAI; consulte Azure OpenAI.

Herramienta OpenAIChatClient (Respuestas) OpenAIChatCompletionClient (Finalización del chat)
Herramientas de funciones ✅ ✅
Aprobación de herramientas ✅ ✅
Intérprete de código ✅ ❌
Búsqueda de archivos ✅ ❌
Búsqueda web ✅ ✅
Generación de imágenes ✅ (get_image_generation_tool) ❌
Shell hospedado ✅ (get_shell_tool) ❌
Herramientas de MCP hospedadas ✅ ❌
Herramientas de MCP locales ✅ ✅

Note

La aprobación de herramientas se controla mediante el cliente de chat de invocación de funciones del marco, por lo que funciona con cualquier llamada a la herramienta de función independientemente de la API subyacente.

Completaciones de chat de OpenAI

El paquete openaiprovider crea agentes utilizando la API de Chat Completions de OpenAI.

Instalación

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

Use el mismo openaiprovider paquete con credenciales de 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 es conveniente para el desarrollo, pero requiere una consideración cuidadosa en producción. En producción, considere usar una credencial específica, como azidentity.NewManagedIdentityCredential, para evitar problemas de latencia, intentos no deseados de probar credenciales y posibles riesgos de seguridad derivados de los mecanismos de respaldo.

Opciones personalizadas

Pase opciones específicas del proveedor mediante openaiprovider.ChatCompletionNewParams:

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

Herramientas admitidas: Herramientas de funciones, búsqueda web, herramientas de MCP locales.

Tip

Consulte el ejemplo de proveedor de OpenAI y Azure ejemplo de OpenAI para obtener ejemplos completos.

Pasos siguientes

Microsoft Foundry

  • Last updated on