ToolProvider

ToolProvider 介面定義 Editor 如何探索並解析外部平台提供的整合 Tool。Mastra 包含兩個內建實作：ComposioToolProvider 與 ArcadeToolProvider。

Provider 設定與 Studio 工作流程請參閱 Editor Tool。已儲存的選擇與解析行為請參閱 Tool 設定。

ToolProvider 介面

Provider 會公開中繼資料，以及舊版探索與解析方法。Agent Builder 整合也可以實作選用的 VNext 目錄、連線、授權與健康狀態方法。

info:

ToolProviderInfo

Provider ID、名稱與說明。

displayName?:

string

Tool 選擇器中顯示的選用名稱。預設為 info.name。

capabilities?:

ToolProviderCapabilities

靜態連線與撤銷能力。VNext Provider 的必要項目。

defaultScope?:

'per-author' | 'caller-supplied'

預設連線身分範圍。省略時預設為 'per-author'。

listToolkits()?:

() => Promise<ToolProviderListResult<ToolProviderToolkit>>

透過舊版介面列出可用的 toolkit。

listTools(params?):

(params?: ListToolProviderToolsOptions) => Promise<ToolProviderListResult<ToolProviderToolInfo>>

列出 Tool，並可選擇套用 toolkit、搜尋與分頁篩選條件。

getToolSchema(slug)?:

(slug: string) => Promise<Record<string, unknown> | null>

透過舊版介面傳回 Tool 輸入 schema。

resolveTools(slugs, configs?, options?):

(slugs: string[], configs?: Record<string, StorageToolConfig>, options?: ResolveToolProviderToolsOptions) => Promise<Record<string, ToolAction>>

將舊版 Tool 選擇解析為可執行的 Mastra Tool。

listToolkitsVNext()?:

() => Promise<ListToolkitsResult>

列出 Agent Builder 與 Editor 允許的 toolkit。

listToolsVNext(options?)?:

(options?: ListToolsOpts) => Promise<ListToolsResult>

使用 toolkit、搜尋與分頁選項，列出允許的 Tool。

resolveToolsVNext(options)?:

(options: ResolveToolsOpts) => Promise<Record<string, ToolAction>>

為一組 slug 與一個已授權連線解析 Tool。

authorize(options)?:

(options: AuthorizeOpts) => Promise<{ url: string; authId: string }>

啟動授權流程。

listConnectionFields(options)?:

(options: { toolkit: string }) => Promise<ConnectionField[]>

列出授權 toolkit 所需的 Provider 專屬值。

getAuthStatus(authId)?:

(authId: string) => Promise<AuthFlowStatus>

傳回授權流程的狀態。

getConnectionStatus(options)?:

(options: { items: Array<{ connectionId: string; toolkit: string }> }) => Promise<Record<string, { connected: boolean }>>

檢查一批連線是否仍在作用中。

listConnections(options)?:

(options: ListConnectionsOpts) => Promise<ListConnectionsResult>

列出某使用者與 toolkit 現有的 Provider 連線。

getHealth()?:

() => Promise<ToolProviderHealth>

傳回 Provider 設定與可連線性健康狀態。

revokeConnection(connectionId)?:

(connectionId: string) => Promise<void>

撤銷 Provider 連線。

---

ComposioToolProvider

連線至 Composio，以存取數百個整合 Tool。

使用範例

src/mastra/index.ts

import { MastraEditor } from '@mastra/editor'
import { ComposioToolProvider } from '@mastra/editor/composio'

const editor = new MastraEditor({
  toolProviders: {
    composio: new ComposioToolProvider({
      apiKey: process.env.COMPOSIO_API_KEY!,
    }),
  },
})

建構函式參數

apiKey:

string

你的 Composio API 金鑰。

allowedToolkits?:

readonly string[]

Toolkit slug 允許清單。支援完全符合與後綴萬用字元。

allowedTools?:

Readonly<Record<string, readonly string[]>>

各 toolkit 的 Tool slug 允許清單。支援完全符合與前綴萬用字元。

defaultScope?:

'per-author' | 'caller-supplied'

= 'per-author'

連線身分範圍。預設為 per-author。

Tool slug

Composio Tool 使用大寫 slug 格式：GITHUB_CREATE_ISSUE、SLACK_SEND_MESSAGE。

驗證

連線預設使用 per-author 範圍。設定 defaultScope: 'caller-supplied'，可依 request context 中 MASTRA_RESOURCE_ID_KEY 解析出的呼叫者身分分組授權。請確保每個已驗證的請求都提供穩定且唯一的資源 ID。使用 MastraAuthWorkos 時，請設定 mapUserToResourceId，以便從已驗證的使用者設定此值。

連線管理 Tool

Composio 提供可從 Agent 對話啟動及監控授權的 Tool。設定 allowedToolkits 時，請加入 composio 以提供這些 Tool：

src/mastra/index.ts

const editor = new MastraEditor({
  toolProviders: {
    composio: new ComposioToolProvider({
      apiKey: process.env.COMPOSIO_API_KEY!,
      allowedToolkits: ['composio', 'gmail'],
      defaultScope: 'caller-supplied',
    }),
  },
})

只加入 Agent 所需的連線管理 Tool：

Tool	行為
COMPOSIO_MANAGE_CONNECTIONS	透過呼叫者擁有的工作階段，在對話中建立授權連結。
COMPOSIO_WAIT_FOR_CONNECTIONS	等待呼叫者完成授權，再讓 Agent 繼續。

COMPOSIO_WAIT_FOR_CONNECTIONS 為選用項目。若未加入，請完成授權後回到對話，再要求 Agent 繼續。已連線的帳戶仍會與呼叫者資源 ID 建立關聯，以供後續請求使用。

---

ArcadeToolProvider

連線至 Arcade，以使用內建驗證功能的精選 Tool 目錄。

使用範例

src/mastra/index.ts

import { MastraEditor } from '@mastra/editor'
import { ArcadeToolProvider } from '@mastra/editor/arcade'

const editor = new MastraEditor({
  toolProviders: {
    arcade: new ArcadeToolProvider({
      apiKey: process.env.ARCADE_API_KEY!,
    }),
  },
})

建構函式參數

apiKey:

string

你的 Arcade API 金鑰。

baseURL?:

string

Arcade API 的自訂基底 URL。

Tool slug

Arcade Tool 使用 Toolkit.ToolName 格式：Github.GetRepository、Slack.SendMessage。

驗證

舊版 Arcade 解析器會在 request context 提供 resourceId 時使用該值，否則會依序改用提供的 userId 與共用的 default 身分。只有刻意共用的整合才應使用 default。在租戶隔離的部署環境中，請提供受信任且穩定的 resourceId 或明確的 userId。兩者皆省略時，無法隔離呼叫者。