深入理解GenAI Works框架：整合MCP服務器、A2A、GenAI與工作流智能體
在AI技術快速迭代的當下，智能體（Agent）系統已從單一功能模塊向復雜協同架構演進。此前我們介紹的智能體AI演示系統僅包含基礎交互功能，而GenAI Works框架（開源倉庫見GitHub）憑借端到端的設計思路，實現了智能體全流程管理與多組件協同，成為企業級智能體開發的重要參考。本文將從框架結構解析、部署實操及多組件整合三個維度，帶您全面掌握這一工具的核心能力
一、GenAI Works框架核心結構：從前端到后端的協同邏輯
GenAI Works的核心優勢在于覆蓋智能體AI的完整技術鏈路，不僅提供可視化交互界面，更通過多協議、多服務的設計，實現智能體注冊、消息路由、任務執行與數據存儲的閉環。其整體架構可拆解為前端交互層、后端服務層、消息路由層、智能體執行層與數據存儲層五大模塊，各模塊通過Docker容器獨立運行，兼顧擴展性與靈活性。
1. 核心技術協議：不止MCP與A2A，新增GenAI智能體協議
框架通過多協議管理智能體通信，除了常見的MCP（多智能體通信協議）與A2A（智能體間通信協議），還引入了2025年5月發布的GenAI Agent Protocol，其中GenAISession對象是關鍵協調者。根據PyPI官方定義，GenAISession是“注冊智能體并管理事件生命周期的中央控制器”，但官方文檔較為簡略。結合實際代碼分析，其核心作用包括：
- 通過WebSocket連接中央路由服務（Router），實現消息與事件的分發；
- 處理文件上傳/下載，確保數據在智能體間高效流轉；
- 維護每條消息的上下文信息，保障多輪交互的連貫性。
2. 前后端交互：HTTP與WebSocket的分工協作
- 前端層：基于React開發，提供三大核心功能——智能體聊天交互、MCP/A2A端點配置、工作流智能體設計，用戶可通過可視化界面完成全流程操作。
- 后端層：基于FastAPI構建，作為前端與路由服務的“橋梁”，通過兩種方式與前端通信：
HTTP端點（定義于backend/routes/xxx/routes.py）：負責數據存儲與用戶管理，如將聊天記錄、智能體注冊信息存入PostgreSQL，用Redis實現緩存加速，同時處理用戶認證與個人資料維護；
WebSocket端點（定義于backend/routes/websocket.py，路徑為/frontend/ws）：不直接向智能體轉發消息，而是通過GenAISession（定義于backend/main.py）將消息傳遞給Router，確保實時通信的穩定性。
3. 消息路由與智能體執行：Router與Master-Agent的協同
- Router服務：作為“消息總線”，承擔消息路由與分發的核心職責，所有智能體的通信均需經過Router中轉。
- Master-Agent（主智能體）：通過
GenAISession的@session.bind裝飾器（定義于/master_agent/main.py）與Router綁定，該裝飾器修飾receive_message函數后，主智能體可自動處理來自Router的消息。其執行邏輯如下：
MCP工具：使用流式HTTP會話（streamable-http session）；
A2A智能體：遵循A2A協議；
GenAI/工作流智能體：通過GenAISession使用GenAI協議（連接器實現見master-agent/connectors/manager.py）。
1）接收Router消息后，調用master_agent.graph.ainvoke方法觸發后續智能體；
2）內部采用LangGraph對象管理任務流程——LangGraph支持多輪工具/智能體調用的重試機制，尤其適合復雜工作流；
3）通過execute_agent節點調用connector.invoke方法，由連接器（Connector）根據智能體類型選擇通信方式：
4. 數據存儲層：PostgreSQL與Redis的分工
- PostgreSQL：存儲結構化數據，包括聊天歷史、智能體注冊信息、用戶配置等，確保數據持久化與可追溯；
- Redis：用于緩存高頻訪問數據（如智能體狀態、臨時會話信息），提升系統響應速度；
- 此外，框架通過Celery監控應用運行狀態，及時發現并處理服務異常。
二、GenAI Works框架部署實操：從環境配置到服務啟動
盡管項目README提供了基礎部署指南，但仍需針對性調整以確保全系統正常運行。以下是經過驗證的完整部署步驟：
1. 基礎環境準備與代碼拉取
- 克隆GitHub倉庫并進入項目目錄：
git clone https://github.com/genai-works-org/genai-agentos.git
cd genai-agentos/- 復制環境變量模板并創建
.env文件：
cp .env-example .env2. 關鍵環境變量調整（核心步驟）
.env文件需修改兩處配置，否則容器間通信會失敗：
- Router地址修正：將
ROUTER_WS_URL=ws://localhost:8080/ws改為ROUTER_WS_URL=ws://genai-router:8080/ws。原因是Docker容器內無法通過localhost訪問其他容器，需使用預定義的服務名genai-router在Docker網絡中通信； - 調試模式開啟：設置
DEBUG=True（默認模板為DEBUG=True/False，需明確啟用調試模式以避免啟動報錯）。
3. 依賴安裝與容器啟動
- 確保Docker Desktop已啟動，且本地安裝了
uv（Python依賴管理工具）； - 在VSCode中打開項目，執行依賴同步：
uv sync- 激活虛擬環境：
source .venv/bin/activate- 啟動所有Docker容器（兩種命令均可）：
make up # 或 docker compose up- 等待容器啟動完成，若所有服務無報錯，則前端可通過
http://localhost:3000訪問。
4. 前端初始化配置：API密鑰與LLM模型添加
框架依賴OpenAI LLM模型（當前僅支持OpenAI API），需完成以下配置：
- 訪問
http://localhost:3000，注冊并登錄賬號（登錄后自動跳轉至首頁）； - 點擊頁面頂部用戶頭像下拉菜單，進入“Settings”頁面；
- 從OpenAI API密鑰頁面復制密鑰，粘貼到“API Key”輸入框；
- 點擊“Add Models”按鈕，配置LLM模型參數（可調整系統提示詞、溫度系數等），點擊“Save”完成配置。
三、多組件整合：MCP服務器、A2A與GenAI智能體的接入與測試
GenAI Works默認不包含MCP服務器與A2A智能體，需自行創建或使用示例項目；GenAI智能體與工作流智能體則需通過特定步驟接入。以下是各組件的整合流程：
1. 示例MCP服務器與A2A智能體的部署
（1）示例項目準備
可使用自定義的MCP/A2A項目，或參考以下要求創建示例：
- A2A智能體返回數據需為
Task對象，且包含artifact屬性（示例代碼如下）：
from uuid import uuid4
from your_module import Artifact, Part, TextPart, Task
def generate_response(final_result):
artifact = Artifact(
artifact_id=str(uuid4()),
parts=[Part(root=TextPart(text=final_result))]
)
task = Task()
task.artifacts = [artifact]
return task- 啟動示例項目后，確保MCP服務器運行于
http://localhost:10011，A2A智能體運行于http://localhost:10010。
（2）MCP服務器接入UI
- 在GenAI Works左側導航欄點擊“MCP Servers”，選擇“Add MCP Agent”；
- 輸入地址
http://host.docker.internal:10011（關鍵：容器內訪問主機服務需用host.docker.internal替代localhost），點擊“Save”； - 接入成功后，MCP服務器會顯示在列表中；
- 在“Chats”窗口輸入測試提示詞，可看到返回結果符合MCP服務器定義的格式。
（3）A2A智能體接入UI
- 左側導航欄點擊“ACA Agents”，選擇“Add ACA Agent”；
- 輸入地址
http://host.docker.internal:10010，點擊“Save”； - 接入成功后，在“Chats”窗口輸入提示詞（如“生成一篇技術博客”），返回結果將顯示A2A智能體已被成功調用；
- 可通過A2A智能體的終端日志驗證調用記錄。
2. GenAI智能體的接入（基于GenAI協議）
由于GenAI協議文檔有限，此處以框架自帶的示例智能體（genai_agent_sample/get_current_date_agent）為例：
- 在左側導航欄點擊“GenAI Agents”，選擇“Generate token”，復制彈出的Token；
- 在VSCode中打開示例智能體文件，將Token粘貼到
jwt_token字段； - 運行該Python文件，終端將顯示智能體信息（如“Agent name: get_current_date, Agent description: Return current date”）；
- 返回GenAI Works UI，點擊“Refresh”按鈕，系統將自動識別運行中的GenAI智能體并顯示在列表中。
3. 工作流智能體（Workflow Agent）的創建與測試
工作流智能體基于LangGraph，整合現有MCP服務器、A2A智能體形成流程鏈，支持狀態管理與重試機制（當前版本UI暫不支持條件分支，僅支持線性鏈）：
- 在左側導航欄點擊“Workflow Agents”，通過拖拽界面選擇已接入的MCP/A2A智能體，連接形成流程鏈；
- 點擊“Save”保存工作流智能體；
- 在“Chats”窗口輸入測試提示詞（如“先調用MCP計算2+3，再用A2A生成結果說明”）；
- 返回結果將顯示工作流的最終輸出（設計上僅返回最后一個智能體的結果，如乘法計算結果）。
四、GenAI Works的價值與后續探索方向
GenAI Works框架通過模塊化設計、多協議支持與可視化界面，降低了企業級智能體系統的開發門檻，尤其適合需要整合多類型智能體（MCP、A2A、GenAI）的場景。但其架構復雜度較高，部分模塊（如GenAISession的深層邏輯）仍需結合代碼深入理解。
后續可探索的方向包括：
- 擴展LLM模型支持（當前僅支持OpenAI，可集成開源模型如Llama 3、Qwen）；
- 完善工作流智能體的條件分支功能，滿足復雜業務場景；
- 優化日志監控系統，提升問題排查效率。
若您需要進一步深入，建議從master-agent的LangGraph流程設計、GenAISession的WebSocket通信邏輯兩個核心模塊入手，逐步掌握框架的底層原理。
