느슨하게

사람들이 공유 채널 스레드나 다이렉트 메시지로 메시지를 보낼 수 있도록 Slack에 Agent를 추가하세요. 누군가 메시지를 보내면 Mastra는 일반 Agent 파이프라인을 통해 Agent를 실행하고 응답을 다시 Slack으로 스트리밍합니다. Slack 어댑터는 Slack AI 표시기와 대화형 카드를 자동으로 처리합니다.

설치
설치에 대한 직접 링크

Chat SDK에서 Slack 어댑터를 설치합니다.

npm
pnpm
Yarn
Bun

npm install @chat-adapter/slack

pnpm add @chat-adapter/slack

yarn add @chat-adapter/slack

bun add @chat-adapter/slack

추가하다createSlackAdapter() to the agent's channels.adapters object:

src/mastra/agents/your-agent.ts
import { Agent } from '@mastra/core/agent'
import { createSlackAdapter } from '@chat-adapter/slack'

export const yourAgent = new Agent({
  id: 'your-agent',
  name: 'Your Agent',
  instructions: 'Help people plan tasks, answer questions, and coordinate work in Slack.',
  model: 'anthropic/claude-opus-4-7',
  channels: {
    adapters: {
      slack: createSlackAdapter(),
    },
  },
})

Slack 앱 만들기
Slack 앱 만들기에 대한 직접 링크

Agent를 연결하려면 실행하려는 작업 공간에서 Slack 앱을 생성하세요. Slack 앱은 Slack의 Agent 표시, 해당 기능 및 수신하는 이벤트를 제어합니다.

이 가이드에서는manifest: Slack 앱 설정을 대신 생성해 주는 구성 파일입니다. 자신의 Workspace에 Agent를 추가할 때 가장 빠른 방법입니다. 다른 Workspace가 Agent를 설치하는 플랫폼 OAuth 흐름은 다루지 않습니다.

매니페스트에서 Slack 앱을 만듭니다.

열려 있는api.slack.com/apps.
선택하다Create an app.
선택하다From a manifest.
Agent를 실행해야 하는 작업공간을 선택하세요.
이 매니페스트를 붙여넣은 다음 선택하세요.Create. Slack은 JSON과 YAML을 모두 지원하므로 앱 생성 모달에 표시된 형식과 일치하는 탭을 사용하세요:

JSON
YAML

{
  "display_information": {
    "name": "mastra-agent"
  },
  "features": {
    "app_home": {
      "home_tab_enabled": false,
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    },
    "bot_user": {
      "display_name": "mastra-agent",
      "always_online": true
    }
  },
  "oauth_config": {
    "scopes": {
      "bot": [
        "im:write",
        "app_mentions:read",
        "channels:history",
        "channels:read",
        "chat:write",
        "users:read",
        "im:read",
        "im:history"
      ]
    },
    "pkce_enabled": false
  },
  "settings": {
    "event_subscriptions": {
      "request_url": "https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook",
      "bot_events": ["app_mention", "message.channels", "message.im"]
    },
    "interactivity": {
      "is_enabled": true,
      "request_url": "https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook"
    },
    "org_deploy_enabled": false,
    "socket_mode_enabled": false,
    "token_rotation_enabled": false,
    "is_mcp_enabled": false
  }
}

display_information:
  name: mastra-agent
features:
  app_home:
    home_tab_enabled: false
    messages_tab_enabled: true
    messages_tab_read_only_enabled: false
  bot_user:
    display_name: mastra-agent
    always_online: true
oauth_config:
  scopes:
    bot:
      - im:write
      - app_mentions:read
      - channels:history
      - channels:read
      - chat:write
      - users:read
      - im:read
      - im:history
  pkce_enabled: false
settings:
  event_subscriptions:
    request_url: https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook
    bot_events:
      - app_mention
      - message.channels
      - message.im
  interactivity:
    is_enabled: true
    request_url: https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook
  org_deploy_enabled: false
  socket_mode_enabled: false
  token_rotation_enabled: false
  is_mcp_enabled: false

이 매니페스트는 다음을 구성합니다.

display_information.name그리고features.bot_user.display_name: Slack에서 Agent의 이름을 설정하세요. 이름은 언제든지 변경할 수 있습니다. 이름이나 권한을 변경한 후에는 앱을 다시 설치해야 합니다.
app_home.messages_tab_enabled그리고app_home.messages_tab_read_only_enabled: Enable direct messages from the Slack app's Messages tab.
always_online: Slack 봇 사용자를 항상 사용 가능한 상태로 표시합니다.
oauth_config.scopes.bot: 봇이 존재하는 채널에 메시지를 게시하고 읽을 수 있는 권한을 부여합니다. 또한 사용자 조회와 함께 멘션 및 직접 메시지도 다룹니다.
event_subscriptions: 웹후크에 보낼 메시지 이벤트를 Slack에 알려줍니다.
interactivity: 대화형 카드를 활성화하고 Slack에게 카드 작업을 보낼 위치를 알려줍니다.

앱이 생성된 후 엽니다.Install App, select Install to Workspace, and approve the requested scopes.

Slack 자격 증명 설정
Slack 자격 증명 설정에 대한 직접 링크

Mastra에서 Slack 자격 증명을 설정하면 Slack 요청을 확인하고 메시지를 Slack으로 다시 보낼 수 있습니다.

Slack 앱 설정에서 다음 값을 복사하세요.

기본정보 > App Credentials > Signing Secret
OAuth 및 권한 > Bot User OAuth Token

Mastra 환경에서 설정하십시오.

.env
SLACK_SIGNING_SECRET=your-signing-secret
SLACK_BOT_TOKEN=xoxb-your-bot-token

Mastra는 이러한 환경 변수를 자동으로 읽습니다.

웹훅 경로 구성
웹훅 경로 구성에 대한 직접 링크

Slack은 웹후크를 통해 채널 활동을 Mastra로 보냅니다. 웹후크는 새 메시지, 멘션, 사용자의 대화형 카드 선택 등 어떤 일이 발생할 때 Slack이 호출하는 HTTP 엔드포인트입니다.

Mastra는 Agent에 대한 Slack 웹훅 경로를 자동으로 등록합니다.

/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook

공개 Mastra 서버 URL과 생성된 경로에서 웹훅 URL을 빌드합니다.

https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook

Slack은 다음으로 이벤트를 보낼 수 없습니다.localhost. 로컬 개발 시에는 Mastra 개발 서버를 계속 실행하고 http://localhost:4111 를 터널을 통해 외부에 노출한 후 Slack에 요청 URL을 저장하세요.

다음과 같은 터널을 사용하십시오.cloudflared or ngrok for local development:

npm
pnpm
Yarn
Bun

npx cloudflared tunnel --url http://localhost:4111

pnpm dlx cloudflared tunnel --url http://localhost:4111

yarn dlx cloudflared tunnel --url http://localhost:4111

bun x cloudflared tunnel --url http://localhost:4111

생성된 터널 호스트를 다음과 같이 사용합니다.<YOUR-PUBLIC-URL>, for example:

https://abc123.trycloudflare.com/api/agents/your-agent/channels/slack/webhook

Slack에서 요청 URL을 업데이트합니다.

Slack 앱 설정에서 다음을 엽니다.Event Subscriptions.
바꾸다Request URL with the final webhook URL.
선택하다Save Changes.
열려 있는Interactivity & Shortcuts.
바꾸다Request URL with the same webhook URL.
선택하다Save Changes.
Slack에서 앱을 다시 설치하라는 메시지가 표시되면 다음을 엽니다.OAuth & Permissions and select Reinstall to Workspace.

Slack에서 사용해 보세요
Slack에서 사용해 보세요에 대한 직접 링크

Slack 봇 사용자와 다이렉트 메시지를 열고 메시지를 보냅니다. 매니페스트에 다음이 포함되어 있기 때문에 직접 메시지가 작동합니다.message.im event and im:* scopes.

채널에서 Agent를 사용하려면 먼저 Slack 봇 사용자를 초대하세요.

/invite @your-bot-name

채널에서 봇을 언급하세요.

@your-bot-name What can you help me with?

Agent는 스레드에서 응답합니다. 응답 내용은 Agent에 구성된 Model, 지침, Memory 및 Tool에 따라 다릅니다.

입증
입증에 대한 직접 링크

Slack 어댑터에는 기본 제공 사용자 허용 목록이 없습니다. 앱이 설치되면 워크스페이스에 있는 누구나 Agent에게 다이렉트 메시지를 보내거나 Agent가 멤버인 채널에서 언급하여 Agent와 대화할 수 있습니다. Slack은 서명 비밀을 사용하여 각 요청을 확인하고 Mastra는 웹훅이 수신하는 모든 유효한 메시지에 대해 Agent를 실행합니다.

액세스를 제어하는 주요 메커니즘은 채널 멤버십입니다. 봇은 다이렉트 메시지와 초대된 채널에서만 이벤트를 수신하므로 봇이 속한 채널 집합에 따라 봇에 접근할 수 있는 사람이 정의됩니다. 봇이 응답하지 않아야 하는 채널에 접근하지 못하게 하고 채널에서 제거하여 액세스를 차단하세요.

더 세밀하게 제어하려면 발신자의 신원을 확인하세요. 모든 요청은 채널에서 보낸 사람의 Slack 사용자 ID를 전달합니다.request context가 포함되므로 Agent가 작업하기 전에 입력 프로세서나 Tool에서 특정 사용자를 허용하거나 거부할 수 있습니다.

Slack 웹훅 경로는 Mastra의 경로에서 제외됩니다.server authentication. Slack은 bearer token을 전송할 수 없으므로 Mastra는 채널 webhook을 공개 route로 등록하고 대신 Slack signing secret으로 각 요청을 검증합니다. 이는 MastraAuthSimple같은 Provider를 활성화한 경우에도 동일합니다. 나머지 API는 계속 보호되지만 webhook route는 서버 인증이 아닌 signing secret을 사용합니다. SLACK_SIGNING_SECRET 를 설정하여 어댑터가 Slack이 서명하지 않은 요청을 거부할 수 있도록 하세요.

외부 채널
외부 채널에 대한 직접 링크

공유채널(Slack Connect)을 사용하면 다른 Workspace의 사용자가 대화에 참여할 수 있습니다. Workspace 구성원이 공유 채널에 bot을 추가하면 조직 외부의 외부 구성원을 포함해 해당 채널의 모든 사용자가 Agent와 대화할 수 있습니다. Agent에 접근할 수 있는 사람은 누구든 Agent가 접근할 수 있는 Tool과 데이터에도 접근할 수 있습니다.

공유 채널이나 외부 채널에 봇을 추가하는 것은 해당 참가자에게 Agent에 대한 액세스 권한을 부여하는 것으로 간주됩니다. 그 전에 Agent의 Tool와 데이터가 외부 구성원에게 노출되어도 안전한지 확인하고, Agent가 응답하는 사람을 제한해야 하는 경우 발신자의 사용자 ID를 차단하세요.

요청 컨텍스트
요청 컨텍스트에 대한 직접 링크

모든 메시지에서 Mastra는 채널 컨텍스트 개체를request context under the channel 키입니다. 이 키에는 발신자의 Slack 표시 이름과 사용자 ID, bot 자체의 ID 정보, 메시지가 전송된 위치에 관한 세부 정보가 담깁니다. 입력 프로세서나 Tool에서 이를 읽어 사용자를 식별하거나 대화 유형에 따라 분기하세요:

src/mastra/tools/whoami.ts
import { createTool } from '@mastra/core/tools'
import type { ChannelContext } from '@mastra/core/channels'
import { z } from 'zod'

export const whoami = createTool({
  id: 'whoami',
  description: 'Return the Slack identity of the current user',
  inputSchema: z.object({}),
  execute: async (_input, context) => {
    const channel = context?.requestContext?.get('channel') as ChannelContext | undefined

    return {
      platform: channel?.platform,
      userId: channel?.userId,
      userName: channel?.userName,
      isDM: channel?.isDM,
    }
  },
})

채널 컨텍스트에는 다음이 포함됩니다.

botMention, botUserId, and botUserName: The bot's own identity on Slack.
channelId그리고threadId: 메시지가 도착한 Slack 채널 및 thread입니다.
isDM: 메시지가 다이렉트 메시지인지 여부입니다.
platform: 플랫폼 식별자,slack for this adapter.
userId그리고userName: The sender's Slack user ID and display name.

Mastra는 또한 이 컨텍스트를 짧은 시스템 메시지로 변환합니다. Agent는 플랫폼과 자체 신원은 물론 대화가 다이렉트 메시지인지 공개 채널인지도 알아냅니다. 보다thread context 해당 동작을 변경하는 방법은 채널 개요의

프로덕션 배포
프로덕션 배포에 대한 직접 링크

Mastra 서버를 배포할 때 Slack 앱 설정의 두 요청 URL을 모두 프로덕션 웹후크 URL로 업데이트하세요. 로컬 개발에 사용되는 터널 URL은 임시 URL이며 터널이 다시 시작되면 변경됩니다.

서버리스 플랫폼의 채널에는 다음이 필요할 수 있습니다.waitUntil 및 공유 pub/sub 구성을 사용하면 수명이 짧은 인스턴스 전반에서도 백그라운드 응답과 thread lease가 작동합니다. 자세한 내용은 serverless deployment in the channels overview.

유휴 서버
유휴 서버에 대한 직접 링크

플랫폼 서버는 트래픽을 수신하지 않을 때 유휴 상태로 축소되며 이는 Slack에 적합합니다. 멘션이나 다이렉트 메시지와 같은 다음 이벤트는 웹훅 요청을 전달하여 서버를 깨우고 서버는 요청 처리를 재개합니다. 서버가 유휴 상태가 된 후 첫 번째 응답은 시작하는 동안 조금 더 오래 걸릴 수 있으며 이는 예상된 것입니다. Slack은 다음을 기대합니다.200 Slack은 3초 이내에 acknowledgement를 받아야 하며 전달에 실패하거나 시간이 초과되면 이벤트를 최대 세 번 다시 시도합니다. 따라서 cold start가 매우 느리면 Agent가 응답하기 전에 한 차례 재시도가 필요할 수 있습니다. 서버가 warm 상태를 유지하는 동안 이후 메시지에는 정상 속도로 응답합니다.

설치설치에 대한 직접 링크

Slack 앱 만들기Slack 앱 만들기에 대한 직접 링크

Slack 자격 증명 설정Slack 자격 증명 설정에 대한 직접 링크

웹훅 경로 구성웹훅 경로 구성에 대한 직접 링크

Slack에서 사용해 보세요Slack에서 사용해 보세요에 대한 직접 링크

입증입증에 대한 직접 링크

서버 인증서버 인증에 대한 직접 링크

외부 채널외부 채널에 대한 직접 링크

요청 컨텍스트요청 컨텍스트에 대한 직접 링크

프로덕션 배포프로덕션 배포에 대한 직접 링크

유휴 서버유휴 서버에 대한 직접 링크

관련된관련된에 대한 직접 링크