> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt

# ToolProvider

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

Provider 設定與 Studio 工作流程請參閱 [Editor Tool](https://mastra.zisheng.pro/zh-TW/docs/editor/overview)。已儲存的選擇與解析行為請參閱 [Tool 設定](https://mastra.zisheng.pro/zh-TW/reference/editor/tools)。

## 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](https://composio.dev)，以存取數百個整合 Tool。

### 使用範例

```typescript
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。 (Default: `'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：

```typescript
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](https://arcade.dev)，以使用內建驗證功能的精選 Tool 目錄。

### 使用範例

```typescript
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`。兩者皆省略時，無法隔離呼叫者。