다음을 통해 공유

방법: 채팅 완료 에이전트 (실험적)

  • 아티클

Warning

의미 체계 커널 에이전트 프레임워크는 아직 개발 중이며 변경될 수 있습니다.

개요

이 샘플에서는 GitHub API에 액세스하도록 플러그 인을 구성하고 GitHub 리포지토리에 대한 질문에 대답하기 위해 채팅 완료 에이전트에 템플릿화된 지침을 제공합니다. 이 방법은 코딩 프로세스의 핵심 부분을 밝게 하기 위해 단계별로 세분화됩니다. 작업의 일부로 에이전트는 응답 내에서 문서 인용을 제공합니다.

스트리밍은 에이전트의 응답을 전달하는 데 사용됩니다. 그러면 작업이 진행됨에 따라 실시간 업데이트가 제공됩니다.

시작하기

기능 코딩을 계속하기 전에 개발 환경이 완전히 설정되고 구성되었는지 확인합니다.

먼저 콘솔 프로젝트를 만듭니다. 그런 다음 필요한 모든 종속성을 사용할 수 있도록 다음 패키지 참조를 포함합니다.

명령줄에서 패키지 종속성을 추가하려면 다음 명령을 사용합니다 dotnet .

dotnet add package Azure.Identity
dotnet add package Microsoft.Extensions.Configuration
dotnet add package Microsoft.Extensions.Configuration.Binder
dotnet add package Microsoft.Extensions.Configuration.UserSecrets
dotnet add package Microsoft.Extensions.Configuration.EnvironmentVariables
dotnet add package Microsoft.SemanticKernel.Connectors.AzureOpenAI
dotnet add package Microsoft.SemanticKernel.Agents.Core --prerelease

Visual Studio에서 NuGet 패키지를 관리하는 경우 확인합니다 Include prerelease .

프로젝트 파일(.csproj)에는 다음 PackageReference 정의가 포함되어야 합니다.

  <ItemGroup>
    <PackageReference Include="Azure.Identity" Version="<stable>" />
    <PackageReference Include="Microsoft.Extensions.Configuration" Version="<stable>" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="<stable>" />
    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" Version="<stable>" />
    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="<stable>" />
    <PackageReference Include="Microsoft.SemanticKernel.Agents.Core" Version="<latest>" />
    <PackageReference Include="Microsoft.SemanticKernel.Connectors.AzureOpenAI" Version="<latest>" />
  </ItemGroup>

에이전트 프레임워크는 실험적이며 경고 표시 안 함이 필요합니다. 프로젝트 파일.csproj()의 속성으로 이 문제를 해결할 수 있습니다.

  <PropertyGroup>
    <NoWarn>$(NoWarn);CA2007;IDE1006;SKEXP0001;SKEXP0110;OPENAI001</NoWarn>
  </PropertyGroup>

또한 의미 체계 커널LearnResources 프로젝트에서 GitHub 플러그 인 및 모델(GitHubPlugin.cs및GitHubModels.cs)을 복사합니다. 프로젝트 폴더에 이러한 파일을 추가합니다.

먼저 스크립트(.py 파일) 및 샘플 리소스를 보관할 폴더를 만듭니다. 파일 맨 위에 .py 다음 가져오기를 포함합니다.

import asyncio
import os
import sys
from datetime import datetime

from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.connectors.ai.function_choice_behavior import FunctionChoiceBehavior
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion
from semantic_kernel.contents.chat_history import ChatHistory
from semantic_kernel.contents.chat_message_content import ChatMessageContent
from semantic_kernel.contents.utils.author_role import AuthorRole
from semantic_kernel.kernel import Kernel

# Adjust the sys.path so we can use the GitHubPlugin and GitHubSettings classes
# This is so we can run the code from the samples/learn_resources/agent_docs directory
# If you are running code from your own project, you may not need need to do this.
sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))

from plugins.GithubPlugin.github import GitHubPlugin, GitHubSettings  # noqa: E402

또한 의미 체계 커널LearnResources 프로젝트에서 GitHub 플러그 인 및 모델(github.py)을 복사합니다. 프로젝트 폴더에 이러한 파일을 추가합니다.

에이전트는 현재 Java에서 사용할 수 없습니다.

구성

이 샘플에서는 원격 서비스에 연결하기 위해 구성 설정이 필요합니다. Open AI 또는 Azure Open AI 및 GitHub에 대한 설정을 정의해야 합니다.

참고: GitHub 개인용 액세스 토큰에 대한 자세한 내용은 다음 을 참조하세요. 개인 액세스 토큰 관리.

# Open AI
dotnet user-secrets set "OpenAISettings:ApiKey" "<api-key>"
dotnet user-secrets set "OpenAISettings:ChatModel" "gpt-4o"

# Azure Open AI
dotnet user-secrets set "AzureOpenAISettings:ApiKey" "<api-key>" # Not required if using token-credential
dotnet user-secrets set "AzureOpenAISettings:Endpoint" "<model-endpoint>"
dotnet user-secrets set "AzureOpenAISettings:ChatModelDeployment" "gpt-4o"

# GitHub
dotnet user-secrets set "GitHubSettings:BaseUrl" "https://api.github.com"
dotnet user-secrets set "GitHubSettings:Token" "<personal access token>"

다음 클래스는 모든 에이전트 예제에서 사용됩니다. 적절한 기능을 보장하려면 프로젝트에 포함해야 합니다. 이 클래스는 다음 예제의 기본 구성 요소 역할을 합니다.

using System.Reflection;
using Microsoft.Extensions.Configuration;

namespace AgentsSample;

public class Settings
{
    private readonly IConfigurationRoot configRoot;

    private AzureOpenAISettings azureOpenAI;
    private OpenAISettings openAI;

    public AzureOpenAISettings AzureOpenAI => this.azureOpenAI ??= this.GetSettings<Settings.AzureOpenAISettings>();
    public OpenAISettings OpenAI => this.openAI ??= this.GetSettings<Settings.OpenAISettings>();

    public class OpenAISettings
    {
        public string ChatModel { get; set; } = string.Empty;
        public string ApiKey { get; set; } = string.Empty;
    }

    public class AzureOpenAISettings
    {
        public string ChatModelDeployment { get; set; } = string.Empty;
        public string Endpoint { get; set; } = string.Empty;
        public string ApiKey { get; set; } = string.Empty;
    }

    public TSettings GetSettings<TSettings>() =>
        this.configRoot.GetRequiredSection(typeof(TSettings).Name).Get<TSettings>()!;

    public Settings()
    {
        this.configRoot =
            new ConfigurationBuilder()
                .AddEnvironmentVariables()
                .AddUserSecrets(Assembly.GetExecutingAssembly(), optional: true)
                .Build();
    }
}

샘플 코드를 실행하는 적절한 구성을 시작하는 가장 빠른 방법은 프로젝트의 루트(스크립트가 실행되는 위치)에 파일을 만드는 .env 것입니다.

Azure OpenAI 또는 OpenAI에 대해 파일에서 다음 설정을 구성합니다 .env .

AZURE_OPENAI_API_KEY="..."
AZURE_OPENAI_ENDPOINT="https://..."
AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="..."
AZURE_OPENAI_API_VERSION="..."

OPENAI_API_KEY="sk-..."
OPENAI_ORG_ID=""
OPENAI_CHAT_MODEL_ID=""

구성되면 각 AI 서비스 클래스는 필요한 변수를 선택하고 인스턴스화 중에 사용합니다.

에이전트는 현재 Java에서 사용할 수 없습니다.

코딩

이 샘플의 코딩 프로세스는 다음과 같습니다.

  1. 설치 - 설정 및 플러그 인 초기화
  2. 에이전트 정의 - 템플릿화된 지침 및 플러그 인을 사용하여 채팅 완료 에이전트를 만듭니다.
  3. 채팅 루프 - 사용자/에이전트 상호 작용을 구동하는 루프를 작성합니다.

전체 예제 코드는 최종 섹션에 제공됩니다. 전체 구현은 해당 섹션을 참조하세요.

설정

채팅 완료 에이전트를 만들기 전에 구성 설정, 플러그 인 및 커널을 초기화해야 합니다.

이전 구성 섹션에서 참조된 클래스를 초기화 Settings 합니다.

Settings settings = new();

에이전트는 현재 Java에서 사용할 수 없습니다.

해당 설정을 사용하여 플러그 인을 초기화합니다.

여기서는 진행률을 나타내는 메시지가 표시됩니다.

Console.WriteLine("Initialize plugins...");
GitHubSettings githubSettings = settings.GetSettings<GitHubSettings>();
GitHubPlugin githubPlugin = new(githubSettings);

gh_settings = GitHubSettings(
    token="<PAT value>"
)
kernel.add_plugin(GitHubPlugin(settings=gh_settings), plugin_name="github")

에이전트는 현재 Java에서 사용할 수 없습니다.

이제 이전에 만든 인스턴스와 인스턴스를 IChatCompletionService GitHubPlugin 초기화 Kernel 합니다.

Console.WriteLine("Creating kernel...");
IKernelBuilder builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
    settings.AzureOpenAI.ChatModelDeployment,
    settings.AzureOpenAI.Endpoint,
    new AzureCliCredential());

builder.Plugins.AddFromObject(githubPlugin);

Kernel kernel = builder.Build();

kernel = Kernel()

# Add the AzureChatCompletion AI Service to the Kernel
service_id = "agent"
kernel.add_service(AzureChatCompletion(service_id=service_id))

settings = kernel.get_prompt_execution_settings_from_service_id(service_id=service_id)
# Configure the function choice behavior to auto invoke kernel functions
settings.function_choice_behavior = FunctionChoiceBehavior.Auto()

에이전트는 현재 Java에서 사용할 수 없습니다.

에이전트 정의

마지막으로 지침, 연결된 커널 및 기본 인수 및 실행 설정을 사용하여 채팅 완료 에이전트 를 인스턴스화할 준비가 완료되었습니다. 이 경우 플러그 인 함수를 자동으로 실행하려고 합니다.

Console.WriteLine("Defining agent...");
ChatCompletionAgent agent =
    new()
    {
        Name = "SampleAssistantAgent",
        Instructions =
            """
            You are an agent designed to query and retrieve information from a single GitHub repository in a read-only manner.
            You are also able to access the profile of the active user.

            Use the current date and time to provide up-to-date details or time-sensitive responses.

            The repository you are querying is a public repository with the following name: {{$repository}}

            The current date and time is: {{$now}}. 
            """,
        Kernel = kernel,
        Arguments =
            new KernelArguments(new AzureOpenAIPromptExecutionSettings() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto() })
            {
                { "repository", "microsoft/semantic-kernel" }
            }
    };

Console.WriteLine("Ready!");

agent = ChatCompletionAgent(
    service_id="agent",
    kernel=kernel,
    name="SampleAssistantAgent",
    instructions=f"""
        You are an agent designed to query and retrieve information from a single GitHub repository in a read-only 
        manner.
        You are also able to access the profile of the active user.

        Use the current date and time to provide up-to-date details or time-sensitive responses.

        The repository you are querying is a public repository with the following name: microsoft/semantic-kernel

        The current date and time is: {current_time}. 
        """,
    execution_settings=settings,
)

에이전트는 현재 Java에서 사용할 수 없습니다.

채팅 루프

마침내 사용자와 에이전트 간의 상호 작용을 조정할 수 있습니다. 먼저 채팅 기록 개체를 만들어 대화 상태를 유지하고 빈 루프를 만듭니다.

ChatHistory history = [];
bool isComplete = false;
do
{
    // processing logic here
} while (!isComplete);

history = ChatHistory()
is_complete: bool = False
while not is_complete:
    # processing logic here

에이전트는 현재 Java에서 사용할 수 없습니다.

이제 이전 루프 내에서 사용자 입력을 캡처해 보겠습니다. 이 경우 빈 입력은 무시되고 용어 EXIT 는 대화가 완료되었음을 나타냅니다. 유효한 입력이 채팅 기록에 사용자 메시지로 추가됩니다.

Console.WriteLine();
Console.Write("> ");
string input = Console.ReadLine();
if (string.IsNullOrWhiteSpace(input))
{
    continue;
}
if (input.Trim().Equals("EXIT", StringComparison.OrdinalIgnoreCase))
{
    isComplete = true;
    break;
}

history.Add(new ChatMessageContent(AuthorRole.User, input));

Console.WriteLine();

user_input = input("User:> ")
if not user_input:
    continue

if user_input.lower() == "exit":
    is_complete = True
    break

history.add_message(ChatMessageContent(role=AuthorRole.USER, content=user_input))

에이전트는 현재 Java에서 사용할 수 없습니다.

사용자 입력에 대한 에이전트 응답을 생성하려면 인수를 사용하여 에이전트를 호출하여 현재 날짜 및 시간을 지정하는 최종 템플릿 매개 변수를 제공합니다.

그런 다음 에이전트 응답이 사용자에게 표시됩니다.

DateTime now = DateTime.Now;
KernelArguments arguments =
    new()
    {
        { "now", $"{now.ToShortDateString()} {now.ToShortTimeString()}" }
    };
await foreach (ChatMessageContent response in agent.InvokeAsync(history, arguments))
{
    Console.WriteLine($"{response.Content}");
}

서비스 예정

에이전트는 현재 Java에서 사용할 수 없습니다.

최종

모든 단계를 함께 가져오면 이 예제의 최종 코드가 있습니다. 전체 구현은 아래에 제공됩니다.

using System;
using System.Threading.Tasks;
using Azure.Identity;
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;
using Microsoft.SemanticKernel.ChatCompletion;
using Microsoft.SemanticKernel.Connectors.AzureOpenAI;
using Plugins;

namespace AgentsSample;

public static class Program
{
    public static async Task Main()
    {
        // Load configuration from environment variables or user secrets.
        Settings settings = new();

        Console.WriteLine("Initialize plugins...");
        GitHubSettings githubSettings = settings.GetSettings<GitHubSettings>();
        GitHubPlugin githubPlugin = new(githubSettings);

        Console.WriteLine("Creating kernel...");
        IKernelBuilder builder = Kernel.CreateBuilder();

        builder.AddAzureOpenAIChatCompletion(
            settings.AzureOpenAI.ChatModelDeployment,
            settings.AzureOpenAI.Endpoint,
            new AzureCliCredential());

        builder.Plugins.AddFromObject(githubPlugin);

        Kernel kernel = builder.Build();

        Console.WriteLine("Defining agent...");
        ChatCompletionAgent agent =
            new()
            {
                Name = "SampleAssistantAgent",
                Instructions =
                        """
                        You are an agent designed to query and retrieve information from a single GitHub repository in a read-only manner.
                        You are also able to access the profile of the active user.

                        Use the current date and time to provide up-to-date details or time-sensitive responses.

                        The repository you are querying is a public repository with the following name: {{$repository}}

                        The current date and time is: {{$now}}. 
                        """,
                Kernel = kernel,
                Arguments =
                    new KernelArguments(new AzureOpenAIPromptExecutionSettings() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto() })
                    {
                        { "repository", "microsoft/semantic-kernel" }
                    }
            };

        Console.WriteLine("Ready!");

        ChatHistory history = [];
        bool isComplete = false;
        do
        {
            Console.WriteLine();
            Console.Write("> ");
            string input = Console.ReadLine();
            if (string.IsNullOrWhiteSpace(input))
            {
                continue;
            }
            if (input.Trim().Equals("EXIT", StringComparison.OrdinalIgnoreCase))
            {
                isComplete = true;
                break;
            }

            history.Add(new ChatMessageContent(AuthorRole.User, input));

            Console.WriteLine();

            DateTime now = DateTime.Now;
            KernelArguments arguments =
                new()
                {
                    { "now", $"{now.ToShortDateString()} {now.ToShortTimeString()}" }
                };
            await foreach (ChatMessageContent response in agent.InvokeAsync(history, arguments))
            {
                // Display response.
                Console.WriteLine($"{response.Content}");
            }

        } while (!isComplete);
    }
}

import asyncio
import os
import sys
from datetime import datetime

from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.connectors.ai.function_choice_behavior import FunctionChoiceBehavior
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion
from semantic_kernel.contents.chat_history import ChatHistory
from semantic_kernel.contents.chat_message_content import ChatMessageContent
from semantic_kernel.contents.utils.author_role import AuthorRole
from semantic_kernel.kernel import Kernel

# Adjust the sys.path so we can use the GitHubPlugin and GitHubSettings classes
# This is so we can run the code from the samples/learn_resources/agent_docs directory
# If you are running code from your own project, you may not need need to do this.
sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))

from plugins.GithubPlugin.github import GitHubPlugin, GitHubSettings  # noqa: E402

###################################################################
# The following sample demonstrates how to create a simple,       #
# ChatCompletionAgent to use a GitHub plugin to interact          #
# with the GitHub API.                                            #
###################################################################


async def main():
    kernel = Kernel()

    # Add the AzureChatCompletion AI Service to the Kernel
    service_id = "agent"
    kernel.add_service(AzureChatCompletion(service_id=service_id))

    settings = kernel.get_prompt_execution_settings_from_service_id(service_id=service_id)
    # Configure the function choice behavior to auto invoke kernel functions
    settings.function_choice_behavior = FunctionChoiceBehavior.Auto()

    # Set your GitHub Personal Access Token (PAT) value here
    gh_settings = GitHubSettings(token="<PAT value>")
    kernel.add_plugin(plugin=GitHubPlugin(gh_settings), plugin_name="GithubPlugin")

    current_time = datetime.now().isoformat()

    # Create the agent
    agent = ChatCompletionAgent(
        service_id="agent",
        kernel=kernel,
        name="SampleAssistantAgent",
        instructions=f"""
            You are an agent designed to query and retrieve information from a single GitHub repository in a read-only 
            manner.
            You are also able to access the profile of the active user.

            Use the current date and time to provide up-to-date details or time-sensitive responses.

            The repository you are querying is a public repository with the following name: microsoft/semantic-kernel

            The current date and time is: {current_time}. 
            """,
        execution_settings=settings,
    )

    history = ChatHistory()
    is_complete: bool = False
    while not is_complete:
        user_input = input("User:> ")
        if not user_input:
            continue

        if user_input.lower() == "exit":
            is_complete = True
            break

        history.add_message(ChatMessageContent(role=AuthorRole.USER, content=user_input))

        async for response in agent.invoke(history=history):
            print(f"{response.content}")


if __name__ == "__main__":
    asyncio.run(main())

에이전트는 현재 Java에서 사용할 수 없습니다.

방법: AI 도우미 에이전트 코드 인터프리터 열기