Skip to content

README.md

Latest commit

 

History

History
208 lines (129 loc) · 8.11 KB

README.md

File metadata and controls

208 lines (129 loc) · 8.11 KB

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

Meet Casey (they/them) — 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.

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
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
# or pip install -e .

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 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.

/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_im.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.

/conversation

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.