Slack공급자

SlackProviderAgent를 Slack에 연결하기 위한 관리 경로입니다. 등록하세요Mastra.channels매니페스트 API를 통해 Slack 앱을 프로비저닝하고, OAuth 설치 흐름을 실행하고, 구성 토큰을 순환하고, Slack 이벤트를 Agent에 라우팅합니다. Mastra가 앱 생성 및 설치를 소유하게 하려는 경우에 사용하세요. Slack 앱을 생성하고 범위 및 웹후크를 직접 구성하는 하위 수준 경로의 경우 다음을 사용합니다.createSlackAdapter대리인의channels.adapters대신에.

사용예

Mastra 생성자에 Provider를 등록하세요. 새로 고침 토큰은 일회용이며 시작 시 교체됩니다. 생성된 액세스 토큰은 Mastra.storage에 영구 저장됩니다.

src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'
import { SlackProvider } from '@mastra/slack'

export const mastra = new Mastra({
  storage,
  channels: {
    slack: new SlackProvider({
      refreshToken: process.env.SLACK_APP_CONFIG_REFRESH_TOKEN,
      baseUrl: process.env.MASTRA_BASE_URL,
    }),
  },
})

생성 시 자격 증명을 사용할 수 없는 경우(예: 편집기 UI를 통해 입력하거나 볼트에서 로드한 경우) 해당 자격 증명 없이 공급자를 구성하고 호출합니다.configure() later:

src/mastra/index.ts

const slack = new SlackProvider()

await slack.configure({
  refreshToken: process.env.SLACK_APP_CONFIG_REFRESH_TOKEN,
})

생성자 매개변수

SlackProviderConfig에는 Slack 관련 필드, Slack 어댑터 재정의(toolDisplay, streaming, typingStatus), 그리고 연결된 모든 Agent에 전달되는 엄선된 ChannelConfig 옵션 일부(handlers, inlineMedia, state 등)가 포함됩니다. 모든 필드는 선택 사항입니다.

refreshToken?:

string

자동 토큰 교체에 사용되는 Slack App Configuration 새로 고침 토큰입니다. 일회용이며 교체할 때마다 새 토큰 쌍이 반환됩니다. 나중에 configure()를 통해 제공할 수도 있습니다. 생략하면 Provider가 구성되지 않은 상태로 시작하며 configure()가 호출되거나 저장소에서 토큰을 불러올 때까지 앱을 만들 수 없습니다. api.slack.com/apps의 "Your App Configuration Tokens"에서 생성하세요.

token?:

string

프로그래밍 방식으로 앱을 생성하기 위한 Slack App Configuration 액세스 토큰입니다. Provider가 시작 시 refreshToken을 사용하여 새 토큰으로 교체하므로 선택 사항입니다.

baseUrl?:

string

웹훅 및 OAuth 콜백을 위한 공개 기본 URL입니다. 앱을 생성하기 위해 connect()를 호출할 때 필요합니다. setBaseUrl()을 통해 설정하거나 Mastra 서버 구성에서 자동으로 감지할 수도 있습니다. 로컬 개발에는 cloudflared와 같은 터널을 사용하세요.

encryptionKey?:

string

저장된 민감한 데이터(클라이언트 비밀, 서명 비밀, 봇 토큰)를 위한 암호화 키입니다. 32자 이상의 임의 문자열을 사용하세요. MASTRA_ENCRYPTION_KEY 환경 변수를 통해 설정할 수 있습니다. 생략하면 비밀 정보가 평문으로 저장됩니다(프로덕션에서는 권장하지 않음).

storage?:

ChannelsStorage

설치를 위한 사용자 정의 저장소입니다. 기본값은 전역 저장소에서 가져온 Mastra의 ChannelsStorage입니다. 영구 저장소를 사용할 수 없으면 오류가 발생합니다.

redirectPath?:

string

= "/"

OAuth 완료 후 리디렉션할 경로입니다.

onInstall?:

(installation: SlackInstallation) => Promise<void>

Workspace가 앱을 성공적으로 설치했을 때 호출됩니다.

streaming?:

StreamingConfig | false

= true

Agent 텍스트 델타가 생성되는 대로 Slack에 스트리밍합니다. 게시 및 편집 간격을 사용자 정의하려면 { updateIntervalMs }를 전달하고, 단계가 끝날 때까지 텍스트를 버퍼링하려면 false를 전달하세요. 스트리밍을 비활성화하면 toolDisplay는 정적 모드로 제한됩니다.

textFormat?:

'markdown' | 'plain'

= 'markdown'

Agent의 최종 응답 텍스트에 사용할 방언이며 Slack 어댑터로 전달됩니다. 'markdown'(기본값)은 응답을 Markdown으로 게시하므로 Slack이 굵은 텍스트, 링크, 표를 기본적으로 렌더링합니다. 'plain'은 리터럴 일반 텍스트로 게시하며, Slack mrkdwn을 출력하도록 지시받은 Agent를 위한 예외 처리 수단입니다. 버퍼링된 응답(streaming: false)과 스트리밍 대체 동작에 적용되며, 네이티브 스트리밍은 항상 Markdown입니다.

toolDisplay?:

ToolDisplay

= 'grouped'

Slack에서 Tool 호출을 렌더링하는 방식입니다: 'cards', 'text', 'timeline', 'grouped', 'hidden' 또는 함수입니다. 'hidden'은 Tool 호출 및 결과 렌더링을 완전히 숨깁니다. 'timeline'과 'grouped'에는 스트리밍이 필요합니다. streaming: false이면 정적 모드만 사용할 수 있으며 기본값은 'cards'입니다.

typingStatus?:

boolean | TypingStatusFn

= true

Agent가 작업하는 동안 입력 표시기를 표시합니다. 비활성화하려면 false로 설정하고, 스트림 청크마다 사용자 정의 상태 텍스트를 반환하려면 함수를 전달하세요(해당 청크의 기본값으로 대체하려면 undefined 반환).

waitUntil?:

WaitUntilFn

현재 Slack 웹훅 요청의 waitUntil을 반환합니다. Hono가 플랫폼의 ExecutionContext를 연결할 수 없는 서버리스 런타임(Vercel, AWS Lambda)에서는 필수입니다. 이것이 없으면 200 확인 응답 후 호출이 정지되고 실행이 도중에 종료됩니다. 플랫폼 SDK(예: @vercel/functions)의 원본 waitUntil(promise)을 전달하세요. Cloudflare Workers와 Netlify 사용자는 일반적으로 필요하지 않습니다.

resolveWaitUntil?:

WaitUntilResolver

Resolve waitUntil from the request's Hono Context when the runtime exposes it through the request and core's default doesn't cover it. Resolution order: waitUntil → resolveWaitUntil → core default.

handlers?:

ChannelHandlers

기본 제공 이벤트 핸들러(onDirectMessage, onMention)를 재정의합니다. 이 Provider를 통해 연결된 모든 Agent의 AgentChannels로 전달됩니다.

inlineMedia?:

ChannelConfig['inlineMedia']

Model에 인라인으로 전송할 미디어 유형입니다.

inlineLinks?:

ChannelConfig['inlineLinks']

메시지 텍스트의 URL을 파일 파트로 승격합니다.

threadContext?:

ChannelConfig['threadContext']

Agent가 대화 도중에 참여하면 Slack에서 최근 스레드 메시지를 가져옵니다.

tools?:

ChannelConfig['tools']

채널이 AgentChannels.getTools()를 통해 채널 Tool(add_reaction, remove_reaction)을 노출할지 여부입니다. 이 Tool은 Agent에 자동으로 추가되지 않습니다. 사용하려면 tools: { ...channels.getTools() }를 통해 명시적으로 전달하세요.

state?:

ChannelConfig['state']

메시지 중복 제거, 잠금, 구독을 위한 상태 어댑터입니다. 기본값은 Mastra 인스턴스에 구성된 저장소를 기반으로 하는 MastraStateAdapter이므로 재시작 후에도 구독이 유지됩니다.

chatOptions?:

ChannelConfig['chatOptions']

Chat SDK에 직접 전달되는 추가 옵션입니다.

logger?:

SlackAdapterConfig['logger']

기반 SlackAdapter로 전달되는 로거입니다. 기본값은 어댑터의 ConsoleLogger입니다.

행동 양식

Agent 연결

connect(agentId, options?)

Manifest API를 통해 Agent용 새 Slack 앱을 생성하고, 사용자를 리디렉션할 인증 URL과 함께 OAuth 결과를 반환합니다. baseUrl이 설정되어 있어야 합니다. Agent에 대기 중인 설치가 이미 있으면 중복 앱을 생성하지 않고 기존 인증 URL을 반환합니다.

const result = await slack.connect('support-agent', {
  name: 'Support Bot',
})

// Redirect the user to result.authorizationUrl to install the app

보고:Promise<ChannelConnectResult>

interface ChannelConnectResult {
  type: 'oauth'
  installationId: string
  authorizationUrl: string
}

SlackConnectOptions직렬화 가능하며 저장된 Agent에 대해 저장할 수 있습니다.

name?:

string

Slack 봇의 표시 이름입니다. 기본값은 Agent 이름이며, 없으면 Agent ID입니다.

description?:

string

Slack에 표시되는 봇 설명입니다. 기본값은 "{name} - Powered by Mastra"입니다.

iconUrl?:

string

앱 아이콘으로 사용할 정사각형 이미지(최소 512x512)의 URL입니다. 자동으로 다운로드하여 Slack에 업로드합니다.

manifest?:

(defaults: SlackAppManifest) => SlackAppManifest

Manifest API로 전송하기 전에 Slack 앱 매니페스트를 사용자 정의합니다. 기본 매니페스트를 받아 최종 매니페스트를 반환합니다. 사용자 정의 범위, 추가 이벤트 또는 상호작용 설정에 사용하세요.

redirectUrl?:

string

OAuth가 성공적으로 완료된 후 리디렉션할 URL입니다. 기본값은 Provider의 redirectPath 또는 /입니다.

disconnect(agentId)

해당 앱을 삭제하고 스토리지에서 설치를 제거하여 Slack에서 Agent의 연결을 끊습니다.

await slack.disconnect('support-agent')

보고:Promise<void>

getInstallation(agentId)

Agent의 Slack 설치를 반환하며, 설치가 없으면 null을 반환합니다.

const installation = await slack.getInstallation('support-agent')

보고:Promise<SlackInstallation | null>

listInstallations()

활성 및 보류 중을 포함하여 모든 Slack 설치(공개 정보만)를 나열합니다.

const installations = await slack.listInstallations()

보고:Promise<ChannelInstallationInfo[]>

구성

configure(credentials)

런타임에 Slack 앱 구성 자격 증명을 제공하거나 지웁니다. 생성 시 자격 증명을 사용할 수 없는 경우 사용하세요. 자격 증명을 지우고 저장된 토큰을 삭제하려면 null을 전달하세요.

// Provide credentials (persists to storage immediately)
await slack.configure({ refreshToken: 'xoxe-1-...' })

// Clear credentials and stored tokens
await slack.configure(null)

보고:Promise<void>

setBaseUrl(baseUrl)

웹훅 및 OAuth 콜백에 사용되는 공개 기본 URL을 설정합니다. 생성 시 URL을 알 수 없고 서버 구성에서 자동 감지할 수 없는 경우 이 방법을 사용하세요.

slack.setBaseUrl('https://abc123.trycloudflare.com')

initialize()

저장소의 각 활성 설치에 대해 SlackAdapter를 다시 생성하고 해당 Agent에 AgentChannels를 주입하여 시작 시 Slack 이벤트를 수신하도록 합니다. 새 앱을 자동으로 프로비저닝하지는 않습니다. 앱을 생성하려면 connect()를 사용하세요. Mastra가 이를 자동으로 호출하므로 직접 호출할 일은 거의 없습니다.

await slack.initialize()

보고:Promise<void>

기본 매니페스트

connect()가 Slack 앱을 빌드할 때 생성된 매니페스트는 기본 봇 범위 및 이벤트 구독 세트를 요청합니다. connect()의 manifest 옵션으로 재정의하세요.

기본 봇 범위	기본 봇 이벤트
chat:write	app_mention
chat:write.public	message.channels
im:write	message.groups
channels:history	message.im
channels:read	message.mpim
groups:history
groups:read
im:history
im:read
mpim:history
mpim:read
app_mentions:read
users:read
reactions:write
files:read
assistant:write

공급자에 액세스

등록할 때 사용한 ID를 키로 하는 channels getter를 통해 등록된 Provider에 접근합니다.

const result = await mastra.channels.slack.connect('support-agent')

키가 런타임에만 알려진 경우 문자열 ID로 키를 찾고 구체적인 유형을 전달합니다.

const slack = mastra.getChannelProvider<SlackProvider>('slack')
const result = await slack.connect('support-agent')

저장 요구 사항

SlackProvider가 설치 및 교체되는 구성 토큰을 암호화하고 영구 저장하려면 Mastra에 영구 저장소가 필요합니다. 영구 저장소를 사용할 수 없고 사용자 정의 storage도 전달하지 않으면 생성자에서 오류가 발생합니다.

관련된

• 채널 Provider: SlackProvider가 구현하는 인터페이스
• 채널: 개념, 플랫폼 설정 및 createSlackAdapter 경로
• 채널 참조: Agent 생성자의 channels 구성