Mastra：TypeScript 优先 Agent 框架

为什么需要 Mastra：JS/TS 生态缺少原生 Agent 生产框架

在 JS/TS 生态中构建生产级 Agent，传统方式是自研拼装。Vercel AI SDK 只解决模型接入与流式传输，不提供状态管理；对话记忆要另接 Redis 或数据库；工具调用要自己写参数校验与重试；多步骤流程要自行设计状态机；排查问题要自建 trace 链路。每一步都有可行方案，但组合起来的代码量、调试成本与团队心智负担都很高。Python 生态有 LangChain 等成熟框架，但 TS 团队整体迁移到 Python 栈会带来额外的运维与人才成本。

Mastra 把这些能力全部收进一个框架。Agent 类提供统一入口：instructions 定义角色设定，model 切换模型，tools 挂载类型安全的工具，memory 接管历史上下文；Workflow 提供确定性的多步编排；所有工具输入输出由 Zod schema 声明，编译期即可发现参数错误。生产路径同样完整：本地 mastra dev 面板可交互调试，生产可部署到 Vercel、Cloudflare、Docker，或直接使用 Mastra Cloud 托管，并内置 OpenTelemetry 观测能力。

与同类工具的气质差异在于：LangChain.js 是从 Python 移植的庞大抽象体系，概念多、类型约束弱；Mastra 的 API 是原生 TS 风格，更接近 Vercel AI SDK 的简洁，但比 AI SDK 多出 Agent 生命周期、记忆、工作流与可观测性这一整层——AI SDK 更适合作为 Mastra 的模型层，而非替代品。

安装与环境配置：3 步就绪

步骤一·安装：使用官方脚手架创建项目。交互式界面可选择示例模板与集成项，自动生成 agents/、workflows/ 目录与 mastra.config.ts 配置文件；也可在既有项目中手动安装核心包。

步骤二·配置：在项目根目录创建 .env 文件，设置模型供应商密钥。脚手架会同时生成 .env.example 说明需要哪些变量。

步骤三·验证：启动本地调试服务器，在浏览器打开调试面板，确认项目注册的 agent 出现在列表中且可以对话。

环境要求：Node.js 18 及以上；脚手架会自动安装 @mastra/core、AI SDK provider（如 @ai-sdk/openai）与 zod。

# 1) 脚手架创建项目（交互式选择集成与示例）npm create mastra@latestcd my-mastra-appnpm install # 2) 配置模型密钥cp .env.example .env# 编辑 .env，填入 OPENAI_API_KEY=sk-xxx（或其他 provider 对应变量） # 3) 启动本地调试（默认 http://localhost:4111）npm run dev# 等价命令：npx mastra dev

快速上手：10 分钟跑通第一个带工具的 Agent

思路：先创建一个 Agent（模型 + 指令），再用 createTool 定义一个带 Zod schema 的工具，把工具挂载到 Agent 上，最后通过调试面板或编程式调用验证 Agent 能自主调用工具并给出答案。

步骤一：在 agents/ 目录新建文件定义 Agent 与工具。工具必须声明输入与输出 schema，execute 函数接收类型推导后的 context，返回值会送回模型作为工具调用结果。

步骤二：在 mastra.config.ts 中注册 agent，使调试面板与部署流程能发现它。

步骤三：npm run dev 启动后在 playground 选择该 agent 并发送「北京天气怎么样？」，观察工具调用轨迹与回答；或在任意 TS 入口调用 generate() 编程式使用。

跑通后，回答会包含工具返回的「24 度、多云」信息。进阶方向：给 Agent 配置 memory 实现多轮记忆，或再挂一个工具让模型在多个工具间做选择。

// my-mastra-app/src/agent.tsimport { Agent, createTool } from '@mastra/core';import { openai } from '@ai-sdk/openai';import { z } from 'zod'; const weatherTool = createTool({  id: 'get-weather',  inputSchema: z.object({ city: z.string().describe('城市名') }),  outputSchema: z.object({ degrees: z.number(), description: z.string() }),  execute: async ({ context }) => {    // 生产环境在此调用真实天气 API    return { degrees: 24, description: '多云' };  },}); export const assistant = new Agent({  name: 'assistant',  instructions: '你是天气助手，必须使用天气工具回答城市天气。',  model: openai('gpt-4o'),  tools: { getWeather: weatherTool },}); // 在 mastra.config.ts 中注册：// import { defineConfig } from '@mastra/core';// import { assistant } from './src/agent';// export default defineConfig({ agents: { assistant } }); // 编程式调用：// const result = await assistant.generate('北京天气怎么样？');// console.log(result.text);

核心能力详解：5 大支柱

支柱一·Agent：统一的智能体容器。instructions + model + tools + memory 四要素组合，generate() 一次调用完成「接收→思考→工具调用→应答」全流程。多个 Agent 可在 Mastra 实例中注册并通过 API 路由暴露，彼此隔离、独立部署。

支柱二·Tools：类型安全的工具系统。createTool 强制声明 inputSchema 与 outputSchema（Zod），execute 收到的 context 自带类型推导；模型产出的工具参数在进入 execute 前经过运行时校验，失败会自动反馈模型重试。工具挂载后自动适配各家模型的 function calling 协议，切换模型供应商无需改工具代码。

支柱三·Workflow：确定性编排。以 step 为最小单位的图式工作流，支持顺序、并行、条件分支、重试与超时。与让模型自由发挥的 Agent 不同，Workflow 适合业务路径固定的场景（先检索、再写作、再审核），关键步骤可控、可观测、可重放。

支柱四·Memory 与 RAG：记忆组件提供线程（thread）级别的会话隔离与多轮上下文管理，storage 可接 PostgreSQL、LibSQL 或内存实现；RAG 工具链提供文档加载、分块、向量化与检索，向量库支持 PG、Qdrant、Chroma 等适配器，适合搭建「私有知识库 + 检索增强应答」。

支柱五·可观测性与评测：内置 OpenTelemetry 追踪，mastra dev 面板展示每次调用的工具轨迹、Token 用量与耗时；@mastra/evals 提供事实一致性、有害性等自动评测指标，可接入 CI 防止回归。

生产部署与监控：从上线到运维

部署方式一·Mastra Cloud：官方托管平台，连接 GitHub 仓库后自动构建部署 Agent/Workflow 服务，自带内置 playground、追踪、用量统计与密钥管理，适合不想维护基础设施的团队；提供免费额度用于 PoC，升级按用量计费。

部署方式二·自托管与边缘部署：@mastra/deployer 系列支持 Vercel、Netlify、Cloudflare Workers 与 Docker。以 Vercel 为例，在 mastra.config.ts 中配置 VercelDeployer 并设置 token 与项目名，执行构建与部署命令即可上线；Docker 场景下框架输出标准 Node.js 服务镜像，适合已有 Kubernetes 或自有服务器的团队。

可观测性：无论哪种部署，建议开启 OpenTelemetry 导出，将追踪接入 Sentry、Datadog 或 Grafana 等 APM 体系；生产环境要为模型调用设置超时与重试，为每个工具调用记录输入输出日志，作为审计与调优依据；Evals 评测纳入 CI，在每次改动后自动检查回答质量。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>0.2.0 是破坏性重构：网上大量 0.1.x 教程中的 Agent/Tool 写法已失效，先确认官方文档版本号再照抄代码。</li><li>mastra dev 只是本地调试面板：生产部署必须走构建与 deployer 流程，不要把 dev 服务直接暴露公网。</li><li>Memory 默认存进程内存：不配置 storage 时重启即丢历史，生产务必接 PostgreSQL 或 LibSQL 持久化。</li><li>工具参数校验依赖 Zod：schema 缺失或版本与 @mastra/core 不匹配会让工具调用在运行时静默失败，升级框架时同步升级 zod。</li></ul>

版本迭代

Mastra 于 2025 年初公开首个版本，此后保持每月级迭代节奏。0.1.x 完成 Agent、工具、工作流基础能力的验证；0.2.0 是一次面向生产化的破坏性重构，重写 Agent 与工具 API，同时推出 Mastra Cloud 与部署器生态，确立了当前 API 风格（截至训练数据，可能已有更新版本）。

AI 应用场景

常见误区

面试题

参考来源

• webpageMastra 官网产品介绍、博客与 Cloud 入口