Настройка агентов с помощью плагинов семантического ядра

Это важно

Эта функция находится на стадии релиз-кандидата. Функции на этом этапе почти завершены и обычно стабильны, хотя они могут пройти незначительные уточнения или оптимизации, прежде чем достичь полной общедоступной доступности.

Функции и подключаемые модули в семантическом ядре

Вызов функций — это мощный инструмент, позволяющий разработчикам добавлять пользовательские функции и расширять возможности приложений искусственного интеллекта. Архитектура подключаемого модуля семантического ядра предлагает гибкую платформу для поддержки вызовов функций. AgentДля интеграции подключаемых модулей и вызовов функций используется эта базовая функция семантического ядра.

После настройки агент будет выбирать, когда и как вызывать доступную функцию, как в любом другом использовании за пределами Agent Framework.

Подсказка

Справочник по API:

Подсказка

Справочник по API:

Подсказка

Справочник по API:

Добавление плагинов в агент

Любой подключаемый модуль , доступный для объекта Agent , управляется в соответствующем Kernel экземпляре. Эта настройка позволяет каждому Agent получать доступ к различным функциям на основе конкретной роли.

Подключаемые модули можно добавить в Kernel либо до, либо после создания Agent. Процесс инициализации подключаемых модулей соответствует тем же шаблонам, которые используются для любой реализации семантического ядра, что позволяет обеспечить согласованность и простоту использования в управлении возможностями искусственного интеллекта.

Замечание

Для 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 с использованием подключаемых модулей.

Метод 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) в конструкторе. С помощью этого параметра подключаемые модули транслируются в модель, но они не вызываются автоматически. Если параметры выполнения указывают те же 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. При настройке нескольких служб ИИ в ядре рекомендуется различать их с помощью аргумента 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();

Ограни́чения на вызов функций агента

При непосредственномChatCompletionAgent вызове функции поддерживаются все действия по выбору функции. Однако при использовании OpenAIAssistant в настоящее время доступна только автоматическая вызов функций.

Инструкции

Полный пример использования вызовов функций см. в следующих примерах:

практическое руководство : ChatCompletionAgent

Дальнейшие шаги

Как осуществлять потоковую передачу ответов агента

Last updated on 2025-04-09

Поделиться через

Настройка агентов с помощью плагинов семантического ядра

Функции и подключаемые модули в семантическом ядре

Добавление плагинов в агент

Метод 1: Указание плагинов с помощью конструктора

Метод 2. Настройка ядра вручную

Добавление функций агенту

Ограни́чения на вызов функций агента

Инструкции

Дальнейшие шаги

Дополнительные ресурсы