Claude Agent SDK Demo Project Learning Map

4 min read

Source Snapshot

  • Origin: Claude Agent SDK docs
  • Type: Demo learning map
  • Author / org: Anthropic
  • One-line takeaway: Learn the demo repo as a ladder: query(), tool permissions, streaming UI, user input, custom MCP tools, and subagent orchestration.

Garden Card

This note is a Quartz-ready learning map for moving from beginner SDK examples to governed enterprise agent patterns.

1. Executive Summary

The demo project is not one application. It is a set of small chapters covering prompt input, agent loop behavior, tool use, permissions, hooks, streaming output, user input, sessions, custom tools, and subagents.

The safest beginner path is read-only first, approved writes second, autonomous writes last. This keeps learning aligned with enterprise safety.

  • Main idea: The SDK is an agent runtime, not a chat wrapper.

  • Why now: Enterprise agents need approval, logging, custom tools, and recovery paths.

  • Where it applies: Repo review, email triage, Feishu automation, manufacturing diagnostics, and knowledge capture.

Decision Signal

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

2. Key Technical Terms

Use these terms to map each demo to an enterprise design concern.

  • query(): Beginner entry point that starts the SDK agent loop.

  • Allowed tools: Explicit list of tools the agent can use.

  • PreToolUse hook: Policy checkpoint before a tool executes.

  • Streaming UI: Product interface that turns SDK messages into progress and output.

  • Custom MCP tool: Typed domain tool exposed to the agent through MCP.

  • Subagent: Specialist worker with separate prompt, model, and tools.

3. Core Notes

3.1 Problem

Beginners can be impressed by a demo without understanding what production concern it teaches.

  • A demo with broad tools is not a safe enterprise default.

  • A local example may lack production security hardening.

  • A multi-agent demo can hide context and cost complexity.

3.2 Mechanism

Read the demo repo as a staircase: hello-world for the loop, chat app for streaming, AskUserQuestion for approvals, email agent for MCP tools, and research agent for subagents.

  • Trace every message and tool call.

  • Reduce allowed tools before extending behavior.

  • Add hooks before adding write permissions.

3.3 Evidence

The source demos show query(), options, hooks, WebSocket streaming, user approval previews, custom MCP tools with schemas, and subagent activity tracking.

  • hello-world gives the smallest mental model.

  • email-agent is the bridge to domain tools.

  • research-agent shows role decomposition and audit hooks.

3.4 Boundary

Demo applications are local-development examples. They should not be deployed to production without security, credential, logging, and privacy review.

  • Read-only first.

  • Approved writes second.

  • Autonomous writes last.

4. Concept Map

Use wikilinks to connect this note into the broader Quartz graph.

flowchart LR
  A["hello-world"] --> B["Loop and Messages"]
  B --> C["Tools and Hooks"]
  C --> D["Streaming UI"]
  D --> E["Human Input"]
  E --> F["Custom MCP Tools"]
  F --> G["Subagent Workflows"]
  G --> H["Governed Agent Platform"]

Diagram labels stay in English for rendering consistency and easier reuse across published pages.

5. My Take

The demo path is useful because it teaches one production concern at a time. That is the right learning pattern for building safe enterprise agents.

  • What changed my thinking: UI state and approval flow are part of the agent architecture.

  • What I may do next: Rewrite hello-world into a read-only project explainer.

  • What still needs verification: Current TypeScript SDK API shape and removed V2 session behavior.

Reuse Path

Convert this note into a step-by-step lab checklist for learning the demo repo.

References

Graph View

Backlinks