ToolProvider

ToolProvider インターフェースは、Editor が外部プラットフォームの統合 Tool を検出して解決する方法を定義します。Mastra には、ComposioToolProvider と ArcadeToolProvider という2つの組み込み実装があります。

Provider の設定と Studio のワークフローについては、Editor の Tool を参照してください。保存される選択内容と解決時の動作については、Tool 設定を参照してください。

ToolProvider インターフェース

Provider は、メタデータと従来の検出・解決メソッドを公開します。Agent Builder の統合では、任意の VNext カタログ、接続、認可、ヘルスチェックの各メソッドも実装できます。

info:

ToolProviderInfo

Provider の ID、名前、説明。

displayName?:

string

Tool ピッカーに表示される任意の名前。デフォルトは info.name です。

capabilities?:

ToolProviderCapabilities

静的な接続および取り消し機能。VNext Provider では必須です。

defaultScope?:

'per-author' | 'caller-supplied'

デフォルトの接続 ID スコープ。省略時のデフォルトは 'per-author' です。

listToolkits()?:

() => Promise<ToolProviderListResult<ToolProviderToolkit>>

従来のインターフェースを通じて、利用可能な Toolkit を一覧表示します。

listTools(params?):

(params?: ListToolProviderToolsOptions) => Promise<ToolProviderListResult<ToolProviderToolInfo>>

任意の Toolkit、検索、ページネーションの各フィルターを指定して Tool を一覧表示します。

getToolSchema(slug)?:

(slug: string) => Promise<Record<string, unknown> | null>

従来のインターフェースを通じて、Tool の入力スキーマを返します。

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>>

1組の slug と1つの認可済み接続に対して 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

数百の統合 Tool にアクセスできるように、Composio に接続します。

使用例

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 キー。

allowedToolkits?:

readonly string[]

Toolkit slug の許可リスト。完全一致と末尾のワイルドカードをサポートします。

allowedTools?:

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

Toolkit ごとの Tool slug 許可リスト。完全一致と先頭のワイルドカードをサポートします。

defaultScope?:

'per-author' | 'caller-supplied'

= 'per-author'

接続 ID のスコープ。デフォルトは per-author です。

Tool slug

Composio の Tool は大文字の slug 形式を使用します：GITHUB_CREATE_ISSUE、SLACK_SEND_MESSAGE。

認証

接続では、デフォルトで作成者ごとのスコープを使用します。defaultScope: 'caller-supplied' を設定すると、リクエストコンテキストの MASTRA_RESOURCE_ID_KEY から解決された呼び出し元 ID ごとに認可を分類できます。認証済みの各リクエストに、安定した一意のリソース ID が含まれていることを確認してください。MastraAuthWorkos を使用する場合は、認証済みユーザーからこの値を設定するように mapUserToResourceId を構成します。

接続管理 Tool

Composio は、Agent のチャットから認可を開始して監視するための Tool を提供します。allowedToolkits を設定する場合は、これらの Tool を利用できるように composio を含めます。

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	呼び出し元が所有するセッションを通じて、チャット内に認可リンクを作成します。
COMPOSIO_WAIT_FOR_CONNECTIONS	Agent が続行する前に、呼び出し元が認可を完了するまで待機します。

COMPOSIO_WAIT_FOR_CONNECTIONS は任意です。使用しない場合は、認可を完了してチャットに戻り、Agent に続行するよう依頼します。接続されたアカウントは、以降のリクエストでも呼び出し元のリソース ID に関連付けられたままになります。

---

ArcadeToolProvider

認証機能を組み込んだ厳選された Tool カタログを利用できるように、Arcade に接続します。

使用例

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 キー。

baseURL?:

string

Arcade API のカスタムベース URL。

Tool slug

Arcade の Tool は Toolkit.ToolName 形式を使用します：Github.GetRepository、Slack.SendMessage。

認証

従来の Arcade リゾルバーは、利用可能な場合、リクエストコンテキストの resourceId を使用します。利用できない場合は、指定された userId、共有の default ID の順にフォールバックします。default は、意図的に共有する統合にのみ使用してください。テナントを分離したデプロイでは、信頼できる安定した resourceId または明示的な userId を指定します。両方を省略すると、呼び出し元は分離されません。