在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仓库并进入项目目录：
- 复制环境变量模板并创建.env文件：
2. 关键环境变量调整（核心步骤）
.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中打开项目，执行依赖同步：
- 激活虚拟环境：
- 启动所有Docker容器（两种命令均可）：
- 等待容器启动完成，若所有服务无报错，则前端可通过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属性（示例代码如下）：
- 启动示例项目后，确保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通信逻辑两个核心模块入手，逐步掌握框架的底层原理。
