执行链路

一次真实请求经过哪里

当你在 Mastra Studio 里向 studyAgent 提问时，链路大致如下：

sequenceDiagram
  participant Studio as Mastra Studio
  participant Runtime as Mastra Runtime
  participant Agent as studyAgent
  participant RC as RequestContext
  participant Memory as Memory
  participant InputP as Input Processors
  participant Model as Model Router
  participant Tool as searchCourseTool
  participant OutputP as Output Processors
  participant Store as LibSQLStore
  participant Trace as Observability

  Studio->>Runtime: 用户消息
  Runtime->>RC: 注入请求级变量
  Runtime->>Agent: generate/stream(message, options)
  RC->>Agent: user-tier / language / tenant
  Agent->>Memory: 读取 thread 历史
  Memory->>Store: 查询 messages
  Agent->>InputP: 清洗、限制、拦截输入
  InputP->>Trace: 记录处理结果
  Agent->>Model: instructions + message + history + tools
  Model->>Trace: 记录 LLM span、usage、latency
  Model-->>Agent: tool call: searchCourseTool
  Agent->>Tool: 执行查询
  Tool->>Trace: 记录工具参数和结果
  Tool-->>Agent: 课程片段
  Agent->>Model: 工具结果
  Model-->>Agent: 最终回答
  Agent->>OutputP: 校验、过滤或改写输出
  OutputP->>Memory: 通过后保存消息和结果
  Runtime-->>Studio: text/fullStream + toolResults + usage

加入结构化输出后的链路

如果调用时传入 structuredOutput.schema，最终不应该只检查 response.text。需要额外检查：

• response.object 是否存在。
• 对象是否通过 Zod 或 JSON Schema 校验。
• 如果同时使用 tools，模型是否支持工具调用和结构化输出组合。
• 如果使用单独 structuring model，trace 里会出现额外一次模型调用。

加入 Streaming 后的链路

stream() 不只是把最终文本拆成小块。调试时应观察完整事件：

事件	说明	用途
text-delta	模型生成的增量文本	UI 实时显示
tool-call	Agent 决定调用工具	检查工具选择和参数
tool-result	工具返回结果	检查资料是否进入上下文
finish	运行结束和 usage	成本和结束原因
step-start / step-finish	Workflow 步骤状态	进度条和失败定位

常见失败点

位置	典型问题	快速定位
Studio 到 Runtime	Agent 不显示	看 src/mastra/index.ts 是否注册
Runtime 到 Model	认证失败	检查 .env 和 provider key
Model 到 Tool	不触发工具	检查 tool description 和 instructions
Tool 执行	参数 undefined	检查 inputSchema 和 execute 参数
Memory	记不住	检查 resource/thread 是否稳定
Workflow	step 串不起来	检查 outputSchema 与下游 input
Structured Output	response.object 为空或校验失败	检查 schema 和模型支持情况
RequestContext	不同用户行为没有变化	检查 requestContext.set() 和配置函数
Streaming	UI 看不到工具状态	检查是否消费 fullStream
Processors	正常输入被拦截	检查 strategy、threshold 和测试样例
Approval	高风险工具直接执行	检查 requireApproval、storage 和 stream chunk
Evals	改动后无法比较质量	建立固定 eval cases

Vibe coding 调试提示词

我有一个 Mastra Agent 调用失败。请按链路排查：
1. Agent 是否注册到 Mastra 实例。
2. model 配置是否依赖环境变量。
3. tool schema 和 execute 参数是否一致。
4. memory resource/thread 是否稳定。
5. workflow step 的输入输出是否匹配。
6. structuredOutput schema 是否过大或和工具调用冲突。
7. requestContext 是否传入，并被 Agent/Tool/Workflow 正确读取。
8. stream 是否消费 fullStream，而不是只消费 textStream。
9. processors 是否拦截、改写或丢弃了消息。
10. approval 是否需要 storage 和同一个 runId。

请只根据我提供的代码和错误日志判断，不要猜测不存在的文件。

最小复现原则

Agent 系统出错时，不要一上来让 AI 重写整个项目。先把问题缩小：

• 如果是工具问题，直接运行或调用工具函数。
• 如果是检索问题，打印 query、chunk 和 score。
• 如果是记忆问题，固定 resource/thread 重试。
• 如果是工作流问题，逐个 step 验证。
• 如果是结构化输出问题，先用最小 schema 测试。
• 如果是请求级配置问题，用两组 RequestContext 对照测试。
• 如果是前端显示问题，先打印完整 stream 事件。
• 如果是安全策略问题，固定违规样例和正常样例分别测试。
• 如果是模型问题，先切换到离线 Demo 验证业务链路。