Mastra

Mastra 是一个基于现代 TypeScript 技术栈的框架，用于构建由 AI 驱动的应用程序和智能体。

它提供了从早期原型到生产就绪应用所需的一切。Mastra 可以与 React、Next.js 和 Node 等前后端框架集成，也可以作为独立服务器部署在任何地方。它是构建、调优和扩展可靠 AI 产品的最简单方式。

为什么选择 Mastra？

Mastra 专为 TypeScript 打造，并围绕成熟的 AI 模式设计，开箱即用，为您提供构建优秀 AI 应用所需的全部功能。

亮点包括：

• 模型路由 - 通过一个标准接口连接 40 多家提供商。支持 OpenAI、Anthropic、Gemini 等多种模型。

• 智能体 - 构建能够使用大语言模型和工具解决开放式任务的自主智能体。智能体会对目标进行推理，决定使用哪些工具，并在内部迭代，直到模型生成最终答案或满足可选的停止条件。

• 工作流 - 当您需要对执行过程进行显式控制时，可以使用 Mastra 基于图的工作流引擎来编排复杂的多步骤流程。Mastra 工作流采用直观的语法来控制流程（.then()、.branch()、.parallel()）。

• 人机协作 - 暂停智能体或工作流，在恢复之前等待用户输入或批准。Mastra 使用 存储 来记住执行状态，因此您可以无限期暂停，并在中断处继续。

• 上下文管理 - 在正确的时间为您的智能体提供合适的上下文。提供 对话历史，从您的数据源（API、数据库、文件）中 检索 数据，并添加类似人类的 工作记忆 和 语义记忆，使您的智能体行为更加连贯。

• 集成 - 将智能体和工作流打包到现有的 React、Next.js 或 Node.js 应用中，或者将其作为独立的 API 端点发布。在构建 UI 时，可以与 Vercel 的 AI SDK UI 和 CopilotKit 等智能体库集成，从而在网页上实现您的 AI 助手。

• MCP 服务器 - 开发 Model Context Protocol 服务器，通过 MCP 接口公开智能体、工具和其他结构化资源。这些资源随后可以被任何支持该协议的系统或智能体访问。

• 生产必备 - 发布可靠的智能体需要持续的洞察、评估和迭代。借助内置的 评估 和 可观测性，Mastra 为您提供持续观察、度量和优化的工具。

开始使用

开始使用 Mastra 的 推荐 方法是运行以下命令：

npm create mastra@latest

请按照 安装指南 中的说明，通过 CLI 或手动安装逐步完成设置。

如果您是 AI 智能体的新手，请查看我们的 模板、课程 和 YouTube 视频，立即开始使用 Mastra 进行开发吧。

文档

请访问我们的 官方文档。

使用 AI 构建

按照 使用 AI 构建指南，学习如何让您的智能体成为 Mastra 专家。

贡献

希望参与贡献吗？我们欢迎各种形式的帮助，从编码到测试和功能规范。请阅读 CONTRIBUTING.md 以了解如何参与。

如果您是开发者并希望提交代码，请先打开一个问题讨论，再创建拉取请求。

有关项目设置的信息，请参阅 开发文档。

支持

我们有一个开放的社区 Discord 群组：discord.gg/BTYqqHKUrf。欢迎加入并与我们交流，如果您有任何问题或需要帮助启动项目，请随时告诉我们。

此外，如果您能在页面顶部的 GitHub 仓库 上给本项目点个赞，将对我们非常有帮助。

许可证

本仓库采用双重许可证模式：

• Apache License 2.0 — 核心框架及本代码库的绝大部分内容均以 Apache-2.0 开源许可发布。
• Mastra 企业许可证 — 任何名为 ee/ 的目录中的代码（例如 packages/core/src/auth/ee/）均以 Mastra 企业许可证开源。这些功能在生产环境中使用需要有效的企业许可证，但在开发和测试阶段可以免费使用。

完整的许可证映射请参阅 LICENSE.md，企业许可证条款请参阅 ee/LICENSE。

安全性

我们致力于维护本仓库以及整个 Mastra 项目的安全性。如果您发现任何安全漏洞，请通过 security@mastra.ai 以负责任的方式向我们报告，我们将尽快与您联系。

Mastra 快速上手指南

Mastra 是一个基于现代 TypeScript 技术栈构建的 AI 应用与智能体（Agent）开发框架。它提供了从原型设计到生产部署所需的全套工具，支持模型路由、自主智能体、工作流编排、人机协作及可观测性等核心功能。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：macOS, Linux, 或 Windows (推荐 WSL2)
• Node.js：版本 18.0 或更高（推荐使用 LTS 版本）
• 包管理器：npm, yarn, pnpm 或 bun
• 编辑器：VS Code 或其他支持 TypeScript 的 IDE

提示：国内开发者若遇到 npm 安装缓慢，可临时切换至淘宝镜像源：

npm config set registry https://registry.npmmirror.com

安装步骤

推荐使用官方提供的 CLI 工具快速初始化项目，这是最简便的起步方式。

1. 创建新项目 在终端运行以下命令：

   npm create mastra@latest
   

2. 跟随向导配置 命令行将引导您完成以下设置：

   • 输入项目名称
   • 选择模板（如基础 Agent、工作流等）
   • 选择包管理器（npm/pnpm/yarn/bun）

3. 进入项目目录并安装依赖

   cd <your-project-name>
   npm install
   # 或者如果您选择了其他包管理器
   # pnpm install
   # yarn install
   # bun install
   

4. 配置环境变量 在项目根目录找到 .env 文件，填入您的 LLM 提供商 API Key（如 OpenAI, Anthropic 等）：

   OPENAI_API_KEY=sk-your-api-key-here
   

基本使用

以下是一个最简单的示例，展示如何定义一个具备工具调用能力的 AI 智能体。

1. 定义智能体 (agent.ts)

在 src/mastra/agents 目录下创建文件（具体路径依模板而定），编写如下代码：

import { Mastra } from '@mastra/core';
import { openai } from '@mastra/openai';
import { calculatorTool } from './tools'; // 假设已定义的工具

export const mastra = new Mastra({
  agents: {
    mathAssistant: {
      name: 'Math Assistant',
      instructions: 'You are a helpful math tutor. Use the calculator tool to solve problems.',
      model: openai('gpt-4o'),
      tools: [calculatorTool],
    },
  },
});

2. 运行智能体

创建一个入口文件（如 index.ts）来启动并调用智能体：

import { mastra } from './src/mastra/agents';

async function main() {
  const agent = mastra.getAgent('mathAssistant');
  
  const response = await agent.generate('What is 123 multiplied by 456?');
  
  console.log(response.text);
}

main().catch(console.error);

3. 启动开发服务器

如果项目包含服务端功能，通常可以使用以下命令启动本地开发服务器：

npm run dev

现在，您已经成功运行了第一个 Mastra 智能体。您可以继续探索 Workflows 进行复杂流程编排，或使用 Memory 功能为智能体添加长期记忆。