• Workflow SDK — Make any TypeScript function durable. Build AI agents that can suspend, resume, and maintain state with ease. Reliability-as-code with automatic retries and observability built in
• AI SDK — The AI Toolkit for TypeScript. Define type-safe tools with schema validation and switch between AI providers by changing a single line of code
• Vercel AI Gateway — One endpoint, all your models. Access hundreds of AI models through a centralized interface with intelligent failovers and no rate limits
• Slack Assistant — Integrates with Slack's Assistant API for threaded conversations with real-time streaming responses
• Human-in-the-Loop — Built-in approval workflows that pause agent execution until a user approves sensitive actions like joining channels
• Built-in Tools — Pre-configured tools for reading channels, threads, joining channels (with approval), and searching

1. Open https://api.slack.com/apps/new and choose "From an app manifest"
2. Choose the workspace you want to use
3. Copy the contents of manifest.json into the text box that says "Paste your manifest code here" (JSON tab) and click Next
4. Review the configuration and click Create
5. On the Install App tab, click Install to You will be redirected to the App Configuration dashboard
6. Copy the Bot User OAuth Token into your environment as SLACK_BOT_TOKEN
7. On the Basic Information tab, copy your Signing Secret into your environment as SLACK_SIGNING_SECRET

Environment Setup

1. Add your AI_GATEWAY_API_KEY to your .env file. You can get one here
2. Add your NGROK_AUTH_TOKEN to your .env file. You can get one here
3. In the terminal run slack app link
4. If prompted update the manifest source to remote select yes
5. Copy your App ID from the app you just created
6. Select Local when prompted
7. Open .slack/config.json and update your manifest source to local

1. Start your local server using slack run. If prompted, select the workspace you'd like to grant access to Select yes if asked "Update app settings with changes to the local manifest?"
2. Open your Slack workspace and add your new Slack Agent to a channel. Your Slack Agent should respond whenever it's tagged in a message or sent a DM

Deploy to Vercel

1. Create a new Slack app for production following the steps from above
2. Create a new Vercel project here and select this repo
3. Copy the Bot User OAuth Token into your Vercel environment variables as SLACK_BOT_TOKEN
4. On the Basic Information tab, copy your Signing Secret into your Vercel environment variables as SLACK_SIGNING_SECRET
5. When your deployment has finished, open your App Manifest from the Slack App Dashboard
6. Update the manifest so all the request_url and url fields use https:///api/slack/events
7. Click save and you will be prompted to verify the URL
8. Open your Slack workspace and add your new Slack Agent to a channel. Your Slack Agent should respond whenever it's tagged in a message or sent a DM Note: Make sure you add the production app, not the local app we setup earlier
9. Your app will now automatically build and deploy whenever you commit to your repo. More information here

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.

/server/app.ts

/server/app.ts is the entry point of the application. This file is kept minimal and primarily serves to route inbound requests.

/server/lib/ai

Contains the AI agent implementation:

• agent.ts — Creates the DurableAgent from Workflow with system instructions and available tools. The agent automatically handles tool calling loops until it has enough context to respond.

• tools.ts — Tool definitions using AI SDK's tool function:

  • getChannelMessages — Fetches recent messages from a Slack channel
  • getThreadMessages — Fetches messages from a specific thread
  • joinChannel — Joins a public Slack channel (with Human-in-the-Loop approval)
  • searchChannels — Searches for channels by name, topic, or purpose

/server/listeners

Every incoming request is routed to a "listener". Inside this directory, we group each listener based on the Slack Platform feature used:

• /listeners/assistant — Handles Slack Assistant events (thread started, user message, context changed)
• /listeners/actions — Handles interactive component actions (buttons, menus) including HITL approval handlers
• /listeners/shortcuts — Handles incoming Shortcuts requests
• /listeners/views — Handles View submissions
• /listeners/events — Handles Slack events like app mentions and home tab opens

/server/api

This is your Nitro server API directory. Contains events.post.ts which matches the request URL defined in your manifest.json. Nitro uses file-based routing for incoming requests. Learn more here.

Agent Architecture

Chat Workflow

The core agent loop is implemented as a durable workflow using Workflow DevKit. When a user sends a message, the workflow orchestrates the agent's response with automatic retry handling and streaming support.

Key files:

• /server/lib/ai/workflows/chat.ts — The durable workflow definition using "use workflow" directive
• /server/lib/ai/agent.ts — Creates the DurableAgent with system prompt and tools
• /server/listeners/assistant/assistantUserMessage.ts — Listener that starts the workflow and streams responses

How it works:

1. User sends a message to the Slack Assistant
2. The assistantUserMessage listener collects thread context and starts the workflow
3. chatWorkflow creates the agent and calls agent.stream() with the messages
4. The agent processes the request, calling tools as needed (each tool uses "use step" for durability)
5. Response chunks are streamed back to Slack in real-time via chatStream()

Human-in-the-Loop (HITL) Workflow

This template demonstrates a production-ready Human-in-the-Loop pattern using Workflow DevKit's defineHook primitive. When the agent needs to perform sensitive actions (like joining a channel), it pauses execution and waits for user approval.

Key files:

• /server/lib/ai/workflows/hooks.ts — Hook definitions for HITL workflows (e.g., channelJoinApprovalHook)
• /server/lib/ai/tools.ts — Tool definitions including joinChannel which uses the approval hook
• /server/lib/slack/blocks.ts — Slack Block Kit UI for approval buttons
• /server/listeners/actions/channel-join-approval.ts — Action handler that resumes the workflow

How it works:

1. The joinChannel tool is called by the agent
2. A Slack message with Approve/Reject buttons is posted to the thread
3. channelJoinApprovalHook.create() creates a hook instance and the workflow pauses at await hook
4. When the user clicks a button, the action handler calls hook.resume() with the decision
5. The workflow resumes and the agent either joins the channel or acknowledges the rejection

This pattern can be extended for any action requiring human approval (e.g., sending messages, modifying data, external API calls).

Customizing the Agent

Modifying Instructions

Edit the system prompt in /server/lib/ai/agent.ts to change how your agent behaves, responds, and uses tools.

Adding New Tools

Add a new tool definition in /server/lib/ai/tools.ts using AI SDK's tool function: