Mastra

一、Mastra 平台包含哪些产品组件？各自的功能是什么？

1. Mastra 框架（Framework）

Mastra 框架是核心开源产品，提供构建 AI 应用所需的全部基础能力，包括 Agents、Workflows、Memory、工具定义、模型路由和可观测性。开发者通过 npm 安装 @mastra/core 包，可在本地完成从原型到生产的全部开发工作。框架采用 Apache 2.0 协议，允许商业使用。

2. Mastra Studio

Studio 是一个可视化的开发和调试环境，支持在不修改代码的情况下编辑 Agent 提示词、切换工具、配置显示条件、保存版本、对比差异和回滚。Studio 同时提供本地运行（mastra studio）和云端部署两种模式，云端版本支持团队共享和基于角色的访问控制。

3. Mastra Server

Server 用于将 Agents 和 Workflows 部署为生产级 API。它自动暴露 REST 端点，生成 OpenAPI 文档和 Swagger UI，并默认从流式响应中脱敏系统提示词、工具定义和 API 密钥。支持通过 CLI（mastra server deploy）或 CI/CD 流水线部署。

4. Memory Gateway

Memory Gateway 是独立的记忆服务，将 Mastra 的 Observational Memory 能力以 API 形式提供给外部系统使用。它支持 Python、TypeScript 或任何框架，只需将 LLM 调用指向网关即可获得持久化记忆能力。Memory Gateway 有独立的定价体系。

二、Mastra 中的 Agent 是如何定义和工作的？

1. Agent 的定义方式

在 Mastra 中，Agent 是一个将模型、指令、工具集和运行时行为整合到单一对象中的类型化定义。开发者通过 Agent 类创建实例，配置 id、name、instructions（系统提示词）、model（模型标识）和 tools（工具集）等属性。所有配置都支持 TypeScript 类型推断和 IDE 自动补全。

2. Agent 的工作机制

Mastra Agent 采用 ReAct（Reasoning + Acting）模式工作。Agent 接收用户输入后，模型会自主决定是直接回复还是调用工具。如果需要调用工具，Agent 执行工具调用并将结果反馈给模型，模型继续推理，如此循环直到模型输出最终答案或达到预设的停止条件。整个过程在 TypeScript 中原生运行，无需额外的编排层。

3. 工具（Tools）的类型安全

Mastra 使用 Zod schema 定义工具的输入和输出结构。每个工具通过 createTool 函数创建，包含 id、description、inputSchema（输入校验规则）、outputSchema（输出结构）和 execute（执行函数）。这种设计确保模型的工具调用与运行时逻辑严格对齐，实现端到端的类型安全。

三、Mastra 的工作流（Workflow）引擎有什么特点？

1. 图结构编排

Mastra 的 Workflow 引擎采用图结构编排多步骤流程。开发者通过链式语法定义执行路径：.then() 用于顺序执行、.branch() 用于条件分支、.parallel() 用于并行执行。每个步骤可以是 Agent 调用、工具执行或确定性代码，混合使用灵活度高。

2. 人类介入（Human-in-the-Loop）

Workflow 支持在任意步骤挂起执行并等待用户输入或审批。挂起时，工作流的完整状态会被序列化并持久化到存储中，恢复时从挂起点精确继续。这一机制适用于需要人工审核的场景，如内容审批、敏感操作确认等。

3. 确定性执行

与 Agent 的自主决策不同，Workflow 遵循预定义的确定性路径。无论模型如何推理，步骤的执行顺序和分支逻辑都由代码显式控制，确保结果可预测、可审计。这使得 Workflow 适合业务流程自动化等对一致性要求较高的场景。

四、Mastra 的 Workflows 与 Agents 有什么区别？

1. 决策权归属

Agent 的决策权在模型：模型根据当前上下文自主判断下一步行动，包括是否调用工具、调用哪个工具、何时停止。Workflow 的决策权在开发者：执行路径完全由代码定义，模型只在需要生成内容的步骤中发挥作用。

2. 适用场景

Agent 适合路径不确定的开放式任务，如客服对话、研究助手、代码生成等需要灵活应对各种输入的场景。Workflow 适合流程固定的结构化任务，如订单处理、数据管道、审批流程等需要严格控制执行顺序和可审计性的场景。

3. 状态管理

Agent 的状态主要是对话历史和记忆系统维护的上下文。Workflow 的状态是整个执行图的快照，包括每个步骤的输入输出、当前执行位置、挂起原因等，支持更细粒度的状态恢复和时间旅行调试。

五、Mastra 的 TypeScript 原生设计有什么优势？

1. 统一技术栈

Mastra 专为 TypeScript 设计，Agent、Workflow、工具、记忆和可观测性都在同一语言表面下完成。TypeScript 开发者无需跨越 Python/JavaScript 边界，可以在 React、Next.js、Node.js 等现有项目中直接嵌入 Mastra，避免了多语言项目的集成成本。

2. 类型安全

借助 TypeScript 和 Zod schema，Mastra 提供从工具定义到 Agent 输出的端到端类型推断。模型的工具调用参数、返回值结构都在编译期校验，减少了运行时错误。这与 Python 优先的框架（如 LangChain）形成对比，后者在 JavaScript 环境中需要额外的类型适配层。

3. 生态系统集成

Mastra 原生支持与 Node.js 生态的主流框架集成，包括 Next.js、React、Express、Hono、Fastify、Koa 等。它提供 Server Adapters 自动注册端点，也支持作为独立服务器运行。部署目标覆盖 Vercel、Netlify、Cloudflare Workers 等边缘平台。

六、Mastra 的内存管理系统包含哪些层次？

1. 对话历史（Thread History）

最基础的记忆层，维护当前会话的最近对话轮次。它为 Agent 提供即时上下文，确保多轮对话的连贯性。对话历史可以持久化到存储中，支持跨会话恢复。

2. 观察记忆（Observational Memory）

Mastra 的旗舰记忆系统，通过后台 Agent 将对话历史压缩为密集的观察日志。它不依赖向量数据库或图数据库，而是使用纯文本格式存储，在 LongMemEval 基准测试中达到 94.87%（gpt-5-mini）的准确率。观察记忆支持稳定的上下文窗口，可利用提示词缓存降低 token 成本。

3. 语义回忆（Semantic Recall）

基于向量嵌入的检索层，从过去的交互中检索语义相关的内容。它适用于需要跨大量历史数据查找特定信息的场景，如知识库问答、历史对话检索等。语义回忆可以与观察记忆结合使用，为 Agent 提供更完整的上下文。

七、Mastra 的 Observational Memory 记忆系统是如何工作的？

1. 双 Agent 压缩架构

Observational Memory 由两个后台 Agent 组成：Observer（观察者）和 Reflector（反思者）。Observer 持续监控对话，当未观察的消息累积到 30,000 token（默认阈值，可配置）时，将原始消息压缩为新的观察条目。Reflector 负责管理观察日志的生命周期，当观察条目累积到 40,000 token 时，合并相关条目、删除过时信息。

2. 日志格式与优先级

观察条目采用纯文本日志格式，而非结构化对象。每条观察包含日期、时间戳和内容，使用 emoji 标记优先级：红色圆圈（重要）、黄色圆圈（可能重要）、绿色圆圈（仅供参考）。这种设计让语言模型能够高效识别信息权重，同时保持人类可读性。

3. 稳定上下文窗口

系统将上下文窗口分为两个区块：前部是观察日志，后部是原始消息历史。新消息追加到后部，直到达到阈值触发压缩。由于观察区块是追加式的，系统提示词和已有观察形成一致的前缀，可以利用 Anthropic、OpenAI 等提供商的提示词缓存机制，将 token 成本降低 4～10 倍。

4. 性能表现

在 LongMemEval 基准测试中，Observational Memory 使用 gpt-5-mini 达到 94.87% 准确率，是公开记录的最高分；使用 gpt-4o 达到 84.23%，超过官方 oracle 配置（仅提供包含答案的对话）2 个百分点。对于工具密集型任务，压缩比可达 5～40 倍。

八、Mastra 的模型路由（Model Routing）机制是怎样的？

1. 统一接口

Mastra 通过统一的模型路由层连接 300+ 个模型，覆盖 OpenAI、Anthropic、Google Gemini、DeepSeek、Groq、Mistral、Llama、Ollama 等主流提供商。开发者使用 provider/model 格式指定模型（如 openai/gpt-5.6、anthropic/claude-sonnet-4-6），无需关心底层提供商的具体 API 差异。

2. 自动回退与切换

模型路由支持自动回退机制：当主模型不可用（如配额耗尽、服务中断）时，自动切换到备选模型。开发者也可以通过修改模型标识字符串来切换提供商，无需重构代码。这种设计为生产环境提供了更高的可用性保障。

3. AI SDK 集成

Mastra 基于 Vercel AI SDK 构建模型抽象层，支持 AI SDK v6 和 v7 的 LanguageModelV3/V4 模型格式。这意味着 Mastra 可以复用 AI SDK 生态的模型绑定和流式传输能力，同时在其上提供更高层的 Agent 和 Workflow 抽象。

九、Mastra 如何实现对 MCP Server 的支持？

1. MCP Server 编写

Mastra 支持编写 Model Context Protocol（MCP）服务器，将 Agents、工具和其他结构化资源通过 MCP 接口暴露出来。开发者可以将 Mastra 的 Agent 或工具封装为 MCP 资源，供任何支持 MCP 协议的客户端或 Agent 消费。

2. MCP 资源类型

通过 MCP 接口，Mastra 可以暴露多种类型的资源：Agent 端点（允许外部系统调用 Agent 能力）、工具函数（允许外部 Agent 调用 Mastra 定义的工具）、结构化数据（如知识库、配置信息等）。这使 Mastra 成为跨系统工具共享的桥梁。

3. 生态互操作

Mastra 编写的 MCP Server 可以与 Claude Desktop、Cursor、Windsurf 等支持 MCP 的应用无缝集成。同时，Mastra 的 Agent 也可以作为 MCP 客户端消费外部 MCP Server 提供的工具，实现双向互操作。

十、Mastra 的 Composite Storage 存储架构是怎样的？

1. 按域分离存储

Mastra 1.0 引入的 Composite Storage 允许为不同功能域配置独立的存储后端，取代了早期版本中单一存储的模式。开发者可以为 memory（记忆）、workflows（工作流）、scores（评估）等不同域指定最适合的数据库，如 Postgres、LibSQL、ClickHouse、MongoDB 等。

2. 存储适配器

Mastra 提供多种官方存储适配器，包括 @mastra/pg（PostgreSQL）、@mastra/libsql（LibSQL/SQLite）、@mastra/mongo（MongoDB）等。每个适配器实现统一的存储接口，Composite Storage 通过 MastraCompositeStore 类管理多个适配器的协作。

3. 生产环境优化

Composite Storage 支持按表设置保留策略（retention: { maxAge }）和多租户隔离（organizationId/projectId 作用域）。它还提供了安全、批量化、可恢复的 storage.prune() 方法用于数据清理。这种架构让成本、延迟和扩展性的权衡可以精确到具体功能域。

十一、Mastra 的 Guardrails 安全机制如何防止提示词注入？

1. 输入处理

Mastra 提供输入护栏（Input Guardrails），在用户输入到达 Agent 之前进行处理。它可以检测并过滤潜在的提示词注入攻击，如试图覆盖系统指令、泄露敏感信息或执行非预期操作的输入。处理后的输入才会进入 Agent 的推理流程。

2. 输出处理

输出护栏（Output Guardrails）在 Agent 生成响应后进行校验和清理。它可以防止 Agent 泄露系统提示词、工具定义或内部配置，也可以对输出内容进行格式校验、敏感信息脱敏等处理，确保返回给用户的内容安全可控。

3. 集成方式

Guardrails 作为 Agent 配置的一部分，与 Agent 的生命周期紧密集成。开发者可以自定义护栏规则，也可以使用 Mastra 提供的默认规则。护栏的执行结果会影响 Agent 的响应，例如拒绝处理恶意输入或替换不安全的输出内容。

十二、Mastra 的 Workflow 如何实现状态持久化和恢复？

1. 状态序列化

当 Workflow 执行到挂起点或需要持久化时，Mastra 会将整个执行图的完整状态序列化为结构化数据，包括每个步骤的输入输出、当前执行位置、分支决策结果、挂起原因等。序列化后的状态存储到配置的存储后端中。

2. 断点恢复

恢复执行时，Mastra 从存储中加载序列化的状态，精确还原到挂起时的执行位置。Workflow 从该位置继续执行，无需重跑之前的步骤。这一机制支持长时间运行的工作流，可以挂起数小时、数天甚至数周后恢复。

3. 时间旅行调试

借助持久化的状态历史，Mastra Studio 支持时间旅行调试：开发者可以查看 Workflow 在任意历史步骤的状态快照，分析每个步骤的输入输出，定位问题根源。这对于生产环境的故障排查和流程优化非常有价值。

十三、Mastra 提供了哪些部署方式和集成选项？

1. 独立服务器

Mastra 可以作为独立 Node.js 服务器运行，通过 mastra start 命令启动。它内置 Hono 作为 HTTP 服务器，自动注册所有 Agent、Workflow 和 MCP 端点。这种方式适合将 Mastra 作为独立的微服务部署。

2. Server Adapters

Mastra 1.0 引入的 Server Adapters 允许将 Mastra 集成到现有的 Web 框架中。官方提供 @mastra/express、@mastra/hono、@mastra/fastify、@mastra/koa 等适配器包。开发者只需传入现有的应用实例和 Mastra 实例，所有端点就会自动注册到现有路由中。

3. 全栈框架集成

对于 Next.js 等全栈框架，Mastra 支持通过 mastra build 构建独立输出，然后部署到 Vercel、Netlify、Cloudflare Workers 等边缘平台。它也可以直接集成到 Next.js 应用中，作为应用的一部分运行。

4. Mastra Cloud

Mastra 提供托管云服务（Mastra Platform），支持一键部署到生产环境。云服务包含 Studio 云端版、Server 托管和 Memory Gateway，提供域名 URL、环境变量管理、托管存储和可观测性仪表板。平台有免费的 Starter 层级，Teams 层级为每团队每月 250 美元。

十四、Mastra 在生产环境中如何保证 Agent 的性能和稳定性？

1. 内置可观测性

Mastra 提供完整的可观测性能力，包括 Traces（追踪每次模型调用、工具执行和工作流步骤）、Metrics（跟踪延迟、成本、模型调用次数和工具使用量）、Datasets（捕获追踪数据和用户反馈用于重复评估）和 Evals（使用模型评分、规则评分和统计方法评估 Agent 输出）。这些能力帮助团队在生产环境中持续监控和优化 Agent 表现。

2. 评估驱动开发

Mastra 的 Evals 系统支持在代码变更进入生产之前，对 Agent 运行结果进行可重复的检查。开发者可以定义自定义评估标准，将测试用例组织为数据集，在新版本发布前回放评估并对比结果。这种机制确保 Agent 质量的稳定性。

3. 企业级部署

Mastra 支持部署到任何 Node.js 兼容环境，包括容器化部署（Docker、Kubernetes）和 Serverless 平台。它提供 Serverless 适配器（Vercel、Netlify、Cloudflare Workers），支持自动扩缩容。对于企业级需求，Mastra Enterprise 版本支持本地部署、VPC 部署、RBAC、SSO 和审计日志。

十五、Mastra 与 LangChain 的主要区别是什么？

1. 语言定位

Mastra 是 TypeScript 原生框架，专为 JavaScript/TypeScript 开发者设计，与 React、Next.js、Node.js 等生态深度集成。LangChain 是 Python 优先的框架，虽然提供 LangChain.js 版本，但核心功能和社区资源仍以 Python 为主。

2. 设计理念

Mastra 采用"开箱即用"（batteries-included）的设计理念，将 Agent、Workflow、Memory、可观测性等能力整合在单一包中，开发者无需额外选择记忆策略或组装多个库。LangChain 采用模块化设计，提供大量可组合的组件，但需要开发者自行选择和集成记忆、追踪等功能。

3. 工作流与状态管理

Mastra 的 Workflow 内置状态持久化和恢复机制，默认即可实现断点续执行。LangChain 需要通过 LangGraph 实现类似功能，LangGraph 提供更强大的图结构编排能力，但配置复杂度更高。

4. 记忆系统

Mastra 内置 Observational Memory，默认启用自动压缩和持久化。LangChain 提供多种记忆类供选择，但需要开发者显式配置，不自动启用长期记忆。

十六、Mastra 与 Vercel AI SDK 相比有什么优劣势？

1. 定位差异

Vercel AI SDK 是底层的模型交互工具包，专注于流式传输、模型抽象和工具调用等基础能力。Mastra 是更高层的框架，在 AI SDK 之上提供 Agent、Workflow、Memory 和可观测性等完整的应用级抽象。两者可以组合使用：AI SDK 作为基础层，Mastra 作为应用层。

2. Mastra 的优势

Mastra 提供了 Vercel AI SDK 不具备的完整应用级能力：持久化工作流（支持挂起和恢复）、内置记忆系统（Observational Memory）、可视化开发环境（Studio）、评估系统（Evals）和 Guardrails 安全机制。对于需要构建复杂 AI 应用的团队，Mastra 可以显著减少从零搭建的时间。

3. Vercel AI SDK 的优势

Vercel AI SDK 更轻量、更灵活，适合构建流式聊天界面和需要精细控制模型交互的场景。它的学习曲线更平缓，与 Next.js 的集成更加紧密。对于简单的 Agent 应用或不需要工作流编排的场景，直接使用 AI SDK 可能更合适。

4. 组合使用

在实践中，许多 TypeScript 团队采用组合方案：使用 Vercel AI SDK 处理模型路由和流式传输，使用 Mastra 处理 Agent 编排、工作流和记忆管理。这种分层架构兼顾了底层的灵活性和上层的功能完整性。