Claude Agent SDK Integration

Deep integration blueprint: weaving @anthropic-ai/claude-agent-sdk into 12 Paths as the practice substrate for building real agents.

12
Paths
13
SDK APIs
25+
Exercises
3
Capstones
L1-L5
Level Span
Philosophy

Why Claude Agent SDK as Practice Substrate

Theory Made Concrete

Every concept in docs/ maps to a real SDK API. "What is an agent loop?" becomes query() streaming messages. "What is tool use?" becomes allowedTools + canUseTool. No abstract pseudocode.

Progressive Complexity

SDK surface area graduates perfectly with the 3-track structure: Track 1 uses query() + tools. Track 2 adds session + hooks. Track 3 unlocks MCP + subagents + sandbox.

Real Over Simulated

Learners run actual agent code on their machine. Not a sandbox simulator, not pseudocode, not a framework wrapper. Direct SDK calls with real Claude API responses. Copy, paste, run.

Integration Strategy: Inline, Not Parallel

SDK code blocks are woven into existing lesson text, not as a separate "Lab" page. When a lesson explains "the agent loop", the SDK code block appears right there, showing the real implementation. Exercises at the end of each Path use SDK as their only language.

Progression

SDK Concept Graduation Map

Each row shows which SDK APIs are introduced at that level. dark = first introduced. light = carried forward from earlier.

Level
SDK APIs Introduced
L1
Explorer
P1: First Agent
query() for await..of message.type system.session_id
L1-L2
Explorer
P2: Tool Calling
query() allowedTools disallowedTools tools config tool_call / tool_result canUseTool (basic)
L2
Apprentice
P3: Prompts & Structured Output
query() systemPrompt (string) systemPrompt (preset) outputFormat Zod schema structured_output maxThinkingTokens
L2-L3
Apprentice
P4: Memory & Context
resume forkSession continue v2_createSession v2_prompt betas: context-1m
L2-L3
Apprentice
P5: Eval, Routing & Recovery
fallbackModel setModel() error codes supportedModels() accountInfo()
L3
Builder
P6: Patterns & Capstone
hooks.PreToolUse hooks.PostToolUse hooks.Stop settingSources permissionMode: plan
L3-L4
Builder+
P7-P8: MCP & Agentic RAG
createSdkMcpServer() tool() mcpServers (stdio) mcpServers (http) mcp__*__* naming mcpServerStatus()
L3-L4
Builder+
P9-P10: Multi-Agent & Code Gen
agents {} AgentDefinition model: haiku|sonnet|opus skills[] maxTurns hooks.SubagentStart/Stop
L4-L5
Expert
P11-P12: HITL & Production
permissionMode (all 4) canUseTool (advanced) sandbox {} enableFileCheckpointing rewindFiles() all 12 hooks plugins[]
Setup

Prerequisites (shown before P1)

Environment Setup

1
Node.js 18+ — node --version to verify
2
Claude Code CLI — npm install -g @anthropic-ai/claude-code
3
API Key — export ANTHROPIC_API_KEY="sk-ant-..."
4
Project scaffold — npm init -y && npm i @anthropic-ai/claude-agent-sdk zod
5
TypeScript (optional) — npm i -D typescript tsx && npx tsc --init

Learner-Level Adaptation

L1 Explorers only need steps 1-4. TypeScript is introduced at P3 with Zod schemas. The setup page detects the learner's current level and shows only the relevant steps.

Path-by-Path SDK Details

Detailed SDK integration for each of the 12 Paths (lessons, exercises, gates) has been merged into the Curriculum page. Each Path card shows SDK Focus APIs and per-lesson integration points inline.

Ripple Effects

Impact on Other Learn Modules

Flashcards

Add "Claude Agent SDK" deck: ~40 cards covering API signatures, error codes, message types, hook events. Auto-generated from exercises.

P1
Skills Library

Each SDK API becomes a skill entry. Skill detail pages link to the Path where the API is introduced. "Generate FlashCard" button creates SDK-specific cards.

P1
Chat Sim (AI Tutor)

Tutor recognizes SDK code in questions. Can explain error codes, suggest fixes for known issues, and walk through API usage step by step.

P2
Exercises Index

Replace "Coming Soon" placeholders with real SDK exercises. Each card shows: SDK APIs used, prerequisite Path, estimated time.

P0
Progress Dashboard

Track SDK API coverage: "You've used 8/13 core APIs". Badge triggers: "First query()" = Tried badge, "All hooks used" = Master badge.

P1
Daily Quests

New quest types: "What error code means X?", "Which hook fires when Y?", "Write a canUseTool for scenario Z".

P2
Coverage

SDK API ↔ Path Coverage Matrix

SDK Feature
Intro
Deepen
Master
query() + streaming
P1
P4
P12
allowedTools / disallowedTools / tools
P2
P6
P9
canUseTool permission callback
P2
P11
P12
systemPrompt (string + preset)
P3
P6
P9
outputFormat + structured_output
P3
P5
P8
Session (resume / fork / continue)
P4
P10
P12
V2 Session APIs
P4
P10
P12
fallbackModel + setModel()
P5
P9
P12
Hooks (12 events)
P6
P9
P12
MCP Servers (in-process + external)
P7
P8
P12
agents{} + AgentDefinition
P9
P10
P12
permissionMode (all 4)
P11
P12
—
sandbox + fileCheckpointing
P11
P12
—

Spiral Learning

Every SDK API appears at least twice: once at introduction (simplified, isolated), once at deepening (combined with other APIs), and optionally at mastery (production-grade, edge cases). This mirrors the competency matrix: Aware → Solid → Edge cases.

Rationale

Key Design Decisions

Inline over Parallel

SDK code lives inside lesson text, not in separate "lab" pages. Reduces navigation, keeps theory and practice co-located. Learner never has to context-switch between "the concept page" and "the code page".

Copy-Paste-Run over Playground

No browser-based code editor. Learners run real code on their machine with real API calls. This is production-skill transfer, not sandboxed simulation. The tradeoff: requires setup (Node.js + API key), but produces genuinely capable practitioners.

TypeScript-First from P3

P1-P2 use plain JavaScript for lowest barrier. P3 introduces TypeScript via Zod (structured output requires it). From P3 onward, all code is TypeScript. This mirrors the SDK's own design.

Error Prevention as Curriculum

The SDK's 14 known issues become teaching moments, not just a reference table. Issue #4 (context overflow) teaches session management. Issue #13 (MCP type field) teaches configuration discipline. Errors are the curriculum.

Level-Appropriate Complexity

L1 sees query("hello"). L3 sees hooks + sessions + tools. L5 sees sandbox + subagents + MCP + checkpointing. The SDK surface area grows exactly as the learner's competency grows. No API is shown before the learner is ready for it.