agentscope-ai/agentscope 開源多代理編排實戰教學:支援即時語音串流與 Web UI 的開發指南

agentscope-ai/agentscope 提供高可靠度的多代理訊息傳遞與分散式執行架構,並支援即時語音串流代理與 Web UI 除錯,一篇帶你完成安裝與多代理範例。

Share
AgentScope官方 GitHub 專案封面圖:AgentScope 教學
AgentScope官方開源專案視覺圖。 圖片來源:官方原文。

開發多代理系統時,最讓工程師崩潰的往往不是單一模型的推論能力,而是代理之間通訊與狀態同步的混亂。

一旦任務需要多個角色協作、工具呼叫與即時打斷恢復,硬寫出來的迴圈很快就會變成難以除錯的義大利麵程式碼。

agentscope-ai/agentscope 在邁入 2.0 版本後,專為高自主性的大型語言模型打造了一套生產級的模組化編排框架。

它不僅提供清晰的 ReAct 推論迴圈、標準作業程序編排與即時語音串流能力,還直接內建 FastAPI 後端與 Web UI。

本篇 AgentScope 教學將帶你拆解其核心建築積木、Python 安裝與快速啟動流程,以及即時語音與多代理團隊的實戰邊界。

為什麼多代理框架需要事件驅動與即時語音支援

早期的 AI 代理框架大多假設使用者只會在網頁上輸入文字,接著等待系統花十幾秒吐出一整段回覆。

然而隨著模型能力提升與應用場景擴大,單純的文字問答已經無法滿足生產環境的需求。

現代多代理應用經常需要同時處理幾項棘手問題:代理執行工具到一半被使用者按 Ctrl+C 或語音插話打斷、背景工具執行時間過長需要非同步喚醒,以及多租戶對話歷史必須嚴格隔離。

如果在傳統同步迴圈上硬塞這些功能,程式碼會充斥著脆弱的鎖定機制與例外處理。

AgentScope 2.0 的核心哲學是「順應模型的推理與工具使用能力,而非用死板的提示詞與強硬編排限制模型」。

它透過統一的事件匯流排貫穿整個系統,把模型思考過程、工具呼叫、文字串流、圖片與即時語音全部統一成可追蹤的事件流。

這種設計讓你在開發階段可以用終端機互動除錯,上線時則無縫切換成支援 WebRTC 語音與多租戶 Web UI 的完整服務。

AgentScope官方 GitHub 專案封面圖:AgentScope 教學
AgentScope官方開源專案視覺圖。 圖片來源:官方原文。

AgentScope 2.0 九大核心積木與技術架構解析

根據官方文件,這套架構將代理開發拆分為九個可自由組合的 SDK 模組,讓開發者像組裝積木一樣建構系統。

推理與工具層:ReAct 與 Toolkit

核心引擎是 ReAct 迴圈,支援結構化輸出、即時中斷與恢復,以及循序或批次並行的工具執行能力。

搭配的 Toolkit 模組除了能掛載自訂 Python 函式與外部 MCP 伺服器,還直接內建了開發常用的檔案與終端機工具,包含 Bash、Grep、Glob、Read、Write 與 Edit。

模型與上下文管理層:Model、Context 與 Memory

在模型抽象層 Model 中,框架原生支援 OpenAI、Anthropic、Gemini、DashScope、DeepSeek、Moonshot、Volcengine、xAI、Ollama 以及 MiniMaxChatModel。

同時提供 ModelRouterMiddleware 模型路由中介軟體,能根據每次回覆的需求動態挑選最合適的對話模型。

針對長對話容易爆掉上下文視窗的問題,Context 模組提供自動壓縮、工具執行結果卸載以及 RAG 與長期記憶注入機制,而 Memory 模組則支援切換 ReMe 與 Mem0 等記憶後端。

控制與安全隔離層:Event System、Permission 與 Workspace

所有輸入輸出都經過統一的 Event System 事件匯流排,確保文字、圖片與音訊能即時串流至前端介面。

在安全性與人工介入方面,Permission & HITL 模組提供細粒度的工具與資源權限控管,支援高風險操作確認或全自動略過模式。

更關鍵的是 Workspace / Sandbox 執行環境隔離層,原生支援本機執行、Docker、Apple Container、Bubblewrap、E2B、OpenSandbox、Daytona 與 Kubernetes,確保代理寫程式或跑指令時不會破壞宿主系統。

延伸閱讀:LangChain 完成 3 億美元 C 輪融資!CapitalG 領投、估值衝上 30 億美元,企業級 AI 代理基礎設施拼什麼?

即時語音串流、TeamPipeline 與 Agent Service

除了基礎 SDK 之外,這套開源專案近期最受矚目的兩大亮點,就是即時語音代理與開箱即用的後端服務。

在語音互動方面,RealtimeAgent 已經整合了 DashScope、OpenAI、Gemini 與 xAI 的即時語音 API,並實驗性支援透過 WebRTC 進行雙向即時語音對話。

這代表使用者在跟客服或語音助理對話時,不需要等整句話說完並轉成文字再送給模型,系統能直接進行低延遲的語音對語音串流互動。

更實用的設計在於語音與文字能共享同一份對話工作階段歷史,同時支援語音設定檔管理與聲音複製功能,開發者可直接透過 SDK 呼叫 DashScope 或 OpenAI 語音複製客戶端。

舉例來說,使用者可以先在手機上用語言交代複雜的旅遊需求,接著回到電腦前打開文字對話框繼續微調行程細節,代理的上下文記憶完全不會斷裂。

在多代理協作方面,框架新增了 TeamPipeline 團隊管線與標準作業程序 SOP 支援。

TeamPipeline 採用領導者與工作者代理模式,由領導者負責拆解複雜任務並指派給不同專長的子代理執行,這對於需要研究員、寫手與審核員分工的長流程任務特別有效。

當任務流程需要高度一致性時,則可改用標準作業程序 SOP 模式,將多步驟任務拆解成可重複執行的標準階段,兼顧模型推理彈性與企業流程合規要求。

如果你不想從頭寫 API 伺服器與聊天室前端,官方直接在儲存庫中附帶了完整的 Agent Service 範例,包含一個 FastAPI 後端與預建的 Web UI,支援多租戶隔離、飛書與 Discord 通訊軟體串接、排程喚醒以及背景長任務卸載。

特別值得一提的是背景任務卸載機制。

當代理呼叫一個需要耗時數分鐘的外部資料分析或爬蟲工具時,系統不會把整個對話執行緒卡死,而是自動把該工具推到背景執行。

等到背景任務完成並回傳結果後,事件匯流排會主動喚醒該工作階段的代理,讓代理接著向使用者彙報成果,大幅提升長任務的互動體驗。

AgentScope 常用模組與擴充生態速查

為了方便團隊在設計系統架構時快速選型,以下整理幾個實務開發最常搭配的進階機制與官方擴充能力。

在工具與技能管理上,除了內建的檔案與終端機操作工具,框架支援透過 MCP & Skill Hub 瀏覽並掛載 GitHub MCP Registry 與 ClawHub 上的開源技能。

開發者可以把常用的資料庫查詢、文件解析或內部系統 API 封裝成標準 MCP 伺服器,透過資源共享機制在組織或群組層級統一授權給多個代理使用,避免每個專案重複造輪子。

在模型成本最佳化方面,ModelRouterMiddleware 允許你在單一對話迴圈中動態切換模型。

例如處理簡單的意圖分類或格式整理時,路由給輕量快速的模型;一旦進入複雜的程式除錯或長文架構規劃,再自動切換到旗艦級推理模型,同時支援 MiniMaxChatModel 等高性價比選項。

在狀態持久化與排程方面,Agent Service 同時支援 SQL 與 NoSQL 資料庫後端,確保代理的對話紀錄與任務狀態不會因為伺服器重啟而遺失。

搭配內建的排程器與代理喚醒機制,團隊甚至能打造出每天定時自動巡檢系統日誌、產出摘要並透過飛書或 Discord 主動回報的自動化維運代理。

如果開發者想要更深入控制代理執行迴圈的每一個階段,也可以善用 Middleware 中介軟體與 Context 上下文管理模組。

透過這兩層機制,你可以在模型呼叫前後插入自訂的合規檢查邏輯、自動過濾敏感資訊,或者在對話過長時自動把舊的工具執行結果卸載到外部儲存空間,只保留精簡摘要在對話視窗內,藉此在長流程任務中穩定控制 Token 消耗量。

AgentScope 教學:安裝設定與快速上手實戰

官方要求使用 Python 3.11 或以上版本,並推薦使用 uv 套件管理工具來加速環境建置。

步驟一:安裝 AgentScope 套件

你可以選擇直接從 PyPI 安裝穩定版本,或是從 GitHub 複製原始碼進行可編輯模式安裝,方便隨時修改或執行範例專案。

# 方式一:從 PyPI 直接安裝
uv pip install agentscope

# 方式二:從 GitHub 複製原始碼並安裝
git clone -b main https://github.com/agentscope-ai/agentscope.git
cd agentscope
uv pip install -e .

步驟二:在終端機啟動第一個編程代理

安裝完成後,設定好模型 API 金鑰環境變數,例如使用 DashScope 模型時設定 DASHSCOPE_API_KEY。

接著建立一個 Python 檔案,使用 Agent 類別與內建開發工具組,並透過 launch_console 在終端機啟動互動介面。

from agentscope.agent import Agent
from agentscope.console import launch_console
from agentscope.tool import Toolkit, Bash, Grep, Glob, Read, Write, Edit
from agentscope.credential import DashScopeCredential
from agentscope.model import DashScopeChatModel

import os, asyncio


async def main() -> None:
    agent = Agent(
        name="Friday",
        system_prompt="You're a helpful assistant named Friday.",
        model=DashScopeChatModel(
            credential=DashScopeCredential(
              api_key=os.environ["DASHSCOPE_API_KEY"]
            ),
            model="qwen3.6-plus",
        ),
        toolkit=Toolkit(
            tools=[
                Bash(),
                Grep(),
                Glob(),
                Read(),
                Write(),
                Edit(),
            ]
        ),
    )

    await launch_console(agent)

asyncio.run(main())

這段程式碼啟動後,終端機就會自動接管串流輸出、工具呼叫前的安全確認提示,以及 Ctrl+C 即時中斷控制。

步驟三:啟動 Agent Service 後端與 Web UI

如果你想直接體驗視覺化監控與網頁對話介面,可以開啟兩個終端機視窗,分別啟動範例後端與前端介面。

# 第一個終端機:啟動 FastAPI 代理服務後端
cd agentscope/examples/agent_service
python main.py
# 第二個終端機:安裝並啟動 Web UI 前端
cd agentscope/examples/web_ui
pnpm install
pnpm dev

啟動完成後打開瀏覽器,就能在圖形介面中觀察代理拆解任務規劃的過程、檢視領導者與子代理的協作狀態,並測試背景長任務自動喚醒功能。

開源多代理編排框架比較表

市面上多代理框架各有側重,下表針對工程團隊最在意的架構特性與整合能力進行對比。

比較維度 AgentScope 2.0 一般輕量級迴圈框架 傳統靜態工作流平台
開源授權條款 Apache 2.0 商業友善授權 視專案而定,多為 MIT 或 Apache 部分企業功能採專有授權
即時語音與多模態 原生支援 RealtimeAgent 與 WebRTC 通常需自行串接音訊管線 較少原生支援雙向語音串流
內建前後端服務 附帶 FastAPI 後端與 Web UI 僅提供 Python 函式庫 提供視覺化介面但客製化受限
程式碼執行沙盒 原生對接 Docker、E2B 與 K8s 需開發者自行封裝安全隔離 依賴平台託管執行環境
通訊軟體整合 內建飛書與 Discord 頻道路由 需透過 Webhook 自行開發 支援常見 SaaS 連結器

實務部署限制與資安邊界提醒

雖然這套架構的功能相當齊全,但團隊在導入生產環境前仍須留意幾項技術限制與資安邊界。

第一項要注意的是權限略過模式的風險控管。

在原型測試時,許多開發者習慣開啟權限略過模式讓代理一路自動執行到底,不必每次跳出工具確認視窗。

然而只要代理掛載了 Bash 或檔案編輯工具,一旦處理到含有惡意指示的外部文件或網頁內容,全自動執行就可能導致系統檔案遭竄改。

因此,生產環境務必搭配 Workspace 沙盒模組,將工具執行強制鎖在 Docker、E2B 或 Kubernetes 隔離環境中,切勿在裸機上對外部使用者開放略過權限模式。

第二項要注意的是實驗性功能的穩定度。

根據官方更新紀錄,WebRTC 即時語音對話、SOP 標準作業程序執行與部分即時語音代理功能目前仍標記為實驗性特色,API 介面在後續小版本更新時仍有可能微調,導入核心業務前建議先鎖定套件版本並建立整合測試。

第三項則是多租戶資料與頻道路由隔離。

當你使用內建的 FastAPI 代理服務串接企業內部通訊軟體如飛書或 Discord 時,務必確認租戶識別碼與工作階段儲存後端的存取權限設定,避免不同部門或使用者的記憶資料混用。

延伸閱讀:OpenAI 宣布 12 月 11 日退場 ChatGPT 舊版語音模式!全面轉向全雙工 GPT-Live 的技術差異與用戶影響

常見問題

1. 這篇 AgentScope 教學使用的版本需要什麼 Python 環境

AgentScope 2.0 官方明確要求 Python 3.11 或以上版本。如果你在安裝或執行範例時遇到非同步語法或套件相依衝突,建議先使用 uv 建立獨立的 Python 3.11 以上虛擬環境再進行安裝。

2. 框架支援哪些大型語言模型與本地模型

框架的模型層已經內建支援 OpenAI、Anthropic、Gemini、DashScope、DeepSeek、Moonshot、Volcengine、xAI、MiniMax 以及本地運行的 Ollama。開發者也可以透過模型路由中介軟體,讓不同複雜度的對話步驟自動切換不同價位的模型。

3. 沒有前端工程師,也能直接使用視覺化監控與對話介面嗎

可以。官方儲存庫的 examples/agent_service 與 examples/web_ui 已經打包好完整的 FastAPI 後端與前端頁面。只要依序執行 Python 後端與 pnpm dev 指令,就能直接在瀏覽器中測試多代理協作、任務規劃與背景工具執行狀態。

4. 即時語音對話和文字對話可以共用記憶嗎

可以。根據官方最新釋出的特性,系統支援透過 WebRTC 進行即時語音對話,並且能讓語音互動與文字訊息共用同一份工作階段歷史紀錄,方便使用者在語音與打字之間無縫切換。

結語

對於正在尋找兼具開發彈性與完整前後端範例的工程團隊來說,agentscope-ai/agentscope 非常適合用來建構需要多代理分工、MCP 工具擴充與即時語音互動的生產級 AI 應用。

如果你只需要寫一個幾十行就能跑完的單純文字問答腳本,那麼直接使用單一模型的官方 SDK 會更加輕便,不需要為專案引入整套多代理事件匯流排與服務端架構。

把基礎通訊、記憶壓縮與沙盒邊界交給成熟框架處理,工程師才能把時間花在真正創造業務價值的代理邏輯上。如果你想持續收到最新開源 AI 代理框架與架構拆解,歡迎免費訂閱 AI 郵報,每週掌握第一手實戰指南。

資料來源