# agentflow

**Repository Path**: codeok/agentflow

## Basic Information

- **Project Name**: agentflow
- **Description**: 智能体平台，微服务架构，采用spring-ai-2.0、langgraph4j、agentscope等技术，支持多智能体协作，agentic-rag, workflow 等功能，基于https://gitee.com/aizuda/snail-ai.git  二次开发
- **Primary Language**: Java
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-07-31
- **Last Updated**: 2026-07-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AgentFlow

> 企业级 AI Agent 协作平台 —— 可视化创建、编排和监控多 Agent 工作流。

AgentFlow 基于 **Spring Boot 4.0.6** + **Spring AI 2.0.0-RC2**，采用 **Supervisor + Worker** 协作架构，支持私有化部署、可视化工作流编排、Agentic RAG、MCP 工具扩展、A2A 跨实例通信与全链路可观测。

---

## 目录

1. [核心特性](#1-核心特性)
2. [架构总览](#2-架构总览)
3. [微服务拓扑](#3-微服务拓扑)
4. [Supervisor + Worker 协作](#4-supervisor--worker-协作)
5. [核心子系统](#5-核心子系统)
6. [技术栈](#6-技术栈)
7. [快速开始](#7-快速开始)
8. [项目结构](#8-项目结构)
9. [文档资源](#9-文档资源)

---

## 1. 核心特性

- **Supervisor + Worker 协作** — Supervisor Agent（:8102）6-Stage Pipeline；React Worker（:8104）5-Phase ReAct；Workflow Worker（:8106）Dify 风格 DAG；Coder Worker（:8108）AgentScope Harness。
- **Memory 服务已内聚到 Platform** — 长期记忆/用户画像/事实/调试统一收敛到 agentflow-platform(:8101)，原 RAG/RAG-Search memory 模块已删除。
- **AG-UI 协议迁移完成** — Supervisor + 6 Worker 全部从 SSE 38 事件升级为 AG-UI 事件流（@ag-ui/client 0.0.57 + @ai-sdk/react）。
- **可视化 Workflow 编排** — Vue Flow 拖拽式编辑器 + LangGraph4j 后端引擎，支持 9 类节点、Checkpoint 持久化、人工审批挂起。
- **Agentic RAG v2** — `agentflow-rag`（:8103）入库 + 切片语义增强；`agentflow-rag-search`（:8111）HYBRID/AGENTIC 双索引 RRF 融合。
- **PostgreSQL 全栈** — 4 库分库（agent / workflow / model / rag），2026-06 全部迁移完成。
- **MCP 工具生态** — stdio / SSE / Streamable HTTP 三传输，ToolGuard 安全分级。
- **A2A 1.0 跨实例通信** — JSON-RPC 2.0 扩展，封装为 `agentflow-a2a-starter`。
- **全链路可观测** — OTel Micrometer Tracing + W3C `traceparent` 跨服务透传。

### 产品界面

#### 知识库切片详情

![知识库切片详情](docs/knowledge-chunk.png)

#### 业务意图库

![业务意图库](docs/intent-tree.png)

#### 可视化工作流编辑器

![可视化工作流编辑器](docs/workflow-editor.png)

---

## 2. 架构总览

```
═══════════════════════════════════════════════════════════════════════════════════
                              接入层   (Access Layer)
═══════════════════════════════════════════════════════════════════════════════════
  浏览器 / 移动端 / Vue3 后台 (:5173) / React 聊天 (:5174) / MCP 客户端
                                          │ HTTP / AG-UI Event Stream
═══════════════════════════════════════════════════════════════════════════════════
                           静态层   (Static Layer :8098 Nginx)
═══════════════════════════════════════════════════════════════════════════════════
  frontend/dist + frontend-chat/dist
                                          │ /api/** + /chat/
═══════════════════════════════════════════════════════════════════════════════════
                          网关层   (Gateway Layer :8100)
═══════════════════════════════════════════════════════════════════════════════════
  agentflow-gateway — JWT 认证 · Redis 限流 · 路由转发
       │
       ├── /api/agent/**      → 8102
       ├── /api/model/**      → 8085
       ├── /api/rag/**        → 8103
       ├── /api/rag-search/** → 8111
       ├── /api/platform/**   → 8101  ← Memory / Agent / User / Eval
       ├── /api/admin/**      → 8105 (BFF)
       ├── /api/workflow/**   → 8106
       └── /api/coder/**      → 8108

═══════════════════════════════════════════════════════════════════════════════════
                              服务层   (Service Layer)
═══════════════════════════════════════════════════════════════════════════════════
  ┌─────────────────────────────────────────────────────────────────────────────┐
  │  BFF 薄代理层  admin (:8105)                                                  │
  │  ─ Feign → platform / agent / rag / rag-search / model / workflow / coder     │
  └─────────────────────────────────────────────────────────────────────────────┘

  智能体协作层 (Supervisor + Workers)
  ┌────────────────────┐  ┌────────────────────┐  ┌────────────────────┐
  │ Supervisor Agent   │  │ Workflow Worker    │  │ React Worker       │
  │ :8102  public      │  │ :8106  public      │  │ :8104  agentflow   │
  │ 6-Stage Pipeline   │  │ LangGraph4j 9 节点 │  │ 5-Phase ReAct      │
  └─────────┬──────────┘  └─────────┬──────────┘  └─────────┴──────────┘
            │                       │                       │
            └───────────┬───────────┴───────────────────────┘
                        │ A2A 1.0 / Feign SDK
  ┌─────────────────────┴─────────────────────────────────────────────────┐
  │ 领域服务层                                                            │
  │  platform(8101) · model(8085) · rag(8103) · rag-search(8111)           │
  │  coder(8108)                                                          │
  └───────────────────────────────────────────────────────────────────────┘

═══════════════════════════════════════════════════════════════════════════════════
                  基础设施层   (Infrastructure Layer · 192.168.1.4)
═══════════════════════════════════════════════════════════════════════════════════
  PostgreSQL(15432) · Redis(6379) · Nacos(8848) · Milvus(19530) · ES(9200) · MinIO(9000)
```

### 关键架构决策

| 决策 | 原因 |
|------|------|
| Supervisor + Workers 解耦 | Supervisor 有状态（PG/Redis），Worker 无状态可水平扩展 |
| Workflow 独立 Worker | DAG 编排是独立业务域，避免污染 Supervisor 主链路 |
| Memory 收敛到 Platform | 长期记忆与 Agent/用户域紧密耦合，统一在 8101 提供可视化与 API |
| RAG 读写分离 | rag(8103) 入库/CRUD，rag-search(8111) 召回/双索引 |
| AG-UI 替代自研 SSE 38 事件 | 标准化事件协议 + 多端 SDK 复用 |
| A2A 1.0 统一协议 | react / coder / workflow / rag-search 均通过 `agentflow-a2a-starter` 暴露 |
| Nacos 跨 namespace | react/react-mesh 在 `agentflow` 命名空间，与主服务（public）解耦 |

---

## 3. 微服务拓扑

### 3.1 服务端口速查

| 端口 | 服务 | 角色 | Nacos ns |
|------|------|------|----------|
| 8085 | agentflow-model | 模型网关（厂商/Key 管理） | public |
| 8098 | frontend (Nginx) | 静态前端（Vue + React Chat） | — |
| 8100 | agentflow-gateway | API 网关 | public |
| 8101 | agentflow-platform | 平台核心（用户/Agent/Memory/Eval） | public |
| **8102** | **agentflow** | **Supervisor Agent** | public |
| 8103 | agentflow-rag | RAG 入库（ETL/文档/切片） | public |
| **8104** | **agentflow-react** | **React Worker（5-Phase ReAct）** | `agentflow` |
| 8105 | agentflow-admin | BFF 薄 Feign 代理 | public |
| **8106** | **agentflow-workflow** | **Workflow Worker（LangGraph4j）** | public |
| 8107 | agentflow-react-mesh | React Worker 副实例（mesh 拓扑） | `agentflow` |
| 8108 | agentflow-coder | Coder Worker（AgentScope Harness） | public |
| 8111 | agentflow-rag-search | RAG Search Worker（召回/双索引） | public |

> 11 端口全部 `200` 才算部署成功。本地 deploy 统一走 `.claude/skills/agentflow-ops/deploy/`，远端应急脚本保留 `scripts/start-agentflow-*.sh`。

### 3.2 服务间通信

| 通信方式 | 路径 | 协议 / 组件 |
|----------|------|------------|
| Gateway → 各服务 | `/api/{service}/**` | Spring Cloud Gateway |
| Admin (BFF) → 各服务 | Feign SDK | OpenFeign |
| Supervisor → React Worker | `ReactExecutionClient` | Feign SDK + Nacos 跨 ns |
| Supervisor → Coder/Workflow/RAG-Search | A2A 1.0 | `agentflow-a2a-starter` |
| Agent ↔ Platform | gRPC :18888 | 内部高频通信 |
| Supervisor/Worker → User | AG-UI Event Stream | SSE 兼容 |

---

## 4. Supervisor + Worker 协作

### 4.1 职责分工

| 维度 | Supervisor (8102) | React Worker (8104) | Coder Worker (8108) | Workflow Worker (8106) |
|------|-------------------|---------------------|---------------------|------------------------|
| 角色 | 监督者 / 调度者 | ReAct 专家 | 编程专家 | 工作流编排 |
| 状态 | 有状态（PG/Redis） | 无状态 | 仅缓存 session | 有状态（PG） |
| 核心职责 | 感知/记忆/路由/规划/委派/观测 | LLM 推理/Tool Calling | Coding Agent / Harness | DAG 编排/Checkpoint |
| Maven 模块 | `agentflow` | `agentflow-react` | `agentflow-coder` | `agentflow-workflow` |

### 4.2 SupervisorPipeline 6-Stage

```
Perception(感知) → Memory(记忆) → Routing(路由) → Planning(规划) → Execution(执行) → Observation(观测)
```

- **感知**：AgentConfig 加载、ArchetypeRouter 判定
- **记忆**：调用 Platform(:8101) STM 滑窗 + 场景化 LTM 召回（按 `intentDomain` 过滤）
- **路由**：LlmRouter v2 + ContinuationRouter 多轮延续，6 RouteMode 分级
- **规划**：Planner SPI 拆分 PlanStep
- **执行**：WorkerManager 通过 A2A 委派 Worker，或 Supervisor 内置 ChatClient 自处理
- **观测**：OTel span、STM 回写、MTM/LTM 异步归档

### 4.3 请求生命周期

```
User → Gateway(8100) → admin(8105) → Supervisor(8102)
                                          │
              ┌───────────────────────────┼───────────────────────────┐
              ▼                           ▼                           ▼
         [CHAT]                      [TOOL/WORKER]              [PLAN/MULTI_WORKER]
    Supervisor 内置 ChatClient    WorkerManager → A2A          Planner + WorkerManager
                                  react(8104) P1-P5            Checkpoint 持久化
```

### 4.4 路由模式（RouteMode）

| RouteMode | 触发条件 | 执行路径 |
|-----------|---------|---------|
| CHAT | 简单问候/闲聊（agentType=supervisor） | Supervisor 内置 ChatClient，跳过工具调用 |
| TOOL | 需要工具调用 | Supervisor → React Worker 5-Phase |
| WORKER | 指定 Worker A2A 委派 | Supervisor → 指定 Worker |
| WORKFLOW | 可视化工作流 | Supervisor → Workflow Worker (8106) |
| PLAN | 复杂长期规划 | Planner + WorkerManager + Checkpoint |
| MULTI_WORKER | 多 Worker 协作 | WorkerManager 并行/串行调度 |

> `agentType` 三值约定：`supervisor` / `expert` / `worker`（2026-06 统一）。

---

## 5. 核心子系统

### 5.1 Workflow 工作流引擎

`agentflow-workflow (:8106)` 提供 Dify/n8n 风格的可视化工作流编排，被 Supervisor 通过 A2A 委派调用。

- **9 类节点**：LlmChat、HttpCall、RagSearch、McpTool、CodeNode、ParameterExtractor、ConditionBranch、HumanApproval、SubWorkflow
- **持久化**：PostgreSQL 存储 `WorkflowDefinition`，Checkpoint 支持 `PostgresSaver` / `MemorySaver`
- **交互**：Vue Flow 拖拽编辑器 + AG-UI 流式执行 + 人工审批挂起

### 5.2 Agentic RAG 知识库

| 服务 | 端口 | 职责 |
|------|------|------|
| agentflow-rag | 8103 | ETL 入库、文档/切片/知识库 CRUD、DocumentCleaner + ChunkEnhancer + SemanticEnhancementStrategy 流水线 |
| agentflow-rag-search | 8111 | HYBRID/AGENTIC 召回、QA 索引 + dense 索引 RRF 融合、A2A 暴露 |

Agentic RAG 采用 6 节点 StateGraph：`QueryUnderstanding → Retrieve → Grade → Synthesize → Verify → Router`，支持多跳推理。

### 5.3 Memory 服务（已收敛到 Platform :8101）

长期记忆（MTM/LTM）、用户画像、事实表、记忆调试可视化统一由 `agentflow-platform` 提供。
RAG/RAG-Search 的 memory 模块代码、WebClient 配置均已删除。

API：`/api/platform/memory/**`

### 5.4 A2A 通信协议

基于 JSON-RPC 2.0 扩展的 A2A 1.0 协议，通过 `agentflow-a2a-starter` 自动装配。

通用端点：

| 方法 | 路径 | 用途 |
|------|------|------|
| POST | `/api/a2a/execute` | 执行 Agent 任务（AG-UI 流） |
| POST | `/api/a2a/cancel` | 幂等取消 |
| GET  | `/api/a2a/discover` | 发现 Agent 能力（AgentCard） |
| GET  | `/api/a2a/health`  | 深度健康检查 |

### 5.5 API 规范

```
/api/{service-name}/{domain}/{path}        # 外部 API
/api/admin/{service-name}/{domain}/{path}  # BFF 内部调用
```

- `{service-name}` 使用 kebab-case
- `/admin/` 仅限 BFF，Gateway 通过 `InternalAccessBlockFilter` 拦截防止外网访问

### 5.6 AG-UI 事件协议

Phases 0–6 全部完成：Supervisor（8102）+ 6 个 Worker（react/react-mesh/coder/workflow/rag-search/platform）全部从自研 SSE 38 事件迁移到 AG-UI 标准事件流。前端使用 `@ag-ui/client` + `@ai-sdk/react` 消费。

---

## 6. 技术栈

### 6.1 后端

| 技术 | 版本 | 用途 |
|------|------|------|
| Java | 21 | 主语言 |
| Spring Boot | 4.0.6 | 应用框架 |
| Spring Cloud | 2025.1.1 | 微服务治理 |
| Spring Cloud Alibaba | 2025.1.0.0 | Nacos 注册发现/配置 |
| Spring AI | 2.0.0-RC2 | AI 核心框架 |
| LangChain4j | 0.34.0 | Agent 编排 |
| LangGraph4j | 1.8.17 | Workflow Checkpoint |
| MyBatis-Plus | 3.5.16 | ORM |
| gRPC | 1.72.0 | 高性能服务间通信 |
| Resilience4j | 最新 | 熔断/限流/重试 |
| A2A Java SDK | 1.0.0.Alpha3 | 跨实例 Agent 协议 |

### 6.2 基础设施

| 组件 | 地址 | 用途 |
|------|------|------|
| Nacos | `192.168.1.4:8848` | 服务注册发现 + 配置中心 |
| PostgreSQL | `192.168.1.4:15432` | 主数据库（4 库分库：`agentflow_agent` / `agentflow_workflow` / `agentflow_model` / `agentflow_rag`） |
| Redis | `192.168.1.4:6379` | 网关限流 + 缓存 |
| Milvus | `192.168.1.4:19530` | 向量检索 |
| Elasticsearch | `192.168.1.4:9200` | 全文检索 |
| MinIO | `192.168.1.4:9000` | 对象存储 |

### 6.3 前端

| 技术 | 用途 |
|------|------|
| Vue 3.5 + Vite 7 + TypeScript | 管理后台（NaiveUI + UnoCSS，soybean 衍生） |
| React 19 + TypeScript | 聊天前端（AG-UI 协议 + TailwindCSS） |
| @ag-ui/client 0.0.57 | AG-UI 事件流客户端 |
| @ai-sdk/react + ai 6.x | Vercel AI SDK |
| Pinia | 状态管理 |
| Vue Flow | 工作流可视化编辑器 |
| ECharts 6.0 | 图表可视化 |

---

## 7. 快速开始

### 7.1 环境要求

JDK 21+ · Maven 3.9+ · PostgreSQL 15+ · Redis 6.0+ · Nacos 2.x · Milvus 2.x · MinIO · Node.js 20+ · pnpm 10+

### 7.2 构建

```bash
mvn clean install -Drevision=0.0.1 -DskipTests

# 指定模块
mvn clean install -Drevision=0.0.1 -pl agentflow -am
mvn clean install -Drevision=0.0.1 -pl agentflow-react -am
mvn clean install -Drevision=0.0.1 -pl agentflow-workflow -am
mvn clean install -Drevision=0.0.1 -pl agentflow-platform -am
```

### 7.3 部署

```bash
# 本地统一 deploy（推荐）
# 详见 .claude/skills/agentflow-ops/deploy/
# backend: deploy-{model|gateway|platform|agent|rag|admin}.sh
# react:   deploy-{react|react-mesh}.sh
# workflow: deploy-workflow.sh
# frontend: deploy.sh
# verify:   11 端口健康检查

# 远端应急启动脚本（保留）
bash /home/admin/apps/agentflow/start-agentflow.sh
bash /home/admin/apps/agentflow/scripts/start-agentflow-rag-search.sh start
bash /home/admin/apps/agentflow/scripts/start-agentflow-coder.sh start
bash /home/admin/apps/agentflow/scripts/start-agentflow-mock.sh start
```

### 7.4 前端开发

```bash
cd frontend && pnpm install && pnpm dev        # :5173
cd frontend-chat && pnpm install && pnpm dev   # :5174
```

### 7.5 健康检查

```bash
for port in 8085 8100 8101 8102 8103 8104 8105 8106 8107 8108 8111; do
  code=$(curl -s -o /dev/null -w "%{http_code}" --connect-timeout 5 \
    http://192.168.1.4:$port/actuator/health 2>/dev/null)
  echo "$port: ${code:-DOWN}"
done
```

---

## 8. 项目结构

```
agentflow/
├── agentflow-gateway/          # API 网关 (:8100)
├── agentflow-admin/            # BFF 薄代理 (:8105)
├── agentflow-platform/         # 平台核心 + Memory (:8101)
├── agentflow/                  # Supervisor Agent (:8102)
│   └── src/main/java/com/agentflow/agent/supervisor/  # 6-Stage Pipeline
├── agentflow-react/            # React Worker (:8104)，8107 副实例通过 -Dspring.application.name 启动
├── agentflow-workflow/         # Workflow Worker (:8106)
├── agentflow-coder/            # Coder Worker (:8108)
├── agentflow-rag/              # RAG 入库服务 (:8103)
├── agentflow-rag-search/       # RAG Search Worker (:8111)
├── agentflow-model/            # 模型网关 (:8085)
├── agentflow-mock/             # Mock MCP 桩服务
├── agentflow-client/           # Feign SDK 纯契约层
├── agentflow-common/           # 公共模块
├── agentflow-starters/         # 自动装配 Starter
│   ├── agentflow-a2a-starter/
│   └── agentflow-mcp-starter/
├── agentflow-eval/             # 评测套件（22 维 LLM judge + 9 capability Provider）
├── frontend/                   # Vue3 管理后台
├── frontend-chat/              # React 19 聊天前端
├── docs/                       # 设计文档
├── scripts/                    # 远端应急启动脚本
├── .claude/skills/agentflow-ops/deploy/   # 本地统一部署脚本（SSOT）
├── AGENTS.md                   # 中间件地址与服务调用关系
├── CLAUDE.md                   # 工程规范与权威源
└── README.md                   # 本文件
```

---

## 9. 文档资源

### 9.1 权威文档

| 文档 | 用途 |
|------|------|
| [CLAUDE.md](CLAUDE.md) | 工程规范 / 构建 / 技术栈 / 拓扑 / 路由 / API / 运维（唯一权威源） |
| [AGENTS.md](AGENTS.md) | 中间件地址 / 服务调用关系 / 补充事实 |

### 9.2 核心设计文档

| 文档 | 用途 |
|------|------|
| [docs/agentflow-chat-pipeline.md](docs/agentflow-chat-pipeline.md) | SupervisorPipeline 6-Stage 详细设计 |
| [docs/agentflow-sse-protocol-spec.md](docs/agentflow-sse-protocol-spec.md) | AG-UI 迁移前的 SSE 38 事件协议（历史） |
| [docs/agentic-rag-migration-plan.md](docs/agentic-rag-migration-plan.md) | Agentic RAG 迁移方案 |
| [docs/agentflow-rag-knowledge-time-effect.md](docs/agentflow-rag-knowledge-time-effect.md) | 知识时效 V0_0_6 |
| [docs/agentflow-observability-analysis.md](docs/agentflow-observability-analysis.md) | 可观测性分析 |
| [docs/coding-agent-plan.md](docs/coding-agent-plan.md) | Coder Worker 设计方案 |
| [docs/agentflow-memory-scenario-recall.md](docs/agentflow-memory-scenario-recall.md) | 场景化长期记忆召回 |
| [docs/agentflow-mcp-tool-row-permission.md](docs/agentflow-mcp-tool-row-permission.md) | MCP 工具行级权限 |

### 9.3 产品与运维

| 文档 | 用途 |
|------|------|
| [docs/product-design.md](docs/product-design.md) | 产品总设计 |
| [docs/agentflow-ops.md](docs/agentflow-ops.md) | 运维操作规范 |
| [docs/agentflow-test.md](docs/agentflow-test.md) | 端到端测试指南 |
| [docs/agent-mock-services.md](docs/agent-mock-services.md) | Mock MCP 桩服务说明 |
| [docs/sql/](docs/sql/) | 数据库初始化脚本 |
| [.claude/skills/agentflow-ops/deploy/](.claude/skills/agentflow-ops/deploy/) | 本地统一部署脚本（SSOT） |

---

> 本文档与 [CLAUDE.md](CLAUDE.md) / [AGENTS.md](AGENTS.md) 共同构成项目文档体系：
> - **CLAUDE.md** — 工程规范唯一权威源
> - **AGENTS.md** — 中间件地址与服务调用关系
> - **README.md** — 面向开发者的架构总览与快速入门