方法: Chat 完了エージェント (試験段階)
警告
Semantic Kernel Agent Framework はまだ開発中であり、変更される可能性があります。
概要
このサンプルでは、GitHub API にアクセスするためのプラグインの構成について説明し、テンプレート化された手順を Chat Completion Agent に提供してGitHub リポジトリに関する質問に回答します。 このアプローチは、コーディング プロセスの重要な部分を明るくするために、段階的に分割されます。 タスクの一環として、エージェントは応答内でドキュメントの引用文献を提供します。
ストリーミングは、エージェントの応答を配信するために使用されます。 これにより、タスクの進行に合ったリアルタイムの更新が提供されます。
はじめに
機能のコーディングに進む前に、開発環境が完全に設定および構成されていることを確認してください。
まず、 Console プロジェクトを作成します。 次に、次のパッケージ参照を含め、必要なすべての依存関係を使用できるようにします。
コマンド ラインからパッケージの依存関係を追加するには、 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>
Agent Framework は試験段階であり、警告の抑制が必要です。 これは、プロジェクト ファイル内のプロパティとして対処できます (.csproj)。
<PropertyGroup>
<NoWarn>$(NoWarn);CA2007;IDE1006;SKEXP0001;SKEXP0110;OPENAI001</NoWarn>
</PropertyGroup>
さらに、GitHub プラグインとモデル (GitHubPlugin.cs と GitHubModels.cs) を Semantic KernelLearnResources Project からコピーします。 これらのファイルをプロジェクト フォルダーに追加します。
まず、スクリプト (.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
さらに、GitHub プラグインとモデル (github.py) を Semantic KernelLearnResources Project からコピーします。 これらのファイルをプロジェクト フォルダーに追加します。
現在、エージェントは Java では使用できません。
構成
このサンプルでは、リモート サービスに接続するための構成設定が必要です。 Open AIまたはazure Open AIの設定と、GitHubの設定を定義する必要があります。
注: GitHub Personal アクセス トークンの詳細については個人用アクセス トークンの管理を参照してください。
# 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 では使用できません。
コーディング
このサンプルのコーディング プロセスには、次のものが含まれます。
- セットアップ - 設定とプラグインの初期化。
- エージェント定義 - テンプレート化された命令とプラグインを使用してChat 完了エージェントを作成します。
- Chat ループ - ユーザー/エージェントの対話を促進するループを記述します。
完全なコード例については、「 Final 」セクションを参照してください。 完全な実装については、そのセクションを参照してください。
セットアップ
Chat 完了エージェントを作成する前に、構成設定、プラグイン、および Kernel を初期化する必要があります。
前の Configuration セクションで参照されている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 では使用できません。
エージェント定義
最後に、Instructions、関連付けられた Kernel、および既定の Arguments Execution 設定を使用して、Chat Completion Agent をインスタンス化する準備ができました。 この場合、プラグイン関数を自動的に実行したいと考えています。
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 では使用できません。
Chat ループ
最後に、ユーザーと Agent の間の相互作用を調整できます。 まず、 Chat History オブジェクトを作成して会話の状態を維持し、空のループを作成します。
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 という用語は会話が完了したことを通知します。 有効な入力は、User メッセージとして Chat History に追加されます。
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 では使用できません。
ユーザー入力に対する Agent 応答を生成するには、 Arguments を使用してエージェントを呼び出し、現在の日時を指定する最終的なテンプレート パラメーターを指定します。
その後、 Agent 応答がユーザーに表示されます。
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 では使用できません。