Mastra Agents 教程

Appearance

Mastra 架构全景 ​

从工程视角看 Mastra ​

Mastra 可以理解成一个 TypeScript Agent 应用框架。它不是只包装模型调用，而是把 Agent 应用常见的工程部件放到同一个运行时里：

  • Agent：负责开放式任务。
  • Tool：负责外部能力和确定性代码。
  • Workflow：负责可控流程。
  • Memory：负责对话和用户状态。
  • Storage：负责持久化。
  • RAG：负责资料检索增强。
  • MCP：负责和外部工具生态互通。
  • Structured Output：负责把模型结果约束成对象。
  • RequestContext：负责传入本次请求的权限、语言、租户和功能开关。
  • Streaming：负责把生成文本、工具调用和工作流状态实时返回给 UI。
  • Processors / Guardrails：负责输入输出拦截、安全策略和成本控制。
  • Approval / HITL：负责高风险动作前的人类确认。
  • Observability / Evals：负责调试、追踪和质量评估。
  • Studio：负责本地调试和观察。

模块关系 ​

mermaid
flowchart TB
  App[你的应用] --> Mastra[Mastra Runtime]
  Mastra --> Agents[Agents]
  Mastra --> Workflows[Workflows]
  Mastra --> Storage[Storage]
  Mastra --> Observability[Observability / Evals]
  Mastra --> Studio[Studio / REST Endpoints]

  Agents --> Model[Model Router]
  Agents --> Tools[Tools]
  Agents --> Memory[Memory]
  Agents --> MCP[MCPClient]
  Agents --> Structured[Structured Output]
  Agents --> RequestContext[RequestContext]
  Agents --> Streaming[Streaming]
  Agents --> Processors[Processors / Guardrails]
  Agents --> Approval[Approval / Suspension]

  Workflows --> Steps[Steps]
  Steps --> Tools
  Steps --> Agents
  Steps --> RequestContext
  Workflows --> Streaming
  Steps --> HITL[Workflow HITL]

  Memory --> Storage
  Observability --> Storage
  Tools --> Data[外部 API / 本地数据 / 数据库]
  MCP --> External[外部 MCP Servers]

默认项目结构 ​

Mastra 官方推荐的默认结构以 src/mastra 为中心：

text
src/
└── mastra/
    ├── agents/
    ├── tools/
    ├── workflows/
    ├── scorers/
    └── index.ts

本教程最终项目沿用这个结构，只是放在 apps/study-agent/src/mastra，这样教程站点和最终项目可以放在同一个仓库里。

设计取舍 ​

设计为什么这样做
用 VitePress 做教程静态站点简单，适合代码、图表和长文档
Demo 先离线读者不用先准备 API Key
最终项目保留 Mastra 结构能迁移到真实 Mastra Studio
不引入 UI 库教程重点是 Agent 机制，不是页面组件
本地资料搜索先用数组聚焦 Tool、Workflow、RAG 思想
RequestContext 和 Streaming 先写成课程当前最终项目无前端和多租户，先教清楚接入点
Evals 和 Observability 先做教学设计保持最小依赖，同时让读者知道生产验证要补什么

你应该重点观察什么 ​

读源码时不要先陷入具体类名。先看数据如何流动：

  1. 用户输入如何进入 Agent。
  2. Agent 如何得到 tools。
  3. Tool 的 schema 如何约束参数。
  4. Memory 如何绑定 resource/thread。
  5. Workflow 如何把步骤输出传给下一步。
  6. 结构化输出如何进入 UI 或后续 API。
  7. RequestContext 如何影响工具、模型和 instructions。
  8. Streaming 事件如何暴露工具调用和工作流进度。
  9. Processors 在模型调用前后改写了什么。
  10. Approval 在高风险动作前是否真的暂停。
  11. Trace、log、metric 和 scorer 如何说明一次运行质量。
  12. Mastra 实例如何统一注册这些模块。