Agent Loop 需求文档

状态：收口版
日期：2026-05-11

背景

AgentV2 早期方案包含多层 agent、stepCall、continue plan、独立 stop verifier 等概念，导致上下文拼接、运行详情、流式输出、前端恢复和测试边界都比较复杂。

本轮目标是把 agent loop 收敛为一条可复用的主循环：

• workflow agent 节点只负责适配 workflow 上下文、工具、回调和持久化；
• 通用 loop 放在 packages/service/core/ai/llm/agentLoop；
• 模型在同一个主 loop 内完成计划维护、工具调用、追问用户和最终回答；
• 前端只展示新的 plan card、工具卡、思考和最终答案，不再兼容旧 stepCall UI。

目标

1. 简化 loop 架构，去掉多层 agent 嵌套和独立 continue plan。
2. 保证上下文连续，用户追问恢复和工具结果回灌都发生在同一条 message 链路中。
3. 支持模型通过 update_plan 维护计划，并由本地 stop gate 保证计划完成后才能 final。
4. 支持 ask_agent 在必要时追问用户，用户回答后继续原上下文，而不是重新生成一份独立计划。
5. 完整保存 thinking、tool call、tool result、plan、answer、requestId、tokens 和 usage。
6. SSE 事件完整覆盖 workflow 和普通对话，计划生成前需要有可感知的 loading 状态，最终答案需要保持流式输出。
7. 运行详情按 agent/tool 调用线性展示，AI 请求都能关联 requestId。

范围

必须支持

• 直接回答：简单问题不创建 plan，直接流式输出 answer。
• 显式计划：用户明确要求规划、复杂调研、比较、方案设计等场景，需要先创建 plan。
• 执行计划：plan steps 必须非空；步骤状态可批量更新。
• 工具调用：runtime tools 正常执行并展示；工具结果需要回灌给模型。
• 工具后计划更新：调用 runtime tool 后，模型必须用 update_plan 记录证据或结果，才能最终回答。
• 用户追问：缺少必要输入时使用 ask_agent，暂停当前 loop 并保存 pending context。
• 追问恢复：用户回答后，把回答作为 ask tool response 追加回原 messages，继续执行。
• 刷新恢复：历史记录恢复后，plan、thinking、tools、interactive、answer 都应完整展示。
• 工作流适配：workflow 节点通过 adapter 调用通用 agent loop，所有 workflow 专属能力通过参数和接口注入。
• 运行详情：每次 LLM 请求都需要记录 requestId、tokens、model、完成原因；runtime tools 作为对应 agent 调用下的工具展示。

不再支持

• 不再写入旧 stepCall 字段。
• 不再保留旧 stepCall 前端 UI。
• 不再使用独立 plan_agent tool。
• 不再使用独立 LLM stop verifier。
• 不再把历史 plan 伪造成 tool call 注入上下文。
• 不再保留 HTML 预览文档。

用户体验需求

Plan Card

• 进入 plan 模式但 plan 尚未生成时，展示 plan loading skeleton 和中文提示文案。
• plan card 默认最小宽度为消息最大宽度的 50%，避免 loading 过窄。
• plan step 用颜色表达状态：
  • 蓝色：进行中，并带轻量动效；
  • 绿色：完成；
  • 灰色：待处理；
  • 黄色/红色：阻塞或需要调整。
• 不展示冗余的 Running/Pending 英文状态标签。
• update_plan 完成后只更新状态、证据和必要内容，不额外插入 step summary 气泡。
• 右侧 step 数量展示可去掉，降低噪音。

流式输出

• plan 生成期间不能让用户长时间无反馈。
• 模型输出过程需要实时透传给前端，包括 stop gate 最终拒绝的草稿 answer。
• stop gate 只影响最终可持久化的 answer，不负责缓存、撤回或延迟推送 answer_delta。
• 前端看到的是模型执行过程流；刷新恢复时只恢复最终保留在 assistantMessages 中的 answer。

运行详情

• 顶层展示 AI 调用节点，例如主 Agent、任务规划等，使用旧版对应 name 和 icon。
• runtime tool 作为所属 AI 调用下的子项展示。
• 每个 AI 调用都需要能看到 requestId、tokens、模型和完成原因。
• 开头或结尾空 nodeResponse 不应展示。

验收清单

仍需专项确认

推荐回归

corepack pnpm --filter @fastgpt/service exec vitest run -c vitest.config.ts test/core/ai/llm/agentLoop test/core/workflow/dispatch/ai/agent/adapter
corepack pnpm --filter @fastgpt/global exec vitest run -c vitest.config.ts test/core/chat/adapt.test.ts test/core/chat/type.test.ts test/core/workflow/runtime/utils.test.ts
corepack pnpm --filter @fastgpt/app exec vitest run -c vitest.config.ts test/web/common/api/request.test.ts
git diff --check