agent-platform/docs/agent-platform-multi-service-roadmap.md

Python 智能体开发平台规划（多服务 / 可横向扩展版）

1. 项目定位

本项目目标不是做一个单体的聊天机器人系统，而是建设一套基于 Python 的智能体开发平台，支持：

• 多应用承载：客服、销售、运营、知识问答、流程自动化、研发助手等
• 多智能体协作：单 Agent、团队 Agent、角色分工、任务拆解、结果汇总
• 复杂流程编排：LLM、条件分支、代码节点、工具节点、检索节点、子流程、人工审批
• 记忆系统：短期记忆、长期记忆、用户记忆、任务记忆、领域隔离记忆
• 技能与工具扩展：技能复用、工具注册、插件接入、外部系统集成
• 平台化运营：版本管理、调试回放、权限治理、监控审计、灰度发布

一句话定位：

一套支持多应用、多智能体、多流程、多服务部署的智能体编排与运行平台。

2. 建设原则

2.1 架构原则

• 先做运行内核，再做可视化 Studio
• 先定义内部 DSL，再做第三方流程导入
• 以图执行引擎为中心，而不是以单个 Agent 为中心
• 状态和记忆是平台一等公民，不能只靠 prompt 拼接
• 所有执行链路必须可追踪、可回放、可审计
• 单服务可独立部署，服务间通过事件和 API 解耦

2.2 工程原则

• 代码按领域边界拆分，避免“伪微服务”
• 核心协议统一，服务内部可独立演进
• 同步调用只用于短链路，长链路一律事件化
• 服务设计默认支持无状态横向扩容
• 数据库按域拆分，读写边界明确

3. 总体架构

平台建议采用“网关 + 核心运行时 + 支撑服务”的多服务架构。

3.1 逻辑分层

1. 接入层
2. API Gateway
3. Web Studio

4. SDK / Webhook

5. 编排与运行层

6. Session Service

7. Workflow Service

8. Agent Runtime Service

9. Team Runtime Service

10. Scheduler Service

11. 能力层

12. Tool Service

13. Skill Service

14. Memory Service

15. Retrieval Service

16. Plugin Service

17. Model Gateway

18. 支撑层

19. Auth / Tenant Service

20. Trace / Eval Service

21. Notification Service

22. File / Artifact Service

23. 基础设施层

24. PostgreSQL

25. Redis

26. pgvector

27. MinIO

28. Kafka / RabbitMQ

29. Prometheus / Grafana / OpenTelemetry

3.2 推荐部署形态

• api-gateway：统一接入入口
• studio-web：管理后台
• session-service：会话与运行入口
• workflow-service：流程定义、版本、执行图解析
• runtime-service：节点执行调度
• agent-service：单智能体执行
• team-service：多智能体协作
• memory-service：记忆与上下文读写
• tool-service：工具注册、鉴权、调用
• retrieval-service：知识库和语义检索
• model-gateway：统一模型接入
• trace-service：追踪、回放、评测
• scheduler-service：异步任务、延迟任务、重试
• auth-service：用户、组织、租户、权限
• artifact-service：文件、产物、日志附件

4. 为什么要做多服务

如果平台未来要支持复杂工作流、多租户、多团队并发开发，以及长链路任务执行，单体架构会很快遇到以下问题：

• 模型调用、工具调用、检索调用耦合在一起，扩容粗糙
• 长任务阻塞普通会话接口
• 记忆、工具、检索、工作流版本难以独立演进
• 某类流量暴涨时无法按服务维度单独扩容
• 复杂流程出问题时定位困难

因此建议从一开始就按照“模块化单体 -> 受控多服务”的方式设计代码和边界，即使初期只部署成少量服务，也要保证未来拆分成本可控。

5. 服务拆分方案

5.1 API Gateway

职责：

• 统一 HTTP / WebSocket / SSE 入口
• 用户认证与请求转发
• 限流、熔断、审计入口
• 聚合常用接口

扩展方式：

• 完全无状态
• 可直接多副本水平扩容

5.2 Session Service

职责：

• 会话生命周期管理
• 用户请求接收
• 会话变量初始化
• 运行实例创建
• 对接 Runtime Service 发起执行

数据边界：

• session
• conversation
• message
• run_request

扩展方式：

• 无状态服务 + Redis 会话缓存
• 通过消息队列把长任务移出请求线程

5.3 Workflow Service

职责：

• 应用定义管理
• 工作流 DSL 存储和版本化
• 节点/边校验
• 工作流编译和执行计划生成
• 第三方 YAML 导入适配

数据边界：

• app_definition
• app_version
• workflow_definition
• workflow_version
• workflow_template

扩展方式：

• 读多写少，适合多副本部署
• 编译结果可缓存到 Redis

5.4 Runtime Service

职责：

• 工作流运行调度
• 节点状态流转
• 并发控制
• 重试 / 超时 / 取消 / 恢复
• 事件发布

这是平台核心服务。

数据边界：

• workflow_run
• node_run
• run_event
• run_snapshot

扩展方式：

• Worker 模式水平扩展
• 消费消息队列任务
• 通过分片键避免同一 run 被多个 worker 冲突处理

5.5 Agent Service

职责：

• 单智能体执行
• Prompt 拼装
• 结构化输出
• 工具调用策略
• 记忆召回拼装

数据边界：

• agent_definition
• agent_version
• agent_policy

扩展方式：

• 无状态执行服务
• 可按模型类型、业务类型拆分不同池子

5.6 Team Service

职责：

• 多智能体团队定义
• 任务拆解
• 角色分配
• 共享上下文管理
• 结果汇总和冲突裁决

数据边界：

• team_definition
• team_version
• team_member
• team_run
• team_task

扩展方式：

• 和 Agent Service 一样无状态
• 高并发时可独立扩容，避免影响普通单 Agent 任务

5.7 Memory Service

职责：

• 短期记忆读写
• 长期记忆写入与召回
• 领域记忆 namespace 隔离
• 会话状态与上下文存取
• 记忆压缩和清洗

数据边界：

• memory_record
• memory_fact
• memory_episode
• context_namespace
• context_kv

扩展方式：

• API 层无状态
• 底层依赖 PostgreSQL + pgvector + Redis

5.8 Tool Service

职责：

• 工具定义、注册、版本管理
• 工具鉴权
• 参数校验
• 调用转发
• 调用审计

数据边界：

• tool_definition
• tool_version
• tool_binding
• tool_credential
• tool_invocation_log

扩展方式：

• 工具元数据无状态服务
• 真正执行可下沉到 executor worker

5.9 Retrieval Service

职责：

• 文档导入
• 分片、Embedding
• 向量检索
• 混合检索
• 知识库权限隔离

数据边界：

• knowledge_base
• document
• document_chunk
• embedding_index
• retrieval_log

5.10 Model Gateway

职责：

• 统一管理 OpenAI / Azure / Anthropic / Gemini / 本地模型
• 模型路由
• 限流与熔断
• token 统计与成本统计
• 模型级缓存

扩展方式：

• 纯无状态
• 可单独横向扩容

5.11 Trace Service

职责：

• 采集 run trace、node trace、tool trace、memory trace
• 执行链路回放
• 错误定位
• 离线评测
• 成本与性能分析

数据边界：

• trace_span
• trace_event
• eval_case
• eval_result

6. 服务通信模型

6.1 同步调用

适合：

• 用户实时请求
• 配置查询
• 权限校验
• 轻量级元数据读取

建议使用：

• REST API
• 内部 gRPC 可作为后续优化选项

6.2 异步调用

适合：

• 工作流执行
• 节点执行调度
• 记忆写入
• 索引构建
• 批量评测
• 失败重试

建议使用：

• Kafka 或 RabbitMQ
• Celery / Dramatiq 作为任务分发层

6.3 推荐事件

• run.created
• run.started
• node.scheduled
• node.completed
• node.failed
• memory.updated
• tool.invoked
• team.task.created
• trace.emitted

7. 数据存储与边界

7.1 核心原则

• 配置类数据和运行类数据分离
• 热数据和冷数据分离
• 向量数据独立索引
• 文件产物独立存储

7.2 推荐存储

• PostgreSQL：应用、流程、Agent、Team、工具、运行记录
• Redis：缓存、幂等键、分布式锁、短期上下文、任务状态
• pgvector：语义记忆和知识检索
• MinIO：文件、附件、产物、回放原始数据
• Kafka / RabbitMQ：异步事件流

7.3 数据拆分建议

初期可共用一个 PostgreSQL 集群，但按 schema 或 database 区分域：

• app_db
• runtime_db
• memory_db
• tool_db
• trace_db
• auth_db

后续热点域可独立迁移。

8. 横向扩展策略

8.1 无状态服务优先

以下服务默认设计为无状态：

• api-gateway
• workflow-service
• agent-service
• team-service
• tool-service
• model-gateway

这样可以直接通过容器副本水平扩容。

8.2 状态服务去中心化

有状态能力不要依赖本地内存：

• 会话状态放 Redis / DB
• 运行状态放 Runtime DB
• 记忆放 Memory DB
• 文件产物放对象存储

8.3 长任务与短请求隔离

• 用户入口只负责接收请求和返回 run_id
• 长链路任务由 Runtime Worker 处理
• WebSocket / SSE 通过 trace/event 推流

8.4 分布式控制

需要引入：

• 分布式锁
• 幂等键
• 节点执行 lease
• 重试次数与死信队列
• 取消和超时标记

8.5 扩容维度

不同服务按不同指标扩容：

• Gateway：QPS
• Model Gateway：模型请求 TPS 和延迟
• Runtime Worker：待处理 run / node 队列长度
• Retrieval：检索吞吐和索引吞吐
• Team Service：复杂任务并发数
• Trace Service：事件写入速率

9. 统一内部 DSL

不要直接使用第三方工作流协议作为内核运行格式，建议定义内部 DSL：

• workflow
• nodes
• edges
• inputs
• outputs
• policies
• runtime_options

节点类型至少支持：

• llm
• condition
• code
• tool
• retrieval
• template
• answer
• agent
• team
• human_approval
• sub_workflow

第三方 YAML 通过 Importer 转换为内部 DSL。

10. 代码仓结构建议

建议采用 Monorepo，多服务共享基础库。

auto-platform/
  services/
    api-gateway/
    session-service/
    workflow-service/
    runtime-service/
    agent-service/
    team-service/
    memory-service/
    tool-service/
    retrieval-service/
    model-gateway/
    trace-service/
    auth-service/
    artifact-service/
    scheduler-service/
  libs/
    core-domain/
    core-dsl/
    core-events/
    core-auth/
    core-trace/
    sdk-models/
    sdk-tools/
    sdk-memory/
  deployments/
    docker/
    k8s/
    helm/
  docs/
  scripts/
  tests/

10.1 公共库职责

• core-domain：领域模型、枚举、基础对象
• core-dsl：工作流 DSL、节点协议、校验器
• core-events：事件定义、消息契约
• core-auth：认证鉴权模型
• core-trace：统一 trace schema
• sdk-models：模型调用封装
• sdk-tools：工具协议和客户端
• sdk-memory：记忆访问协议

11. Python 服务代码结构建议

每个服务内部尽量保持一致结构：

service-name/
  app/
    api/
    application/
    domain/
    infrastructure/
    tasks/
    schemas/
    bootstrap/
  tests/
  pyproject.toml

11.1 分层说明

• api：HTTP / WebSocket / gRPC 接口
• application：用例编排、服务层
• domain：领域实体、仓储接口、规则
• infrastructure：DB、Redis、MQ、第三方适配器
• tasks：异步任务消费
• schemas：请求响应模型
• bootstrap：依赖注入和启动

12. 核心运行模型

12.1 一次请求的链路

1. 用户请求进入 api-gateway
2. session-service 创建会话和 run
3. workflow-service 返回对应 workflow version 和执行计划
4. runtime-service 创建 root run 并投递节点任务
5. 各 executor 调用 agent-service、tool-service、retrieval-service
6. memory-service 负责读写上下文和记忆
7. trace-service 持续收集执行事件
8. 用户通过 SSE/WebSocket 获取进度和结果

12.2 节点执行模型

每类节点统一接口：

• prepare(context)
• execute(input)
• handle_result(output)
• emit_events()
• schedule_next_nodes()

这样方便以后继续扩展节点类型。

13. 版本落地路线

V0.1 基础内核版

目标：

• 跑通最小闭环

交付：

• Monorepo 工程
• api-gateway
• session-service
• workflow-service
• runtime-service
• model-gateway
• tool-service
• 基础 DSL
• 基础节点：llm、condition、tool、code、answer

验收标准：

• 可以创建一个应用并执行一条流程
• 支持基础工具调用
• 支持 run 级日志追踪

周期：

• 4~6 周

V0.2 智能体版

目标：

• 把流程平台升级为智能体平台

交付：

• agent-service
• memory-service
• 技能系统
• Agent 节点
• 短期记忆
• 长期记忆基础版

验收标准：

• 单 Agent 能结合工具与记忆完成任务
• 记忆支持按用户、应用、会话隔离

周期：

• 4~5 周

V0.3 多智能体与复杂流程版

目标：

• 支撑复杂业务场景

交付：

• team-service
• Team 节点
• retrieval-service
• 子流程节点
• 并行节点
• 人工审批节点
• 异步挂起与恢复
• 领域记忆 namespace

验收标准：

• 支持复杂路由、长链路、多角色协作
• 支持失败恢复、流程中断、人工接管

周期：

• 5~6 周

V0.4 平台治理版

目标：

• 支撑多人协作与生产发布

交付：

• auth-service
• trace-service
• 环境管理
• 版本发布
• 灰度策略
• 审计日志
• 成本与性能监控

验收标准：

• 多团队可在同平台开发多个应用
• 平台具备基础治理能力

周期：

• 4~6 周

V0.5 Studio 可视化版

目标：

• 提升交付效率

交付：

• 可视化流程设计器
• Agent / Team 配置台
• 技能和工具配置台
• 回放与调试页面
• 评测面板

验收标准：

• 大部分应用可通过平台配置完成搭建

周期：

• 4~6 周

V1.0 企业生产版

目标：

• 进入生产化稳定运营

交付：

• 多租户
• 配额与计费
• 高可用部署
• 沙箱执行
• 插件市场
• 第三方工作流导入适配器
• 大规模性能优化

验收标准：

• 可稳定支撑多个生产应用和复杂工作流

周期：

• 6~8 周

14. MVP 与最终形态的关系

初期不建议一开始就拆十几个独立服务上线。更稳妥的方式是：

阶段 A

• 先按多服务边界写代码
• 但物理上只部署为 3~4 个服务

建议初期合并：

• session-service + workflow-service
• agent-service + team-service + model-gateway
• tool-service + retrieval-service + memory-service

阶段 B

• 当并发量和复杂度上来后再独立拆出热点服务

这样既保留横向扩展能力，也避免前期微服务治理成本过高。

15. 技术选型建议

• Python：3.11+
• Web 框架：FastAPI
• 数据校验：Pydantic v2
• ORM：SQLAlchemy 2.x
• 迁移：Alembic
• 任务队列：Celery 或 Dramatiq
• 消息队列：Kafka 或 RabbitMQ
• 缓存：Redis
• 主数据库：PostgreSQL
• 向量检索：pgvector
• 对象存储：MinIO
• 容器化：Docker + Kubernetes
• 可观测：OpenTelemetry + Prometheus + Grafana

16. 风险与治理建议

16.1 主要风险

• 过早微服务化导致研发效率低
• 多智能体成本和延迟快速上升
• 记忆污染导致答复不稳定
• 工具权限控制不到位带来安全问题
• 流程 DSL 演进失控导致兼容性问题

16.2 治理建议

• 所有协议强制版本化
• 所有节点执行结果强制 trace
• 所有工具调用强制审计
• 所有记忆写入建立策略控制
• 长链路任务默认异步执行
• 先支持 80% 场景，再做高级自治能力

17. 结论

这套平台的正确建设路径，不是从“聊天机器人”出发，而是从“可横向扩展的流程运行内核”出发。只有先把工作流执行、状态管理、记忆隔离、服务边界和异步通信做好，后面的多智能体、复杂业务编排、Studio 可视化和企业级治理才能稳稳落下去。

如果下一步进入实施，建议优先产出两份工程文档：

1. 数据库表结构设计
2. Monorepo 代码骨架与各服务启动模板