Skip to content

README.md

Latest commit

 

History

History
328 lines (206 loc) · 11.7 KB

README.md

File metadata and controls

328 lines (206 loc) · 11.7 KB

Starter Agent for Slack (Bolt for Python and Pydantic AI)

A minimal starter template for building AI-powered Slack agents with Bolt for Python and Pydantic AI using models from Anthropic or OpenAI. Works with the Slack MCP Server to search messages, read channels, send messages, and manage canvases — all from within your agent.

App Overview

The starter agent interacts with users through four entry points:

  • App Home — Displays a welcome message with instructions on how to interact.
  • Direct Messages — Users message the agent directly. It responds in-thread, maintaining context across follow-ups.
  • Channel @mentions — Mention the agent in any channel to get a response without leaving the conversation.
  • Assistant Panel — Users click Add Agent in Slack, select the agent, and pick from suggested prompts or type a message.

The template also includes one example tool (emoji reactions). Add your own tools to customize it for your use case.

Slack MCP Server

When connected to the Slack MCP Server, the agent can search messages and files, read channel history and threads, send and schedule messages, and create and update canvases. When deployed with OAuth (HTTP mode), the agent automatically connects to the Slack MCP Server using the user's token.

Setup

Before getting started, make sure you have a development workspace where you have permissions to install apps.

Developer Program

Join the Slack Developer Program for exclusive access to sandbox environments for building and testing your apps, tooling, and resources created to help you build and grow.

Create the Slack app

Using Slack CLI

Install the latest version of the Slack CLI for your operating system:

You'll also need to log in if this is your first time using the Slack CLI.

slack login

Initializing the project

slack create my-starter-agent --template slack-samples/bolt-python-starter-agent --subdir pydantic-ai
cd my-starter-agent
Using App Settings

Create Your Slack App

  1. Open https://api.slack.com/apps/new and choose "From an app manifest"
  2. Choose the workspace you want to install the application to
  3. Copy the contents of manifest.json into the text box that says *Paste your manifest code here* (within the JSON tab) and click Next
  4. Review the configuration and click Create
  5. Click Install to Workspace and Allow on the screen that follows. You'll then be redirected to the App Configuration dashboard.

Environment Variables

Before you can run the app, you'll need to store some environment variables.

  1. Rename .env.sample to .env.
  2. Open your apps setting page from this list, click OAuth & Permissions in the left hand menu, then copy the Bot User OAuth Token into your .env file under SLACK_BOT_TOKEN.
SLACK_BOT_TOKEN=YOUR_SLACK_BOT_TOKEN
  1. Click Basic Information from the left hand menu and follow the steps in the App-Level Tokens section to create an app-level token with the connections:write scope. Copy that token into your .env as SLACK_APP_TOKEN.
SLACK_APP_TOKEN=YOUR_SLACK_APP_TOKEN

Initializing the project

git clone https://github.com/slack-samples/bolt-python-starter-agent.git my-starter-agent
cd my-starter-agent

Setup your python virtual environment

python3 -m venv .venv
source .venv/bin/activate  # for Windows OS, .\.venv\Scripts\Activate instead should work

Install dependencies

pip install -r requirements.txt

Providers

This app supports both Anthropic and OpenAI as AI providers. Set at least one API key — if both are set, Anthropic is used by default.

Anthropic Setup

Uses Anthropic's claude-sonnet-4-6 model through Pydantic AI.

  1. Create an API key from your Anthropic dashboard.
  2. Rename .env.sample to .env.
  3. Save the Anthropic API key to .env:
ANTHROPIC_API_KEY=YOUR_ANTHROPIC_API_KEY

OpenAI Setup

Uses OpenAI's gpt-4.1-mini model through Pydantic AI.

  1. Create an API key from your OpenAI dashboard.
  2. Rename .env.sample to .env.
  3. Save the OpenAI API key to .env:
OPENAI_API_KEY=YOUR_OPENAI_API_KEY

Development

Starting the app

Using the Slack CLI

Slack CLI

slack run
Using the Terminal

Terminal

python3 app.py
Using OAuth HTTP Server (with ngrok)

OAuth HTTP Server

This mode uses an HTTP server instead of Socket Mode, which is required for OAuth-based distribution.

  1. Install ngrok and start a tunnel:
ngrok http 3000
  1. Copy the https://*.ngrok-free.app URL from the ngrok output.
Using Slack CLI

Slack CLI

  1. Update manifest.json for HTTP mode:

    • Set socket_mode_enabled to false
    • Replace ngrok-free.app with your ngrok domain (e.g. YOUR_NGROK_SUBDOMAIN.ngrok-free.app)

  2. Create a new local dev app:

slack install -E local

  1. Enable MCP for your app:

    • Run slack app settings to open your app's settings
    • Navigate to Agents & AI Apps in the left-side navigation
    • Toggle Model Context Protocol on

  2. Update your .env OAuth environment variables:

    • Run slack app settings to open App Settings
    • Copy Client ID, Client Secret, and Signing Secret
    • Update SLACK_REDIRECT_URI in .env with your ngrok domain
SLACK_CLIENT_ID=YOUR_CLIENT_ID
SLACK_CLIENT_SECRET=YOUR_CLIENT_SECRET
SLACK_SIGNING_SECRET=YOUR_SIGNING_SECRET
SLACK_REDIRECT_URI=https://YOUR_NGROK_SUBDOMAIN.ngrok-free.app/slack/oauth_redirect
  1. Start the app:
slack run app_oauth.py
  1. Click the install URL printed in the terminal to install the app to your workspace via OAuth.
Using the Terminal

Terminal

  1. Create your Slack app at api.slack.com/apps/new using manifest.json. Before pasting the manifest, set socket_mode_enabled to false and replace ngrok-free.app with your ngrok domain.

  2. Install the app to your workspace and copy the following values into your .env:

    • Signing Secret — from Basic Information
    • Bot User OAuth Token — from OAuth & Permissions
    • Client ID and Client Secret — from Basic Information
SLACK_BOT_TOKEN=xoxb-YOUR_BOT_TOKEN
SLACK_CLIENT_ID=YOUR_CLIENT_ID
SLACK_CLIENT_SECRET=YOUR_CLIENT_SECRET
SLACK_SIGNING_SECRET=YOUR_SIGNING_SECRET
SLACK_REDIRECT_URI=https://YOUR_NGROK_SUBDOMAIN.ngrok-free.app/slack/oauth_redirect

Replace your-subdomain in SLACK_REDIRECT_URI with your ngrok subdomain.

  1. Enable MCP for your app:

    • Open your app at api.slack.com/apps
    • Navigate to Agents & AI Apps in the left-side navigation
    • Toggle Model Context Protocol on

  2. Start the app:

python3 app_oauth.py
  1. Click the install URL printed in the terminal to install the app to your workspace via OAuth.

Note: Each time ngrok restarts, it generates a new URL. You'll need to update the ngrok domain in manifest.json, SLACK_REDIRECT_URI in your .env, and re-install the app.

Using the App

Once the agent is running, there are several ways to interact:

App Home — Open the agent in Slack and click the Home tab. You'll see a welcome message with instructions on how to interact.

Direct Messages — Open a DM with the agent. You'll see suggested prompts like Write a Message, Summarize, and Brainstorm — pick one or type your own message. The agent replies in a thread. Send follow-up messages in the same thread and the agent will maintain the full conversation context.

Channel @mentions — Invite the agent to a channel by typing /invite @agent-name in the message box, then @mention it followed by your message. The agent responds in a thread so the channel stays clean.

Assistant Panel — Click Add Agent in the top-right corner of Slack, select the agent from the list, then pick a suggested prompt or type a message.

Linting

# Run ruff check from root directory for linting
ruff check

# Run ruff format from root directory for code formatting
ruff format

Project Structure

manifest.json

manifest.json is a configuration for Slack apps. With a manifest, you can create an app with a pre-defined configuration, or adjust the configuration of an existing app.

app.py

app.py is the entry point for the application and is the file you'll run to start the server. This project aims to keep this file as thin as possible, primarily using it as a way to route inbound requests.

app_oauth.py

app_oauth.py is an alternative entry point that runs the app in HTTP mode instead of Socket Mode. This is intended for deployments that use OAuth for app distribution. See the HTTP Mode section under Development for setup instructions.

/listeners

Every incoming request is routed to a "listener". This directory groups each listener based on the Slack Platform feature used.

/listeners/events — Handles incoming events:

  • app_home_opened.py — Publishes the App Home view with a welcome message and MCP status.
  • app_mentioned.py — Responds to @mentions in channels.
  • message.py — Responds to direct messages from users.

/listeners/actions — Handles interactive components:

  • feedback_buttons.py — Handles thumbs up/down feedback on agent responses.

/listeners/views — Builds Block Kit views:

  • app_home_builder.py — Constructs the App Home Block Kit view.
  • feedback_builder.py — Creates the feedback button block attached to responses.

/agent

The agent.py file defines the Pydantic AI Agent with a system prompt, personality, and tool configuration.

The deps.py file defines the AgentDeps dataclass passed to the agent at runtime, providing access to the Slack client and conversation context.

The tools directory contains one example tool (emoji reaction) that the agent can call during a conversation.

/thread_context

The store.py file implements a thread-safe in-memory conversation history store, keyed by channel and thread. This enables multi-turn conversations where the agent remembers previous context within a thread.

Troubleshooting

MCP Server connection error: HTTP error 400 (Bad Request)

If you see an error like:

Failed to connect to MCP server 'streamable_http: https://mcp.slack.com/mcp': HTTP error 400 (Bad Request)

This means the Slack MCP feature has not been enabled for your app. There is no manifest property for this yet, so it must be toggled on manually:

  1. Run slack app settings to open your app's settings page (or visit api.slack.com/apps and select your app)
  2. Navigate to Agents & AI Apps in the left-side navigation
  3. Toggle Slack Model Context Protocol on