章小结：Agents 设计架构与扩展
三节下来，agent 的神秘面纱应该已经揭开了：模型 + 一组工具 + 预制提示词，没有更多玄学。但这只是"组成部分"，真正拉开差距的是架构——执行循环怎么设计、控制权怎么分配、行为怎么观测。这节把整章收拢成几条带得走的心智模型，再补两块没来得及展开的扩展：子代理与可观测性。
一条主线收束：控制权在谁手里
全章所有模式，最终都收敛到同一个判断：任务推进过程中，谁掌握控制权。
- 流程明确 → Workflow：串行、并行、条件、循环——执行图写死在代码里，可预测可审计。这四种原语和编程里的顺序/分支/循环同构，复杂应用无非是它们的组合（16-03 的 docs-pipeline 用了 .then + .branch，docs-council 用了 .parallel）。
- 流程不明确 → 交给 AI 控制，按控制权浓度从高到低：Supervisor（一个主 agent 全程掌控、边走边委派）→ Council（多视角并行独立作答、最后综合裁决）→ Handoffs（控制权随阶段完全移交给专家）。
这个分野不是 Mastra 的发明。看看主流工具：Claude Code、Codex 这类编码 agent 都是主进程统筹核心任务 + 子代理分担子任务的结构——主管型（Supervisor）在生产工具里的普遍印证。
扩展一：子代理（Subagent）
类比一次就懂：进程有线程，主代理下可以挂多个子代理。子代理执行的仍然是 16-02 讲的 agent 任务——可能是一个简单委派，也可能本身是一条 workflow 甚至是另一组多 agent 协作。
Mastra 把这层封装好了：agents 属性注册子 agent，委派的生命周期（启动、停止、改写下行提示词、结果回流）都有对应设施（16-03 的 delegation 三件套）。课程的落地是 orchestration/children.ts：researcher/writer/reviewer 三个子 agent 定义是纯配置对象，instantiateAgent(def) 一个函数完成"定义 → Agent 实例"的收窄——子 agent 和普通 agent 用同一套定义语言，这是"agent 即数据"设计的又一次兑现。
顺带两个工程视角：
- Node.js 对多任务天然友好：异步非阻塞 IO，天生适合"同时跑三个子 agent、等全部回来再综合"这种场景——
Promise.all与 Mastra.parallel()背后是同一类机制； - 需要更精细的流程控制时可了解 RxJS：并行、串行、条件分支的操作符体系在前端圈已经验证了十年，思路可以平移到 agent 编排（Mastra 的
.then/.branch/.parallel/.dountil就是这些控制流的原生表达，先用原生的，不够再上通用库）。
Mastra 的分层架构：把整章放回一张图
用一张分层图把全章内容归位（用 NotebookLM 整理官方文档得到的框架，按仓库真实落地校准过）：
（有的资料把认知层与控制层分列成"四层"，实质相同：上面管交互，中间管编排与执行，下面管记忆与观测。）
对照课程进度看这张图：16-01 重构解决的是这张图怎么装进我们的 monorepo（机制进库、实例进服务）；16-02 填的是 Agents 与 Tools 两格；16-03 填的是 Workflows 与多层控制；17-01 接 MCP、17-03 深挖 Memory；本节最后一块——Observability——现在补上。
AI agent 的能力四要素
换个视角看 agent，它由四样东西构成（与 15-02 的"模型层/工具层/调度层"三层切法不冲突——那是按分层切，这是按能力组件切）：
- 工具（Tools）：能做什么——16-02 的颗粒度方法论；
- 推理引擎：解析输入、规划动作链、评估结果——本质是规范化提示词 + 模型的结构化输出，动力核心是 ReAct 循环（思考-行动-观察-纠正，15-02 已拆解，不重复）；
- 记忆中枢：缓存 + 向量存储，对接各类存储——17-03 的主题。认知科学把记忆分工作记忆/情节记忆/程序记忆/语义记忆四类，Mastra Memory 的 lastN/semanticRecall/workingMemory 三档就是工程化的近似，细节到 17-03 展开；
- 控制路由：小模型 + 向量匹配快速识别用户意图，路由到对应 agent 或工具——16-03 三问决策树的运行时版本。
终局判断：什么时候用 agent，什么时候用 workflow
一句话版本：AI agent 有自主决策权，workflow 是铺好的轨道。
- 输入输出都确定、过程也确定——财务报表、固定格式数据分析、明确的多步内容生产 → workflow（可预测、可审计、便宜）；
- 过程中需要 AI 加工和决策——客服、知识库问答、开放性排查 → AI agent（贵一点，但没有它任务不成立）。
编排形态回顾一遍（16-03 四模式的另一种叫法）：流水线型、脑爆型（council）、主管型、专家接力型（handoffs）。主管型最适合"一个大循环带着几个小子代理"的结构——也是当前主流编码工具的形态。
扩展二：可观测性——traces 与 logging
孙子兵法讲知己知彼。AI 应用比传统应用多一层黑盒：模型每一步为什么这么决策、工具调了什么、token 花在哪——不观测，就是在盲猜自己的系统。
《孙子兵法》的话翻成工程语言：追踪（tracing）和日志（logging）就是了解 AI 行为与程序状态的手段，用来判断整个流程是否与预期一致。没有它之前，"为什么答错"只能靠复现猜测；有了它，每一步的输入输出都是呈堂证供。
落地：一个文件接通 Studio 的 traces
不装可观测性时，Studio 里的 traces / evaluate 视图是灰的。接通只需要 @mastra/observability 和一个装配文件（真实代码）：
// packages/dev-server/src/observability.ts
import {
MastraStorageExporter,
Observability,
SensitiveDataFilter,
} from '@mastra/observability'
export function createObservability(): Observability {
return new Observability({
configs: {
default: {
serviceName: 'dev-server', // 服务名：traces 里标识来源
exporters: [new MastraStorageExporter()], // 导出器：traces 落 Mastra storage（Studio 直接读）
spanOutputProcessors: [new SensitiveDataFilter()], // 输出处理器：敏感数据过滤
logging: { enabled: true, level: 'info' },
},
},
})
}
typescript
挂在 Mastra 实例的 observability 字段上（env 门控：MASTRA_TELEMETRY 默认开启，设 false 显式关闭）。TypeScript 的类型定义读起来不难——Observability 是入口、exporters 决定数据去哪、configs 按服务维度配置，读懂单词就读懂了结构。
接通后的体验：在 Studio 发一条会话，traces 视图立刻多一条记录——点开是完整的时间线：用了什么模型、发出什么消息、模型回了什么、走了哪些工具、每个环节多少 token、整个请求执行了多久。AI 的生成过程第一次变成可回放的录像。
两个加分细节：
- 业务埋点能自动关联 trace：docs-pipeline 的 retrieve 步里
mastra.getLogger().info('检索完成', { task, research_chars })，结构化日志经 observability 转发进 Studio 的 logs 视图并与该步的 trace 关联——业务事件和执行轨迹在同一条时间线上； - 存储分域（17-03 展开）：traces/logs 落独立的 DuckDB 文件（
observability.duckdb），与会话库（LibSQL）分文件分引擎——起因是@mastra/libsql当时未实现batchCreateLogs，logs 落不了库；独立文件还附带一个好处：删掉观测文件重置演示数据，不伤会话历史。
exporter 不止一种：官方还有
@mastra/otel-exporter（OTLP 协议，可接任意 OpenTelemetry 兼容平台——Datadog/Grafana 等）。本地开发用 MastraStorageExporter 落库进 Studio 最省事，生产接第三方平台时换 exporter 即可。
收束：AI 时代你的角色变了
回看这一章的开发过程，一个事实值得明说：90% 以上的代码是 AI 写的。人做的是四件事：最终确认效果、在 AI 求决策时明确细节、提出架构层面的要求、把可验证的完成标准说清楚。角色从打工者变成了老板——借助 AI 干活，但对结果负责。
这也回答了"为什么学 Mastra 这类框架"：当市面上的 MCP 工具没有现成的、公司内部有一套自己的工作流要接的时候，你需要一个高度可定制的底座——Mastra、n8n 这类方案把 agent、workflow、记忆、观测都封装成了可插拔的件，站在别人搭好的台子上，让 AI 替你唱戏，事半功倍。课程选 Mastra 落地，同样的思路换 n8n/Dify 也成立——重要的是这套架构心智：机制与实例分离、控制权分配、可观测、成本受控。
小结
- 一条主线：控制权在谁手里——流程明确→workflow（串行/并行/条件/循环四原语），不明确→AI 控制（Supervisor/Council/Handoffs 按控制权浓度排列）；Claude Code/Codex 的主进程+子代理结构是主管型的主流印证
- 子代理：进程/线程类比，Mastra
agents属性 + delegation 设施封装生命周期；课程落地 children.ts 三角色同用一套定义语言；Node.js 异步非阻塞天然适配，更细粒度控制可了解 RxJS - Mastra 分层：交互层（CLI/Studio/Client）→ 认知编排层（agents/workflows/tools+MCP）→ 持久化层（storage/memory + observability）——整章内容各归其位
- agent 四要素：工具/推理引擎（ReAct，15-02）/记忆中枢（四类记忆的工程近似，17-03）/控制路由；agent vs workflow：自主决策权 vs 铺好的轨道——确定性任务用 workflow，需要 AI 判断的用 agent
- 可观测性：traces + logging 让 AI 行为从黑盒变录像；
@mastra/observability一个文件接通 Studio（serviceName/exporters/SensitiveDataFilter/logging 四件配置），业务埋点自动关联 trace，观测数据独立 DuckDB 域（17-03），换 otel-exporter 可接第三方平台 - 角色转变：90% 代码交给 AI，人负责确认效果、明确细节、提架构要求、定验收标准；学框架的意义是"站在别人搭的台子上，让 AI 替你唱戏"
下一章在这套地基上接生态：MCP 工具系统（17-01，宿主视角）、插件系统（17-02）、记忆系统（17-03）、RAG 与语义检索（17-04）——全部接在 16-01 留下的三个可插拔口上。
↑