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

## 1. 项目定位

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

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

一句话定位：

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

## 2. 建设原则

### 2.1 架构原则

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

### 2.2 工程原则

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

## 3. 总体架构

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

### 3.1 逻辑分层

1. 接入层
- API Gateway
- Web Studio
- SDK / Webhook

2. 编排与运行层
- Session Service
- Workflow Service
- Agent Runtime Service
- Team Runtime Service
- Scheduler Service

3. 能力层
- Tool Service
- Skill Service
- Memory Service
- Retrieval Service
- Plugin Service
- Model Gateway

4. 支撑层
- Auth Service
- Trace / Eval Service
- Notification Service
- File / Artifact Service

5. 基础设施层
- PostgreSQL
- Redis
- pgvector
- MinIO
- Kafka / RabbitMQ
- 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，多服务共享基础库。

```text
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 服务代码结构建议

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

```text
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 代码骨架与各服务启动模板