TypeScript + Mastra：前端开发者的AI代理构建指南

快速开发一些ai应用的时候，往往有一些框架可以选择，其中鼎鼎大名的LangChain就是可选项之一，LangChain有pytho和js的版本，但今天介绍使用的是对前端开发人员更友好的Mastra。因为它有更好的类型支持，更简单、更容易使用，并且支持代理和工作流原语。

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

环境准备（3分钟）

安装 Node.js ≥ 20
获取任意LLM密钥（以OpenAI为例）
一键创建脚手架

bash

npm create mastra@latest my-agent

按提示选择 Agent + RAG + Workflow

cd my-agent

npm install

配置环境变量

在根目录创建 .env 文件：

OPENAI_API_KEY=sk-xxxxxxxx

目录结构速览

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 中：

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' };
  },
});

组装Agent

在 src/mastra/agents/weatherAgent.ts 中：

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 },
});

注册到框架

在 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 文件保存即热更新，体验与前端开发一致。

第三步：集成到前端/全栈项目

脚本调用方式

在 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示例）

在 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 即可零胶水接入聊天界面。

第四步：添加长期记忆与企业知识库

配置向量库

在 src/mastra/memory/rag.ts 中：

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

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

导入文档数据

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

启用知识库功能

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

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

第五步：构建可观测、可重试的Workflow

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

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 # 本地生产环境验证

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”，但零配置、前端友好。

你只需：

编写tools（普通函数 + Zod）
编写Agent（绑定模型、指令、工具、知识库）
必要时编写Workflow（图状流程、可重试）

开发体验完全等同于写前端：热更新、类型提示、可视化Playground、一键部署。

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

祝编码愉快！

留言列表

留言板