Teams example: demo bot

A runnable demo of @copilotkit/bot-teams: a Microsoft Teams bot backed by a CopilotKit BuiltInAgent that shows streamed-by-edit replies, agent-rendered Adaptive Cards, and a human-in-the-loop approval gate, testable locally in the Microsoft 365 Agents Playground with no Microsoft credentials. It needs an OPENAI_API_KEY.

Run it

From this directory (after pnpm install at the repo root):

export OPENAI_API_KEY=sk-...   # or add it to .env (see .env.example)
pnpm start                     # starts the bot on http://localhost:3978/api/messages

In a second terminal:

pnpm playground   # opens the M365 Agents Playground at http://localhost:56150

Then, in the Playground:

• Ask anything → the agent replies, streaming in by message edit (a typing indicator first, then text that fills in as it's edited, following Teams' baseline post-then-updateActivity streaming model).
• Ask for a summary, status, or any structured data → the agent calls the show_card tool and posts an Adaptive Card (header, facts, table).
• Ask it to "announce X to the team" → it drafts the message, posts an Approve/Reject card, and only sends after you approve (the card updates in place to ✅/🚫).

That exercises the CopilotKit bot engine and the Teams adapter end-to-end: streaming, agent-rendered Adaptive Cards, and human-in-the-loop.

What's in here

• app/index.tsx: the whole bot, covering an in-process BuiltInAgent runtime, the createBot({ adapters: [teams()] }) wiring, an onMessage handler that runs the agent, and the agent-facing show_card tool.
• app/human-in-the-loop/: the confirm_write approval gate and the Adaptive Card it posts. This is user-land code, not SDK code.

Use a remote agent

By default the example serves an in-process BuiltInAgent. To point the bot at a remote AG-UI endpoint (a deployed CopilotKit runtime, LangGraph, and so on) instead, swap the agent factory to read a URL from the environment:

agent: (threadId) => {
  const a = new SanitizingHttpAgent({ url: process.env.AGENT_URL! });
  a.threadId = threadId;
  return a;
},

Connect to Microsoft Teams

The Playground needs no credentials; real Teams does. The high-level path:

1. Register the bot with Microsoft. Create an Entra app registration and note its Application (client) ID, Directory (tenant) ID, and a client secret. Create an Azure Bot resource that uses that app, enable the Microsoft Teams channel, and set its messaging endpoint to https://<your-host>/api/messages.
2. Give the bot the credentials. Set clientId / clientSecret / tenantId (the names the M365 Agents SDK reads) in the bot's environment. With them set, the bot acks each turn and runs the agent on a detached context, so HITL approvals can resume minutes later.
3. Build and upload the app package (below), then in Teams: Apps → Manage your apps → Upload a custom app.

The full step-by-step walkthrough is in the Microsoft Teams guide.

Build the Teams app package

The app package is the manifest + icons you sideload into Teams. Build it with:

pnpm package   # -> appPackage/appPackage.zip

The script (appPackage/package.mjs, dependency-free) reads your bot id from MICROSOFT_APP_ID / CLIENT_ID / clientId (env or .env) and injects it into the manifest, validates the manifest, and auto-generates placeholder icons if they're missing, so the committed manifest.json stays a placeholder and you never hardcode your id. See appPackage/README.md for details.

Files and charts (upload a CSV, get a chart)

The agent can read uploaded files and render charts. Upload a CSV and ask for a pie/bar chart: the bot parses the data and calls render_chart, which posts a native Teams chart (an Adaptive Card chart element, no image generation, no headless browser). How the file reaches the bot depends on where it's uploaded, because of a Teams limitation:

• 1:1 (personal) chat — the file is delivered to the bot inline (requires supportsFiles: true in the manifest, already set). Works with no extra setup.

• Channel / group chat — Teams does not send the file to bots here, so the bot fetches it through Microsoft Graph. That needs two application permissions on the bot's Entra app, consented once by a tenant admin:

  • Files.Read.All — download the file from SharePoint.
  • Group.Read.All (or the manifest's RSC ChannelMessage.Read.Group, which a team owner can consent without a tenant admin) — read the channel message that references the file.

  Without that consent the bot still works — it asks the user to paste the data inline (which also renders a chart). To verify the Graph chain in a tenant where you control consent before requesting it org-wide, run scripts/verify-graph-channel.ts (see its header).

Charts render natively in the Teams client, so there's nothing extra to install (no Chromium, no headless browser). Native charts need a Teams app manifest at version 1.25+ (already set in appPackage/manifest.json).

Deploy

The bot is a plain HTTP service: it serves POST /api/messages (plus a /healthz liveness probe) and binds PORT, so it runs anywhere a Node process does. Teams is an inbound webhook, so the service needs a public URL: point your Azure Bot resource's messaging endpoint at https://<your-host>/api/messages.

Deploy as a workspace member (built from source)

This example consumes the @copilotkit/* packages via the workspace:* protocol, so it always builds from the in-repo source — not the npm registry. That decouples the deploy from publishing: a change to packages/** redeploys with the new code immediately.

Because it's a workspace member, the deploy must run from the repo root so the workspace and packages/** are visible. The bot runs its BuiltInAgent runtime in-process (on RUNTIME_PORT, localhost-only), so it's a single service — no separate runtime process. On Railway (or any host), set:

pnpm --filter teams-example build builds the workspace libs the example imports (@copilotkit/bot, bot-teams, bot-ui, runtime) and everything they depend on, via the Nx project graph — so tsx runs against fresh dist. The Watch Paths are what make a packages/**-only change trigger a redeploy. On Railway, generate a public domain on the service (Settings → Networking); it routes to $PORT, which the bot listens on for /api/messages.

Copying this example out of the monorepo? Replace the workspace:* ranges in package.json with the published versions (e.g. @copilotkit/bot-teams: ^0.0.1) — workspace:* only resolves inside this monorepo.

Set the environment for wherever you deploy:

• OPENAI_API_KEY (required): the bot runs a BuiltInAgent and exits at startup without it.
• OPENAI_MODEL (optional): defaults to openai/gpt-5.5.
• clientId / clientSecret / tenantId: needed to reach real Teams (see above). The in-process BuiltInAgent runtime stays on RUNTIME_PORT (localhost-only, default 8200).

Note: the conversation store and pending HITL approvals are in-memory, so they do not survive a restart. Swap in a durable store before relying on long-lived approvals in production.