脚手架与首个 Agent：create mastra 与 provider/model

你将得到什么

• 一个可运行的 Mastra TypeScript 项目（CLI 脚手架或手动安装）
• 一个已注册的 Agent（id / name / instructions / model）
• 一次成功的 agent.generate(...)，终端能打印 response.text

开始前准备

1. 本机 Node.js 18+（官方说明 Node 22.18.0+ 可直接跑 TypeScript；更低版本请自行配 tsx / 编译）。
2. 至少一个提供商 API Key。官方按 model 前缀自动读环境变量，例如：
   • openai/... → OPENAI_API_KEY
   • anthropic/... → ANTHROPIC_API_KEY
   • google/... → GOOGLE_API_KEY
   • 完整列表见 Environment variables
3. 终端能执行 npm。

不要把 Key 写进仓库；只用环境变量。

官方文档中出现的已知模型字符串示例（以 Get started / Models 为准，可能随版本更新）：

• openai/gpt-5.6-sol、openai/gpt-5-mini
• anthropic/claude-sonnet-4-6、anthropic/claude-opus-4-7、anthropic/claude-haiku-4-5
• google/gemini-2.5-flash

本课默认用 openai/gpt-5.6-sol；若你改用 Anthropic/Google，只需换 model 字符串与对应 Key。

步骤 1：创建项目（推荐 CLI）

官方 Quickstart：

npm create mastra@latest

等价包管理器（官方文档同页）：

pnpm create mastra@latest
# 或
yarn create mastra
# 或
bunx create-mastra

按交互提示选择目录与选项。创建完成后进入项目目录。

对照结果：目录里应有 Mastra 相关入口（常见为 src/mastra/ 一类结构；以脚手架实际输出为准），且 package.json 含 @mastra/core / mastra 等依赖。

CLI 也会装好本地 Studio 等交互能力；本课验收以代码里的 generate 为准。更多 CLI 说明见 create-mastra 参考。

步骤 2（可选）：手动脚手架

若你想完全按官方 Get started「condensed instructions」手搭：

mkdir mastra-quickstart && cd mastra-quickstart
echo '{ "type": "module" }' > package.json
npm install @mastra/core@latest zod@latest typescript@latest @types/node@latest mastra@latest

tsconfig.json（与官方一致）：

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

对照结果：npm install 无报错；package.json 中 "type": "module"。

步骤 3：写第一个 Agent

新建（或编辑脚手架生成的）Agent 文件，例如 src/mastra/agents/weather-agent.ts。官方示例要点：

• import { Agent } from "@mastra/core/agent"
• 构造参数：{ id, name, instructions, model }
• model 必须是字符串，格式 provider/model，例如 openai/gpt-5.6-sol
• 不要写 openai:gpt-...，不要 import/传入 provider 对象

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

export const weatherAgent = new Agent({
  id: 'weather-agent',
  name: 'Weather Agent',
  instructions: `
You are a helpful weather assistant that provides accurate weather information.
Keep responses concise but informative.
`,
  // 使用 provider/model 字符串，不是 provider:model，也不是 provider 对象
  model: 'openai/gpt-5.6-sol',
})

对照结果：文件无语法错误；id 后续要用 getAgentById('weather-agent')。

步骤 4：注册到 Mastra 入口

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

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

本地 import 请带文件扩展名（官方示例如此）。

步骤 5：配置 API Key 并首调

export OPENAI_API_KEY="YOUR_API_KEY"

验收脚本 run.mjs（与官方一致；Node 22.18+ 可直接跑 TS import）：

// run.mjs
import { mastra } from './src/mastra/index.ts'

const agent = mastra.getAgentById('weather-agent')
const response = await agent.generate('Weather in SF')
console.log(response.text)

运行：

node run.mjs

对照结果：

常见失败：

• 缺环境变量：openai/ 模型必须有 OPENAI_API_KEY（见 Environment variables）。
• model 拼写：必须与官方列表一致，例如 openai/gpt-5.6-sol，不要臆造 ID。
• ESM / 扩展名：本地相对路径缺 .ts 可能解析失败。

本课检查清单

• npm create mastra@latest（或手动安装）完成
• Agent 的 model 为 provider/model 字符串
• Mastra({ agents: { weatherAgent } }) 已注册
• getAgentById('weather-agent').generate(...) 打印出文本

下一课：用官方 createTool 给 Agent 挂上可执行工具，再 generate 触发工具调用。