에이전트 프레임워크를 사용하여 에이전트 만들기 및 실행

이 자습서에서는 Azure OpenAI 채팅 완료 서비스를 기반으로 에이전트 프레임워크를 사용하여 에이전트를 만들고 실행하는 방법을 보여 줍니다.

중요합니다

에이전트 프레임워크는 다양한 유형의 에이전트를 지원합니다. 이 자습서에서는 채팅 완료 서비스를 기반으로 하는 에이전트를 사용하지만 다른 모든 에이전트 유형은 동일한 방식으로 실행됩니다. 다른 에이전트 유형 및 에이전트를 생성하는 방법에 대한 자세한 내용은 Agent Framework 사용자 가이드를 참조하세요.

필수 조건

시작하기 전에 다음과 같은 필수 구성 요소가 있는지 확인합니다.

• .NET 8.0 SDK 이상
• 구성된 Azure OpenAI 서비스 엔드포인트 및 배포
• Azure CLI 설치 및 인증(Azure 자격 증명 인증용)
• 사용자에게 Cognitive Services OpenAI User 또는 Cognitive Services OpenAI Contributor 역할이 Azure OpenAI 리소스에 부여되었습니다.

비고

Microsoft 에이전트 프레임워크는 적극적으로 지원되는 모든 .NET 버전에서 지원됩니다. 이 샘플에서는 .NET 8 SDK 이상 버전을 사용하는 것이 좋습니다.

중요합니다

이 자습서에서는 채팅 완료 서비스에 Azure OpenAI를 사용하지만 구현을 제공하는 IChatClient 모든 유추 서비스를 사용할 수 있습니다.

NuGet 패키지 설치

Azure OpenAI에서 Microsoft 에이전트 프레임워크를 사용하려면 다음 NuGet 패키지를 설치해야 합니다.

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

에이전트 만들기

• 먼저 Azure OpenAI 엔드포인트를 제공하고 필수 구성 요소 단계에서 Azure CLI로 인증할 때 사용한 것과 동일한 로그인을 사용하여 Azure OpenAI용 클라이언트를 만듭니다.
• 그런 다음 채팅 완료 서비스와 통신하기 위한 채팅 클라이언트를 가져옵니다. 여기서 사용할 특정 모델 배포도 지정합니다. 필수 구성 요소 단계에서 만든 배포 중 하나를 사용합니다.
• 마지막으로 에이전트에 대한 지침과 이름을 제공하여 에이전트를 만듭니다.

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.

이 자습서에서는 Azure OpenAI 채팅 완료 서비스를 기반으로 에이전트 프레임워크를 사용하여 에이전트를 만들고 실행하는 방법을 보여 줍니다.

중요합니다

에이전트 프레임워크는 다양한 유형의 에이전트를 지원합니다. 이 자습서에서는 채팅 완료 서비스를 기반으로 하는 에이전트를 사용하지만 다른 모든 에이전트 유형은 동일한 방식으로 실행됩니다. 다른 에이전트 유형 및 에이전트를 생성하는 방법에 대한 자세한 내용은 Agent Framework 사용자 가이드를 참조하세요.

필수 조건

시작하기 전에 다음과 같은 필수 구성 요소가 있는지 확인합니다.

• Python 3.10 이상
• 구성된 Azure OpenAI 서비스 엔드포인트 및 배포
• Azure CLI 설치 및 인증(Azure 자격 증명 인증용)
• 사용자에게 Cognitive Services OpenAI User 또는 Cognitive Services OpenAI Contributor 역할이 Azure OpenAI 리소스에 부여되었습니다.

중요합니다

이 자습서에서는 채팅 완료 서비스에 Azure OpenAI를 사용하지만 에이전트 프레임워크의 채팅 클라이언트 프로토콜과 호환되는 모든 유추 서비스를 사용할 수 있습니다.

Python 패키지 설치

Azure OpenAI에서 Microsoft 에이전트 프레임워크를 사용하려면 다음 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())

다음 단계

에이전트와 함께 이미지 사용