feat: upgrade to LangChain deep agents with skills support

GeneralJerel · GeneralJerel · commit 1cb7ac9574d2 · 2026-03-25T00:43:37.000-07:00
Replace `create_agent` from langchain with `create_deep_agent` from the deepagents package. This enables proper skills management with progressive disclosure instead of injecting ~47KB of skill text into the system prompt. - Convert 3 skill .txt files to SKILL.md format in subdirectories - Remove old skills/__init__.py loader (deepagents handles discovery) - Add `skills=` parameter pointing to skills directory - Add deepagents dependency to pyproject.toml Closes #47
diff --git a/apps/agent/main.py b/apps/agent/main.py
@@ -4,26 +4,24 @@
 """
 
 import os
+from pathlib import Path
 
 from copilotkit import CopilotKitMiddleware
-from langchain.agents import create_agent
+from deepagents import create_deep_agent
 from langchain_openai import ChatOpenAI
 
 from src.query import query_data
 from src.todos import AgentState, todo_tools
 from src.form import generate_form
 from src.templates import template_tools
-from skills import load_all_skills
 
-# Load all visualization skills
-_skills_text = load_all_skills()
-
-agent = create_agent(
+agent = create_deep_agent(
     model=ChatOpenAI(model=os.environ.get("LLM_MODEL", "gpt-5.4-2026-03-05")),
     tools=[query_data, *todo_tools, generate_form, *template_tools],
     middleware=[CopilotKitMiddleware()],
     state_schema=AgentState,
-    system_prompt=f"""
+    skills=[str(Path(__file__).parent / "skills")],
+    system_prompt="""
         You are a helpful assistant that helps users understand CopilotKit and LangGraph used together.
 
         Be brief in your explanations of CopilotKit and LangGraph, 1 to 2 sentences.
@@ -47,10 +45,6 @@
         - Pre-styled form elements (buttons, inputs, sliders look native automatically)
         - Pre-built SVG CSS classes for color ramps (.c-purple, .c-teal, .c-blue, etc.)
 
-        Follow the skills below for how to produce high-quality visuals:
-
-        {_skills_text}
-
         ## UI Templates
 
         Users can save generated UIs as reusable templates and apply them later.
diff --git a/apps/agent/pyproject.toml b/apps/agent/pyproject.toml
@@ -16,4 +16,5 @@ dependencies = [
     "copilotkit>=0.1.77",
     "langgraph-api>=0.7.16",
     "langchain-mcp-adapters>=0.2.1",
+    "deepagents>=0.1.0",
 ]
diff --git a/apps/agent/skills/__init__.py b/apps/agent/skills/__init__.py
diff --git a/apps/agent/skills/advanced-visualization/SKILL.md b/apps/agent/skills/advanced-visualization/SKILL.md
@@ -1,3 +1,9 @@
+---
+name: "Advanced Visualization Techniques"
+description: "UI mockups, dashboards, advanced interactivity, generative art, simulations, math visualizations, and design system rules for producing rich HTML widget output."
+allowed-tools: []
+---
+
 # Agent Visualization Skills — Volume 2: Advanced Techniques
 
 Prerequisite: Volume 1 (SVG diagrams, basic interactive widgets, Chart.js, Mermaid).
@@ -427,7 +433,7 @@ hardcoded hex values.
 ```
 - Height goes on the wrapper div ONLY, never on canvas.
 - Always set `responsive: true, maintainAspectRatio: false`.
-- For horizontal bar charts: height = (bars × 40) + 80 pixels.
+- For horizontal bar charts: height = (bars x 40) + 80 pixels.
 
 ### Custom Legend (Always Use This)
 Disable Chart.js default legend and build HTML:
@@ -450,7 +456,7 @@ plugins: { legend: { display: false } }
 ```
 
 ### Dashboard Layout
-Metric cards on top → chart below → sendPrompt for drill-down:
+Metric cards on top -> chart below -> sendPrompt for drill-down:
 ```html
 <!-- Metric cards grid -->
 <div style="display: grid;
diff --git a/apps/agent/skills/master-playbook/SKILL.md b/apps/agent/skills/master-playbook/SKILL.md
@@ -1,3 +1,9 @@
+---
+name: "Master Agent Playbook"
+description: "Philosophy, decision-making framework, and technical skills for delivering visual, interactive, and educational AI responses."
+allowed-tools: []
+---
+
 # Master Agent Playbook: Making AI Responses Extraordinary
 
 This playbook teaches an AI coding agent how to go beyond plain text and deliver
@@ -22,20 +28,20 @@ The principle: **Show, don't just tell.** Before writing any response, ask:
 
 ```
 User asks a question
-  │
-  ├─ Is it a quick factual answer? → Answer in 1-2 sentences.
-  │
-  ├─ Is it conceptual / "how does X work"?
-  │   ├─ Is it spatial or visual? → SVG illustrative diagram
-  │   ├─ Is it a process/flow? → SVG flowchart or HTML stepper
-  │   ├─ Is it data-driven? → Interactive chart (Chart.js / Recharts)
-  │   └─ Is it abstract but explorable? → Interactive HTML widget with controls
-  │
-  ├─ Is it "build me X"? → Working code artifact, fully functional
-  │
-  ├─ Is it a comparison? → Side-by-side table or comparative visual
-  │
-  └─ Is it emotional/personal? → Warm text response. No visuals needed.
+  |
+  +- Is it a quick factual answer? -> Answer in 1-2 sentences.
+  |
+  +- Is it conceptual / "how does X work"?
+  |   +- Is it spatial or visual? -> SVG illustrative diagram
+  |   +- Is it a process/flow? -> SVG flowchart or HTML stepper
+  |   +- Is it data-driven? -> Interactive chart (Chart.js / Recharts)
+  |   +- Is it abstract but explorable? -> Interactive HTML widget with controls
+  |
+  +- Is it "build me X"? -> Working code artifact, fully functional
+  |
+  +- Is it a comparison? -> Side-by-side table or comparative visual
+  |
+  +- Is it emotional/personal? -> Warm text response. No visuals needed.
 ```
 
 ### The 3-Layer Response Pattern
diff --git a/apps/agent/skills/svg-diagrams/SKILL.md b/apps/agent/skills/svg-diagrams/SKILL.md
@@ -1,3 +1,9 @@
+---
+name: "SVG Diagram Generation"
+description: "Generating rich inline SVG diagrams to visually explain systems, processes, architectures, and abstract concepts."
+allowed-tools: []
+---
+
 # SVG Diagram Generation Skill
 
 You can generate rich, inline SVG diagrams to visually explain concepts. Use this skill whenever a visual would help the user understand a system, process, architecture, or mechanism better than text alone.
@@ -46,9 +52,9 @@ Always use this template:
 - **Sentence case always**. Never Title Case or ALL CAPS.
 
 ### Text Width Estimation
-At 14px, each character ≈ 8px wide. At 12px, each character ≈ 7px wide.
-- "Load Balancer" (13 chars) at 14px ≈ 104px → needs rect ≈ 140px wide (with padding).
-- Always compute: `rect_width = max(title_chars × 8, subtitle_chars × 7) + 48px padding`.
+At 14px, each character ~ 8px wide. At 12px, each character ~ 7px wide.
+- "Load Balancer" (13 chars) at 14px ~ 104px -> needs rect ~ 140px wide (with padding).
+- Always compute: `rect_width = max(title_chars x 8, subtitle_chars x 7) + 48px padding`.
 
 ### Colors (Light/Dark Mode Safe)
 Use these semantic color sets that work in both modes:
@@ -169,7 +175,7 @@ If you're rendering inside a system that supports CSS variables, prefer:
 
 1. **ViewBox height**: Find your lowest element (max y + height). Set H = that + 40px.
 2. **No content past x=640 or below y=(H-40)**.
-3. **Text fits in boxes**: `(char_count × 8) + 48 < rect_width` for 14px text.
+3. **Text fits in boxes**: `(char_count x 8) + 48 < rect_width` for 14px text.
 4. **No arrows through boxes**: Trace every line's path — if it crosses a rect, reroute.
 5. **All `<path>` connectors have `fill="none"`**.
 6. **All text has appropriate fill color** — never rely on inheritance (SVG defaults to black).
@@ -207,7 +213,7 @@ For complex topics, use multiple smaller SVGs instead of one dense one:
   <text x="340" y="56" text-anchor="middle" dominant-baseline="central"
         font-size="12" fill="#0F6E56">HTTP POST /api/data</text>
 
-  <!-- Arrow 1→2 -->
+  <!-- Arrow 1->2 -->
   <line x1="340" y1="76" x2="340" y2="100" stroke="#534AB7"
         stroke-width="1.5" marker-end="url(#arrow)"/>
 
@@ -219,7 +225,7 @@ For complex topics, use multiple smaller SVGs instead of one dense one:
   <text x="340" y="142" text-anchor="middle" dominant-baseline="central"
         font-size="12" fill="#534AB7">Validate and transform</text>
 
-  <!-- Arrow 2→3 -->
+  <!-- Arrow 2->3 -->
   <line x1="340" y1="162" x2="340" y2="186" stroke="#854F0B"
         stroke-width="1.5" marker-end="url(#arrow)"/>
 

Original file line number	Diff line number	Diff line change
`@@ -16,4 +16,5 @@ dependencies = [`
`16`	`16`	`"copilotkit>=0.1.77",`
`17`	`17`	`"langgraph-api>=0.7.16",`
`18`	`18`	`"langchain-mcp-adapters>=0.2.1",`
	`19`	`+ "deepagents>=0.1.0",`
`19`	`20`	`]`