wehub-resource-sync
138 lines
5.7 KiB
Markdown
138 lines
5.7 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.
|
||
|
||
## 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
|
||
|
||
## 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).
|