Slack Agent Template

A Slack Agent template built with Workflow DevKit's DurableAgent, AI SDK tools, Bolt for JavaScript (TypeScript), and the Nitro server framework.

Features

• Workflow DevKit — 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

Prerequisites

Before getting started, make sure you have a development workspace where you have permissions to install apps. You can use a developer sandbox or create a workspace.

Getting Started

Clone and install dependencies

1
git clone https://github.com/vercel-partner-solutions/slack-agent-template && cd slack-agent-template && pnpm install

Create a Slack App

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 <Workspace_Name>
   • 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
{
2
  "manifest": {
3
    "source": "local"
4
  },
5
  "project_id": "<project-id-added-by-slack-cli>"
6
}

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://<your-app-domain>/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.

1
┌─────────────────────────────────────────────────────────────────┐
2
│                       Chat Workflow                             │
3
├─────────────────────────────────────────────────────────────────┤
4
│                                                                 │
5
│  User Message ──▶ assistantUserMessage listener                 │
6
│                              │                                  │
7
│                              ▼                                  │
8
│                   ┌─────────────────────┐                       │
9
│                   │  start(chatWorkflow)│                       │
10
│                   │  with messages +    │                       │
11
│                   │  context            │                       │
12
│                   └─────────────────────┘                       │
13
│                              │                                  │
14
│                              ▼                                  │
15
│                   ┌─────────────────────┐                       │
16
│                   │  createSlackAgent() │                       │
17
│                   │  with tools         │                       │
18
│                   └─────────────────────┘                       │
19
│                              │                                  │
20
│                              ▼                                  │
21
│                   ┌─────────────────────┐                       │
22
│                   │  agent.stream()     │──▶ Tool calls         │
23
│                   │  generates response │    (may loop)         │
24
│                   └─────────────────────┘                       │
25
│                              │                                  │
26
│                              ▼                                  │
27
│                   ┌─────────────────────┐                       │
28
│                   │  Stream chunks to   │                       │
29
│                   │  Slack via          │                       │
30
│                   │  chatStream()       │                       │
31
│                   └─────────────────────┘                       │
32
│                              │                                  │
33
│                              ▼                                  │
34
│                        User sees response                       │
35
│                                                                 │
36
└─────────────────────────────────────────────────────────────────┘

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.

1
┌─────────────────────────────────────────────────────────────────┐
2
│                         HITL Flow                               │
3
├─────────────────────────────────────────────────────────────────┤
4
│                                                                 │
5
│  User Request ──▶ Agent ──▶ joinChannel Tool                    │
6
│                                    │                            │
7
│                                    ▼                            │
8
│                        ┌─────────────────────┐                  │
9
│                        │  Send Slack message │                  │
10
│                        │  with Approve/Reject│                  │
11
│                        │  buttons            │                  │
12
│                        └─────────────────────┘                  │
13
│                                    │                            │
14
│                                    ▼                            │
15
│                        ┌─────────────────────┐                  │
16
│                        │  Workflow PAUSES    │                  │
17
│                        │  (no compute used)  │◀── await hook    │
18
│                        └─────────────────────┘                  │
19
│                                    │                            │
20
│                         User clicks button                      │
21
│                                    │                            │
22
│                                    ▼                            │
23
│                        ┌─────────────────────┐                  │
24
│                        │  Action handler     │                  │
25
│                        │  calls hook.resume()│                  │
26
│                        └─────────────────────┘                  │
27
│                                    │                            │
28
│                                    ▼                            │
29
│                        ┌─────────────────────┐                  │
30
│                        │  Workflow RESUMES   │                  │
31
│                        │  with approval data │                  │
32
│                        └─────────────────────┘                  │
33
│                                    │                            │
34
│                                    ▼                            │
35
│                           Agent responds                        │
36
│                                                                 │
37
└─────────────────────────────────────────────────────────────────┘

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

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

1
import { tool } from "ai";
2
import { z } from "zod";
3
import type { SlackAgentContextInput } from "~/lib/ai/context";
4

5
const myNewTool = tool({
6
  description: "Description of what this tool does",
7
  inputSchema: z.object({
8
    param: z.string().describe("Parameter description"),
9
  }),
10
  execute: async ({ param }, { experimental_context }) => {
11
    "use step"; // Required for Workflow's durable execution
12

13
    // Dynamic imports inside step to avoid bundling Node.js modules in workflow
14
    const { WebClient } = await import("@slack/web-api");
15

16
    const ctx = experimental_context as SlackAgentContextInput;
17
    const client = new WebClient(ctx.token);
18
    // Tool implementation
19
    return { result: "..." };
20
  },
21
});

1. Add it to the slackTools export in /server/lib/ai/tools.ts
2. Update the agent instructions in /server/lib/ai/agent.ts to describe when to use the new tool

Learn more about building agents with the AI SDK in the Agents documentation.

Adding Human-in-the-Loop to Tools

To add approval workflows to your own tools:

1. Add a hook definition to /server/lib/ai/workflows/hooks.ts:

1
import { defineHook } from "workflow";
2
import { z } from "zod";
3

4
export const myApprovalHook = defineHook({
5
  schema: z.object({
6
    approved: z.boolean(),
7
    // Add any additional data you need
8
  }),
9
});

1. In your tool's execute function (without "use step"), create and await the hook:

1
execute: async ({ param }, { toolCallId, experimental_context }) => {
2
  const ctx = experimental_context as SlackAgentContextInput;
3

4
  // Send approval UI to user (in a step)
5
  await sendApprovalMessage(ctx, toolCallId);
6

7
  // Create hook and wait for approval (in workflow context)
8
  const hook = myApprovalHook.create({ token: toolCallId });
9
  const { approved } = await hook;
10

11
  if (!approved) {
12
    return { success: false, message: "User declined" };
13
  }
14

15
  // Perform the action (in a step)
16
  return await performAction(ctx);
17
};

1. Create an action handler that calls hook.resume() when the user responds

Learn more about hooks in the Workflow DevKit documentation.

Learn More

• Workflow DevKit Documentation
• AI SDK Documentation
• Slack Bolt Documentation
• Slack Assistant API
• Nitro Documentation