> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/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 運行框架，當中包含本機 Workspace、shell Tool、記憶、任務追蹤、網絡存取及週期排程。它亦會為你已安裝的編程助手安裝 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/zh-HK/docs/studio/overview)，這是供你的 Mastra 項目使用的互動式使用者介面。完整步驟請參閱[快速開始指南](https://mastra.zisheng.pro/zh-HK/guides/getting-started/quickstart)。

## 與你的框架整合

將 Mastra 加入現有項目，或使用你偏好的框架建立新應用程式：

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

如要使用其他框架，請參閱[框架整合指南](https://mastra.zisheng.pro/zh-HK/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)、[瀏覽器 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>

> **Video:** [Mastra 平台快速導覽](https://www.youtube.com/watch?v=NosES9aJxCc)展示各個部分如何互相配合。