ToolProvider

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

有关 Provider 设置和 Studio 工作流，请参阅 Editor Tool。有关已存储选择和解析行为，请参阅 Tool 配置。

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，以访问数百个集成 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 key。

allowedToolkits?:

readonly string[]

Toolkit slug allowlist。支持精确匹配和后缀通配符。

allowedTools?:

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

每个 toolkit 的 Tool slug allowlist。支持精确匹配和前缀通配符。

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

使用示例

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 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。两者均省略时，调用者之间不会隔离。