wehub-resource-sync
174 lines
8.1 KiB
Markdown
174 lines
8.1 KiB
Markdown
# Teams example: demo bot
|
|
|
|
A runnable demo of [`@copilotkit/channels-teams`](../../packages/channels-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):
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```ts
|
|
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](https://learn.microsoft.com/entra/identity-platform/quickstart-register-app)
|
|
and note its Application (client) ID, Directory (tenant) ID, and a client
|
|
secret. Create an [Azure Bot
|
|
resource](https://learn.microsoft.com/azure/bot-service/bot-service-quickstart-registration)
|
|
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](../../showcase/shell-docs/src/content/docs/frontends/teams.mdx).
|
|
|
|
## Build the Teams app package
|
|
|
|
The app package is the manifest + icons you sideload into Teams. Build it with:
|
|
|
|
```sh
|
|
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`](./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:
|
|
|
|
| Setting | Value |
|
|
| ------------------ | -------------------------------------------------------------------- |
|
|
| **Root Directory** | repo root (`/`) |
|
|
| **Build Command** | `pnpm install && pnpm --filter teams-example build` |
|
|
| **Start Command** | `pnpm --filter teams-example start` |
|
|
| **Watch Paths** | `packages/**`, `examples/teams/**`, `pnpm-lock.yaml`, `package.json` |
|
|
|
|
`pnpm --filter teams-example build` builds the workspace libs the example
|
|
imports (`@copilotkit/channels`, `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/channels-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.
|