14 KiB
14 KiB
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