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

# ToolProvider

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

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

## 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](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!,
    }),
  },
})
```

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

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

### 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`。兩者都省略便無法隔離呼叫者。