CLAUDE.md

1# CopilotKit + LangGraph Todo Demo
2 
3## Purpose
4 
5This repository serves as both a **showcase** and **template** for building AI agents with CopilotKit and LangGraph. It demonstrates how CopilotKit can drive interactive UI beyond just chat, using a **collaborative todo list** as the primary example.
6 
7**Target audience:** Developers evaluating CopilotKit or starting new projects with AI agents.
8 
9## Core Concept
10 
11The todo list demonstrates **agent-driven UI** where:
12 
13- The agent can manipulate application state (adding todos, updating status, organizing tasks)
14- Users can interact with the same state (editing titles, checking off tasks, deleting todos)
15- Both agent and user changes update the same shared state
16- The UI reactively updates based on agent state changes
17 
18This uses CopilotKit's **v2 agent state pattern** where state lives in the agent and syncs to the frontend.
19 
20## Architecture
21 
22This is a **flat npm project** with a Next.js frontend at the root and a Python agent in `agent/`.
23 
24### Repository Structure
25 
26```
27├── src/
28│   ├── app/
29│   │   ├── page.tsx              # Main page - wires up all components
30│   │   └── api/copilotkit/       # CopilotKit API route
31│   ├── components/
32│   │   ├── canvas/               # Todo list UI
33│   │   │   ├── index.tsx         # Canvas container
34│   │   │   ├── todo-list.tsx     # Todo list with columns
35│   │   │   ├── todo-column.tsx   # Column (pending/completed)
36│   │   │   └── todo-card.tsx     # Individual todo card
37│   │   ├── example-layout/       # Layout: chat + canvas side-by-side
38│   │   └── generative-ui/        # Example generative UI components
39│   └── hooks/
40│       ├── use-generative-ui-examples.tsx  # Example CopilotKit patterns
41│       └── use-example-suggestions.tsx     # Chat suggestions
42├── agent/                         # LangGraph Python agent
43│   ├── main.py                    # Agent entry point
44│   └── src/
45│       ├── todos.py               # Todo tools and state schema
46│       └── query.py               # Example data query tool
47├── scripts/                       # Agent setup and run scripts
48│   ├── setup-agent.sh / .bat
49│   └── run-agent.sh / .bat
50├── package.json                   # Root project config (npm + concurrently)
51└── next.config.ts
52```
53 
54## Key Pattern: Agent State with CopilotKit v2
55 
56The todo list uses **CopilotKit v2's agent state pattern** where state lives in the agent backend and syncs bidirectionally with the frontend.
57 
58### How It Works
59 
601. **Agent defines state schema and tools** (Python)
61 
62```python
63   # agent/src/todos.py
64   class Todo(TypedDict):
65       id: str
66       title: str
67       description: str
68       emoji: str
69       status: Literal["pending", "completed"]
70 
71   class AgentState(TypedDict):
72       todos: list[Todo]
73 
74   @tool
75   def manage_todos(todos: list[Todo], runtime: ToolRuntime) -> Command:
76       """Manage the current todos."""
77       return Command(update={"todos": todos, ...})
78```
79 
802. **Frontend reads from agent state**
81 
82```typescript
83   // src/components/canvas/index.tsx
84   const { agent } = useAgent();
85 
86   return (
87     <TodoList
88       todos={agent.state?.todos || []}
89       onUpdate={(updatedTodos) => agent.setState({ todos: updatedTodos })}
90       isAgentRunning={agent.isRunning}
91     />
92   );
93```
94 
953. **User interactions update agent state**
96 
97```typescript
98   // User clicks checkbox → frontend calls agent.setState()
99   const toggleStatus = (todo) => {
100     const updated = todos.map((t) =>
101       t.id === todo.id
102         ? { ...t, status: t.status === "completed" ? "pending" : "completed" }
103         : t,
104     );
105     agent.setState({ todos: updated });
106   };
107```
108 
1094. **Agent can manipulate state via tools**
110   - The agent calls `manage_todos` tool to update the todo list
111   - Both user and agent changes update the same `agent.state.todos`
112   - Frontend automatically re-renders when state changes
113 
114### Why This Pattern?
115 
116- **Single source of truth**: State lives in the agent, not duplicated in frontend
117- **Bidirectional sync**: User changes → agent state, Agent changes → UI update
118- **Simple**: No need for separate frontend state management
119- **Observable**: Agent has full visibility into state changes
120 
121## Implementation Details
122 
123### Agent Backend
124 
125**Agent Definition** (`agent/main.py`):
126 
127```python
128from langchain.agents import create_agent
129from copilotkit import CopilotKitMiddleware
130from src.todos import todo_tools, AgentState
131 
132agent = create_agent(
133    model="gpt-5.5",
134    tools=[*todo_tools, ...],  # manage_todos, get_todos
135    middleware=[CopilotKitMiddleware()],
136    state_schema=AgentState,  # Defines state shape
137    system_prompt="You are a helpful assistant..."
138)
139```
140 
141**Todo Tools** (`agent/src/todos.py`):
142 
143```python
144@tool
145def manage_todos(todos: list[Todo], runtime: ToolRuntime) -> Command:
146    """Manage the current todos."""
147    # Ensure todos have unique IDs
148    for todo in todos:
149        if "id" not in todo or not todo["id"]:
150            todo["id"] = str(uuid.uuid4())
151 
152    # Update agent state
153    return Command(update={
154        "todos": todos,
155        "messages": [ToolMessage(...)]
156    })
157 
158@tool
159def get_todos(runtime: ToolRuntime):
160    """Get the current todos."""
161    return runtime.state.get("todos", [])
162```
163 
164### Frontend
165 
166**Canvas Component** (`src/components/canvas/index.tsx`):
167 
168```typescript
169export function Canvas() {
170  const { agent } = useAgent();  // CopilotKit v2 hook
171 
172  return (
173    <div className="h-full p-8 bg-gray-50">
174      <TodoList
175        // Read state from agent
176        todos={agent.state?.todos || []}
177        // Update state in agent
178        onUpdate={(updatedTodos) => agent.setState({ todos: updatedTodos })}
179        // React to agent execution
180        isAgentRunning={agent.isRunning}
181      />
182    </div>
183  );
184}
185```
186 
187**Todo List** (`src/components/canvas/todo-list.tsx`):
188 
189```typescript
190export function TodoList({ todos, onUpdate, isAgentRunning }: TodoListProps) {
191  const toggleStatus = (todo: Todo) => {
192    const updated = todos.map((t) =>
193      t.id === todo.id
194        ? { ...t, status: t.status === "completed" ? "pending" : "completed" }
195        : t
196    );
197    onUpdate(updated);  // Calls agent.setState()
198  };
199 
200  const addTodo = () => {
201    const newTodo = { id: crypto.randomUUID(), ... };
202    onUpdate([...todos, newTodo]);
203  };
204 
205  return (
206    <div className="flex gap-8">
207      <TodoColumn title="To Do" todos={pendingTodos} onAddTodo={addTodo} ... />
208      <TodoColumn title="Done" todos={completedTodos} ... />
209    </div>
210  );
211}
212```
213 
214### How State Flows
215 
2161. **User adds/edits todo** → Frontend calls `agent.setState({ todos: [...] })`
2172. **Agent state updates** → CopilotKit syncs to backend
2183. **Agent observes change** → Can respond via `manage_todos` tool
2194. **Agent modifies todos** → Calls `manage_todos` tool
2205. **State syncs to frontend** → `agent.state.todos` updates
2216. **UI re-renders** → React sees new state and updates display
222 
223**Key insight**: State lives in the agent, frontend just reads/writes to it via CopilotKit hooks.
224 
225## Tech Stack
226 
227- **Frontend**: Next.js 16, React 19, TailwindCSS 4
228- **Agent**: LangGraph (Python), OpenAI GPT-5.2
229- **CopilotKit**: React hooks for agent integration (v2)
230- **Build**: npm with concurrently for parallel dev processes
231- **Other**: Recharts for generative UI examples
232 
233## Development
234 
235```bash
236# Install dependencies (also sets up agent via postinstall)
237npm install
238 
239# Start both frontend and agent
240npm run dev
241 
242# Start individually
243npm run dev:ui      # Next.js frontend on port 3000
244npm run dev:agent   # LangGraph agent on port 8123
245 
246# Build
247npm run build
248```
249 
250### Environment Setup
251 
252```bash
253# Set OpenAI API key
254cp .env.example .env
255# Edit .env and add your OPENAI_API_KEY
256```
257 
258## Design Principles
259 
2601. **Simple over complex** - The todo list is intentionally simple and focused
2612. **CopilotKit v2 patterns** - Uses modern agent state management
2623. **Template-first** - Code is meant to be forked and extended
2634. **Showcasing agent-driven UI** - Demonstrates AI manipulating application state beyond chat
264 
265---
266 
267## Key Takeaways for Developers
268 
269**State Management Pattern**: This app uses CopilotKit v2's agent state pattern where:
270 
271- State is defined in the agent backend (Python TypedDict)
272- Frontend reads via `agent.state.todos`
273- Frontend writes via `agent.setState({ todos: ... })`
274- Agent can modify state via tools (`manage_todos`)
275- Changes sync bidirectionally automatically
276 
277**When extending this template**:
278 
279- Define state schema in the agent (`AgentState`)
280- Create tools that manipulate state via `Command(update={...})`
281- Use `useAgent()` hook in frontend to read/write state
282- Let CopilotKit handle the sync - no manual state management needed
283 
284This pattern works great for **agent-driven applications** where the AI needs to manipulate structured application state, not just chat.
285