209 lines
14 KiB
Markdown
209 lines
14 KiB
Markdown
# 00 - 多 Agent 协作架构总览
|
||
|
||
## 1. 设计哲学
|
||
|
||
本系统借鉴 Claude Code 的核心架构理念：
|
||
|
||
> **程序做脚手架，LLM 做决策。**
|
||
|
||
- 程序只负责：循环、注入上下文、执行工具、限流、权限
|
||
- LLM 负责：理解用户意图、选择策略、调用工具、判断完成
|
||
- 多个专业 Agent 各司其职，由 Coordinator 统一编排
|
||
|
||
与旧架构的根本区别：**不再用程序化状态机控制对话流程**，而是通过精心设计的 Prompt 引导 LLM 自主决策。
|
||
|
||
## 2. 整体架构图
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Frontend │
|
||
│ web-client (React + Socket.io) │
|
||
│ ┌─────────────┐ ┌──────────────┐ ┌───────────────┐ │
|
||
│ │ ChatWindow │ │ AgentStatus │ │ MessageBubble │ │
|
||
│ └──────┬──────┘ └──────────────┘ └───────────────┘ │
|
||
│ │ WebSocket │
|
||
└─────────┼───────────────────────────────────────────────────┘
|
||
│
|
||
┌─────────▼───────────────────────────────────────────────────┐
|
||
│ Conversation Gateway (WebSocket) │
|
||
│ conversation.gateway.ts │
|
||
└─────────┬───────────────────────────────────────────────────┘
|
||
│
|
||
┌─────────▼───────────────────────────────────────────────────┐
|
||
│ Conversation Service │
|
||
│ conversation.service.ts │
|
||
│ (消息持久化、对话管理、Token 追踪) │
|
||
└─────────┬───────────────────────────────────────────────────┘
|
||
│
|
||
┌─────────▼───────────────────────────────────────────────────┐
|
||
│ Coordinator Agent Service (主协调器) │
|
||
│ coordinator-agent.service.ts │
|
||
│ │
|
||
│ ┌──────────────────────────────────────────────────────┐ │
|
||
│ │ Agent Loop (递归 async generator) │ │
|
||
│ │ │ │
|
||
│ │ ┌──────────────┐ ┌─────────────────────┐ │ │
|
||
│ │ │ Context │───→│ Claude API (Sonnet) │ │ │
|
||
│ │ │ Injector │ │ + Coordinator Prompt │ │ │
|
||
│ │ │ (动态上下文) │ │ + Agent Tools │ │ │
|
||
│ │ └──────────────┘ └──────────┬──────────┘ │ │
|
||
│ │ │ │ │
|
||
│ │ ┌────────────▼────────────┐ │ │
|
||
│ │ │ Tool Execution Queue │ │ │
|
||
│ │ │ (并发/串行调度) │ │ │
|
||
│ │ └────────────┬────────────┘ │ │
|
||
│ │ │ │ │
|
||
│ │ ┌──────────────────┼──────────────┐ │ │
|
||
│ │ ▼ ▼ ▼ │ │
|
||
│ │ ┌─────────────┐ ┌─────────────┐ ┌──────────┐ │ │
|
||
│ │ │ Agent Tools │ │ Agent Tools │ │ Direct │ │ │
|
||
│ │ │ (invoke_xxx) │ │ (invoke_xxx) │ │ Tools │ │ │
|
||
│ │ │ → Specialist │ │ → Specialist │ │ (payment │ │ │
|
||
│ │ │ API Call │ │ API Call │ │ search) │ │ │
|
||
│ │ └──────┬──────┘ └──────┬──────┘ └────┬─────┘ │ │
|
||
│ │ │ │ │ │ │
|
||
│ │ ▼ ▼ ▼ │ │
|
||
│ │ ┌─────────────────────────────────────────┐ │ │
|
||
│ │ │ tool_results → 递归回 Agent Loop │ │ │
|
||
│ │ └─────────────────────────────────────────┘ │ │
|
||
│ └──────────────────────────────────────────────────┘ │
|
||
└──────────────────────────────────────────────────────────┘
|
||
|
||
┌──────────────────────────────────────────────────────────┐
|
||
│ Specialist Agents │
|
||
│ │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ Policy │ │ Assessment │ │ Strategist │ │
|
||
│ │ Expert │ │ Expert │ │ │ │
|
||
│ │ (Sonnet) │ │ (Sonnet) │ │ (Sonnet) │ │
|
||
│ │ Tools: │ │ Tools: │ │ Tools: │ │
|
||
│ │ - search_kb │ │ - search_kb │ │ - get_user │ │
|
||
│ └──────────────┘ │ - get_user │ │ _context │ │
|
||
│ └──────────────┘ └──────────────┘ │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ Objection │ │ Case │ │ Memory │ │
|
||
│ │ Handler │ │ Analyst │ │ Manager │ │
|
||
│ │ (Sonnet) │ │ (Haiku) │ │ (Haiku) │ │
|
||
│ │ Tools: │ │ Tools: │ │ Tools: │ │
|
||
│ │ - search_kb │ │ - search_kb │ │ - save_mem │ │
|
||
│ │ - get_user │ │ - get_user │ │ - get_user │ │
|
||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||
└──────────────────────────────────────────────────────────┘
|
||
|
||
┌──────────────────────────────────────────────────────────┐
|
||
│ External Services │
|
||
│ │
|
||
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
|
||
│ │ Knowledge │ │ Payment │ │ Evolution │ │
|
||
│ │ Service │ │ Service │ │ Service │ │
|
||
│ │ (RAG+Neo4j)│ │ (Alipay/ │ │ (Analytics│ │
|
||
│ │ Port 3003 │ │ WeChat) │ │ +Learn) │ │
|
||
│ │ │ │ Port 3002 │ │ Port 3005 │ │
|
||
│ └───────────┘ └───────────┘ └───────────┘ │
|
||
└──────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 3. 七个 Agent 一览
|
||
|
||
| Agent | 角色 | Model | 工具 | 触发时机 |
|
||
|-------|------|-------|------|----------|
|
||
| **Coordinator** | 主协调器，面对用户 | Sonnet | invoke_* + 直接工具 | 每次用户消息 |
|
||
| **Policy Expert** | 政策专家 | Sonnet | search_knowledge | 用户问政策、条件、流程 |
|
||
| **Assessment Expert** | 评估专家 | Sonnet | search_knowledge, get_user_context | 需要评估用户资格时 |
|
||
| **Strategist** | 策略顾问 | Sonnet | get_user_context | 需要对话策略建议时 |
|
||
| **Objection Handler** | 异议处理 | Sonnet | search_knowledge, get_user_context | 用户表达顾虑/犹豫 |
|
||
| **Case Analyst** | 案例分析 | Haiku | search_knowledge, get_user_context | 需要用案例说服用户 |
|
||
| **Memory Manager** | 记忆管理 | Haiku | save_user_memory, get_user_context | 需要保存/加载用户信息 |
|
||
|
||
## 4. 消息流转完整路径
|
||
|
||
```
|
||
1. 用户发送消息 (WebSocket: 'message' event)
|
||
│
|
||
2. ConversationGateway → ConversationService.sendMessage()
|
||
│
|
||
3. ConversationService:
|
||
│ a. 验证对话所有权
|
||
│ b. 保存用户消息
|
||
│ c. 构建 ConversationContext (last 20 messages + state)
|
||
│ d. 调用 CoordinatorAgentService.sendMessage()
|
||
│
|
||
4. CoordinatorAgentService → agentLoop():
|
||
│ a. ContextInjector 注入动态上下文:
|
||
│ - 用户历史记忆摘要
|
||
│ - 已收集的用户信息
|
||
│ - 对话统计（轮次、时长）
|
||
│ - 最近的评估结果
|
||
│ - 相关知识预检索
|
||
│
|
||
│ b. 调用 Claude API (Sonnet, streaming)
|
||
│ → yield: text chunks (流式传输给前端)
|
||
│ → yield: agent_start / agent_progress events
|
||
│
|
||
│ c. 如果 Claude 返回 tool_use:
|
||
│ │
|
||
│ ├── invoke_policy_expert({...})
|
||
│ │ → PolicyExpertService.execute()
|
||
│ │ → 独立 Claude API 调用 (Sonnet)
|
||
│ │ → 内部可调 search_knowledge (最多 3 轮)
|
||
│ │ → 返回结构化政策信息
|
||
│ │
|
||
│ ├── invoke_assessment_expert({...})
|
||
│ │ → AssessmentExpertService.execute()
|
||
│ │ → 独立 Claude API 调用 (Sonnet)
|
||
│ │ → 返回评估报告
|
||
│ │
|
||
│ ├── generate_payment({...}) [直接工具，不调 Agent]
|
||
│ │ → 调用 payment-service API
|
||
│ │ → 返回支付链接
|
||
│ │
|
||
│ └── get_current_datetime() [直接工具，不调 Agent]
|
||
│ → 返回当前时间
|
||
│
|
||
│ d. ToolExecutionQueue:
|
||
│ - Agent 调用之间可并行（invoke_policy + invoke_memory 并行）
|
||
│ - Agent 调用与直接工具可并行
|
||
│ - 写操作串行（save_user_memory）
|
||
│
|
||
│ e. tool_results 返回后 → 递归回步骤 b
|
||
│ Coordinator 综合所有结果，生成最终回复
|
||
│
|
||
│ f. 无 tool_use → 自然结束递归
|
||
│
|
||
5. ConversationService:
|
||
│ a. 聚合完整回复
|
||
│ b. 保存助手消息
|
||
│ c. 更新对话统计 (tokens, message count)
|
||
│ d. 提取并保存咨询状态
|
||
│
|
||
6. ConversationGateway → WebSocket events:
|
||
- stream_start
|
||
- agent_start {agentName: "policy_expert"}
|
||
- stream_chunk {content: "..."}
|
||
- agent_complete {agentName: "policy_expert"}
|
||
- stream_chunk {content: "综合分析..."}
|
||
- stream_end {usage: {...}}
|
||
```
|
||
|
||
## 5. 与旧架构的关键区别
|
||
|
||
| 方面 | 旧架构 | 新架构 |
|
||
|------|--------|--------|
|
||
| 对话流程控制 | 策略引擎（程序状态机，8 阶段） | Coordinator Prompt（LLM 自主判断） |
|
||
| 意图分类 | IntentClassifier（规则匹配） | LLM 自行理解意图 |
|
||
| 响应质量 | ResponseGate（关键词检查） | Prompt 内置质量标准 |
|
||
| 工具调用 | 单 Agent 串行调 10 个工具 | Coordinator 编排，专家 Agent 各持少量工具 |
|
||
| 评估逻辑 | 程序化评分算法 | Assessment Expert (LLM + 知识库) |
|
||
| 并发能力 | 无 | ToolExecutionQueue 并发调度 |
|
||
| 上下文管理 | 固定拼接 last 20 messages | 动态注入 8+ 种上下文 |
|
||
| 扩展性 | 改代码加阶段/工具 | 新增 Agent + 注册工具 |
|
||
|
||
## 6. 技术栈
|
||
|
||
- **Runtime**: Node.js 18+ / NestJS 10
|
||
- **AI SDK**: @anthropic-ai/sdk 0.52+
|
||
- **Models**: claude-sonnet-4-20250514 (主力), claude-haiku (辅助)
|
||
- **Streaming**: AsyncGenerator + WebSocket (Socket.io)
|
||
- **Database**: PostgreSQL + pgVector (RAG), Neo4j (知识图谱), Redis (缓存)
|
||
- **Frontend**: React 18 + Zustand + Socket.io-client
|