跳到主要内容

构建 Slack 助手

在本指南中，你将构建一个可在 Slack 中回复消息和提及的 Mastra Agent。你将学习如何配置 channel adapter、设置具备正确权限的 Slack app、通过 webhook 将其连接到 Agent，以及测试交互。

前提条件
前提条件的直接链接

  • 已安装 Node.js v22.13.0 或更高版本
  • 受支持的 Model Provider 提供的 API 密钥
  • 现有的 Mastra 项目。如有需要，请按照安装指南操作。
  • 你可以在其中创建 app 的 Slack Workspace

创建 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 属性会让 Mastra 为每个 adapter 生成一个 webhook 端点。在本例中，Slack adapter 会自动处理事件验证、签名验证和消息格式化。

在 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 已关闭。

将凭据添加到 .env 文件：

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

adapter 默认会读取这些环境变量。有关更多详情，请参阅 Chat SDK Slack adapter 文档。

连接 webhook
连接 webhook的直接链接

Slack 通过 webhook 把事件传递给 Agent。Mastra 会自动为每个 channel adapter 生成此端点。

启动开发服务器：

npm run dev

在本地开发期间，Slack 需要通过公共 URL 访问你的本地 server。打开新的终端并启动隧道：

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

该命令会输出一个临时公共 URL，例如 https://triple-arms-solutions-kit.trycloudflare.com。每次重启隧道时，URL 都会改变。

在 Slack app 设置中，转到 Event Subscriptions，并将 Enable Events 切换为 On。

将 Request URL 设置为隧道 URL，并附加 Agent webhook 路径：

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

Slack 会发送验证请求。如果开发服务器正在运行，它会显示绿色对勾。

在 Subscribe to bot events 下添加：

  • app_mention
  • message.channels

选择 Save Changes。更改事件订阅后，Slack 要求你重新安装 app。转到 OAuth & Permissions 并选择 Reinstall to Workspace，以应用更新后的权限。

备注

隧道 URL 仅用于本地开发。部署应用后，请将 Slack app 的 Event Subscriptions 中的 Request URL 更新为生产环境 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 集成。在 Slack 中邀请 bot 加入某个 channel：

/invite @your-bot-name

在 channel 中提及 bot：

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

Agent 会在线程中回复。输出可能因模型和 instructions 而异。

后续步骤
后续步骤的直接链接

你可以扩展此 Agent：

  • 部署应用，并把 Slack Request URL 更新为生产环境端点
  • 向同一 Agent 添加更多 adapter（Discord、Telegram），让它可以在多个平台上回复
  • 配置多模态内容，让 Agent 可以处理聊天中分享的图像、视频和音频
  • 添加 Tool，让 Agent 能够访问外部 API 和数据

了解更多：

On this page