Setup

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

A public endpoint for Slack to send events to. In development, use ngrok to forward Slack traffic to your local AgentOS server.
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.
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[os,slack]' openai. Set OPENAI_API_KEY in the server terminal for the example agent.

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.

Update Slack callback URLs whenever your assigned tunnel URL changes. Use a stable configured endpoint for persistent callbacks; for production, deploy with a Starter template.

For new apps, use Slack's current Agent messaging experience (agent_view). Existing assistant_view apps use a legacy lifecycle. Agno's shipped manifest still declares assistant_view; use the Manual path for a new app and follow Slack's agent setup for the current feature configuration.

Agno currently initializes suggested prompts on assistant_thread_started, not the new-app DM-open event app_home_opened. That prompt lifecycle needs an upstream adapter update; ordinary messaging and prompt initialization are separate capabilities.

This manifest documents the legacy Assistant experience and is not a new-app setup template. It pre-configures the scopes, events, and settings needed for DMs, @mentions, and Human-in-the-Loop interactions.

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

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

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.

Create the app

Go to api.slack.com/apps
Click Create New App → From scratch
Name it (e.g., "My Agent"), select your workspace, then click Create App

Configure App Home

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

Click App Home in the sidebar
Under Show Tabs, enable Messages Tab
Check Allow users to send Slash commands and messages from the messages tab

Enable Agents & AI Apps

Configure the current agent feature using Slack's setup instructions; new apps use agent_view. Dashboard options depend on the app's selected experience.

Click Agents & AI Apps in the sidebar
Toggle the feature On

Agno does not automatically fall back if Slack rejects streaming. Choose Slack(agent=agent, streaming=False) for non-streaming replies; see Streaming.

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.

Subscribe to events

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

Toggle Enable Events to On
Enter Request URL: https://YOUR-NGROK-URL/slack/events
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`	Legacy Assistant thread creation; used by the current Agno prompt handler

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

Enable interactivity

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

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

Verify message delivery and interactivity for your selected Slack app experience. Suggested prompts retain the adapter limitation described above.

3. Install and collect credentials

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

Click Install App in the sidebar
Click Install to Workspace, review permissions, then click Allow
Copy the Bot User OAuth Token (starts with xoxb-)
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

Save the following as app.py and start it in the terminal containing the Slack credentials and OPENAI_API_KEY:

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!

With the default reply_to_mentions_only=True, channel follow-ups still need an @mention, including replies inside a thread. DMs do not. Add a database and add_history_to_context=True to the agent when those follow-ups need previous-message context.

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:

In Event Subscriptions, add message.channels and message.groups events
Go to Install App → Reinstall to Workspace
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

The current Slack interface copies event.assistant_thread.action_token into run metadata. It does not read the top-level event.action_token used in Slack's current agent example. Events carrying only that top-level token reach search_workspace without the required credential and return a no-token error.

Slack's Real-time Search guide prohibits retaining data retrieved by that API. Agno's ordinary session persistence can retain raw tool results; the Slack Team interface also enables member-response storage. Configure and verify event-token handling and the complete storage path before enabling this search. The workspace-tools example keeps it disabled pending those integration changes.

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.