social-app/docs/plans/2026-03-04-agent-hard-reset-design.md

Agent 后端硬切重构设计

目标

• 一次性移除现有 Agent 运行时代码、测试和旧文档契约，避免新旧方案并存。
• 仅从后端重新设计 Agent 体系，不依赖前端实现细节。
• 新方案必须满足以下六项要求：
  1. 配置层可通过 .env 驱动 LLM API Key。
  2. 对话与 resume 通过 Celery 队列处理，不阻塞 Web 主线程。
  3. v1/agent 仅负责路由组织与服务调用，核心逻辑在 core/agent。
  4. 按 CrewAI 官方模型组织 Agent/Task/Crew/Flow/Tools。
  5. 按 AG-UI 协议输出事件，优先使用 ag-ui-crewai 适配库。
  6. 使用 LiteLLM 统计每次 LLM 调用的 token 和 cost。

设计原则

• 单一职责：HTTP 层只做协议和鉴权，编排与执行下沉到核心层。
• 异步优先：长耗时推理、工具调用、恢复流程全部异步化。
• 协议优先：AG-UI 作为唯一事件契约，不维护自定义事件方言。
• 可观测性优先：每次 run、每次 stage、每次 LLM 调用可追踪。
• 配置单一来源：所有密钥和模型配置只走 core.config.settings。

目标架构

1) 分层

• backend/src/v1/agent/
  • router.py: 暴露 HTTP/SSE 接口。
  • schemas.py: 请求/响应 DTO 和输入校验。
  • dependencies.py: DI 装配。
  • service.py: 薄服务，仅调用 core/agent 应用服务。
• backend/src/core/agent/
  • application/: run/resume 应用服务。
  • domain/: run 状态机、resume 幂等语义、错误模型。
  • infrastructure/crewai/: CrewAI Agent/Task/Crew/Flow 装配与执行。
  • infrastructure/agui/: AG-UI 事件映射与 SSE 序列化。
  • infrastructure/litellm/: LiteLLM 客户端与 usage/cost 拦截器。
  • infrastructure/queue/: Celery task producer/consumer。

1.1) 配置来源与合并策略

• Agent 运行配置由两部分组成：
  • 数据库存量配置：system_agents（每种 agent_type 对应 llm 与 llm_config）。
  • 静态模板配置：backend/src/core/config/static/crewai/*.yaml（角色描述、任务模板、workflow、tools）。
• 合并策略：
  • llm 与 llm_config 以 system_agents 为准。
  • prompt 模板、task 描述、flow stage、tool 白名单以 static/crewai 为准。
  • 若任一 agent_type 在 system_agents 缺失，运行前失败并返回受控错误。

2) 核心运行链路

1. POST /api/v1/agent/runs 只负责参数校验和鉴权。
2. 路由调用 AgentRunAppService.enqueue_run()，写入 run 记录并投递 Celery。
3. Worker 执行 run_agent_task：
   • 读取 run 上下文。
   • 构建 CrewAI Agent/Task/Crew/Flow。
   • 通过 ag-ui-crewai 将执行事件转为 AG-UI 标准事件。
   • 每次 LLM 调用由 LiteLLM 中间层记录 token/cost。
4. 事件落库并发布到事件通道（Redis Stream/Channel）。
5. SSE 接口从事件通道读取并持续推送，直到 RUN_FINISHED 或 RUN_ERROR。

3) Resume 链路

1. POST /api/v1/agent/runs/{run_id}/resume 校验 interrupt_id 与决策 payload。
2. 调用 enqueue_resume() 投递 resume_agent_task。
3. Worker 在事务内做并发控制：
   • run_id + interrupt_id 幂等锁。
   • 过期校验与状态迁移。
4. 恢复后继续 CrewAI Flow，事件按 AG-UI 继续输出。

4) Session 状态持久化

• 使用 sessions.state_snapshot 作为运行态单一快照来源。
• 快照至少包含：
  • run 上下文（thread_id、run_id、stage）
  • pending_tool_calls（tool_call_id、tool_name、args、status、expires_at）
  • correlation 索引（tool_call_id -> message_id / step_id）
• 所有中断/恢复均以 state_snapshot 事务更新为准，避免内存态漂移。

5) 会话与消息落库模型

• 会话主表：sessions
  • 新建 run 时写入：id/user_id/session_type/status=running/last_activity_at。
  • 运行中持续更新：status、last_activity_at、message_count、total_tokens、total_cost、state_snapshot。
  • 运行结束更新：
    • 成功：status=completed
    • 失败：status=failed
• 消息表：messages
  • 用户输入落库为 role=user（每次 run 开始时先写入）。
  • 模型输出落库为 role=assistant（按最终聚合文本落库，保留 metadata 记录增量信息）。
  • 工具调用结果落库为 role=tool，并写入 tool_name 与 metadata.tool_call_id。
  • seq 由每个 session_id 内单调递增分配，满足 uq_messages_session_seq。
• 计量落库：每次 LLM 调用的 usage/cost 先写消息级，再聚合更新到 session 级。

六项要求落地映射

要求 1: .env 驱动 LLM API Key

• 新增 LLMSettings 到 core.config.settings.Settings，统一定义：
  • SOCIAL_LLM__PROVIDER_KEYS__DASHSCOPE
  • SOCIAL_LLM__PROVIDER_KEYS__MINIMAX
  • SOCIAL_LLM__PROVIDER_KEYS__MOONSHOT
  • SOCIAL_LLM__PROVIDER_KEYS__DEEPSEEK
  • SOCIAL_LLM__PROVIDER_KEYS__ARK
  • SOCIAL_LLM__PROVIDER_KEYS__ZAI
• 禁止 os.environ 直接读取密钥。

要求 2: 对话和 resume 走 Celery

• Web 层不直接执行编排。
• run/resume 一律入队，Worker 处理，Web 仅做事件流转发。
• 加入任务级超时、重试、死信策略。

要求 3: v1 仅路由与调用

• v1/agent/service.py 仅保留应用服务调用和错误映射。
• 任何编排、状态机、工具执行逻辑禁止进入 v1。

要求 4: CrewAI 官方流程

• 采用 CrewAI 原生对象：Agent、Task、Crew、Flow。
• tools 通过 CrewAI Tool 机制注册，不做平行实现。
• 任务模板与 agent 配置集中化（静态模板 + 运行时拼装）。
• 配置拼装明确依赖 system_agents + static/crewai，不再使用双套来源。

要求 5: AG-UI + ag-ui-crewai

• 事件集遵循 AG-UI 协议，生命周期闭环：
  • RUN_STARTED
  • 流式消息和工具事件
  • 终态 RUN_FINISHED 或 RUN_ERROR
• 优先引入 ag-ui-crewai 做 CrewAI 到 AG-UI 的桥接，避免重复造轮子。

要求 6: LiteLLM token/cost 统计

• 所有 LLM 调用通过 LiteLLM 统一出入口。
• 按调用粒度记录：input_tokens、output_tokens、total_tokens、cost、currency。
• 按 run 粒度聚合并落库，支持后续计费和审计。

数据与可观测性

• 保留现有 Agent 相关表结构，不在本次硬切做数据库破坏性变更。
• 新增事件日志与调用指标落点（如已有字段不足，后续增量迁移）。
• 日志使用结构化字段：run_id、task_id、stage、tool_name、llm_model、latency_ms。
• 持久化原则：run/resume 的关键状态变更必须可重放，禁止仅保存在内存。

事务边界

• run 入口事务：创建或加载 session + 写入用户消息。
• worker 执行事务（可分阶段短事务）：
  • 阶段开始：更新 session.status/state_snapshot。
  • LLM 返回：写 assistant/tool 消息 + 更新 token/cost 聚合。
  • 中断：写 pending_tool_calls 到 state_snapshot 并提交。
  • 完成：更新终态 session.status 并提交。
• resume 事务：校验 interrupt_id 与 ownership，CAS 更新 state_snapshot，然后进入后续执行事务。

错误处理与安全

• API Key 缺失启动即失败，不进入运行态。
• 外部工具入参统一白名单和 schema 校验。
• resume 决策必须鉴权与会话所有权校验。
• 错误响应遵循 RFC 7807，避免泄漏敏感上下文。

工具调用与恢复语义

• 工具分三类：
  • 前端工具：由 RunAgentInput.tools 提供能力声明，触发 interrupt，由客户端执行并回传 result。
  • 后端工具（需审批）：先 interrupt 给前端审批；审批通过后由后端执行，不由前端执行。
  • 后端工具（直执）：后端直接执行。
• 一致性约束：
  • 每个 tool_result 必须携带 tool_call_id。
  • 后端仅接受当前 state_snapshot.pending_tool_calls 中存在且状态合法的 tool_call_id。
  • 若收到未知/已消费/过期 tool_call_id，立即产出 RUN_ERROR 并记录审计日志。

测试策略

• 单元测试：
  • 配置解析与 key 解析
  • run/resume 状态机与幂等
  • LiteLLM usage 聚合
• 集成测试：
  • API 入队
  • Worker 消费
  • SSE 事件顺序与终态
• E2E：
  • run 成功链路
  • interrupt + resume 链路
  • tool 调用链路

迁移策略

• 阶段 0（本次）：硬切删除旧代码、旧测试、旧文档契约。
• 阶段 1：搭建新架构骨架和最小可运行 run 流程。
• 阶段 2：接入 CrewAI + ag-ui-crewai + LiteLLM 完整链路。
• 阶段 3：补齐可观测性、压测与稳定性治理。

验收标准

• 后端仓库不存在旧 v1/agent 和 core/agent 旧实现。
• 所有 Agent 相关旧测试与旧文档契约已移除。
• 新方案设计文档明确覆盖六项要求并可进入实现阶段。