从语义内核模板创建代理

项目
03/06/2025

重要

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

语义内核中的提示模板

代理的角色主要由它收到的指令决定其行为和操作。与调用Kernel提示类似，代理的说明可以包括模板化参数（值和函数），这些参数在执行期间动态替换。这可实现灵活的上下文感知响应，使代理能够基于实时输入调整其输出。

此外，可以通过提示模板配置直接配置代理，为开发人员提供一种结构化且可重用的方式来定义其行为。此方法提供了一个功能强大的工具，用于标准化和自定义代理指令，确保各种用例的一致性，同时仍保持动态适应性。

代理当前在 Java 中不可用。

代理指令作为模板

使用模板参数创建代理可以更灵活地根据不同的方案或要求轻松自定义其说明。此方法使代理的行为可以通过将特定值或函数替换到模板中来定制，使其适应各种任务或上下文。通过利用模板参数，开发人员可以设计更通用的代理，这些代理可以配置为满足各种用例，而无需修改核心逻辑。

聊天完成助手

// Initialize a Kernel with a chat-completion service
Kernel kernel = ...;

ChatCompletionAgent agent =
    new()
    {
        Kernel = kernel,
        Name = "StoryTeller",
        Instructions = "Tell a story about {{$topic}} that is {{$length}} sentences long.",
        Arguments = new KernelArguments()
        {
            { "topic", "Dog" },
            { "length", "3" },
        }
    };

agent = ChatCompletionAgent(
    service=AzureChatCompletion(), # or other supported AI Services
    name="StoryTeller",
    instructions="Tell a story about {{$topic}} that is {{$length}} sentences long.",
    arguments=KernelArguments(topic="Dog", length="2"),
)

代理当前在 Java 中不可用。

OpenAI 助手代理

在使用 OpenAIAssistantAgent时，模板化指令非常强大。使用此方法，可以多次创建和重复使用单个助理定义，每次使用不同的参数值针对特定任务或上下文。这可实现更高效的设置，允许同一助手框架处理各种方案，同时保持其核心行为的一致性。

// Retrieve an existing assistant definition by identifier
AzureOpenAIClient client = OpenAIAssistantAgent.CreateAzureOpenAIClient(new AzureCliCredential(), new Uri("<your endpoint>"));
AssistantClient assistantClient = client.GetAssistantClient();
Assistant assistant = await client.GetAssistantAsync();
OpenAIAssistantAgent agent = new(assistant, assistantClient, new KernelPromptTemplateFactory(), PromptTemplateConfig.SemanticKernelTemplateFormat)
{
    Arguments = new KernelArguments()
    {
        { "topic", "Dog" },
        { "length", "3" },
    }
}

# Create the client using Azure OpenAI resources and configuration
client, model = AzureAssistantAgent.setup_resources()

# Retrieve the assistant definition from the server based on the assistant ID
definition = await client.beta.assistants.retrieve(
    assistant_id="your-assistant-id",
)

# Create the AzureAssistantAgent instance using the client and the assistant definition
agent = AzureAssistantAgent(
    client=client,
    definition=definition,
    arguments=KernelArguments(topic="Dog", length="3"),
)

代理当前在 Java 中不可用。

来自提示模板的代理定义

还可以利用用于创建内核提示函数的提示模板配置来定义代理。这允许统一的方法管理提示和代理，促进不同组件的一致性和重复使用。通过从代码库外部化代理定义，此方法简化了多个代理的管理，使其更易于更新和维护，而无需对基础逻辑进行更改。这种分离还可以提高灵活性，使开发人员只需更新配置即可修改代理行为或引入新代理，而不是调整代码本身。

YAML 模板

name: GenerateStory
template: |
  Tell a story about {{$topic}} that is {{$length}} sentences long.
template_format: semantic-kernel
description: A function that generates a story about a topic.
input_variables:
  - name: topic
    description: The topic of the story.
    is_required: true
  - name: length
    description: The number of sentences in the story.
    is_required: true

代理初始化

// Read YAML resource
string generateStoryYaml = File.ReadAllText("./GenerateStory.yaml");
// Convert to a prompt template config
PromptTemplateConfig templateConfig = KernelFunctionYaml.ToPromptTemplateConfig(generateStoryYaml);

// Create agent with Instructions, Name and Description 
// provided by the template config.
ChatCompletionAgent agent =
    new(templateConfig)
    {
        Kernel = this.CreateKernelWithChatCompletion(),
        // Provide default values for template parameters
        Arguments = new KernelArguments()
        {
            { "topic", "Dog" },
            { "length", "3" },
        }
    };

import yaml

from semantic_kernel.prompt_template import PromptTemplateConfig

# Read the YAML file
with open("./GenerateStory.yaml", "r", encoding="utf-8") as file:
    generate_story_yaml = file.read()

# Parse the YAML content
data = yaml.safe_load(generate_story_yaml)

# Use the parsed data to create a PromptTemplateConfig object
prompt_template_config = PromptTemplateConfig(**data)

agent = ChatCompletionAgent(
    service=AzureChatCompletion(), # or other supported AI services
    prompt_template_config=prompt_template_config,
    arguments=KernelArguments(topic="Dog", length="3"),
)

代理当前在 Java 中不可用。

直接调用时覆盖模板值

直接调用代理时，无需使用 AgentChat，可以根据需要重写代理的参数。这允许在特定任务期间更好地控制和自定义代理的行为，使你能够动态修改代理的说明或设置，以满足特定要求。

// Initialize a Kernel with a chat-completion service
Kernel kernel = ...;

ChatCompletionAgent agent =
    new()
    {
        Kernel = kernel,
        Name = "StoryTeller",
        Instructions = "Tell a story about {{$topic}} that is {{$length}} sentences long.",
        Arguments = new KernelArguments()
        {
            { "topic", "Dog" },
            { "length", "3" },
        }
    };

// Create a ChatHistory object to maintain the conversation state.
ChatHistory chat = [];

KernelArguments overrideArguments =
    new()
    {
        { "topic", "Cat" },
        { "length", "3" },
    });

// Generate the agent response(s)
await foreach (ChatMessageContent response in agent.InvokeAsync(chat, overrideArguments))
{
  // Process agent response(s)...
}

agent = ChatCompletionAgent(
    service=AzureChatCompletion(),
    name="StoryTeller",
    instructions="Tell a story about {{$topic}} that is {{$length}} sentences long.",
    arguments=KernelArguments(topic="Dog", length="2"),
)

# Create a chat history to maintain the conversation state
chat = ChatHistory()

override_arguments = KernelArguments(topic="Cat", length="3")

# Two ways to get a response from the agent

# Get the response which returns a ChatMessageContent directly
response = await agent.get_response(chat, arguments=override_arguments)

# or use the invoke method to return an AsyncIterable of ChatMessageContent
async for response in agent.invoke(chat, arguments=override_arguments):
    # process agent response(s)...

代理当前在 Java 中不可用。

操作说明

有关从 提示模板创建代理的端到端示例，请参阅：

操作指南：ChatCompletionAgent

使用插件配置代理

通过

从语义内核模板创建代理

语义内核中的提示模板

相关 API：

代理指令作为模板

聊天完成助手

OpenAI 助手代理

来自提示模板的代理定义

YAML 模板

代理初始化

直接调用时覆盖模板值

操作说明

其他资源