AI 原生开放教材

外观

AI 工程从零到一（中文）源码研读·中文原文 ↗原件 ↓仓库 ↗

Harness 即库——子 agent 与会话存储 ​

一套可以直接导入的 harness：内置工具、用于上下文隔离的子 agent、hook、W3C trace 传播和会话持久化。Claude Agent SDK 是参考实现，也就是 Claude Code harness 的库形态；Claude Managed Agents 则是面向长时异步工作的托管替代品。

类型： Learn + Build 语言： Python（标准库） 前置要求： 阶段 14 · 01（Agent 循环）、阶段 14 · 10（技能库） 预计时间： ~75 分钟

学习目标 ​

  • 解释 Anthropic Client SDK（原始 API）与 Claude Agent SDK（harness 形态）的区别。
  • 描述子 agent —— 并行化和上下文隔离 —— 以及何时该上它们。
  • 说出 Python SDK 的会话存储接触面（append、load、list_sessions、delete、list_subkeys）以及 --session-mirror 的作用。
  • 用标准库实现一个 harness，带内置工具、上下文隔离的子 agent 派生、生命周期 hook 和一个会话存储。

问题背景 ​

一个原始 LLM API 只给你一次往返。一个生产 agent 需要工具执行、MCP 服务器、生命周期 hook、子 agent 派生、会话持久化、trace 传播。Claude Agent SDK 把这个形态作为一个库提供出来 —— 和 Claude Code 用的同一个 harness，暴露出来给自定义 agent。

核心概念 ​

Client SDK vs Agent SDK ​

  • Client SDK（anthropic）。 原始 Messages API。你掌管循环、工具、状态。
  • Agent SDK（claude-agent-sdk）。 内置工具执行、MCP 连接、hook、子 agent 派生、会话存储。Claude Code 循环作为一个库。

内置工具 ​

SDK 开箱提供 10+ 个工具：文件读/写、shell、grep、glob、网页抓取，等等。自定义工具通过标准的工具 schema 接口注册。

子 agent ​

Anthropic 记录了两个用途：

  1. 并行化。 并发跑相互独立的工作。「为这 20 个模块各找测试文件」就是 20 个并行的子 agent 任务。
  2. 上下文隔离。 子 agent 用它们自己的上下文窗口；只有结果返回给编排器。编排器的预算被保住了。

Python SDK 近期新增：list_subagents()、get_subagent_messages()，用于读取子 agent 的 transcript。

会话存储 ​

与 TypeScript 协议对齐：

  • append(session_id, message) —— 加一轮。
  • load(session_id) —— 恢复对话。
  • list_sessions() —— 枚举。
  • delete(session_id) —— 级联到子 agent 会话。
  • list_subkeys(session_id) —— 列出子 agent 键。

--session-mirror（CLI 标志）在 transcript 流式产出时把它镜像到一个外部文件，供调试用。

Hook ​

你可以注册的生命周期 hook：

  • PreToolUse、PostToolUse —— 对工具调用设关卡或审计。
  • SessionStart、SessionEnd —— 建立和拆除。
  • UserPromptSubmit —— 在模型看到用户输入之前对其采取行动。
  • PreCompact —— 在上下文压实之前运行。
  • Stop —— agent 退出时清理。
  • Notification —— 旁路告警。

hook 就是 pro-workflow（阶段 14 课程参考）和类似系统添加横切行为的方式。

W3C trace context ​

调用方上活跃的 OTel span 通过 W3C trace context 头传播进 CLI 子进程。整个多进程 trace 在你的后端里显示为一条 trace。

Claude Managed Agents ​

托管替代品（beta 头 managed-agents-2026-04-01）。长时运行的异步工作、内置 prompt 缓存、内置压实。用控制权换托管基础设施。

这个模式在哪里会出错 ​

  • 子 agent 过度派生。 为 100 个小任务派生 100 个子 agent。开销主导一切。改成批处理。
  • hook 蔓延。 每个团队都加 hook；启动时间膨胀。每季度审查 hook。
  • 会话膨胀。 会话越攒越多；体积增长。用 list_sessions + 过期策略。
figure
ae-subagent-isolation

动手构建 ​

code/main.py 用标准库实现 SDK 的形态：

  • Tool、ToolRegistry，带内置的 read_file、write_file、list_dir。
  • Subagent —— 私有上下文、隔离运行、返回结果。
  • SessionStore —— append、load、list、delete、list_subkeys。
  • Hooks —— pre_tool_use、post_tool_use、session_start、session_end。
  • 一个演示：主 agent 并行派生 3 个子 agent（各自隔离），聚合结果，持久化会话。

运行它：

python3 code/main.py

轨迹展示子 agent 的上下文隔离（编排器上下文大小保持有界）、hook 执行和会话持久化。

实际使用 ​

  • Claude Agent SDK 用于想要 Claude Code harness 形态的 Claude 优先产品。
  • Claude Managed Agents 用于托管的长时运行异步工作。
  • OpenAI Agents SDK（第 16 课）用于 OpenAI 优先的对应物。
  • LangGraph + 自定义工具 如果你想要图形态的状态机。

拿去用 ​

outputs/skill-claude-agent-scaffold.md 脚手架出一个 Claude Agent SDK 应用，带子 agent、hook、会话存储、MCP 服务器挂载和 W3C trace 传播。

练习 ​

  1. 加一个子 agent 派生器，把 20 个任务批成每组 5 个并行子 agent。度量编排器上下文大小，与每任务一个对比。
  2. 实现一个 PreToolUse hook，对 write_file 调用限速（每会话每分钟 5 次）。追踪行为。
  3. 把 list_subkeys 接起来渲染一棵子 agent 树。深层嵌套长什么样？
  4. 把玩具移植到真实的 claude-agent-sdk Python 包。工具注册有什么变化？
  5. 读 Claude Managed Agents 文档。你什么时候会从自托管切到托管？

关键术语 ​

术语大家怎么说它实际是什么
Agent SDK「Claude Code 作为库」harness 形态：工具、MCP、hook、子 agent、会话存储
Subagent「子 agent」独立上下文、自己的预算；结果冒泡上来
Session store「对话数据库」持久化、加载、列出、删除轮次，带子 agent 级联
Hook「生命周期回调」pre/post 工具、会话、prompt 提交、压实、停止
W3C trace context「跨进程 trace」父 span 传播进 CLI 子进程
Managed Agents「托管 harness」Anthropic 托管的长时运行异步工作
--session-mirror「transcript 镜像」在会话轮次流式产出时把它们写到一个外部文件
MCP server「工具接触面」挂在 agent 上的外部工具/资源来源

延伸阅读 ​