Mastra框架：构建企业级AI助手与自主代理的TypeScript解决方案

Introduction

Mastra 是一个用于构建复杂 AI 助手和自主代理的 TypeScript 框架。它已被世界上一些大型公司采用，用于驱动内部 AI 自动化工具和面向客户的代理。该框架提供了灵活的部署选项，允许您在本地机器上运行，使用 Hono 将其打包到 Node.js 服务器中，或部署到无服务器云环境。本文将对 Mastra 的核心架构和功能进行深入的技术探讨。

Core Concepts & Architecture

Mastra 围绕几个关键抽象构建，这些抽象共同协作以创建健壮、可扩展的 AI 应用程序。理解这些组件对于高效开发至关重要。

LLM Models & The Vercel AI SDK

其基础是，Mastra 利用 Vercel AI SDK 进行模型路由。这为与几乎所有大型语言模型提供商交互提供了一个统一的接口，包括 OpenAI、Anthropic 和 Google Gemini。开发人员可以选择特定的模型和提供商，并且关键的是，可以决定是否流式传输响应——这是创建响应式用户体验的关键功能。

Agents: The Orchestrators

代理是语言模型选择并执行一系列动作的系统。在 Mastra 中，代理充当中央协调器，为 LLM 提供对工具、工作流和上下文数据的访问。代理可以调用自定义函数、调用第三方集成的 API 以及查询您构建的知识库，从而实现复杂的多步推理和任务执行。

Tools: Typed, Executable Functions

工具是可由代理或在工作流内执行的类型化函数。它们具有内置的集成访问和参数验证功能。每个工具由以下部分定义：

1. 描述其输入的模式。
2. 实现其逻辑的执行函数。
3. 对已配置集成的访问。
   这种结构确保了类型安全，减少了运行时错误，并使工具行为可预测且易于调试。

Workflows: Stateful, Graph-Based Processes

工作流是基于图的持久状态机，代表复杂的多步骤流程。它们是 Mastra 的核心功能，支持：

• 控制流：循环、条件分支以及带重试的错误处理。
• 人在回路：可以暂停并等待人工输入的步骤。
• 可组合性：嵌入其他工作流的能力。
• 可观测性：每个步骤都内置 OpenTelemetry 追踪。
• 灵活开发：可以通过代码或可视化编辑器构建。
  工作流非常适合长时间运行的有状态操作，例如客户入职流程、多阶段数据处理或审批链。

RAG: Building Knowledge for Agents

检索增强生成允许您为代理配备其基础训练之外的专业知识。在 Mastra 中，RAG 被实现为具有特定查询技术的 ETL 管道。该过程通常包括：

1. 分块：将文档分解为可管理的片段。
2. 嵌入：将文本块转换为向量表示。
3. 向量搜索：根据查询高效检索最相关的块。
   这使得代理能够基于专有文档、内部维基或实时数据回答问题。

Integrations: Type-Safe API Clients

Mastra 中的集成是自动生成的、类型安全的第三方服务 API 客户端。这些可以直接用作代理的工具或工作流中的步骤。自动类型生成显著减少了集成样板代码和手动实现 API 客户端可能带来的错误。

Evaluations: Automated LLM Testing

评估是旨在评估 LLM 输出质量的自动化测试。它们结合使用了：

• 基于模型的评分：使用一个 LLM 来给另一个 LLM 的输出打分。
• 基于规则的方法：检查特定的关键词、格式或逻辑。
• 统计方法：分析分布或其他指标。
  每次评估都会返回一个介于 0 和 1 之间的标准化分数，该分数可以被记录并随时间进行比较。它们是完全可定制的，允许您定义自己的提示词和评分函数，以符合特定的业务或质量要求。

Getting Started

Prerequisites

要开始使用 Mastra，请确保您具备以下条件：

• Node.js（版本 20.0 或更高）
• LLM 提供商的 API 密钥

Creating a New Project

npx create-mastra@latest

最简单的方法是使用 create-mastra CLI 工具。它会搭建一个包含所有必要配置的新 Mastra 应用程序脚手架。

Running the Development Server

npm run dev

项目创建后，进入项目目录并启动开发服务器，这将打开 Mastra Playground。

请记住为您选择的 LLM 提供商设置所需的环境变量。

Enhancing Development with MCP

Mastra 提供了一个模型上下文协议服务器，使 AI 助手能够直接访问完整的 Mastra.ai 知识库。这对于在开发过程中获取上下文帮助非常宝贵。

Configuration for Cursor

macOS/Linux:

{
  "mcpServers": {
    "mastra": {
      "command": "npx",
      "args": ["-y", "@mastra/mcp-docs-server"]
    }
  }
}

Windows:

{
  "mcpServers": {
    "mastra": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@mastra/mcp-docs-server"]
    }
  }
}

要在 Cursor 中启用它，请在项目根目录中创建或更新 .cursor/mcp.json 文件。

配置后，您必须通过 设置 -> MCP 设置 在 Cursor 中手动启用该服务器。

Community & Contribution

Mastra 是一个欢迎贡献的开源项目。无论您对编码、测试还是定义功能规范感兴趣，都可以参与进来。鼓励开发人员在提交拉取请求之前先开一个 issue 进行讨论。项目设置详情可在开发文档中找到。

如需支持，请加入开放的社区 Discord。要负责任地报告安全漏洞，请联系 security@mastra.ai。

Conclusion

Mastra 提出了一个引人注目、可用于企业环境的框架，用于构建下一代 AI 应用程序。它通过结合统一的 LLM 接口、强大的代理模式、有状态的工作流以及用于知识集成和评估的健壮工具，解决了许多生产 AI 系统中固有的复杂性。其对 TypeScript 的使用确保了开发人员的熟悉度和类型安全，而 MCP 服务器等功能则增强了开发体验。对于希望超越简单聊天界面，创建动态、自主且具备知识感知能力的 AI 代理的团队来说，Mastra 提供了一条结构化且可扩展的前进道路。