Mastra 框架完整指南：TypeScript 开发者的 AI Agent 利器

为什么选择 Mastra？

如果你是一名 TypeScript/JavaScript 开发者，想要在 AI 应用开发中获得与 Python 开发者同等的生产力，Mastra 就是为你打造的框架。

Mastra 是一个开源的 TypeScript 原生 AI Agent 框架，由 Y Combinator 支持，专为 Web 开发者设计。它提供了构建、测试和部署 AI 应用所需的所有原语，让你能够快速从想法走向生产环境。

核心优势

• TypeScript 原生：完整的类型支持和 IDE 智能提示
• 生产就绪：内置工作流、记忆、RAG、评估和追踪
• 开发者体验：交互式 Playground 和实时调试
• 开源免费：MIT 许可证，社区驱动

快速开始

安装 Mastra

# 创建新项目
npx create-mastra@latest my-ai-app

# 进入项目目录
cd my-ai-app

# 安装依赖
npm install

项目结构

my-ai-app/
├── src/
│   ├── mastra/
│   │   ├── agents/          # Agent 定义
│   │   ├── tools/           # 自定义工具
│   │   ├── workflows/       # 工作流
│   │   └── index.ts         # 主入口
│   └── index.ts
├── package.json
└── mastra.config.ts

核心概念

1. 创建 Agent

Agent 是 Mastra 的核心构建块。每个 Agent 都有特定的角色、工具和记忆。

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

export const customerSupportAgent = new Agent({
  name: 'Customer Support Agent',
  instructions: `
    你是一名专业的客服助手，负责回答用户关于产品的问题。
    - 保持友好和专业的语气
    - 提供准确的信息
    - 如果不知道答案，诚实告知并建议联系人工客服
  `,
  model: {
    provider: 'ANTHROPIC',
    name: 'claude-sonnet-4-20250514',
  },
});

2. 创建自定义工具

工具让 Agent 能够执行具体操作，比如查询数据库、调用 API 等。

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

export const orderLookupTool = createTool({
  id: 'order-lookup',
  description:
cover: https://res.makeronsite.com/freeaitool.com/mastra-typescript-ai-agent-framework-2026-cover.webp '根据订单号查询订单状态',
  inputSchema: z.object({
    orderId: z.string().describe('订单编号'),
  }),
  execute: async ({ context }) => {
    const { orderId } = context;

    // 模拟数据库查询
    const order = await db.orders.findUnique({
      where: { id: orderId },
    });

    return {
      status: order?.status || 'not_found',
      items: order?.items || [],
      total: order?.total || 0,
    };
  },
});

3. 将工具绑定到 Agent

// src/mastra/agents/customer-support.ts
import { customerSupportAgent } from './customer-support';
import { orderLookupTool } from '../tools/order-lookup';

// 添加工具
customerSupportAgent.addTools([orderLookupTool]);

4. 创建工作流

工作流让你能够编排多个 Agent 和工具，实现复杂的业务流程。

// src/mastra/workflows/order-processing.ts
import { Workflow } from '@mastra/core/workflows';
import { agentStep } from '@mastra/core/step';

export const orderProcessingWorkflow = new Workflow({
  name: 'order-processing',
  triggerSchema: z.object({
    orderId: z.string(),
    customerEmail: z.string().email(),
  }),
});

// 定义步骤
const checkOrder = agentStep({
  agent: customerSupportAgent,
  outputSchema: z.object({
    status: z.string(),
    canRefund: z.boolean(),
  }),
});

const sendEmail = agentStep({
  agent: emailAgent,
  outputSchema: z.object({
    sent: z.boolean(),
  }),
});

// 编排流程
orderProcessingWorkflow
  .step(checkOrder)
  .then(sendEmail, {
    when: { ref: checkOrder, path: 'canRefund', eq: true },
  });

实战示例：构建客服机器人

让我们构建一个完整的客服机器人，能够处理订单查询、退货请求和产品咨询。

完整代码

// src/mastra/index.ts
import { Mastra } from '@mastra/core/mastra';
import { customerSupportAgent } from './agents/customer-support';
import { orderLookupTool } from './tools/order-lookup';
import { refundTool } from './tools/refund';
import { orderProcessingWorkflow } from './workflows/order-processing';

export const mastra = new Mastra({
  agents: {
    'customer-support': customerSupportAgent,
  },
  tools: {
    'order-lookup': orderLookupTool,
    'refund': refundTool,
  },
  workflows: {
    'order-processing': orderProcessingWorkflow,
  },
});

启动开发服务器

# 启动 Mastra 开发服务器（包含 Playground）
npx mastra dev

访问 http://localhost:4111 打开交互式 Playground，可以实时测试你的 Agent。

调用 Agent

// src/index.ts
import { mastra } from './mastra';

async function main() {
  const agent = mastra.getAgent('customer-support');

  const response = await agent.generate(
    '我的订单号是 ORD-12345，请帮我查询状态'
  );

  console.log(response.text);
}

main();

高级功能

记忆系统

Mastra 内置记忆功能，让 Agent 能够记住对话历史。

import { Memory } from '@mastra/memory';

const memory = new Memory({
  storage: {
    type: 'postgres',
    connectionString: process.env.DATABASE_URL,
  },
});

const agent = new Agent({
  name: 'Support Agent',
  memory,
  // ...其他配置
});

RAG（检索增强生成）

import { RAG } from '@mastra/rag';

const rag = new RAG({
  vectorStore: {
    type: 'pinecone',
    apiKey: process.env.PINECONE_API_KEY,
  },
});

// 索引文档
await rag.index({
  documents: ['./docs/product-manual.pdf'],
  indexName: 'product-knowledge',
});

// 在 Agent 中使用
const agent = new Agent({
  name: 'Product Expert',
  rag: {
    indexes: ['product-knowledge'],
  },
});

评估和追踪

import { Eval } from '@mastra/evals';

const eval = new Eval({
  name: 'response-quality',
  criteria: [
    { name: 'accuracy', weight: 0.4 },
    { name: 'helpfulness', weight: 0.3 },
    { name: 'tone', weight: 0.3 },
  ],
});

// 运行评估
const results = await eval.evaluate(agent, testCases);
console.log(results.summary);

生产部署

部署到 Vercel

# 安装 Vercel CLI
npm i -g vercel

# 部署
vercel deploy --prod

部署到 Docker

# Dockerfile
FROM node:20-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

EXPOSE 3000
CMD ["npm", "start"]

# 构建和运行
docker build -t my-mastra-app .
docker run -p 3000:3000 my-mastra-app

性能优化建议

1. 使用流式响应：对于长文本生成，启用 streaming 提升用户体验
2. 缓存工具结果：对于频繁调用的工具，实现结果缓存
3. 批量处理：对于多个相似请求，使用批量 API 调用
4. 监控延迟：使用 Mastra 内置追踪监控各步骤耗时

与其他框架对比

特性	Mastra	LangChain.js	Vercel AI SDK
TypeScript 原生	✅	⚠️	✅
内置工作流	✅	✅	❌
交互式 Playground	✅	❌	❌
记忆系统	✅	✅	⚠️
RAG 支持	✅	✅	❌
评估工具	✅	⚠️	❌
学习曲线	中等	陡峭	平缓

总结

Mastra 是 TypeScript 开发者进入 AI Agent 开发的最佳选择之一。它提供了：

• 🎯 开发者友好的 API：类型安全、智能提示完整
• 🔧 丰富的内置功能：工作流、记忆、RAG、评估一站式解决
• 🚀 生产就绪：从开发到部署的完整工具链
• 📚 优秀的文档：详细的教程和示例

如果你已经在 TypeScript 生态中工作，想要快速构建 AI 应用，Mastra 值得尝试。

参考资源

• Mastra 官方文档
• GitHub 仓库
• Mastra Playground
• 示例项目集合
• 社区 Discord

---

相关推荐阅读：

• LangGraph 多 Agent 编排指南
• Google ADK 代理开发工具包
• PydanticAI 框架完整指南