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

# ToolProvider

`ToolProvider` 接口定义 Editor 如何发现和解析外部平台提供的集成 Tool。Mastra 包含两个内置实现：`ComposioToolProvider` 和 `ArcadeToolProvider`。

有关 Provider 设置和 Studio 工作流，请参阅 [Editor Tool](https://mastra.zisheng.pro/docs/editor/overview)。有关已存储选择和解析行为，请参阅 [Tool 配置](https://mastra.zisheng.pro/reference/editor/tools)。

## ToolProvider 接口

Provider 公开元数据以及旧版发现和解析方法。Agent Builder 集成还可以实现可选的 VNext catalog、连接、授权和健康状态方法。

**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 key。

**allowedToolkits** (`readonly string[]`): Toolkit slug allowlist。支持精确匹配和后缀通配符。

**allowedTools** (`Readonly<Record<string, readonly string[]>>`): 每个 toolkit 的 Tool slug allowlist。支持精确匹配和前缀通配符。

**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 catalog 和内置身份验证。

### 使用示例

```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 key。

**baseURL** (`string`): Arcade API 的自定义 base URL。

### Tool slug

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

### 身份验证

旧版 Arcade resolver 会优先使用 request context 中的 `resourceId`。如果不可用，则依次回退到提供的 `userId` 和共享的 `default` 身份。仅对有意共享的集成使用 `default`。在租户隔离的部署中，请提供可信且稳定的 `resourceId` 或显式 `userId`。两者均省略时，调用者之间不会隔离。