Tool 제공자

그만큼ToolProvider인터페이스는 편집기가 외부 플랫폼에서 통합 Tool을 검색하고 해결하는 방법을 정의합니다. Mastra에는 두 가지 내장 구현이 포함되어 있습니다.ComposioToolProvider그리고ArcadeToolProvider.

Provider 설정과 Studio Workflow는 Editor Tool을 참조하세요. 저장된 선택 항목과 해석 동작은 Tool 구성을 참조하세요.

ToolProvider 인터페이스

공급자는 메타데이터와 레거시 검색 및 해결 방법을 공개합니다. 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>>

레거시 인터페이스를 통해 사용 가능한 툴킷을 나열합니다.

listTools(params?):

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

선택적 툴킷, 검색 및 페이지네이션 필터를 적용해 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에서 허용된 툴킷을 나열합니다.

listToolsVNext(options?)?:

(options?: ListToolsOpts) => Promise<ListToolsResult>

툴킷, 검색 및 페이지네이션 옵션을 적용해 허용된 Tool을 나열합니다.

resolveToolsVNext(options)?:

(options: ResolveToolsOpts) => Promise<Record<string, ToolAction>>

하나의 슬러그 집합과 하나의 승인된 연결에 대한 Tool을 해석합니다.

authorize(options)?:

(options: AuthorizeOpts) => Promise<{ url: string; authId: string }>

승인 흐름을 시작합니다.

listConnectionFields(options)?:

(options: { toolkit: string }) => Promise<ConnectionField[]>

툴킷 승인에 필요한 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>

사용자와 툴킷의 기존 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[]

툴킷 슬러그 허용 목록입니다. 정확한 일치와 접미사 와일드카드를 지원합니다.

allowedTools?:

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

툴킷별 Tool 슬러그 허용 목록입니다. 정확한 일치와 접두사 와일드카드를 지원합니다.

defaultScope?:

'per-author' | 'caller-supplied'

= 'per-author'

연결 ID 범위입니다. 기본값은 per-author입니다.

Tool 슬러그

Composio Tool은 대문자 슬러그 형식을 사용합니다.GITHUB_CREATE_ISSUE, SLACK_SEND_MESSAGE.

입증

연결은 기본적으로 작성자별 범위를 사용합니다. 요청 컨텍스트의 MASTRA_RESOURCE_ID_KEY에서 해석한 호출자 ID별로 승인을 분류하려면 defaultScope: 'caller-supplied'를 설정하세요. 인증된 각 요청이 안정적이고 고유한 리소스 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와 연결된 상태로 유지됩니다.

---

아케이드Tool공급자

인증 기능이 내장된 엄선된 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 슬러그

아케이드 Tool 사용Toolkit.ToolName format: Github.GetRepository, Slack.SendMessage.

입증

레거시 Arcade 리졸버는 사용할 수 있는 경우 요청 컨텍스트의 resourceId를 사용합니다. 그렇지 않으면 제공된 userId를 사용하고, 이 값도 없으면 공유 default ID를 사용합니다. 의도적으로 공유하는 통합에만 default를 사용하세요. 테넌트 격리 배포에서는 신뢰할 수 있고 안정적인 resourceId 또는 명시적 userId를 제공하세요. 둘 다 생략하면 호출자가 격리되지 않습니다.