mirror of
https://github.com/CopilotKit/CopilotKit.git
synced 2026-09-14 16:26:20 +08:00
Ben Taylor
8a8e52d9e9
Closes OSS-646. Split out of OSS-641 as the unambiguous half. This PR does **not** change when activation happens — whether the long-running wrappers should auto-connect stays open on OSS-641. ## Why `createCopilotRuntimeHandler` builds the `ChannelManager` but opens no connection; activation is lazy, triggered by the first `channels.ready()`. That is deliberate (`fbf35ac59`, OSS-473) — Cloudflare/Next isolates freeze and recycle per request, so cold starts would mint conflicting listeners. Two things were left inconsistent with it: 1. `endpoints/node.ts` still documented the pre-`fbf35ac59` world — "the same `ChannelsControl` surface the underlying fetch handler **activates at creation time**" — and labelled the one required call as `// Optional:`. That's the TSDoc developers and coding agents see in-editor, and it contradicted every channel-package README. Same failure class as OSS-634. 2. `68349bc1f` gave the fetch handler a branded overload so `handler.channels.ready()` type-checks without `?.`, but the node wrapper never got it — so every call site, including our own example and all nine showcase docs pages, was written defensively. ### A live consequence, found en route `examples/slack/app/managed.ts` never called `ready()`. It built the runtime, mounted the listener, logged `[channel] started managed Channel "…"`, and only ever called `stop()` — so since activation went lazy it has connected nothing while reporting success. It was written against exactly the creation-time model the TSDoc described. Fixed here, with a regression assertion. ## What changed - **Types** — `createCopilotNodeListener` gets the branded overload pair mirroring `createCopilotRuntimeHandler`: a runtime with at least one declared Channel yields non-optional `.channels`; `activateChannels: false` and channel-less runtimes keep the optional shape. Adds `NodeCopilotListenerWithChannels`; both listener types are now exported from `@copilotkit/runtime/v2/node`. - **Docs** — node/express/hono TSDoc corrected: creation opens no connection, `ready()` is what activates, and it is required on a long-running host. Same stale claim fixed in the three example comments and `examples/slack/README.md` that repeated it. - **Call sites** — `?.` dropped from `examples/slack`, `examples/teams`, both READMEs, and the nine `showcase/shell-docs` channel pages. ## Deliberate scope choices, called out - **Express/Hono keep an optional `.channels`.** Only their TSDoc is corrected here. Their own type docs name Node as the lifecycle-owning surface and attach `.channels` best-effort, so the branded overload is Node-only for now; `endpoints-channels.test.ts` still uses `!` for those two. Say the word if the overload should extend to them. - **The non-optional shape requires a literal `channels` tuple** (`readonly [Channel, ...Channel[]]`). A runtime built from a dynamically-assembled `Channel[]` is unbranded and still needs `?.`. Now stated in the node TSDoc. - **`examples/slack/app/managed.ts` now exits nonzero if activation fails**, where before it stayed up serving HTTP with nothing connected. Intentional — fail loud, and it matches `index.ts`. Note that `ready()` resolves for `setup_required`, so a declared-but-unprovisioned channel still logs as started. - **Signal handlers are registered before awaiting activation** in `managed.ts`, so a Ctrl-C inside the 30s activation window still tears the Channel down instead of hitting Node's default handler. ## Verification - **Type contract, red → green:** the new `KeyIsRequired<typeof listener, "channels">` assertion in `handler-channels-types.test.ts` failed to compile before the overload (`error TS2344: Type 'false' does not satisfy the constraint 'true'`) and passes after. - **Example bug, red → green:** stashing only `managed.ts` fails the new guard with `expected "vi.fn()" to be called once, but got 0 times`. - **Strict-null proof:** `slack-example` and `teams-example` both `tsc --noEmit` clean under `strict: true` with the `?.` removed. This matters because the runtime package compiles with `strict: false`, so its own type test can only probe the optionality modifier structurally. - Runtime channel suites 54/54; slack example 63/63. - **Coverage limit:** the `managed.ts` guard is mocked — it proves the example *calls* `ready()` with a bound, not that a Channel connects. Nothing in CI exercises a real gateway connect for these examples. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
CopilotKit Examples
This directory contains 50 consolidated demo repositories showcasing CopilotKit integrations, canvas apps, and showcases.
Each example is a self-contained project. To get started:
GIT_LFS_SKIP_SMUDGE=1 git clone <repo-url>
cd examples/<category>/<name>
# Follow the example's own README for setup instructions
Note: The
v1/andv2/directories at the top level are legacy workspace examples from earlier CopilotKit releases and are not part of the consolidated demo set.
Integrations (19)
Framework integration starters demonstrating CopilotKit with various agent frameworks.
| Example | Description |
|---|---|
| langgraph-python | Starter template for building AI agents using LangGraph (Python) and CopilotKit |
| langgraph-js | Starter template for building AI agents using LangGraph (JS) with Turborepo monorepo |
| langgraph-fastapi | Starter template for building AI agents using LangGraph with FastAPI and Poetry |
| mastra | Starter template for building AI agents using Mastra and CopilotKit |
| crewai-flows | Starter template for building AI agents using CrewAI Flows (uv-based) |
| llamaindex | Starter template with a LlamaIndex investment analyst agent |
| pydantic-ai | Starter template with a PydanticAI investment analyst agent |
| ms-agent-framework-python | CopilotKit with Microsoft Agent Framework (Python/FastAPI, AG-UI protocol) |
| ms-agent-framework-dotnet | CopilotKit with Microsoft Agent Framework (.NET/C#, AG-UI protocol) |
| strands-python | Starter template with a Strands investment analyst agent |
| mcp-apps | Integration of MCP Apps with CopilotKit using Three.js |
| adk | Starter template using Google ADK with an investment analyst agent |
| agent-spec | Starter for Agent Spec with A2UI-powered frontend tool rendering |
| a2a-a2ui | Starter for A2UI + A2A with a restaurant finder agent (Gemini/ADK) |
| agno | Starter template using Agno with an investment analyst agent |
| crewai-crews | Starter template for building AI agents using CrewAI Crews |
| a2a-middleware | Multi-agent starter with A2A Protocol and AG-UI Protocol (LangGraph + ADK) |
| claude-sdk-python | Starter template using the Claude Agent SDK (Python) and CopilotKit |
| claude-sdk-typescript | Starter template using the Claude Agent SDK (TypeScript) and CopilotKit |
Canvas (7)
AI-powered canvas applications with visual card interfaces, real-time state sync, and HITL workflows.
| Example | Description |
|---|---|
| langgraph-python | AG-UI canvas starter with LangGraph — interactive cards with real-time AI sync |
| llamaindex | AG-UI canvas starter with LlamaIndex — visual cards, multi-step planning, HITL |
| llamaindex-composio | Hackathon starter with LlamaIndex, CopilotKit, and Composio (Google Sheets integration) |
| pydantic-ai | AG-UI canvas starter with PydanticAI — visual cards, planning, HITL |
| mastra | AG-UI canvas starter with Mastra — interactive cards with real-time AI sync |
| gemini | Open Gemini Canvas — post generator and stack analyzer agents (Gemini + LangGraph) |
| mastra-pm | AG-UI + Mastra workshop — shared state, multiple clients, generative UI |
Showcases (24)
Full-featured demo applications highlighting CopilotKit capabilities in real-world scenarios.
| Example | Description |
|---|---|
| banking | Banking app demo with authorization, multiple operations, and generative UI |
| presentation | PowerPoint-like web app built with CopilotKit |
| deep-agents | Deep research assistant with planning, memory/files, and generative UI (Tavily) |
| deep-agents-job-search | Job application assistant — resume parsing, skill extraction, DeepAgents orchestration |
| generative-ui | Generative UI for agentic apps — AG-UI protocol showcase |
| generative-ui-playground | Playground for static GenUI, MCP Apps, and A2UI generative UI types |
| mcp-apps | MCP Apps demo — airline booking, hotel booking, investment simulator, kanban board |
| research-canvas | ANA (Agent Native Application) — research canvas with Tavily search and LangGraph |
| mcp-demo | Working Memory — MCP server-client integration for project management (Linear) |
| strands-file-analyzer | AI-powered document analysis with Strands Agents and Amazon Bedrock |
| microsoft-kanban | Kanban board demo with CopilotKit + Microsoft Agent Framework (.NET, AG-UI) |
| multi-page | Multi-page Remix app with CopilotKit |
| orca | Cisco CopilotKit demo — PR and repository analytics dashboard |
| pydantic-ai-todos | AI-powered todo board with PydanticAI (Todo, In-Progress, Done columns) |
| scene-creator | Scene creator with LangGraph + Gemini 3 — AI-generated characters and backgrounds |
| adk-dashboard | Generative canvas with Google ADK — metrics, charts, and real-time data |
| langgraph-js-support-agents | Multi-agent telecom support system with intent, lookup, reply, and escalation agents |
| multi-agent-canvas | Open Multi-Agent Canvas — manage multiple agents (travel, research, MCP) in one chat |
| chatkit-studio | Open ChatKit Studio — explore and build embeddable chat experiences |
| enterprise-brex | Enterprise banking demo with authorization, operations, and generative UI |
| a2a-travel | A2A + AG-UI multi-agent travel demo (LangGraph + Google ADK) |
| spreadsheet | AI-powered Excel-like spreadsheet web app |
| todo | Simple todo app built with CopilotKit |
| strands-crm | Enterprise sales CRM — dashboard, pipeline, products, quotes, reports & agentic canvas (TypeScript Strands + AG-UI) |