Connect and run your agent in Slack
Run any supported agent framework in Slack through a cloud-hosted Intelligence connection.
Run your agent as a Slack app. CopilotKit Intelligence holds the Slack credentials, and your process holds the agent and the application logic.
New to the product? Start with the Channels overview to understand how the SDK, Runtime, Intelligence, and provider connection fit together.
Before you continue, configure the Channel in Intelligence.
You should have CHANNEL_CODE and CPK_INTELLIGENCE_API_KEY.
Start with your coding agent
Use this prompt to connect your agent to Slack, start the runner, and verify a real workspace message. You can also follow the manual steps below.
Open your coding agent in your project's folder, or in an empty folder for a new app.This runs in a coding agent on your computer.
Before you start
- Node.js 22 or later; the managed launcher requires the global
WebSocketavailable in Node.js 22+ - A long-running Node host or container; serverless request handlers cannot own the persistent gateway connection
Build and run your Channel
Create the runner
mkdir my-slack-channel
cd my-slack-channel
npm init -y
npm pkg set type=moduleUse this tested package combination. Keep exact versions in your lockfile and verify compatibility before changing either package.
npm install --save-exact @copilotkit/channels@0.11.0 @copilotkit/runtime@1.73.3npm install -D tsx typescript @types/nodeAdd a NodeNext TypeScript configuration:
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"strict": true,
"skipLibCheck": true,
"noEmit": true,
"types": ["node"]
},
"include": ["*.ts", "*.tsx"]
}Connect your agent backend
The runner can use any supported backend. The selector's
Agent backend controls the setup below. It must export a fresh
makeAgent(threadId) result for each Slack conversation; do not share one
stateful agent instance across threads.
Declare the managed Slack Channel
Create the runner below. Replace support-slack with the exact Code shown
in Intelligence.
Set agent: makeAgent on the Channel because this handler calls
thread.runAgent(). Channels do not inherit runtime.agents. A Channel
whose handlers reply directly without runAgent() can omit agent.
import { createServer } from "node:http";
import { createChannel } from "@copilotkit/channels";
import {
CopilotKitIntelligence,
CopilotRuntime,
} from "@copilotkit/runtime/v2";
import { createCopilotNodeListener } from "@copilotkit/runtime/v2/node";
import { makeAgent } from "./agent.js";
function required(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Missing required environment variable: ${name}`);
return value;
}
const channel = createChannel({
name: required("CHANNEL_CODE"),
identifyUser: "platform",
agent: makeAgent,
});
channel.onMessage(async ({ thread, message }) => {
await thread.runAgent({
context: [
{ description: "Originating platform", value: message.platform },
],
});
});
const intelligence = new CopilotKitIntelligence({
apiKey: required("CPK_INTELLIGENCE_API_KEY"),
// Cloud-hosted deployments use the default URLs. Override both URLs
// together only for self-hosted or non-production Intelligence.
apiUrl: process.env.INTELLIGENCE_API_URL,
wsUrl: process.env.INTELLIGENCE_GATEWAY_WS_URL,
});
const runtime = new CopilotRuntime({
agents: {},
intelligence,
channels: [channel],
});
// Wire teardown before the listener exists, because creating it is what
// starts the Channel. A Ctrl-C during the connect window then still tears
// the Channel down instead of hitting Node's default handler.
let teardown: (() => Promise<void>) | undefined;
const shutdown = async () => {
await teardown?.();
};
process.once("SIGINT", shutdown);
process.once("SIGTERM", shutdown);
const listener = createCopilotNodeListener({
runtime,
basePath: "/api/copilotkit",
});
const channels = listener.channels;
const server = createServer(listener);
teardown = async () => {
await channels.stop();
if (server.listening) server.close();
};
// Optional: block startup until the activation above settles, so a broken
// deploy fails loudly instead of serving as a bot that never answers.
await channels.ready({ timeoutMs: 30_000 });
const status = channels.status();
if (status.overall !== "online") {
throw new Error(`Slack Channel is not online: ${JSON.stringify(status)}`);
}
const port = Number(process.env.PORT ?? 3001);
server.listen(port, () => {
console.log(`Slack Channel online; lifecycle server listening on :${port}`);
});Calling createCopilotNodeListener starts the Channel. ready() is
optional. It waits until the start settles and throws if it fails.
ready() can settle while setup is still incomplete, so check status()
before you report the Channel online. Without ready(), start failures
appear in your logs.
Configure secrets and start
CPK_INTELLIGENCE_API_KEY=<project-api-key>
CHANNEL_CODE=support-slack
# Add the agent variables shown for your selected backend.
PORT=3001
# Optional paired overrides for self-hosted or non-production Intelligence:
# INTELLIGENCE_API_URL=https://intelligence.example.com
# INTELLIGENCE_GATEWAY_WS_URL=wss://realtime.intelligence.example.comThe runner uses port 3001 so it can run alongside a web app
on port 3000. If 3001 is already in use, set PORT to another free port.
Where these values come from
Three variables matter here:
OPENAI_API_KEY, or the key for whichever model provider your agent uses. This one is yours to create and paste.CPK_INTELLIGENCE_API_KEY:npx copilotkit@latest project selectwrites it to.envand provisions the project and its key.CHANNEL_CODE: the Code shown on the Channel in Intelligence.
If you started with the coding-agent prompt above, the onboarding run writes both Intelligence values for you. To set them yourself, see configure the runtime handoff for where each value appears in Intelligence.
Cloud-hosted Intelligence supplies both default base URLs. For a
self-hosted or non-production deployment, override both together. The REST
and realtime planes use separate hosts, so do not derive the WebSocket URL
from the API URL. Pass each as a bare base URL without /api, /socket,
/runner, or /client. Create the project-scoped runtime key from API
Keys in the Intelligence project sidebar.
-
Add
.envto.gitignore. -
Start the selected agent backend.
-
Start the runner:
Terminal node --env-file=.env --import tsx channel.ts
Intelligence should change from Waiting for runtime to Online.
Know the healthy state
| Status | What to check |
|---|---|
| Disabled | Enable the Channel before expecting delivery. |
| Setup incomplete | Finish the selected provider's required setup fields before starting the runtime. |
| Setup failed | Reopen platform setup and correct the rejected credentials or configuration. |
| Waiting for runtime | Start the process, and match its Code and provider to this Channel. |
| Conflict | Compare every replica's complete Channel declaration set. Identical replicas should elect one active owner and connected standbys; different but overlapping sets are unsafe. |
| Offline | Check the runner process, network, and Intelligence gateway connection. |
| Delivery failing | Check platform credentials, app permissions, and the provider response. |
| Online | The runtime is connected; send a real provider message to verify the full path. |
Verify a real Slack message
Invite the app if needed, then mention it in a channel:
/invite @your-app
@your-app summarize the decisions in this threadAlso test a direct message. A response in the real workspace validates the Slack token pair, Intelligence delivery, the runner, the AG-UI agent, and reply path end to end.
Tool-call progress
Managed Slack keeps tool-call progress out of the streamed reply by default, so the conversation ends with a clean result. Tool lifecycle events still remain in Intelligence history and are available during replay.
Opt in per Channel when the live tool timeline is useful:
const channel = createChannel({
name: required("CHANNEL_CODE"),
identifyUser: "platform",
agent: makeAgent,
showToolStatus: true,
});Troubleshooting
Confirm CHANNEL_CODE exactly matches the Intelligence Code and the
project-scoped CPK_INTELLIGENCE_API_KEY belongs to the same project. Provider
routing comes from the Slack connection attached in Intelligence, not from a
createChannel option.
Reopen the Channel in Intelligence and finish the Slack credential steps.
ready() settling does not by itself mean the provider is online.
Invite it to the channel, then verify the xoxb-… Bot User OAuth token and
Signing Secret came from the same Slack app. Intelligence cannot fully
detect valid but mismatched credentials during setup. If you updated the
manifest or scopes, reinstall the app and save the current bot token in
Intelligence before retrying.
Make sure that makeAgent creates a new agent for every threadId and assigns that
id where the selected framework requires it.
Next, map application users and choose Memory grants, add tools and context, or build interactive approvals.
How is this guide?