Assistentes e Agentes do OpenAI

Introdução

Adicione os pacotes NuGet necessários ao seu projeto.

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

Criando um agente de assistentes do OpenAI

Como primeira etapa, você precisa criar um cliente para se conectar ao serviço OpenAI.

using System;
using Microsoft.Agents.AI;
using OpenAI;

OpenAIClient client = new OpenAIClient("<your_api_key>");

O OpenAI dá suporte a vários serviços que fornecem recursos de chamada de modelo. Para criar um agente baseado no Assistentes, usaremos o cliente Assistentes.

#pragma warning disable OPENAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates.
var assistantClient = client.GetAssistantClient();
#pragma warning restore OPENAI001

Para usar o serviço Assistentes openai, você precisa criar um recurso de assistente no serviço. Isso pode ser feito usando o SDK do OpenAI ou os auxiliares do Microsoft Agent Framework.

Usando o SDK do OpenAI

Crie um assistente e recupere-o como um AIAgent usando o cliente.

// Create a server-side assistant
var createResult = await assistantClient.CreateAssistantAsync(
    "gpt-4o-mini",
    new() { Name = "Joker", Instructions = "You are good at telling jokes." });

// Retrieve the assistant as an AIAgent
AIAgent agent1 = await assistantClient.GetAIAgentAsync(createResult.Value.Id);

// Invoke the agent and output the text result.
Console.WriteLine(await agent1.RunAsync("Tell me a joke about a pirate."));

Usando os auxiliares do Agent Framework

Você também pode criar e retornar um AIAgent em uma etapa:

AIAgent agent2 = await assistantClient.CreateAIAgentAsync(
    model: "gpt-4o-mini",
    name: "Joker",
    instructions: "You are good at telling jokes.");

Reutilizando assistentes do OpenAI

Você pode reutilizar assistentes OpenAI existentes recuperando-os usando suas IDs.

AIAgent agent3 = await assistantClient.GetAIAgentAsync("<agent-id>");

Usando o agente

O agente é um padrão AIAgent e dá suporte a todas as operações de agente padrão.

Consulte os tutoriais de introdução do Agente para obter mais informações sobre como executar e interagir com agentes.

Pré-requisitos

Instale o pacote do Microsoft Agent Framework.

pip install agent-framework --pre

Configuração

Variáveis de ambiente

Configure as variáveis de ambiente necessárias para autenticação OpenAI:

# Required for OpenAI API access
OPENAI_API_KEY="your-openai-api-key"
OPENAI_CHAT_MODEL_ID="gpt-4o-mini"  # or your preferred model

Como alternativa, você pode usar um .env arquivo na raiz do projeto:

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

Introdução

Importe as classes necessárias do Agent Framework:

import asyncio
from agent_framework import ChatAgent
from agent_framework.openai import OpenAIAssistantsClient

Criando um agente de assistentes do OpenAI

Criação básica de agente

A maneira mais simples de criar um agente é usando o OpenAIAssistantsClient que cria e gerencia automaticamente os assistentes:

async def basic_example():
    # Create an agent with automatic assistant creation and cleanup
    async with OpenAIAssistantsClient().create_agent(
        instructions="You are a helpful assistant.",
        name="MyAssistant"
    ) as agent:
        result = await agent.run("Hello, how are you?")
        print(result.text)

Usando a configuração explícita

Você pode fornecer uma configuração explícita em vez de depender de variáveis de ambiente:

async def explicit_config_example():
    async with OpenAIAssistantsClient(
        ai_model_id="gpt-4o-mini",
        api_key="your-api-key-here",
    ).create_agent(
        instructions="You are a helpful assistant.",
    ) as agent:
        result = await agent.run("What's the weather like?")
        print(result.text)

Usando um assistente existente

Você pode reutilizar os assistentes openai existentes fornecendo suas IDs:

from openai import AsyncOpenAI

async def existing_assistant_example():
    # Create OpenAI client directly
    client = AsyncOpenAI()

    # Create or get an existing assistant
    assistant = await client.beta.assistants.create(
        model="gpt-4o-mini",
        name="WeatherAssistant",
        instructions="You are a weather forecasting assistant."
    )

    try:
        # Use the existing assistant with Agent Framework
        async with ChatAgent(
            chat_client=OpenAIAssistantsClient(
                async_client=client,
                assistant_id=assistant.id
            ),
            instructions="You are a helpful weather agent.",
        ) as agent:
            result = await agent.run("What's the weather like in Seattle?")
            print(result.text)
    finally:
        # Clean up the assistant
        await client.beta.assistants.delete(assistant.id)

Recursos do agente

Ferramentas de Funções

Você pode equipar seu assistente com funções personalizadas:

from typing import Annotated
from pydantic import Field

def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")]
) -> str:
    """Get the weather for a given location."""
    return f"The weather in {location} is sunny with 25°C."

async def tools_example():
    async with ChatAgent(
        chat_client=OpenAIAssistantsClient(),
        instructions="You are a helpful weather assistant.",
        tools=get_weather,  # Provide tools to the agent
    ) as agent:
        result = await agent.run("What's the weather like in Tokyo?")
        print(result.text)

Interpretador de Código

Habilite o assistente para executar o código do Python:

from agent_framework import HostedCodeInterpreterTool

async def code_interpreter_example():
    async with ChatAgent(
        chat_client=OpenAIAssistantsClient(),
        instructions="You are a helpful assistant that can write and execute Python code.",
        tools=HostedCodeInterpreterTool(),
    ) as agent:
        result = await agent.run("Calculate the factorial of 100 using Python code.")
        print(result.text)

Respostas do streaming

Obtenha respostas conforme elas são geradas para uma melhor experiência do usuário:

async def streaming_example():
    async with OpenAIAssistantsClient().create_agent(
        instructions="You are a helpful assistant.",
    ) as agent:
        print("Assistant: ", end="", flush=True)
        async for chunk in agent.run_stream("Tell me a story about AI."):
            if chunk.text:
                print(chunk.text, end="", flush=True)
        print()  # New line after streaming is complete

Usando o agente

O agente é um padrão BaseAgent e dá suporte a todas as operações de agente padrão.

Consulte os tutoriais de introdução do Agente para obter mais informações sobre como executar e interagir com agentes.