跳至主要內容

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>
在運行期間提供或清除平台憑證。傳入 null 可清除憑證並刪除已儲存的 token。

getInfo?:

() => ChannelPlatformInfo
傳回編輯器 UI 的探索中繼資料：平台名稱、設定狀態及連接選項 schema。

connect?:

(agentId: string, options?: Record<string, unknown>) => Promise<ChannelConnectResult>
將 Agent 連接至平台。傳回可判別的結果，說明完成連接所需的授權流程。

disconnect?:

(agentId: string) => Promise<void>
中斷 Agent 與平台的連接。刪除平台應用程式並清理已儲存的狀態。

listInstallations?:

() => Promise<ChannelInstallationInfo[]>
列出此平台的有效安裝項目。只傳回公開資料，絕不包含機密資料。

存取 Provider
存取 Provider 的直接連結

透過 channels getter 存取已註冊的 Provider，並以註冊時所用的 id 作為鍵。Getter 的類型由建構函數設定推斷，因此 mastra.channels.slack 是具備完整方法介面的具體 Provider。

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

如果只有在運行期間才知道鍵，可改為以字串 id 查找 Provider。getChannelProvider 接受具體類型作為泛型，而 getChannelProviders 會傳回所有已註冊的 Provider，並以 id 作為鍵。

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

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