deanlu.ai

Claude Agent SDK Demo Project Learning Map

10 min read

Source Snapshot

Origin: Claude Agent SDK docs Author / org: Anthropic Why this matters: This project turns the abstract SDK concepts into runnable examples, which is the fastest beginner path from “Claude can chat” to “Claude can operate a controlled workflow with tools, sessions, user input, and audit hooks.”

One-line takeaway: Learn this repo as a ladder: start with query(), then tool permissions, then streaming UI, then custom MCP tools, then multi-agent orchestration.

1. Executive Summary

Reading Position

This note explains how to learn the Claude Agent SDK demo project for a beginner building enterprise-grade agentic AI workflows. It should help me understand what each demo teaches, how it maps to the core SDK concepts, and which use cases are worth adapting for manufacturing, Lark/Feishu, GitHub/Vercel, and Obsidian workflows.

Core Message

This repo is not one application. It is a collection of small demos that show different parts of the Claude Agent SDK operating model. The best way to learn it is to treat each folder as a chapter in the same system: prompt input, agent loop, tool use, permissions, hooks, streaming output, user input, sessions, custom tools, and subagents.

  • Main idea: The SDK is an agent runtime, not just a chat wrapper.
  • Why now: Enterprise AI value comes from agents that can read, act, ask for approval, log decisions, and resume work.
  • What changed my thinking: The serious design work is around the boundary of the loop: tools, permissions, sessions, and observability.
  • Where I can apply it: Internal assistants for repo review, email triage, Lark workflow automation, manufacturing issue diagnosis, report generation, and personal knowledge capture.

Decision Signal

If I only remember one thing from this note, it should be:

Start with a read-only agent loop, then add write actions only when permissions, logs, and recovery paths are explicit.

2. Key Ideas

2.1 query() Is The Beginner Entry Point

Concept

query() starts the SDK agent loop. You pass a prompt plus options, then iterate over streamed messages until the result is complete.

Evidence from project

  • hello-world/hello-world.ts imports query from @anthropic-ai/claude-agent-sdk.
  • It sets options such as maxTurns, cwd, model, allowedTools, and hooks.
  • It loops through messages and extracts assistant text from streamed output.

My interpretation

For a beginner, hello-world is the minimum mental model: the app sends work into the loop, Claude may emit messages or tool calls, and the host application decides how to display, log, or govern that stream.

2.2 Tool Permissions Are The Control Surface

Limitation

A powerful agent without a tight tool boundary can damage files, leak data, or act outside the intended business process.

Evidence from project

  • hello-world/hello-world.ts allows many built-in tools, including Read, Write, Edit, Bash, WebSearch, and Task.
  • It adds a PreToolUse hook to block .js and .ts writes outside agent/custom_scripts.
  • email-agent/ccsdk/ai-client.ts allows both built-in tools and custom MCP tools such as mcp__email__search_inbox.

My interpretation

This is the enterprise governance layer. For manufacturing or CIO-level automation, permissions should express policy: what the agent can read, what it can change, what needs approval, and what must be impossible.

2.3 Hooks Make The Agent Auditable And Enforceable

Example

A hook can block unsafe writes, log every subagent tool call, or notify a human when Claude is waiting for approval.

Evidence from project

  • hello-world uses a PreToolUse hook to enforce a file-writing rule.
  • research-agent/research_agent/utils/subagent_tracker.py uses pre/post tool hooks to write structured tool logs.
  • The research agent records who acted, what tool was used, when it happened, input parameters, output size, and errors.

My interpretation

Hooks turn an impressive demo into an operational system. They create the audit trail needed for data integrity, post-incident analysis, and safe delegation.

2.4 Streaming Is How Agent Work Becomes A Product UI

Concept

The SDK emits a message stream. A useful app needs to convert that stream into UI state, logs, progress indicators, and human approvals.

Evidence from project

  • simple-chatapp/server/ai-client.ts wraps query() behind an AgentSession.
  • It feeds user messages through an async queue and streams output back to the app.
  • ask-user-question-previews/server.ts forwards AskUserQuestion events to the browser over WebSocket, waits for the user response, then resumes the SDK loop.

My interpretation

The UI is not just chat decoration. It is the control room for long-running agent work: show progress, collect decisions, explain why the agent is waiting, and preserve enough state to resume safely.

2.5 MCP And Custom Tools Connect Claude To Real Business Systems

Example

The email demo exposes domain actions as custom tools: search inbox and read emails. A manufacturing version could expose tools like search_quality_incidents, read_work_order, or create_supplier_followup.

Evidence from project

  • email-agent/ccsdk/custom-tools.ts uses createSdkMcpServer and tool.
  • Tools are defined with schemas using zod.
  • The custom email tools catch errors and return structured text back to Claude.

My interpretation

This is the bridge from generic AI to enterprise workflow. The quality of the tool schema determines how safely Claude can operate over private systems.

2.6 Subagents Are For Parallel Specialist Work

Key Principle

Use subagents when the work naturally separates into specialist roles, not just because “multi-agent” sounds advanced.

Evidence from project

  • research-agent defines a lead agent plus researcher, data-analyst, and report-writer subagents.
  • Each subagent has its own prompt, tool list, and model.
  • The lead agent delegates through Task, and hooks track the subagent activity.

My interpretation

Subagents are useful when they reduce context overload and improve accountability. In enterprise workflows, this can mirror an operating process: investigator, analyst, reviewer, and report writer.

3. Structure Map

flowchart TD
  A["Beginner: hello-world"] --> B["Understand query(), messages, options"]
  B --> C["Control: tools + permissions + hooks"]
  C --> D["Product UI: simple-chatapp streaming loop"]
  D --> E["Human-in-loop: AskUserQuestion previews"]
  E --> F["Business tools: email-agent custom MCP server"]
  F --> G["Specialist workflows: research-agent subagents"]
  G --> H["Enterprise pattern: governed agent platform"]

Structure Insight

The project is organized like a learning staircase. Each demo adds one production concern: simple loop, persistent conversation, browser transport, user input, domain tools, then multi-agent orchestration.

4. Core Concepts To Demo Mapping

SDK Core ConceptWhere To StudyWhat It TeachesEnterprise Use Case
Agent loophello-world/hello-world.tsquery() starts a bounded autonomous loop and emits messagesRead-only repo explainer or document summarizer
Tool permissionshello-world/hello-world.ts, email-agent/ccsdk/ai-client.tsAllow only the tools needed for the jobSeparate diagnostic, drafting, and write-capable agents
Hookshello-world/hello-world.ts, research-agent/research_agent/utils/subagent_tracker.pyEnforce rules and log tool useAudit trail for regulated workflows
Streaming input/outputsimple-chatapp/server/ai-client.tsKeep a session alive while users continue interactingInternal assistant UI with live progress
User approval/inputask-user-question-previews/server.tsPause agent execution until the user chooses an optionApproval gates for publishing, sending, or changing records
Custom tools / MCPemail-agent/ccsdk/custom-tools.tsExpose domain systems through typed tool schemasLark, GitHub, Vercel, email, MES, ERP connectors
Sessionssimple-chatapp, hello-world-v2Preserve context across turns or resume laterLong-running task continuity
Subagentsresearch-agent/research_agent/agent.pyDelegate specialist work with separate tools and promptsResearch, diagnosis, data analysis, and report writing pipeline
Output artifactsresume-generator, excel-demo, research-agentAgent produces files such as .docx, spreadsheets, charts, PDFsAutomated business reports and evidence packs

Current SDK Caveat

hello-world-v2 is useful for understanding session-style APIs, but Anthropic’s current docs say the TypeScript V2 session API was removed in newer SDK versions. Treat it as historical or pin to an older SDK if running it.

5. Chart / Quantitative View

xychart-beta
  title "Learning value by demo for a beginner"
  x-axis ["hello", "chat", "ask-user", "email", "research", "excel/resume"]
  y-axis "Learning priority" 0 --> 10
  bar [10, 8, 8, 9, 9, 6]

Chart interpretation: hello-world gives the cleanest entry point. email-agent and research-agent are the highest-value enterprise patterns, but they should come after the loop, permissions, and streaming basics are understood.

6. Code / Technical Pattern

import { query } from "@anthropic-ai/claude-agent-sdk";
 
async function runReadOnlyProjectExplainer(prompt: string): Promise<void> {
  for await (const message of query({
    prompt,
    options: {
      maxTurns: 12,
      model: "sonnet",
      allowedTools: ["Read", "Glob", "Grep"],
      cwd: process.cwd(),
    },
  })) {
    if (message.type === "assistant") {
      const text = message.message.content
        .filter((block: any) => block.type === "text")
        .map((block: any) => block.text)
        .join("");
 
      if (text) {
        console.log(text);
      }
    }
 
    if (message.type === "result" && message.subtype !== "success") {
      throw new Error(`Agent failed: ${message.subtype}`);
    }
  }
}

What it demonstrates: This is the beginner-safe pattern: let the agent inspect files but not edit, run shell commands, or call external systems.

Production note: The next production step is not “more tools”; it is logging, error handling, cost limits, session capture, and explicit approval for state-changing actions. This protects operational efficiency because the agent can help quickly, and protects data integrity because it cannot silently mutate systems.

Implementation Risk

Before connecting an SDK agent to enterprise systems, validate credential scope, tool schemas, error handling, output logging, PII handling, and whether the runtime is isolated from production assets.

7. Highlight Blocks

Source Phrase

Agent SDK applications are built around Claude’s autonomous loop with tools, context, permissions, and sessions.

Key Principle

The safest learning path is read-only first, approved writes second, autonomous writes last.

Open Question

Which internal workflow should become my first serious adaptation: Lark agenda/task assistant, GitHub/Vercel publishing assistant, manufacturing issue diagnosis, or Obsidian knowledge capture?

Do Not Forget

Demo apps are local-development examples. The repo itself warns not to deploy them to production or use them at scale without security hardening.

8. Personal Synthesis

Practical Application

  1. Start with hello-world and rewrite it into a read-only project explainer for one local repo.
  2. Add one hook that logs every tool request and blocks unsafe paths.
  3. Study simple-chatapp to understand how a backend can stream SDK messages into a browser UI.
  4. Study ask-user-question-previews to learn the human-in-the-loop approval pattern.
  5. Study email-agent as the template for Lark/Feishu or GitHub/Vercel custom tools.
  6. Study research-agent only after the basics, because it combines subagents, prompts, hooks, logs, generated files, and orchestration.

Reusable Design Rule

When learning or adapting a Claude Agent SDK demo,
choose the smallest useful tool set,
make every state-changing action visible or approved,
log the session and tool calls,
and validate outputs outside the model loop before trusting them.

9. Beginner Learning Plan

  • Run hello-world and identify where query() starts, where options are passed, and where assistant text is extracted.
  • Change allowedTools to only Read, Glob, and Grep; observe how this changes the agent’s operating boundary.
  • Add or modify a hook that blocks one unsafe behavior and explains the reason.
  • Read simple-chatapp/server/ai-client.ts and draw the path from browser message to SDK stream and back.
  • Read ask-user-question-previews/server.ts and trace how canUseTool pauses execution until the browser answers.
  • Read email-agent/ccsdk/custom-tools.ts and identify the tool name, schema, handler, error path, and returned content.
  • Read research-agent/research_agent/agent.py and identify the lead agent, subagent definitions, allowed tools, and hook tracker.
  • Pick one personal or enterprise use case and sketch the tools, permissions, session state, and approval points.

11. References & Credits

Attribution

This note is based on Anthropic documentation, the local demo repository, and my existing Obsidian note on Claude Agent SDK core concepts. Keep source links visible so future updates can be checked against SDK changes.

Graph View