语义核

使用这款企业级编排框架构建智能 AI 代理和多代理系统

什么是语义核？

语义核是一个与模型无关的 SDK，它使开发者能够构建、编排和部署 AI 代理及多代理系统。无论您是在构建一个简单的聊天机器人，还是复杂的多代理工作流，语义核都能为您提供所需工具，并具备企业级的可靠性和灵活性。

系统要求

• Python: 3.10+
• .NET: .NET 10.0+
• Java: JDK 17+
• 操作系统支持: Windows、macOS、Linux

核心特性

• 模型灵活性: 可连接任何 LLM，内置对 OpenAI、Azure OpenAI、Hugging Face、NVidia 等的支持
• 代理框架: 构建模块化 AI 代理，可访问工具/插件、记忆和规划能力
• 多代理系统: 编排复杂的工作流程，让专业代理协同工作
• 插件生态系统: 可通过原生代码函数、提示模板、OpenAPI 规范或模型上下文协议 (MCP) 进行扩展
• 向量数据库支持: 无缝集成 Azure AI 搜索、Elasticsearch、Chroma 等
• 多模态支持: 处理文本、视觉和音频输入
• 本地部署: 可与 Ollama、LMStudio 或 ONNX 配合使用
• 流程框架: 使用结构化的流程方法来建模复杂的业务流程
• 企业就绪: 专为可观测性、安全性及稳定的 API 而设计

安装

首先，设置您的 AI 服务环境变量：

Azure OpenAI:

export AZURE_OPENAI_API_KEY=AAA....

或直接使用 OpenAI:

export OPENAI_API_KEY=sk-...

Python

pip install semantic-kernel

.NET

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

Java

请参阅 semantic-kernel-java 构建文档，获取安装说明。

快速入门

基础代理 - Python

创建一个简单的助手，响应用户提示：

import asyncio
from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion

async def main():
    # 初始化一个带有基本指令的聊天代理
    agent = ChatCompletionAgent(
        service=AzureChatCompletion(),
        name="SK-Assistant",
        instructions="你是一位乐于助人的助手。",
    )

    # 获取用户消息的回应
    response = await agent.get_response(messages="写一首关于语义核的俳句。")
    print(response.content)

asyncio.run(main()) 

# 输出：
# 语言之精髓，
# 语义线交织，
# 意义核心现。

基础代理 - .NET

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;

var builder = Kernel.CreateBuilder();
builder.AddAzureOpenAIChatCompletion(
                Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT"),
                Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT"),
                Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY")
                );
var kernel = builder.Build();

ChatCompletionAgent agent =
    new()
    {
        Name = "SK-Agent",
        Instructions = "你是一位乐于助人的助手。",
        Kernel = kernel,
    };

await foreach (AgentResponseItem<ChatMessageContent> response 
    in agent.InvokeAsync("写一首关于语义核的俳句。"))
{
    Console.WriteLine(response.Message);
}

// 输出：
// 语言之精髓，
// 语义线交织，
// 意义核心现。

带插件的代理 - Python

通过自定义工具（插件）和结构化输出增强您的代理：

import asyncio
from typing import Annotated
from pydantic import BaseModel
from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion, OpenAIChatPromptExecutionSettings
from semantic_kernel.functions import kernel_function, KernelArguments

class MenuPlugin:
    @kernel_function(description="提供菜单中的特价菜品列表。")
    def get_specials(self) -> Annotated[str, "返回菜单中的特价菜品。"]:
        return """
        特价汤：蛤蜊浓汤
        特价沙拉：科布沙拉
        特价饮品：柴茶
        """

    @kernel_function(description="提供所请求菜单项的价格。")
    def get_item_price(
        self, menu_item: Annotated[str, "菜单项的名称。"]
    ) -> Annotated[str, "返回菜单项的价格。"]:
        return "$9.99"

class MenuItem(BaseModel):
    price: float
    name: str

async def main():
    # 配置结构化输出格式
    settings = OpenAIChatPromptExecutionSettings()
    settings.response_format = MenuItem

    # 创建带有插件和设置的代理
    agent = ChatCompletionAgent(
        service=AzureChatCompletion(),
        name="SK-Assistant",
        instructions="你是一位乐于助人的助手。",
        plugins=[MenuPlugin()],
        arguments=KernelArguments(settings)
    )

    response = await agent.get_response(messages="特价汤的价格是多少？")
    print(response.content)

    # 输出：
    # 特价汤——蛤蜊浓汤的价格是 $9.99。

asyncio.run(main()) 

带插件的代理 - .NET

using System.ComponentModel;
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;
using Microsoft.SemanticKernel.ChatCompletion;

var builder = Kernel.CreateBuilder();
builder.AddAzureOpenAIChatCompletion(
                Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT"),
                Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT"),
                Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY")
                );
var kernel = builder.Build();

kernel.Plugins.Add(KernelPluginFactory.CreateFromType<MenuPlugin>());

ChatCompletionAgent agent =
    new()
    {
        Name = "SK-Assistant",
        Instructions = "You are a helpful assistant.",
        Kernel = kernel,
        Arguments = new KernelArguments(new PromptExecutionSettings() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto() })

    };

await foreach (AgentResponseItem<ChatMessageContent> response 
    in agent.InvokeAsync("What is the price of the soup special?"))
{
    Console.WriteLine(response.Message);
}

sealed class MenuPlugin
{
    [KernelFunction, Description("Provides a list of specials from the menu.")]
    public string GetSpecials() =>
        """
        Special Soup: Clam Chowder
        Special Salad: Cobb Salad
        Special Drink: Chai Tea
        """;

    [KernelFunction, Description("Provides the price of the requested menu item.")]
    public string GetItemPrice(
        [Description("The name of the menu item.")]
        string menuItem) =>
        "$9.99";
}

多智能体系统 - Python

构建一个可以协作的专业化智能体系统：

import asyncio
from semantic_kernel.agents import ChatCompletionAgent, ChatHistoryAgentThread
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion, OpenAIChatCompletion

billing_agent = ChatCompletionAgent(
    service=AzureChatCompletion(), 
    name="BillingAgent", 
    instructions="You handle billing issues like charges, payment methods, cycles, fees, discrepancies, and payment failures."
)

refund_agent = ChatCompletionAgent(
    service=AzureChatCompletion(),
    name="RefundAgent",
    instructions="Assist users with refund inquiries, including eligibility, policies, processing, and status updates."
)

triage_agent = ChatCompletionAgent(
    service=OpenAIChatCompletion(),
    name="TriageAgent",
    instructions="Evaluate user requests and forward them to BillingAgent or RefundAgent for targeted assistance.
    Provide the full answer to the user containing any information from the agents",
    plugins=[billing_agent, refund_agent],
)

thread: ChatHistoryAgentThread = None

async def main() -> None:
    print("Welcome to the chat bot!\n  Type 'exit' to exit.\n  Try to get some billing or refund help.")
    while True:
        user_input = input("User:> ")

        if user_input.lower().strip() == "exit":
            print("\n\nExiting chat...")
            return False

        response = await triage_agent.get_response(
            messages=user_input,
            thread=thread,
        )

        if response:
            print(f"Agent :> {response}")

# Agent :> I understand that you were charged twice for your subscription last month, and I'm here to assist you with resolving this issue. Here’s what we need to do next:

# 1. **Billing Inquiry**:
#    - Please provide the email address or account number associated with your subscription, the date(s) of the charges, and the amount charged. This will allow the billing team to investigate the discrepancy in the charges.

# 2. **Refund Process**:
#    - For the refund, please confirm your subscription type and the email address associated with your account.
#    - Provide the dates and transaction IDs for the charges you believe were duplicated.

# Once we have these details, we will be able to:

# - Check your billing history for any discrepancies.
# - Confirm any duplicate charges.
# - Initiate a refund for the duplicate payment if it qualifies. The refund process usually takes 5-10 business days after approval.

# Please provide the necessary details so we can proceed with resolving this issue for you.


if __name__ == "__main__":
    asyncio.run(main())

下一步

1. 📖 尝试我们的入门指南或了解构建智能体
2. 🔌 浏览超过100个详细示例
3. 💡 了解核心语义知识图谱的概念

API 参考

• C# API 参考
• Python API 参考

故障排除

常见问题

• 身份验证错误: 检查您的 API 密钥环境变量是否正确设置
• 模型可用性: 验证您的 Azure OpenAI 部署或 OpenAI 模型访问权限

获取帮助

• 查看我们的GitHub 问题以了解已知问题
• 在Discord 社区中搜索解决方案
• 请求帮助时，请包含您的 SDK 版本和完整的错误信息

加入社区

我们欢迎您对 SK 社区的贡献和建议！参与最简单的方式就是在 GitHub 仓库中参与讨论。我们欢迎提交 bug 报告和修复！

对于新功能、组件或扩展，请在发送 PR 之前先创建一个问题并与我们讨论。这样做既可以避免因我们可能朝不同方向发展而被拒绝，也可以考虑对更大生态系统的影响。

要了解更多并开始参与：

• 阅读文档

• 学习如何为项目做出贡献

• 在GitHub 讨论区提问

• 在Discord 社区提问

• 参加定期的办公时间和 SK 社区活动

• 关注我们的博客

贡献者名人堂

行为准则

本项目已采用 微软开源行为准则。 如需更多信息，请参阅 行为准则常见问题解答 或发送邮件至 opencode@microsoft.com 以提出任何其他问题或意见。

许可证

版权所有 © 微软公司。保留所有权利。

根据 MIT 许可证授权。

Semantic Kernel 快速上手指南

Semantic Kernel 是微软推出的企业级 AI 编排框架，支持构建智能 AI 代理（Agent）及多代理系统。它模型无关，可灵活连接各类大语言模型（LLM），并提供插件扩展、记忆管理和复杂工作流编排能力。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Windows, macOS, 或 Linux
• Python 用户：Python 3.10+
• .NET 用户：.NET 10.0+
• Java 用户：JDK 17+
• API 密钥：需准备好 Azure OpenAI 或 OpenAI 的 API Key

配置环境变量

在使用前，请在终端中设置您的 AI 服务密钥：

使用 Azure OpenAI:

export AZURE_OPENAI_API_KEY=AAA....
export AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
export AZURE_OPENAI_DEPLOYMENT=your-deployment-name

或直接使用 OpenAI:

export OPENAI_API_KEY=sk-...

安装步骤

根据您的开发语言选择相应的安装命令。

提示：国内开发者若遇到 PyPI 下载缓慢，可使用清华源加速安装： pip install semantic-kernel -i https://pypi.tuna.tsinghua.edu.cn/simple

Python

pip install semantic-kernel

.NET

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

Java

请参考官方构建文档：semantic-kernel-java build

基本使用

以下示例展示如何创建一个基础的 AI 代理并与其对话。

Python 示例

创建一个简单的助手，使其能够响应用户指令生成内容：

import asyncio
from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion

async def main():
    # 初始化一个带有基本指令的聊天代理
    agent = ChatCompletionAgent(
        service=AzureChatCompletion(),
        name="SK-Assistant",
        instructions="You are a helpful assistant.",
    )

    # 获取对用户消息的响应
    response = await agent.get_response(messages="Write a haiku about Semantic Kernel.")
    print(response.content)

asyncio.run(main()) 

# Output:
# Language's essence,
# Semantic threads intertwine,
# Meaning's core revealed.

.NET 示例

在 C# 中构建并运行同一个助手：

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;

var builder = Kernel.CreateBuilder();
builder.AddAzureOpenAIChatCompletion(
                Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT"),
                Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT"),
                Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY")
                );
var kernel = builder.Build();

ChatCompletionAgent agent =
    new()
    {
        Name = "SK-Agent",
        Instructions = "You are a helpful assistant.",
        Kernel = kernel,
    };

await foreach (AgentResponseItem<ChatMessageContent> response 
    in agent.InvokeAsync("Write a haiku about Semantic Kernel."))
{
    Console.WriteLine(response.Message);
}

// Output:
// Language's essence,
// Semantic threads intertwine,
// Meaning's core revealed.

进阶：带插件的代理 (Python)

通过插件为代理添加自定义工具能力（例如查询菜单价格）：

import asyncio
from typing import Annotated
from pydantic import BaseModel
from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion, OpenAIChatPromptExecutionSettings
from semantic_kernel.functions import kernel_function, KernelArguments

class MenuPlugin:
    @kernel_function(description="Provides a list of specials from the menu.")
    def get_specials(self) -> Annotated[str, "Returns the specials from the menu."]:
        return """
        Special Soup: Clam Chowder
        Special Salad: Cobb Salad
        Special Drink: Chai Tea
        """

    @kernel_function(description="Provides the price of the requested menu item.")
    def get_item_price(
        self, menu_item: Annotated[str, "The name of the menu item."]
    ) -> Annotated[str, "Returns the price of the menu item."]:
        return "$9.99"

class MenuItem(BaseModel):
    price: float
    name: str

async def main():
    # 配置结构化输出格式
    settings = OpenAIChatPromptExecutionSettings()
    settings.response_format = MenuItem

    # 创建带有插件和设置的代理
    agent = ChatCompletionAgent(
        service=AzureChatCompletion(),
        name="SK-Assistant",
        instructions="You are a helpful assistant.",
        plugins=[MenuPlugin()],
        arguments=KernelArguments(settings)
    )

    response = await agent.get_response(messages="What is the price of the soup special?")
    print(response.content)

    # Output:
    # The price of the Clam Chowder, which is the soup special, is $9.99.

asyncio.run(main())