使用语义内核插件配置代理

重要

此功能处于候选发布阶段。 此阶段的功能几乎完整且一般稳定，尽管在全面推出之前，它们可能会进行轻微的改进或优化。

语义内核中的函数和插件

函数调用是一种功能强大的工具，可让开发人员添加自定义功能并扩展 AI 应用程序的功能。 语义内核 插件 体系结构提供了一个灵活的框架来支持 函数调用。 对于一个Agent，整合插件和函数调用是基于这一基础的语义内核功能构建的。

配置完成后，智能体将选择何时以及如何调用可用函数，就像在 Agent Framework 外部的任何使用场景中一样。

小提示

API 参考：

• KernelFunctionFactory
• KernelFunction
• KernelPluginFactory
• KernelPlugin
• Kernel.Plugins

小提示

API 参考：

• kernel_function
• kernel_function_extension
• kernel_plugin

小提示

API 参考：

• KernelFunction
• KernelFunctionFromMethod
• KernelFunctionFromPrompt

将插件添加到代理

任何可用于的Agent都在其各自的Kernel实例内进行管理。 此设置使每个人都 Agent 能够根据其特定角色访问不同的功能。

可以在创建之前或之后将Kernel添加到Agent。 初始化 插件 的过程遵循用于任何语义内核实现的相同模式，允许在管理 AI 功能方面保持一致性和易用性。

注释

对于 a ChatCompletionAgent，必须显式启用函数调用模式。 OpenAIAssistant 代理始终基于自动函数调用。

// Factory method to product 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 插件。

方法 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),
)

小提示

如果在将服务添加到内核时未指定 a 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();

将功能添加到代理

插件是配置函数调用的最常见方法。 但是，还可以单独提供各个函数，包括提示函数。

// 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

后续步骤

如何流式传输代理响应