mirror of
https://github.com/CopilotKit/CopilotKit.git
synced 2026-09-14 16:26:20 +08:00
Benjamin Taylor
e1f88ebc12
Addresses review feedback that channel-host.mts is doing too much.
Two changes, both scoped to the starters:
1. Channel construction moves to a new `channels.mts` beside `agent.ts` —
name resolution, `createChannel`, and the `onMessage` handler. That is
also the file to edit to customise a Channel (commands, reactions,
onMention), which previously meant editing the host.
The per-framework agent import moves with it, so `channel-host.mts` is now
byte-identical in all 15 starters rather than 13 + 2.
2. The host no longer stands up an HTTP server. Its comment claimed the
server was what "keeps the lifecycle-owning process alive"; that is false.
An open undici WebSocket holds the event loop on its own — verified with a
standalone repro where a process with no HTTP server and no timers of its
own stayed up indefinitely on a single WebSocket connection. The server was
therefore serving a second, uncalled copy of the runtime API on port 8300
for no reason.
With the server gone, `createCopilotNodeListener` was the wrong factory —
it builds a request listener purely for its activation side effect. The
host now uses `createCopilotRuntimeHandler` + `ready()`, which is the
documented long-running-host pattern (see fetch-handler.ts). This also
drops `node:http`, `basePath`, and the CHANNEL_PORT env var.
Behaviour is unchanged: same Channel, same agent, same status reporting, and
the same non-zero exit on activation failure.
Verified: 14/14 starters with a `typecheck:channel` script pass; mastra has no
such script by design (166dc94691) and its pre-existing Mastra `Memory` type
error is byte-identical before and after. `npm run channel` exercised on both
failure paths — missing channels.json, and missing INTELLIGENCE_API_KEY with a
name supplied — confirming the new `./channels.mjs` specifier resolves under
tsx as well as tsc. `parity:check` output identical to the pre-change baseline.
Refs #6315
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
173 lines
7.2 KiB
Markdown
173 lines
7.2 KiB
Markdown
# CopilotKit × Claude Agent SDK — Python Starter
|
||
|
||
A starter template for building AI agents with the [Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk/overview)
|
||
and [CopilotKit](https://copilotkit.ai). It pairs a modern Next.js frontend with a Python
|
||
agent that speaks the [AG-UI protocol](https://docs.ag-ui.com), and shows CopilotKit driving
|
||
**interactive UI beyond chat**:
|
||
|
||
- a shared-state **todos canvas** the agent and the user both edit,
|
||
- **charts** rendered from queried data,
|
||
- **flight cards** and **dynamic dashboards** via A2UI generative UI,
|
||
- a **human-in-the-loop** meeting picker,
|
||
- a light/dark **theme toggle**, and
|
||
- the SDK **threads drawer** (activated with a CopilotKit Intelligence license).
|
||
|
||
The agent is powered by Claude (`claude-sonnet-5` by default) and exposes three backend tools —
|
||
`query_data`, `search_flights`, and `generate_a2ui` — while the todo board is shared state the
|
||
agent updates through the adapter's built-in `ag_ui_update_state` tool.
|
||
|
||
## Prerequisites
|
||
|
||
- **Node.js 20.9+**
|
||
- **Python 3.12 or 3.13**
|
||
- **[uv](https://docs.astral.sh/uv/)** (Python package manager)
|
||
- An **Anthropic API key** — create one at <https://console.anthropic.com/>
|
||
|
||
## Getting Started
|
||
|
||
1. **Copy the environment file:**
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
2. **Add your Anthropic API key** to `.env`:
|
||
|
||
```bash
|
||
ANTHROPIC_API_KEY=sk-ant-...
|
||
```
|
||
|
||
The other values are optional and already set to sensible defaults:
|
||
`CLAUDE_MODEL=claude-sonnet-5` and `AGENT_URL=http://localhost:8000`.
|
||
|
||
3. **Install dependencies:**
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
> This installs the Next.js frontend and, via the `postinstall` script, the
|
||
> Python agent's dependencies with `uv sync`.
|
||
|
||
4. **Start the app:**
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
This runs the Next.js UI on **http://localhost:3000** and the Claude agent on
|
||
**http://localhost:8000** concurrently.
|
||
|
||
5. **Open [http://localhost:3000](http://localhost:3000)** and try the suggested prompts
|
||
(add todos, draw a chart, search flights, build a dashboard, schedule a meeting).
|
||
|
||
6. **(Optional) Enable the Threads drawer.** Thread history is gated behind a CopilotKit
|
||
Intelligence license. Set `COPILOTKIT_LICENSE_TOKEN` (and the `INTELLIGENCE_*` URLs) in
|
||
`.env` to activate live thread history; without it the drawer shows a locked state.
|
||
|
||
## Running a Channel
|
||
|
||
`channel-host.mts` mounts the same agent as an Intelligence Channel
|
||
(Slack, Teams). It requires `INTELLIGENCE_API_KEY` and a declared Channel in
|
||
`.copilotkit/channels.json` — set both up with `copilotkit init` or
|
||
`copilotkit channels add`, which write that file and the credentials your
|
||
`.env` needs, then:
|
||
|
||
```bash
|
||
npm run channel
|
||
```
|
||
|
||
The host reads which Channel to hold from `.copilotkit/channels.json`. If a
|
||
project declares more than one, set `INTELLIGENCE_CHANNEL_NAME` to pick one.
|
||
|
||
The host holds no provider credentials and exposes no provider endpoint —
|
||
Intelligence owns the provider edge — so the same file works for every provider.
|
||
|
||
The Channel itself is declared in `channels.mts` — that is where to add commands,
|
||
reactions, or an `onMention` handler. `channel-host.mts` only owns the process
|
||
lifetime, and is byte-identical in every starter.
|
||
|
||
Once startup finishes, the log reports the truth per Channel:
|
||
|
||
- `Channel "<name>" is online.` — the session is up and can send.
|
||
- `Channel "<name>" is declared but no provider is attached yet.` —
|
||
a normal waiting state, not a failure. Run `copilotkit channels status` to
|
||
see what setup remains.
|
||
|
||
Neither message proves the provider app is installed, reachable, or that
|
||
anyone can message it — verify that separately (invite the bot, then message
|
||
it) before treating the Channel as working.
|
||
|
||
## Available scripts
|
||
|
||
- `npm run dev` — start the UI and agent together (dev mode)
|
||
- `npm run dev:ui` — start only the Next.js UI (port 3000)
|
||
- `npm run dev:agent` — start only the Claude agent (port 8000)
|
||
- `npm run build` — build the Next.js app for production
|
||
- `npm start` — start the production server
|
||
- `npm run install:agent` — (re)install the Python agent's dependencies
|
||
- `npm run channel` — hold an Intelligence Channel open (see "Running a Channel" above)
|
||
- `npm run typecheck:channel` — type-check the channel host on its own `tsconfig.channel.json`
|
||
|
||
## Project structure
|
||
|
||
```
|
||
├── src/
|
||
│ ├── app/
|
||
│ │ ├── page.tsx # Main page (chat + todos canvas + threads drawer)
|
||
│ │ ├── layout.tsx # CopilotKit v2 provider + A2UI catalog
|
||
│ │ └── api/copilotkit/[[...slug]]/ # CopilotKit runtime route (HttpAgent → :8000)
|
||
│ ├── components/ # Canvas, generative UI, chat, UI primitives
|
||
│ └── hooks/ # Example suggestions + generative-UI examples
|
||
└── agent/ # Python Claude agent (AG-UI on port 8000)
|
||
├── main.py # Server: mounts the adapter's FastAPI endpoint
|
||
├── pyproject.toml # Agent dependencies (managed by uv)
|
||
└── src/
|
||
├── agent.py # The agent: backend tools → ClaudeAgentAdapter
|
||
├── model.py # Model resolution (CLAUDE_MODEL)
|
||
├── query.py # query_data tool
|
||
├── a2ui_fixed_schema.py # search_flights tool (fixed A2UI schema)
|
||
├── a2ui_dynamic_schema.py # generate_a2ui tool (LLM-designed dashboard)
|
||
├── db.csv # Sample data for query_data
|
||
└── a2ui/schemas/flight_schema.json
|
||
```
|
||
|
||
## How it works
|
||
|
||
- The **frontend** uses CopilotKit's v2 React hooks. Shared state (like the todo list) lives in
|
||
the agent and syncs bidirectionally with the UI.
|
||
- The **runtime route** (`src/app/api/copilotkit/[[...slug]]/route.ts`) connects to the agent
|
||
over HTTP with `HttpAgent` from `@ag-ui/client`.
|
||
- The **agent** is a thin layer on the official
|
||
[`ag-ui-claude-sdk`](https://pypi.org/project/ag-ui-claude-sdk/) adapter. `src/agent.py`
|
||
defines the three backend tools and hands them to `ClaudeAgentAdapter`; `main.py` serves it
|
||
with the adapter's `add_claude_fastapi_endpoint`. The adapter drives Claude through the Claude
|
||
Agent SDK, bridges CopilotKit frontend tools + human-in-the-loop, and manages the shared
|
||
`todos` state via its built-in `ag_ui_update_state` tool.
|
||
|
||
To customize: add or edit tools in `agent/src/` and the system prompt in `agent/src/agent.py`,
|
||
and the UI in `src/app/page.tsx` and `src/components/`.
|
||
|
||
## Troubleshooting
|
||
|
||
**"I'm having trouble connecting to my tools" / agent unreachable**
|
||
|
||
- Make sure the agent is running on port 8000 (`npm run dev:agent`) and that
|
||
`ANTHROPIC_API_KEY` is set in `.env`.
|
||
- Confirm the agent's health check: `curl http://localhost:8000/health` → `{"status":"ok"}`.
|
||
|
||
**Python import errors**
|
||
|
||
- Reinstall the agent's dependencies: `cd agent && uv sync`.
|
||
|
||
## Learn more
|
||
|
||
- [Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk/overview)
|
||
- [CopilotKit documentation](https://docs.copilotkit.ai)
|
||
- [AG-UI protocol](https://docs.ag-ui.com)
|
||
- [Next.js documentation](https://nextjs.org/docs)
|
||
|
||
## License
|
||
|
||
MIT — see [LICENSE](./LICENSE).
|