图1 Mastra 官方站点 og:image 品牌图（官方素材）

Mastra：用现代 TypeScript 栈构建 AI 应用与 Agent 的全栈框架｜部署与使用全指南

项目仓库： https://github.com/mastra-ai/mastra

开源协议：双许可（Apache 2.0 + Mastra Enterprise License）· 主要语言：TypeScript · 交付形态：npm 包 @mastra/core + CLI + Mastra Studio · 官方文档：mastra.ai/docs

官方定位（README 原文）：Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack. It includes everything you need to go from early prototypes to production-ready applications.

1 项目简介

Mastra 是面向 TypeScript 生态的 AI 应用与 Agent 框架，从早期原型到生产环境一站式覆盖。它可以与 React、Next.js、Node.js 等前后端框架集成，也可以作为独立服务部署；自带模型路由、Agent、图式工作流、HITL、上下文管理、MCP server、evals 与可观测性。

1.1 核心信息一览

项目项	内容
项目名称	Mastra（核心包 `@mastra/core`）
仓库地址	github.com/mastra-ai/mastra
项目定位	TypeScript AI 应用与 Agent 框架，覆盖原型到生产
开源协议	双许可：Apache 2.0（核心）+ Mastra Enterprise License（`ee/` 目录）
主要语言	TypeScript / Node.js
交付形态	npm 包、`npm create mastra` CLI、Mastra Studio（本地 Web 界面）
模型路由	40+ 提供者，含 OpenAI、Anthropic、Gemini、xAI 等
默认 Studio 端口	`4111`
官方文档	mastra.ai/docs
官方课程	mastra.ai/course
公司背景	Y Combinator W25 批次

1.2 适用场景

已经在用 React / Next.js / Node.js，希望把 Agent 能力直接嵌进现有 TypeScript 应用。
需要从一个标准接口切换 40+ 模型提供者，做 A/B 与成本对比。
业务流程需要显式编排（路由、分支、并行），而不是完全交给 LLM 自由推理。
需要 HITL：暂停 Agent / 工作流，等用户输入或审批后再继续。
想把 Agent 通过 MCP server 暴露给 Claude、ChatGPT 等外部系统。

1.3 能力边界（官方口径）

核心框架 Apache 2.0；ee/ 目录下企业功能源码可见但生产使用需要 Enterprise License（开发测试可自由使用）。
README 明确：Pull requests 仅对 collaborator 开放；外部贡献以高质量 issue 为主。
模型本身不附带，需要自行准备 OpenAI / Anthropic / Google / xAI 等凭据。

2 功能特性

2.1 模型路由（Model Routing）

通过一个标准接口连接 40+ 提供者：OpenAI、Anthropic、Gemini 等，详见 mastra.ai/models。

2.2 Agents

构建自主 Agent，使用 LLM 与工具解决开放式任务；Agent 自行推理目标、选择工具、内部迭代，直到模型给出最终答案或触发停止条件。

2.3 Workflows（图式工作流）

需要显式控制执行时使用图式引擎：.then()、.branch()、.parallel() 等直观语法编排多步流程。

2.4 Human-in-the-loop

暂停 Agent 或工作流等待用户输入 / 审批；用 storage 记住执行状态，可以无限期暂停再续跑。

2.5 上下文管理

对话历史：Conversation Memory。
RAG 检索：从 API、数据库、文件中检索数据。
Observational Memory：让 Agent 行为更连贯的“类人记忆”。

2.6 集成与 MCP

把 Agent / 工作流打包进 React、Next.js、Node 应用，或作为独立 endpoint 发布。
与 Vercel AI SDK UI、CopilotKit 等 agentic UI 库集成。
内置 MCP server 能力，把 Agent、工具、结构化资源暴露给任何支持 MCP 的系统。

2.7 生产级能力

Evals：内置评估框架，持续测量与迭代。
Observability：内置可观测性，观察 Agent 行为与失败模式。

3 官方界面预览

Mastra Studio 是本地开发时的可视化界面，用于构建、测试、管理 Agent、工作流与工具。启动开发服务器后访问 http://localhost:4111。

README 未在 Markdown 中嵌入 Studio 截图；可按第 6 节启动后自行查看。

4 官方跳转链接汇总

类别	链接	说明
仓库主页	github.com/mastra-ai/mastra	源码、README、开发文档
官方文档	mastra.ai/docs	Agents、Workflows、Memory、RAG、MCP、Evals、Observability
模型路由	mastra.ai/models	40+ 模型提供者清单
官方课程	mastra.ai/course	入门课程
YouTube	@mastra-ai	视频教程
Discord	discord.gg/mastra-ai	社区支持
X	@mastra	发布与动态
npm 包	@mastra/core	核心包
安全	security@mastra.ai	安全问题上报

5 前置要求与服务器配置

5.1 软件前提

Node.js 18+（推荐 20 LTS）。
npm / pnpm / yarn 任一包管理器。
Git。
至少一个模型提供者 API Key：OpenAI、Anthropic、Google、xAI 之一。

5.2 服务器建议

项目	最低 / 建议
操作系统	Linux（Ubuntu 22.04+）/ macOS
CPU	2 核起步，4 核建议
内存	2 GB 起步，4 GB 建议
磁盘	10 GB 可用
网络	能访问模型厂商 API

5.3 端口说明

端口	服务	默认绑定	用途
`4111`	Mastra Studio	`127.0.0.1`	本地开发时可视化管理 Agent / Workflow
`3000` / 自定义	应用服务	视部署	把 Agent 暴露为 HTTP endpoint

6 方式一：npm create 脚手架（推荐）

6.1 新建项目

# 交互式创建
npm create mastra@latest

# 非交互：指定项目名与 LLM 提供者
npm create mastra@latest my-mastra-app -- --llm openai

支持的 --llm 取值：openai、anthropic、google、xai。

6.2 启动开发服务器

cd my-mastra-app
npx bgproc start -n my-mastra-app -w -- npm run dev

打开 Mastra Studio：http://localhost:4111。

6.3 环境变量

创建项目后按 .env 模板填入对应模型 Key：

OPENAI_API_KEY=sk-...
# 或
ANTHROPIC_API_KEY=sk-ant-...
# 或
GOOGLE_API_KEY=...
# 或
XAI_API_KEY=...

7 方式二：源码 / 本地运行

7.1 克隆仓库

git clone https://github.com/mastra-ai/mastra.git
cd mastra

7.2 安装依赖与跑测试

仓库内含 monorepo；本地运行或测试请参考官方 DEVELOPMENT.md：

# 进入仓库后按 DEVELOPMENT.md 安装依赖、构建、跑测试
# 不建议直接在仓库根目录跑业务，业务应基于 npm create 脚手架

7.3 在现有 Node 应用中使用

npm install @mastra/core

按官方文档 Agents 与 Workflows 章节定义 Agent 与工作流，再用框架自带的 server 或 Next.js Route Handler 暴露。

8 配置项说明

8.1 模型提供者

通过统一模型路由接口接入 40+ 提供者；切换模型不改业务代码，详见 mastra.ai/models。

8.2 Storage 与 HITL

工作流暂停 / 恢复依赖 storage；按 server-db/storage 配置。
生产环境建议用持久化数据库（PostgreSQL 等），不要用内存存储。

8.3 Enterprise 功能

ee/ 目录下的功能源码可见，但生产使用需要 Mastra Enterprise License；开发 / 测试可自由使用。

9 常用运维命令

# ---- 项目脚手架 ----
npm create mastra@latest my-mastra-app -- --llm openai
cd my-mastra-app
npx bgproc start -n my-mastra-app -w -- npm run dev

# ---- 包管理 ----
npm install @mastra/core
npm run dev          # 开发
npm run build        # 构建
npm run start        # 生产启动

# ---- Studio ----
# 浏览器访问 http://localhost:4111

# ---- 源码开发 ----
# 克隆仓库后按 DEVELOPMENT.md 操作

10 常见故障排查

10.1 模型调用失败

检查 .env 中对应模型 Key 是否正确。
确认 --llm 选项与所选模型一致。
网络是否能访问模型厂商 API；公司代理需配置 Node 端代理。

10.2 Studio 打不开

确认 npm run dev 已启动；
默认端口 4111 是否被占用；
浏览器插件拦截本地端口时换 Chrome 隐身窗口。

10.3 HITL 暂停后状态丢失

生产环境不要用内存 storage；配置持久化数据库。
重启进程后从 storage 恢复执行状态。

10.4 提交 PR 被拒

README 明确：PR 仅对 collaborator 开放；外部贡献请先开高质量 issue，附复现步骤与描述。

11 风险与合规说明

以下条款整理自官方 README 与双许可证；如与官方原文不一致，以仓库 LICENSE.md、ee/LICENSE 与 mastra.ai/docs 为准。

11.1 开源协议与商业边界

核心框架 Apache 2.0；ee/ 目录下代码采用 Mastra Enterprise License，生产使用需授权。
官方商业支持、托管服务等不在开源仓库交付范围内。

11.2 模型与 API 责任

框架不附带模型；OpenAI、Anthropic、Google、xAI 等模型与服务归各自厂商。
业务数据会按所选模型外发；敏感场景优先本地模型与离线配置。

11.3 自动化与工具权限

Agent / Workflow 可以调用工具、读写外部系统；生产环境应限制工具范围、保留 HITL 审批。
MCP server 暴露后，任何支持 MCP 的系统都能调用对应能力；公网暴露需鉴权。

11.4 免责

使用者在法律允许的最大范围内，自行承担因部署、修改、运行本项目产生的代码质量、数据泄露、服务中断与业务损失风险。安全问题请通过 security@mastra.ai 负责上报，不要在公开 Issue 中提交凭据。