Mastra Agents 教程

Appearance

官方文档学习地图 ​

为什么要先做选材 ​

Mastra 官方文档覆盖 Agent、Workflow、Memory、RAG、MCP、Server、Deployment、Observability、Evals、Voice、Channels 等模块。完整学习当然有价值，但本教程目标不是把文档逐页翻译，而是帮助使用 vibe coding 的开发者从零搭出一个可验证的 Agent 应用。

因此，本教程把官方内容分成三层：

层级纳入方式原因
主线必学Agent、Model、Tool、Memory、Workflow、RAG、MCP能组成最小但完整的 Agent 应用
工程必补RequestContext、Streaming、结构化输出、Processors、Guardrails、Approval、Supervisor、Observability、Scorers、Server决定代码是否可验证、可调试、可集成
延后扩展Voice、Channels、A2A、ACP、Browser、托管部署、Editor需要具体产品场景，先不打断核心学习

官方资料到教程章节的映射 ​

官方主题本教程章节教学重点
Agents overviewAgent、执行链路开放式任务、Agent Loop、.generate() 和 .stream()
Models、Embeddings、Gateways模型与路由provider/model、动态模型、fallback、本地模型、embedding 维度
Tools、Tool streamingTool、Demo 02createTool()、schema、工具选择、工具结果、toModelOutput、展示转换
MemoryMemory、Demo 03resource、thread、消息历史、长期上下文
Working memory 与 Semantic recallMemory 深入用户画像、语义召回、上下文控制
WorkflowsWorkflow、Demo 04确定流程、step schema、.then()、运行验证
Workflow control flow、Workflow state、Snapshots、Suspend & Resume、Error handlingWorkflow 控制流并行、分支、共享状态、snapshot、暂停恢复、失败定位
RAGRAG 与 MCP、Demo 05chunk、embedding、向量库、检索时上下文
RAG chunking、Vector databases、RetrievalRAG 深入chunk 策略、向量维度、rerank、来源引用
MCPRAG 与 MCP、MCP 集成接外部工具、暴露自身能力、多用户工具加载
Structured output结构化输出把模型输出变成可处理对象
Request Context 与 StreamingRequestContext 与 Streaming请求级配置、工具选择、流式调试
Processors 与 GuardrailsProcessors 与 Guardrails输入输出拦截、提示注入防护、PII、成本限制
Agent Approval 与 Workflow HITL人工确认与多 Agent敏感工具审批、暂停恢复、人工决策点
Supervisor Agents人工确认与多 Agent子 Agent 分工、委派、记忆隔离
Observability 与 Evals / Scorers可观测性与评估、评估设计trace、log、metric、scorer、回归验证
Deploy a Mastra server、Middleware、Auth、Storage、Custom API Routes、Deployment服务化与 API 集成Studio、Swagger UI、鉴权、storage、请求上下文、前端接入、部署取舍
Build with AIVibe Coding 工作法给 AI 编程工具提供最新上下文

本教程故意不展开的内容 ​

以下内容在最终项目的扩展方向中提到，但不作为主线实现：

  • Voice 和 Channels：适合语音助手、客服、聊天平台集成，不影响 Agent 核心机制。
  • A2A、ACP 和 Browser：适合跨 Agent 或浏览器自动化场景，学习成本高于本教程目标。
  • 托管平台、完整 Auth、Editor：属于上线和团队协作阶段，主线先讲服务化边界和数据隔离。
  • Hosted Platform：适合生产监控和团队管理，不是理解 Mastra 运行模型的前提。

给 AI 编程工具的资料准备 ​

官方文档提醒：AI 编程工具可能不了解 Mastra 最新 API。实际用 vibe coding 时，推荐先把以下信息交给 AI：

text
请基于 Mastra 官方文档实现，不要凭旧知识猜 API。
核心参考：
- https://mastra.ai/docs/agents/overview
- https://mastra.ai/models
- https://mastra.ai/docs/agents/using-tools
- https://mastra.ai/docs/workflows/overview
- https://mastra.ai/docs/workflows/snapshots
- https://mastra.ai/docs/memory/overview
- https://mastra.ai/docs/agents/structured-output
- https://mastra.ai/docs/server/request-context
- https://mastra.ai/docs/evals/overview

如果需要某个 API，请先说明参考页面，再给代码。

更严谨的做法是使用官方的 Build with AI 页面提到的 Mastra Skills、MCP Docs Server 或每页 llms.txt。本教程仍保留手写提示词，是为了让开发者理解 AI 需要什么上下文，而不是只依赖工具自动补全。