Condividi tramite

Creare ed eseguire un agente con Agent Framework

Questa esercitazione illustra come creare ed eseguire un agente con Agent Framework, basato sul servizio Completamento chat OpenAI di Azure.

Importante

Agent Framework supporta molti tipi diversi di agenti. Questo tutorial utilizza un agente basato su un servizio di completamento chat, mentre tutti gli altri tipi di agenti vengono eseguiti nello stesso modo. Per altre informazioni su altri tipi di agente e su come crearli, vedere la Guida per l'utente di Agent Framework.

Prerequisiti

Prima di iniziare, assicurarsi di avere i prerequisiti seguenti:

Annotazioni

Microsoft Agent Framework è supportato con tutte le versioni supportate attivamente di .NET. Ai fini di questo esempio, è consigliabile usare .NET 8 SDK o una versione successiva.

Importante

Questo tutorial usa Azure OpenAI per il servizio di completamento della chat, ma è possibile usare qualsiasi servizio di inferenza che forniscono un'implementazione di IChatClient.

Installare i pacchetti NuGet

Per usare Microsoft Agent Framework con Azure OpenAI, è necessario installare i pacchetti NuGet seguenti:

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

Creare l'agente

  • Creare prima di tutto un client per Azure OpenAI fornendo l'endpoint OpenAI di Azure e usando lo stesso account di accesso usato per l'autenticazione con l'interfaccia della riga di comando di Azure nel passaggio Prerequisiti .
  • Ottenere quindi un client di chat per comunicare con il servizio di completamento della chat, in cui si specifica anche la distribuzione del modello specifica da usare. Usare una delle distribuzioni create nel passaggio Prerequisiti .
  • Infine, creare l'agente, fornendo istruzioni e un nome per l'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");

Esecuzione dell'agente

Per eseguire l'agente, chiamare il RunAsync metodo nell'istanza dell'agente, fornendo l'input dell'utente. L'agente restituirà un oggetto AgentRunResponse, e chiamando .ToString() o .Text su questo oggetto risposta si ottiene il risultato testuale dall'agente.

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

Output di esempio:

Why did the pirate go to school?

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

Esecuzione dell'agente con streaming

Per eseguire l'agente con streaming, chiamare il metodo nell'istanza RunStreamingAsync dell'agente, fornendo l'input dell'utente. L'agente restituirà un flusso di oggetti AgentRunResponseUpdate e chiamando .ToString() o .Text su ogni oggetto di aggiornamento fornisce la parte del testo risultante contenuta in quell'aggiornamento.

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

Output di esempio:

Why
 did
 the
 pirate
 go
 to
 school
?


To
 improve
 his
 "
ar
rrrr
rr
tic
ulation
!"

Esecuzione dell'agente con ChatMessages

Anziché una stringa semplice, è anche possibile fornire uno o più oggetti ChatMessage ai metodi RunAsync e RunStreamingAsync.

Di seguito è riportato un esempio con un singolo messaggio utente:

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

Output di esempio:

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

Because he wanted to make a splash!

Di seguito è riportato un esempio con un messaggio di sistema e utente:

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]));

Output di esempio:

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.

Questa esercitazione illustra come creare ed eseguire un agente con Agent Framework, basato sul servizio Completamento chat OpenAI di Azure.

Importante

Agent Framework supporta molti tipi diversi di agenti. Questo tutorial utilizza un agente basato su un servizio di completamento chat, mentre tutti gli altri tipi di agenti vengono eseguiti nello stesso modo. Per altre informazioni su altri tipi di agente e su come crearli, vedere la Guida per l'utente di Agent Framework.

Prerequisiti

Prima di iniziare, assicurarsi di avere i prerequisiti seguenti:

Importante

Questa esercitazione usa Azure OpenAI per il servizio Completamento chat, ma è possibile usare qualsiasi servizio di inferenza compatibile con il protocollo client chat di Agent Framework.

Installare i pacchetti Python

Per usare Microsoft Agent Framework con Azure OpenAI, è necessario installare i pacchetti Python seguenti:

pip install agent-framework --pre

Creare l'agente

  • Creare prima di tutto un client di chat per comunicare con Azure OpenAI e usare lo stesso account di accesso usato per l'autenticazione con l'interfaccia della riga di comando di Azure nel passaggio Prerequisiti .
  • Creare quindi l'agente, fornendo istruzioni e un nome per l'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"
)

Esecuzione dell'agente

Per eseguire l'agente, chiamare il run metodo nell'istanza dell'agente, fornendo l'input dell'utente. L'agente restituirà un oggetto di risposta e l'accesso alla proprietà .text fornisce il risultato del testo dell'agente.

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

asyncio.run(main())

Esecuzione dell'agente con streaming

Per eseguire l'agente con streaming, chiamare il metodo nell'istanza run_stream dell'agente, fornendo l'input dell'utente. L'agente trasmetterà in streaming un elenco di oggetti di aggiornamento e accedere alla proprietà .text in ogni oggetto di aggiornamento fornisce la parte del risultato di testo contenuta in quell'aggiornamento.

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

Esecuzione dell'agente con un messaggio di chat

Anziché una stringa semplice, è anche possibile fornire uno o più oggetti ChatMessage ai metodi 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())

Passaggi successivi

Uso di immagini con un agente

  • Last updated on