Mastra 深度解析：TypeScript 原生 AI Agent 框架——从单智能体到企业级多 Agent 编排的完整实战指南

引言：TypeScript 生态的 AI Agent 缺位

2026年，AI Agent 框架大战已经进入白热化阶段。Python 生态有 LangChain、CrewAI、AutoGPT 等老牌选手，Go 生态有字节跳动开源的 Eino 框架填补空白。但 TypeScript/JavaScript 生态——这个拥有全球最多开发者的语言社区——长期以来却没有一个真正能打的原生 AI Agent 框架。

Vercel AI SDK 虽好，但定位是"AI SDK"而非"Agent 框架"，更侧重模型调用和流式输出，缺少 Agent 编排、工作流引擎、多 Agent 协作等核心能力。LangChain.js 则是从 Python 版本移植而来，TypeScript 开发者用起来总觉得"差点意思"——类型推断不完整、API 设计带着 Python 味、生态割裂。

Mastra 的出现，彻底改变了这个局面。

Mastra 是一个 TypeScript-first 的 AI Agent 框架，由一支深耕开发者工具的团队打造。它不是从 Python 移植过来的"翻译版"，而是从第一行代码开始就为 TypeScript 生态设计的原生框架。截至目前，Mastra 在 GitHub 上已有超过 16,000 次提交，被 Replit、Fireworks、Medusa、SoftBank、Sanity、Factorial 等知名企业用于生产环境。

本文将从架构设计、核心模块、代码实战、性能优化等多个维度，深度解析 Mastra 框架的技术细节，帮助你全面理解这个正在重新定义 TypeScript AI Agent 开发体验的项目。

一、为什么 TypeScript 需要自己的 Agent 框架？

1.1 语言特性决定了框架设计

TypeScript 和 Python 在类型系统、模块系统、异步模型上有本质差异。Python 的鸭子类型和动态特性让 LangChain 可以用大量的运行时魔法来实现灵活性，但这种设计移植到 TypeScript 后会带来严重的类型安全问题。

举个简单的例子：在 LangChain.js 中，Tool 的定义往往是这样的：

// LangChain.js 的 Tool 定义 —— 类型推断有限
const tool = new DynamicTool({
  name: "search",
  description: "Search the web",
  func: async (input: string) => { ... }
});

而在 Mastra 中，Tool 的定义利用了 Zod schema 的完整类型推断：

// Mastra 的 Tool 定义 —— 完整类型安全
const searchTool = createTool({
  id: 'web-search',
  description: 'Search the web for information',
  inputSchema: z.object({
    query: z.string().describe('Search query'),
    maxResults: z.number().optional().default(10),
  }),
  outputSchema: z.object({
    results: z.array(z.object({
      title: z.string(),
      url: z.string().url(),
      snippet: z.string(),
    })),
  }),
  execute: async ({ query, maxResults }) => {
    // input 的类型是 { query: string; maxResults: number }
    // 完整的类型推断，IDE 自动补全
    const results = await searchWeb(query, maxResults);
    return { results };
  },
});

这个差异看似微小，但在大型项目中，完整的类型推断意味着更少的运行时错误、更好的 IDE 支持、更顺畅的重构体验。

1.2 全栈 TypeScript 的天然优势

现代 Web 开发的主流技术栈——Next.js、React、Astro、SvelteKit——全部基于 TypeScript。当你的前端和后端使用同一种语言时，AI Agent 可以直接嵌入到现有的 Web 应用中，而不需要额外的 Python 服务。

Mastra 深谙这一点，它提供了与主流框架的无缝集成：

• Next.js：通过 Route Handlers 直接暴露 Agent API
• React：配合 useChat/useCompletion hooks 实现流式 UI
• Astro：作为 Astro Actions 的后端
• Express/Hono：作为中间件集成
• SvelteKit：通过 server routes 集成

这种"零摩擦"的集成体验，是 Python 框架无法提供的。

1.3 Edge Runtime 的天然适配

TypeScript 生态有一个 Python 生态不具备的独特优势：Edge Runtime。Cloudflare Workers、Vercel Edge Functions、Deno Deploy 等边缘计算平台都原生支持 TypeScript，但对 Python 的支持极其有限。

Mastra 的设计天然适配 Edge Runtime。它的核心模块（Agent、Workflow、Tool）不依赖 Node.js 特有的 API，可以在任何支持 Web Standard API 的环境中运行。这意味着你可以把 AI Agent 部署到离用户最近的边缘节点，实现毫秒级响应。

二、架构设计：六大核心模块

Mastra 的架构由六个核心模块组成，每个模块都可以独立使用，也可以组合在一起构建复杂的 AI 应用。

2.1 Agent 模块：智能体的"大脑"

Agent 是 Mastra 的核心抽象。每个 Agent 由以下部分组成：

• Instructions（指令）：定义 Agent 的行为模式和能力边界
• Model（模型）：通过 Model Router 选择底层 LLM
• Tools（工具）：Agent 可以调用的外部能力
• Memory（记忆）：跨会话的上下文持久化
• Voice（语音）：可选的 TTS/STS 能力

import { Agent } from '@mastra/core/agent'

const codeReviewAgent = new Agent({
  id: 'code-reviewer',
  name: 'Code Review Agent',
  instructions: `
    你是一个专业的代码审查助手。
    当收到代码时，你需要：
    1. 分析代码结构和设计模式
    2. 识别潜在的 bug 和安全漏洞
    3. 评估性能影响
    4. 给出具体的改进建议
    
    使用 markdown 格式输出审查结果。
  `,
  model: 'anthropic/claude-sonnet-4-6',
  tools: { searchTool, fileReadTool },
})

Model Router 是 Mastra 的一个亮点设计。你不需要手动实例化 OpenAI、Anthropic、Google 等不同 provider 的客户端，只需要用 provider/model 格式的字符串，Mastra 会自动查找对应的环境变量并创建客户端。这大大简化了多模型切换的复杂度。

2.2 Workflow 模块：确定性编排引擎

Agent 适合处理开放性任务，但很多业务场景需要确定性的流程控制。Workflow 模块就是为此设计的。

Workflow 的核心概念是 Step（步骤）。每个 Step 有明确的输入输出 schema，通过 .then() 链式组合，形成有向无环图（DAG）。

import { createWorkflow, createStep } from '@mastra/core/workflows'
import { z } from 'zod'

// Step 1: 代码分析
const analyzeStep = createStep({
  id: 'analyze-code',
  inputSchema: z.object({
    code: z.string(),
    language: z.string(),
  }),
  outputSchema: z.object({
    issues: z.array(z.object({
      type: z.enum(['bug', 'security', 'performance', 'style']),
      severity: z.enum(['low', 'medium', 'high', 'critical']),
      line: z.number(),
      message: z.string(),
    })),
    score: z.number().min(0).max(100),
  }),
  execute: async ({ inputData }) => {
    const { code, language } = inputData
    // 调用 LLM 进行代码分析
    const analysis = await llm.analyze(code, language)
    return analysis
  },
})

// Step 2: 生成报告
const reportStep = createStep({
  id: 'generate-report',
  inputSchema: z.object({
    issues: z.array(z.object({
      type: z.enum(['bug', 'security', 'performance', 'style']),
      severity: z.enum(['low', 'medium', 'high', 'critical']),
      line: z.number(),
      message: z.string(),
    })),
    score: z.number(),
  }),
  outputSchema: z.object({
    report: z.string(),
    summary: z.object({
      totalIssues: z.number(),
      criticalCount: z.number(),
      recommendation: z.string(),
    }),
  }),
  execute: async ({ inputData }) => {
    const { issues, score } = inputData
    // 生成结构化报告
    return generateReport(issues, score)
  },
})

// 组合工作流
const codeReviewWorkflow = createWorkflow({
  id: 'code-review-workflow',
  inputSchema: z.object({
    code: z.string(),
    language: z.string(),
  }),
  outputSchema: z.object({
    report: z.string(),
    summary: z.object({
      totalIssues: z.number(),
      criticalCount: z.number(),
      recommendation: z.string(),
    }),
  }),
})
  .then(analyzeStep)
  .then(reportStep)
  .commit()

Workflow 支持多种控制流模式：

• 串行（.then()）：步骤按顺序执行
• 并行（.parallel()）：多个步骤同时执行
• 条件分支（.branch()）：根据条件选择不同路径
• 循环（.foreach()）：对数组中的每个元素执行步骤
• 挂起/恢复（suspend/resume）：支持 Human-in-the-Loop

2.3 RAG 模块：知识增强

RAG（Retrieval-Augmented Generation）是让 AI Agent 基于私有数据回答问题的关键技术。Mastra 的 RAG 模块提供了完整的文档处理流水线：

import { MDocument } from '@mastra/rag'
import { PgVector } from '@mastra/pg'

// 1. 文档加载和分块
const doc = MDocument.fromText(yourDocumentText)
const chunks = await doc.chunk({
  strategy: 'recursive',  // 递归分块策略
  size: 512,              // 每块 512 tokens
  overlap: 50,            // 50 tokens 重叠
})

// 2. 生成嵌入向量
const { embeddings } = await embedMany({
  values: chunks.map(chunk => chunk.text),
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
})

// 3. 存储到向量数据库
const pgVector = new PgVector({
  id: 'pg-vector',
  connectionString: process.env.POSTGRES_CONNECTION_STRING,
})
await pgVector.upsert({
  indexName: 'knowledge-base',
  vectors: embeddings,
  metadata: chunks.map(chunk => ({ text: chunk.text })),
})

// 4. 查询时检索相关上下文
const queryEmbedding = await embed({
  value: userQuery,
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
})
const results = await pgVector.query({
  indexName: 'knowledge-base',
  queryVector: queryEmbedding,
  topK: 5,
})

Mastra 支持多种向量数据库后端：PostgreSQL (pgvector)、Pinecone、Qdrant、MongoDB Atlas。你可以根据自己的基础设施选择最合适的方案。

2.4 Voice 模块：语音交互

Voice 模块是 Mastra 的差异化能力之一。它提供了统一的语音接口，支持 TTS（文本转语音）、STT（语音转文本）和 STS（语音到语音）三种模式，并且支持 8 个语音 provider：OpenAI、Azure、ElevenLabs、PlayAI、Google、Cloudflare、Deepgram、Inworld。

import { Agent } from '@mastra/core/agent'
import { ElevenLabsVoice } from '@mastra/voice-elevenlabs'

const voiceAgent = new Agent({
  id: 'voice-assistant',
  name: 'Voice Assistant',
  instructions: '你是一个语音助手，用简洁自然的语言回答问题。',
  model: 'openai/gpt-5.5',
  voice: new ElevenLabsVoice({
    apiKey: process.env.ELEVENLABS_API_KEY,
  }),
})

// 文本转语音
const { text } = await voiceAgent.generate('今天天气怎么样？')
const audioStream = await voiceAgent.voice.speak(text, {
  speaker: 'rachel',
  responseFormat: 'mp3',
})

// 语音转文本
const transcription = await voiceAgent.voice.listen(audioBuffer)

2.5 Memory 模块：跨会话记忆

Memory 模块让 Agent 能够在多个对话之间保持上下文。它支持两种记忆模式：

• 短期记忆（Working Memory）：当前会话的上下文窗口
• 长期记忆（Long-term Memory）：跨会话的持久化存储

import { Agent } from '@mastra/core/agent'
import { Memory } from '@mastra/memory'

const memory = new Memory({
  storage: 'postgresql',  // 使用 PostgreSQL 存储
  vectorStore: 'pgvector', // 使用 pgvector 进行语义检索
})

const agent = new Agent({
  id: 'personal-assistant',
  name: 'Personal Assistant',
  instructions: '你是一个个人助理，记住用户的偏好和历史对话。',
  model: 'openai/gpt-5.5',
  memory,
})

// 第一次对话
const response1 = await agent.generate('我叫张三，我喜欢Python', {
  threadId: 'user-zhang-san',
})

// 后续对话 —— Agent 会记住之前的上下文
const response2 = await agent.generate('推荐一个适合我的编程语言学习路线', {
  threadId: 'user-zhang-san',
})
// Agent 会基于之前的对话，推荐以 Python 为核心的学习路线

2.6 Channels 模块：多平台接入

Channels 模块让 Agent 可以直接接入 Slack、Discord、Telegram 等消息平台，无需额外的适配层。

import { Agent } from '@mastra/core/agent'
import { SlackChannel } from '@mastra/channel-slack'

const agent = new Agent({
  id: 'team-assistant',
  name: 'Team Assistant',
  instructions: '你是一个团队助手，帮助团队成员解答问题。',
  model: 'anthropic/claude-sonnet-4-6',
  channels: [
    new SlackChannel({
      token: process.env.SLACK_BOT_TOKEN,
      signingSecret: process.env.SLACK_SIGNING_SECRET,
    }),
  ],
})

三、实战：从零构建一个生产级 AI Agent 系统

让我们通过一个完整的实战案例，展示如何用 Mastra 构建一个企业级的客服 Agent 系统。

3.1 项目初始化

npm create mastra@latest
# 选择模板：Agent with RAG
# 选择模型 provider：OpenAI + Anthropic
# 选择向量数据库：PostgreSQL

3.2 定义工具集

// src/mastra/tools/order-tool.ts
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const queryOrderTool = createTool({
  id: 'query-order',
  description: '查询订单状态和详情',
  inputSchema: z.object({
    orderId: z.string().describe('订单号'),
    userId: z.string().describe('用户ID'),
  }),
  outputSchema: z.object({
    order: z.object({
      id: z.string(),
      status: z.enum(['pending', 'paid', 'shipped', 'delivered', 'cancelled']),
      items: z.array(z.object({
        name: z.string(),
        quantity: z.number(),
        price: z.number(),
      })),
      totalAmount: z.number(),
      createdAt: z.string(),
      estimatedDelivery: z.string().optional(),
    }).nullable(),
    error: z.string().optional(),
  }),
  execute: async ({ orderId, userId }) => {
    try {
      const order = await orderService.getOrder(orderId, userId)
      if (!order) {
        return { order: null, error: '订单不存在或无权访问' }
      }
      return { order, error: undefined }
    } catch (err) {
      return { order: null, error: `查询失败: ${err.message}` }
    }
  },
})

export const refundTool = createTool({
  id: 'request-refund',
  description: '发起退款申请',
  inputSchema: z.object({
    orderId: z.string(),
    userId: z.string(),
    reason: z.string().describe('退款原因'),
    amount: z.number().optional().describe('退款金额，不填则全额退款'),
  }),
  outputSchema: z.object({
    refundId: z.string().optional(),
    status: z.enum(['approved', 'pending', 'rejected']),
    message: z.string(),
  }),
  execute: async ({ orderId, userId, reason, amount }) => {
    const result = await refundService.createRefund({
      orderId, userId, reason, amount,
    })
    return result
  },
})

// src/mastra/tools/knowledge-tool.ts
export const searchKnowledgeTool = createTool({
  id: 'search-knowledge',
  description: '搜索产品文档和FAQ',
  inputSchema: z.object({
    query: z.string().describe('搜索关键词'),
    category: z.enum(['product', 'shipping', 'payment', 'return', 'general'])
      .optional()
      .describe('文档分类'),
  }),
  outputSchema: z.object({
    results: z.array(z.object({
      title: z.string(),
      content: z.string(),
      relevance: z.number(),
    })),
  }),
  execute: async ({ query, category }) => {
    const filter = category ? { category } : undefined
    const results = await knowledgeBase.search(query, filter)
    return { results }
  },
})

3.3 构建多 Agent 系统

// src/mastra/agents/triage-agent.ts
import { Agent } from '@mastra/core/agent'

export const triageAgent = new Agent({
  id: 'triage-agent',
  name: '客服分流Agent',
  instructions: `
    你是客服系统的分流Agent。你的职责是：
    1. 理解用户的问题类型
    2. 将问题路由到合适的专业Agent
    3. 对于简单问题，直接回答
    
    路由规则：
    - 订单相关问题 → 转给 orderAgent
    - 产品咨询 → 转给 productAgent
    - 投诉建议 → 转给 complaintAgent
    - 简单FAQ → 直接用知识库回答
  `,
  model: 'openai/gpt-5-mini', // 分流用轻量模型，降低成本
  tools: { searchKnowledgeTool },
})

// src/mastra/agents/order-agent.ts
export const orderAgent = new Agent({
  id: 'order-agent',
  name: '订单服务Agent',
  instructions: `
    你是订单服务专家Agent。你可以：
    1. 查询订单状态和物流信息
    2. 处理退款申请
    3. 解答订单相关问题
    
    注意事项：
    - 涉及退款时，金额超过500元需要人工审批
    - 物流问题需要先查询订单状态再给出建议
    - 保持专业、友好的态度
  `,
  model: 'anthropic/claude-sonnet-4-6',
  tools: { queryOrderTool, refundTool, searchKnowledgeTool },
})

// src/mastra/agents/supervisor-agent.ts
export const supervisorAgent = new Agent({
  id: 'supervisor-agent',
  name: '客服主管Agent',
  instructions: `
    你是客服系统的主管Agent，负责协调其他Agent的工作。
    当专业Agent无法解决问题时，由你进行最终决策。
    你也可以在必要时将问题升级给人工客服。
  `,
  model: 'anthropic/claude-opus-4-7',
  tools: { searchKnowledgeTool },
  subAgents: [triageAgent, orderAgent],
})

3.4 注册和部署

// src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { PgVector } from '@mastra/pg'

export const mastra = new Mastra({
  agents: { triageAgent, orderAgent, supervisorAgent },
  workflows: { customerServiceWorkflow },
  vectors: {
    pg: new PgVector({
      connectionString: process.env.POSTGRES_CONNECTION_STRING,
    }),
  },
  logger: true, // 启用内置日志
  telemetry: true, // 启用 OpenTelemetry 追踪
})

// API Route (Next.js)
// app/api/chat/route.ts
export async function POST(req: Request) {
  const { message, threadId } = await req.json()
  
  const agent = mastra.getAgentById('triage-agent')
  const stream = await agent.stream(message, { threadId })
  
  return new Response(stream.toDataStream())
}

四、与竞品框架的深度对比

4.1 Mastra vs LangChain.js

4.2 Mastra vs Vercel AI SDK

4.3 Mastra vs Google ADK

五、性能优化与生产实践

5.1 模型选择策略

在实际生产中，不同环节应使用不同级别的模型：

// 轻量任务用小模型，复杂任务用大模型
const triageAgent = new Agent({
  model: 'openai/gpt-5-mini',      // 分流：便宜、快
})

const orderAgent = new Agent({
  model: 'anthropic/claude-sonnet-4-6',  // 订单处理：平衡
})

const supervisorAgent = new Agent({
  model: 'anthropic/claude-opus-4-7',    // 复杂决策：最强
})

5.2 流式输出优化

对于面向用户的 Agent，流式输出是必须的。Mastra 的 .stream() 方法支持逐 token 输出：

const agent = mastra.getAgentById('customer-service')
const stream = await agent.stream(userMessage, { threadId })

// 前端可以立即开始渲染，不用等待完整响应
for await (const chunk of stream.textStream) {
  // 逐 chunk 推送到前端
  controller.enqueue(new TextEncoder().encode(chunk))
}

5.3 错误处理与重试

import { Agent } from '@mastra/core/agent'

const resilientAgent = new Agent({
  id: 'resilient-agent',
  model: 'openai/gpt-5.5',
  tools: { apiTool },
  // 配置重试策略
  retryConfig: {
    maxRetries: 3,
    backoffMs: 1000,
    retryableErrors: ['rate_limit', 'timeout', 'server_error'],
  },
})

5.4 可观测性

Mastra 内置了 OpenTelemetry 支持，可以追踪每个 Agent 调用、Tool 执行、Workflow 步骤的详细信息：

const mastra = new Mastra({
  agents: { ... },
  telemetry: {
    serviceName: 'customer-service',
    exporter: 'otlp',  // 导出到 Jaeger/Zipkin/Grafana
    endpoint: process.env.OTEL_ENDPOINT,
  },
})

六、部署方案

6.1 Serverless 部署（推荐）

Mastra 原生支持部署到主流 Serverless 平台：

Vercel:

# vercel.json
{
  "functions": {
    "api/chat/**/*.ts": { "runtime": "nodejs20.x" }
  }
}

Cloudflare Workers:

// wrangler.toml
[vars]
OPENAI_API_KEY = "sk-..."

6.2 Docker 部署

FROM node:22-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY dist/ ./dist/
ENV NODE_ENV=production
CMD ["node", "dist/server.js"]

6.3 长期运行的 Agent

对于需要持续运行的 Agent（如 Slack Bot），可以使用 PM2 或 systemd：

pm2 start dist/server.js --name mastra-agent --instances 4

七、生态与社区

Mastra 的生态正在快速成长：

• 模板库：提供 20+ 开箱即用的项目模板，覆盖客服、数据分析、内容生成、DevOps 等场景
• Studio：内置的可视化调试工具，可以实时查看 Agent 的推理过程、Tool 调用、Workflow 执行状态
• 部署器：支持 Vercel、Cloudflare、AWS Lambda、Docker 等多种部署方式
• 存储后端：支持 PostgreSQL、MongoDB、Redis、Pinecone、Qdrant 等
• 企业客户：Replit（在线 IDE）、SoftBank（电信）、Factorial（HR SaaS）、Sanity（CMS）、Medusa（电商）

八、总结与展望

Mastra 的出现填补了 TypeScript 生态在 AI Agent 框架领域的空白。它的核心优势在于：

1. TypeScript-first 设计：不是从 Python 移植的"翻译版"，而是充分利用 TypeScript 类型系统的原生框架
2. 六大模块全覆盖：Agent、Workflow、RAG、Voice、Memory、Channels，一站式解决 AI 应用开发的所有需求
3. Model Router：统一的模型路由层，一行代码切换 provider，零摩擦多模型支持
4. Edge Runtime 适配：天然支持 Cloudflare Workers、Vercel Edge 等边缘计算平台
5. 生产就绪：内置 OpenTelemetry、错误重试、流式输出等生产级特性

当然，Mastra 也有需要改进的地方：

• 生态成熟度：与 LangChain 相比，社区插件和第三方集成还不够丰富
• 文档覆盖：部分高级特性的文档还不够完善
• 性能基准：缺少与其他框架的系统性性能对比数据

但从发展趋势来看，Mastra 正在以惊人的速度迭代。16,000+ 次提交、Replit/SoftBank 等企业客户的背书、以及 TypeScript 生态天然的全栈优势，都让它成为 2026 年最值得关注的 AI Agent 框架之一。

如果你是一个 TypeScript 开发者，正在寻找一个真正好用的 AI Agent 框架——不是"能用"，而是"好用"——Mastra 值得你认真看一看。

参考资料：

• Mastra 官方文档：https://mastra.ai/docs
• GitHub 仓库：https://github.com/mastra-ai/mastra
• Mastra Templates：https://mastra.ai/templates