Mastra 是什么：面向 TypeScript 的现代 AI Agent 框架核心原语解析

Mastra 是什么：面向 TypeScript 的现代 AI Agent 框架核心原语解析

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra

导读：本篇文章是 Mastra「构建你的第一个 Agent」入门课程的第二课，围绕 docs/src/course/01-first-agent/02-what-is-mastra.md 展开。你将理解 Mastra 作为 TypeScript AI Agent 框架的核心定位：开箱即用的 AI 工程原语——带工具、记忆与追踪的 Agent、基于状态机的工作流、Evals 评测、RAG 存储与本地开发 Playground。读完本文，你将掌握 Mastra 的能力地图、核心模块在仓库中的真实分布，以及「模块化、可扩展」设计的具体含义，为后续动手创建第一个 Agent 打下基础。

从一个问题开始：为什么需要专门的 Agent 框架

在 上一课 中我们了解到：Agent 是能够感知环境、基于输入做决策、采取行动达成目标，并持续学习与适应行为的软件系统。但把大语言模型（LLM）接入业务逻辑，远不止「调用一次 API」那么简单——它需要记忆、规划、工具调用、反馈闭环等一系列工程能力的组合。

Mastra 正是为了解决这一问题而出现的：一个面向 TypeScript 的开源 AI Agent 框架，把 AI 工程所需的基本原语（primitives）直接内置在框架里。正如仓库根目录 README.md 所概括的，Mastra 是「用现代 TypeScript 技术栈构建 AI 应用与 Agent 的框架」，它包含了从早期原型到生产级应用所需的一切，并且可以与 React、Next.js、Node.js 等前端/后端框架集成，也可以作为独立服务部署到任意环境。

Mastra 的五大核心原语

根据本课文档，Mastra 开箱即用地提供了以下五大 AI 工程原语。下面我们逐一展开，并结合仓库源码说明它们在代码库中的真实落点。

1. Agents：带工具、记忆与追踪的智能体

Agent 是 Mastra 的核心抽象。文档明确指出，Mastra 的 Agent 原生支持三类关键能力：

• Tools（工具）：Agent 可以调用外部工具与 API 来扩展自身能力，解决模型本身无法完成的操作（如查询数据库、读写文件、调用第三方服务）；
• Memory（记忆）：Agent 可以记住过去的交互并从中学习，维持对话与任务的连贯性；
• Tracing（追踪）：框架对 Agent 的执行过程进行埋点追踪，让开发者可以观察每次推理的完整链路。

在仓库源码中，Agent 的实现位于 packages/core/src/agent/，入口文件 packages/core/src/agent/index.ts 导出了MessageList、TripWire、Signals、调度（Schedules）、委托 Hook（OnDelegationStartHandler等）以及类型系统，而核心的Agent类定义在 agent.ts。从源码结构还可以看到 Agent 模块还细分出了 durable/（持久化 Agent）、goal/（目标拆解）、fs-routing/（文件系统路由）等子能力，印证了「Agent 是一等公民」的设计取向。

与 Agent 配套的模块还包括：

• packages/core/src/tools/：工具定义与执行；
• packages/core/src/memory/：记忆实现；
• packages/core/src/telemetry/ 与 packages/core/src/observability/：追踪与可观测性。

2. Workflows：基于状态机的工作流

并非所有任务都适合交给模型自由发挥。当需要对执行流程进行显式控制时，Mastra 提供了基于状态机（state-machine）的工作流引擎。README 中对此的表述是：工作流引擎使用直观的.then()、.branch()、.parallel()语法编排多步骤复杂流程，适合需要确定性控制流的场景。

工作流的源码位于 packages/core/src/workflows/，包含 create.ts（创建工作流）、execution-engine.ts（执行引擎）、builder/（构建器）、dynamic/（动态工作流）与 evented/（事件驱动工作流）等实现。仓库还提供了与 Inngest、Temporal 等外部编排系统的集成模块，位于 workflows/inngest/ 与 workflows/temporal/。

更进一步，Mastra 支持Human-in-the-loop（人在回路）：Agent 或工作流可以挂起（suspend）等待用户输入或审批后再继续执行，框架借助存储层记住执行状态，从而实现「随时暂停、原地续跑」。

3. Evals：评测与衡量 AI 输出

AI 应用的可靠性依赖持续的评测。Mastra 内置 Evals 原语，用于跟踪与衡量 AI 输出的质量，帮助开发者度量、迭代和优化模型表现。README 将 evals 与可观测性并称为「生产就绪必备」（production essentials），强调「可靠地发布 Agent 需要持续的洞察、评估与迭代」。

评测相关代码位于 packages/core/src/evals/，而独立的评测工具库位于 packages/evals/。在本课程的项目结构中，src/mastra/scorers/目录专门存放评分器（scorer）文件（见 04-project-structure.md），例如示例项目会生成scorers/weather-scorer.ts。

4. Storage：支撑 RAG 管道的存储

RAG（检索增强生成）管道需要三类基础设施：向量存储（vector store）、嵌入（embeddings）与文档存储。Mastra 通过 Storage 与 Vector 两个原语提供支撑：

• packages/core/src/storage/：存储抽象，负责保存消息、工作流状态、执行快照等结构化数据；
• packages/core/src/vector/：向量存储抽象，用于 RAG 的检索侧。

在仓库中，这两类抽象都有大量具体实现：存储侧覆盖 PostgreSQL（stores/pg/）、LibSQL（stores/libsql/）、MongoDB（stores/mongodb/）、ClickHouse（stores/clickhouse/）等数十种数据库；向量侧覆盖 Pinecone（stores/pinecone/）、Qdrant（stores/qdrant/）、Chroma（stores/chroma/）等主流向量数据库。README 也提到，通过 Retrieval 可以从 API、数据库、文件等数据源拉取内容注入上下文。

5. Local Development Playground：本地开发调试环境

Mastra 内置本地开发 Playground（Mastra Studio），让你在浏览器中与 Agent 交互、测试其能力。根据 05-running-playground.md，运行npm run dev后 Studio 会启动在http://localhost:4111，支持：

• 向 Agent 发送消息并查看响应；
• 查看 Agent 的思考过程；
• 直接测试工具；
• 调试运行中出现的各种问题。

Playground 的前端实现位于 packages/playground/ 与 packages/playground-ui/，后者包含 800 余个 TSX 组件，是 Studio 界面的主要载体。

模块化与可扩展：一个原语丰富的能力矩阵

文档强调，Mastra 的设计目标是模块化（modular）与可扩展（extensible），开发者可以根据需要随时添加新能力。这一点在 packages/core/package.json 的 exports 导出映射中体现得淋漓尽致：@mastra/core通过子路径导出暴露了超过 40 个模块，除上述五大原语外还包括：

这种「核心 + 子路径」的模块化设计意味着：你可以只安装@mastra/core使用最基础的 Agent 能力，也可以按需引入 memory、vector、voice、mcp 等扩展模块，而不必为用不到的能力付费。

与其他生态的互操作性

可扩展性还体现在与既有生态的集成上：

• AI SDK 生态：README 提到可借助 Vercel AI SDK UI、CopilotKit 等 Agent 库构建 Web 界面；仓库中的 client-sdks/ai-sdk/ 与 client-sdks/react/ 即为客户端 SDK；
• MCP 标准：Mastra 既能消费 MCP 工具，也能作为 MCP 服务器把 Agent、工具等结构化资源暴露给任何支持该协议的系统（packages/mcp/）；
• 服务端框架适配：server-adapters/ 提供了 Express、Fastify、Hono、Next.js、NestJS 等主流 Node 框架的适配器，方便把 Agent 嵌入既有后端。

在课程中的定位：通往第一个 Agent 的桥梁

本课（第 02 课）处于「First Agent」课程的承上启下位置：

1. 01-introduction-to-mastra.md 定义了 Agent 的概念与优秀 Agent 的四个特征（记忆、规划、工具、反馈闭环）；
2. 本文（02-what-is-mastra.md）回答「Mastra 是什么」，建立框架的整体心智模型；
3. 后续课程将逐步带你完成环境验证（03-verifying-installation.md，要求 Node.js 18.x+ 并通过npm -y create mastra@latest初始化项目）、认识项目结构（04-project-structure.md）、运行 Studio（05-running-playground.md），以及创建、导出与测试你的第一个 Agent。

需要注意的是，本课程文档对环境的最低要求是 Node.js 18.x 或更高，而当前仓库中@mastra/core的package.json声明的 engines 为>=22.13.0（见 packages/core/package.json），两者以你在课程实操时实际使用的版本要求为准。

小结

Mastra 的本质是一个将 AI 工程原语内置化、模块化、可扩展的 TypeScript 框架：Agent（含工具/记忆/追踪）、状态机工作流、Evals 评测、RAG 存储与本地 Playground 五大原语开箱即用，LLM 路由、MCP、语音、调度等能力则通过@mastra/core的子路径导出按需接入。理解了这份能力地图，你就能在动手写代码前，先在心里为「我的 Agent 需要哪些模块」画好一张架构草图——这正是下一步创建第一个 Agent 之前最有价值的准备。

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra