如何把 Mastra 代理接入 Slack 让其响应频道消息并回写回复

原创2026-09-12 20:44:471,975 阅读
文章标签:人工智能大模型AI AgentAgent 框架Agent 工作流Agent 编排工作流自动化RAGMCP 服务AI 评测后端语音可观测性

如何把 Mastra 代理接入 Slack 让其响应频道消息并回写回复

你的目标是把一个已有的 Mastra 代理接入 Slack:有人在频道里 @ 机器人或直接发消息时,Mastra 通过正常代理管线处理消息,并把回复写回 Slack 的会话(频道消息会回复在线程中)。整条路径是:给代理挂上 Slack 通道适配器 → 在 Slack 侧创建应用并配置 webhook → 本地起开发服务器并用隧道暴露 → 在 Slack 里验证机器人能收发消息。

适用前提:你已有一个 Mastra 项目(推荐框架代码放在 src/mastra/ 下,参考 Develop),并且能在 Slack 工作区中创建应用。通道(Channels)功能自 @mastra/core@1.22.0 起可用,Slack 适配器基于 Chat SDK,具体指南见 Slack 通道文档 和 Channels 总览。

安装适配器并给代理挂上 Slack 通道

在项目里安装 Chat SDK 的 Slack 适配器:

npm install @chat-adapter/slack

然后在代理配置中加入 createSlackAdapter()。以下示例放在 src/mastra/agents/your-agent.ts,模型用的是文档中解析后的示例值 openai/gpt-5.6-sol,可换成你自己的模型:

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

export const yourAgent = new Agent({
  id: 'your-agent',
  name: 'Your Agent',
  instructions: 'Help people plan tasks, answer questions, and coordinate work in Slack.',
  model: 'openai/gpt-5.6-sol',
  channels: {
    adapters: {
      slack: createSlackAdapter(),
    },
  },
})

注意 id: 'your-agent':Slack webhook 路径会用这个 id 拼接,后面配置 Slack 应用时要保持一致。

使用 openai/<model> 格式的模型时,需要设置对应提供商的环境变量,例如 OpenAI 需要 OPENAI_API_KEY。

通道文档建议在 Mastra 实例上配置 storage(如 LibSQLStore),让线程订阅、工具审批等通道状态在重启后保留;本地验证阶段可先不加,上线前建议补上。

在 Slack 侧用 manifest 创建应用

Slack 应用决定机器人的显示名、能力和接收的事件。最快的方式是在目标工作区用 manifest 直接创建(这条路只适用于把代理加进自己的工作区,不覆盖给其他工作区安装的 OAuth 流程):

  1. 打开 api.slack.com/apps,选择 Create an app,再选 From a manifest;
  2. 选择机器人运行的工作区;
  3. 粘贴下面的 manifest 并选择 Create。Slack 同时接受 JSON 和 YAML,用创建弹窗里对应的标签页格式即可。
{
  "display_information": {
    "name": "mastra-agent"
  },
  "features": {
    "app_home": {
      "home_tab_enabled": false,
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    },
    "bot_user": {
      "display_name": "mastra-agent",
      "always_online": true
    }
  },
  "oauth_config": {
    "scopes": {
      "bot": [
        "im:write",
        "app_mentions:read",
        "channels:history",
        "channels:read",
        "chat:write",
        "users:read",
        "im:read",
        "im:history"
      ]
    },
    "pkce_enabled": false
  },
  "settings": {
    "event_subscriptions": {
      "request_url": "https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook",
      "bot_events": ["app_mention", "message.channels", "message.im"]
    },
    "interactivity": {
      "is_enabled": true,
      "request_url": "https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook"
    },
    "org_deploy_enabled": false,
    "socket_mode_enabled": false,
    "token_rotation_enabled": false,
    "is_mcp_enabled": false
  }
}

其中两处占位符:<YOUR-PUBLIC-URL> 是你的 Mastra 服务公网地址(本地开发时就是隧道地址,见下节);<YOUR-AGENT-ID> 是上面代码里 Agent 的 id,例如 your-agent。创建应用时如果 Slack 不接受占位符,可以先留空或用临时值,后面统一回填真实 webhook URL。

这份 manifest 各部分的用途:

  • display_information.name 和 bot_user.display_name:机器人在 Slack 里的名字,改完需要重装应用;
  • messages_tab_enabled + messages_tab_read_only_enabled:允许从应用 Messages 标签页给机器人发私信;
  • oauth_config.scopes.bot:允许机器人在它所在的频道发帖、读历史、读 @ 提及和私信,并做用户查询;
  • event_subscriptions:告诉 Slack 把哪些消息事件发到 webhook,这里订阅了 app_mention(被 @)、message.channels(频道消息)、message.im(私信);
  • interactivity:启用交互卡片,并把卡片按钮动作发回同一个 webhook。

应用创建后,打开 Install App,选择 Install to Workspace 并批准请求的 scopes。

配置 Slack 凭据

Slack 会向你的 webhook 发请求,Mastra 需要两样东西来完成验签和回写消息。在 Slack 应用设置里复制:

  • Basic Information > App Credentials > Signing Secret
  • OAuth & Permissions > Bot User OAuth Token

写入 Mastra 项目的 .env:

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

Mastra 会自动读取这两个环境变量;验签失败的请求会被适配器直接拒绝(401)。

启动本地服务并用隧道暴露 webhook

Slack 无法把事件发到 localhost,所以本地开发要先把 Mastra 开发服务器暴露出去:

  1. 在项目根目录启动开发服务器:

    npx mastra dev
    

    服务默认监听 http://localhost:4111,src/mastra/ 下的改动会自动重启服务。

  2. 另开终端用隧道暴露 4111 端口(cloudflared 或 ngrok 均可)。这里用 cloudflared:

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

    这条命令会在你的机器上启动一个公网隧道进程,只要终端不关,公网地址就能访问你本地的 4111 端口。

  3. 把生成的隧道主机名作为 <YOUR-PUBLIC-URL>,得到完整 webhook URL,例如:

    https://abc123.trycloudflare.com/api/agents/your-agent/channels/slack/webhook
    

    路径格式是 /api/agents/<AGENT_ID>/channels/slack/webhook,这是 Mastra 为每个适配器自动注册的固定路由,不需要你手写服务端代码。

隧道地址只用于本地开发;部署到正式服务器后要换成生产 URL,因为隧道重启后地址会变。

在 Slack 应用设置里回填 Request URL

回到 Slack 应用设置,把两处请求地址都改成上一步的 webhook URL:

  1. Event Subscriptions:把 Request URL 替换为完整 webhook URL,选择 Save Changes;
  2. Interactivity & Shortcuts:把 Request URL 替换为同一个 webhook URL,选择 Save Changes;
  3. 如果 Slack 提示需要重装应用,打开 OAuth & Permissions 选择 Reinstall to Workspace。

注意顺序:先启动本地服务并拿到隧道地址,再保存 Slack 侧的 Request URL,否则 Slack 校验 URL 时会连不上。

在 Slack 中验证

按 Slack 指南 的验证步骤:

私信验证。 直接给 Slack 机器人用户发一条私信。manifest 里包含 message.im 事件和 im:* scopes,所以私信必须能走通。机器人应在线程/会话中回复;回复内容取决于你给代理配置的模型、指令、记忆和工具,文档不保证固定输出。

频道验证。 先用 /invite @your-bot-name(@your-bot-name 换成你机器人的名字)把机器人拉进目标频道,然后在频道里 @ 它:

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

代理会回复在该消息的线程里。首次被 @ 时,Mastra 默认会从平台拉取该线程最近 10 条消息作为上下文,之后订阅该线程并通过 Mastra 记忆保持完整历史;不想要这个行为可以设置 threadContext: { maxMessages: 0 }(只影响非私信线程),详见 Channels 总览。

webhook 层的判断依据。 Slack 期望在 3 秒内收到 200 确认,投递失败或超时会重试,最多重试 3 次;所以“发出去但没回复”先看服务是否在 3 秒内回了 200(本地冷启动慢时第一次可能需要等一次重试)。确认 200 之后 Slack 不再重试,后续错误由 Mastra 处理,默认行为是把 agent 运行失败的错误信息发到线程里。另外注意:webhook 的 200 表示“已收到”,不代表“已回答”,两者要分开判断。

访问控制与上线注意事项

  • 适配器本身没有用户白名单:应用装好后,工作区里任何人都可以通过私信或在它所在的频道 @ 它来调用代理。Slack 用 signing secret 校验每个请求,Mastra 对每条有效消息都会运行代理。主要控制手段是频道成员关系——机器人不在的频道收不到事件,把机器人移出频道即可切断访问。需要更细粒度控制时,每条请求的 request context 都带发送者的 Slack 用户 ID(channel key 下可取 userId 等字段),可以在 input processor 或工具里按用户 ID 放行/拒绝。
  • 共享频道(Slack Connect)会把外部工作区的人也放进会话,等于把代理的工具和数据暴露给对方,加机器人进共享频道前先确认工具和数据可以对外。
  • 部署到正式环境后,把 Slack 应用设置里的两个 Request URL 都更新为生产 webhook URL,隧道地址是临时的,不能留在生产配置里。
  • 如果部署在 Vercel 这类 serverless 平台,通道需要 waitUntil(Vercel 从 @vercel/functions 传入,AWS Lambda 同理)让函数在代理跑完前不被冻结,并配置跨实例的共享 pub/sub(如 RedisStreamsPubSub)来协调线程租约;Cloudflare Workers 和 Netlify Functions 会自动检测,不需要 waitUntil。细节见 Channels 总览的 Serverless 一节。
  • 平台服务缩到空闲后,Slack 的下一次事件会通过 webhook 把服务唤醒,空闲后第一条回复会慢一些属于预期行为。

完成上面验证(私信有回复、频道 @ 后线程内有回复)即表示接入成功。要继续扩展,可以按需配置 Channels reference 中列出的 inlineMedia、threadContext、textFormat 等选项,或阅读 Channels 总览 了解工具审批卡片和自定义 action 处理。

登录后查看全文
mastra