/copilotkit-channels

name: copilotkit-channels
description: >
  Use for the CODE half of a managed Intelligence Channel with Slack or Microsoft
  Teams: customising the Channel a CLI-scaffolded project already ships, or — for a
  project the CLI did not generate — writing the Channel declaration, the
  long-running host, and the awaited activation call. Teams provider setup is in
  scope, because the CLI or dashboard wizard performs it. Creating a Slack app for
  the first time is not: if no Slack app exists yet, use setup-slack-channel for
  the provider half and return here for the code.
version: 1.1.0

CopilotKit Channels

Managed Channels let an agent answer in Slack or Microsoft Teams. Intelligence owns the provider edge — signed ingress, egress, credential storage — and delivers turns to your runtime over its realtime transport.

Scope

This skill covers **managed Intelligence Channels**: `CopilotIntelligenceRuntime`, app-api Channel resources, and the realtime gateway.

It does **not** cover the self-hosted `@copilotkit/channels` provider adapters (`@copilotkit/channels-slack`, `-teams`, `-discord`, `-telegram`, `-whatsapp`). Those hold provider credentials in your process and talk to the provider directly. Both products use the words "channels" and "Slack", so confirm which one the user means before wiring anything. If they want to hold their own Slack tokens and run their own ingress, they want the adapter packages, not this skill.

Decide which path you are on first

Everything below depends on this, and getting it wrong produces a project with two Channel declarations that fight over one Channel.

**Look for `channel-host.mts` at the project root.**

| It is there | It is not | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | The project was scaffolded by `npx copilotkit init`. The code half is **already done** — go to "Customising a scaffolded Channel". Do not write a new host or a second `createChannel`. | The project predates the Channel, or was not made by the CLI. Go to "Wiring a project the CLI did not generate", at the end. |

The scaffolded path is the one exercised end to end. Wiring an existing project is supported and works, but it is less trodden: the CLI reads source it did not generate, so a project laid out unusually may get a `status` leg reported as `undetermined` rather than a confident answer. That is deliberate — an unsure answer beats a wrong one — but verify the wiring yourself there rather than trusting a green report.

A Channel has two halves

A Channel only works when both are correct, and each half is invisible from the other:

1. **The provider half** — an app registered with Slack or Microsoft, credentials stored server-side, ingress pointed at Intelligence. Three entry points converge on it: `npx copilotkit init` guides a new project, `npx copilotkit channels add` handles an existing project or agent, and the dashboard wizard works in a browser. A new Teams app begins with the browser-created draft and uses one of the two paths below. 2. **The code half** — a long-running runtime that declares the Channel and awaits activation. A scaffolded project **already has this**; for anything else, it is what this skill writes.

The most confusing failure in this product is a correct provider half with a missing code half: the app serves HTTP normally, reports no error, shows an encouraging badge in the dashboard, and answers nothing. Nothing in the browser can diagnose it, because the missing piece is in the source tree.

Teams provider setup has two peer paths

For Teams, create the durable Channel draft in Intelligence before provisioning Microsoft resources. The browser then offers:

• **Fast CLI setup (recommended):** copy the fully scoped command from the draft:

  npx copilotkit@latest channels add --project-id <project-id> --channel-id <channel-id> --adapter teams --provision

It works outside a repository, reuses the CopilotKit login, confirms the Microsoft tenant, creates one single-tenant Teams-managed app, and sends the generated secret directly to encrypted Intelligence storage. It does not print the secret, write provider environment files, or modify runtime code.

• **Guided manual setup:** use Teams Developer Portal and Microsoft Entra, enter write-only credentials, and download the finished package from the browser. The normal path does not need Azure Bot and never asks the user to edit `manifest.json`.

Both paths use the same durable setup state and can replace one another mid-setup. `Files.ReadWrite.All` administrator consent and one **Add to a team** installation are required. A non-admin pause is a successful `blocked` outcome with one approval link and the same resume command; rerunning it must reuse the existing Microsoft app.

Custom icon and package bytes stay in browser/CLI memory or a temporary local directory. Never send them to Intelligence, Redis, or another relay. If an attempt stops before upload, require the user to select custom icons again (or explicitly choose the default kite) and delete every temporary copy on exit.

Treat **Created and installed** narrowly: the Microsoft app exists, encrypted credentials are stored, file and Team message access are approved, and a Team installation was recorded. It is not proof that this runtime is online or that a message was delivered.

Customising a scaffolded Channel

A scaffolded project ships three files, and on