Создание и запуск агента с помощью Agent Framework

В этом руководстве показано, как создать и запустить агент с помощью Agent Framework на основе службы завершения чата Azure OpenAI.

Это важно

Agent Framework поддерживает множество различных типов агентов. В этом руководстве используется агент, основанный на сервисе завершения чата, но все остальные типы агентов выполняются так же. Дополнительные сведения о других типах агентов и их создании см. в руководстве пользователя Agent Framework.

Предпосылки

Перед началом работы убедитесь, что у вас есть следующие предварительные требования:

• Пакет SDK для .NET 8.0 или более поздней версии
• Конечная точка и развертывание службы Azure OpenAI настроены
• Установленный и прошедший проверку подлинности Azure CLI (для проверки подлинности учетных данных Azure)
• У пользователя есть роли Cognitive Services OpenAI User или Cognitive Services OpenAI Contributor для ресурса Azure OpenAI.

Замечание

Microsoft Agent Framework поддерживается всеми активно поддерживаемыми версиями .NET. В целях этого примера рекомендуется использовать пакет SDK для .NET 8 или более позднюю версию.

Это важно

В этом руководстве используется Azure OpenAI для службы завершения чата, но вы можете использовать любую службу вывода, которая предоставляет IChatClient реализацию.

Установка пакетов Nuget

Чтобы использовать Microsoft Agent Framework с Azure OpenAI, необходимо установить следующие пакеты NuGet:

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

Создать агента

• Сначала создайте клиент для Azure OpenAI, предоставив конечную точку Azure OpenAI и используя то же имя входа, что и при проверке подлинности с помощью Azure CLI на шаге предварительных требований .
• Затем получите чат-клиент для взаимодействия с сервисом завершения чата, в котором также указываете развертывание используемой конкретной модели. Используйте одно из развертываний, созданных на шаге предварительных требований .
• Наконец, создайте агент, указав инструкции и имя агента.

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

Запуск агента

Чтобы запустить агент, вызовите RunAsync метод в экземпляре агента, предоставив пользователю входные данные. Агент вернет AgentRunResponse объект, и вызов .ToString() или .Text на этом объекте ответа предоставит текстовый результат от агента.

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

Образец вывода:

Why did the pirate go to school?

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

Запуск агента с потоковой передачей

Чтобы запустить агент с потоковой передачей, вызовите RunStreamingAsync метод в экземпляре агента, предоставив пользователю входные данные. Агент вернет поток AgentRunResponseUpdate объектов, и вызов .ToString() или .Text для каждого объекта обновления предоставляет часть текстового результата, содержащегося в этом обновлении.

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

Образец вывода:

Why
 did
 the
 pirate
 go
 to
 school
?


To
 improve
 his
 "
ar
rrrr
rr
tic
ulation
!"

Запуск агента с помощью ChatMessages

Вместо простой строки можно предоставить один или несколько объектов ChatMessage как для методов RunAsync, так и для методов RunStreamingAsync.

Ниже приведен пример с одним сообщением пользователя:

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

Образец вывода:

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

Because he wanted to make a splash!

Ниже приведен пример с сообщением системы и пользователя:

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

Образец вывода:

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.

В этом руководстве показано, как создать и запустить агент с помощью Agent Framework на основе службы завершения чата Azure OpenAI.

Это важно

Agent Framework поддерживает множество различных типов агентов. В этом руководстве используется агент, основанный на сервисе завершения чата, но все остальные типы агентов выполняются так же. Дополнительные сведения о других типах агентов и их создании см. в руководстве пользователя Agent Framework.

Предпосылки

Перед началом работы убедитесь, что у вас есть следующие предварительные требования:

• Python 3.10 или более поздней версии
• Конечная точка и развертывание службы Azure OpenAI настроены
• Установленный и прошедший проверку подлинности Azure CLI (для проверки подлинности учетных данных Azure)
• У пользователя есть роли Cognitive Services OpenAI User или Cognitive Services OpenAI Contributor для ресурса Azure OpenAI.

Это важно

В этом руководстве используется Azure OpenAI для службы завершения чата, но вы можете использовать любую службу вывода, совместимую с клиентским протоколом чата Agent Framework.

Установка пакетов Python

Чтобы использовать Microsoft Agent Framework с Azure OpenAI, необходимо установить следующие пакеты Python:

pip install agent-framework --pre

Создать агента

• Сначала создайте клиент чата для взаимодействия с Azure OpenAI и используйте то же имя входа, что и при проверке подлинности с помощью Azure CLI на шаге предварительных требований .
• Затем создайте агент, указав ему инструкции и имя.

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

Запуск агента

Чтобы запустить агент, вызовите run метод в экземпляре агента, предоставив пользователю входные данные. Агент вернет объект ответа, и доступ к свойству производится пользователем, что позволяет получить .text текстовый результат от агента.

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

asyncio.run(main())

Запуск агента с потоковой передачей

Чтобы запустить агент с потоковой передачей, вызовите run_stream метод в экземпляре агента, предоставив пользователю входные данные. Агент будет передавать список объектов обновления, а доступ к .text свойству для каждого объекта обновления предоставляет часть текстового результата, содержащегося в этом обновлении.

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

Запуск агента с помощью ChatMessage

Вместо простой строки можно предоставить один или несколько объектов ChatMessage как для методов run, так и для методов 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())

Дальнейшие шаги

Использование изображений с агентом