mirror of
https://github.com/CopilotKit/CopilotKit.git
synced 2026-09-14 16:26:20 +08:00
Benjamin Taylor
6f58b2c6a4
Three names for one value were live in CopilotKit's own documentation, and following the wrong one with a CLI-provisioned project yields an undefined key: - `INTELLIGENCE_API_KEY` — what `copilotkit project select` writes, used by all 34 integration examples and the docs site. - `COPILOTKIT_INTELLIGENCE_API_KEY` — the seven Channels package READMEs and the packaged skills. Nothing ever read it. - `COPILOTKIT_API_KEY` — the Slack and Teams examples, and the TSDoc on `CopilotKitIntelligence` itself, which is what an IDE shows on hover. `INTELLIGENCE_API_KEY` wins, because it is the name the CLI provisions and changing it would break every scaffolded project in the wild. `COPILOTKIT_INTELLIGENCE_API_KEY` is retired outright — no code read it. `COPILOTKIT_API_KEY` stays readable as a deprecated alias in the two examples that consume it, so an existing `.env` keeps working, and is documented as deprecated everywhere it appears. The skills reference also documented `organizationId`, sourced from a fourth and fifth env name, as a `CopilotKitIntelligence` option. It is not one: `CopilotKitIntelligenceConfig` has no such field, so the copy-pasteable sample it appeared in would not compile. Removed from the samples, and the prose that told readers to fetch a value for it corrected. The Intelligence wiring itself was published only inside `node_modules/@copilotkit/runtime/skills/`, and the only docs pages showing `CopilotKitIntelligence` were the two Channels frontends — so a developer on the plain web path had no page to reach it from. Adds `/premium/connect-your-runtime`, which covers the wiring, how to confirm the credential is actually consumed, and the self-hosted two-URL rule. `scripts/validate-intelligence-env-names.ts` keeps this from drifting back. It runs unfiltered in CI on purpose: the two workflows that would otherwise cover it filter paths, and static/quality ignores `examples/**` — exactly where the deprecated alias lives.
@copilotkit/channels
@copilotkit/channels is the batteries-included CopilotKit Channels package. One install
provides the engine, JSX vocabulary, UI primitives, testing API, and every supported adapter.
Channels run through a channel runner. CopilotKit Intelligence provides the
managed runner, available on a free plan: the CopilotRuntime starts and owns
each Channel's lifecycle once Intelligence is configured. You can also build and
operate your own channel runner on the lower-level SDK primitives, with no
Intelligence dependency — a supported path where your team owns state,
persistence, concurrency, locking, retries, and race-condition handling.
Install
pnpm add @copilotkit/channels
Configure TypeScript to use the Channels JSX runtime:
{
"compilerOptions": {
"jsx": "react-jsx",
"jsxImportSource": "@copilotkit/channels"
}
}
import { createChannel, Message, Section } from "@copilotkit/channels";
import { slack } from "@copilotkit/channels/slack";
import { CopilotRuntime, CopilotKitIntelligence } from "@copilotkit/runtime/v2";
import { createCopilotNodeListener } from "@copilotkit/runtime/v2/node";
const channel = createChannel({
name: "support-bot", // project-unique Intelligence Channel name
identifyUser: "platform",
adapters: [
slack({
botToken: process.env.SLACK_BOT_TOKEN!,
appToken: process.env.SLACK_APP_TOKEN!,
}),
],
});
channel.onMessage(({ thread, message }) =>
thread.post(
<Message>
<Section>Echo: {message.text}</Section>
</Message>,
),
);
// The runtime owns the Channel's lifecycle — there is no `channel.start()`.
const runtime = new CopilotRuntime({
intelligence: new CopilotKitIntelligence({
// apiUrl and wsUrl default to the managed Intelligence platform — override
// both together only for a self-hosted deployment.
apiKey: process.env.INTELLIGENCE_API_KEY!, // free tier available
}),
channels: [channel],
});
// Creating the listener starts the Channel's connection.
const listener = createCopilotNodeListener({ runtime });
// Optional: await that activation so a broken config fails startup loudly.
await listener.channels.ready(); // listener.channels.stop() tears it down
Adapter entry points
@copilotkit/channels/slack(plus/slack/codecand/slack/render)@copilotkit/channels/teams(plus/teams/render)@copilotkit/channels/discord@copilotkit/channels/telegram@copilotkit/channels/whatsapp
One package version gives you a tested snapshot of the core engine, JSX/UI vocabulary, testing helpers, and every adapter listed above.
For adapter authoring or a selective dependency graph, install
@copilotkit/channels-core plus the direct adapter package you need, for example:
pnpm add @copilotkit/channels-core @copilotkit/channels-slack