頻道總覽

新增於： @mastra/core@1.22.0

頻道會將 Agent 連接至 Slack、Microsoft Teams、Discord、Telegram、WhatsApp、GitHub 與 Linear 等訊息和協作平台。當使用者在平台上傳送訊息或留言時，Agent 會接收內容、透過一般 Agent pipeline 處理，並將回應串流回對話。Mastra 的頻道層使用 Chat SDK。

請從你所用平台的頁面開始：

• Slack
• Microsoft Teams
• Discord
• Telegram
• WhatsApp
• iMessage

更多平台列出其他可用平台。除了此處列出的平台，Mastra 頻道也能搭配相容的 Chat SDK adapter，而且所有 adapter 都採用相同的 Mastra 設定模式。

適合使用頻道的情境

若 Agent 需要執行下列工作，請使用頻道：

• 在使用者原本溝通或工作的地方與其互動。
• 在 Slack、Microsoft Teams、Discord、Telegram 與 WhatsApp 等聊天平台中回應。
• 支援多人 Agent，讓多位使用者在共享頻道或討論串中與同一個 Agent 互動。
• 與 GitHub issue、pull request 討論串和 Linear 留言等協作流程整合。

設定 Agent

頻道使用 Chat SDK adapter，並遵循相同的 Mastra 端模式：建立頻道 adapter，再將其加入 Agent。

src/mastra/agents/your-agent.ts

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

export const yourAgent = new Agent({
  id: 'your-agent',
  name: 'Your Agent',
  instructions: 'You are a helpful assistant.',
  model: 'openai/gpt-5.6-sol',
  channels: {
    adapters: {
      slack: createSlackAdapter(),
    },
  },
})

備註

頻道 adapter 需要 Provider 專屬的環境變數，以提供憑證並驗證請求，例如機器人 token、簽署 secret、應用程式 ID 與 webhook 驗證 token。確切的變數名稱請查看所用平台的指南或 Chat SDK adapter 目錄。

建議為頻道設定儲存空間。儲存空間可讓 Mastra 在重新啟動後繼續保留頻道 state、討論串訂閱、Tool 核准與記憶：

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { LibSQLStore } from '@mastra/libsql'
import { yourAgent } from './agents/your-agent'

export const mastra = new Mastra({
  agents: { yourAgent },
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: process.env.DATABASE_URL,
  }),
})

Webhook 路由

平台會透過 webhook 將頻道活動傳送至 Mastra。Webhook 是 HTTP 端點；當新訊息、提及等事件發生，或使用者在互動式 Tool 核准卡片上選取「Approve」時，平台就會呼叫此端點。Agent 會透過這個方式接收並開始處理新訊息，再於同一頻道中回應。

Mastra 會為每個已設定的 adapter 註冊 webhook 路由，並代為處理請求：

/api/agents/<AGENT_ID>/channels/<PLATFORM>/webhook

例如，ID 為 your-agent 的 Agent 所使用的 Slack adapter 路由如下：

/api/agents/your-agent/channels/slack/webhook

將平台的 webhook、事件或互動 URL 指向此路徑。請依照所用平台的指南或 Chat SDK 文件操作。

進行本機開發時，平台 webhook 需要公開 URL 才能連線至本機伺服器。請使用 cloudflared 或 ngrok 等 tunnel 公開伺服器；預設位址為 localhost:4111：

npm

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

pnpm

pnpm dlx cloudflared tunnel --url http://localhost:4111

Yarn

yarn dlx cloudflared tunnel --url http://localhost:4111

Bun

bun x cloudflared tunnel --url http://localhost:4111

使用產生的公開 URL 作為 webhook 路徑的基底 URL，例如 https://abc123.trycloudflare.com/api/agents/your-agent/channels/slack/webhook。

備註

Tunnel URL 僅供本機開發使用。部署 Mastra 伺服器後，請將平台的 webhook、事件或互動 URL 更新為正式環境 URL。

討論串 context

使用者在頻道討論串的對話途中提及 Agent 時，Agent 可能沒有先前的 context。預設情況下，Agent 第一次被提及時，Mastra 會從平台擷取最近 10 則訊息。

1. Agent 第一次在討論串中被提及時，會從平台擷取近期訊息。
2. 這些訊息會加在使用者訊息之前，作為對話 context。
3. Agent 回應後會訂閱該討論串，並透過 Mastra 記憶取得完整歷史記錄。
4. 該討論串後續的訊息不會再次從平台擷取。

設定 threadContext: { maxMessages: 0 } 即可停用此行為。這只適用於非私訊的討論串。

Mastra 還會加入一則簡短的系統訊息，告知 Agent 請求來自哪個頻道與平台，例如訊息來自私訊或公開頻道。設定 threadContext: { addSystemMessage: false } 即可略過此訊息。

Tool 核准

設有 requireApproval: true 的 Tool 會顯示為包含 Approve 與 Deny 按鈕的互動式卡片：

src/mastra/tools/delete-file.ts

import { promises as fs } from 'node:fs'
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const deleteFile = createTool({
  id: 'delete-file',
  description: 'Delete a file from the system',
  inputSchema: z.object({
    path: z.string().describe('Path to the file to delete'),
  }),
  requireApproval: true,
  execute: async ({ path }) => {
    await fs.unlink(path)
    return { deleted: path }
  },
})

Agent 呼叫此 Tool 時，使用者會看到包含 Tool 名稱、引數以及 Approve 和 Deny 動作的卡片。Tool 只會在核准後執行。

在 adapter 上設定 toolDisplay: 'text'，即可將 Tool 呼叫顯示為純文字，而非互動式卡片。在 'hidden' 模式下，當使用者後續在同一討論串中傳送訊息時，autoResumeSuspendedTools 可恢復已暫停的 Tool；此功能需要記憶。Hidden 模式只會隱藏核准按鈕。

回覆格式

Agent 回覆預設會以 markdown 發布。Slack 等原生支援 markdown 算繪的平台會直接顯示粗體、連結與表格，其他平台則會將 markdown 轉換為自身格式。Agent 只需輸出標準 markdown，即可在各平台正確顯示，效果與相同回覆在 Studio 中的顯示方式一致。

若要改為以原始純文字發布回覆，請在 adapter 上設定 textFormat: 'plain'：

src/mastra/agents/your-agent.ts

channels: {
  adapters: {
    slack: {
      adapter: createSlackAdapter(),
      textFormat: 'plain',
    },
  },
},

若 Agent 的 prompt 要求輸出 Slack mrkdwn 等平台專屬語法，而非標準 markdown，可使用此替代設定。如果你先前為解決 markdown 被顯示成原始文字而加入這類 prompt 指示，請移除它們；目前預設會以原生方式算繪標準 markdown。textFormat 只影響最終回覆文字，不會影響 Tool 卡片、錯誤訊息與原生串流文字。

多使用者識別

在群組對話中，Mastra 會在每則訊息前加上傳送者姓名與平台 ID，讓 Agent 能區分不同發言者：

[Alice (@U123ABC)]: Can you help me with this?
[Bob (@U456DEF)]: I have a question too.

多模態內容

Gemini 等模型可原生處理圖片、影片與音訊。搭配使用 inlineMedia 與 inlineLinks，即可讓使用者跨平台與 Agent 分享 rich content：

src/mastra/agents/vision-agent.ts

import { Agent } from '@mastra/core/agent'
import { createDiscordAdapter } from '@chat-adapter/discord'

export const visionAgent = new Agent({
  id: 'vision-agent',
  name: 'Vision Agent',
  instructions: 'You can see images, watch videos, and listen to audio.',
  model: 'google/gemini-2.5-flash',
  channels: {
    adapters: {
      discord: createDiscordAdapter(),
    },
    inlineMedia: ['image/*', 'video/*', 'audio/*'],
    inlineLinks: [
      { match: 'youtube.com', mimeType: 'video/*' },
      { match: 'youtu.be', mimeType: 'video/*' },
      'imgur.com',
    ],
  },
})

採用此設定後：

• 使用者上傳螢幕截圖，Agent 會描述所見內容。
• 使用者上傳 .mp4 片段，Agent 會摘要影片。
• 使用者貼上 YouTube 連結，Agent 會觀看並討論影片。
• 使用者貼上 imgur 連結，Agent 會直接看到圖片。

預設只會以 inline 方式傳送圖片（inlineMedia: ['image/*']）。不支援的類型會以文字摘要描述，讓 Agent 得知檔案內容，同時避免在拒絕這些類型的模型上失敗。所有 inlineMedia pattern 請參閱頻道參考文件；網域比對、HEAD 偵測與強制 MIME 類型則請參閱 inlineLinks 參考文件。

Serverless 部署

在 Vercel 等 serverless 平台上，每項請求都會在獨立且短暫存活的 instance 中執行。頻道需要兩項機制才能在此環境中可靠運作：Agent 回應期間讓函式持續運作，以及供各 instance 協調的共享 pub/sub。

使用 waitUntil 讓函式持續運作

頻道 webhook 會立即傳回 200 回應，接著 Agent 在背景執行並發布回覆。大多數 serverless 平台會在函式回應後立即凍結函式，導致執行作業在 Agent 回答前停止。請傳入 waitUntil 函式，讓平台維持 instance 運作直到執行完成。

在 Vercel 上，請傳入 @vercel/functions 的 waitUntil：

src/mastra/agents/your-agent.ts

import { Agent } from '@mastra/core/agent'
import { createSlackAdapter } from '@chat-adapter/slack'
import { waitUntil } from '@vercel/functions'

export const yourAgent = new Agent({
  id: 'your-agent',
  name: 'Your Agent',
  instructions: 'You are a helpful assistant.',
  model: 'openai/gpt-5.6-sol',
  channels: {
    adapters: {
      slack: createSlackAdapter(),
    },
    waitUntil,
  },
})

Vercel 與 AWS Lambda 會在送出回應後立即凍結函式，因此需要 waitUntil。系統會從請求 context 自動偵測 Cloudflare Workers 與 Netlify Functions，所以不需設定。若 runtime 的 waitUntil 位於請求 context 中，但無法自動偵測，請使用 resolveWaitUntil。詳細資訊請參閱頻道參考文件。

使用共享 pub/sub 協調 instance

頻道會透過 Agent 的 signal pipeline 路由訊息，而且每次執行都會取得其討論串的 lease，確保一次只由一項執行作業掌控對話。

預設的記憶體內 pub/sub 無法跨越 instance 邊界，因此在 serverless 環境中，後續訊息可能被路由至不同於 Agent 執行所在的 instance。

若沒有共享 pub/sub，該 instance 無法連線至作用中的執行作業，因而會自行啟動另一項作業；原始作業仍繼續執行，造成討論串被處理兩次。

請在 Mastra instance 上設定由 Redis Streams 支援的共享 pub/sub，讓 lease 與 signal 能跨 instance 協調：

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { RedisStreamsPubSub } from '@mastra/redis-streams'
import { yourAgent } from './agents/your-agent'

export const mastra = new Mastra({
  agents: { yourAgent },
  pubsub: new RedisStreamsPubSub({
    url: process.env.REDIS_URL,
    keyPrefix: 'mastra:my-app',
  }),
})

Vercel 的代管 Redis 整合與 Upstash Redis 都很適合。若要進一步了解何時需要分散式 pub/sub，請參閱 PubSub 指南與 RedisStreamsPubSub 參考文件。

相關內容

• 頻道參考文件
• AgentController 頻道
• 📹 Mastra 頻道工作坊