跳到主要内容

ChannelProvider

ChannelProvider 是平台集成用于将 Agent 连接到消息平台的接口。Provider 负责集成的完整生命周期：应用预配和 OAuth、webhook 路由和事件处理、adapter 创建和 Agent 连接，以及凭证管理。

在 Mastra 构造函数的 channels 下注册 Provider，并使用你选择的 id 作为键。每个 Provider 的路由都会自动合并到服务器的 API 路由中，并且 initialize() 会在 Mastra 启动期间运行。

src/mastra/index.ts
import { Mastra } from '@mastra/core/mastra'
import { SlackProvider } from '@mastra/slack'

export const mastra = new Mastra({
  channels: {
    slack: new SlackProvider({
      refreshToken: process.env.SLACK_REFRESH_TOKEN!,
      baseUrl: process.env.MASTRA_BASE_URL,
    }),
  },
})

Provider 的 baseUrl 是平台发送 webhook 和事件的公共 URL。在生产环境中，这是已部署的 Mastra 服务器 URL。在本地开发中，平台无法访问 http://localhost:4111，因此请运行隧道（例如 cloudflared 或 ngrok），并将 baseUrl 指向隧道 URL（例如 https://abc123.trycloudflare.com），让事件能到达本地开发进程。

SlackProvider 是第一个内置实现。你可以通过实现此接口构建自定义 Provider。

属性
属性的直接链接

id:

string
此 channel 类型的唯一标识符，例如 'slack' 或 'discord'。路由事件以及从 Mastra 中查找 Provider 时用作键。

方法
方法的直接链接

getRoutes:

() => ApiRoute[]
返回此 channel 的 API 路由（OAuth、webhook、事件）。这些路由会自动合并到服务器的 apiRoutes 中。

initialize?:

() => Promise<void>
在所有 Agent 注册后，于 Mastra 初始化期间调用。可用于恢复活跃安装等异步设置。不会预配新应用。

configure?:

(credentials: Record<string, unknown> | null) => void | Promise<void>
在 runtime 提供或清除平台凭证。传入 null 可清除凭证并删除存储的 token。

getInfo?:

() => ChannelPlatformInfo
返回 Editor UI 的发现元数据：平台名称、配置状态和连接选项 schema。

connect?:

(agentId: string, options?: Record<string, unknown>) => Promise<ChannelConnectResult>
将 Agent 连接到平台。返回一个可辨识结果，描述完成连接所需的授权流程。

disconnect?:

(agentId: string) => Promise<void>
断开 Agent 与平台的连接。删除平台应用并清理存储的状态。

listInstallations?:

() => Promise<ChannelInstallationInfo[]>
列出此平台的活跃安装。仅返回公共信息，绝不返回 secret。

访问 Provider
访问 Provider的直接链接

通过 channels getter 访问已注册的 Provider，并使用注册时的 id 作为键。getter 的类型源自构造函数配置，因此 mastra.channels.slack 是具体的 Provider，并包含其完整方法。

await mastra.channels.slack.configure({ refreshToken })

如果仅在 runtime 才知道键，请改为按字符串 id 查找 Provider。getChannelProvider 将具体类型作为泛型，而 getChannelProviders 返回以 id 为键的所有已注册 Provider。

import type { SlackProvider } from '@mastra/slack'

const slack = mastra.getChannelProvider<SlackProvider>('slack')
const all = mastra.getChannelProviders()
On this page