# @copilotkit/channels-teams The **Microsoft Teams platform adapter** for [`@copilotkit/channels`](../channels). It's a concrete `PlatformAdapter` that plugs Teams into the platform-agnostic bot engine, exactly like [`@copilotkit/channels-slack`](../channels-slack) does for Slack. You write your bot once with `createChannel` (handlers, JSX, tools, context) and run it on Teams by adding this adapter. It is built on the **Microsoft 365 Agents SDK** (`@microsoft/agents-hosting`), the successor to the Bot Framework SDK. The adapter keeps its own Teams/Microsoft 365 credentials (`clientId` / `clientSecret` / `tenantId`, or none for anonymous local dev) — in the managed path the Channel runs inside a CopilotKit Intelligence-configured `CopilotRuntime` (free plan available), which starts and owns the channel's lifecycle. Building and operating your own channel runner on the SDK primitives is also a supported path. ## Managed Channels: the alternative to holding your own credentials This adapter is the **self-hosted** path: your process holds the Microsoft Teams credentials, runs the Microsoft Teams ingress, and talks to Microsoft Teams directly. **Managed Intelligence Channels** is the alternative. Intelligence owns the provider edge — signed ingress, egress, and encrypted credential storage — so your process holds no Microsoft Teams credentials and exposes no public Microsoft Teams endpoint. You also get durable threads, the Channels dashboard with per-Channel health and transcripts, and guided provider setup from either the browser wizard or the CLI. For a newly created managed app, the browser creates the durable Channel draft and issues the fully scoped provisioning command: ```bash npx copilotkit@latest channels add --project-id --channel-id --adapter teams --provision ``` That managed path creates a Teams-managed bot and Entra identity; it does not require Azure Bot. The peer manual path uses Teams Developer Portal plus Entra. Both keep provider secrets and one-time app-package bytes out of your project. Your bot code is otherwise identical — the agent, tools, context, commands, and turn handlers do not change. Only the transport does. See `examples/teams/app/managed.ts` for the same bot wired both ways, and the **copilotkit-channels** skill for the runtime wiring. This self-hosted adapter remains fully supported. Choose it when you want the provider connection inside your own infrastructure. ## Install ```sh pnpm add @copilotkit/channels @copilotkit/channels-ui @copilotkit/channels-teams pnpm add @microsoft/agents-hosting @microsoft/agents-activity ``` The Microsoft 365 Agents SDK packages are **optional peer dependencies**, so they are not installed for you. Add them as shown above — this adapter is the self-hosted path, and it needs them to run the Teams ingress. `express` is an optional peer too, but you only need it if you use the built-in listener, `createTeamsServer`. It is loaded lazily inside `start()`, so a bot that serves `POST /api/messages` from its own HTTP server does not install it: ```sh pnpm add express # only for createTeamsServer ``` They are optional because the managed path does not need them. Managed Channels reach this package only through the `./render` subpath, which never touches the Microsoft SDK, so an app that installs `@copilotkit/runtime` for a plain chat UI no longer pulls the whole Microsoft Agents stack, or the exact `zod` pin that comes with it. If you import the adapter without them, Node fails at import time and names the package to install: ``` Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@microsoft/agents-hosting' ``` ## Quickstart ```ts import { createChannel } from "@copilotkit/channels"; import { teams } from "@copilotkit/channels-teams"; import { CopilotRuntime, CopilotKitIntelligence } from "@copilotkit/runtime/v2"; import { createCopilotNodeListener } from "@copilotkit/runtime/v2/node"; const bot = createChannel({ name: "support-bot", // project-unique Intelligence Channel name identifyUser: "platform", adapters: [teams({ port: 3978 })], }); bot.onMessage(({ thread, message }) => thread.post(`Echo: ${message.text}`)); // The runtime owns the channel's lifecycle — there is no `bot.start()`. const runtime = new CopilotRuntime({ intelligence: new CopilotKitIntelligence({ // apiUrl and wsUrl default to cloud-hosted CopilotKit Intelligence — override // both together only for a self-hosted deployment. apiKey: process.env.CPK_INTELLIGENCE_API_KEY!, // free tier available }), channels: [bot], }); // Creating the listener starts the Channel's connection. const listener = createCopilotNodeListener({ runtime }); // Optional: await that activation; once settled, POST /api/messages is listening // on :3978. await listener.channels.ready(); ``` Then point the **Microsoft 365 Agents Playground** at it. No Microsoft credentials are required for local development: ```sh npx @microsoft/m365agentsplayground # opens http://localhost:56150 ``` The Playground connects to `http://127.0.0.1:3978/api/messages` and gives you a Teams-like chat UI to test against. See [`examples/teams`](../../examples/teams) for a complete, runnable echo bot, and the [Microsoft Teams guide](../../showcase/shell-docs/src/content/docs/frontends/teams.mdx) for sideloading into real Teams via Azure Bot Service. ## How it maps onto the `PlatformAdapter` contract - **Ingress:** a `CloudAdapter` receives Teams activities at `POST /api/messages` (stood up by an Express server). Each `message` activity is normalized into `sink.onTurn(...)`. Uploaded files ride along as attachments: `buildFileContentParts` downloads them (a `file.download.info` URL, or a `data:`/https media URL) and hands the agent multimodal content parts — CSV/JSON/text as decoded text, images and PDFs as binary. That's what makes "upload a CSV → get a chart" work. Note Teams only delivers uploaded files to a bot in **1:1 (personal) chat** (requires `supportsFiles: true` in the app manifest); in a channel or group chat Teams does NOT send the file to the bot at all, so chart-from-data there means pasting the data inline. - **Egress:** structured/interactive UI is rendered to an **Adaptive Card** (1.5) and sent as an attachment; a reply that collapses to plain text is sent as a normal text activity (a bare `Echo: hi` shouldn't be a card). Both go out on the live `TurnContext` _within the originating turn_. The engine awaits the whole turn handler, so a reply (or a full `runAgent()` loop) completes before the HTTP response closes. (Out-of-turn / proactive sends fall back to `CloudAdapter.continueConversation` via the captured conversation reference.) - **Files out:** `postFile` posts a file to the conversation. An image (e.g. a rendered chart PNG) is sent as an inline attachment via a `data:` URI, so it renders directly in the thread — the bot-slack `postFile` parallel. - **Streaming:** text replies stream **by message edit** (Teams' baseline model). It posts the first content, then `updateActivity` edits the same message as the buffer grows (throttled and serialised; see `TeamsMessageStream`), after a typing indicator. Native token streaming is a later enhancement. - **Agent runs:** `createRunRenderer` bridges AG-UI events to Teams. Each text message is streamed by edit, and tool calls plus interrupts are captured for the run loop. - **History:** Teams does not hand the bot a queryable transcript, so an in-memory `TeamsConversationStore` keeps one per conversation and seeds each agent run with it. Swap in a durable `ConversationStore` for production. ## Native Teams JSX Use the `Teams` namespace for Adaptive Card types outside the portable JSX set. A native card has one explicit `Teams.AdaptiveCard` root. Actions can be root children or children of `Teams.ActionSet`. ```tsx import { Teams } from "@copilotkit/channels-teams"; await thread.post( approve(action.value)} /> , ); ``` The serializer computes the card version from the types and properties in use. An explicit lower root version fails with the component and property that raised the minimum. Named child slots stay traversable, so handlers inside an action set survive managed delivery and action recovery. `Teams.Raw` accepts a reviewed non-interactive Adaptive Card object. The generated [native catalog](../channels/native-catalogs.md) labels the 38 stable Teams body types, 7 stable actions, preview entries, and supporting nodes. Host badges and catalog presence come from adaptivecards.microsoft.com. “Supported” here means Microsoft marks the entry for Teams; verification in a live tenant remains a separate release check. Direct Teams and managed Teams use the same serializer and Bot Framework attachment shape. ## Options ```ts teams({ port: 3978, // POST /api/messages port (Playground default) clientId, // Microsoft app id; omit for anonymous local dev clientSecret, // omit for anonymous local dev tenantId, // omit for multi-tenant / anonymous interruptEventNames, // custom-event names treated as agent interrupts }); ``` Credentials also resolve from the `clientId` / `clientSecret` / `tenantId` environment variables (the names the M365 Agents SDK reads). ## Status & roadmap Implemented: message ingress; **Adaptive Card rendering** of the bot-ui vocabulary (`
`, `
`/``, ``, ``, ``, ``/`