create-mastra

创建 Mastra 技能

创建新的 Mastra AI Agent 项目的完整指南。包含快速启动 CLI 方法，以及附带完整可运行代码示例的详细手动安装方法。

官方文档：mastra.ai/docs

---

开始使用

询问：“您想如何创建 Mastra 项目？”

1. 快速设置 - 复制并运行：npm create mastra@latest
2. 引导式设置 - 我会逐步引导您完成每个步骤，由您批准命令
3. 自动设置 ⭐ - 我会创建所有内容，您只需提供 API 密钥

致 AI Agent： CLI 采用交互式操作。请使用自动设置——按照下方“自动设置 / 手动安装”中的步骤创建文件。

---

前提条件

• 来自受支持模型提供商（OpenAI、Anthropic、Google 等）的 API 密钥

---

快速设置（用户运行 CLI）

只需一条命令即可创建新的 Mastra 项目：

npm create mastra@latest

其他包管理器：

pnpm create mastra@latest
yarn create mastra@latest
bun create mastra@latest

---

CLI 标志

跳过示例 Agent：

npm create mastra@latest --no-example

使用特定模板：

npm create mastra@latest --template <template-name>

---

自动设置 / 手动安装

自动设置时使用此方法（由 AI 创建所有文件），或者在您希望手动控制时使用。

按照以下步骤创建完整的 Mastra 项目：

步骤 1：创建项目目录

mkdir my-first-agent && cd my-first-agent
npm init -y

步骤 2：安装依赖项

npm install -D typescript @types/node mastra@latest
npm install @mastra/core@latest zod@^4

步骤 3：配置包脚本

添加到 package.json：

{
  "scripts": {
    "dev": "mastra dev",
    "build": "mastra build"
  }
}

步骤 4：配置 TypeScript

创建 tsconfig.json：

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "outDir": "dist"
  },
  "include": ["src/**/*"]
}

重要： Mastra 要求 "module": "ES2022" 和 "moduleResolution": "bundler"。CommonJS 会导致错误。

步骤 5：创建环境文件

创建包含 API 密钥的 .env：

GOOGLE_GENERATIVE_AI_API_KEY=<your-api-key>

或者使用 OPENAI_API_KEY、ANTHROPIC_API_KEY 等。

步骤 6：创建天气工具

创建 src/mastra/tools/weather-tool.ts：

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

export const weatherTool = createTool({
  id: "get-weather",
  description: "Get current weather for a location",
  inputSchema: z.object({
    location: z.string().describe("City name"),
  }),
  outputSchema: z.object({
    output: z.string(),
  }),
  execute: async () => {
    return { output: "The weather is sunny" };
  },
});

步骤 7：创建天气 Agent

创建 src/mastra/agents/weather-agent.ts：

import { Agent } from "@mastra/core/agent";
import { weatherTool } from "../tools/weather-tool";

export const weatherAgent = new Agent({
  id: "weather-agent",
  name: "Weather Agent",
  instructions: `
      You are a helpful weather assistant that provides accurate weather information.

      Your primary function is to help users get weather details for specific locations. When responding:
      - Always ask for a location if none is provided
      - If the location name isn't in English, please translate it
      - If giving a location with multiple parts (e.g. "New York, NY"), use the most relevant part (e.g. "New York")
      - Include relevant details like humidity, wind conditions, and precipitation
      - Keep responses concise but informative

      Use the weatherTool to fetch current weather data.
`,
  model: "google/gemini-2.5-pro",
  tools: { weatherTool },
});

注意： 模型格式为 "provider/model-name"。示例：

• "google/gemini-2.5-pro"
• "openai/gpt-4o"
• "anthropic/claude-3-5-sonnet-20241022"

步骤 8：创建 Mastra 入口点

创建 src/mastra/index.ts：

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

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

步骤 9：启动开发服务器

npm run dev

访问 http://localhost:4111 打开 Studio 并测试您的 Agent。

---

后续步骤

使用 create mastra 创建项目后：

• 自定义示例 Agent，修改 src/mastra/agents/weather-agent.ts
• 添加新 Agent - 请参阅 Agent 文档
• 创建工作流 - 请参阅 工作流文档
• 添加更多工具以扩展 Agent 的功能
• 集成到您的应用中 - 请参阅 mastra.ai/docs 中的框架指南

---

故障排除

问题	解决方案
未找到 API 密钥	确认您的 .env 文件中包含正确的密钥
Studio 无法启动	检查端口 4111 是否可用
CommonJS 错误	确认 tsconfig.json 使用 "module": "ES2022" 和 "moduleResolution": "bundler"
找不到命令	确认您使用的是 Node.js 20+

---

资源

• 文档
• 安装
• Agent
• 工作流
• 示例
• GitHub