Skip to content

README.md

Latest commit

 

History

History
330 lines (208 loc) · 12.6 KB

README.md

File metadata and controls

330 lines (208 loc) · 12.6 KB

Casey: IT Helpdesk Agent (Bolt for Python and Claude Agent SDK)

Meet Casey (it/this/that) — an AI-powered IT helpdesk agent that lives in Slack. Casey can troubleshoot common issues, search knowledge base articles, reset passwords, check system status, and create support tickets, all without leaving the conversation.

Built with Bolt for Python and the Claude Agent SDK using models from Anthropic.

App Overview

Casey gives your team instant IT support through three entry points:

  • App Home — Users open Casey's Home tab and choose from common issue categories (Password Reset, Access Request, Software Help, Network Issues, Something Else). A modal collects details, then Casey starts a DM thread with a resolution.
  • Direct Messages — Users message Casey directly to describe any IT issue. Casey responds in-thread, maintaining context across follow-ups.
  • Channel @mentions — Users mention @Casey in any channel to get help without leaving the conversation.

Casey uses five simulated tools to assist users:

  • Knowledge Base Search — Finds relevant articles for common topics like VPN, email, Wi-Fi, printers, and more.
  • Support Ticket Creation — Creates a tracked ticket when issues need human follow-up.
  • Password Reset — Triggers a password reset and confirms the action.
  • System Status Check — Reports the operational status of company systems.
  • User Permissions Lookup — Shows access levels and group memberships.

Note: All tools return simulated data for demonstration purposes. In a production app, these would connect to your actual IT systems.

Slack MCP Server

Casey also works with the Slack MCP Server, giving it the ability to search messages and files, read channel history and threads, send messages, schedule messages, and create or update Slack canvases. When deployed with OAuth (HTTP mode), Casey automatically connects to the Slack MCP Server using the user's token, unlocking these capabilities on top of the built-in IT tools.

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-casey-agent --template slack-samples/bolt-python-support-agent --subdir claude-agent-sdk
cd my-casey-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-support-agent.git my-casey-agent
cd my-casey-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

Anthropic Setup

This app uses Claude through the Claude Agent SDK.

  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

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 Casey is running, there are three ways to interact:

App Home — Open Casey in Slack and click the Home tab. You'll see five category buttons. Click one to open a modal, describe your issue, and submit. Casey will start a DM thread with you containing a diagnosis and next steps.

Direct Messages — Open a DM with Casey and describe your issue. Casey will react with 👀 while processing, then reply in a thread. Send follow-up messages in the same thread and Casey will maintain the full conversation context.

Channel @mentions — In any channel where Casey has been added, type @Casey followed by your issue. Casey responds in a thread so the channel stays clean.

Casey will add a ✅ reaction when it believes an issue has been resolved, and occasionally adds a contextual emoji reaction to keep things friendly.

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 uses AsyncApp from Bolt for Python, with all handlers running asynchronously.

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.

manifest_oauth.json

manifest_oauth.json is the app manifest configured for HTTP mode (Socket Mode disabled, with request URLs for event subscriptions and interactivity). Use this when setting up the app for HTTP mode instead of manifest.json.

/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 category buttons.
  • app_mentioned.py — Responds to @Casey mentions in channels.
  • message.py — Responds to direct messages from users.

/listeners/actions — Handles interactive components:

  • category_buttons.py — Opens the issue submission modal when a category button is clicked.
  • feedback.py — Handles thumbs up/down feedback on Casey's responses.

/listeners/views — Handles view submissions and builds Block Kit views:

  • issue_modal.py — Processes modal submissions, starts a DM thread, and runs the agent.
  • app_home_builder.py — Constructs the App Home Block Kit view.
  • modal_builder.py — Constructs the issue submission modal.
  • feedback_block.py — Creates the feedback button block attached to responses.

/agent

The casey.py file configures the Claude Agent SDK with a system prompt, tools registered via an MCP server, and a run_casey_agent() async function that handles sending queries and collecting responses.

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

The tools directory contains five IT helpdesk tools defined using the @tool decorator from the Claude Agent SDK.

/thread_context

The store.py file implements a thread-safe in-memory session ID store, keyed by channel and thread. The Claude Agent SDK manages conversation history server-side via sessions, so only session IDs need to be tracked locally for resuming conversations.

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