social-app/docs/plans/2026-03-08-agent-tool-architecture-design.md

Agent Tool Architecture Design

Date: 2026-03-08 Source: docs/bugs/2026-03-08-agent-tool-architecture.md Scope: backend/src/core/agent Status: Approved for planning

---

1. Objective

修复 Agent 工具架构相关 8 个问题，优先恢复端到端闭环能力（工具审批后继续推理并产出最终回复），并在同版本内补齐工具输出结构化、存储分层、阶段策略解耦、多模态与语音输入能力。

---

2. Deliverables

1. 两阶段修复蓝图（Phase 1 + Phase 2）
2. 统一事件与状态机设计（AG-UI Step 事件 + 审批恢复）
3. 接口边界与职责重划分（run/resume/runtime/persistence）
4. 风险与回滚策略
5. 验收标准（双金路径）

---

3. Constraints And Decisions

3.1 Release Strategy

• 一次性切换
• 不做灰度
• 不做双轨
• 不留兼容代码

3.2 Contract Decisions

• run 接口允许破坏性变更：移除前端传完整历史 messages 的语义
• 前端只传本次输入，历史以后端为准
• Phase 1 不引入 client hint
• 工具架构在 Phase 1 完整迁移至 CrewAI Tools（非桥接）

3.3 AG-UI Event Decisions

• 三阶段固定发 StepStarted/StepFinished：intent, execution, organization
• 等待工具审批不单独新增 step，归属 execution 内部状态
• 后端只发英文机器名，前端自行文案化

3.4 ASR / Multimodal Decisions

• 多模态首版只支持文件上传（不支持 URL）
• ASR 首版为“录音结束后上传音频 -> 后端同步返回 transcript”
• 前端将 transcript 回填输入框，再调用 run

---

4. Complexity And Risk

• Complexity: S2（跨多个核心模块的架构调整）
• Risk Tier: L2（包含高危安全项：前端可篡改历史）

风险驱动原则：先修复闭环与安全问题，再扩展能力面。

---

5. Phased Plan

Phase 1 - Close Loop And Stop Security Bleeding

Bugs: #1, #5, #6

Goals

1. 后端成为历史与上下文唯一事实源
2. 工具审批后恢复并继续 Agent Loop
3. 工具执行完整迁移到 CrewAI Tools 注册体系

Module Boundaries

• backend/src/core/agent/application/run_service.py

  • 仅负责本次输入解析、后端上下文组装、触发 runtime
  • 移除前端历史信任路径
  • 移除硬编码工具分发

• backend/src/core/agent/application/resume_service.py

  • 审批确认后触发异步续跑，立即返回 accepted
  • 不可在工具执行后直接置 COMPLETED
  • 增加 approval_request_id 幂等保护

• backend/src/core/agent/infrastructure/crewai/runtime.py

  • 引入 CrewAI Tools 注册与注入
  • 按 agent/stage 装配工具集
  • 三阶段统一发 Step start/end 事件

• backend/src/core/agent/application/session_state_persistence.py

  • 保障审批状态、工具结果、续跑状态一致性落库
  • 为 Phase 2 元数据扩展保留一致接口

Runtime Flow (Phase 1)

1. run 接收本次输入
2. 后端读取 Redis/DB 重建历史
3. 进入 intent/execution/organization 三阶段
4. execution 中若触发工具审批：进入 WAITING_APPROVAL
5. 前端审批后调用 resume
6. resume 异步触发续跑：执行工具 -> 写 tool result -> 继续 loop
7. 生成最终 assistant 回复并 RunFinished

---

Phase 2 - Capability Completion In Same Version

Order: #3 -> #2 -> #4 -> #7 -> #8

#3 Tool Output As UI Schema v1

• 统一工具输出结构：type/version/data/actions
• 单一版本 v1，短期不做多版本并行

#2 Tool Result Object Storage

• 大 payload 存对象存储
• DB 仅存摘要、索引、校验信息
• 启用 storage_bucket/storage_path/payload_sha256

#4 Stage-Level Strategy Decoupling

• intent/execution/organization 支持独立参数与工具策略
• intent 阶段可配置为只读（禁工具）

#7 Multimodal Input

• 首版支持图片文件上传输入
• 不再丢弃非 text 内容

#8 ASR API

• 新增语音转写 API（同步返回 transcript）
• 语音转写与 agent run 解耦

---

6. Session State And Events

推荐状态机：

RUNNING -> WAITING_APPROVAL -> RESUMING -> RUNNING -> COMPLETED/FAILED

关键约束：

• 重复审批请求不得重复执行工具（幂等）
• COMPLETED 仅在 loop 自然结束时设置
• Step 事件覆盖三阶段完整生命周期

---

7. Acceptance Criteria

7.1 Golden Path A (No Tool)

用户输入后，完整经历三阶段并产出最终回复；前端收到完整 step 事件与 RunFinished。

7.2 Golden Path B (Tool + Approval + Resume)

用户触发工具调用，审批后系统异步续跑并最终产出 assistant 回复；会话不在审批后直接结束。

7.3 Security Validation

前端即使提交伪造历史字段，也不会影响后端实际上下文。

7.4 Event Validation

每轮 run 必须包含 intent/execution/organization 的 StepStarted/StepFinished。

---

8. Risk And Rollback

High Risk: #6 Context Ownership Migration

• 风险：上下文错绑、历史缺失
• 控制：会话归属校验 + Redis/DB 一致性读取
• 回滚：可退到“后端 DB-only 历史重建”

High Risk: #5 Async Resume Consistency

• 风险：重复审批、状态卡死
• 控制：审批幂等键 + 状态跃迁约束 + 超时终态
• 回滚：降级为“仅返回工具结果，不自动续跑”

Medium Risk: #2 Storage Split Consistency

• 风险：对象存储与 DB 元数据不一致
• 控制：先对象后元数据 + 失败补偿清理
• 回滚：临时退回 DB 内联存储

---

9. Bug-To-Phase Mapping

• Phase 1: #1, #5, #6
• Phase 2: #2, #3, #4, #7, #8

---

10. Next Step

进入 implementation planning：将本设计拆解为任务级可执行计划（文件、测试、命令、验收证据）。