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

# 頻道總覽

**新增於：** `@mastra/core@1.22.0`

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

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

- [Slack](https://mastra.zisheng.pro/zh-TW/docs/capabilities/channels/slack)
- [Microsoft Teams](https://mastra.zisheng.pro/zh-TW/docs/capabilities/channels/teams)
- [Discord](https://mastra.zisheng.pro/zh-TW/docs/capabilities/channels/discord)
- [Telegram](https://mastra.zisheng.pro/zh-TW/docs/capabilities/channels/telegram)
- [WhatsApp](https://mastra.zisheng.pro/zh-TW/docs/capabilities/channels/whatsapp)
- [iMessage](https://mastra.zisheng.pro/zh-TW/docs/capabilities/channels/imessage)

[更多平台](https://mastra.zisheng.pro/zh-TW/docs/capabilities/channels/other-adapters)列出其他可用平台。除了此處列出的平台，Mastra 頻道也能搭配相容的 [Chat SDK adapter](https://chat-sdk.dev/adapters)，而且所有 adapter 都採用相同的 Mastra 設定模式。

## 適合使用頻道的情境

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

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

## 設定 Agent

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

```typescript
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 目錄](https://chat-sdk.dev/adapters)。

建議為頻道設定[儲存空間](https://mastra.zisheng.pro/zh-TW/docs/storage/overview)。儲存空間可讓 Mastra 在重新啟動後繼續保留頻道 state、討論串訂閱、Tool 核准與記憶：

```typescript
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 路由，並代為處理請求：

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

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

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

將平台的 webhook、事件或互動 URL 指向此路徑。請依照所用平台的指南或 [Chat SDK 文件](https://chat-sdk.dev/adapters)操作。

進行本機開發時，平台 webhook 需要公開 URL 才能連線至本機伺服器。請使用 [cloudflared](https://github.com/cloudflare/cloudflared) 或 [ngrok](https://ngrok.com/) 等 tunnel 公開伺服器；預設位址為 `localhost:4111`：

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

```bash
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 按鈕的互動式卡片：

```typescript
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'`：

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

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

## 多使用者識別

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

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

## 多模態內容

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

```typescript
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 請參閱[頻道參考文件](https://mastra.zisheng.pro/zh-TW/reference/agents/channels)；網域比對、HEAD 偵測與強制 MIME 類型則請參閱 [inlineLinks 參考文件](https://mastra.zisheng.pro/zh-TW/reference/agents/channels)。

## Serverless 部署

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

### 使用 `waitUntil` 讓函式持續運作

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

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

```typescript
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`。詳細資訊請參閱[頻道參考文件](https://mastra.zisheng.pro/zh-TW/reference/agents/channels)。

### 使用共享 pub/sub 協調 instance

頻道會透過 Agent 的 [signal pipeline](https://mastra.zisheng.pro/zh-TW/docs/long-running-agents/signals) 路由訊息，而且每次執行都會取得其討論串的 lease，確保一次只由一項執行作業掌控對話。

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

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

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

```typescript
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 指南](https://mastra.zisheng.pro/zh-TW/docs/server/pubsub)與 [`RedisStreamsPubSub` 參考文件](https://mastra.zisheng.pro/zh-TW/reference/pubsub/redis-streams)。

## 相關內容

- [頻道參考文件](https://mastra.zisheng.pro/zh-TW/reference/agents/channels)
- [AgentController 頻道](https://mastra.zisheng.pro/zh-TW/docs/harness/agent-controller)
- 📹 [Mastra 頻道工作坊](https://www.youtube.com/watch?v=E9KFsZEnQO8\&t=5s)