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

# 建構 Slack assistant

在本指南中，你將建構一個能在 Slack 回應訊息與提及的 Mastra Agent。你將學會如何設定 channel adapter、以正確權限設定 Slack app、透過 webhook 將其連接至 Agent，以及測試互動。

## 先決條件

- 已安裝 Node.js `v22.13.0` 或更新版本
- 具備受支援 [Model Provider](https://mastra.zisheng.pro/zh-TW/models) 的 API key
- 已有 Mastra 專案。如有需要，請依照[安裝指南](https://mastra.zisheng.pro/zh-TW/guides/getting-started/quickstart)操作。
- 一個可建立 app 的 [Slack workspace](https://slack.com/)

## 建立 Agent

安裝 Slack adapter：

**npm**:

```bash
npm install @chat-adapter/slack
```

**pnpm**:

```bash
pnpm add @chat-adapter/slack
```

**Yarn**:

```bash
yarn add @chat-adapter/slack
```

**Bun**:

```bash
bun add @chat-adapter/slack
```

建立新檔案 `src/mastra/agents/slack-agent.ts` 並定義 Agent：

```ts
import { Agent } from '@mastra/core/agent'
import { createSlackAdapter } from '@chat-adapter/slack'

export const slackAgent = new Agent({
  id: 'slack-agent',
  name: 'Slack Agent',
  instructions:
    'You are a helpful assistant. Answer questions, help with tasks, and have natural conversations.',
  model: 'anthropic/claude-opus-4-7',
  channels: {
    adapters: {
      slack: createSlackAdapter(),
    },
  },
})
```

`channels` property 會指示 Mastra 為每個 adapter 產生 webhook endpoint。在此情況下，Slack adapter 會自動處理 event verification、signature validation 和訊息格式。

在 `src/mastra/index.ts` 檔案中註冊 Agent：

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

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

## 建立 Slack app

你需要一個 Slack app，才能將 Agent 連接至 workspace。

前往 <https://api.slack.com/apps>，然後選取 **Create New App** > **From scratch**。為 app 命名並選取 workspace。

前往 **OAuth & Permissions**，向下捲動至 **Bot Token Scopes**。新增下列 scope：

- `app_mentions:read`
- `channels:history`
- `channels:read`
- `chat:write`
- `users:read`

在 **OAuth & Permissions** 頂端選取 **Install to Workspace**。複製 **Bot User OAuth Token**（`xoxb-...`）。

前往 **Basic Information** > **App Credentials**，並複製 **Signing Secret**（例如 `c3a4...`）。

確認 **Settings** > **Socket Mode** 下的 **Socket Mode** 已設為 **off**。

將憑證加入 `.env` 檔案：

```bash
SLACK_SIGNING_SECRET=your-signing-secret
SLACK_BOT_TOKEN=xoxb-your-bot-token
```

Adapter 預設會讀取這些環境變數。如需更多詳細資訊，請參閱 [Chat SDK Slack adapter 文件](https://chat-sdk.dev/adapters/slack)。

## 連接 webhook

Slack 透過 webhook 將 event 傳送給 Agent。Mastra 會自動為每個 channel adapter 產生這個 endpoint。

啟動開發伺服器：

**npm**:

```bash
npm run dev
```

**pnpm**:

```bash
pnpm run dev
```

**Yarn**:

```bash
yarn dev
```

**Bun**:

```bash
bun run dev
```

在本機開發期間，Slack 需要 public URL 才能連線至本機伺服器。開啟新的 terminal 並啟動 tunnel：

```bash
npx cloudflared tunnel --url http://localhost:4111
```

這會輸出一個類似 `https://triple-arms-solutions-kit.trycloudflare.com` 的臨時 public URL。每次重新啟動 tunnel 時，URL 都會變更。

在 Slack app 設定中，前往 **Event Subscriptions**，並將 **Enable Events** 切換為 **On**。

將 **Request URL** 設為 tunnel URL 加上 Agent webhook path：

```text
https://<your-tunnel-url>/api/agents/slack-agent/channels/slack/webhook
```

Slack 會傳送 verification request。如果開發伺服器正在執行，就會回應綠色勾號。

在 **Subscribe to bot events** 下新增：

- `app_mention`
- `message.channels`

選取 **Save Changes**。變更 event subscription 後，Slack 會要求你重新安裝 app。前往 **OAuth & Permissions** 並選取 **Reinstall to Workspace**，以套用更新後的權限。

> **備註:** Tunnel URL 僅供本機開發使用。[部署應用程式](https://mastra.zisheng.pro/zh-TW/docs/deployment/overview)後，請將 Slack app **Event Subscriptions** 中的 **Request URL** 更新為 production URL（例如 `https://your-app.example.com/api/agents/slack-agent/channels/slack/webhook`）。

## 測試 Agent

使用 Slack 測試之前，你可以先在 [Studio](https://mastra.zisheng.pro/zh-TW/docs/studio/overview) 中調整 Agent 的行為。開啟 <http://localhost:4111/> 與 Agent 對話並調整 instructions。檢查 Trace 以了解回應的產生方式。

對 Agent 的回應感到滿意後，即可測試 Slack integration。在 Slack 中邀請 bot 加入 channel：

```text
/invite @your-bot-name
```

在 channel 中提及 bot：

```text
@your-bot-name What can you help me with?
```

Agent 會在 thread 中回應。輸出可能會因 model 和 instructions 而異。

## 後續步驟

你可以進一步擴充這個 Agent：

- [部署應用程式](https://mastra.zisheng.pro/zh-TW/docs/deployment/overview)，並將 Slack **Request URL** 更新為 production endpoint
- 將更多 adapter（Discord、Telegram）加入同一個 Agent，讓它能在多個平台上回應
- 設定[多模態內容](https://mastra.zisheng.pro/zh-TW/docs/capabilities/channels/overview)，讓 Agent 處理聊天中分享的圖片、影片和音訊
- 新增 [tools](https://mastra.zisheng.pro/zh-TW/docs/agents/using-tools)，讓 Agent 能存取外部 API 和資料

深入了解：

- [Channels 概覽](https://mastra.zisheng.pro/zh-TW/docs/capabilities/channels/overview)
- [Studio](https://mastra.zisheng.pro/zh-TW/docs/studio/overview)
- [部署概覽](https://mastra.zisheng.pro/zh-TW/docs/deployment/overview)
- [Chat SDK adapter 文件](https://chat-sdk.dev)