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

# 在 Express 項目中整合 Mastra

本指南會示範如何使用 Mastra 及 Express 建立可呼叫 Tool 的 AI Agent。透過 [Express 伺服器配接器](https://mastra.zisheng.pro/zh-HK/reference/server/express-adapter)，你毋須自行編寫路由或執行獨立的 Mastra 伺服器，便可將 Agent 公開為 HTTP 端點。

## 開始之前

- 你需要受支援[模型 Provider](https://mastra.zisheng.pro/zh-HK/models) 的 API 金鑰。如沒有偏好，可使用 [OpenAI](https://mastra.zisheng.pro/zh-HK/models/providers/openai)。
- 安裝 Node.js `v22.13.0` 或更新版本

## 建立新的 Express 應用程式（可選）

如已有 Express 應用程式，可跳至下一步。

複製此[樣板程式庫](https://github.com/mastra-ai/express-ts-boilerplate)，然後安裝依賴套件：

**HTTPS**:

**npm**:

```bash
git clone https://github.com/mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
npm install
```

**pnpm**:

```bash
git clone https://github.com/mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
pnpm install
```

**Yarn**:

```bash
git clone https://github.com/mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
yarn install
```

**Bun**:

```bash
git clone https://github.com/mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
bun install
```

**SSH**:

```bash
git clone https://github.com/mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
npm install
```

**Tab 3**:

```bash
git clone https://github.com/mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
pnpm install
```

**Tab 4**:

```bash
git clone https://github.com/mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
yarn install
```

**Tab 5**:

```bash
git clone https://github.com/mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
bun install
```

**Tab 6**:

**npm**:

```bash
git clone git@github.com:mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
npm install
```

**pnpm**:

```bash
git clone git@github.com:mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
pnpm install
```

**Yarn**:

```bash
git clone git@github.com:mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
yarn install
```

**Bun**:

```bash
git clone git@github.com:mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
bun install
```

**Tab 7**:

```bash
git clone git@github.com:mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
npm install
```

**Tab 8**:

```bash
git clone git@github.com:mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
pnpm install
```

**Tab 9**:

```bash
git clone git@github.com:mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
yarn install
```

**Tab 10**:

```bash
git clone git@github.com:mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
bun install
```

## 初始化 Mastra

在 Express 項目目錄內執行 [`mastra init`](https://mastra.zisheng.pro/zh-HK/reference/cli/mastra)。

出現提示時，選擇 Provider（例如 OpenAI）並輸入金鑰：

```bash
npx mastra@latest init
```

這會建立包含天氣 Agent 範例的 `src/mastra` 資料夾，以及下列檔案：

- `index.ts` - Mastra 設定，包括記憶體
- `tools/weather-tool.ts` - 擷取指定地點天氣資料的 Tool
- `agents/weather-agent.ts`- 使用該 Tool 的天氣 Agent，並包含提示詞

稍後你會將 `src/mastra/index.ts` 檔案傳給 Express 伺服器配接器。

## 加入伺服器配接器

安裝 Express 伺服器配接器套件：

**npm**:

```bash
npm install @mastra/express@latest
```

**pnpm**:

```bash
pnpm add @mastra/express@latest
```

**Yarn**:

```bash
yarn add @mastra/express@latest
```

**Bun**:

```bash
bun add @mastra/express@latest
```

開啟位於 `src/index.ts` 的 Express 進入點檔案，並加入所需的 import 及初始化程式碼：

```typescript
import express, { type Request, type Response } from 'express'
import { MastraServer } from '@mastra/express'
import { mastra } from './mastra'

const app = express()
const PORT = process.env.PORT || 3000

// Middleware
app.use(express.json())

const server = new MastraServer({ app, mastra })
await server.init()

// Routes
app.get('/', (_req: Request, res: Response) => {
  res.json({ message: 'Hello, World!' })
})

// Start server
app.listen(PORT, () => {
  console.log(`Server is running on http://localhost:${PORT}`)
})
```

系統會使用現有的 Express `app` 及根 ⁠`mastra` 實例初始化 ⁠`MastraServer`。呼叫 `⁠init()` 會註冊 Mastra 中介軟件，並公開所有可用的 Mastra 端點。

## 測試你的 Agent

Mastra 預設會在 `/api` 子路徑下加入端點，並使用你的 Agent／Workflow ID。由 `mastra init` 建立的預設 `weather-agent` 可於 `/api/agents/weather-agent` 使用。

啟動 Express 伺服器：

```bash
npm run start
```

在另一個終端機視窗中，使用 `curl` 向天氣 Agent 提問：

```bash
curl -X POST http://localhost:3000/api/agents/weather-agent/generate -H "Content-Type: application/json" -d "{\"messages\":[{\"role\":\"user\",\"content\":\"What is the weather like in Seoul?\"}]}"
```

## 下一步

恭喜你使用 Express 建立了 Mastra Agent！🎉

接下來，你可以使用自己的 Tool 及邏輯擴充項目：

- 進一步了解 [Agent](https://mastra.zisheng.pro/zh-HK/docs/agents/overview)
- 為 Agent 提供專屬 [Tool](https://mastra.zisheng.pro/zh-HK/docs/agents/using-tools)
- 為 Agent 加入仿人的[記憶體](https://mastra.zisheng.pro/zh-HK/docs/memory/overview)

準備好後，可進一步了解 Mastra 如何與 Express 整合：

- [伺服器配接器](https://mastra.zisheng.pro/zh-HK/docs/server/server-adapters)