探索语义内核 `ChatCompletionAgent`

项目
03/12/2025

重要

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

有关此讨论的详细 API 文档在以下位置提供：

ChatCompletionAgent

代理当前在 Java 中不可用。

语义内核中的聊天功能完成

聊天完成 基本上是一种协议，用于与 AI 模型进行基于聊天的交互，其中聊天历史记录通过每个请求维护并呈现给模型。 语义内核AI 服务提供统一的框架，用于集成各种 AI 模型的聊天完成功能。

聊天完成代理可以利用这些 AI 服务中的任何一个来生成响应，无论是定向到用户还是另一个代理。

对于 .NET， 聊天完成 AI 服务基于 IChatCompletionService 接口。

对于 .NET，支持通过聊天完成的模型的某些 AI 服务包括：

型号	语义内核 AI 服务
Azure OpenAI	`Microsoft.SemanticKernel.Connectors.AzureOpenAI`
双子座	`Microsoft.SemanticKernel.Connectors.Google`
HuggingFace	`Microsoft.SemanticKernel.Connectors.HuggingFace`
Mistral	`Microsoft.SemanticKernel.Connectors.MistralAI`
OpenAI	`Microsoft.SemanticKernel.Connectors.OpenAI`
Onnx	`Microsoft.SemanticKernel.Connectors.Onnx`

代理当前在 Java 中不可用。

准备您的开发环境

若要继续开发 AzureAIAgent，请使用相应的包配置开发环境。

将 Microsoft.SemanticKernel.Agents.Core 包添加到项目：

dotnet add package Microsoft.SemanticKernel.Agents.Core --prerelease

安装 semantic-kernel 包：

pip install semantic-kernel

代理当前在 Java 中不可用。

创建 `ChatCompletionAgent`

ChatCompletionAgent 从根本上基于 AI 服务。因此，创建 ChatCompletionAgent 需要先创建一个包含一个或多个聊天完成服务的 Kernel 实例，然后通过引用该 Kernel 实例来实例化代理。

// Initialize a Kernel with a chat-completion service
IKernelBuilder builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(/*<...configuration parameters>*/);

Kernel kernel = builder.Build();

// Create the agent
ChatCompletionAgent agent =
    new()
    {
        Name = "SummarizationAgent",
        Instructions = "Summarize user input",
        Kernel = kernel
    };

可通过两种方法创建 ChatCompletionAgent：

1.直接提供聊天完成服务：

# Create the agent by directly providing the chat completion service
agent = ChatCompletionAgent(
    service=AzureChatCompletion(),  # your chat completion service instance
    name="<agent name>",
    instructions="<agent instructions>",
)

2.首先创建内核，向其添加服务，然后提供内核：

# Define the kernel
kernel = Kernel()

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

# Create the agent using the kernel
agent = ChatCompletionAgent(
  kernel=kernel, 
  name="<agent name>", 
  instructions="<agent instructions>",
)

当你已准备好聊天完成服务时，第一种方法非常有用。当你需要管理多个服务或其他功能的内核时，第二种方法非常有用。

代理当前在 Java 中不可用。

AI 服务选择

与直接使用语义内核 AI 服务不同，ChatCompletionAgent 支持服务选择器的规范。服务选择器会在 Kernel 包含多个 AI 服务时识别目标。

注意：如果存在多个 AI 服务，并且未提供任何服务选择器，则会对代理应用与在 Agent Framework 外部使用 AI 服务时相同的默认逻辑。

IKernelBuilder builder = Kernel.CreateBuilder();

// Initialize multiple chat-completion services.
builder.AddAzureOpenAIChatCompletion(/*<...service configuration>*/, serviceId: "service-1");
builder.AddAzureOpenAIChatCompletion(/*<...service configuration>*/, serviceId: "service-2");

Kernel kernel = builder.Build();

ChatCompletionAgent agent =
    new()
    {
        Name = "<agent name>",
        Instructions = "<agent instructions>",
        Kernel = kernel,
        Arguments = // Specify the service-identifier via the KernelArguments
          new KernelArguments(
            new OpenAIPromptExecutionSettings() 
            { 
              ServiceId = "service-2" // The target service-identifier.
            });
    };

from semantic_kernel.connectors.ai.open_ai import (
    AzureChatCompletion,
    AzureChatPromptExecutionSettings,
)

# Define the Kernel
kernel = Kernel()

# Add the AzureChatCompletion AI Service to the Kernel
kernel.add_service(AzureChatCompletion(service_id="service1"))
kernel.add_service(AzureChatCompletion(service_id="service2"))

settings = AzureChatPromptExecutionSettings(service_id="service2")

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

代理当前在 Java 中不可用。

与 `ChatCompletionAgent` 交谈

与 ChatCompletionAgent 进行交流是基于 ChatHistory 实例的，这与互动聊天完成的 AI 服务没有什么不同。

// Define agent
ChatCompletionAgent agent = ...;

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

// Add a user message to the conversation
chat.Add(new ChatMessageContent(AuthorRole.User, "<user input>"));

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

有多种方法可以与 ChatCompletionAgent对话。

最简单的方法是调用并等待 get_response：

# Define agent
agent = ChatCompletionAgent(...)

# Define the chat history
chat = ChatHistory()

# Add the user message
chat.add_user_message(user_input)
# Generate the agent response
response = await agent.get_response(chat)
# response is a `ChatMessageContent` object

否则，调用 invoke 方法将返回 AsyncIterable的 ChatMessageContent。

# Define agent
agent = ChatCompletionAgent(...)

# Define the chat history
chat = ChatHistory()

# Add the user message
chat.add_user_message(user_input)

# Generate the agent response(s)
async for response in agent.invoke(chat):
  # process agent response(s)

ChatCompletionAgent 还支持流式处理，其中 invoke_stream 方法返回 AsyncIterableStreamingChatMessageContent：

# Define agent
agent = ChatCompletionAgent(...)

# Define the chat history
chat = ChatHistory()

# Add the user message
chat.add_message(ChatMessageContent(role=AuthorRole.USER, content=input))

# Generate the agent response(s)
async for response in agent.invoke_stream(chat):
  # process agent response(s)

代理当前在 Java 中不可用。

操作说明：

如需了解 ChatCompletionAgent 的端到端示例，请参阅：

操作指南：ChatCompletionAgent

探索 OpenAI 智能助手

通过

探索语义内核 ChatCompletionAgent

语义内核中的聊天功能完成

准备您的开发环境

创建 ChatCompletionAgent

1.直接提供聊天完成服务：

2.首先创建内核，向其添加服务，然后提供内核：

AI 服务选择

与 ChatCompletionAgent 交谈

操作说明：

其他资源

探索语义内核 `ChatCompletionAgent`

创建 `ChatCompletionAgent`

与 `ChatCompletionAgent` 交谈