Setup

Create a Slack App and connect it to your Agno agent.

To connect an agent to Slack, you need three pieces in place:

1. A public endpoint for Slack to send events to. In development, use ngrok to forward Slack traffic to your local AgentOS server.

2. A Slack app that represents your agent in the workspace. This is what users see under Apps in Slack, with its own name, icon, and permissions.

3. Credentials so your agent can talk to Slack and verify incoming requests. You’ll use a bot token for Slack API calls and a signing secret for webhook verification.

After setup, Slack events follow this path:

Slack  →  https://YOUR-URL/slack/events  →  AgentOS  →  Agent

The guide below walks through the setup step by step.

Install dependencies first: uv pip install 'agno[slack]'

1. Expose your local server

Slack needs a public HTTPS URL for event callbacks. For local development, start an ngrok tunnel to your AgentOS server:

ngrok http 7777

You now have a public HTTPS endpoint. Copy the forwarding URL, since the app you create next will point at it.

ngrok generates a new URL on each restart. For production, use a stable domain instead (see the deployment guide).

2. Create the Slack app

Create a Slack app for your agent and configure the permissions and events it needs.

Manifest

The manifest is the quickest setup path. It pre-configures the scopes, events, and settings needed for DMs, @mentions, and Human-in-the-Loop interactions.

1. Download manifest.json and replace https://YOUR-URL with your ngrok URL
2. Go to api.slack.com/apps → Create New App → From a manifest
3. Select your workspace, choose JSON, and paste the manifest contents
4. Click Next, review the summary, then click Create

Your Slack app now has the required scopes and event subscriptions.

Manual

This path configures each setting individually. Use it when you need custom scopes or want to understand what the manifest abstracts. Each area below maps to a page in the Slack app dashboard.

1. Create the app

   1. Go to api.slack.com/apps
   2. Click Create New App → From scratch
   3. Name it (e.g., “My Agent”), select your workspace, then click Create App
2. Configure App Home

   App Home is your agent’s surface in Slack. Users find it under Apps and start conversations there.

   1. Click App Home in the sidebar
   2. Under Show Tabs, enable Messages Tab
   3. Check Allow users to send Slash commands and messages from the messages tab
3. Enable Agents & AI Apps

   Streaming responses and task cards use Slack’s assistant UI, which has its own feature toggle.

   1. Click Agents & AI Apps in the sidebar
   2. Toggle the feature On

   Without this, users see a spinner until the full response is ready (see Streaming).

4. Add OAuth scopes

   Scopes are the permissions your app requests, and each one grants a single capability like reading messages, sending replies, or accessing files.

   Go to OAuth & Permissions → Scopes → Bot Token Scopes and add:

   Scope	Purpose	Required?
   app_mentions:read	See @mentions	Yes
   chat:write	Send messages	Yes
   im:history	Read DM history	Yes
   assistant:write	Slack’s assistant UI with streaming	Yes
   channels:read	See public channel membership	Yes
   channels:history	Read public channel history	Recommended
   groups:read	See private channel membership	Optional
   groups:history	Read private channel history	Optional
   files:read	Access shared files	Optional
   files:write	Upload files	Optional
   users:read	Look up user profiles	Optional
   users:read.email	Look up user emails	Optional

   Start with the required scopes and add optional ones later, keeping in mind that each change needs a reinstall. Slack’s scopes reference documents the full catalog.

5. Subscribe to events

   Events tell Slack when to call your webhook. Go to Event Subscriptions:

   1. Toggle Enable Events to On
   2. Enter Request URL: https://YOUR-NGROK-URL/slack/events
   3. Slack sends a verification challenge to that URL

   The verification challenge needs a live endpoint. If it fails, complete the Connect your agent step first, then return and retry.

   Under Subscribe to bot events, add:

   Event	Fires when
   app_mention	Someone @mentions the agent
   message.im	Someone DMs the agent
   assistant_thread_started	Someone opens a thread with the agent

   To also receive channel messages, add message.channels and message.groups (see Respond to all channel messages).

6. Enable interactivity

   Human-in-the-Loop features (confirmation buttons, input forms) require interactivity. This routes button clicks and form submissions to your agent.

   1. Click Interactivity & Shortcuts in the sidebar
   2. Toggle Interactivity to On
   3. Enter Request URL: https://YOUR-NGROK-URL/slack/interactions

The manual configuration now matches what the manifest sets up automatically.

3. Install and collect credentials

The last remaining problem is authentication, and installing the app to your workspace generates both credentials you need.

1. Click Install App in the sidebar
2. Click Install to Workspace, review permissions, then click Allow
3. Copy the Bot User OAuth Token (starts with xoxb-)
4. Go to Basic Information → App Credentials and copy the Signing Secret

Export them so your code can authenticate:

export SLACK_TOKEN="xoxb-..."           # Bot User OAuth Token
export SLACK_SIGNING_SECRET="..."       # From Basic Information → App Credentials

Slack-side setup is complete: the app exists, it points at your URL, and you hold its credentials.

4. Connect your agent

With all three problems solved, the only thing left is to connect the agent itself:

app.py

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.os.app import AgentOS
from agno.os.interfaces.slack import Slack

agent = Agent(name="My Agent", model=OpenAIResponses(id="gpt-5.4"))

agent_os = AgentOS(
    agents=[agent],
    interfaces=[Slack(agent=agent)],
)
app = agent_os.get_app()

if __name__ == "__main__":
    agent_os.serve(app="app:app", reload=True)

python app.py

AgentOS mounts the Slack interface at /slack/events, the same path your webhook points at. Events from Slack now reach your agent.

5. Test in Slack

Once the agent is running, verify everything works by sending it a message. The quickest check is a direct message: find your agent under Apps in Slack and say hello.

To test in a channel, invite the agent and then mention it:

/invite @MyAgent
@MyAgent hello!

Each thread keeps its own conversation, so follow-up messages in the same thread don’t need another @mention.

If the agent replies, events are flowing from Slack through AgentOS to your agent. Setup is complete.

Customization

The five steps above cover the standard setup. Two adjustments come up often enough to walk through here.

Scope and event changes require reinstalling. Go to Install App → Reinstall to Workspace after any change.

Respond to all channel messages

By default, the agent only responds to @mentions and DMs. To respond to every message in channels it’s in:

1. In Event Subscriptions, add message.channels and message.groups events
2. Go to Install App → Reinstall to Workspace
3. Update your code:

Slack(agent=agent, reply_to_mentions_only=False)

See Response control for how this changes the agent’s behavior.

Add search tools

If your agent uses SlackTools.search_workspace(), the app needs three additional scopes:

• search:read.public
• search:read.files
• search:read.users

Add them under OAuth & Permissions, then reinstall.

Next steps

Once your agent is responding in Slack, continue with the deeper interface guides.

Features

Sessions, files, streaming, and more

Human-in-the-Loop

Pause for approval before taking actions

Reference

All parameters, scopes, and events