Agent 运行时：用户发一条消息之后，平台做了什么？

定位：块二 §1 核心课 · 讲清一次 Chat 请求的完整路径（面试、讲课、排错都从这里开始）。
接口：POST /api/agents/{id}/chat · 代码入口 chenyue-platform/app/api/chat.py

---

一、先建立直觉：不是「问大模型一句话」

很多同学习惯把 Agent 想成：用户输入 → ChatGPT → 输出。

在编排平台里，一次对话更像过安检、分诊、查档案、调工具、再让医生开口——能本地解决的，绝不浪费一次大模型调用。

你在 JD 里常看到的词：RAG 检索、Tool Calling、工作流编排、长期记忆、内容安全——都发生在这条链路里的不同站点。

下面这张图，就是你要能对着白板讲出来的主线（也是晨悦编排的实现顺序）：

用户消息
  → 内容安全（入站）
  → Scene Layer1 本地命中？ → 直出（结束）
  → Scene Layer2 AI + hint
  → 语义缓存命中？ → 直出（结束）
  → 加载 Agent 配置（Prompt + 挂载）
  → Memory Load（短 / 中 / 长）
  → RAG 检索（若挂知识库）
  → Workflow Skill 触发？（交易类等确定性任务）
  → Tool Calling（Plugin）
  → LLM 生成
  → Memory Save + 摘要
  → 内容安全（出站）
  → 结构化响应（text / cards / actions）

记住三个「早退」——省钱、省时间：

1. Scene Layer1：固定话术直接回，0 token，通常 <10ms
2. 语义缓存：相似问题用过答案，0 token
3. Workflow 独立跑：复杂交易链路在画布上调试，不必每次靠 LLM 猜

---

二、逐步走一遍（像讲故事）

第 1 站：用户消息进来

妈妈在小程序里输入：「推荐一款适合 6 个月宝宝的米粉」。

平台收到的是一次 HTTP 请求：message + 可选的 conversation_id（续聊）。

此时还没调用大模型。

---

第 2 站：内容安全（入站）

干什么：检查用户输入是否违规（广告引流、敏感内容等）。

现状：

• 小程序侧：XiaoYueShell 已在发送前做检查
• 平台 Chat API：目标态在入站统一过一遍（商用必备）

没过怎么办：直接拒绝或返回固定提示，不进入后续链路。

→ 深读 内容安全

---

第 3 站：Scene —— Layer1 能不能直接答？

Scene 是什么？
可以把它理解成意图路由 + 预设回复：高频、意图明确的问题，不必上大模型。

Layer1：匹配成功 → 返回写好的文案 → 对话结束。

举例：

• 「有优惠券吗」→ 直接给领券引导
• 「查看待产清单」→ 触发清单入口话术

响应里会有 scene_local_reply: true，表示这条没花 token。

Layer2：匹配了但不够确定 → 不直出，而是给 LLM 一句 hint（例如「用户在问辅食，请结合 6–12 月龄」），后面照常走 AI。

→ 深读 意图路由 Scene

---

第 4 站：语义缓存（代码里在 Layer1 之后）

如果 Layer1 没拦住，平台还会问：这个问题以前是不是问过类似的？

命中缓存 → 直接返回上次的答案 → 0 token → 结束。

适合：FAQ、「公司退货政策是什么」这类重复问句。

---

第 5 站：加载 Agent 配置

到这里，说明需要「真 AI」了。

平台读出这个 Agent 的配置：

• 人设 Prompt（你是谁、边界是什么）
• 挂载：知识库 ID、插件列表、Skills、是否开 Scene / Memory
• 模型：默认用 GLM-4-Flash 还是别的

Agent = Prompt + 模型 + 挂载，不是单独一段 Prompt 字符串。

→ 深读 Agent 管理

---

第 6 站：Memory Load —— 短 / 中 / 长期记忆

短期：当前会话里刚才说了什么（多轮上下文）。

中期：更早的对话被摘要过（对话太长时自动压缩，避免 token 爆掉）。

长期：用户画像——例如「宝宝阶段：6–12 个月」「上次搜过尿不湿」。

母婴场景里，baby_stage 存在长期记忆里，比每次让用户重复「宝宝多大了」体验好得多。

→ 深读 记忆系统

---

第 7 站：RAG 检索（知识库）

如果 Agent 挂了知识库，平台会用用户这句话去库里搜相关段落，拼进 Prompt。

AgentPM 示例：搜 PRD 规范、SDAD 节选 → 出稿不跑偏。
母婴示例：搜「6 个月辅食添加原则」→ 回答有据，而不是纯幻觉。

注意：商品列表、价格、库存不要放 KB，应走 API 实时查（Plugin / Workflow HTTP）。

→ 深读 知识库 RAG

---

第 8 站：Skills 处理（Prompt / KB / Tool / Workflow 打包）

Skill 是比「单个插件」更高一层的能力包，一次挂载多样东西。

平台在这一步按类型分别处理：

Skill 类型	干什么
Prompt Skill	再注入一段专业 Prompt
Knowledge Skill	从指定 KB 再搜一轮
Tool Skill	把一组插件并进 Tool 列表
Workflow Skill	关键词命中 → 应触发哪条工作流

「推荐米粉」在母婴 Agent 里，理想情况在这里匹配 Workflow Skill，走确定性交易链路（搜商品 API → 格式化卡片），而不是让 LLM 编造商品名和价格。

⚠️ 现状：Workflow Skill 的关键词匹配已有，执行结果回注 Chat 仍在完善（平台 Phase A6）。

→ 深读 Agent Skills

---

第 9 站：Tool Calling（插件）

LLM 需要查实时数据时，会调用挂载的 Plugin（行业里也常写 Tool Calling）。

例如：

• 调 GET /api/goods/list?keyword=米粉
• 调 GET /api/goods/checklist-by-stage?stage=baby-6-12

插件返回 JSON，LLM 基于真实字段组织回复——价格、链接不能瞎编。

→ 深读 插件与 Tool Calling

---

第 10 站：LLM 生成

前面所有上下文（Prompt + 记忆 + RAG + hint + Tool 结果）一起送给大模型。

这里才是 token 消耗的大头。

模型路由：简单分类用便宜模型，复杂写作可切强模型——面试常问的「成本怎么控」，答案就在 Layer1 / 缓存 / 路由三件套。

→ 深读 模型路由与成本

若 LLM 或网络失败，平台还有 Layer3 兜底话术，用户不会看到白屏或 500。

---

第 11 站：Memory Save + 摘要

对话结束后异步做几件事：

• 从本轮对话抽取长期记忆（偏好、事实）
• 对话太长时写中期摘要
• 把优质 Q&A 写入语义缓存，下次类似问题更快

用户无感知，但下一轮会更「认识你」。

---

第 12 站：内容安全（出站）

模型生成的文字，商用场景也要过审（尤其母婴、医疗相关）。

目标态：平台统一出站检查后再返回客户端。
现状：Prompt 边界 + 客户端检查；平台出站钩子待统一。

---

第 13 站：结构化响应

最后返回给前端的不一定只是纯文本。

类型	什么时候	前端表现
text	普通聊天	气泡文字
goods_cards	搜到商品	商品卡 + 购买按钮
checklist_groups	阶段清单	分组清单 + 跳转
actions	引导操作	「去好物广场」等按钮

AgentPM 以 Markdown PRD 为主；母婴小悦以 卡片 + 清单 为主——同一套运行时，End 输出协议不同。

Workflow 画布上的 End 节点负责拼这类结构；Chat 默认仍多为 message.content 文本，商用扩展见 repo docs/baby-xiaoyue-ai-upgrade.md §2.8。

→ 深读 工作流编排

---

三、走两条真实路径（加深印象）

路径 A：Layer1 直出（最快）

「有优惠券吗」
  → 入站安全 ✓
  → Scene Layer1 命中
  → 返回预设话术
  → 结束（0 token）

路径 B：完整 AI + Tool（母婴搜商品）

「推荐一款米粉」
  → 入站安全 ✓
  → Scene 未 Layer1
  → 缓存未命中
  → 加载母婴 Agent + 记忆里的 baby_stage
  → RAG 补辅食原则（可选）
  → Workflow Skill 或 Tool 调 goods API
  → LLM 写一段 ≤80 字导语（不编价格）
  → 出站安全
  → 返回 text + goods_list

路径 C：AgentPM 出 PRD

「帮我写登录功能的 PRD 大纲」
  → Scene 通常不拦
  → 加载 AgentPM + PRD 规范 KB
  → RAG 检索 SDAD/模板
  → Workflow：需求 → 结构化 → PRD 章节
  → 返回 Markdown 文稿

更多对照 → 案例对照：PM vs 母婴

---

四、和 Coze / Dify 怎么说同一件事？

你讲的主线	行业常见说法
Scene Layer1	意图识别 + 固定回复 / 本地命中
RAG	知识库检索增强
Tool Calling	插件 / Function Calling
Workflow Skill	工作流编排 / 确定性分支
Memory Load/Save	长期记忆 / 用户画像
结构化响应	富媒体消息 / 卡片消息

面试 30 秒版：

我们的 Agent 运行时是一条可观测的链路：先意图路由降本，再记忆和 RAG 补上下文，交易类走工作流和 Tool 保证数据真实，最后 LLM 只负责共情和总结，输出可以是文本或商品卡片。

---

五、动手验证（15 分钟）

1. 打开 flow-admin → 选一个 Agent → 对话
2. 发一条普通问题，看响应时间（完整 AI 路径）
3. 若有 Scene 环境，发 Layer1 能命中的句子，看是否秒回
4. 打开浏览器 Network → 找 POST .../chat → 看 JSON 里有没有 scene_local_reply / cache_hit

详细步骤 → 动手实验 0 · 5 分钟上手

---

六、各模块在本链路中的位置（速查）

需要查某一站怎么配置时：

• 意图路由 → Scene
• 记忆 → Memory
• 知识库 → RAG
• 能力包 → Skills
• 工作流 → Workflow
• 插件 → Plugins
• 模型与成本 → 模型路由
• 安全 → Security

工程真源：app/api/chat.py · app/services/chat_service.py

---

相关

• 平台总览 · vs Coze/Dify