Mastra

Mastra 快速入门

TypeScript 生态的 AI Agent 框架——Gatsby 团队出品，$35M 融资，一体化搞定 Agents、Workflows、Memory、Evals，让你从原型到生产一条龙。

这是什么？适合谁？

Mastra 是一个 TypeScript 原生的 AI Agent 框架（Apache 2.0 许可），由 Gatsby 团队打造。它在 2025 年获得 $35M 融资，GitHub 23k+ Stars。核心定位：不是 Python 框架的 TypeScript 封装，而是从零为 TypeScript/JavaScript 生态设计的 Agent 框架。

Mastra 内置了构建 AI Agent 应用所需的全部组件：Agents（定义 Agent 的行为和工具）、Memory（持久化对话历史和上下文）、Tools（Agent 可调用的函数和 API）、Workflows（多步骤 Agent 编排）、Evals（评估 Agent 输出质量）、Observability（监控和调试 Agent 运行）。这种一体化设计意味着你不需要拼凑 LangChain + LangSmith + LangGraph 等多个库，一个 Mastra 全搞定。

**适合谁？**三类人最受益：一是 TypeScript 全栈开发者，不想学 Python 但想用 AI Agent，Mastra 是天然选择；二是需要快速从原型到生产的团队，Mastra 的一体化设计减少了技术选型和集成成本；三是已有 Node.js 后端的项目，可以直接在现有项目中集成 Mastra，无需引入 Python 技术栈。

注意：Mastra 是纯 TypeScript 框架，如果你主要是 Python 开发者，LangChain 或 CrewAI 可能更合适。Mastra 目前仍处于快速发展期，API 可能有不稳定变更。

准备工作

• 设备要求：Node.js 18+，npm/pnpm/yarn
• 账号要求：至少一个 LLM 提供商 API Key（OpenAI、Anthropic、Google 等）
• 付费要求：Mastra 本身免费开源，LLM API 按量付费
• 可选准备：安装 PostgreSQL（用于 Memory 持久化）、Docker（用于本地开发）

3 步快速上手

第 1 步：创建项目

npx create-mastra@latest my-agent-app
cd my-agent-app
npm install

第 2 步：配置 LLM

创建 .env 文件：

OPENAI_API_KEY="your-key-here"
# 或
ANTHROPIC_API_KEY="your-key-here"

第 3 步：编写第一个 Agent

编辑 src/mastra/agents/hello-agent.ts：

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

export const helloAgent = new Agent({
  name: 'hello-agent',
  instructions: '你是一个友好的助手，用中文回答问题。',
  model: openai('gpt-4o'),
});

// 运行 Agent
const result = await helloAgent.generate('什么是 Mastra？');
console.log(result.text);

启动开发服务器：

npm run dev

访问 http://localhost:3000 即可与你的 Agent 对话。

常见踩坑

踩坑 1：TypeScript 类型错误

• 症状：IDE 中大量 TypeScript 类型报错
• 原因：Mastra 快速迭代，类型定义可能不完全匹配当前版本
• 解决：使用 @ts-ignore 临时绕过，关注 GitHub Issues 和 Release Notes

踩坑 2：Memory 持久化配置

• 症状：重启后对话历史丢失
• 原因：默认使用内存存储，未配置持久化
• 解决：配置 PostgreSQL 或 LibSQL 作为 Memory 存储后端

踩坑 3：Evals 评估失败

• 症状：Evals 运行时报错或超时
• 原因：评估需要额外的 LLM 调用，API 配额不足
• 解决：增加 API 配额，或降低评估频率

踩坑 4：Workflows 步骤执行顺序

• 症状：Workflow 步骤不按预期顺序执行
• 原因：异步步骤的错误处理不完整
• 解决：使用 try-catch 包裹每个步骤，添加 dependsOn 明确依赖关系

常见问题 FAQ

Q1：Mastra 和 LangChain 有什么区别？

A：LangChain 是 Python 生态的 LLM 框架，生态最广但学习曲线陡峭。Mastra 是 TypeScript 原生，学习曲线更平缓，一体化设计减少了集成成本。如果你用 TypeScript，Mastra 是更好的选择；如果你用 Python，LangChain 生态更成熟。

Q2：Mastra 和 CrewAI 有什么区别？

A：CrewAI 专注于多 Agent 协作（Python），Mastra 是一体化 Agent 框架（TypeScript）。CrewAI 适合复杂的多 Agent 场景，Mastra 适合从简单到复杂的全栈 Agent 应用。

Q3：能否部署到生产环境？

A：可以。Mastra 提供 @mastra/deployer 用于生产部署，支持 Vercel、AWS、Docker 等平台。但 Mastra 仍在快速迭代，建议在非关键业务中使用。

Q4：是否支持本地模型？

A：通过 @ai-sdk/openai-compatible 可以连接 Ollama 等本地模型服务。但 Mastra 的某些高级功能（如结构化输出）对模型能力有要求。

Q5：Mastra 和 Vercel AI SDK 有什么关系？

A：Mastra 底层使用了 Vercel AI SDK（@ai-sdk/*），但提供了更高层的 Agent 抽象。可以理解为 Mastra 是 Vercel AI SDK 的 Agent 框架封装。

参考链接

• Mastra 官网
• GitHub 仓库
• Mastra 文档
• 快速开始
• Vercel AI SDK