微軟 microsoft/autogen 多代理框架實戰教學:非同步事件驅動架構與程式執行沙盒設定
微軟開源的 AutoGen 採用非同步事件驅動架構,支援多代理自動協作、人類介入審核與 Docker 程式碼沙盒,一篇整理核心模組、安裝步驟與實務避坑。
多數開發者第一次串接大型語言模型時,很快會撞上一堵牆。單一模型就算提示詞寫得再漂亮,遇到需要寫程式、查資料、再交給另一個角色驗收的任務,輸出品質還是會大幅滑落。
微軟開源的 microsoft/autogen 專案,正是為了把這種單兵作戰改成多代理協作而誕生。它讓不同專長的 AI 代理透過非同步事件驅動架構彼此傳遞訊息,還能把產生的程式碼丟進隔離沙盒安全執行。
不過在動手寫第一行程式之前,有一件關鍵現況必須先說清楚。根據微軟官方 GitHub 倉庫最新公告,AutoGen 目前已經轉為封存狀態,不再由微軟提供新功能開發或安全性修補,官方已將新專案的建議轉往 Microsoft Agent Framework。
即便如此,AutoGen 留下的 Core API、AgentChat API 與 Docker 執行沙盒設計,依然是理解多代理系統架構的最佳教材。這篇 AutoGen 教學會帶你拆解它的三層模組設計、完整安裝流程、MCP 工具串接與程式碼沙盒設定,同時整理從舊專案遷移與資安避坑的實務重點。
動手前先看清現況:AutoGen 封存與架構定位
在 GitHub 上搜尋多代理框架時,microsoft/autogen 依然擁有極高討論度,但開啟官方頁面就會看到醒目的紅色封存警示。微軟明確指出,AutoGen 最初是為了研究與實驗目的而開發,目前倉庫已進入封存與社群維護模式,官方不再提供漏洞修補或長期支援。
對技術團隊來說,這代表兩個明確的工程決策邊界。如果你的目標是把多代理服務正式部署到企業生產環境,微軟建議直接採用後繼者 Microsoft Agent Framework,以取得穩定的 API 與跨執行期互通支援。但如果你正在維護既有的 AutoGen 系統、進行學術原型實驗,或是想學習事件驅動的多代理底層設計,這套框架依然非常值得拆解研究。
AutoGen 之所以能在開源社群形成標準,關鍵在於它把複雜的代理協作拆成三個職責分明的層級,讓開發者能依照需求選擇抽象程度。
- Core API:位於最底層,負責訊息傳遞、事件驅動代理生命週期管理,以及本機與分散式執行環境,並同時支援 Python 與 .NET 雙語言。
- AgentChat API:建構在 Core API 之上的高階介面,專注於快速原型開發,提供開發者熟悉的雙代理對話、團隊協作與人類介入審核模式。
- Extensions API:負責與外部世界對接的擴充套件層,包含 OpenAI 與 Azure OpenAI 等模型用戶端實作,以及 Docker 程式碼執行器與 MCP 工具橋接。
除了這三層程式庫之外,生態系還包含兩款輔助工具。AutoGen Studio 提供免寫程式的視覺化介面來組裝工作流,AutoGen Bench 則用來量化評估不同代理組合的任務表現。這五個元件組成了完整的多代理實驗室,讓工程師不必從零刻出訊息匯流排與工具呼叫迴圈。

AutoGen 教學實作:Python 環境安裝與快速上手
要在本機跑通 AutoGen,系統必須先安裝 Python 3.10 或更新版本。官方把核心對話介面與模型擴充拆成獨立套件,因此在建立虛擬環境後,第一步就是安裝 autogen-agentchat 與支援 OpenAI 模型的 autogen-ext。
# 建立並啟用虛擬環境後,安裝 AgentChat 與 OpenAI 擴充套件
pip install -U "autogen-agentchat" "autogen-ext[openai]"
如果你希望透過圖形介面拖拉代理流程,可以額外安裝 AutoGen Studio。官方特別提醒這個介面僅適合快速原型展示,並沒有內建生產等級的身份驗證與存取控制,千萬不要直接對外公開埠號。
# 選用安裝:啟動本機視覺化原型介面 AutoGen Studio
pip install -U "autogenstudio"
autogenstudio ui --port 8080 --appdir ./my-app
執行程式碼前,請先在終端機匯出模型金鑰環境變數 export OPENAI_API_KEY="sk-..."。接著我們用一段極簡的非同步腳本,確認 AssistantAgent 與 OpenAIChatCompletionClient 是否能正常運作。
import asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient
async def main() -> None:
model_client = OpenAIChatCompletionClient(model="gpt-4.1")
agent = AssistantAgent("assistant", model_client=model_client)
result = await agent.run(task="請用一句話說明什麼是事件驅動架構。")
print(result)
await model_client.close()
asyncio.run(main())
這段程式碼雖然只有十幾行,卻完整體現了新版 AutoGen 與早期 0.2 版本的設計差異。所有模型呼叫與代理回應都改採 asyncio 非同步執行,並且在結束時明確關閉 model_client 連線池,避免長期執行下發生網路資源洩漏。
多代理協作設計:用 AgentTool 組裝專家團隊
單一代理只適合處理線性問答,真正的多代理威力在於「分派任務與交叉驗證」。在最新版的 AgentChat 架構中,開發者除了傳統的群組對話之外,還可以直接透過 AgentTool 把專業代理包裝成工具,交給一位總控協調代理依情境呼叫。
這種模式的優勢在於權責邊界非常清楚。數學專家代理只專注在推導算式,化學專家代理只負責計算分子量,總控代理則扮演專案經理,決定何時該呼叫哪位專家、何時該把結果整理給使用者。
import asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.tools import AgentTool
from autogen_agentchat.ui import Console
from autogen_ext.models.openai import OpenAIChatCompletionClient
async def main() -> None:
model_client = OpenAIChatCompletionClient(model="gpt-4.1")
math_agent = AssistantAgent(
"math_expert",
model_client=model_client,
system_message="你是數學專家,擅長微積分與代數推導。",
description="負責解答數學計算與公式推導的專家代理。",
model_client_stream=True,
)
math_agent_tool = AgentTool(math_agent, return_value_as_last_message=True)
chemistry_agent = AssistantAgent(
"chemistry_expert",
model_client=model_client,
system_message="你是化學專家,擅長化學計量與反應式分析。",
description="負責解答化學性質與分子量計算的專家代理。",
model_client_stream=True,
)
chemistry_agent_tool = AgentTool(chemistry_agent, return_value_as_last_message=True)
coordinator = AssistantAgent(
"assistant",
system_message="你是總控助理,遇到專業問題時請呼叫對應的專家工具。",
model_client=model_client,
model_client_stream=True,
tools=[math_agent_tool, chemistry_agent_tool],
max_tool_iterations=10,
)
await Console(coordinator.run_stream(task="請計算 x 平方的積分,並說明水的分子量。"))
await model_client.close()
asyncio.run(main())
請特別留意程式碼中的 max_tool_iterations=10 參數。在多代理互動的世界裡,如果沒有設定最大工具呼叫次數上限,一旦兩個代理對彼此的答案不滿意,就可能陷入無窮互相呼叫的死胡同,在短短幾分鐘內燒光 API 額度。加上迭代上限是控制成本與執行時間最基本也最有效的一道保險絲。
延伸閱讀:IBM、Microsoft 推出 Imagine Enterprise:6,000多項代理與資產如何進企業流程?
串接 MCP 協定與 Docker 程式碼執行沙盒
當多代理需要讀取外部網頁或執行分析腳本時,工具接入與環境隔離就成為系統能否安全運作的分水嶺。AutoGen 透過 Extensions API 提供了兩種關鍵能力,分別是標準化的 MCP 工具工作台,以及隔離本機系統的 Docker 程式碼執行器。
用 McpWorkbench 接入瀏覽器與外部工具
Model Context Protocol 已經成為代理串接外部資料與工具的共通標準。在 AutoGen 中,你不需要自己手寫 Playwright 的包裝函式,只要透過 McpWorkbench 與 StdioServerParams,就能直接把外部 MCP 伺服器掛載給代理使用。
使用前請先確認本機已安裝 Node.js 環境,並執行 npm install -g @playwright/mcp@latest。接著就能讓代理在無頭瀏覽器中自動查詢公開網頁資訊。
import asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.ui import Console
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_ext.tools.mcp import McpWorkbench, StdioServerParams
async def main() -> None:
model_client = OpenAIChatCompletionClient(model="gpt-4.1")
server_params = StdioServerParams(
command="npx",
args=["@playwright/mcp@latest", "--headless"],
)
async with McpWorkbench(server_params) as mcp:
agent = AssistantAgent(
"web_browsing_assistant",
model_client=model_client,
workbench=mcp,
model_client_stream=True,
max_tool_iterations=10,
)
await Console(agent.run_stream(task="查詢 microsoft/autogen 專案的貢獻者數量。"))
await model_client.close()
asyncio.run(main())
微軟在官方文件中也發出明確警告,只應該連線到完全受信任的 MCP 伺服器,因為這些伺服器可能在本機環境中執行系統指令或接觸到敏感的環境變數。
用 DockerCommandLineCodeExecutor 建立程式執行沙盒
讓大型語言模型自己寫 Python 並立刻在本機執行,是許多資料分析與自動化代理的核心賣點,但這同時也是極高風險的操作。萬一模型受到提示詞注入攻擊,或是單純寫錯了一個刪除檔案的路徑,沒有隔離的本機環境就會直接受損。
正確的作法是安裝 pip install "autogen-ext[docker]",並確保電腦上的 Docker Daemon 處於啟動狀態,接著使用 DockerCommandLineCodeExecutor。它會把代理產生的程式碼存進指定的暫存目錄,再掛載到獨立的 python:3-slim 容器中執行,執行完畢後自動銷毀容器。
import asyncio
from pathlib import Path
from autogen_core.code_executor import CodeBlock
from autogen_ext.code_executors.docker import DockerCommandLineCodeExecutor
async def main() -> None:
work_dir = Path("coding_sandbox")
work_dir.mkdir(exist_ok=True)
async with DockerCommandLineCodeExecutor(
image="python:3-slim",
work_dir=work_dir,
timeout=30,
auto_remove=True,
) as executor:
code_block = CodeBlock(
code="print('已安全在 Docker 隔離容器中完成運算!')",
language="python",
)
result = await executor.execute_code_blocks([code_block], cancellation_token=None)
print(result.output)
asyncio.run(main())
透過 timeout 限制單次執行秒數與 auto_remove=True 自動清理容器,即使模型產出無窮迴圈或意外消耗大量記憶體,影響範圍也會被嚴格鎖死在容器邊界內。
延伸閱讀:加州檢察長控告 OpenAI:700 個 AI 代理逃出沙盒入侵 Hugging Face,訴訟焦點與責任爭議全解析
AutoGen 與 Microsoft Agent Framework 實務對比
許多剛接觸多代理開發的團隊,常會在「繼續學 AutoGen 還是直接換新框架」之間猶豫。以下整理 AutoGen 與官方後繼者 Microsoft Agent Framework 及同級開源工具的核心差異,協助技術主管做架構評估。
| 評估維度 | microsoft/autogen | Microsoft Agent Framework | 實務選型建議 |
|---|---|---|---|
| 專案維護狀態 | 已封存,僅保留歷史參考與社群討論 | 微軟官方主推,具備長期維護承諾 | 新專案優先選擇 MAF |
| 核心架構設計 | Core、AgentChat、Extensions 三層非同步架構 | 承襲 AutoGen 經驗,強化企業級 API 穩定度 | 學習事件驅動概念兩者皆可 |
| 跨協定與工具支援 | 支援 MCP 工作台與 Docker 程式碼沙盒 | 原生整合 A2A 與 MCP 跨執行期互通 | 需跨系統協作建議選 MAF |
| 生產環境適配度 | 官方明確建議勿用於高敏感生產環境 | 專為生產環境打造,具備完整支援路線圖 | 企業上線務必避開已封存套件 |
| 視覺化原型工具 | 內建 AutoGen Studio 適合快速展示 | 著重工程化編排與企業工作流管理 | 本機教學示範仍可用 Studio |
從這張對照表可以看出,AutoGen 在開源歷史上扮演了極為重要的探路者角色,它證明了非同步訊息匯流排加上受控工具沙盒,確實能解決複雜推理任務。但在工程維護的現實面前,沒有官方安全修補的套件不應該出現在核心商業流程中。
資安邊界與實務避坑指南
把 AutoGen 拿來做技術驗證或研究實驗時,有四個常見的地雷特別容易讓開發者踩坑。
第一是忽略封存帶來的依賴套件漏洞風險。當上游倉庫停止維護,相依的第三方套件一旦爆出高風險弱點,就不會有官方自動更新補丁,這也是微軟在公告中反覆強調不要拿它處理機密資料的主因。
第二是誤把 AutoGen Studio 當成正式對外網站。許多人看到它能用一條指令就在 8080 埠起出漂亮的對話介面,就想直接掛上反向代理給團隊使用。但 Studio 預設沒有完整的身分驗證與權限隔離,任何能連上該頁面的人都能透過代理呼叫你設定的 API 金鑰甚至本機工具。
第三是忘記限制工作目錄與容器網路權限。雖然 DockerCommandLineCodeExecutor 隔開了宿主機檔案系統,但如果容器預設仍保有對外網路存取能力,受污染的程式碼還是有可能向外部伺服器傳送敏感資訊,高敏場景建議搭配無網路模式或自訂安全映像檔。
第四是沒有為對話設定明確終止條件與預算上限。多代理協作最迷人的地方是會自己反思與修正,但這也意味著 Token 消耗呈現倍數成長。務必在程式中搭配 max_tool_iterations 與終止條件檢查,避免帳單失控。
常見問題
AutoGen 現在還能用來開發新專案嗎?
可以拿來做研究、教學或快速技術驗證,但不建議用於新的企業生產環境。因為微軟已經將 microsoft/autogen 轉為封存狀態,不再提供安全性修補或新功能更新,正式上線的新專案建議改採官方接棒的 Microsoft Agent Framework。
為什麼一定要設定 Docker 沙盒來執行代理產出的程式碼?
因為大型語言模型產出的程式碼有可能包含邏輯錯誤、誤刪檔案的指令,或是因為讀取外部網頁而觸發間接提示詞注入攻擊。透過 Docker 容器把執行環境與本機系統隔離開來,才能確保就算腳本出錯也不會破壞開發機或伺服器。
AutoGen 的 Core API 跟 AgentChat API 有什麼差別?
Core API 是最底層的訊息傳遞與事件驅動引擎,自由度最高但設定較繁瑣,適合需要自訂分散式架構的團隊。AgentChat API 則是建構在 Core 之上的高階包裝,提供現成的助理代理、工具封裝與團隊對話模式,多數教學與原型開發都會從 AgentChat 開始。
舊版 AutoGen 0.2 的程式可以直接升級嗎?
不能直接無痛替換,因為新版改為徹底的非同步架構並重新拆分了套件命名空間。如果你的系統還停留在 0.2 版,建議直接參考微軟官方提供的遷移指南,評估改寫成新版非同步模式或直接轉移至 Microsoft Agent Framework。
結語
回頭看這套曾引爆開源社群熱潮的多代理框架,AutoGen 最大的價值在於確立了「角色分工、事件驅動、沙盒執行、人類審核」四個現代 AI 代理的黃金設計原則。
- 適合誰:正在學習多代理架構原理的工程師、需要維護既有 AutoGen 實驗專案的研究人員,以及想在安全本機環境測試 MCP 與 Docker 沙盒機制的開發者。
- 不適合誰:準備打造長期營運企業級 AI 產品的團隊、需要官方資安合規保證的金融或醫療專案,以及不願自行承擔已封存套件維護風險的生產系統。
- 為什麼:因為官方已明確停止維護與安全更新,AutoGen 最適合扮演理解多代理底層邏輯的練功房,真正要上線服務客戶的系統,應該把重心轉往仍在積極演進的後繼框架。
如果你想持續追蹤多代理框架的最新演進、開源工具實測與工程避坑指南,歡迎免費訂閱 AI 郵報,每週幫你把繁雜的技術動態整理成可直接上手的實戰精華。