企业官网建设流程全解析

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_completion（Chat Completion Agent）、open_ai（OpenAI Assistant / Responses Agent）、azure_ai（Azure AI Agent）、group_chat与orchestration（多 Agent 协作）、strategies（选择与终止策略）以及runtime（进程内运行时）。

由于不同 Agent 类型依赖不同的底层服务 API，各功能的可用性对应了不同的 PyPI 最低版本（当前仓库 README 明确给出）：

从源码结构看，这一版本梯度与各模块引入的时间线一致：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 服务的本地 Agent，11 个 step；
• azure_ai_agent/：Azure AI Foundry（原 Azure AI Foundry）托管的 Agent，8 个 step；
• openai_assistant/：OpenAI Assistants API Agent，6 个 step；
• openai_responses/：OpenAI Responses API Agent，8 个 step；
• multi_agent_orchestration/：多 Agent 编排，10 个 step；
• copilot_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( service=AzureChatCompletion(credential=AzureCliCredential()), name="Assistant", instructions="Answer 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(messages=user_input) print(f"# {response.name}: {response}") if __name__ == "__main__": asyncio.run(main())

关键点：

• service参数接收任意ChatCompletionClientBase实现，这里使用的是AzureChatCompletion；name定义 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(messages=user_input, thread=thread) print(f"# {response.name}: {response}") # 将返回的线程保存下来，供下一轮继续使用 thread = response.thread # 会话结束后的清理 await thread.delete() if thread else None

注意：若未传入thread，Agent 会在首次响应时新建线程并随响应返回；thread.delete()用于释放会话资源。从示例输出可以看到，第三问 “What is my name?” 能正确回忆出第一轮 “I am John Doe.”，这正是线程携带上下文的体现。

3.3 通过 Kernel 注入服务与插件

README 中的 step03～step05 展示了两种组织方式：

• step03_chat_completion_agent_with_kernel.py：在Kernel上注册 AI 服务后，将Kernel传入 Agent 构造器；
• step04_chat_completion_agent_plugin_simple.py：通过构造器直接指定带插件的 Kernel；
• step05_chat_completion_agent_plugin_with_kernel.py：在 Kernel 上注册插件（Plugin），Agent 自动获得调用函数的能力。

推荐用 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 Schema；
• step09_chat_completion_agent_logging.py：开启 Agent 日志，便于排查调用链路。

3.5 声明式 Agent（Declarative Agent）

step11_chat_completion_agent_declarative.py 演示如何从声明式规范（spec）创建 Agent。这种方式把 Agent 的定义（名称、指令、所用服务）与代码解耦，便于配置化管理，语义上与multi_agent_orchestration和azure_ai_agent中的声明式 step 一脉相承。

四、Azure AI Agent：云托管式 Agent

Azure 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 Agent：

from 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( credential=creds, endpoint=ai_agent_settings.endpoint, api_version=ai_agent_settings.api_version, ) as client, ): # 1. 在云端创建 Agent 定义 agent_definition = await client.agents.create_agent( model=ai_agent_settings.model_deployment_name, name=AGENT_NAME, instructions=AGENT_INSTRUCTIONS, ) # 2. 包装为 Semantic Kernel Agent agent = AzureAIAgent(client=client, definition=agent_definition) # 3. 创建线程、添加消息并调用

运行前需先执行az login完成 Azure CLI 认证。

4.3 工具链：Code Interpreter / File Search / OpenAPI / MCP

README 列出的一系列 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.py（MCP 工具）与 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( client=client, definition=agent_definition, polling_options=RunPollingOptions(run_polling_interval=timedelta(seconds=1)), )

也可以在 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(credential=AzureCliCredential()) # 2. 在服务端创建 Assistant definition = await client.beta.assistants.create( model=AzureOpenAISettings().chat_deployment_name, instructions="Answer questions about the world in one sentence.", name="Assistant", ) # 3. 包装为 Semantic Kernel Agent agent = AzureAssistantAgent(client=client, definition=definition) # 4. 对话（线程由服务端维护） thread: AssistantAgentThread = None try: for user_input in USER_INPUTS: response = await agent.get_response(messages=user_input, thread=thread) 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_id=agent.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.py：Code Interpreter 与 File Search 工具；
• step6_assistant_declarative.py：声明式创建。

六、OpenAI Responses Agent：新一代有状态 API

Responses 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(credential=AzureCliCredential()) agent = AzureResponsesAgent( ai_model_id=AzureOpenAISettings().responses_deployment_name, client=client, instructions="Answer questions about the world in one sentence.", name="Expert", ) for user_input in USER_INPUTS: response = await agent.get_response(messages=user_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_ID=""；
• Azure Responses Agent 依赖 Azure OpenAI 新的有状态 API，要求 API 版本为2025-03-01-preview或更新，即设置AZURE_OPENAI_API_VERSION="2025-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 五种编排模式

对应 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 新实现：GroupChatOrchestration

step3_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( members=agents, manager=RoundRobinGroupChatManager(max_rounds=5), agent_response_callback=agent_response_callback, ) runtime = InProcessRuntime() runtime.start() orchestration_result = await group_chat_orchestration.invoke( task="Create a slogan for a new electric SUV that is affordable and fun to drive.", runtime=runtime, ) 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_strategy=ApprovalTerminationStrategy( agents=[agent_reviewer], maximum_iterations=10, ), ) await group_chat.add_chat_message(message=TASK) 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 OpenAI：AZURE_OPENAI_API_KEY、AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_CHAT_DEPLOYMENT_NAME、AZURE_OPENAI_API_VERSION等；
• OpenAI：OPENAI_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.md）；
• Responses 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( service=AzureChatCompletion(), # 通过环境变量自动完成配置 name="Assistant", instructions="Answer questions about the world in one sentence.", )

若偏好手动配置，也可在构造器中显式传入api_key、endpoint、deployment_name、api_version（例如api_version="2025-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 的示例编排，建议按以下顺序循序渐进：

1. Chat Completion 专题（step01→step11）：掌握 Agent 的最小形态、线程、Kernel 与插件注入，再进阶 JSON / 结构化输出 / 日志 / 声明式；
2. OpenAI Responses 专题（step1→step8）：理解新一代有状态 API 与无状态/有状态线程的差异；
3. Azure AI Agent 与 OpenAI Assistant：体验云端托管 Agent 的生命周期与 Code Interpreter、File Search、OpenAPI 等工具链；
4. 多 Agent 编排（step1→step5）：按 并发 → 顺序 → 群聊 → 交接 → Magentic 的顺序，理解五种协作模式的取舍；
5. 如需深入框架实现，可从 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