How to Connect an AI Agent to Slack (Bolt for Python, Socket Mode)

Intermediate ~4 min read Last tested October 2026

Updated 2026-10-15

This guide connects an AI agent to Slack with Slack’s official Bolt for Python framework in Socket Mode, so you can run it from your laptop without exposing a public URL. The bot answers when @mentioned and replies in the thread.

Prerequisites

A Slack workspace where you can install apps
Python 3.10+ and an LLM API key

Steps

1. Create the Slack app

Go to api.slack.com/apps → Create New App → From scratch.
Socket Mode: turn it on and create an app-level token with the connections:write scope. Copy it (xapp-...).
OAuth & Permissions → Bot Token Scopes: add app_mentions:read, chat:write, channels:history.
Event Subscriptions: enable, and under Subscribe to bot events add app_mention.
Install to Workspace and copy the Bot User OAuth Token (xoxb-...).

2. Install dependencies

pip install slack_bolt openai
export SLACK_BOT_TOKEN="xoxb-..."  SLACK_APP_TOKEN="xapp-..."  OPENAI_API_KEY="sk-..."

3. Write the bot

# slack_agent.py
import os, re
from slack_bolt import App
from slack_bolt.adapter.socket_mode import SocketModeHandler
from openai import OpenAI

app, llm = App(token=os.environ["SLACK_BOT_TOKEN"]), OpenAI()

@app.event("app_mention")
def on_mention(event, client, say):
    thread_ts = event.get("thread_ts", event["ts"])
    # Load the thread so the agent has context
    history = client.conversations_replies(channel=event["channel"], ts=thread_ts, limit=20)["messages"]
    bot_id = client.auth_test()["user_id"]
    messages = [{"role": "system", "content": "You are a concise, helpful Slack assistant."}]
    for m in history:
        role = "assistant" if m.get("user") == bot_id else "user"
        messages.append({"role": role, "content": re.sub(r"<@[A-Z0-9]+>", "", m.get("text", "")).strip()})
    reply = llm.chat.completions.create(model="gpt-4.1-mini", messages=messages).choices[0].message.content
    say(text=reply, thread_ts=thread_ts)

if __name__ == "__main__":
    SocketModeHandler(app, os.environ["SLACK_APP_TOKEN"]).start()

4. Run and test

python slack_agent.py

Invite the bot to a channel (/invite @YourBot) and mention it. It replies in a thread and remembers the thread on follow-ups.

5. Give it tools

Replace the single LLM call with the tool loop from Build your first AI agent in Python. Common tools: search your docs, create a Jira issue, query a database.

6. Deploy

Socket Mode works anywhere with outbound internet (a small VPS, a container). For HTTP mode instead, drop SocketModeHandler, serve Bolt behind a public URL and set the Request URL in Event Subscriptions.

Common errors

not_in_channel or no reply: invite the bot to the channel.

missing_scope: add the scope named in the error, then reinstall the app (scopes only apply after reinstall).

Bot replies twice: Slack retries events not acknowledged within 3 seconds. Bolt acks automatically, but slow handlers in HTTP mode can still trigger retries. Use lazy listeners or check the X-Slack-Retry-Num header.

invalid_auth: you swapped the xoxb and xapp tokens.

Build an agent that runs on a schedule (post a daily digest)
Connect an AI agent to WhatsApp