跳到主要内容

Mastra 指南

本文聚焦 Mastra 在 TypeScript 路线中的定位、核心能力、代码组织方式和适用场景。

内容基于 Mastra 当前官方资料整理，重点放在：

  • Agent 怎么定义
  • Tool / MCP 怎么接
  • Workflow 怎么编排
  • Memory / Runtime Context 怎么用
  • Evals / Scorers / Observability 怎么接
  • 它和这个专题里的哪些章节适合放在一起看

1. 定位​

一句话概括如下：

Mastra 是一套偏 TypeScript-first 的 AI Agent 框架，除了 agent 运行，还覆盖 workflow、memory、MCP、observability 和 evals。

所以它不像：

  • 只做最小模型调用的轻封装
  • 只做单一步骤 agent loop 的薄 SDK
  • 只做平台托管的纯服务层

更准确地说，它适合在 TS 项目里承担 agent 系统工程化这一层。

2. Mastra 提供的核心能力​

从官方首页、Agents、Workflows、Observability、Evals、MCP 文档合在一起看，Mastra 主要提供 6 类核心能力：

  1. Agents
  2. Workflows
  3. Memory
  4. Tools / MCP
  5. Observability
  6. Evals / Scorers

这 6 层和这个专题里的几条主线能很自然地对上：

  • Tool Use / Function Calling
  • Workflow vs Agent
  • Memory and State
  • Observability
  • Evals / Harness

所以 Mastra 对这个专题来说，不只是多了一个框架名字，而是补上了一条很顺的 TS 工程化路线。

3. 适用场景​

3.1 适合已经不满足于“最小 Agent demo”的 TS 项目​

如果已经做过：

  • 最小 tool-using agent
  • 一个简单 RAG demo
  • 一个 research helper

接下来你开始在意：

  • 流程怎么拆
  • 状态怎么带
  • 线上怎么观察
  • 结果怎么评估

Mastra 往往会更顺手。

3.2 适合同时需要 Agent 和 Workflow 的系统​

Mastra 官方 Workflows 页面讲得非常明确：

  • 可以定义 execution graph
  • 支持 sequential / parallel / branch / loop
  • 支持 suspend / resume
  • 支持 agents 和 tools 直接进入 workflow steps

因此它和下面这些场景贴得很紧：

  • 不是只有一次工具调用
  • 而是已经进入多步任务
  • 且希望流程可控、可视化、可恢复

的系统。

3.3 适合很在意 evals 和 observability 的团队​

这点是 Mastra 很突出的地方。

官方 Observability 页面明确强调：

  • token usage
  • latency
  • prompts and completions
  • decision paths
  • tool calls
  • memory operations
  • OTel-compatible providers

官方 Evals / Scorers 页面则进一步给了：

  • built-in scorers
  • custom scorers
  • live evaluations
  • 在 CI/CD 里运行
  • 在 Studio 里评分 trace

这说明 Mastra 不是只关心“能跑”，而是关心：

能不能长期评估、长期观察、长期调优。

4. 不太适合的场景​

4.1 不适合作为第一个最小起点​

如果只是想先学：

  • tool schema
  • 单工具调用
  • 最小 loop

更轻的起点一般还是：

  • OpenAI Agents SDK
  • Vercel AI SDK

更适合把它当作第二站，而不是第一站。

4.2 不适合还没分清 Agent 和 Workflow 边界的场景​

Mastra 很强的一点，是它会很快把你带进：

  • agents
  • workflows
  • context
  • memory
  • evals
  • observability

这很爽，但也意味着：

如果还没分清：

  • 哪些步骤应该写死
  • 哪些步骤才该交给模型
  • 哪些地方需要人工确认

那很容易过早进入“完整框架”，反而把边界做糊。

5. 一个基础理解框架​

第一次接触 Mastra 时，可先用下面这个模型理解：

5.1 Agent 负责开放式判断​

这一层主要负责：

  • 会看输入
  • 会调工具
  • 会结合上下文做决策

5.2 Workflow 负责显式流程控制​

这一层主要负责：

  • 把步骤串起来
  • 决定顺序、并发、分支、循环
  • 决定暂停和恢复

5.3 Runtime Context 负责动态环境​

这一层主要负责：

  • 当前用户是谁
  • 当前租户是谁
  • 当前权限等级是什么
  • 当前地区 / 当前策略 / 当前模型偏好是什么

5.4 Memory 负责长期和短期上下文​

这一层主要负责：

  • conversation history
  • persistent user data
  • semantic recall

5.5 Scorers / Observability 负责验证和排查​

这一层主要负责：

  • 这次输出有没有变差
  • 哪一步耗时最高
  • 工具到底怎么被调了
  • memory 有没有带来副作用

如果用一句话压缩：

Agent 负责“想”，Workflow 负责“排”，Runtime Context 负责“带环境”，Memory 负责“记”，Scorers / Observability 负责“看清和验证”。

6. 常见的起步方式：先定义一个 Agent​

Mastra 的 Agent 可以先理解成一个配置好的执行单元。官方 reference 里给出的构造思路大致是：

import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";

export const assistant = new Agent({
  name: "assistant",
  instructions: "You are a helpful assistant.",
  model: openai("gpt-4o"),
});

这个最小版本里，核心通常有：

  • name
  • instructions
  • model
  • tools
  • memory
  • scorers

它并不只有 prompt 和 model。

6.1 instructions 不只是静态字符串​

Mastra 的一个很实用的点是，官方 reference 明确支持把 instructions 写成函数。

这里最实用的一点是，可以根据 runtimeContext 动态生成系统指令：

instructions: async ({ runtimeContext }) => {
  const tier = runtimeContext.get("user-tier");
  return tier === "enterprise"
    ? "You are an enterprise-grade assistant with stricter compliance rules."
    : "You are a helpful assistant.";
}

这个能力和专题里的这些部分很贴：

  • Prompt Engineering
  • Context Engineering
  • Guardrails

因为它让 prompt 不再只是静态文本，而能变成“带运行时语境的策略”。

6.2 model 也可以动态选择​

Mastra 官方 reference 也支持把 model 写成函数。

这样一来：

  • 普通用户走便宜模型
  • 高价值请求走更强模型
  • 某些租户走指定 provider

都可以在框架层完成，而不用在业务代码里到处手写分支。

7. Tool 怎么接​

Tool 是 Mastra 里最适合尽快上手的一层。

官方 Using Tools with Agents 文档里的核心思路很直接：

  1. 先定义 tool
  2. 再把 tool 挂到 agent 的 tools 上
  3. agent 在生成过程中自行决定是否调用

一个很典型的形态是：

import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import { weatherInfo } from "../tools/weatherInfo";

export const weatherAgent = new Agent({
  name: "Weather Agent",
  instructions:
    "You are a helpful assistant that provides current weather information. When asked about the weather, use the weather information tool to fetch the data.",
  model: openai("gpt-4o-mini"),
  tools: {
    weatherInfo,
  },
});

7.1 这里最重要的不是“能不能调工具”​

而是：

  • 工具边界是否清楚
  • 工具命名是否清楚
  • 工具 description 是否能指导模型正确选用
  • 工具输入 schema 是否稳定

所以 Mastra 在 tool 这一层，最适合拿来练的是：

怎么把 Tool Use 真正做成清晰的工程接口。

8. MCP 怎么接​

Mastra 对 MCP 的支持非常正式，不是附带支持。

官方 MCP overview 明确说它支持两类能力：

  1. MCPClient
  2. MCPServer

8.1 MCPClient 是什么​

MCPClient 用来连接一个或多个 MCP server，从中取用：

  • tools
  • resources
  • prompts

官方文档甚至直接给了通过 npx 跑 server、或通过 SSE 接远程 MCP 的例子。

Mastra 可以把外部 MCP 生态直接纳入 agent 能力层。

8.2 MCPServer 是什么​

MCPServer 则反过来：把你自己的 Mastra 内容暴露给外部系统。

官方文档明确提到可以暴露：

  • agents
  • tools
  • workflows
  • prompts
  • resources

一个典型思路是：

import { MCPServer } from "@mastra/mcp";

export const testMcpServer = new MCPServer({
  id: "test-mcp-server",
  name: "Test Server",
  version: "1.0.0",
  agents: { testAgent },
  tools: { testTool },
  workflows: { testWorkflow },
});

这里很关键的一点是：

Mastra 不只是消费 MCP，也能把自己的能力以 MCP 的方式暴露出去。

9. Workflow 怎么写，为什么它很重要​

Workflow 是这篇里需要认真理解的部分之一。

官方 Workflows 首页给出的定位非常明确：

  • 用 clear, structured steps 组织复杂流程
  • 不依赖单个 agent 自己推理所有步骤
  • 支持 schema、顺序、并行、分支、循环、错误处理

压成一句话就是：

当一个任务已经不该由“单个 agent 自己一路想完”时，Workflow 就开始变得重要。

9.1 它支持哪些控制流​

官方当前明确给了这些模式：

  • sequential：step.then(nextStep)
  • parallel：step.parallel([a, b])
  • branch：step.branch([[cond1, step1], [cond2, step2]])
  • loops：step.doWhile(cond)

这和专题里的这些内容贴得很近：

  • Workflow vs Agent
  • Planning Patterns
  • Research Agent

因为这些模式已经不只是“有个 agent 会调工具”，而是在处理：

  • 路由
  • 分支
  • 并发
  • 重试 / 迭代

9.2 Workflow 为什么比“全交给 Agent”更稳​

Mastra 官方文案里有一个很值得记住的点：

当流程需要 repeatable、predictable、auditable 时，Workflow 很重要。

这背后对应的就是：

  • 可重复
  • 可预测
  • 可审计

也就是：

你不想每一步都依赖模型临场决定。

9.3 Agent 和 Tool 可以直接进 Workflow step​

Mastra 官方 Workflows 页面还明确写到：

  • 直接在 workflow steps 里调用 agents 和 tools
  • workflow 之间可以嵌套
  • 可以持久化状态并从暂停点恢复

这类能力常用在：

  • research workflow
  • review workflow
  • HITL approval flow
  • 带中间状态的知识处理流程

10. Runtime Context 到底有什么用​

这也是 Mastra 在工程化落地里比较有优势的一点。

官方 Runtime Context 文档给的能力非常实在：

  • 可以在 server middleware 里设置值
  • agent 的 instructions / model / tools / memory 都可以读取它
  • workflow step 里也可以读取它

官方文档里的典型场景包括：

  • 根据用户地区切换温度单位
  • 根据用户等级切换系统规则
  • 根据权限控制可用工具

例如：

runtimeContext.set("temperature-unit", "celsius");
runtimeContext.set("user-tier", "enterprise");

然后在 agent 里读取：

instructions: async ({ runtimeContext }) => {
  const tier = runtimeContext.get("user-tier");
  return tier === "enterprise"
    ? "Use enterprise compliance rules."
    : "Use normal rules.";
}

10.1 这层最适合解决什么问题​

这层最适合解决：

  • 多租户
  • 多角色
  • 权限分层
  • 区域差异
  • 动态模型选择
  • 动态工具暴露

runtimeContext 把“同一个 agent 根据环境调整行为”这件事做成了正式能力。

11. Memory 怎么理解​

Mastra 官方 Agents 首页和 Memory docs 把 memory 放得很靠前。

它强调的不是单一“聊天记录”，而是：

  • conversation history
  • working memory
  • semantic recall
  • persistent user data

所以在 Mastra 里，memory 更接近一整组能力，而不是单一字段。

11.1 一个官方首页级别的最小形态​

Mastra 首页就直接给了这种写法：

const memory = new Memory({
  storage: new LibSQLStore({
    url: "file:../mastra.db",
  }),
});

const agent = new Agent({
  instructions,
  model: anthropic("claude-3-5-sonnet"),
  memory,
});

这说明 memory 在 Mastra 里不是外挂，而是 agent 的核心原语之一。

11.2 它最适合拿来练什么​

在这个专题里，Mastra 的 memory 可以和这些主题对照着看：

  • Agent Memory and State
  • Context Engineering
  • Research Agent

因为它会逼你开始认真区分：

  • 临时上下文
  • 会话历史
  • 长期用户数据
  • 语义召回

12. Evals / Scorers 怎么用​

Mastra 在这块其实比很多框架更“工程化”。

官方 Evals / Scorers 文档明确说：

  • scorer 是 automated test
  • 可以 model-graded
  • 可以 rule-based
  • 可以 statistical
  • 返回数值分数
  • 可以实时跑，也可以放到 CI/CD 里跑

压成一句话就是：

Mastra 把“AI 输出质量评估”正式做成了框架层能力。

12.1 可以直接挂到 Agent 上​

官方文档里给了很直接的例子：

import { Agent } from "@mastra/core/agent";
import {
  createAnswerRelevancyScorer,
  createToxicityScorer,
} from "@mastra/evals/scorers/prebuilt";

export const evaluatedAgent = new Agent({
  scorers: {
    relevancy: {
      scorer: createAnswerRelevancyScorer({ model: "openai/gpt-5-mini" }),
      sampling: { type: "ratio", rate: 0.5 },
    },
    safety: {
      scorer: createToxicityScorer({ model: "openai/gpt-5-mini" }),
      sampling: { type: "ratio", rate: 1 },
    },
  },
});

这样一来：

  • 不是只在离线脚本里跑评估
  • 而是可以在真实 agent 执行链路里持续评分

12.2 也可以挂到 Workflow Step 上​

官方文档也支持把 scorer 挂到 workflow step。

这类能力常见于：

  • 多步内容生成
  • 多阶段 research
  • 中间结果质量控制

这样不仅可以评最终答案，也可以评流程中的关键节点。

12.3 为什么这对本专题重要​

因为这和你现在专题里的：

  • Evaluation / Evals
  • Harness Engineering
  • Agent Observability and Debugging

能形成很自然的工程闭环。

13. Observability 到底能看到什么​

Mastra Observability 官方页给的描述已经非常具体：

  • 每次 LLM call 记录 token usage、latency、prompts、completions
  • 每次 agent run 捕获 decision paths、tool calls、memory operations
  • traces 可以发到任何 OTel-compatible provider

如果是在做真实项目，这些信息几乎每一项都很有用：

  • token 用量：看成本
  • latency：看瓶颈
  • prompts / completions：看模型行为
  • decision path：看为什么走到这一步
  • tool calls：看 tool selection 是否合理
  • memory operations：看上下文到底怎么被带入

13.1 它不是“锦上添花”​

Mastra 在这点上的价值很大，因为它把 observability 放在首页产品叙事里，而不是埋到附录里。

因此它比较适合这个专题里的工程化主线。

14. 阅读顺序​

系统学习 Mastra 时，可按下面顺序阅读：

  1. 先看 Agent
  2. 再看 tools
  3. 再看 runtimeContext
  4. 再看 workflow
  5. 再看 memory
  6. 再看 observability
  7. 最后看 evals / scorers

原因很简单：

  • 先学最小执行单元
  • 再学动作能力
  • 再学动态环境
  • 再学显式编排
  • 再学状态
  • 最后补验证和观察

15. 在这个专题里，它最适合和哪些文档一起读​

最适合一起看的是：

16. 和 Vercel AI SDK、LangGraph、Google ADK 怎么分​

16.1 和 Vercel AI SDK​

  • Vercel AI SDK 更适合快速做 TS/Web 里的最小 agent 和 tool loop
  • Mastra 更适合已经开始要 workflow、memory、observability、evals、MCP

可以简单记成：

  • Vercel AI SDK 更偏轻量应用开发层
  • Mastra 更偏完整 TS Agent 框架

16.2 和 LangGraph​

  • LangGraph 更偏 orchestration 底座
  • Mastra 更偏 TS-first 的完整开发框架

如果关注重点包括以下方面：

  • graph 编排本身
  • durable execution
  • 更细的 orchestration

LangGraph 仍然非常核心。

如果关注重点包括以下方面：

  • TS 工程体验
  • agent + workflow + evals + observability 一体化

Mastra 会更顺手。

16.3 和 Google ADK​

  • Google ADK 更偏多语言、完整 agent framework
  • Mastra 更偏 TypeScript-first

所以如果这个专题里要给 TS 读者一条更自然的工程路线，Mastra 非常值得放在前面。

17. 小结​

Mastra 真正有价值的地方，不是“它有很多名词”，而是：

它把 TypeScript 路线里你迟早要面对的工程问题，比较早地一起摆到了桌面上。

因此，它可以作为：

  • 学完最小 agent 之后的第二阶段框架
  • 进入 workflow / evals / observability 的 TypeScript 工程化框架

18. 参考的官方资料​