跳至主要內容

建構 Slack assistant

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

先決條件
「先決條件」的直接連結

建立 Agent
「建立 Agent」的直接連結

安裝 Slack adapter：

npm install @chat-adapter/slack

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

src/mastra/agents/slack-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：

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

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

建立 Slack app
「建立 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 檔案：

.env
SLACK_SIGNING_SECRET=your-signing-secret
SLACK_BOT_TOKEN=xoxb-your-bot-token

Adapter 預設會讀取這些環境變數。如需更多詳細資訊，請參閱 Chat SDK Slack adapter 文件。

連接 webhook
「連接 webhook」的直接連結

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

啟動開發伺服器：

npm run dev

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

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：

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 僅供本機開發使用。部署應用程式後，請將 Slack app Event Subscriptions 中的 Request URL 更新為 production URL（例如 https://your-app.example.com/api/agents/slack-agent/channels/slack/webhook）。

測試 Agent
「測試 Agent」的直接連結

使用 Slack 測試之前，你可以先在 Studio 中調整 Agent 的行為。開啟 http://localhost:4111/ 與 Agent 對話並調整 instructions。檢查 Trace 以了解回應的產生方式。

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

/invite @your-bot-name

在 channel 中提及 bot：

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

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

後續步驟
「後續步驟」的直接連結

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

  • 部署應用程式，並將 Slack Request URL 更新為 production endpoint
  • 將更多 adapter（Discord、Telegram）加入同一個 Agent，讓它能在多個平台上回應
  • 設定多模態內容，讓 Agent 處理聊天中分享的圖片、影片和音訊
  • 新增 tools，讓 Agent 能存取外部 API 和資料

深入了解：

On this page