Mastra AI 框架实战指南：TypeScript 全栈团队的最佳 Agent 选择

Mastra 是 2025 年崛起的 TypeScript 优先 Agent 框架。对 Next.js / Remix / Node.js 全栈团队来说，它已经取代 LangChain.js 成为最值得投入的 Agent 抽象。本文系统讲清楚它的设计、用法、与同类框架对比。

一、为什么 TypeScript 团队需要 Mastra

2024 年前，TypeScript 生态的 Agent 开发有几个长期痛点：

• LangChain.js 跟随 Python 版本，类型支持差：很多 API 是 any 或 unknown
• 没有原生 TS 抽象：要么用 LangChain.js，要么自己手撸
• 与 Next.js / Edge 集成不顺畅：流式响应、Server Actions 都要自己处理

Mastra 是为解决这些问题而生的——TypeScript 优先，类型推导完善，与 Vercel 生态深度协同。

二、五大核心抽象

抽象	作用	类比
Agent	LLM + 工具 + system prompt	类似 OpenAI Agents SDK 的 Agent
Workflow	状态机式多步流程编排	类似 LangGraph 但更轻
Memory	短期/长期记忆管理	类似 Letta / Mem0

• RAG | 文档检索增强
• Eval | Agent 输出评估

这五大块覆盖了 90% 的 Agent 应用场景——不需要再装 5 个不同的库。

三、Agent 基本用法

import { Agent } from '@mastra/core';

const researchAgent = new Agent({
  name: 'research-agent',
  instructions: 'You help users research topics using web search.',
  model: openai('gpt-5'),
  tools: { webSearch, fetchUrl },
});

const result = await researchAgent.generate('Summarize the latest on agent frameworks.');

类型推导完整——tools 的 schema、generate 的返回都有强类型。这与 LangChain.js 的"any 走天下"形成鲜明对比。

四、Workflow：状态机式编排

Mastra Workflow 是它的杀手特性——用状态机抽象描述多步流程：

import { Workflow } from '@mastra/core';

const researchWorkflow = new Workflow({
  name: 'research',
  triggerSchema: z.object({ topic: z.string() }),
});

researchWorkflow
  .step(searchStep)
  .then(analyzeStep)
  .then(summarizeStep);

const run = await researchWorkflow.run({ topic: 'agent frameworks' });

每个 step 有明确输入输出 schema，失败、重试、分支都有原生支持。比 LangChain 的 chain 更直观，比 LangGraph 更轻——适合中等复杂度（5-20 步）的业务流程。

五、与 Next.js / Vercel AI SDK 集成

Mastra 与 Vercel AI SDK 深度互操作，流式响应在 Next.js 里几乎零配置：

// app/api/chat/route.ts
import { researchAgent } from '@/mastra/agents';
import { openai } from '@ai-sdk/openai';

export async function POST(req: Request) {
  const { messages } = await req.json();
  const result = await researchAgent.stream(messages);
  return result.toDataStreamResponse();
}

前端用 useChat() hook 接收，全套流式 UI 不用自己拼装。这是 LangChain.js 一直没做好的体验。

六、Memory 与 RAG

Mastra 内置 Memory 抽象，支持短期/长期记忆：

import { Memory } from '@mastra/memory';

const memory = new Memory({
  options: {
    lastMessages: 10,
    semanticRecall: true,
  },
});

researchAgent.memory = memory;

RAG 也内置——文档加载、切分、嵌入、检索都有 TS 原生实现，无需拼装 LangChain + Pinecone + OpenAI embedding 多个库。

七、Eval：Agent 输出评估

这是大多数框架忽视的能力——Mastra 内置 Agent 输出的自动评估：

import { Eval } from '@mastra/eval';

const evalResult = await Eval.accuracy({
  agent: researchAgent,
  input: 'What is LangGraph?',
  output: agentResponse,
  context: { rubric: 'Must mention state graph and LangChain team' },
});

对生产环境的 Agent 质量保障非常重要——CI 里跑 eval，发现回归立即修复。

八、与同类框架对比

维度	Mastra	LangChain.js	OpenAI Agents SDK (TS)	Claude Agent SDK (TS)
类型支持	⭐⭐⭐⭐⭐	⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐
学习曲线	低	中	低	中

• Next.js 集成 | 原生 | 通过 adapter | 良好 | 良好
• 模型支持 | 多模型（通过 Vercel AI SDK） | 多模型 | OpenAI 专属 | Claude 专属
• 内置 RAG | 是 | 需拼装 | 否 | 否
• 内置 Eval | 是 | 否 | 否 | 否
• 适合规模 | 小到中 | 任意 | 小到中 | 小到中

九、生产部署要点

1. Edge 部署： Mastra 在 Vercel Edge / Cloudflare Workers 表现良好，但有些依赖（如部分向量数据库 SDK）需要 Node.js runtime，部署前确认。

2. 持久化： Memory 默认 InMemoryStore，生产要切换到 Postgres / Redis / 向量数据库后端。

3. 可观测性： Mastra 与 OpenTelemetry 兼容，但 dashboard 弱于 LangSmith/Langfuse。生产建议接 Langfuse 或自建 OTel collector。

4. 成本控制： Workflow 的每一步都要监控 token 用量。Mastra 的 Eval 功能可以批量跑，但成本不低，建议在 CI 跑子集而不是全量。

十、什么时候用 Mastra

强烈推荐：

• TypeScript 全栈团队（Next.js / Remix / Astro / Nuxt）
• 中等复杂度的业务流程（5-20 步 Workflow）
• 需要内置 RAG/Memory/Eval 一站式解决方案
• Edge / Serverless 部署场景

不推荐：

• Python 团队（继续用 LangGraph/CrewAI）
• 复杂状态机（用 LangGraph）
• 重度绑定 OpenAI 或 Claude 单一模型（用对应厂商 SDK）

十一、常见坑

• Workflow 不是图： Mastra Workflow 是线性 + 简单分支，复杂循环和条件还是 LangGraph 更合适
• Eval 成本： 默认用最强模型评估，CI 里跑全量很贵，建议采样
• Memory 后端： InMemoryStore 不能用于生产，务必配置持久化
• 版本节奏快： Mastra 还在快速迭代，breaking changes 不罕见，pin 住版本

总结

对 TypeScript 团队来说，Mastra 是 2026 年最值得投入的 Agent 框架。它不是 LangGraph 的 TS 版（定位不同），而是为 TypeScript 全栈场景量身打造的"Vercel AI SDK + Agent 编排 + RAG/Memory/Eval"组合。

---

本文由 AgentList 团队整理。更多 Agent 框架、工具、应用项目，请浏览 AgentList 项目目录。

本文涉及的相关项目

• Mastra — 本文主角，TypeScript 首选 Agent 框架
• LangChain — Mastra 主要是 TS 团队对它的不满而起的；Mastra 流程更强但生态组件库仍较弱
• OpenAI Agents Python — Python 对标 SDK，仅 OpenAI 模型
• Microsoft Agent Framework — 企业 + .NET 对标 SDK