Phase 14 · Lesson 17 of 54

The Harness as a Library — Subagents and Session Store

A harness you can import: built-in tools, subagents for context isolation, hooks, W3C trace propagation, session persistence. The Claude Agent SDK is the reference example — the library form of the Claude Code harness — and Claude Managed Agents is the hosted alternative for long-running async work.

Lesson 17 of 54Learn + Build~75 minutesPython (stdlib)

Before this: Lesson 1 of Phase 14 (Agent Loop), lesson 10 of Phase 14 (Skill Libraries)

On this page

Learning Objectives

  • Explain the difference between the Anthropic Client SDK (raw API) and the Claude Agent SDK (harness shape).
  • Describe subagents — parallelization and context isolation — and when to reach for them.
  • Name the Python SDK's session store surface (append, load, list_sessions, delete, list_subkeys) and the role of --session-mirror.
  • Implement a stdlib harness with built-in tools, subagent spawning with isolated context, lifecycle hooks, and a session store.

The Problem

A raw LLM API gets you one round-trip. A production agent needs tool execution, MCP servers, lifecycle hooks, subagent spawning, session persistence, trace propagation. Claude Agent SDK ships this shape as a library — the same harness Claude Code uses, exposed for custom agents.

The Concept

Client SDK vs Agent SDK

  • Client SDK (anthropic). Raw Messages API. You own the loop, the tools, the state.
  • Agent SDK (claude-agent-sdk). Built-in tool execution, MCP connections, hooks, subagent spawning, session store. The Claude Code loop as a library.

Built-in tools

The SDK ships 10+ tools out of the box: file read/write, shell, grep, glob, web fetch, more. Custom tools register via the standard tool-schema interface.

Subagents

Two purposes documented by Anthropic:

  1. Parallelization. Run independent work concurrently. "Find the test file for each of these 20 modules" is 20 parallel subagent tasks.
  2. Context isolation. Subagents use their own context window; only results return to the orchestrator. The orchestrator's budget is preserved.

Python SDK recent additions: list_subagents(), get_subagent_messages() for reading subagent transcripts.

Session store

Protocol parity with TypeScript:

  • append(session_id, message) — add a turn.
  • load(session_id) — restore conversation.
  • list_sessions() — enumerate.
  • delete(session_id) — with cascade to subagent sessions.
  • list_subkeys(session_id) — list subagent keys.

--session-mirror (CLI flag) mirrors the transcript to an external file as it streams, for debugging.

Hooks

Lifecycle hooks you can register:

  • PreToolUse, PostToolUse — gate or audit tool calls.
  • SessionStart, SessionEnd — set up and tear down.
  • UserPromptSubmit — act on user input before the model sees it.
  • PreCompact — run before context compaction.
  • Stop — cleanup on agent exit.
  • Notification — side-channel alerts.

Hooks are how pro-workflow (Phase 14 curriculum reference) and similar systems add cross-cutting behavior.

W3C trace context

OTel spans active on the caller propagate into the CLI subprocess via W3C trace context headers. The whole multi-process trace shows up as one trace in your backend.

Claude Managed Agents

The hosted alternative (beta header managed-agents-2026-04-01). Long-running async work, built-in prompt caching, built-in compaction. Trade control for managed infrastructure.

Where this pattern goes wrong

  • Subagent over-spawn. Spawning 100 subagents for 100 tiny tasks. Overhead dominates. Batch instead.
  • Hook creep. Every team adds hooks; startup time balloons. Review hooks quarterly.
  • Session bloat. Sessions accumulate; size grows. Use list_sessions + expiry policy.
ae-subagent-isolation

Build It

code/main.py implements the SDK shape in stdlib:

  • Tool, ToolRegistry with built-in read_file, write_file, list_dir.
  • Subagent — private context, isolated run, results returned.
  • SessionStore — append, load, list, delete, list_subkeys.
  • Hooks — pre_tool_use, post_tool_use, session_start, session_end.
  • A demo: main agent spawns 3 subagents in parallel (each isolated), aggregates results, persists session.

Run it:

python3 code/main.py

The trace shows subagent context isolation (orchestrator context size stays bounded), hook execution, and session persistence.

Use It

  • Claude Agent SDK for Claude-first products that want the Claude Code harness shape.
  • Claude Managed Agents for hosted long-running async work.
  • OpenAI Agents SDK (Lesson 16) for OpenAI-first counterparts.
  • LangGraph + custom tools if you want the graph-shaped state machine instead.

Ship It

outputs/skill-claude-agent-scaffold.md scaffolds a Claude Agent SDK app with subagents, hooks, session store, MCP server attachment, and W3C trace propagation.

Exercises

  1. Add a subagent spawner that batches 20 tasks into groups of 5 parallel subagents. Measure orchestrator context size vs one-per-task.
  2. Implement a PreToolUse hook that rate-limits write_file calls (5 per minute per session). Trace the behavior.
  3. Wire list_subkeys to render a subagent tree. What does deep nesting look like?
  4. Port the toy to the real claude-agent-sdk Python package. What changes about tool registration?
  5. Read the Claude Managed Agents docs. When would you switch from self-hosted to managed?

Key Terms

Term What people say What it actually means
Agent SDK "Claude Code as a library" Harness shape: tools, MCP, hooks, subagents, session store
Subagent "Child agent" Separate context, own budget; results bubble up
Session store "Conversation DB" Persist, load, list, delete turns with subagent cascade
Hook "Lifecycle callback" Pre/post tool, session, prompt submit, compact, stop
W3C trace context "Cross-process trace" Parent span propagates into CLI subprocess
Managed Agents "Hosted harness" Anthropic-hosted long-running async work
--session-mirror "Transcript mirror" Writes session turns to an external file as they stream
MCP server "Tool surface" External tool/resource source attached to the agent

Further Reading

Check yourself

Quick quiz

  1. What is the difference between the Anthropic Client SDK and the Claude Agent SDK?

    1. Client SDK is raw Messages API; Agent SDK is the Claude Code harness shape with built-in tools, MCP, hooks, subagents, and session store
    2. There is no difference
    3. Client SDK is for Python only
    4. Client SDK is paid; Agent SDK is free
    Show the answer

    A. Client SDK is raw Messages API; Agent SDK is the Claude Code harness shape with built-in tools, MCP, hooks, subagents, and session store Client SDK gives you the loop; Agent SDK ships the loop pre-built.

  2. What are the two documented purposes of subagents?

    1. Authn and authz
    2. Logging and metrics
    3. Caching and rate limiting
    4. Parallelization and context isolation
    Show the answer

    D. Parallelization and context isolation Subagents run independent work concurrently and preserve the orchestrator's context budget by isolating context.

  3. Which method is NOT part of the session store surface?

    1. append
    2. compile_prompt
    3. load
    4. list_subkeys
    Show the answer

    B. compile_prompt Session store ships append, load, list_sessions, delete, list_subkeys; compile_prompt is not a session API.

  4. Which is NOT a Claude Agent SDK lifecycle hook?

    1. PreEmbedding
    2. PreToolUse
    3. PostToolUse
    4. PreCompact
    Show the answer

    A. PreEmbedding Hooks include PreToolUse, PostToolUse, SessionStart/End, UserPromptSubmit, PreCompact, Stop, Notification. PreEmbedding is not a hook.

  5. How does trace context propagate across the agent and CLI subprocess?

    1. Only via the provider's dashboard
    2. Through the file system
    3. Through environment variables only
    4. Through W3C trace context headers passed into the CLI subprocess
    Show the answer

    D. Through W3C trace context headers passed into the CLI subprocess OTel spans on the caller propagate into the CLI subprocess via W3C trace context, so the whole multi-process run is one trace.

  6. What is subagent over-spawn and when does it happen?

    1. Spawning more subagents than CPU cores
    2. Spawning before SessionStart
    3. Spawning 100 subagents for 100 tiny tasks where overhead dominates; batch instead
    4. Forgetting to close subagents
    Show the answer

    C. Spawning 100 subagents for 100 tiny tasks where overhead dominates; batch instead Subagents have overhead; batch small tasks instead of spawning one each.

  7. What does Claude Managed Agents trade off against the self-hosted SDK?

    1. Tracing for streaming
    2. Tools for memory
    3. Latency for cost
    4. Control for managed infrastructure (long-running async, built-in prompt caching, built-in compaction)
    Show the answer

    D. Control for managed infrastructure (long-running async, built-in prompt caching, built-in compaction) Managed Agents is the hosted alternative for long-running async work; less control, less ops surface.

Questions people ask

What is the Claude Agent SDK?

The Claude Agent SDK is Anthropic's library version of the Claude Code harness. It provides built-in tools such as file and shell access, subagents, hooks, and session storage, so developers can build their own agents on it.

What is a subagent?

A subagent is a helper agent the main agent starts for a focused job, such as searching files. It works in its own context and returns only a summary, which keeps the main conversation shorter and more focused.

Run the code Read it on GitHub

Next lessonProduction Agent Runtimes — Fast Instantiation and Typed WorkflowsPrevious: OpenAI Agents SDK: Handoffs, Guardrails, Tracing

Lessons from AI Engineering from Scratch by Rohit Ghumare and contributors, MIT license. Notes for owners by Lozo. License

Next step

Rather have it built for you?

Reading is optional. Tell me what's stuck and I'll build it into the business you already run.

Tell me what's stuck
  • A real conversation, not a pitch
  • You keep your accounts
  • Nothing sends without your yes