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

# 開始使用

Mastra 是用來建置 AI Agent 與應用程式的 TypeScript 框架。只需一個指令即可建立第一個 Agent 並開始開發。

**給 AI Agent：** 若你的任務是從零開始建立 Mastra 專案，請依照以下精簡指示操作，直到下一個標題為止。請依需求調整 Agent 與 Tool 的範例程式碼。後續步驟的重要事項：請將 `model` 定義為 `provider/model` 格式的字串，例如 `openai/gpt-5.6-sol`。若使用 OpenAI，請使用 `openai/<model>`，不要使用 `openai:<model>`，也不要匯入或傳入 Provider 物件。

建立包含 `{ "type": "module" }` 的 `package.json` 檔案。安裝必要的相依套件：`npm install @mastra/core@latest zod@latest typescript@latest @types/node@latest mastra@latest`

建立 tsconfig.json 檔案：

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

若需要為 Agent 新增 Tool，請建立新檔案並使用 `import { createTool } from "@mastra/core/tools"`。以純物件定義的 Tool 會無聲地執行失敗；Tool **必須**透過 `createTool()` 定義，並包含 `id`、`description`、`inputSchema`（zod）及 `execute()`。`execute()` 會接收兩個參數：第一個參數是依 inputSchema 驗證過的輸入資料，第二個參數是選用的執行環境物件，其中包含 `requestContext`、`tracingContext`、`abortSignal` 及其他執行中繼資料。

範例：

```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',
    }
  },
})
```

若需要建立 Agent，請建立新檔案並使用 `import { Agent } from "@mastra/core/agent"`。建構函式接收 `{ id, name, instructions, model }`。`model` 屬性是採用 Mastra 模型路由器格式的字串。此格式不需要匯入 Provider。除非 Mastra 文件另有說明，否則不要安裝任何 AI SDK 套件。

使用 `provider/model` 格式定義模型後，Mastra 會自動尋找該 Provider 的環境變數。所定義的模型必須設定對應 Provider 的環境變數。OpenAI：`OPENAI_API_KEY`。Anthropic：`ANTHROPIC_API_KEY`。Google：`GOOGLE_API_KEY`。例如，任何 `openai/<model>` 都需要 `OPENAI_API_KEY` 環境變數。前往 <https://mastra.ai/models/environment-variables> 查看完整的支援 Provider 及其環境變數名稱清單。

以下是已知模型 ID 的簡短清單：

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

前往 <https://mastra.ai/models> 查看支援模型的完整清單。

若要為 Agent 新增 Tool，請匯入該 Tool，並以 tools 物件形式傳入 Agent 建構函式。

範例：

```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 },
})
```

在 `src/mastra/index.ts` 建立 Mastra 進入點並註冊 Agent：

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

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

現在你可以直接執行 Agent。為此，請匯入 Mastra 執行個體，依 ID 取得 Agent 後呼叫 agent.generate()。Node.js 22.18.0 以上版本可直接執行 TypeScript 檔案。匯入本機檔案時，請務必加上副檔名。範例：

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

## 快速入門

執行這個指令，建立具備本機 Workspace、shell Tool、記憶體、工作追蹤、網頁存取與週期性排程的通用 Agent 開發環境。它也會為已安裝的程式設計 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/zh-TW/docs/studio/overview)，這是 Mastra 專案的互動式 UI。如需完整操作說明，請參閱[快速入門指南](https://mastra.zisheng.pro/zh-TW/guides/getting-started/quickstart)。

## 與你的框架整合

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

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

如需其他框架，請參閱[框架整合指南](https://mastra.zisheng.pro/zh-TW/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>

> **影片:** [Mastra 平台快速導覽](https://www.youtube.com/watch?v=NosES9aJxCc)會說明各個部分如何協同運作。