戰(zhàn)指南)
Semantic Kernel Python Agent 快速上手從 Chat Completion 到多 Agent 編排的完整實(shí)戰(zhàn)指南【免費(fèi)下載鏈接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps項(xiàng)目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel本指南以 python/samples/getting_started_with_agents/README.md 為主線系統(tǒng)講解 Semantic Kernel Python 中 Agent智能體框架的入門路徑從最基礎(chǔ)的 Chat Completion Agent到 Azure AI Agent、OpenAI Assistant Agent、OpenAI Responses Agent再到多 Agent 并發(fā)、順序、Group Chat、Handoff 與 Magentic 編排。讀完本文你將掌握各類 Agent 的適用場景、版本約束、環(huán)境配置方法并能直接運(yùn)行倉庫中的 40 個 step 示例代碼構(gòu)建自己的單 Agent 對話與多 Agent 協(xié)作應(yīng)用。一、Agent 框架概覽與版本要求Semantic Kernel 的 Agent 框架位于 python/semantic_kernel/agents/ 目錄內(nèi)部按能力劃分模塊chat_completionChat Completion Agent、open_aiOpenAI Assistant / Responses Agent、azure_aiAzure AI Agent、group_chat與orchestration多 Agent 協(xié)作、strategies選擇與終止策略以及runtime進(jìn)程內(nèi)運(yùn)行時。由于不同 Agent 類型依賴不同的底層服務(wù) API各功能的可用性對應(yīng)了不同的 PyPI 最低版本當(dāng)前倉庫 README 明確給出功能最低 PyPI 版本Chat Completion Agent1.3.0OpenAI Assistant Agent1.4.0Agent Group Chat1.6.0Streaming OpenAI Assistant Agent1.11.0OpenAI Responses Agent1.27.0從源碼結(jié)構(gòu)看這一版本梯度與各模塊引入的時間線一致Chat Completion Agent 最先穩(wěn)定open_ai模塊中的azure_responses_agent.py、openai_responses_agent.py是較晚加入的。實(shí)際使用中建議直接安裝最新版pip install semantic-kernel即可覆蓋以上全部能力。二、示例總覽五個專題、四十余個 step入門示例按專題組織在 python/samples/getting_started_with_agents/ 下包括chat_completion/基于 Chat Completion 服務(wù)的本地 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 都是可直接獨(dú)立運(yùn)行的完整腳本命名遵循stepNN_主題.py的慣例由淺入深地遞進(jìn)。下文按 README 的順序逐一展開。三、Chat Completion Agent最基礎(chǔ)的 Agent 形態(tài)Chat Completion Agent 是理解整個框架的入口。它不依賴云端 Agent 服務(wù)而是由 Semantic Kernel 在本地用 AI 服務(wù)連接器包裝出一個具有 Agent 會話能力的對象。對應(yīng)源碼見 python/semantic_kernel/agents/chat_completion/chat_completion_agent.py。3.1 最小可用示例step01_chat_completion_agent_simple.py 演示了最基礎(chǔ)的用法把 AI 服務(wù)直接傳入ChatCompletionAgent構(gòu)造器用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. 創(chuàng)建 Agent直接指定底層 AI 服務(wù) 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 獲取響應(yīng) response await agent.get_response(messagesuser_input) print(f# {response.name}: {response}) if __name__ __main__: asyncio.run(main())關(guān)鍵點(diǎn)service參數(shù)接收任意ChatCompletionClientBase實(shí)現(xiàn)這里使用的是AzureChatCompletionname定義 Agent 名字instructions定義系統(tǒng)提示詞get_response是統(tǒng)一的交互入口傳入messages字符串或消息列表返回包含name與內(nèi)容的結(jié)果對象所有示例均為async風(fēng)格入口統(tǒng)一使用asyncio.run(main())。3.2 會話線程管理step02_chat_completion_agent_thread_management.py 展示了多輪對話的關(guān)鍵——線程Thread。Chat Completion Agent 本身不保存狀態(tài)會話歷史由調(diào)用方通過ChatHistoryAgentThread維護(hù)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}) # 將返回的線程保存下來供下一輪繼續(xù)使用 thread response.thread # 會話結(jié)束后的清理 await thread.delete() if thread else None注意若未傳入threadAgent 會在首次響應(yīng)時新建線程并隨響應(yīng)返回thread.delete()用于釋放會話資源。從示例輸出可以看到第三問 “What is my name?” 能正確回憶出第一輪 “I am John Doe.”這正是線程攜帶上下文的體現(xiàn)。3.3 通過 Kernel 注入服務(wù)與插件README 中的 step03step05 展示了兩種組織方式step03_chat_completion_agent_with_kernel.py在Kernel上注冊 AI 服務(wù)后將Kernel傳入 Agent 構(gòu)造器step04_chat_completion_agent_plugin_simple.py通過構(gòu)造器直接指定帶插件的 Kernelstep05_chat_completion_agent_plugin_with_kernel.py在 Kernel 上注冊插件PluginAgent 自動獲得調(diào)用函數(shù)的能力。推薦用 Kernel 承載服務(wù)與插件的注冊這樣 Agent 與 Kernel 共享同一套依賴管理便于后續(xù)擴(kuò)展 Function Calling。3.4 高級能力JSON 輸出、結(jié)構(gòu)化輸出與日志step08_chat_completion_agent_json_result.py讓 Agent 以 JSON 格式返回結(jié)果step10_chat_completion_agent_structured_outputs.py使用模型的結(jié)構(gòu)化輸出Structured Outputs能力聲明式約束返回的 JSON Schemastep09_chat_completion_agent_logging.py開啟 Agent 日志便于排查調(diào)用鏈路。3.5 聲明式 AgentDeclarative Agentstep11_chat_completion_agent_declarative.py 演示如何從聲明式規(guī)范spec創(chuàng)建 Agent。這種方式把 Agent 的定義名稱、指令、所用服務(wù)與代碼解耦便于配置化管理語義上與multi_agent_orchestration和azure_ai_agent中的聲明式 step 一脈相承。四、Azure AI Agent云托管式 AgentAzure AI Agent 由 Azure AI Foundry 托管運(yùn)行Agent 的線程、工具、運(yùn)行狀態(tài)都在云端管理客戶端通過AzureAIAgent封裝訪問。示例位于 python/samples/getting_started_with_agents/azure_ai_agent/其專屬說明見 azure_ai_agent/README.md。4.1 環(huán)境配置在項(xiàng)目根目錄的.env中配置三項(xiàng)必需變量注意變量名以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 客戶端創(chuàng)建與 Agent 定義與 Chat Completion Agent 不同Azure AI Agent 需要先創(chuàng)建服務(wù)端客戶端再創(chuàng)建云端 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. 在云端創(chuàng)建 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. 創(chuàng)建線程、添加消息并調(diào)用運(yùn)行前需先執(zhí)行az login完成 Azure CLI 認(rèn)證。4.3 工具鏈Code Interpreter / File Search / OpenAPI / MCPREADME 列出的一系列 step 覆蓋了云端工具能力step04_azure_ai_agent_code_interpreter.py使用 Code Interpreter 工具執(zhí)行代碼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 集成已具備實(shí)現(xiàn)。4.4 復(fù)用已有 Agent 定義與輪詢限流復(fù)用定義調(diào)用await client.agents.get_agent(...)代替create_agent(...)即可引用已存在的 Agent見 step7_azure_ai_agent_retrieval.py輪詢限流默認(rèn)輪詢間隔 250ms可通過RunPollingOptions調(diào)慢以減少 API 調(diào)用頻次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 的部署設(shè)置中提高 “Tokens per minute” 限流配額。五、OpenAI Assistant Agent云端會話式助手OpenAI Assistant Agent 基于 Assistants API會話歷史由服務(wù)端線程自動維護(hù)客戶端無需自己保存上下文。示例位于 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. 創(chuàng)建客戶端此處為 Azure OpenAI 資源 client AzureAssistantAgent.create_client(credentialAzureCliCredential()) # 2. 在服務(wù)端創(chuàng)建 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. 對話線程由服務(wù)端維護(hù) 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這里多出“創(chuàng)建服務(wù)端 Assistant 定義”與“結(jié)束時刪除云端資源”兩步體現(xiàn)了云端托管 Agent 的生命周期管理。README 列出的其余 step 進(jìn)一步覆蓋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聲明式創(chuàng)建。六、OpenAI Responses Agent新一代有狀態(tài) APIResponses API 是 OpenAI 最新一代的核心 API 與 agentic 原語融合了 Chat Completions 與 Assistants 兩套 API 的能力。示例位于 python/samples/getting_started_with_agents/openai_responses/詳細(xì)說明見 openai_responses/README.md。6.1 無狀態(tài)最小示例step1_responses_agent.py 展示了不使用線程的“無狀態(tài) Agent”——它無法回憶之前的對話示例中最后一問 “What is my name?” 無法回答即為預(yù)期行為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對應(yīng)環(huán)境變量AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME。6.2 配置與環(huán)境變量OpenAI Responses Agent 對應(yīng)環(huán)境變量OPENAI_RESPONSES_MODEL_IDAzure Responses Agent 依賴 Azure OpenAI 新的有狀態(tài) API要求 API 版本為2025-03-01-preview或更新即設(shè)置AZURE_OPENAI_API_VERSION2025-03-01-preview其余 Azure OpenAI 配置如AZURE_OPENAI_ENDPOINT與 Assistant / Chat Completion 共用可直接復(fù)用當(dāng)前版本暫不支持 Computer User Agent Tool官方計(jì)劃中尚未實(shí)現(xiàn)。6.3 Responses 專題能力step2_responses_agent_thread_management.py 通過ResponsesAgentThread恢復(fù)有狀態(tài)對話其余 step 覆蓋插件、Web Search預(yù)覽工具、File Search、視覺輸入、結(jié)構(gòu)化輸出與聲明式創(chuàng)建。七、多 Agent 編排Multi-Agent Orchestration當(dāng)任務(wù)需要多個 Agent 協(xié)作完成時可以使用 multi_agent_orchestration 下的編排能力。其說明見 multi_agent_orchestration/README.md實(shí)現(xiàn)位于 python/semantic_kernel/agents/orchestration/。7.1 五種編排模式編排適用場景Concurrent并發(fā)任務(wù)適合多個 Agent 獨(dú)立分析、并行產(chǎn)出Sequential順序任務(wù)有清晰的步驟依賴需逐步執(zhí)行Handoff交接任務(wù)動態(tài)變化沒有固定步驟按需把工作交接給合適 AgentGroupChat群聊任務(wù)需要多個 Agent 共同參與、高度可配置的對話流Magentic類似 Group Chat但由基于規(guī)劃器的 Manager 驅(qū)動靈感來自 Microsoft 的 Magentic One 研究對應(yīng) step 示例并發(fā)見 step1_concurrent.py含結(jié)構(gòu)化輸出變體 step1a、順序見 step2_sequential.py含取消令牌變體 step2a、群聊見 step3_group_chat.py、交接見 step4_handoff.py、Magentic 見 step5_magentic.py。目錄下還提供了observability.py用于編排的可觀測性演示。7.2 Group Chat 新實(shí)現(xiàn)GroupChatOrchestrationstep3_group_chat.py 展示了新的群聊編排方式把 Manager 視為狀態(tài)機(jī)請求用戶消息 → 終止并篩選結(jié)果 → 選擇下一位發(fā)言 Agent配合進(jìn)程內(nèi)運(yùn)行時運(yùn)行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()要點(diǎn)RoundRobinGroupChatManager按成員列表順序輪流發(fā)言max_rounds控制總輪數(shù)agent_response_callback作為觀察者函數(shù)可實(shí)時打印每個 Agent 的消息需要顯式runtime.start()與runtime.stop_when_idle()管理運(yùn)行時生命周期。7.3 舊版 AgentGroupChat 與遷移提示step06_chat_completion_agent_group_chat.py 使用了舊的AgentGroupChat 自定義TerminationStrategy模式源碼文件頭注釋明確指出AgentGroupChat已不再維護(hù)推薦遷移到GroupChatOrchestration。舊模式通過子類化TerminationStrategy并實(shí)現(xiàn)should_agent_terminate控制何時結(jié)束例如“當(dāng)評審 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})新老對比舊模式把“輪流發(fā)言”與“終止判斷”寫死在AgentGroupChat內(nèi)部新模式通過GroupChatOrchestration 可插拔 Manager 解耦了這兩件事。新編寫代碼應(yīng)優(yōu)先采用后者。終止/選擇策略的抽象實(shí)現(xiàn)位于 python/semantic_kernel/agents/strategies/。八、配置 Kernel 與運(yùn)行環(huán)境8.1 密鑰與環(huán)境變量與 Semantic Kernel 的 concept 示例一致Agent 示例同樣需要配置模型服務(wù)的密鑰。請參考 python/samples/concepts/README.md 中的 “Configuring the Kernel” 指南按所選 AI 服務(wù)設(shè)置對應(yīng)的.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放在項(xiàng)目根目錄使用 VSCode 時會自動加載使下面的代碼無需顯式傳參即可工作from semantic_kernel.agents import ChatCompletionAgent from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion agent ChatCompletionAgent( serviceAzureChatCompletion(), # 通過環(huán)境變量自動完成配置 nameAssistant, instructionsAnswer questions about the world in one sentence., )若偏好手動配置也可在構(gòu)造器中顯式傳入api_key、endpoint、deployment_name、api_version例如api_version2025-03-01-preview。8.2 運(yùn)行方式示例既可在 IDE 中直接運(yùn)行也可通過命令行執(zhí)行。在配置好對應(yīng) AI 連接器的 API Key 后示例無需任何額外命令行參數(shù)即可運(yùn)行。例如cd python/samples/getting_started_with_agents/chat_completion python step01_chat_completion_agent_simple.py使用 Azure 服務(wù)的示例需要先執(zhí)行az login完成 Azure CLI 認(rèn)證使用 OpenAI / 其他模型服務(wù)時可參考多 Agent 編排的 multi_agent_orchestration/README.md 與 python/samples/concepts/setup/ 的環(huán)境變量設(shè)置說明將示例中的服務(wù)替換為對應(yīng)廠商的連接器。九、推薦學(xué)習(xí)路徑結(jié)合 README 的示例編排建議按以下順序循序漸進(jìn)Chat Completion 專題step01→step11掌握 Agent 的最小形態(tài)、線程、Kernel 與插件注入再進(jìn)階 JSON / 結(jié)構(gòu)化輸出 / 日志 / 聲明式OpenAI Responses 專題step1→step8理解新一代有狀態(tài) API 與無狀態(tài)/有狀態(tài)線程的差異Azure AI Agent 與 OpenAI Assistant體驗(yàn)云端托管 Agent 的生命周期與 Code Interpreter、File Search、OpenAPI 等工具鏈多 Agent 編排step1→step5按 并發(fā) → 順序 → 群聊 → 交接 → Magentic 的順序理解五種協(xié)作模式的取舍如需深入框架實(shí)現(xiàn)可從 python/semantic_kernel/agents/ 的agent.py、chat_completion/、orchestration/模塊入手結(jié)合各step示例反向印證調(diào)用鏈?！久赓M(fèi)下載鏈接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps項(xiàng)目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Semantic Kernel Python Agent 快速上手：從 Chat Completion 到多 Agent 編排的完整實(shí)戰(zhàn)指南
Semantic Kernel Python Agent 快速上手從 Chat Completion 到多 Agent 編排的完整實(shí)戰(zhàn)指南【免費(fèi)下載鏈接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps項(xiàng)目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel本指南以 python/samples/getting_started_with_agents/README.md 為主線系統(tǒng)講解 Semantic Kernel Python 中 Agent智能體框架的入門路徑從最基礎(chǔ)的 Chat Completion Agent到 Azure AI Agent、OpenAI Assistant Agent、OpenAI Responses Agent再到多 Agent 并發(fā)、順序、Group Chat、Handoff 與 Magentic 編排。讀完本文你將掌握各類 Agent 的適用場景、版本約束、環(huán)境配置方法并能直接運(yùn)行倉庫中的 40 個 step 示例代碼構(gòu)建自己的單 Agent 對話與多 Agent 協(xié)作應(yīng)用。一、Agent 框架概覽與版本要求Semantic Kernel 的 Agent 框架位于 python/semantic_kernel/agents/ 目錄內(nèi)部按能力劃分模塊chat_completionChat Completion Agent、open_aiOpenAI Assistant / Responses Agent、azure_aiAzure AI Agent、group_chat與orchestration多 Agent 協(xié)作、strategies選擇與終止策略以及runtime進(jìn)程內(nèi)運(yùn)行時。由于不同 Agent 類型依賴不同的底層服務(wù) API各功能的可用性對應(yīng)了不同的 PyPI 最低版本當(dāng)前倉庫 README 明確給出功能最低 PyPI 版本Chat Completion Agent1.3.0OpenAI Assistant Agent1.4.0Agent Group Chat1.6.0Streaming OpenAI Assistant Agent1.11.0OpenAI Responses Agent1.27.0從源碼結(jié)構(gòu)看這一版本梯度與各模塊引入的時間線一致Chat Completion Agent 最先穩(wěn)定open_ai模塊中的azure_responses_agent.py、openai_responses_agent.py是較晚加入的。實(shí)際使用中建議直接安裝最新版pip install semantic-kernel即可覆蓋以上全部能力。二、示例總覽五個專題、四十余個 step入門示例按專題組織在 python/samples/getting_started_with_agents/ 下包括chat_completion/基于 Chat Completion 服務(wù)的本地 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 都是可直接獨(dú)立運(yùn)行的完整腳本命名遵循stepNN_主題.py的慣例由淺入深地遞進(jìn)。下文按 README 的順序逐一展開。三、Chat Completion Agent最基礎(chǔ)的 Agent 形態(tài)Chat Completion Agent 是理解整個框架的入口。它不依賴云端 Agent 服務(wù)而是由 Semantic Kernel 在本地用 AI 服務(wù)連接器包裝出一個具有 Agent 會話能力的對象。對應(yīng)源碼見 python/semantic_kernel/agents/chat_completion/chat_completion_agent.py。3.1 最小可用示例step01_chat_completion_agent_simple.py 演示了最基礎(chǔ)的用法把 AI 服務(wù)直接傳入ChatCompletionAgent構(gòu)造器用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. 創(chuàng)建 Agent直接指定底層 AI 服務(wù) 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 獲取響應(yīng) response await agent.get_response(messagesuser_input) print(f# {response.name}: {response}) if __name__ __main__: asyncio.run(main())關(guān)鍵點(diǎn)service參數(shù)接收任意ChatCompletionClientBase實(shí)現(xiàn)這里使用的是AzureChatCompletionname定義 Agent 名字instructions定義系統(tǒng)提示詞get_response是統(tǒng)一的交互入口傳入messages字符串或消息列表返回包含name與內(nèi)容的結(jié)果對象所有示例均為async風(fēng)格入口統(tǒng)一使用asyncio.run(main())。3.2 會話線程管理step02_chat_completion_agent_thread_management.py 展示了多輪對話的關(guān)鍵——線程Thread。Chat Completion Agent 本身不保存狀態(tài)會話歷史由調(diào)用方通過ChatHistoryAgentThread維護(hù)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}) # 將返回的線程保存下來供下一輪繼續(xù)使用 thread response.thread # 會話結(jié)束后的清理 await thread.delete() if thread else None注意若未傳入threadAgent 會在首次響應(yīng)時新建線程并隨響應(yīng)返回thread.delete()用于釋放會話資源。從示例輸出可以看到第三問 “What is my name?” 能正確回憶出第一輪 “I am John Doe.”這正是線程攜帶上下文的體現(xiàn)。3.3 通過 Kernel 注入服務(wù)與插件README 中的 step03step05 展示了兩種組織方式step03_chat_completion_agent_with_kernel.py在Kernel上注冊 AI 服務(wù)后將Kernel傳入 Agent 構(gòu)造器step04_chat_completion_agent_plugin_simple.py通過構(gòu)造器直接指定帶插件的 Kernelstep05_chat_completion_agent_plugin_with_kernel.py在 Kernel 上注冊插件PluginAgent 自動獲得調(diào)用函數(shù)的能力。推薦用 Kernel 承載服務(wù)與插件的注冊這樣 Agent 與 Kernel 共享同一套依賴管理便于后續(xù)擴(kuò)展 Function Calling。3.4 高級能力JSON 輸出、結(jié)構(gòu)化輸出與日志step08_chat_completion_agent_json_result.py讓 Agent 以 JSON 格式返回結(jié)果step10_chat_completion_agent_structured_outputs.py使用模型的結(jié)構(gòu)化輸出Structured Outputs能力聲明式約束返回的 JSON Schemastep09_chat_completion_agent_logging.py開啟 Agent 日志便于排查調(diào)用鏈路。3.5 聲明式 AgentDeclarative Agentstep11_chat_completion_agent_declarative.py 演示如何從聲明式規(guī)范spec創(chuàng)建 Agent。這種方式把 Agent 的定義名稱、指令、所用服務(wù)與代碼解耦便于配置化管理語義上與multi_agent_orchestration和azure_ai_agent中的聲明式 step 一脈相承。四、Azure AI Agent云托管式 AgentAzure AI Agent 由 Azure AI Foundry 托管運(yùn)行Agent 的線程、工具、運(yùn)行狀態(tài)都在云端管理客戶端通過AzureAIAgent封裝訪問。示例位于 python/samples/getting_started_with_agents/azure_ai_agent/其專屬說明見 azure_ai_agent/README.md。4.1 環(huán)境配置在項(xiàng)目根目錄的.env中配置三項(xiàng)必需變量注意變量名以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 客戶端創(chuàng)建與 Agent 定義與 Chat Completion Agent 不同Azure AI Agent 需要先創(chuàng)建服務(wù)端客戶端再創(chuàng)建云端 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. 在云端創(chuàng)建 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. 創(chuàng)建線程、添加消息并調(diào)用運(yùn)行前需先執(zhí)行az login完成 Azure CLI 認(rèn)證。4.3 工具鏈Code Interpreter / File Search / OpenAPI / MCPREADME 列出的一系列 step 覆蓋了云端工具能力step04_azure_ai_agent_code_interpreter.py使用 Code Interpreter 工具執(zhí)行代碼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 集成已具備實(shí)現(xiàn)。4.4 復(fù)用已有 Agent 定義與輪詢限流復(fù)用定義調(diào)用await client.agents.get_agent(...)代替create_agent(...)即可引用已存在的 Agent見 step7_azure_ai_agent_retrieval.py輪詢限流默認(rèn)輪詢間隔 250ms可通過RunPollingOptions調(diào)慢以減少 API 調(diào)用頻次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 的部署設(shè)置中提高 “Tokens per minute” 限流配額。五、OpenAI Assistant Agent云端會話式助手OpenAI Assistant Agent 基于 Assistants API會話歷史由服務(wù)端線程自動維護(hù)客戶端無需自己保存上下文。示例位于 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. 創(chuàng)建客戶端此處為 Azure OpenAI 資源 client AzureAssistantAgent.create_client(credentialAzureCliCredential()) # 2. 在服務(wù)端創(chuàng)建 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. 對話線程由服務(wù)端維護(hù) 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這里多出“創(chuàng)建服務(wù)端 Assistant 定義”與“結(jié)束時刪除云端資源”兩步體現(xiàn)了云端托管 Agent 的生命周期管理。README 列出的其余 step 進(jìn)一步覆蓋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聲明式創(chuàng)建。六、OpenAI Responses Agent新一代有狀態(tài) APIResponses API 是 OpenAI 最新一代的核心 API 與 agentic 原語融合了 Chat Completions 與 Assistants 兩套 API 的能力。示例位于 python/samples/getting_started_with_agents/openai_responses/詳細(xì)說明見 openai_responses/README.md。6.1 無狀態(tài)最小示例step1_responses_agent.py 展示了不使用線程的“無狀態(tài) Agent”——它無法回憶之前的對話示例中最后一問 “What is my name?” 無法回答即為預(yù)期行為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對應(yīng)環(huán)境變量AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME。6.2 配置與環(huán)境變量OpenAI Responses Agent 對應(yīng)環(huán)境變量OPENAI_RESPONSES_MODEL_IDAzure Responses Agent 依賴 Azure OpenAI 新的有狀態(tài) API要求 API 版本為2025-03-01-preview或更新即設(shè)置AZURE_OPENAI_API_VERSION2025-03-01-preview其余 Azure OpenAI 配置如AZURE_OPENAI_ENDPOINT與 Assistant / Chat Completion 共用可直接復(fù)用當(dāng)前版本暫不支持 Computer User Agent Tool官方計(jì)劃中尚未實(shí)現(xiàn)。6.3 Responses 專題能力step2_responses_agent_thread_management.py 通過ResponsesAgentThread恢復(fù)有狀態(tài)對話其余 step 覆蓋插件、Web Search預(yù)覽工具、File Search、視覺輸入、結(jié)構(gòu)化輸出與聲明式創(chuàng)建。七、多 Agent 編排Multi-Agent Orchestration當(dāng)任務(wù)需要多個 Agent 協(xié)作完成時可以使用 multi_agent_orchestration 下的編排能力。其說明見 multi_agent_orchestration/README.md實(shí)現(xiàn)位于 python/semantic_kernel/agents/orchestration/。7.1 五種編排模式編排適用場景Concurrent并發(fā)任務(wù)適合多個 Agent 獨(dú)立分析、并行產(chǎn)出Sequential順序任務(wù)有清晰的步驟依賴需逐步執(zhí)行Handoff交接任務(wù)動態(tài)變化沒有固定步驟按需把工作交接給合適 AgentGroupChat群聊任務(wù)需要多個 Agent 共同參與、高度可配置的對話流Magentic類似 Group Chat但由基于規(guī)劃器的 Manager 驅(qū)動靈感來自 Microsoft 的 Magentic One 研究對應(yīng) step 示例并發(fā)見 step1_concurrent.py含結(jié)構(gòu)化輸出變體 step1a、順序見 step2_sequential.py含取消令牌變體 step2a、群聊見 step3_group_chat.py、交接見 step4_handoff.py、Magentic 見 step5_magentic.py。目錄下還提供了observability.py用于編排的可觀測性演示。7.2 Group Chat 新實(shí)現(xiàn)GroupChatOrchestrationstep3_group_chat.py 展示了新的群聊編排方式把 Manager 視為狀態(tài)機(jī)請求用戶消息 → 終止并篩選結(jié)果 → 選擇下一位發(fā)言 Agent配合進(jìn)程內(nèi)運(yùn)行時運(yùn)行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()要點(diǎn)RoundRobinGroupChatManager按成員列表順序輪流發(fā)言max_rounds控制總輪數(shù)agent_response_callback作為觀察者函數(shù)可實(shí)時打印每個 Agent 的消息需要顯式runtime.start()與runtime.stop_when_idle()管理運(yùn)行時生命周期。7.3 舊版 AgentGroupChat 與遷移提示step06_chat_completion_agent_group_chat.py 使用了舊的AgentGroupChat 自定義TerminationStrategy模式源碼文件頭注釋明確指出AgentGroupChat已不再維護(hù)推薦遷移到GroupChatOrchestration。舊模式通過子類化TerminationStrategy并實(shí)現(xiàn)should_agent_terminate控制何時結(jié)束例如“當(dāng)評審 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})新老對比舊模式把“輪流發(fā)言”與“終止判斷”寫死在AgentGroupChat內(nèi)部新模式通過GroupChatOrchestration 可插拔 Manager 解耦了這兩件事。新編寫代碼應(yīng)優(yōu)先采用后者。終止/選擇策略的抽象實(shí)現(xiàn)位于 python/semantic_kernel/agents/strategies/。八、配置 Kernel 與運(yùn)行環(huán)境8.1 密鑰與環(huán)境變量與 Semantic Kernel 的 concept 示例一致Agent 示例同樣需要配置模型服務(wù)的密鑰。請參考 python/samples/concepts/README.md 中的 “Configuring the Kernel” 指南按所選 AI 服務(wù)設(shè)置對應(yīng)的.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放在項(xiàng)目根目錄使用 VSCode 時會自動加載使下面的代碼無需顯式傳參即可工作from semantic_kernel.agents import ChatCompletionAgent from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion agent ChatCompletionAgent( serviceAzureChatCompletion(), # 通過環(huán)境變量自動完成配置 nameAssistant, instructionsAnswer questions about the world in one sentence., )若偏好手動配置也可在構(gòu)造器中顯式傳入api_key、endpoint、deployment_name、api_version例如api_version2025-03-01-preview。8.2 運(yùn)行方式示例既可在 IDE 中直接運(yùn)行也可通過命令行執(zhí)行。在配置好對應(yīng) AI 連接器的 API Key 后示例無需任何額外命令行參數(shù)即可運(yùn)行。例如cd python/samples/getting_started_with_agents/chat_completion python step01_chat_completion_agent_simple.py使用 Azure 服務(wù)的示例需要先執(zhí)行az login完成 Azure CLI 認(rèn)證使用 OpenAI / 其他模型服務(wù)時可參考多 Agent 編排的 multi_agent_orchestration/README.md 與 python/samples/concepts/setup/ 的環(huán)境變量設(shè)置說明將示例中的服務(wù)替換為對應(yīng)廠商的連接器。九、推薦學(xué)習(xí)路徑結(jié)合 README 的示例編排建議按以下順序循序漸進(jìn)Chat Completion 專題step01→step11掌握 Agent 的最小形態(tài)、線程、Kernel 與插件注入再進(jìn)階 JSON / 結(jié)構(gòu)化輸出 / 日志 / 聲明式OpenAI Responses 專題step1→step8理解新一代有狀態(tài) API 與無狀態(tài)/有狀態(tài)線程的差異Azure AI Agent 與 OpenAI Assistant體驗(yàn)云端托管 Agent 的生命周期與 Code Interpreter、File Search、OpenAPI 等工具鏈多 Agent 編排step1→step5按 并發(fā) → 順序 → 群聊 → 交接 → Magentic 的順序理解五種協(xié)作模式的取舍如需深入框架實(shí)現(xiàn)可從 python/semantic_kernel/agents/ 的agent.py、chat_completion/、orchestration/模塊入手結(jié)合各step示例反向印證調(diào)用鏈?！久赓M(fèi)下載鏈接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps項(xiàng)目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考