Semantic Kernel Python Agent 快速上手：从 Chat Completion 到多 Agent 编排的完整实战指南-北京尧图网络

Semantic Kernel Python Agent 快速上手从 Chat Completion 到多 Agent 编排的完整实战指南【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel本指南以 python/samples/getting_started_with_agents/README.md 为主线系统讲解 Semantic Kernel Python 中 Agent智能体框架的入门路径从最基础的 Chat Completion Agent到 Azure AI Agent、OpenAI Assistant Agent、OpenAI Responses Agent再到多 Agent 并发、顺序、Group Chat、Handoff 与 Magentic 编排。读完本文你将掌握各类 Agent 的适用场景、版本约束、环境配置方法并能直接运行仓库中的 40 个 step 示例代码构建自己的单 Agent 对话与多 Agent 协作应用。一、Agent 框架概览与版本要求Semantic Kernel 的 Agent 框架位于 python/semantic_kernel/agents/ 目录内部按能力划分模块chat_completionChat Completion Agent、open_aiOpenAI Assistant / Responses Agent、azure_aiAzure AI Agent、group_chat与orchestration多 Agent 协作、strategies选择与终止策略以及runtime进程内运行时。由于不同 Agent 类型依赖不同的底层服务 API各功能的可用性对应了不同的 PyPI 最低版本当前仓库 README 明确给出功能最低 PyPI 版本Chat Completion Agent1.3.0OpenAI Assistant Agent1.4.0Agent Group Chat1.6.0Streaming OpenAI Assistant Agent1.11.0OpenAI Responses Agent1.27.0从源码结构看这一版本梯度与各模块引入的时间线一致Chat Completion Agent 最先稳定open_ai模块中的azure_responses_agent.py、openai_responses_agent.py是较晚加入的。实际使用中建议直接安装最新版pip install semantic-kernel即可覆盖以上全部能力。二、示例总览五个专题、四十余个 step入门示例按专题组织在 python/samples/getting_started_with_agents/ 下包括chat_completion/基于 Chat Completion 服务的本地 Agent11 个 stepazure_ai_agent/Azure AI Foundry原 Azure AI Foundry托管的 Agent8 个 stepopenai_assistant/OpenAI Assistants API Agent6 个 stepopenai_responses/OpenAI Responses API Agent8 个 stepmulti_agent_orchestration/多 Agent 编排10 个 stepcopilot_studio/Microsoft Copilot Studio Agent 示例目录已存在但未列入 README 主表。每个 step 都是可直接独立运行的完整脚本命名遵循stepNN_主题.py的惯例由浅入深地递进。下文按 README 的顺序逐一展开。三、Chat Completion Agent最基础的 Agent 形态Chat Completion Agent 是理解整个框架的入口。它不依赖云端 Agent 服务而是由 Semantic Kernel 在本地用 AI 服务连接器包装出一个具有 Agent 会话能力的对象。对应源码见 python/semantic_kernel/agents/chat_completion/chat_completion_agent.py。3.1 最小可用示例step01_chat_completion_agent_simple.py 演示了最基础的用法把 AI 服务直接传入ChatCompletionAgent构造器用get_response完成一问一答。import asyncio from azure.identity import AzureCliCredential from semantic_kernel.agents import ChatCompletionAgent from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion USER_INPUTS [ Why is the sky blue?, What is the capital of France?, ] async def main(): # 1. 创建 Agent直接指定底层 AI 服务 agent ChatCompletionAgent( serviceAzureChatCompletion(credentialAzureCliCredential()), nameAssistant, instructionsAnswer questions about the world in one sentence., ) for user_input in USER_INPUTS: print(f# User: {user_input}) # 2. 通过 get_response 获取响应 response await agent.get_response(messagesuser_input) print(f# {response.name}: {response}) if __name__ __main__: asyncio.run(main())关键点service参数接收任意ChatCompletionClientBase实现这里使用的是AzureChatCompletionname定义 Agent 名字instructions定义系统提示词get_response是统一的交互入口传入messages字符串或消息列表返回包含name与内容的结果对象所有示例均为async风格入口统一使用asyncio.run(main())。3.2 会话线程管理step02_chat_completion_agent_thread_management.py 展示了多轮对话的关键——线程Thread。Chat Completion Agent 本身不保存状态会话历史由调用方通过ChatHistoryAgentThread维护from semantic_kernel.agents import ChatCompletionAgent, ChatHistoryAgentThread thread: ChatHistoryAgentThread None for user_input in USER_INPUTS: response await agent.get_response(messagesuser_input, threadthread) print(f# {response.name}: {response}) # 将返回的线程保存下来供下一轮继续使用 thread response.thread # 会话结束后的清理 await thread.delete() if thread else None注意若未传入threadAgent 会在首次响应时新建线程并随响应返回thread.delete()用于释放会话资源。从示例输出可以看到第三问 “What is my name?” 能正确回忆出第一轮 “I am John Doe.”这正是线程携带上下文的体现。3.3 通过 Kernel 注入服务与插件README 中的 step03step05 展示了两种组织方式step03_chat_completion_agent_with_kernel.py在Kernel上注册 AI 服务后将Kernel传入 Agent 构造器step04_chat_completion_agent_plugin_simple.py通过构造器直接指定带插件的 Kernelstep05_chat_completion_agent_plugin_with_kernel.py在 Kernel 上注册插件PluginAgent 自动获得调用函数的能力。推荐用 Kernel 承载服务与插件的注册这样 Agent 与 Kernel 共享同一套依赖管理便于后续扩展 Function Calling。3.4 高级能力JSON 输出、结构化输出与日志step08_chat_completion_agent_json_result.py让 Agent 以 JSON 格式返回结果step10_chat_completion_agent_structured_outputs.py使用模型的结构化输出Structured Outputs能力声明式约束返回的 JSON Schemastep09_chat_completion_agent_logging.py开启 Agent 日志便于排查调用链路。3.5 声明式 AgentDeclarative Agentstep11_chat_completion_agent_declarative.py 演示如何从声明式规范spec创建 Agent。这种方式把 Agent 的定义名称、指令、所用服务与代码解耦便于配置化管理语义上与multi_agent_orchestration和azure_ai_agent中的声明式 step 一脉相承。四、Azure AI Agent云托管式 AgentAzure AI Agent 由 Azure AI Foundry 托管运行Agent 的线程、工具、运行状态都在云端管理客户端通过AzureAIAgent封装访问。示例位于 python/samples/getting_started_with_agents/azure_ai_agent/其专属说明见 azure_ai_agent/README.md。4.1 环境配置在项目根目录的.env中配置三项必需变量注意变量名以AZURE_AI_AGENT_开头AZURE_AI_AGENT_ENDPOINT example-endpoint-string AZURE_AI_AGENT_MODEL_DEPLOYMENT_NAME example-deployment-name AZURE_AI_AGENT_API_VERSION example-api-version其中 endpoint 格式为https://resource.services.ai.azure.com/api/projects/project-name可在 Azure AI Foundry 门户获取。Azure 资源需配置至少 Basic 或 Standard SKU。4.2 客户端创建与 Agent 定义与 Chat Completion Agent 不同Azure AI Agent 需要先创建服务端客户端再创建云端 Agent 定义最后包装成 SK Agentfrom azure.identity.aio import AzureCliCredential from semantic_kernel.agents import AzureAIAgent from semantic_kernel.agents.azure_ai.azure_ai_agent_settings import AzureAIAgentSettings ai_agent_settings AzureAIAgentSettings() async with ( AzureCliCredential() as creds, AzureAIAgent.create_client( credentialcreds, endpointai_agent_settings.endpoint, api_versionai_agent_settings.api_version, ) as client, ): # 1. 在云端创建 Agent 定义 agent_definition await client.agents.create_agent( modelai_agent_settings.model_deployment_name, nameAGENT_NAME, instructionsAGENT_INSTRUCTIONS, ) # 2. 包装为 Semantic Kernel Agent agent AzureAIAgent(clientclient, definitionagent_definition) # 3. 创建线程、添加消息并调用运行前需先执行az login完成 Azure CLI 认证。4.3 工具链Code Interpreter / File Search / OpenAPI / MCPREADME 列出的一系列 step 覆盖了云端工具能力step04_azure_ai_agent_code_interpreter.py使用 Code Interpreter 工具执行代码step05_azure_ai_agent_file_search.py使用 File Search 工具检索文件step06_azure_ai_agent_openapi.py挂载 OpenAPI 定义将外部 REST API 暴露给 Agent目录中还新增了 step09_azure_ai_agent_mcp.pyMCP 工具与 step10 深度研究示例仓库源码中的mcp_tool_approval.py等模块佐证了 MCP 集成已具备实现。4.4 复用已有 Agent 定义与轮询限流复用定义调用await client.agents.get_agent(...)代替create_agent(...)即可引用已存在的 Agent见 step7_azure_ai_agent_retrieval.py轮询限流默认轮询间隔 250ms可通过RunPollingOptions调慢以减少 API 调用频次from datetime import timedelta from semantic_kernel.agents.run_polling_options import RunPollingOptions agent AzureAIAgent( clientclient, definitionagent_definition, polling_optionsRunPollingOptions(run_polling_intervaltimedelta(seconds1)), )也可以在 Azure AI Foundry 的部署设置中提高 “Tokens per minute” 限流配额。五、OpenAI Assistant Agent云端会话式助手OpenAI Assistant Agent 基于 Assistants API会话历史由服务端线程自动维护客户端无需自己保存上下文。示例位于 python/samples/getting_started_with_agents/openai_assistant/。step1_assistant.py 展示了完整流程from semantic_kernel.agents import AssistantAgentThread, AzureAssistantAgent from semantic_kernel.connectors.ai.open_ai import AzureOpenAISettings # 1. 创建客户端此处为 Azure OpenAI 资源 client AzureAssistantAgent.create_client(credentialAzureCliCredential()) # 2. 在服务端创建 Assistant definition await client.beta.assistants.create( modelAzureOpenAISettings().chat_deployment_name, instructionsAnswer questions about the world in one sentence., nameAssistant, ) # 3. 包装为 Semantic Kernel Agent agent AzureAssistantAgent(clientclient, definitiondefinition) # 4. 对话线程由服务端维护 thread: AssistantAgentThread None try: for user_input in USER_INPUTS: response await agent.get_response(messagesuser_input, threadthread) print(f# {response.name}: {response}) thread response.thread finally: # 5. 清理删除线程与云端 Assistant await thread.delete() if thread else None await agent.client.beta.assistants.delete(assistant_idagent.id)相比 Chat Completion Agent这里多出“创建服务端 Assistant 定义”与“结束时删除云端资源”两步体现了云端托管 Agent 的生命周期管理。README 列出的其余 step 进一步覆盖step2_assistant_plugins.py为 Assistant 挂载插件step3_assistant_vision.py以图片作为输入视觉能力step4_assistant_tool_code_interpreter.py 与 step5_assistant_tool_file_search.pyCode Interpreter 与 File Search 工具step6_assistant_declarative.py声明式创建。六、OpenAI Responses Agent新一代有状态 APIResponses API 是 OpenAI 最新一代的核心 API 与 agentic 原语融合了 Chat Completions 与 Assistants 两套 API 的能力。示例位于 python/samples/getting_started_with_agents/openai_responses/详细说明见 openai_responses/README.md。6.1 无状态最小示例step1_responses_agent.py 展示了不使用线程的“无状态 Agent”——它无法回忆之前的对话示例中最后一问 “What is my name?” 无法回答即为预期行为from semantic_kernel.agents import AzureResponsesAgent from semantic_kernel.connectors.ai.open_ai import AzureOpenAISettings client AzureResponsesAgent.create_client(credentialAzureCliCredential()) agent AzureResponsesAgent( ai_model_idAzureOpenAISettings().responses_deployment_name, clientclient, instructionsAnswer questions about the world in one sentence., nameExpert, ) for user_input in USER_INPUTS: response await agent.get_response(messagesuser_input) print(f# {response.name}: {response.content})注意模型 ID 来自AzureOpenAISettings().responses_deployment_name对应环境变量AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME。6.2 配置与环境变量OpenAI Responses Agent 对应环境变量OPENAI_RESPONSES_MODEL_IDAzure Responses Agent 依赖 Azure OpenAI 新的有状态 API要求 API 版本为2025-03-01-preview或更新即设置AZURE_OPENAI_API_VERSION2025-03-01-preview其余 Azure OpenAI 配置如AZURE_OPENAI_ENDPOINT与 Assistant / Chat Completion 共用可直接复用当前版本暂不支持 Computer User Agent Tool官方计划中尚未实现。6.3 Responses 专题能力step2_responses_agent_thread_management.py 通过ResponsesAgentThread恢复有状态对话其余 step 覆盖插件、Web Search预览工具、File Search、视觉输入、结构化输出与声明式创建。七、多 Agent 编排Multi-Agent Orchestration当任务需要多个 Agent 协作完成时可以使用 multi_agent_orchestration 下的编排能力。其说明见 multi_agent_orchestration/README.md实现位于 python/semantic_kernel/agents/orchestration/。7.1 五种编排模式编排适用场景Concurrent并发任务适合多个 Agent 独立分析、并行产出Sequential顺序任务有清晰的步骤依赖需逐步执行Handoff交接任务动态变化没有固定步骤按需把工作交接给合适 AgentGroupChat群聊任务需要多个 Agent 共同参与、高度可配置的对话流Magentic类似 Group Chat但由基于规划器的 Manager 驱动灵感来自 Microsoft 的 Magentic One 研究对应 step 示例并发见 step1_concurrent.py含结构化输出变体 step1a、顺序见 step2_sequential.py含取消令牌变体 step2a、群聊见 step3_group_chat.py、交接见 step4_handoff.py、Magentic 见 step5_magentic.py。目录下还提供了observability.py用于编排的可观测性演示。7.2 Group Chat 新实现GroupChatOrchestrationstep3_group_chat.py 展示了新的群聊编排方式把 Manager 视为状态机请求用户消息 → 终止并筛选结果 → 选择下一位发言 Agent配合进程内运行时运行from semantic_kernel.agents import ChatCompletionAgent, GroupChatOrchestration, RoundRobinGroupChatManager from semantic_kernel.agents.runtime import InProcessRuntime agents get_agents() # [Writer, Reviewer] group_chat_orchestration GroupChatOrchestration( membersagents, managerRoundRobinGroupChatManager(max_rounds5), agent_response_callbackagent_response_callback, ) runtime InProcessRuntime() runtime.start() orchestration_result await group_chat_orchestration.invoke( taskCreate a slogan for a new electric SUV that is affordable and fun to drive., runtimeruntime, ) value await orchestration_result.get() await runtime.stop_when_idle()要点RoundRobinGroupChatManager按成员列表顺序轮流发言max_rounds控制总轮数agent_response_callback作为观察者函数可实时打印每个 Agent 的消息需要显式runtime.start()与runtime.stop_when_idle()管理运行时生命周期。7.3 旧版 AgentGroupChat 与迁移提示step06_chat_completion_agent_group_chat.py 使用了旧的AgentGroupChat 自定义TerminationStrategy模式源码文件头注释明确指出AgentGroupChat已不再维护推荐迁移到GroupChatOrchestration。旧模式通过子类化TerminationStrategy并实现should_agent_terminate控制何时结束例如“当评审 Agent 说出 approved 时终止”class ApprovalTerminationStrategy(TerminationStrategy): async def should_agent_terminate(self, agent, history): last_message history[-1].content.lower() return approved in last_message and not approved not in last_message group_chat AgentGroupChat( agents[agent_writer, agent_reviewer], termination_strategyApprovalTerminationStrategy( agents[agent_reviewer], maximum_iterations10, ), ) await group_chat.add_chat_message(messageTASK) async for content in group_chat.invoke(): print(f# {content.name}: {content.content})新老对比旧模式把“轮流发言”与“终止判断”写死在AgentGroupChat内部新模式通过GroupChatOrchestration 可插拔 Manager 解耦了这两件事。新编写代码应优先采用后者。终止/选择策略的抽象实现位于 python/semantic_kernel/agents/strategies/。八、配置 Kernel 与运行环境8.1 密钥与环境变量与 Semantic Kernel 的 concept 示例一致Agent 示例同样需要配置模型服务的密钥。请参考 python/samples/concepts/README.md 中的 “Configuring the Kernel” 指南按所选 AI 服务设置对应的.env变量Azure OpenAIAZURE_OPENAI_API_KEY、AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_CHAT_DEPLOYMENT_NAME、AZURE_OPENAI_API_VERSION等OpenAIOPENAI_API_KEY、OPENAI_CHAT_MODEL_ID等Azure AI Agent 专属变量AZURE_AI_AGENT_ENDPOINT、AZURE_AI_AGENT_MODEL_DEPLOYMENT_NAME、AZURE_AI_AGENT_API_VERSION见 azure_ai_agent/README.mdResponses Agent 额外变量OPENAI_RESPONSES_MODEL_ID或AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME见 openai_responses/README.md。建议把.env放在项目根目录使用 VSCode 时会自动加载使下面的代码无需显式传参即可工作from semantic_kernel.agents import ChatCompletionAgent from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion agent ChatCompletionAgent( serviceAzureChatCompletion(), # 通过环境变量自动完成配置 nameAssistant, instructionsAnswer questions about the world in one sentence., )若偏好手动配置也可在构造器中显式传入api_key、endpoint、deployment_name、api_version例如api_version2025-03-01-preview。8.2 运行方式示例既可在 IDE 中直接运行也可通过命令行执行。在配置好对应 AI 连接器的 API Key 后示例无需任何额外命令行参数即可运行。例如cd python/samples/getting_started_with_agents/chat_completion python step01_chat_completion_agent_simple.py使用 Azure 服务的示例需要先执行az login完成 Azure CLI 认证使用 OpenAI / 其他模型服务时可参考多 Agent 编排的 multi_agent_orchestration/README.md 与 python/samples/concepts/setup/ 的环境变量设置说明将示例中的服务替换为对应厂商的连接器。九、推荐学习路径结合 README 的示例编排建议按以下顺序循序渐进Chat Completion 专题step01→step11掌握 Agent 的最小形态、线程、Kernel 与插件注入再进阶 JSON / 结构化输出 / 日志 / 声明式OpenAI Responses 专题step1→step8理解新一代有状态 API 与无状态/有状态线程的差异Azure AI Agent 与 OpenAI Assistant体验云端托管 Agent 的生命周期与 Code Interpreter、File Search、OpenAPI 等工具链多 Agent 编排step1→step5按并发 → 顺序 → 群聊 → 交接 → Magentic 的顺序理解五种协作模式的取舍如需深入框架实现可从 python/semantic_kernel/agents/ 的agent.py、chat_completion/、orchestration/模块入手结合各step示例反向印证调用链。【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Semantic Kernel Python Agent 快速上手：从 Chat Completion 到多 Agent 编排的完整实战指南

相关推荐

基于 Zeek 检测 DNS 数据外渗：dns.log 字段解析、熵分析与多工具联动实战

Vue Router 核心原理与SPA路由实战指南

SpacetimeDB 客户端连接完全指南：DbConnection 构建器、WebSocket 生命周期与多语言实践

更多资讯

克制的美学：为什么我的界面永远只有一个主行动点

秋季新出三款小型创意模型速评：性价比与手账画风实测

手账字体子集化流水线：字蛛与 pyftsubset 实战

Python数据可视化：Plotly交互式图表实战指南

多级蒙特卡洛方法在电力系统连锁故障风险评估中的应用

Semantic Kernel Python Agent 快速上手：从 Chat Completion 到多 Agent 编排的完整实战指南

今日更新

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？