前端基于 TypeScript 使用 Mastra 来开发一个 AI 应用 / AI 代理（Agent）

下面给出一份"从 0 到 1"的完整路线，演示如何用前端熟悉的 TypeScript 技术栈 （Node 20 + npm + VSCode）借助 Mastra 快速落地一个可对话、可调用工具、具备记忆与知识库的 AI 代理（Agent） 。全部代码均为纯 TypeScript，无需切 Python，也无需自己拼 OpenAI SDK。

环境准备（3 分钟）

① 安装 Node ≥ 20

② 拿到任意 LLM 密钥（下面以 OpenAI 为例）

③ 一键脚手架

bash 复制代码

npm create mastra@latest my-agent   # 按提示选 Agent + RAG + Workflow
cd my-agent
npm install

④ 把密钥写进根目录 .env

ini 复制代码

OPENAI_API_KEY=sk-xxxxxxxx

scss 复制代码

src/
├─ mastra/
│  ├─ index.ts         // 框架入口，注册 Agent/Workflow
│  ├─ agents/
│  ├─ tools/           // 自定义工具（函数 + Zod Schema）
│  ├─ workflows/       // 图状工作流
│  └─ memory/          // 可选：向量库配置（pgvector / Pinecone ...）
└─ index.ts            // 你的业务脚本 / API 路由

所有 .ts 文件在 npm run dev 时会被 tsx 实时转译，前端同学零学习成本。

第一步：写一只"会查天气"的 Agent

在 src/mastra/tools/weather.ts 里声明"工具"

typescript 复制代码

import { createTool } from '@mastra/core';
import { z } from 'zod';

export const weatherTool = createTool({
  id: 'get_weather',
  description: '查询城市当前气温',
  inputSchema: z.object({ city: z.string() }),
  outputSchema: z.object({ temp: z.number(), unit: z.string() }),
  execute: async ({ city }) => {
    // 这里调真实天气 API，示例直接 mock
    return { temp: 26, unit: '°C' };
  },
});

在 src/mastra/agents/weatherAgent.ts 里组装 Agent

typescript 复制代码

import { Agent } from '@mastra/core';
import { openai } from '@ai-sdk/openai';
import { weatherTool } from '../tools/weather';

export const weatherAgent = new Agent({
  name: 'weatherBot',
  model: openai('gpt-4o'),
  instructions: '你是天气小助手，可按用户要求查询实时气温。',
  tools: { weatherTool },
});

把 Agent 注册到框架

typescript 复制代码

// src/mastra/index.ts
import { Mastra } from '@mastra/core';
import { weatherAgent } from './agents/weatherAgent';

export const mastra = new Mastra({
  agents: { weatherBot: weatherAgent },
});

第二步：本地调试 ------ 官方 Playground

bash 复制代码

npm run dev     # 默认拉起 http://localhost:4111

浏览器里会出现类似 Vite 的 DevUI：

左侧直接对话，右侧可看 Agent 调用栈、工具参数、耗时。
修改 .ts 文件保存即热更新，体验与前端开发一致。

第三步：把 Agent 嵌入你的前端/全栈项目

任何脚本里调用

typescript 复制代码

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

(async () => {
  const agent = mastra.getAgent('weatherBot');
  const reply = await agent.generate('上海现在多少度？');
  console.log(reply.text);          // 文字答复
  console.log(reply.toolCalls);     // 实际调了 weatherTool
})();

或者作为 API 路由（以 Next.js 为例）

typescript 复制代码

// app/api/chat/route.ts
import { mastra } from '@/mastra';
import { CoreMessage, streamText } from 'ai';

export async function POST(req: Request) {
  const { messages }: { messages: CoreMessage[] } = await req.json();
  const agent = mastra.getAgent('weatherBot');
  const result = await streamText({    // 支持流式返回
    model: agent.model,
    messages,
    tools: agent.tools,
  });
  return result.toDataStreamResponse();
}

前端直接用 Vercel useChat 即可零胶水接入聊天界面。

第四步：给 Agent 加上"长期记忆 + 企业知识库"

启动向量库（本地实验可用 SQLite + pgvector 扩展，生产换 Pinecone）
在 src/mastra/memory/ 新建 rag.ts

typescript 复制代码

import { PgVector } from '@mastra/vector-pgvector';
import { embedMany } from '@ai-sdk/openai';

export const rag = new PgVector({
  connectionString: process.env.PG_CONN!,
  embed: embedMany,
});

把文档灌进去（一次 ETL）

typescript 复制代码

await rag.upsert('kb001', [
  { text: '公司退货政策：7 天内无理由...', metadata: { url: '/policies' } },
]);

在 Agent 里打开 knowledge 开关

typescript 复制代码

new Agent({
  name: 'supportBot',
  model: openai('gpt-4o'),
  knowledge: { rag, topK: 5 },
  instructions: '你只能用知识库内容回答售后问题。',
});

至此，Agent 回复将完全基于企业内部文档，并可标注引用段落。

第五步：让多步业务"可观测、可重试"------ Workflow

当流程需要"确定性"时（审批、报告、ETL），用 Workflow 而非让 Agent 自由发挥：

typescript 复制代码

import { Workflow } from '@mastra/core';

export const refundWorkflow = new Workflow({
  name: 'refund',
  inputSchema: z.object({ orderId: z.string() }),
  steps: [
    { id: 'checkOrder', run: async ({ input }) => { /* 查订单 */ } },
    { id: 'llmSummary', run: async ({ ctx }) => {
        // 任意步骤都可再次调用 LLM
        const agent = mastra.getAgent('supportBot');
        return agent.generate(`请总结订单 ${ctx.input.orderId} 的退款原因`);
    }},
    { id: 'approve', if: (ctx) => ctx.stepResults.llmSummary.score > 0.8,
      run: async () => { /* 自动同意 */ } },
  ],
});

Workflow 自带

可视化追踪（OpenTelemetry）
失败重试 / 人工审核（.waitForEvent）
子流程复用

构建 & 部署

bash 复制代码

npm run build        # 生成 standalone 产物
npm start            # 本地生产验证

官方助手一键部署：

bash 复制代码

npx mastra deploy vercel       # 或 cloudflare / netlify / docker

生成的端点即标准 HTTP API，前端（React/Vue/Swift/Flutter）直接 fetch。

常见前端集成模式

场景	推荐做法
Web 聊天框	`useChat`（Vercel AI SDK）+ 上面 `/api/chat` 路由
小程序	把 `streamText` 换成 `generateText`，一次性返回
本地 Electron	把 `mastra` 实例挂在主进程，渲染进程 IPC 调用
SSR 站点	在 `getServerSideProps` 里预执行 Workflow，生成静态报告

小结

Mastra = "TypeScript 版的 LangChain + Temporal"，但零配置、前端友好。
你只需：
1. 写 tools（普通函数 + Zod）
2. 写 Agent（绑定模型、指令、工具、知识库）
3. 必要时写 Workflow（图状流程、可重试）
开发体验完全等同于写前端：热更新、类型提示、可视化 Playground、一键部署。

照着上面 5 步走，30 分钟内即可拥有一个可对话、可查询天气、具备知识库与记忆、可上线部署的 AI 代理；后续继续叠工具、叠 Workflow、换模型即可快速演进。祝编码愉快!