Mastra 1.0 构建生产级 TypeScript AI Agent

# 使用 npm 创建项目
npm create mastra@latest my-mastra-app

cd my-mastra-app
npm install

# 或使用 pnpm
pnpm create mastra
pnpm install

# OpenAI（推荐）
OPENAI_API_KEY=sk-your-api-key-here

# 或使用 Anthropic
# ANTHROPIC_API_KEY=sk-ant-...

# 或使用 Google
# GOOGLE_GENERATIVE_AI_API_KEY=...

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

export const weatherTool = createTool({
  id: "fetch-weather",
  name: "Weather Tool",
  description: "Fetches current weather data for a given city",
  
  // 输入验证 Schema
  inputSchema: z.object({
    city: z.string().describe("City name, e.g., 'Tokyo', 'New York'"),
  }),
  
  // 输出验证 Schema
  outputSchema: z.object({
    temp: z.number().describe("Temperature in Celsius"),
    condition: z.string().describe("Weather condition"),
    humidity: z.number().optional().describe("Humidity percentage"),
  }),
  
  // 执行逻辑
  execute: async ({ inputData }) => {
    const { city } = inputData;
    
    // 使用真实天气 API（示例使用 OpenWeatherMap）
    const apiKey = process.env.OPENWEATHER_API_KEY;
    const response = await fetch(
      `https://api.openweathermap.org/data/2.5/weather?q=${city}&appid=${apiKey}&units=metric`
    );
    
    if (!response.ok) {
      throw new Error(`Failed to fetch weather for ${city}`);
    }
    
    const data = await response.json();
    
    return {
      temp: Math.round(data.main.temp),
      condition: data.weather[0].description,
      humidity: data.main.humidity,
    };
  },
});

import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import { Memory } from "@mastra/core/memory";
import { LibSQLStore } from "@mastra/libsql";
import { weatherTool } from "../tools/weather-tool";

export const weatherAgent = new Agent({
  id: "weather-agent",
  name: "Weather Assistant",
  description: "An AI agent that provides weather information",
  
  // 使用 OpenAI GPT-4 Turbo
  model: openai("gpt-4-turbo"),
  
  // 系统指令：定义 Agent 行为准则
  instructions: `
You are a helpful weather assistant. Follow these rules:
1. ALWAYS use the weatherTool to fetch weather data
2. Never hallucinate weather information
3. If the tool fails, explain the issue to the user
4. Provide temperature in Celsius and describe conditions in simple terms
5. Suggest appropriate clothing based on weather
  `.trim(),
  
  // 注册可用工具
  tools: {
    weatherTool,
  },
  
  // 配置长期记忆（可选）
  memory: new Memory({
    storage: new LibSQLStore({
      url: "file:./mastra.db",
    }),
  }),
  
  // 限制最大推理步骤，防止无限循环
  maxSteps: 5,
});

import {
  createWorkflow,
  createStep,
  WorkflowStep,
  WorkflowEngine,
} from "@mastra/core/workflows";
import { z } from "zod";
import { weatherTool } from "../tools/weather-tool";

// 定义步骤 1：获取天气数据
const getWeatherStep = createStep({
  id: "get-weather",
  inputSchema: z.object({
    city: z.string(),
  }),
  outputSchema: z.object({
    temp: z.number(),
    condition: z.string(),
    humidity: z.number(),
  }),
  execute: async ({ inputData }) => {
    return await weatherTool.execute({ inputData });
  },
});

// 定义步骤 2：生成穿衣建议
const clothingAdviceStep = createStep({
  id: "clothing-advice",
  inputSchema: z.object({
    temp: z.number(),
    condition: z.string(),
  }),
  outputSchema: z.object({
    advice: z.string(),
  }),
  execute: async ({ inputData }) => {
    const { temp, condition } = inputData;
    
    let advice = "";
    if (temp < 10) {
      advice = "穿厚外套、羽绒服，注意保暖";
    } else if (temp < 20) {
      advice = "穿长袖衬衫或薄外套";
    } else if (temp < 30) {
      advice = "穿短袖 T 恤，保持清爽";
    } else {
      advice = "穿轻薄透气衣物，注意防晒";
    }
    
    if (condition.includes("雨")) {
      advice += "，记得带伞";
    }
    
    return { advice };
  },
});

// 组装 Workflow
export const weatherWorkflow = createWorkflow({
  id: "weather-workflow",
  name: "Weather Information Workflow",
  description: "Get weather data and generate clothing advice",
  inputSchema: z.object({ city: z.string() }),
  outputSchema: z.object({
    temp: z.number(),
    condition: z.string(),
    humidity: z.number(),
    advice: z.string(),
  }),
})
  // 顺序执行：先获取天气，再生成建议
  .then(getWeatherStep)
  .then(clothingAdviceStep)
  .commit();

import { Mastra } from "@mastra/core";
import { weatherAgent } from "./agents/weather-agent";
import { weatherWorkflow } from "./workflows/weather-workflow";

export const mastra = new Mastra({
  // 注册 Agents
  agents: {
    weatherAgent,
  },
  
  // 注册 Workflows
  workflows: {
    weatherWorkflow,
  },
  
  // 启用可观测性（可选）
  // observability: {
  //   traceExport: new ConsoleSpanExporter(),
  // },
});

import { mastra } from "./mastra";

async function main() {
  // ===== 方式 1：直接调用 Agent =====
  const agent = mastra.getAgent("weather-agent");
  
  // 简单查询
  const result = await agent.generate("东京的天气怎么样？");
  console.log("Agent 回复:", result.text);
  
  // 流式输出（适合 UI 展示）
  const stream = await agent.stream("北京的天气怎么样？");
  for await (const chunk of stream.textStream) {
    process.stdout.write(chunk);
  }
  console.log();
  
  // ===== 方式 2：运行 Workflow =====
  const workflow = mastra.getWorkflow("weather-workflow");
  const run = await workflow.createRun();
  
  const wfResult = await run.start({
    inputData: { city: "Shanghai" },
  });
  
  if (wfResult.status === "success") {
    console.log("天气:", wfResult.result.temp, "°C");
    console.log("状况:", wfResult.result.condition);
    console.log("穿衣建议:", wfResult.result.advice);
  }
}

main().catch(console.error);

# 启动开发服务器（监听文件变化）
npm run dev

# 输出示例:
# ✓ Mastra dev server running on:
# - REST API: http://localhost:4111
# - DevTools: http://localhost:4111/dev
# - API Docs: http://localhost:4111/api-docs

import { Memory } from "@mastra/core/memory";
import { LibSQLStore } from "@mastra/libsql";
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";

// 创建记忆存储
const memory = new Memory({
  // 使用 LibSQL 本地存储
  storage: new LibSQLStore({
    url: "file:./mastra.db",
  }),
  
  // 语义召回配置
  semanticRecall: {
    enabled: true,
    topK: 3,  // 召回最相关的 3 条历史消息
  },
  
  // 工作记忆（短期上下文）
  workingMemory: {
    enabled: true,
    maxMessages: 10,
  },
});

export const chatAgent = new Agent({
  id: "chat-agent",
  model: openai("gpt-4-turbo"),
  instructions: "You are a helpful assistant with memory.",
  memory,
});

// 使用示例：
// const response = await chatAgent.generate("还记得我昨天问的问题吗？");
// 系统会自动召回相关历史消息并注入上下文