Partilhar via

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.

Importante

O Agent Framework suporta muitos tipos diferentes de agentes. Este tutorial usa um agente baseado em um serviço de Conclusão de Chat, mas todos os outros tipos de agente são executados da mesma maneira. Para obter mais informações sobre outros tipos de agente e como construí-los, consulte o guia do usuário do Agent Framework.

Pré-requisitos

Antes de começar, certifique-se de ter os seguintes pré-requisitos:

Observação

O Microsoft Agent Framework é suportado com todas as versões ativamente suportadas do .NET. Para os fins deste exemplo, recomendamos o SDK do .NET 8 ou uma versão posterior.

Importante

Este tutorial usa o Azure OpenAI para o serviço de Conclusão de Chat, mas você pode usar qualquer serviço de inferência que forneça uma IChatClient implementação.

Instalar 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 ponto de extremidade do Azure OpenAI e usando o mesmo logon que você usou ao 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 completamento de chat, onde também se especifica a implantação do modelo específico a ser utilizado. Use uma das implantações que você criou na etapa Pré-requisitos .
  • Finalmente, 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, ao chamar .ToString() ou .Text neste objeto de resposta, fornecerá o resultado de 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 transmissão contínua

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á uma série de objetos AgentRunResponseUpdate, e chamar .ToString() ou .Text em cada objeto de atualização fornece 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 string simples, você também pode fornecer um ou mais ChatMessage objetos para os 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 mensagem do 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.

Importante

O Agent Framework suporta muitos tipos diferentes de agentes. Este tutorial usa um agente baseado em um serviço de Conclusão de Chat, mas todos os outros tipos de agente são executados da mesma maneira. Para obter mais informações sobre outros tipos de agente e como construí-los, consulte o guia do usuário do Agent Framework.

Pré-requisitos

Antes de começar, certifique-se de ter os seguintes pré-requisitos:

Importante

Este tutorial usa o Azure OpenAI para o serviço de Conclusão de Chat, mas você pode usar qualquer serviço de inferência compatível com o protocolo de cliente de chat do Agent Framework.

Instalar pacotes Python

Para usar o Microsoft Agent Framework com o Azure OpenAI, você precisa instalar os seguintes pacotes 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 que você usou 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 o acesso à propriedade .text fornecerá 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 transmissão contínua

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 o acesso à .text propriedade 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 ChatMessage

Em vez de uma string simples, você também pode fornecer um ou mais ChatMessage objetos para os 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())

Próximos passos

Usando imagens com um agente

  • Last updated on