跳至主要內容

ChannelProvider

ChannelProvider 是平台整合用來將 Agent 連接至訊息平台的介面。Provider 擁有整項整合的完整生命週期：app 佈建與 OAuth、webhook 路由與事件處理、adapter 建立與 Agent 接線，以及認證管理。

在 Mastra 建構函式的 channels 下註冊 Provider，並以你選擇的 ID 作為 key。每個 Provider 的 route 都會自動合併至伺服器的 API route，且 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，因此請執行 tunnel（例如 cloudflared 或 ngrok），並將 baseUrl 指向 tunnel URL（例如 https://abc123.trycloudflare.com），讓事件送達本機開發處理程序。

SlackProvider 是第一個內建實作。實作此介面即可建立自訂 Provider。

屬性
「屬性」的直接連結

id:

string
此 channel 類型的唯一識別碼，例如 'slack' 或 'discord'。路由事件及從 Mastra 查找 Provider 時，會使用此值作為 key。

方法
「方法」的直接連結

getRoutes:

() => ApiRoute[]
傳回此 channel 的 API route（OAuth、webhook、事件）。這些 route 會自動合併至伺服器的 apiRoutes。

initialize?:

() => Promise<void>
所有 Agent 註冊完成後，在 Mastra 初始化期間呼叫。可用於還原作用中 installation 等非同步設定工作，但不會佈建新的 app。

configure?:

(credentials: Record<string, unknown> | null) => void | Promise<void>
在執行階段提供或清除平台認證。傳入 null 可清除認證並刪除已儲存的 token。

getInfo?:

() => ChannelPlatformInfo
傳回 editor UI 的探索中繼資料：平台名稱、設定狀態與 connect 選項 schema。

connect?:

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

disconnect?:

(agentId: string) => Promise<void>
中斷 Agent 與平台的連線。刪除平台 app 並清除已儲存的狀態。

listInstallations?:

() => Promise<ChannelInstallationInfo[]>
列出此平台作用中的 installation。只傳回公開資訊，絕不傳回 secret。

存取 Provider
「存取 Provider」的直接連結

透過 channels getter 存取已註冊的 Provider，並以註冊時使用的 ID 作為 key。getter 的型別來自建構函式設定，因此 mastra.channels.slack 是具有完整方法介面的具體 Provider。

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

若只在執行階段才知道 key，請改用字串 ID 查找 Provider。getChannelProvider 接受具體型別作為泛型，而 getChannelProviders 會傳回以 ID 為 key 的所有已註冊 Provider。

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

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