deanlu.ai

Claude Agent SDK Demo Project Learning Map

8 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.

这篇笔记是一张 Quartz 学习路线图，帮助从 SDK 入门示例走向受治理的企业智能体模式。

  • Core question: Which demo teaches which SDK production concern? 核心问题：哪个 Demo 对应哪个 SDK 生产化关注点？

  • Operational value: It prevents learning the demos as disconnected examples. 运营价值：它避免把 Demo 当成互不相关的示例来学习。

  • Best connection: Agent SDK Core Concepts, GitHub Projects for Agent SDK, How to Use Claude Cowork Effectively 最适合连接的内容：SDK 核心概念、GitHub 项目参考和 Claude Cowork 使用方法。

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.

Demo 项目不是一个单一应用，而是一组小章节，分别覆盖提示输入、智能体循环、工具使用、权限、钩子、流式输出、用户输入、会话、自定义工具和子智能体。

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. 主要观点：SDK 是智能体运行时，不是聊天包装器。

  • 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.

这些术语可以把每个 Demo 映射到企业设计关注点。

  • query() / 查询入口: Beginner entry point that starts the SDK agent loop.

    启动 SDK 智能体循环的入门入口。

  • 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.

    把 SDK 消息转成进度和输出的产品界面。

  • Custom MCP tool / 自定义 MCP 工具: Typed domain tool exposed to the agent through MCP.

    通过 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.

初学者可能被 Demo 效果吸引，却没有理解它对应的生产化关注点。

  • A demo with broad tools is not a safe enterprise default. 拥有宽泛工具的 Demo 不是安全的企业默认配置。

  • A local example may lack production security hardening. 本地示例可能缺少生产安全加固。

  • A multi-agent demo can hide context and cost complexity. 多智能体 Demo 可能隐藏上下文和成本复杂度。

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.

把 Demo 仓库当成阶梯来读：hello-world 学循环，chat app 学流式输出，AskUserQuestion 学审批，email agent 学 MCP 工具，research agent 学子智能体。

  • 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.

来源 Demo 展示了 query()、选项、钩子、WebSocket 流式输出、用户审批预览、带模式的自定义 MCP 工具和子智能体活动跟踪。

  • hello-world gives the smallest mental model. hello-world 提供最小心智模型。

  • email-agent is the bridge to domain tools. email-agent 是连接领域工具的桥梁。

  • research-agent shows role decomposition and audit hooks. research-agent 展示角色拆分和审计钩子。

3.4 Boundary

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

Demo 应用是本地开发示例。未经安全、凭证、日志和隐私审查，不应部署到生产环境。

  • Read-only first. 先只读。

  • Approved writes second. 再审批写入。

  • Autonomous writes last. 最后才考虑自主写入。

4. Concept Map

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

使用双向链接把这篇笔记接入更大的 Quartz 知识网络。

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.

图中的标签保持英文，便于 Quartz 渲染后跨页面复用，也方便技术读者快速识别。

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.

Demo 路线有价值，因为它一次只教授一个生产化关注点。这是构建安全企业智能体的正确学习方式。

  • 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. 下一步可能行动：把 hello-world 改成只读项目解释器。

  • What still needs verification: Current TypeScript SDK API shape and removed V2 session behavior. 仍需要验证的内容：当前 TypeScript SDK API 形态和已移除的 V2 会话行为。

Reuse Path

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

References

Graph View

Backlinks