Slack Bot Modernization: Vercel AI SDK, Chat SDK, and official Slack templates

Status: Active consideration (restart recommended)
Owner: Uttam Kumaran
Created: 2026-03-01
Last updated: 2026-03-28
Related: ROADMAP.md · Cloud Agent runbook · brainforge-assistant app

Why revisit this now

Maintenance cost of the current brainforge-assistant stack is high relative to value: large untyped entrypoints, hand-rolled Slack formatting, in-memory state that resets on every Railway deploy, weak CI story (no real AI-path E2E), and operational friction for safe deploys and testing.

Between early March 2026 and now, Vercel shipped a coherent, documented path from “Slack Assistant + streaming + tools + HITL” to production on Vercel, plus a coding-agent skill that automates much of setup. That reduces exploration risk and makes a phased migration or greenfield v2 more realistic than when this doc was first drafted.

Discovery: Plan refresh used Exa (user-exa MCP) plus first-party links below.

Azure region policy: East US 2 (brainforge-openai-eastus2) is the only target for new Azure OpenAI deployments. brainforge-openai (East US) is legacy and we are deprecating it. Any modernization should assume East US 2 keys, base URLs, and deployments. See azure-openai-setup.md.

Overview

Modernize the Brainforge Slack Assistant by adopting Vercel AI SDK patterns (streaming, typed tools, optional ToolLoopAgent) and choosing one of two first-party integration styles:

Chat SDK (chat + @chat-adapter/slack) — recommended by Vercel for new projects; abstracts markdown ↔ Slack, streaming, and multi-platform reach.
Bolt + Nitro + Workflow DevKit — official Slack Agent Template stack: Slack Assistant API, DurableAgent, AI SDK tools, human-in-the-loop via hooks; docs assume Vercel, but the stack is still Node (see Hosting below).

Both align with the same goal as the original write-up: replace raw fetch() to Azure Responses API, persist state across deploys, and make testing and deployment repeatable.

Important: “Vercel AI SDK” is the name of the TypeScript library (ai, provider packages). It runs wherever Node runs — Railway is not ruled out.

The problem (current pain points)

Clunky development

Plain JavaScript with limited type safety (index.js is very large)
Hand-rolled markdown-to-Slack conversion in assistant.js that Chat SDK is designed to absorb
In-memory Maps for thread memory, deduplication, and in-flight locks — state lost on every Railway redeploy
Manual ExpressReceiver wiring, body-parser, raw body verification
Direct fetch() to Azure OpenAI Responses API with manual parsing

Lack of interoperability

Little shared code between the Slack bot and the platform app
Platform has Mastra, CopilotKit, @ag-ui/client — not unified with Slack
POST /api/brainforge/repo-context and other HTTP bridges are ad hoc
Multiple Slack call sites in platform code without a shared abstraction

Lack of testing and safe deploys

E2E today mostly checks HTTP surfaces, not full event → AI → Slack behavior
Integration flows that require a live #ai-test-channel are hard to run in CI
No durable workflow layer — hard to test “pause for approval, resume later”

What Vercel (and Slack) ship now (March 2026)

1. Slack Agent Template (Bolt + Nitro + Workflow + AI SDK)

The Slack Agent Template (repo: vercel-partner-solutions/slack-agent-template) is the closest “batteries included” reference for a Slack Assistant-style bot on Vercel:

Workflow DevKit — durable workflows ("use workflow"), suspend/resume, retries and observability
AI SDK — tool() + Zod schemas; model routing compatible with AI Gateway or direct providers
Bolt for JavaScript (TypeScript) — familiar if we keep a listener-oriented structure
Nitro — file-based API routes (e.g. events under /api/slack/...)
Slack Assistant API — threaded conversations, streaming responses
Human-in-the-loop — defineHook + Block Kit buttons; workflow pauses until approval (pattern in template docs)

2. Slack Agent Skill (wizard for Cursor / Claude Code / Copilot)

vercel-labs/slack-agent-skill automates setup and encodes quality bars (lint, typecheck, tests). It supports both:

Chat SDK (recommended for greenfield) — chat + @chat-adapter/slack + Next.js
Bolt + Nitro (for Bolt-shaped apps) — aligns with the Slack Agent Template

Install: npx skills add vercel-labs/slack-agent-skill — see Building Slack agents can be easy (2026-03-03).

Slack’s own post Deploy Agents to Slack Faster with Vercel Skills (2026-03-04) describes the same workflow from Slack’s side.

3. Chat SDK (cross-platform agents)

Chat SDK brings agents to your users (2026-03-19) positions Chat SDK as the integration layer: one handler model, adapters for Slack, Teams, Discord, Linear, GitHub, WhatsApp, etc.

Highlights relevant to Brainforge:

thread.post(result.textStream) — pipe AI SDK streams without custom Slack streaming glue
State adapters — Redis; PostgreSQL adapter available for teams that want durable state without Redis (blog)
Markdown ↔ platform handled in adapters (reduces custom formatter burden)

Optional ecosystem: e.g. Redis tutorial: Chat SDK + distributed locking — directly addresses duplicate replies / race conditions in multi-instance bots.

4. AI SDK agents abstraction

Building Agents documents ToolLoopAgent — reusable agent config (model, tools, loop limits, structured output) for routes or workers. Useful if we want one defined agent shared between a future Slack surface and platform APIs.

5. Operations: Vercel + Slack webhooks

How to test a Slack bot with your Vercel preview deployment — deployment protection bypass via query param (Slack cannot send custom headers)
Deploying Bolt apps to Vercel — Slack developer docs for Bolt on Vercel

Choose a track (decision)

Criterion	Track A — Chat SDK (`chat` + `@chat-adapter/slack`, often Next.js)	Track B — Bolt + Nitro + Workflow (Slack Agent Template)
Best when	Greenfield `v2`, multi-channel future, minimize Slack-specific code	Closest to current Bolt mental model; Assistant API + HITL + durability out of the box
State	Redis or Postgres via `@chat-adapter/state-*`	Workflow DevKit + steps; align with long-running / approval flows
Streaming + formatting	Strong (adapter-owned)	Template’s `chatStream()` + Assistant patterns
Migration from current app	More rewrite of listeners	Incremental port of concepts (listeners → structured `server/listeners`)
Deploy target	Often Next on Vercel in examples; Chat SDK + Node on Railway is fine	Template targets Vercel; self-host possible via Workflow Postgres World (extra setup)

Recommendation for a “start this quarter” spike:

Run /slack-agent new (or equivalent) from slack-agent-skill and scaffold both minimal samples in a branch (time-boxed).
Pick Track B if the priority is Assistant streaming + approval workflows + durable steps with minimal custom infrastructure.
Pick Track A if the priority is long-term multi-surface (Slack + future adapters) and maximum deletion of custom Slack formatting.

Provider strategy (Brainforge-specific): Prefer @ai-sdk/azure for parity with existing Azure OpenAI contracts. Treat AI Gateway as optional for model fallback and multi-provider routing once baseline works — the official template uses Gateway; we can swap the model factory to Azure-first and add Gateway later.

Hosting: Railway vs Vercel

You do not have to move to Vercel to adopt AI SDK, typed tools, Chat SDK, or a cleaner Bolt app. The current bot already proves Slack events + HTTPS + env vars on Railway; a modernized service is the same contract with better code and persistent state (Redis/Postgres).

Approach	When it fits
Stay on Railway	Minimize new vendor surface; team already operates the bot there; Track A (Chat SDK) or Bolt + Express (evolution of today’s app) with a public URL and the same Slack manifest `request_url` pattern.
Add Vercel	You want the official Slack Agent Template deploy path, preview-deployment docs, and the default Workflow “Vercel World” without running your own workflow backend. Setup is mostly: project from repo, env vars (`SLACK_BOT_TOKEN`, `SLACK_SIGNING_SECRET`, Azure or `AI_GATEWAY_API_KEY`), point Slack at `https://<deployment>/api/slack/events`, verify URL.
Railway + Workflow DevKit	If you want Track B durability without Vercel, Workflow supports self-hosted Postgres World (`@workflow/world-postgres`, migrations, long-running worker) — more moving parts than “git push to Vercel,” but explicitly not locked to Vercel.

If Vercel setup feels heavy: spike AI SDK + Redis/Postgres state on Railway first (smallest operational delta). Defer Vercel until you hit something that really needs it (e.g. you choose the stock template + Vercel World and accept one more host).

Environment strategy: separate Slack apps for test and production

Use two Slack apps from day one:

brainforge-assistant-test (or current test assistant app) for all migration work, shadow runs, and prompt/tool tuning.
brainforge-assistant (production) for stable users and staged cutover only.

Why this is recommended:

Slack app manifests, bot tokens, and event URLs are environment-coupled. Separate apps remove cross-environment risk.
We can point test app event URLs to Railway test service without touching prod request URLs.
Feature flags and unsafe tools can be enabled in test only.

Operational guardrails:

Keep env vars fully separate (SLACK_BOT_TOKEN_TEST, SLACK_SIGNING_SECRET_TEST, etc. in deployment config).
Restrict test bot channel access to internal testing channels.
Promote behavior from test to prod only after fixture tests + live test-channel validation pass.

Proposed architecture (conceptual)

graph TB
    subgraph slackV2 ["brainforge-assistant-v2 (TBD: Chat SDK or Bolt+Nitro)"]
        Adapter["Slack adapter OR Bolt listeners"]
        AISDK["AI SDK: streamText / ToolLoopAgent / tool()"]
        Durability["Redis or Postgres state OR Workflow DevKit"]
    end

    subgraph shared ["Shared package (future: packages/ai-core)"]
        ToolDefs["Tool definitions + RAG helpers"]
        ClientCtx["Client / vault context"]
    end

    subgraph platform ["Platform (Next.js)"]
        Mastra["Mastra / CopilotKit (existing)"]
    end

    Adapter --> AISDK
    AISDK --> Durability
    slackV2 --> shared
    platform --> shared

Migration strategy (revised phases)

Phase 0: Spike (1–2 weeks)

Time-box: scaffold via Slack Agent Skill; clone or reference Slack Agent Template for Track B.
Prove: one tool call (e.g. read thread), streaming reply, deploy to Railway or Vercel (pick one for the spike), wire test assistant app manifest URLs first.
Document: Azure vs Gateway decision, secrets layout, parity checklist vs current Railway bot.

Phase 1: Vertical slice

Port one high-value flow (e.g. @brainforge Q&A or slash command) to v2 with AI SDK + typed tools.
Add persistent state (Redis or Postgres for Chat SDK; workflow + store for Track B).
CI: unit tests + fixture-based request replay; avoid hard dependency on live #ai-test-channel for merge gating.

Phase 2: Feature parity + cutover

Map ROADMAP items (approval, reminders, RAG) to Chat SDK JSX/actions or Workflow hooks + Block Kit.
Run v2 in shadow or internal channel via the test assistant app before switching production app URLs.
Decommission or archive monolithic index.js paths once parity is verified.

Phase 3: Interoperability

Extract shared tool schemas and retrieval into packages/ai-core (or equivalent).
Optional: same ToolLoopAgent config behind both Slack and a platform API route.

Human-only steps (expected)

Most implementation can be AI-executed; these steps still need a human owner:

Create or approve Slack app settings/manifest changes in Slack admin UI (scopes, event subscriptions, Assistant settings).
Install/reinstall test and prod apps in target workspaces/channels.
Confirm and rotate secrets/tokens in deployment provider(s).
Approve production cutover timing and rollback window.
Validate production behavior in real channels before broad rollout.

AI can prepare exact click-by-click instructions and perform all code/config changes around these gates.

Roadmap mapping (unchanged intent, implementation depends on track)

Roadmap item	Chat SDK track	Bolt + Workflow track
Approval flow	JSX `<Card>` + actions	`defineHook` + Block Kit + resume
Reminders / cron	Scheduled route + `thread.post()`	Workflow + external scheduler calling API
Testing	In-memory state adapter + replay	Fixture listeners + mocked WebClient
Knowledge RAG	Shared tool + `thread.post(stream)`	Shared tool + `chatStream()`
Streaming	`thread.post(result.textStream)`	Template streaming path
Multi-surface later	Other adapters	More work; still possible via shared `ai-core`

What not to adopt (updated)

Pi agent framework — still unnecessary; AI SDK + Workflow or Chat SDK covers orchestration.
Vercel Sandboxes — optional future for arbitrary user code; not required for assistant Q&A / tools.
“Nitro is out” — obsolete guidance. Nitro is now a first-party path via the Slack Agent Template; keep or drop based on Track A vs B, not dogma.
“AI Gateway is out” — soften. Prefer Azure for primary models; use Gateway when we want multi-provider failover or faster model experiments without Azure config churn.

Sources (first-party)

Slack Agent Template (Nitro) · GitHub: vercel-partner-solutions/slack-agent-template
Building Slack agents can be easy (Vercel blog, 2026-03-03)
GitHub: vercel-labs/slack-agent-skill
Chat SDK brings agents to your users (Vercel blog, 2026-03-19)
AI SDK: Building Agents
Vercel Academy: Slack Agents
Test a Slack bot with Vercel preview deployments
Slack docs: Deploying Bolt to Vercel

Sources (Exa / ecosystem)

Deploy Agents to Slack Faster with Vercel Skills (Slack Developers blog, 2026-03-04)
Build a Slack bot with Chat SDK and Redis distributed locking (Redis, 2026-03)

Brainforge Knowledge

Explorer

slack-bot-modernization-plan