セマンティックカーネルプラグインを使用したエージェントの構成

重要

この機能はリリース候補段階にあります。この段階の機能はほぼ完全で一般的に安定していますが、完全な一般提供に到達する前に、小さな改良や最適化が行われる可能性があります。

セマンティックカーネルの関数とプラグイン

関数呼び出しは、開発者がカスタム機能を追加し、AI アプリケーションの機能を拡張できる強力なツールです。セマンティックカーネルプラグインアーキテクチャは、関数呼び出しをサポートする柔軟なフレームワークを提供します。 Agentの場合、プラグインと関数呼び出しの統合は、この基本的なセマンティックカーネル機能に基づいて構築されます。

構成後、エージェントは、 Agent Frameworkの外部で使用する場合と同様に、使用可能な関数を呼び出すタイミングと方法を選択します。

ヒント

API リファレンス:

ヒント

API リファレンス:

ヒント

API リファレンス:

エージェントへのプラグインの追加

で使用可能なすべてのAgentは、それぞれのKernel インスタンス内で管理されます。このセットアップにより、各 Agent は、その特定のロールに基づいて個別の機能にアクセスできます。

プラグインは、Kernelが作成される前または後に、Agentに追加できます。プラグインを初期化するプロセスは、セマンティックカーネルの実装に使用されるのと同じパターンに従い、AI 機能の管理における一貫性と使いやすさを実現します。

注

ChatCompletionAgentの場合、関数呼び出しモードを明示的に有効にする必要があります。 OpenAIAssistant エージェントは常に自動関数呼び出しに基づいています。

// Factory method to produce an agent with a specific role.
// Could be incorporated into DI initialization.
ChatCompletionAgent CreateSpecificAgent(Kernel kernel, string credentials)
{
    // Clone kernel instance to allow for agent specific plug-in definition
    Kernel agentKernel = kernel.Clone();

    // Import plug-in from type
    agentKernel.ImportPluginFromType<StatelessPlugin>();

    // Import plug-in from object
    agentKernel.ImportPluginFromObject(new StatefulPlugin(credentials));

    // Create the agent
    return
        new ChatCompletionAgent()
        {
            Name = "<agent name>",
            Instructions = "<agent instructions>",
            Kernel = agentKernel,
            Arguments = new KernelArguments(
                new OpenAIPromptExecutionSettings()
                {
                    FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
                })
        };
}

プラグインを使用して ChatCompletionAgent を作成するには、2 つの方法があります。

方法 1: コンストラクターを使用してプラグインを指定する

プラグインの一覧をコンストラクターに直接渡すことができます。

from semantic_kernel.agents import ChatCompletionAgent

# Create the Chat Completion Agent instance by specifying a list of plugins
agent = ChatCompletionAgent(
    service=AzureChatCompletion(),
    instructions="<instructions>",
    plugins=[SamplePlugin()]
)

ヒント

既定では、自動関数呼び出しが有効になっています。これを無効にするには、 function_choice_behavior 引数をコンストラクターで function_choice_behavior=FunctionChoiceBehavior.Auto(auto_invoke=False) するように設定します。この設定では、プラグインはモデルにブロードキャストされますが、自動的には呼び出されません。実行設定で AI サービス構成と同じ service_id または ai_model_id が指定されている場合、(KernelArgumentsを介して) 実行設定で定義された関数呼び出し動作が、コンストラクターで設定された関数の選択動作よりも優先されます。

方法 2: カーネルを手動で構成する

コンストラクターを介してカーネルが指定されていない場合、モデルの検証中にカーネルが自動的に作成されます。渡されるすべてのプラグインが優先され、カーネルに追加されます。カーネルの状態をより細かく制御するには、次の手順に従います。

from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.connectors.ai import FunctionChoiceBehavior
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion, AzureChatPromptExecutionSettings
from semantic_kernel.functions import KernelFunctionFromPrompt
from semantic_kernel.kernel import Kernel

# Create the instance of the Kernel
kernel = Kernel()

# Add the chat completion service to the Kernel
kernel.add_service(AzureChatCompletion())

# Get the AI Service settings
settings = kernel.get_prompt_execution_settings_from_service_id()

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

# Add the Plugin to the Kernel
kernel.add_plugin(SamplePlugin(), plugin_name="<plugin name>")

# Create the agent
agent = ChatCompletionAgent(
    kernel=kernel,
    name=<agent name>,
    instructions=<agent instructions>,
    arguments=KernelArguments(settings=settings),
)

ヒント

カーネルにサービスを追加するときに service_id が指定されていない場合、既定では default になります。カーネルで複数の AI サービスを構成する場合は、 service_id 引数を使用して区別することをお勧めします。これにより、特定の service_id の実行設定を取得し、それらの設定を目的のサービスに関連付けられます。

var chatCompletion = OpenAIChatCompletion.builder()
    .withModelId("<model-id>")
    .withOpenAIAsyncClient(new OpenAIClientBuilder()
            .credential(new AzureKeyCredential("<api-key>"))
            .endpoint("<endpoint>")
            .buildAsyncClient())
    .build();

Kernel kernel = Kernel.builder()
    .withAIService(ChatCompletionService.class, chatCompletion)
    .withPlugin(KernelPluginFactory.createFromObject(new SamplePlugin(), "<plugin name>"))
    .build();

var agent = ChatCompletionAgent.builder()
    .withKernel(kernel)
    .withName("<agent name>")
    .withInstructions("<agent instructions>")
    .build();

エージェントへの関数の追加

Plugin は、Function Calling を構成するための最も一般的な方法です。ただし、プロンプト関数を含め、個々の関数を個別に指定することもできます。

// Factory method to product an agent with a specific role.
// Could be incorporated into DI initialization.
ChatCompletionAgent CreateSpecificAgent(Kernel kernel)
{
    // Clone kernel instance to allow for agent specific plug-in definition
    Kernel agentKernel = kernel.Clone();

    // Create plug-in from a static function
    var functionFromMethod = agentKernel.CreateFunctionFromMethod(StatelessPlugin.AStaticMethod);

    // Create plug-in from a prompt
    var functionFromPrompt = agentKernel.CreateFunctionFromPrompt("<your prompt instructions>");

    // Add to the kernel
    agentKernel.ImportPluginFromFunctions("my_plugin", [functionFromMethod, functionFromPrompt]);

    // Create the agent
    return
        new ChatCompletionAgent()
        {
            Name = "<agent name>",
            Instructions = "<agent instructions>",
            Kernel = agentKernel,
            Arguments = new KernelArguments(
                new OpenAIPromptExecutionSettings()
                {
                    FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
                })
        };
}

from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.connectors.ai import FunctionChoiceBehavior
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion, AzureChatPromptExecutionSettings
from semantic_kernel.functions import KernelFunctionFromPrompt
from semantic_kernel.kernel import Kernel

# Create the instance of the Kernel
kernel = Kernel()

# Add the chat completion service to the Kernel
kernel.add_service(AzureChatCompletion())

# Create the AI Service settings
settings = AzureChatPromptExecutionSettings()

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

# Add the Plugin to the Kernel
kernel.add_function(
    plugin_name="<plugin_name>",
    function=KernelFunctionFromPrompt(
        function_name="<function_name>",
        prompt="<your prompt instructions>",
    )
)

# Create the agent
agent = ChatCompletionAgent(
    kernel=kernel,
    name=<agent name>,
    instructions=<agent instructions>,
    arguments=KernelArguments(settings=settings),
)

var chatCompletion = OpenAIChatCompletion.builder()
    .withModelId("<model-id>")
    .withOpenAIAsyncClient(new OpenAIClientBuilder()
            .credential(new AzureKeyCredential("<api-key>"))
            .endpoint("<endpoint>")
            .buildAsyncClient())
    .build();

// Create function from method
var functionFromMethod = KernelFunction.createFromMethod(SamplePlugin.class.getMethod("method"), new SamplePlugin());

// Create function from prompt
var functionFromPrompt = KernelFunction.createFromPrompt("<your prompt instructions>");

// Create the kernel with a plugin from the two functions
Kernel kernel = Kernel.builder()
    .withAIService(ChatCompletionService.class, chatCompletion)
    .withPlugin(KernelPluginFactory.createFromFunctions("SamplePlugin", List.of(functionFromMethod, functionFromPrompt)))
    .build();

InvocationContext invocationContext = InvocationContext.builder()
    .withFunctionChoiceBehavior(FunctionChoiceBehavior.auto(true))
    .build();

// Create the agent
var agent = ChatCompletionAgent.builder()
    .withKernel(kernel)
    .withName("<agent name>")
    .withInstructions("<agent instructions>")
    .withInvocationContext(invocationContext)
    .build();

エージェント関数呼び出しの制限事項

aChatCompletionAgent を直接呼び出す場合は、すべての関数の選択動作がサポートされます。ただし、 OpenAIAssistantを使用する場合は、現在、自動関数呼び出しのみを使用できます。

使い方

関数呼び出しを使用するエンドツーエンドの例については、次を参照してください。

方法: ChatCompletionAgent

次のステップ

エージェントの応答をストリーミングする方法

Last updated on 2025-05-23

次の方法で共有

セマンティック カーネル プラグインを使用したエージェントの構成

セマンティック カーネルの関数とプラグイン

エージェントへのプラグインの追加

方法 1: コンストラクターを使用してプラグインを指定する

方法 2: カーネルを手動で構成する

エージェントへの関数の追加

エージェント関数呼び出しの制限事項

使い方

次のステップ

その他のリソース

セマンティックカーネルプラグインを使用したエージェントの構成

セマンティックカーネルの関数とプラグイン