Semantic Kernel:微软出品的模型无关企业级 Agent 编排 SDK|部署与使用全指南
项目仓库: https://github.com/microsoft/semantic-kernel
开源协议:MIT(© Microsoft Corporation)· 支持语言:Python 3.10+ / .NET 10.0+ / Java JDK 17+ · 交付形态:SDK(NuGet / PyPI / Maven)· 官方文档:learn.microsoft.com/semantic-kernel
官方重要提示(README 顶部):Semantic Kernel 现已由 Microsoft Agent Framework(MAF) 接棒。MAF 1.0 已作为生产就绪版本发布,提供企业级多 Agent 编排、多提供者模型支持与 A2A / MCP 跨运行时互操作。迁移路径见官方 migration guide。
1 项目简介
Semantic Kernel 是微软开源的模型无关 SDK,用于构建、编排、部署 AI Agent 与多 Agent 系统。无论简单聊天机器人还是复杂多 Agent 工作流,它都提供企业级可靠性与灵活性。
1.1 核心信息一览
| 项目项 | 内容 |
|---|---|
| 项目名称 | Semantic Kernel(SK) |
| 仓库地址 | github.com/microsoft/semantic-kernel |
| 项目定位 | 模型无关的企业级 Agent 编排 SDK |
| 开源协议 | MIT |
| 支持语言 | Python 3.10+、.NET 10.0+、Java JDK 17+ |
| 操作系统 | Windows / macOS / Linux |
| 包 | semantic-kernel(PyPI)、Microsoft.SemanticKernel(NuGet) |
| 模型接入 | OpenAI、Azure OpenAI、Hugging Face、NVidia、Ollama、LMStudio、ONNX 等 |
| 向量库 | Azure AI Search、Elasticsearch、Chroma 等 |
| 官方文档 | learn.microsoft.com/semantic-kernel |
| 继任者 | Microsoft Agent Framework 1.0(生产就绪) |
1.2 适用场景
- 已经在用 .NET / Python 企业栈,希望把 LLM 能力以 SDK 方式嵌入现有应用。
- 需要多 Agent 协作(如 Triage → Billing / Refund),用代码而不是可视化编排器描述。
- 同时对接 OpenAI、Azure OpenAI、本地 Ollama、Hugging Face 等多个模型后端。
- 需要企业级可观测性、安全与稳定 API 承诺。
1.3 能力边界(官方口径)
- README 顶部明确:SK 已被 MAF 1.0 接棒;新项目建议直接评估 MAF,存量项目按官方迁移路径升级。
- SDK 本身不附带模型;需要自行准备 OpenAI / Azure OpenAI 等凭据。
- 插件、记忆、规划等能力以 SDK 抽象提供,不替代业务系统。
2 功能特性
2.1 模型灵活性
内置支持 OpenAI、Azure OpenAI、Hugging Face、NVidia 等;可本地跑 Ollama、LMStudio、ONNX。
2.2 Agent 框架
用工具 / 插件、记忆、规划能力构建模块化 Agent。
2.3 多 Agent 系统
编排协作型专家 Agent,例如 Triage Agent 把请求转给 Billing / Refund Agent。
2.4 插件生态
- 原生代码函数;
- 提示词模板;
- OpenAPI 规格;
- Model Context Protocol(MCP)。
2.5 向量库与多模态
- 无缝集成 Azure AI Search、Elasticsearch、Chroma 等;
- 处理文本、视觉、音频输入。
2.6 Process Framework
用结构化工作流方式建模复杂业务流程。
2.7 企业级就绪
内置可观测性、安全、稳定 API。
3 官方界面预览
SK 是 SDK,不自带 Web UI;官方示例见 detailed-samples。
4 官方跳转链接汇总
| 类别 | 链接 | 说明 |
|---|---|---|
| 仓库主页 | github.com/microsoft/semantic-kernel | 源码、README、示例 |
| 官方文档 | learn.microsoft.com/semantic-kernel | 概念、快速入门、API 参考 |
| 快速入门 | get-started/quick-start-guide | 官方入门 |
| 详细示例 | detailed-samples | 100+ 示例 |
| 构建 Agent | frameworks/agent | Agent 文档 |
| Python API | C# / Python API 参考 | API 参考 |
| MAF 继任者 | Microsoft Agent Framework | 1.0 生产就绪 |
| 迁移指南 | from-semantic-kernel | SK → MAF |
| Discord | aka.ms/SKDiscord | 社区 |
| Issues | github.com/microsoft/semantic-kernel/issues | 问题上报 |
5 前置要求与服务器配置
5.1 软件前提
| 运行时 | 版本 |
|---|---|
| Python | 3.10+ |
| .NET | .NET 10.0+ |
| Java | JDK 17+ |
| 操作系统 | Windows / macOS / Linux |
5.2 模型凭据
# Azure OpenAI
export AZURE_OPENAI_API_KEY=AAA....
# 或直接用 OpenAI
export OPENAI_API_KEY=sk-...5.3 服务器建议
| 项目 | 最低 / 建议 |
|---|---|
| 操作系统 | Linux(Ubuntu 22.04+) |
| CPU | 2 核起步,4 核建议 |
| 内存 | 4 GB 起步,8 GB 建议 |
| 磁盘 | 10 GB 可用 |
| 网络 | 能访问 Azure OpenAI / OpenAI API |
6 方式一:pip / dotnet 安装(推荐)
6.1 Python
pip install semantic-kernel6.2 .NET
dotnet add package Microsoft.SemanticKernel
dotnet add package Microsoft.SemanticKernel.Agents.Core6.3 Java
参见 semantic-kernel-java build。
6.4 最小 Agent(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())6.5 最小 Agent(.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 = "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);
}7 方式二:源码 / 多 Agent 示例
7.1 克隆仓库
git clone https://github.com/microsoft/semantic-kernel.git
cd semantic-kernel7.2 带插件的 Agent(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\nSpecial Salad: Cobb Salad\nSpecial 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)
asyncio.run(main())7.3 多 Agent 系统(Python)
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.",
plugins=[billing_agent, refund_agent],
)8 配置项说明
8.1 环境变量
| 变量 | 作用 |
|---|---|
AZURE_OPENAI_API_KEY |
Azure OpenAI 密钥 |
AZURE_OPENAI_ENDPOINT |
Azure OpenAI 实例地址 |
AZURE_OPENAI_DEPLOYMENT |
Azure 部署名 |
OPENAI_API_KEY |
直接用 OpenAI 时的密钥 |
8.2 插件
- Python:
@kernel_function装饰函数; - .NET:
[KernelFunction, Description]标注方法; - 也可从 OpenAPI 规格、MCP server 导入。
8.3 结构化输出
settings = OpenAIChatPromptExecutionSettings()
settings.response_format = MenuItem # pydantic BaseModel9 常用运维命令
# ---- Python ----
pip install semantic-kernel
pip show semantic-kernel
# ---- .NET ----
dotnet add package Microsoft.SemanticKernel
dotnet add package Microsoft.SemanticKernel.Agents.Core
dotnet build
# ---- 凭据 ----
export OPENAI_API_KEY=sk-...
export AZURE_OPENAI_API_KEY=...
export AZURE_OPENAI_ENDPOINT=...
export AZURE_OPENAI_DEPLOYMENT=...
# ---- 本地模型 ----
# 配合 Ollama / LMStudio / ONNX 使用,按官方文档配置10 常见故障排查
10.1 认证错误
- 检查 API Key 环境变量是否正确设置;
- Azure OpenAI 还要核对 endpoint 与 deployment 名。
10.2 模型不可用
- 确认 Azure OpenAI 部署已就绪;
- 确认 OpenAI 账户有对应模型访问权限与额度。
10.3 求助方式
- 查 GitHub Issues;
- 上 Discord 提问;
- 反馈时附上 SDK 版本与完整错误信息。
10.4 是否该用 MAF
README 顶部已明确:新项目建议直接评估 Microsoft Agent Framework 1.0;存量 SK 项目按官方迁移路径升级。
11 风险与合规说明
以下条款整理自官方 README 与 MIT 许可证;如与官方原文不一致,以仓库
LICENSE、README 与 learn.microsoft.com 为准。
11.1 开源协议与维护状态
SK 采用 MIT 许可证;但官方已将未来投入转向 MAF 1.0,新项目建议优先评估 MAF。
11.2 模型与 API 责任
- SDK 不附带模型;OpenAI、Azure OpenAI、Hugging Face、NVidia 等归各自厂商。
- 业务数据会按所选模型外发;敏感场景优先本地模型与离线配置。
11.3 自动化与工具权限
- 插件 / 工具可以读写外部系统;生产环境应限制工具范围、保留人工审批。
- 多 Agent 系统的行为由提示词与插件共同决定,上线前应充分测试。
11.4 免责
使用者在法律允许的最大范围内,自行承担因部署、修改、运行本项目产生的代码质量、数据泄露、服务中断与业务损失风险。如认为仓库内特定文件侵犯合法权益,请通过 GitHub Issues 提交说明。