Compartir a través de

Agentes de OpenAI

Microsoft Agent Framework admite tres tipos de cliente openAI distintos, cada uno de los cuales tiene como destino una superficie de API diferente con distintas funcionalidades de herramientas:

Tipo de cliente: API Mejor para
Finalización del chat API de finalizaciones de chat Agentes simples, compatibilidad amplia con modelos
Respuestas API de respuestas Agentes completos con herramientas hospedadas (intérprete de código, búsqueda de archivos, búsqueda web, MCP hospedado)
Asistentes API de asistentes Agentes administrados por el servidor con el intérprete de código y la búsqueda de archivos

Sugerencia

Para los equivalentes de Azure OpenAI (AzureOpenAIChatClient, AzureOpenAIResponsesClient, AzureOpenAIAssistantsClient), consulte la página del proveedor de Azure OpenAI. El soporte de herramientas es idéntico.

Introducción

Agregue los paquetes NuGet necesarios al proyecto.

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

Cliente de finalización de chat

El cliente de finalización de chat proporciona una manera sencilla de crear agentes mediante chatCompletion API.

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 respuestas

El cliente de respuestas 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.GetResponseClient("gpt-4o-mini");

AIAgent agent = responsesClient.AsAIAgent(
    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 asistentes

El cliente assistants crea agentes administrados por el servidor con el intérprete de código integrado y la búsqueda de archivos.

using Microsoft.Agents.AI;
using OpenAI;

OpenAIClient client = new OpenAIClient("<your_api_key>");
var assistantsClient = client.GetAssistantClient();

// Assistants are managed server-side
AIAgent agent = assistantsClient.AsAIAgent(
    instructions: "You are a data analysis assistant.",
    name: "DataHelper");

Console.WriteLine(await agent.RunAsync("Analyze trends in the uploaded data."));

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

Sugerencia

Consulte los ejemplos de .NET para obtener ejemplos completos de ejecución.

Uso del agente

Los tres tipos de cliente producen 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.

Installation

pip install agent-framework --pre

Configuración

Cada tipo de cliente usa diferentes variables de entorno:

Finalización del chat

OPENAI_API_KEY="your-openai-api-key"
OPENAI_CHAT_MODEL_ID="gpt-4o-mini"

Respuestas

OPENAI_API_KEY="your-openai-api-key"
OPENAI_RESPONSES_MODEL_ID="gpt-4o-mini"

Assistants

OPENAI_API_KEY="your-openai-api-key"
OPENAI_CHAT_MODEL_ID="gpt-4o-mini"

Cliente de finalización de chat

OpenAIChatClient usa la API de finalizaciones de chat, la opción más sencilla con amplia compatibilidad con los modelos.

import asyncio
from agent_framework.openai import OpenAIChatClient

async def main():
    agent = OpenAIChatClient().as_agent(
        name="HelpfulAssistant",
        instructions="You are a helpful assistant.",
    )
    result = await agent.run("Hello, how can you help me?")
    print(result)

asyncio.run(main())

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

Búsqueda web con finalización de chat

async def web_search_example():
    client = OpenAIChatClient()
    web_search = client.get_web_search_tool()

    agent = client.as_agent(
        name="SearchBot",
        instructions="You can search the web for current information.",
        tools=web_search,
    )
    result = await agent.run("What are the latest developments in AI?")
    print(result)

Cliente de respuestas

OpenAIResponsesClient utiliza la API de Respuestas, la opción más completa con herramientas alojadas.

import asyncio
from agent_framework.openai import OpenAIResponsesClient

async def main():
    agent = OpenAIResponsesClient().as_agent(
        name="FullFeaturedAgent",
        instructions="You are a helpful assistant with access to many tools.",
    )
    result = await agent.run("Write and run a Python script that calculates fibonacci numbers.")
    print(result)

asyncio.run(main())

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.

Herramientas hospedadas con el cliente de respuestas

El cliente de respuestas proporciona get_*_tool() métodos para cada tipo de herramienta hospedada:

async def hosted_tools_example():
    client = OpenAIResponsesClient()

    # Each tool is created via a client method
    code_interpreter = client.get_code_interpreter_tool()
    web_search = client.get_web_search_tool()
    file_search = client.get_file_search_tool(vector_store_ids=["vs_abc123"])
    mcp_tool = client.get_mcp_tool(
        name="GitHub",
        url="https://api.githubcopilot.com/mcp/",
        approval_mode="never_require",
    )

    agent = client.as_agent(
        name="PowerAgent",
        instructions="You have access to code execution, web search, files, and GitHub.",
        tools=[code_interpreter, web_search, file_search, mcp_tool],
    )
    result = await agent.run("Search the web for Python best practices, then write a summary.")
    print(result)

Cliente de asistentes

OpenAIAssistantProvider usa la API Assistants: agentes administrados por el servidor con intérprete de código integrado y búsqueda de archivos. El proveedor administra automáticamente el ciclo de vida del asistente.

import asyncio
from agent_framework.openai import OpenAIAssistantProvider
from openai import AsyncOpenAI

async def main():
    client = AsyncOpenAI()
    provider = OpenAIAssistantProvider(client)

    agent = await provider.create_agent(
        name="DataAnalyst",
        model="gpt-4o-mini",
        instructions="You analyze data using code execution.",
    )

    try:
        result = await agent.run("Calculate the first 20 prime numbers.")
        print(result)
    finally:
        await provider.delete_agent(agent.id)

asyncio.run(main())

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

Características comunes

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

Herramientas de funciones

from agent_framework import 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 = OpenAIResponsesClient().as_agent(
        instructions="You are a weather assistant.",
        tools=get_weather,
    )
    result = await agent.run("What's the weather in Tokyo?")
    print(result)

Conversaciones multiturno

async def thread_example():
    agent = OpenAIResponsesClient().as_agent(
        instructions="You are a helpful assistant.",
    )
    session = await 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"

Transmisión en línea

async def streaming_example():
    agent = OpenAIResponsesClient().as_agent(
        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()

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.

Pasos siguientes

Azure OpenAI

  • Last updated on