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

# Channels 概览

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

Channels 将 Agent 连接到 Slack、Microsoft Teams、Discord、Telegram、WhatsApp、GitHub 和 Linear 等消息与协作平台。当用户在平台上发送消息或评论时，Agent 会接收该内容，通过常规 Agent 流水线进行处理，并将响应流式传回对话。Mastra 使用 [Chat SDK](https://chat-sdk.dev/) 提供这一 Channel 层。

请从对应平台的页面开始：

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

[更多适配器](https://mastra.zisheng.pro/docs/capabilities/channels/other-adapters)列出了其他平台。除这里列出的平台外，Mastra Channels 也适用于兼容的 [Chat SDK 适配器](https://chat-sdk.dev/adapters)，并且所有适配器都采用相同的 Mastra 配置模式。

## 何时使用 Channels

当 Agent 需要完成以下任务时，请使用 Channels：

- 在用户已经交流或工作的地方与其互动。
- 在 Slack、Microsoft Teams、Discord、Telegram 和 WhatsApp 等聊天平台中响应。
- 支持多人 Agent，让多个人在共享 Channel 或线程中与同一个 Agent 交互。
- 与 GitHub issue、pull request 线程和 Linear 评论等协作工作流集成。

## 配置 Agent

Channels 使用 Chat SDK 适配器，并遵循相同的 Mastra 侧模式：创建 Channel 适配器并将其添加到 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(),
    },
  },
})
```

> **备注:** Channel 适配器需要 Provider 特有的环境变量，以提供凭据并验证请求，例如机器人 token、签名 secret、应用 ID 和 webhook 验证 token。请查看对应平台的指南或 [Chat SDK 适配器目录](https://chat-sdk.dev/adapters)，了解确切的变量名称。

建议为 Channels 配置 [Storage](https://mastra.zisheng.pro/docs/storage/overview)。Storage 让 Mastra 能够跨重启持久保存 Channel state、线程订阅、Tool 审批和 Memory：

```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 将 Channel 活动发送到 Mastra。Webhook 是平台在发生事件时调用的 HTTP 端点，例如出现新消息、有人提及 Agent，或用户在交互式 Tool 审批卡片上选择“Approve”。Agent 正是通过这种方式接收新消息、开始处理，并在同一 Channel 中响应。

Mastra 会为每个已配置的适配器注册 webhook 路由，并代你处理请求：

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

例如，ID 为 `your-agent` 的 Agent 上的 Slack 适配器会使用：

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

将平台的 webhook、事件或交互 URL 指向此路径。请遵循对应平台的指南或 [Chat SDK 文档](https://chat-sdk.dev/adapters)。

本地开发期间，平台 webhook 需要公开 URL 才能访问本地 Server。请使用 [cloudflared](https://github.com/cloudflare/cloudflared) 或 [ngrok](https://ngrok.com/) 等隧道公开 Server，默认地址为 `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`。

> **备注:** 隧道 URL 仅用于本地开发。部署 Mastra Server 后，请将平台的 webhook、事件或交互 URL 更新为生产环境 URL。

## 线程上下文

当用户在 Channel 线程的对话中途提及 Agent 时，Agent 可能没有此前的上下文。默认情况下，Mastra 会在首次被提及时从平台获取最近 10 条消息。

1. 在线程中首次被提及时，Agent 从平台获取最近的消息。
2. 这些消息会作为对话上下文添加到用户消息之前。
3. 响应后，Agent 会订阅该线程，并通过 Mastra Memory 获得完整历史记录。
4. 该线程中的后续消息不会再次从平台获取历史记录。

设置 `threadContext: { maxMessages: 0 }` 可禁用此行为。这仅适用于非私信线程。

Mastra 还会添加一条简短的系统消息，告知 Agent 请求来自哪个 Channel 和平台，例如该消息来自私信还是公开 Channel。设置 `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 只会在获得批准后执行。

在适配器上设置 `toolDisplay: 'text'`，可将 Tool 调用呈现为纯文本而不是交互式卡片。在 `'hidden'` 模式下，之后有用户消息到达同一线程时，`autoResumeSuspendedTools` 可以恢复已暂停的 Tool。这需要 Memory。隐藏模式只会隐藏审批按钮。

## 回复格式

Agent 回复默认以 markdown 形式发送。Slack 等原生支持 markdown 渲染的平台会直接渲染粗体文本、链接和表格。其他平台会将 markdown 转换为自己的格式。Agent 编写标准 markdown 后，可以在所有平台上正确渲染，与同一回复在 Studio 中的渲染效果一致。

在适配器上设置 `textFormat: 'plain'`，可改为按字面意义的纯文本发送回复：

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

如果通过提示词要求 Agent 输出平台特有语法（例如 Slack mrkdwn），而非标准 markdown，可使用此应急选项。如果你曾添加此类提示词指令来规避 markdown 被按字面渲染的问题，请改为移除这些指令。现在默认行为会以原生方式渲染标准 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 分享富媒体内容：

```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 会直接看到图像。

默认情况下，只会以内联形式发送图像（`inlineMedia: ['image/*']`）。不支持的类型会以文本摘要描述，这样 Agent 既能知道文件的存在，又不会让拒绝这些类型的模型失败。有关所有 `inlineMedia` 模式，请参阅 [Channels Reference](https://mastra.zisheng.pro/reference/agents/channels)；有关域名匹配、HEAD 检测和强制 MIME 类型，请参阅 [inlineLinks Reference](https://mastra.zisheng.pro/reference/agents/channels)。

## Serverless 部署

在 Vercel 等 serverless 平台上，每个请求都会在独立且短暂存活的实例中运行。Channels 要在这种环境中可靠工作，需要满足两个条件：在 Agent 响应期间保持函数存活，以及使用共享 pub/sub 让实例能够协调。

### 使用 `waitUntil` 保持函数存活

Channel webhook 会立即返回 `200` 响应，随后 Agent 在后台运行并发送回复。在大多数 serverless 平台上，函数会在响应后立即冻结，导致运行在 Agent 回复前停止。请传入 `waitUntil` 函数，让平台保持实例存活，直到运行结束。

在 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`，因为它们会在发送响应后立即冻结函数。Cloudflare Workers 和 Netlify Functions 会根据请求上下文自动检测，因此不需要传入。对于 `waitUntil` 位于请求上下文中但无法自动检测的运行时，请使用 `resolveWaitUntil`。详情请参阅 [Channels Reference](https://mastra.zisheng.pro/reference/agents/channels)。

### 使用共享 pub/sub 协调实例

Channels 通过 Agent 的 [signal 流水线](https://mastra.zisheng.pro/docs/long-running-agents/signals)路由消息，每次运行都会获取其线程的租约，因此同一时间只有一次运行拥有该对话。

默认的内存 pub/sub 无法跨越实例边界，因此在 serverless 环境中，后续消息可能被路由到与 Agent 当前运行所在实例不同的实例。

如果没有共享 pub/sub，该实例无法联系正在进行的运行，于是会启动自己的运行，导致原始运行不受影响，而线程被处理两次。

请在 `Mastra` 实例上配置由 Redis Streams 支持的共享 pub/sub，让租约和 signal 能够跨实例协调：

```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/docs/server/pubsub)和 [`RedisStreamsPubSub` Reference](https://mastra.zisheng.pro/reference/pubsub/redis-streams)。

## 相关内容

- [Channels Reference](https://mastra.zisheng.pro/reference/agents/channels)
- [AgentController Channels](https://mastra.zisheng.pro/docs/harness/agent-controller)
- 📹 [Mastra Channels workshop](https://www.youtube.com/watch?v=E9KFsZEnQO8\&t=5s)