ToolProvider

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

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

ToolProvider 介面

Provider 會提供 metadata 及舊版探索和解析方法。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 input 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!,
    }),
  },
})

Constructor 參數

apiKey:

string

你的 Composio API 金鑰。

allowedToolkits?:

readonly string[]

Toolkit slug 允許清單，支援完全相符及 suffix wildcard。

allowedTools?:

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

每個 toolkit 的 Tool slug 允許清單，支援完全相符及 prefix wildcard。

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 解析的呼叫者身分劃分授權。請確保每個已驗證請求都提供穩定且唯一的 resource 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	透過呼叫者擁有的 session，在對話中建立授權連結。
COMPOSIO_WAIT_FOR_CONNECTIONS	等待呼叫者完成授權，然後 Agent 才繼續。

COMPOSIO_WAIT_FOR_CONNECTIONS 是選用的。如不使用它，請完成授權後返回對話，再要求 Agent 繼續。已連接帳戶會維持與呼叫者 resource 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!,
    }),
  },
})

Constructor 參數

apiKey:

string

你的 Arcade API 金鑰。

baseURL?:

string

Arcade API 的自訂 base URL。

Tool slug

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

驗證

舊版 Arcade resolver 會在可用時使用 request context 的 resourceId，否則改用提供的 userId，再改用共用的 default 身分。只有刻意共用的整合才應使用 default。在 tenant 隔離的部署中，請提供可信且穩定的 resourceId 或明確的 userId。兩者都省略便無法隔離呼叫者。