Mastra翻译站点

Mastra 是 Mastra 团队（Gatsby.js 原班）打造的 TypeScript-first AI 智能体框架，官方定位：”Mastra is the modern TypeScript framework for AI-powered applications and agents” 。

许可采用双轨制：核心框架 Apache-2.0，企业特性目录 ee/ 采用 Mastra Enterprise License（源代码可见，开发测试免费，生产需企业许可） 。

核心能力一体化：Agents（ReAct 式自主智能体，内置 memory、tool calling、MCP 支持）+ Workflows（graph-based 确定性工作流，.then()/.branch()/.parallel() 控制流，支持 human-in-the-loop）+ Memory（conversation history、working memory、semantic memory）+ Observability（built-in evals、tracing、telemetry）+ Deploy（Next.js/Express/Hono 集成或 standalone server） 。模型路由连接 90+ 提供商​ 通过统一接口。它是 Agent 框架分类中“TypeScript 生态原生生产框架”的代表作。

 

产品概述

Mastra 的故事始于 Gatsby.js 团队（著名的静态站点生成器）向 AI 时代的延伸——他们把”opinionated defaults、conventions over configuration、tight ecosystem integration”的哲学应用到 Agent 框架 ，由 YC W25 批次支持 。v1.0 于 2026 年 1 月发布 ，2026 年 7 月 Vercel AI SDK 7 发布后与 Mastra 形成”Vercel AI SDK 作为基础 + Mastra 作为上层框架”的常见组合 。

 

核心定位哲学：

官方 GitHub 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” 。三个不可妥协的设计原则：

• TypeScript 原生：为 TypeScript/JavaScript 生态原生设计，Zod 模式端到端类型化——而非 Python 框架的 TS 移植
• Batteries-included：agents + workflows + memory + observability + deploy 一体化，开发者无需拼凑单独的库
• Agents 与 Workflows 明确分离：自主推理用 Agents（ReAct 式），确定性执行用 Workflows（graph-based）——这种拆分给开发者同时提供灵活性与可预测性

 

它做什么 / 不做什么（关键归类）：

• ✅ 做：作为 TypeScript 框架安装到你的项目中 → 通过 npm create mastra@latest 创建项目 → 定义 Agents（instructions + model + tools + memory）和 Workflows（.then()/.branch()/.parallel()）→ 通过 Mastra Studio（http://localhost:4111）构建、测试、管理 → 部署为 Next.js/Express/Hono 集成或 standalone server
• ❌ 不做：不提供 LLM 推理本身（通过模型路由连接 90+ 提供商）；ee/ 目录企业特性（如 packages/core/src/auth/ee/）需企业许可用于生产
• 本质是 TypeScript 原生智能体框架：它必须 npm install 安装到 TypeScript 项目中，写 TS 代码定义 Agents/Workflows——与 AutoGPT（可视化 SaaS 平台）、Goose（本地桌面/CLI 智能体产品）有根本形态差异。它是 Agent 框架分类中唯一的”TypeScript 原生生产框架”。

 

技术架构​ ：

• 实现语言：TypeScript 99.3%（核心） ，需要 Node.js 22.18.0+ 直接运行 TS 文件
• 核心抽象：
  • Agent：new Agent({ id, name, instructions, model, tools })——ReAct 式自主智能体，LLM 决策路径
  • Workflow：graph-based 确定性工作流引擎，显式控制执行流
  • Tool：通过 createTool() 定义（必须用 createTool()，plain object 会静默失败），含 inputSchema(Zod) + execute()
  • Memory：conversation history + working memory + semantic memory
  • Mastra 实例：new Mastra({ agents, workflows, server }) 统一注册
• 模型路由：provider/model 格式字符串（如 openai/gpt-5.6-sol、anthropic/claude-sonnet-4-6），连接 90+ 提供商 通过统一接口，自动读取环境变量（如 OPENAI_API_KEY）
• Workflow 控制流：.then()（顺序）、.branch()（条件）、.parallel()（并行）；支持 human-in-the-loop——挂起工作流等待用户输入或审批，通过 storage 记住执行状态，可无限期暂停后从断点恢复
• 部署形态：
  • 集成部署：bundle 到 React/Next.js/Node.js 应用
  • Standalone server：mastra dev 启动开发服务器（Mastra Studio 在 http://localhost:4111）
  • Deploy platform：Mastra Cloud 或任意托管平台
  • Serverless：Vercel、Netlify、Cloudflare Workers
• Mastra Studio：本地开发服务器，构建、测试、管理智能体/工作流/工具的界面
• 能力矩阵：
  • Observability：built-in evals、tracing、telemetry
  • MCP 支持：author MCP servers，exposing agents/tools 通过 MCP 接口
  • Guardrails：input/output processing 防止 prompt injection
  • Integrations：与 Vercel AI SDK UI、CopilotKit 等 agentic libraries 集成
  • Dynamic Workflows：2026 年 8 月 12 日引入——运行中动态添加/更新/移除工作流
  • iMessage Support：2026 年 8 月 11 日引入
  • Sensitive Data Redaction：2026 年 8 月 10 日引入 observability 敏感数据脱敏

 

许可策略（双轨制）​ ：

📌 核心框架 Apache-2.0：绝大多数代码开源，商用、修改、分发无限制

📌 Mastra Enterprise License：ee/ 目录下的代码（如 packages/core/src/auth/ee/）采用源代码可见的企业许可，开发测试免费，生产使用需有效企业许可​

这是与纯 Apache-2.0 项目（Milvus/Qdrant/Vespa/AG2/Goose）的关键差异——Mastra 的核心框架自由，但企业特性（如某些 auth 功能）受商业许可约束。

 

生态定位（2026 年 TypeScript Agent 框架三分天下）：

第三方对比分析（2026 年 7 月）显示，TypeScript 原生 AI Agent 框架生态由三个领导者组成 ：

• Mastra：Batteries-included 一体化框架，v1.0（2026 年 1 月）
• LangChain + LangGraph：Modular framework + graph orchestrator，LangGraph.js 是 TS 实现
• Vercel AI SDK：Foundational toolkit，SDK 7（2026 年 6 月）

LangChain 官方在 2026 年 6 月的框架对比中也将 Mastra 列为七大主流框架之一，定位：”Partial open source, TypeScript teams building production custom agents” ——明确点出 Mastra 的双许可特性和 TypeScript 生产定位 。

 

核心能力

 

-Agents（ReAct 式自主智能体）

• 定义：new Agent({ id, name, instructions, model, tools })
• LLM 决策路径：Agents reason about goals，decide which tools to use，iterate internally until final answer
• 内置能力：memory、tool calling、MCP support
• 模型路由：provider/model 格式字符串，90+ 提供商 通过统一接口
• 与 Workflows 明确分离：自主推理用 Agents，确定性执行用 Workflows

 

-Workflows（graph-based 确定性工作流）

• graph-based workflow engine：编排复杂多步骤流程，显式控制执行
• 控制流语法：
  • .then()：顺序执行
  • .branch()：条件分支
  • .parallel()：并行执行
• Human-in-the-loop：挂起工作流等待用户输入或审批
• 持久化状态：通过 storage 记住执行状态，可无限期暂停后从断点恢复
• Dynamic Workflows（2026 年 8 月 12 日）：运行中动态添加/更新/移除工作流，无需改代码

 

– Memory（上下文管理）

• Conversation history：对话历史
• Working memory：类人的工作记忆
• Semantic memory：语义记忆
• Retrieval：从 APIs、databases、files 检索数据
• 自动压缩：memory 层自动维护与压缩对话上下文（代价是 token 开销）

 

-Observability（内置可观测与评估）

• Built-in evals：model-graded、rule-based、statistical 三种评估方法
• Tracing：查看智能体调用与 token 使用
• Telemetry：与 o11y platform 集成
• Sensitive Data Redaction（2026 年 8 月 10 日）：自动脱敏 agent traces 中的敏感客户信息
• Mastra Studio：本地开发服务器（http://localhost:4111），构建/测试/管理智能体

 

-Integrations & MCP

• 框架集成：React、Next.js、Node.js、Express、Hono
• Agentic libraries：Vercel AI SDK UI、CopilotKit
• MCP 支持：author MCP servers，exposing agents/tools 通过 MCP 接口
• iMessage Support（2026 年 8 月 11 日）：用户可通过 iPhone/iPad/Mac 的 iMessage 与智能体聊天

 

-Guardrails

• Input/output processing：防止 prompt injection
• Sensitive data redaction：traces 中自动脱敏

 

-Deployment

• Bundle 集成：将 agents/workflows 打包进现有 React/Next.js/Node.js 应用
• Standalone server：mastra dev 启动独立服务
• Serverless：Vercel、Netlify、Cloudflare Workers
• Mastra Cloud：官方全托管部署平台
• 灵活架构：wherever you’re hosting your app

 

 -开发者体验

• npm create mastra@latest：一键脚手架
• TypeScript 原生：Zod 模式端到端类型化，IDE 自动补全全链路
• Node.js 22.18.0+：直接运行 TS 文件
• Templates：预构建解决方案
• Agent Book / Tutorial / Workshops：学习资源

 

优势亮点

• TypeScript 原生：为 TypeScript/JavaScript 生态原生设计，Zod 类型化贯穿全栈——不是 Python 框架的 TS 移植
• Batteries-included：agents + workflows + memory + observability + deploy 一体化，开发者无需拼凑单独的库
• Agents 与 Workflows 明确分离：自主推理与确定性执行语义清晰，开发者可根据任务选择合适原语
• 90+ 模型提供商：通过统一模型路由接口连接 OpenAI/Anthropic/Gemini 等
• 内置可观测与评估：built-in evals、tracing、telemetry，无需外接 LangSmith
• Human-in-the-loop：工作流可挂起等待用户输入，storage 持久化状态
• Mastra Studio：本地开发服务器提供构建/测试/管理界面
• 部署灵活：React/Next.js/Node 集成 / Standalone server / Serverless / Mastra Cloud
• MCP 原生：author MCP servers
• 双许可开源：核心框架 Apache-2.0 完全自由；ee/ 企业特性源代码可见
• v1.0 稳定：2026 年 1 月发布，不再是 beta
• 社区增长迅速：约 25,458 GitHub Stars（2026 年 6 月）
• Gatsby 团队背景：十年 TypeScript 框架经验，开发者体验优先
• 2026 年 8 月密集发布：Dynamic Workflows、iMessage Support、Sensitive Data Redaction
• 与 Vercel AI SDK 互补：常见组合是 Vercel AI SDK 作基础 + Mastra 作上层框架

 

局限

• ⚠️ 双许可约束：核心框架 Apache-2.0 自由，但 ee/ 目录企业特性（如 packages/core/src/auth/ee/）采用 Mastra Enterprise License，生产使用需企业许可​ ——与纯 Apache-2.0 项目（Milvus/Qdrant/Vespa/AG2/Goose）有本质差异
• ⚠️ TypeScript 锁定：Mastra 是 JavaScript/TypeScript 专用，切换到 Python/Go 后端需要重写编排逻辑 ——Python 团队应选用 LangChain/LangGraph
• ⚠️ 默认 token 开销较大：第三方基准测试显示相同 Agent pipeline 下 Mastra 消耗 1.5-2.5x token，比 LangChain 慢 25-45% ——差距主要来自 Mastra 的 memory 层自动维护与压缩对话上下文
• ⚠️ 生态集成小于 LangChain：LangChain 有 1000+ 集成，Mastra 的预构建集成库较小，更多需要 DIY tool authoring
• ⚠️ 无官方 SOC 2/HIPAA 认证：截至 2026 年初，Mastra 本身无合规认证，自托管需自己产生合规文书 ——受监管行业需评估
• ⚠️ 企业支持不成熟：Mastra Cloud 团队版 $250/月定价较新，企业支持体系仍在成熟中
• ⚠️ Workflows 是确定性的：非常开放的”让模型决定一切”的动态执行图在 Mastra 中较难推理，需 guardrails ——极端开放式任务可用 LangGraph
• ⚠️ 供应商特定 LLM 功能受限：Mastra 的通用抽象无法暴露 provider-specific 功能（constrained decoding、proprietary tool schemas）
• ⚠️ 模型切换需重测：尽管支持多提供商，但 provider-specific behavior（prompt interpretation、tool calling、output format）仍有差异，切换模型需重新测试与 prompt 调优
• 与 LangChain 对比：LangChain 有 Python 核心、1000+ 集成、LangSmith 企业级可观测性、SOC 2/HIPAA 认证；Mastra 是 TypeScript 原生、集成库较小、无合规认证
• 与 LangGraph 对比：LangGraph 提供显式状态图控制（nodes、conditional edges、checkpointing、interrupts），对复杂有状态多智能体编排更精细；Mastra 的 workflow 引擎较高级封装
• 与 MAF 对比：MAF 有 Python/.NET 双语言、Azure AD/RBAC/SOC 2 企业特性；Mastra 仅 TypeScript，企业特性需企业许可
• 学习曲线：Agents 与 Workflows 的明确分离要求开发者在任务设计阶段就决定使用哪种原语

 

适用人群

• TypeScript/JavaScript 技术栈团队：前端/全栈开发者构建 AI Agent，无需切换到 Python
• Next.js/React/Node.js 生态：希望将 agents/workflows 直接 bundle 进现有应用
• 追求 time-to-first-agent 的团队：batteries-included 的一体化框架，agents + workflows + memory + observability + studio 开箱即用
• 生产级 TypeScript Agent 应用：需要内置可观测性、评估、human-in-the-loop 的生产系统
• Vercel/Netlify/Cloudflare Workers 部署：serverless-first 的 TypeScript 团队
• 不想拼凑多个库：希望一个框架覆盖从原型到生产的完整生命周期
• 需要 Agents 与 Workflows 明确分离：同时需要自主推理（agents）和确定性执行（workflows）的场景
• YC/初创团队：Mastra 自身 YC W25 背景，对初创团队友好

⚠️ 不适用场景：

• Python 核心技术栈（应选 LangChain/LangGraph/MAF）
• 需要 1000+ 预构建集成的场景（LangChain 更合适）
• 受监管行业需要 SOC 2/HIPAA 认证（Mastra 无官方认证，需自产生合规文书）
• 极端开放式”让模型决定一切”的动态执行（LangGraph 更精细）
• 不愿意接受双许可约束（核心 Apache-2.0 自由，但 ee/ 企业特性需企业许可）

 

安装与部署

 

1. 环境要求

• Node.js 22.18.0+（支持直接运行 TS 文件）
• npm/pnpm/yarn/bun 包管理器
• TypeScript 项目（ES2022 模块设置）

 

2. 创建 Mastra 项目（推荐）

# 使用 create-mastra 脚手架
npm create mastra@latest

# 按提示输入项目名称，选择 provider（openai/anthropic/google 等）

 

3. 手动安装

# 创建项目
mkdir my-first-agent && cd my-first-agent
npm init

# 安装依赖
npm install -D typescript @types/node mastra@latest
npm install @mastra/core@latest zod@^4

# 配置 package.json scripts
# {
#   "scripts": {
#     "dev": "mastra dev",
#     "build": "mastra build"
#   }
# }

# 创建 tsconfig.json
# {
#   "compilerOptions": {
#     "target": "ES2022",
#     "module": "ES2022",
#     "moduleResolution": "bundler",
#     "esModuleInterop": true,
#     "strict": true,
#     "skipLibCheck": true,
#     "noEmit": true
#   },
#   "include": ["src/**/*"]
# }

# 配置 .env
# OPENAI_API_KEY=sk-...
# 或 ANTHROPIC_API_KEY、GOOGLE_API_KEY 等

 

4. 定义 Tool

// src/mastra/tools/weather-tool.ts
import { createTool } from "@mastra/core/tools";
import { z } from "zod";

export const weatherTool = createTool({
  id: "get-weather",
  description: "Get current weather for a location",
  inputSchema: z.object({
    location: z.string().describe("City name"),
  }),
  outputSchema: z.object({
    location: z.string(),
    temperatureCelsius: z.number(),
    conditions: z.string(),
  }),
  execute: async ({ location }) => {
    return {
      location,
      temperatureCelsius: 21,
      conditions: "sunny",
    };
  },
});

⚠️ 必须使用 createTool()：plain object 工具定义会静默执行失败

 

5. 定义 Agent

// src/mastra/agents/weather-agent.ts
import { Agent } from "@mastra/core/agent";
import { weatherTool } from "../tools/weather-tool.ts";

export const weatherAgent = new Agent({
  id: "weather-agent",
  name: "Weather Agent",
  instructions: `You are a helpful weather assistant.`,
  model: "openai/gpt-5.6-sol",  // provider/model 格式
  tools: { weatherTool },
});

📌 模型字符串格式：provider/model（用 / 不用 :），如 openai/gpt-5.6-sol、anthropic/claude-sonnet-4-6、google/gemini-2.5-flash

 

6. 创建 Mastra 实例

// src/mastra/index.ts
import { Mastra } from "@mastra/core";
import { weatherAgent } from "./agents/weather-agent.ts";

export const mastra = new Mastra({
  agents: { weatherAgent },
  server: { port: 4111 },
});

 

7. 运行与开发

# 启动开发服务器（Mastra Studio 在 http://localhost:4111）
npm run dev

# 运行 agent
node --experimental-strip-types run.mts
# 或 Node.js 22.18.0+ 直接运行 TS

 

8. 定义 Workflow

import { createWorkflow } from "@mastra/core/workflows";

const myWorkflow = createWorkflow({
  id: "my-workflow",
  inputSchema: z.object({ input: z.string() }),
})
  .then(step1)
  .branch((ctx) => ctx.input.someCondition, trueBranch, falseBranch)
  .parallel([parallelStep1, parallelStep2])
  .commit();

 

9. 部署到生产

# 构建
npm run build

# 部署选项：
# 1. Bundle 到 Next.js/Express/Hono 应用
# 2. Standalone server: node dist/server.js
# 3. Serverless: Vercel/Netlify/Cloudflare Workers
# 4. Mastra Cloud: 官方全托管平台

 

10. 部署前必检清单

• 确认仓库位于 github.com/mastra-ai/mastra（官方）
• 许可：双许可证​
  • 核心框架：Apache-2.0（绝大多数代码）
  • 企业特性（ee/ 目录）：Mastra Enterprise License（源代码可见，开发测试免费，生产使用需企业许可）
• 严格属于 Agent 框架分类，“TypeScript 原生生产框架”子类
• 官方定位：”Mastra is the modern TypeScript framework for AI-powered applications and agents”
• 开发方：Mastra 团队（Gatsby.js 原班），YC W25 支持
• 语言：TypeScript 99.3%
• 最新版本：v1.0（2026 年 1 月发布）
• 社区规模：约 25,458 GitHub Stars（2026 年 6 月）