> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# 入门

Mastra 是一个用于构建 AI Agent 和应用的 TypeScript 框架。只需一条命令即可创建第一个 Agent 并开始构建。

**For AI agents:** If you're tasked to build a Mastra project from scratch, follow the condensed instructions until the next heading. Adjust the example code for the agent & tool to your needs. Important for later: Define `model` as a string in `provider/model` format, for example `openai/gpt-5.6-sol`. For OpenAI, use `openai/<model>`, not `openai:<model>`, and don't import or pass a provider object.

Create a `package.json` file with `{ "type": "module" }`. Install the required dependencies: `npm install @mastra/core@latest zod@latest typescript@latest @types/node@latest mastra@latest`

Create a tsconfig.json file:

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

If you need to add a tool to the agent, create a new file and use `import { createTool } from "@mastra/core/tools"`. Plain object tool definitions silently fail to execute; tools MUST be defined via `createTool()` with `id`, `description`, `inputSchema` (zod), `execute()`. `execute()` receives two parameters: the validated input data based on inputSchema (first parameter) and an optional execution context object (second parameter) containing `requestContext`, `tracingContext`, `abortSignal`, and other execution metadata.

Example:

```ts
// 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({
    location: z.string(),
    temperatureCelsius: z.number(),
    conditions: z.string(),
  }),
  execute: async ({ location }) => {
    return {
      location,
      temperatureCelsius: 21,
      conditions: 'sunny',
    }
  },
})
```

If you need to create an agent, create a new file and use `import { Agent } from "@mastra/core/agent"`. The constructor takes `{ id, name, instructions, model }`. The `model` property is a string in Mastra's model router format. No provider import is needed for this format. Don't install any AI SDK package unless Mastra's documentation says otherwise.

By defining the model using `provider/model` format Mastra automatically looks for environment variables for the provider. The defined model requires an environment variable to be set for the provider. OpenAI: `OPENAI_API_KEY`. Anthropic: `ANTHROPIC_API_KEY`. Google: `GOOGLE_API_KEY`. Example: Any `openai/<model>` requires the `OPENAI_API_KEY` environment variable. Go to <https://mastra.ai/models/environment-variables> for a full list of supported providers and their environment variable names.

Short list of known model IDs are:

- `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`

Go to <https://mastra.ai/models> for a full list of supported models.

Add a tool an agent by importing the tool and passing it to the agent constructor as a tools object.

Example:

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

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:
      - Include relevant details like humidity, wind conditions, and precipitation
      - Keep responses concise but informative

      Use the weatherTool to fetch current weather data.
`,
  // Use a string in provider/model format, not provider:model or a provider object.
  model: 'openai/gpt-5.6-sol',
  tools: { weatherTool },
})
```

Create a Mastra entry point at `src/mastra/index.ts` and register the agent:

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

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

You're now able to run the agent directly. For this, import the Mastra instance and call the agent.generate() after retrieving the agent by its id. Node.js 22.18.0 and later are able to run TypeScript files directly. Make sure to add file extensions when importing local files. Example:

```ts
// 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)
```

## 快速开始

运行此命令可创建通用 Agent Harness，其中包含本地 Workspace、shell Tool、Memory、任务跟踪、网页访问和定期调度。它还会为已安装的编程 Agent 安装 Mastra Skill，让你可以立即通过提示词与它交互并进行编辑：

**npm**:

```bash
npm create mastra@latest
```

**pnpm**:

```bash
pnpm create mastra@latest
```

**Yarn**:

```bash
yarn create mastra
```

**Bun**:

```bash
bunx create-mastra
```

你可以立即打开 [Studio](https://mastra.zisheng.pro/docs/studio/overview)，这是 Mastra 项目的交互式 UI。有关完整演练，请参阅[快速入门指南](https://mastra.zisheng.pro/guides/getting-started/quickstart)。

## 与框架集成

将 Mastra 添加到现有项目，或使用你偏好的框架创建新应用：

- [Next.js](https://mastra.ai/guides/getting-started/next-js)
- [React](https://mastra.ai/guides/getting-started/vite-react)
- [Astro](https://mastra.ai/guides/getting-started/astro)
- [Express](https://mastra.ai/guides/getting-started/express)
- [SvelteKit](https://mastra.ai/guides/getting-started/sveltekit)
- [Hono](https://mastra.ai/guides/getting-started/hono)

有关其他框架，请参阅[框架集成指南](https://mastra.zisheng.pro/guides/getting-started/next-js)。

## 模板

浏览[模板](https://mastra.ai/templates)，查找可克隆和调整的完整 Mastra 项目。

## 用例

<details>
**将 Agent 嵌入产品**

为平台添加 AI 能力，让用户可以构建 Agent 或与 Agent 交互。

已有客户：[Replit](https://mastra.zisheng.pro/blog/replitagent3)、[Fireworks](https://mastra.zisheng.pro/blog/fireworks-xml-prompting)、[Medusa](https://mastra.zisheng.pro/blog/medusa-ecommerce)

</details>

<details>
**面向客户的助手**

构建能够处理咨询、安排预约、发送提醒，并通过聊天、WhatsApp 或语音回答问题的 Agent。

已有客户：[Vetnio](https://mastra.zisheng.pro/blog/vetnio)、[Lua](https://mastra.zisheng.pro/blog/lua-scaling)

模板：[文档聊天机器人](https://mastra.zisheng.pro/templates/docs-chatbot)、[Slack Agent](https://mastra.zisheng.pro/templates/slack-agent)

</details>

<details>
**内部 Copilot**

使用理解业务领域的 AI 帮助员工提高工作效率，例如处理人力资源查询、临床文档、销售准备或文档生成。

已有客户：[Factorial](https://mastra.zisheng.pro/blog/factorial-case-study)、[Counsel Health](https://mastra.zisheng.pro/blog/counsel-health)、[Cedar](https://mastra.zisheng.pro/blog/cedar-case-study)、[SoftBank](https://mastra.zisheng.pro/blog/softbank-productivity-mastra-2025-08-20)

模板：[与 PDF 对话](https://mastra.zisheng.pro/templates/chat-with-pdf)、[Google 表格分析](https://mastra.zisheng.pro/templates/google-sheets-analysis)

</details>

<details>
**数据分析 Agent**

让用户使用自然语言查询数据库和仪表板。连接数据源并返回答案、图表或报告。

已有客户：[Index](https://mastra.zisheng.pro/blog/index-case-study)、[PLAID Japan](https://mastra.zisheng.pro/blog/plaid-jpn-gcp-agents)

模板：[与数据库对话](https://mastra.zisheng.pro/templates/text-to-sql)、[CSV 问答](https://mastra.zisheng.pro/templates/csv-to-questions)

</details>

<details>
**内容自动化**

为内容管理系统、知识库或文档系统大规模生成、转换和管理结构化内容。

已有客户：[Sanity](https://mastra.zisheng.pro/blog/sanity)

模板：[与 YouTube 对话](https://mastra.zisheng.pro/templates/chat-with-youtube)、[从 PDF 生成抽认卡](https://mastra.zisheng.pro/templates/flash-cards-from-pdf)

</details>

<details>
**DevOps 和工程自动化**

自动执行部署、调试生产问题、管理基础设施并处理值班 Workflow。

已有客户：[StarSling](https://mastra.zisheng.pro/blog/starsling)

模板：[GitHub PR 代码审查](https://mastra.zisheng.pro/templates/github-pr-code-review-agent)、[Browser Agent](https://mastra.zisheng.pro/templates/browsing-agent)

</details>

<details>
**销售和市场进入 Workflow**

将客户对话转换为结构化任务、生成投资备忘录，或自动执行客户触达序列。

已有客户：[Kestral](https://mastra.zisheng.pro/blog/kestral)、[Orange Collective](https://mastra.zisheng.pro/blog/orange-collective-vc-operating-system)、[WorkOS](https://mastra.zisheng.pro/blog/workos-teaching-mastra)

模板：[客户反馈摘要](https://mastra.zisheng.pro/templates/customer-feedback-summarization)

</details>

> **视频:** [Mastra 平台快速导览](https://www.youtube.com/watch?v=NosES9aJxCc)展示了各个组件如何协同工作。