Criar e executar um agente com o Agent Framework

Este tutorial mostra como criar e executar um agente com o Agent Framework, com base no serviço de Conclusão de Chat do Azure OpenAI.

Pré-requisitos

Antes de começar, verifique se de que tem os seguintes pré-requisitos:

• SDK do .NET 8.0 ou posterior
• Ponto de extremidade do serviço Azure OpenAI e implantação configurada
• CLI do Azure instalada e autenticada (para autenticação de credenciais do Azure)
• O usuário possui as funções Cognitive Services OpenAI User ou Cognitive Services OpenAI Contributor para o recurso Azure OpenAI.

Instalar os pacotes NuGet

Para usar o Microsoft Agent Framework com o Azure OpenAI, você precisa instalar os seguintes pacotes NuGet:

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

Criar o agente

• Primeiro, crie um cliente para o Azure OpenAI fornecendo o endpoint do Azure OpenAI e usando o mesmo login que você usou ao se autenticar com a CLI do Azure na etapa Pré-requisitos.
• Em seguida, obtenha um cliente de chat para se comunicar com o serviço de conclusão de chat, onde você também especifica o desdobramento de modelo específico a ser usado. Use uma das implantações que você criou na etapa Pré-requisitos .
• Por fim, crie o agente, fornecendo instruções e um nome para o agente.

using System;
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using OpenAI;

AIAgent agent = new AzureOpenAIClient(
    new Uri("https://<myresource>.openai.azure.com"),
    new AzureCliCredential())
        .GetChatClient("gpt-4o-mini")
        .CreateAIAgent(instructions: "You are good at telling jokes.", name: "Joker");

Executando o agente

Para executar o agente, chame o RunAsync método na instância do agente, fornecendo a entrada do usuário. O agente retornará um AgentRunResponse objeto e a chamada .ToString() ou .Text neste objeto de resposta fornecerá o resultado do texto do agente.

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

Saída de exemplo:

Why did the pirate go to school?

Because he wanted to improve his "arrr-ticulation"! 🏴‍☠️

Executando o agente com streaming

Para executar o agente com streaming, chame o RunStreamingAsync método na instância do agente, fornecendo a entrada do usuário. O agente retornará um fluxo de objetos AgentRunResponseUpdate, e chamar .ToString() ou .Text para cada objeto de atualização fornecerá a parte do resultado do texto contido nessa atualização.

await foreach (var update in agent.RunStreamingAsync("Tell me a joke about a pirate."))
{
    Console.WriteLine(update);
}

Saída de exemplo:

Why
 did
 the
 pirate
 go
 to
 school
?


To
 improve
 his
 "
ar
rrrr
rr
tic
ulation
!"

Executando o agente com ChatMessages

Em vez de uma cadeia de caracteres simples, você também pode fornecer um ou mais objetos ChatMessage aos métodos RunAsync e RunStreamingAsync.

Aqui está um exemplo com uma única mensagem de usuário:

ChatMessage message = new(ChatRole.User, [
    new TextContent("Tell me a joke about this image?"),
    new UriContent("https://upload.wikimedia.org/wikipedia/commons/1/11/Joseph_Grimaldi.jpg", "image/jpeg")
]);

Console.WriteLine(await agent.RunAsync(message));

Saída de exemplo:

Why did the clown bring a bottle of sparkling water to the show?

Because he wanted to make a splash!

Aqui está um exemplo com um sistema e uma mensagem de usuário:

ChatMessage systemMessage = new(
    ChatRole.System,
    """
    If the user asks you to tell a joke, refuse to do so, explaining that you are not a clown.
    Offer the user an interesting fact instead.
    """);
ChatMessage userMessage = new(ChatRole.User, "Tell me a joke about a pirate.");

Console.WriteLine(await agent.RunAsync([systemMessage, userMessage]));

Saída de exemplo:

I'm not a clown, but I can share an interesting fact! Did you know that pirates often revised the Jolly Roger flag? Depending on the pirate captain, it could feature different symbols like skulls, bones, or hourglasses, each representing their unique approach to piracy.

Este tutorial mostra como criar e executar um agente com o Agent Framework, com base no serviço de Conclusão de Chat do Azure OpenAI.

Pré-requisitos

Antes de começar, verifique se de que tem os seguintes pré-requisitos:

• Python 3.10 ou posterior
• Ponto de extremidade do serviço Azure OpenAI e implantação configurada
• CLI do Azure instalada e autenticada (para autenticação de credenciais do Azure)
• O usuário possui as funções Cognitive Services OpenAI User ou Cognitive Services OpenAI Contributor para o recurso Azure OpenAI.

Instalar pacotes do Python

Para usar o Microsoft Agent Framework com o Azure OpenAI, você precisa instalar os seguintes pacotes do Python:

pip install agent-framework --pre

Criar o agente

• Primeiro, crie um cliente de chat para se comunicar com o Azure OpenAI e use o mesmo logon usado ao autenticar com a CLI do Azure na etapa Pré-requisitos .
• Em seguida, crie o agente, fornecendo instruções e um nome para o agente.

import asyncio
from agent_framework.azure import AzureOpenAIChatClient
from azure.identity import AzureCliCredential

agent = AzureOpenAIChatClient(credential=AzureCliCredential()).create_agent(
    instructions="You are good at telling jokes.",
    name="Joker"
)

Executando o agente

Para executar o agente, chame o run método na instância do agente, fornecendo a entrada do usuário. O agente retornará um objeto de resposta e, ao acessar a propriedade .text, obtém-se o resultado de texto do agente.

async def main():
    result = await agent.run("Tell me a joke about a pirate.")
    print(result.text)

asyncio.run(main())

Executando o agente com streaming

Para executar o agente com streaming, chame o run_stream método na instância do agente, fornecendo a entrada do usuário. O agente transmitirá uma lista de objetos de atualização, e acessando a propriedade .text em cada objeto de atualização, fornece a parte do resultado de texto contido nessa atualização.

async def main():
    async for update in agent.run_stream("Tell me a joke about a pirate."):
        if update.text:
            print(update.text, end="", flush=True)
    print()  # New line after streaming is complete

asyncio.run(main())

Executando o agente com uma Mensagem de Chat

Em vez de uma cadeia de caracteres simples, você também pode fornecer um ou mais objetos ChatMessage aos métodos run e run_stream.

from agent_framework import ChatMessage, TextContent, UriContent, Role

message = ChatMessage(
    role=Role.USER,
    contents=[
        TextContent(text="Tell me a joke about this image?"),
        UriContent(uri="https://samplesite.org/clown.jpg", media_type="image/jpeg")
    ]
)

async def main():
    result = await agent.run(message)
    print(result.text)

asyncio.run(main())