Claude Agent SDK（Anthropic）

1. Introduction

1.1. Platform Positioning and Origin

Claude Agent SDK is the agent runtime library officially provided by Anthropic, used to embed the Claude Code tooling of "tools + agent loop + context management" programmatically into a developer's own process, with language coverage of Python and TypeScript. Here is the exact positioning statement from Anthropic's official engineering blog:

"The Claude Agent SDK is a powerful, general-purpose agent harness adept at coding, as well as other tasks that require the model to use tools to gather context, plan, and execute."

This statement is of tone-setting significance throughout the entire AI Harness research: it is the first time a leading model vendor wrote the word "harness" into a product definition, rather than treating it as an internal implementation jargon. It confirms the core judgment in the parameter card — Harness is not responsible for improving model intelligence, but for transforming the model's uncertainty into engineering predictability.

It is worth emphasizing the SDK's three boundaries:

1. Boundary with Claude Code CLI: the CLI is a human-in-the-loop terminal tool, while the SDK is a program-in-the-loop programming library; both run on the same agent loop.
2. Boundary with Anthropic Client SDK: the Client SDK exposes only the Messages API, so the tool loop must be written by the developer; the Agent SDK builds in the tool loop, permissions, compaction, and sessions entirely.
3. Boundary with Managed Agents: Managed Agents is a REST API product hosted by Anthropic, with the sandbox provided by Anthropic; the Agent SDK runs in the developer's own process, so the sandbox must be solved by the developer.

1.2. Basic Information Card

1.3. Development Timeline

1.4. Position in the AI Harness System

According to the boundary table in the parameter card, Claude Agent SDK is neither a pure Agent Framework nor an Agent Platform, but rather a vendor-provided Harness reference implementation:

• It covers most of L1~L4 and provides strong primitives for L6 (permission modes, Hooks interception, budget caps);
• It does not build in L5 (evaluation and observability) and multi-tenant governance; these two layers must be completed by the host system;
• It provides no UI, tenancy, or billing, and therefore does not constitute an Agent Platform.

This is also where it is most easily misread: developers often equate "installing the Agent SDK" with "having a Harness", but in reality the SDK only provides the chassis — the evaluation set, regression, and auditing still need to be self-built.

2. Glossary

3. Features

3.1. Built-in Tool Set

The SDK ships with a set of file and retrieval tools out of the box; the developer decides the agent's visible scope through the allowed_tools allowlist:

Read-only scenarios can be explicitly configured as ["Read", "Glob", "Grep"], and the agent cannot go beyond that list. This "allowlist-as-capability-boundary" design is the meeting point of L2 and L6.

3.2. Hooks Event Mechanism

Hooks are the most Harness-typical design in the SDK — it makes "interception points" first-class citizens. Typical events are as follows:

The callback returns a decision object that can express four intentions: allow, block, rewrite input, and inject context. For example, use PreToolUse with matcher Write|Edit to intercept writes to a .env file and return permissionDecision: "deny".

3.3. Permissions and Approval

The SDK's permission decision is an ordered chain: Hooks → deny rules → permission mode → allow rules → canUseTool callback. This order matters, because it means:

• Hooks have the highest priority and can hard-block;
• canUseTool sits at the end as the fallback human-approval slot and can suspend indefinitely waiting for a decision;
• permission mode is a coarse-grained switch, allow / deny rules are medium-grained, and canUseTool is fine-grained.

The three layers stacked together constitute the main implementation form of the L6 governance layer on this platform.

3.4. Sessions, Subagents, and Context Management

Three mechanisms together solve the "long-task" problem:

1. Session persistence: sessions are written to disk in JSONL, carrying the complete file-read history, conversation context, and completed reasoning; passing the session id back via resume resumes the run and avoids re-reading.
2. Subagent isolation: a subagent's context starts fresh, intermediate tool calls remain inside the subagent, and only one final message is returned. This is the most effective "context isolation" means at the L1 layer.
3. Context Compaction: when approaching the token limit, early turns are automatically summarized.

The combined effect of the three is: the main context length stays approximately constant, so the task length can be far greater than the context window.

3.5. MCP and Skills Extension

• MCP: the SDK supports three transports — stdio subprocess, HTTP/SSE remote services, and in-process SDK MCP servers. Custom tools can be implemented directly as in-process MCP servers without an extra process.
• Skills: organized as a directory + SKILL.md, with the YAML frontmatter necessarily containing name and description. Progressive disclosure separates "capability description" from "capability implementation", so that mounting dozens of Skills costs about as much as mounting a few.

3.6. Budget and Runtime Constraints

4. Platform Architecture

图 4-1｜Claude Agent SDK 四层架构（宿主 × SDK × 执行面 × 模型后端）

数据来源：基于本文分析绘制的示意图。

4.1. Layered Architecture

┌──────────────────────────────────────────────────────────┐
│ 宿主应用（你自己的进程）                                    │
│  - 任务编排 / 队列 / 多租户 / 计费                          │
│  - canUseTool 审批回调                                     │
└──────────────────────────────────────────────────────────┘
                          │
┌──────────────────────────────────────────────────────────┐
│ Claude Agent SDK                                          │
│  query() / ClaudeSDKClient                                │
│  ├─ Agent Loop（接收 → 评估 → 执行工具 → 回灌 → 重复）      │
│  ├─ Context Manager（Compaction / Subagent 隔离）          │
│  ├─ Permission Engine（Hooks → deny → mode → allow → 回调）│
│  ├─ Session Store（JSONL 落盘，resume / fork）             │
│  └─ Extension Loader（MCP / Skills / Plugins / Commands）  │
└──────────────────────────────────────────────────────────┘
                          │
┌──────────────────────────────────────────────────────────┐
│ 执行面                                                     │
│  - Built-in Tools（Read/Write/Edit/Bash/Glob/Grep/...）    │
│  - MCP Servers（stdio / HTTP / in-process）                │
│  - 外部沙箱（需宿主自备：Docker / 容器 / 受限用户）           │
└──────────────────────────────────────────────────────────┘
                          │
┌──────────────────────────────────────────────────────────┐
│ 模型后端                                                   │
│  Anthropic API / Bedrock / Vertex AI / Azure AI Foundry    │
└──────────────────────────────────────────────────────────┘

4.2. Complete Lifecycle of a Single Query

1. Initialization: the SDK returns a SystemMessage (of the init subtype) carrying the session_id.
2. Prompt processing: the UserPromptSubmit hook fires, allowing context to be injected or filtered.
3. Model reasoning: the model returns a ThinkingBlock and / or a ToolUseBlock.
4. Pre-tool interception: the PreToolUse hook matches by matcher and returns allow / block / rewrite.
5. Permission decision: Hooks → deny → permission mode → allow → canUseTool.
6. Tool execution: the execution result is fed back as a UserMessage via ToolResultBlock.
7. Loop: return to step 3 until the model output contains no tool calls.
8. Wrap-up: the Stop hook fires and a ResultMessage is returned.

4.3. Boundaries with CLI / Client SDK / Managed Agents

5. Harness Design

5.1. Overview of the Six-Layer Capabilities

5.2. L1 Context Engineering Layer

Claude Agent SDK's design at L1 can be summarized into four principles:

1. Filesystem-as-context: large objects do not enter the context window; only the path and summary are placed in the context, and the object is read when needed. This is an extension of the "MCP-as-Code-API" approach — intermediate data stays in the execution environment rather than the context window.
2. Subagent-as-isolation-unit: exploratory, high-noise retrieval work is pushed down to subagents, and the main context only receives the conclusions.
3. Progressive disclosure: Skills only load name + description at session start, load the full text on a hit, and read scripts and reference files on demand.
4. Compaction as fallback: when approaching the limit, early turns are automatically summarized.

The cost is that both compaction and isolation lose details. This is also the platform's only negative item at L1 — the more aggressive the context strategy, the weaker the traceability.

5.3. L2 Tools and Execution Layer

• Tool registration: built-in tools + custom in-process MCP servers + external MCP servers (stdio / HTTP).
• Call form: predominantly serial; batching is hinted at by PostToolBatch, implying a batch-call semantic exists.
• Execution isolation: explicitly absent. According to the official docs, the SDK does not provide container isolation, and the agent can access the host filesystem by default; for production safety you must add Docker or an equivalent isolation yourself.

This item is the risk point most easily overlooked during selection: the SDK's "very capable" and "not secure by default" are two sides of the same coin.

5.4. L3 Orchestration and Control Layer

The judgment of this section is: at L3, Claude Agent SDK belongs to "implicit orchestration", forming the two ends of the same axis with LangGraph's "explicit orchestration".

Concretely:

• Control flow is decided autonomously by the model within the loop; the developer writes no graphs and no state machines;
• only three structured means are available: subagent derivation, Hooks interception, and session resume/fork;
• there is no DAG, no conditional-branch primitive, and no parallel orchestrator (parallelism is achieved by deriving multiple subagents in a single prompt).

The flexibility ↔ predictability tension is sharpest here:

• the flexibility gained: no need to enumerate paths in advance, adapting to open-ended tasks;
• the predictability paid: the same input may take different paths across two runs, making it impossible to assert "execution order" regressions at the code level.

The corresponding engineering compensation is to confine unpredictability within Hooks and the permission chain — not to control "which way to go", but to control "which ways are forbidden". This is one representative answer offered by this platform.

5.5. L4 Memory and State Layer

Strengths: sessions can be resumed and forked, so long tasks can continue from the point of a crash.

Weaknesses: there is no semantic-oriented long-term memory (unlike Dify's knowledge base or a dedicated Memory Service); across sessions, "what to remember" still requires manual writing to files or an external retrieval system.

5.6. L5 Evaluation and Observability Layer

This is the weakest layer of the platform, and it must be clearly stated:

• no built-in Eval Set, no Golden Dataset, no regression-set management mechanism;
• trace data is not automatically persisted; it must be exported manually to an external observability system via Hooks such as PostToolUse / Stop;
• no A/B or online-metric capabilities.

Therefore, any production system built on Claude Agent SDK must have L5 self-built by the host. This also confirms the judgment in the parameter card: a Framework mainly covers L2/L3 and is a subset of a Harness — Claude Agent SDK covers wider than a typical Framework, yet still does not complete L5.

5.7. L6 Governance and Security Layer

The openness ↔ governance tension is very clear on this platform: MCP lets an agent connect to any external system — as the capability boundary opens, the attack surface opens at the same time; malicious MCP servers, prompt injection, and credential leakage all happen at this layer. The compensation the SDK offers is the trio of "Hooks highest priority + allowlist + approval callback", but this mechanism requires the host team to write and maintain it themselves; it is not an out-of-the-box compliance capability.

5.8. Concrete Manifestations of the Three Intrinsic Tensions

6. Real-World Examples

The following cases all come from Anthropic's official public engineering blog, with no extrapolation of effect data.

Case One: A two-agent Harness for long-running agents

In Effective harnesses for long-running agents, Anthropic presented an initial design for long-running agents: one initializer agent is responsible for setting up the environment and writing the initial progress file, and one coding agent is responsible for advancing in increments and writing structured progress at the end of each round. The core value lies not in the model, but in the Harness cutting a long task into decidable, resumable increments. The article also gives the official positioning statement of the Claude Agent SDK, which serves as the tone-setting source cited by this group of documents.

Case Two: The three-agent evolution

In the same series of work, the design evolved from two agents to three, adding a dedicated verification / wrap-up role. This evolution shows that: as the task grows longer, the growth in Harness complexity is mainly reflected in the L3 (orchestration) and L5 (verification) layers, not the model-call layer.

Case Three: Claude Code as a same-origin validation of the Agent SDK

Claude Code and the Agent SDK share the same agent loop, so Claude Code's public data can serve as supporting evidence for the engineering usability of that loop. Third-party sources claim that within seven weeks of its release Claude Code reached 350,000 DAU, produced more than 1 million merged PRs, and generated about 1/4 of Anthropic's internal code commits — this set of data comes from secondary sources, is marked [To be verified], and is not used as a basis for conclusions.

Part for which no public quantified data was found: as of the search date 2026-09-12, no third-party enterprise adoption data with quantified effects (such as cost-reduction percentages or task success rates) officially published by Anthropic and built on the Claude Agent SDK could be found. This is stated truthfully here, with no attempt to fill the gap.

7. Summary

7.1. Strengths

1. An officially defining sample: the vendor wrote "harness" into the product definition for the first time, and the six-layer model has a complete, comparable counterpart on this platform.
2. Mature L1 design: the combination of context compaction, subagent isolation, and progressive disclosure is key to the feasibility of long tasks.
3. Strong L6 mechanisms: the permission-decision chain is ordered, Hooks can hard-block, and the budget has a hard stop — among the most complete governance primitives in similar SDKs.
4. Same origin as Claude Code: engineering validation is ample, and the tools and loop are refined through large-scale real-world use.
5. Replaceable backends: supports Bedrock / Vertex AI / Azure AI Foundry, fitting existing cloud cost ledgers.

7.2. Weaknesses

1. L5 is missing: there is no built-in evaluation or observability, and traces and regression sets must be self-built.
2. No built-in sandbox: production safety requires the host to provide container isolation.
3. Implicit L3: control flow is invisible and non-assertable, and predictability is weaker than in explicit-graph frameworks.
4. No multi-tenancy or RBAC: it does not constitute an Agent Platform, so the tenancy, billing, and audit systems must be self-built.
5. Cost cannot be estimated in advance: the implicit loop plus subagent parallelism makes the cost variance of a single task large.

7.3. Applicability Scope

7.4. Selection Recommendations

• If the team already has strong platform-engineering capabilities and can complete L5 (evaluation and observability) and the audit / tenancy parts of L6, Claude Agent SDK is currently the vendor-grade chassis with the most well-balanced six-layer coverage.
• If the team's primary requirement is "execution order must be assertable and regressable", explicit-graph frameworks should be preferred (see 04-langgraph.md).
• If the team's primary requirement is "non-engineering roles can also build agents", an Agent Platform should be preferred (see 05-dify.md, 06-coze.md).
• Regardless of the choice, max_budget_usd and max_turns must be configured before the first launch; otherwise, the cost guardrail is nothing but a formality.

Information Gap Statement

1. Exact license of each package: third-party directory sites give the statement "Python package MIT, TypeScript package Anthropic Commercial Terms", but it has not been checked package by package against the repository LICENSE file; marked [To be verified].
2. Current latest version number: the SDK version changes rapidly with the release cadence; no authoritative version number was obtained as of the search date 2026-09-12; marked [To be verified].
3. Specific model unit prices: unit prices given by different third-party sources for the Sonnet / Opus tiers conflict with each other; this document only retains the definitive statement "SDK is free, billed by token", and the unit price is marked [To be verified].
4. Complete list of Hooks events: the total number of events differs across versions of the official docs (one source cites 27 event points); this document only lists the major events that can be cross-validated.
5. Third-party enterprise adoption quantified data: no publicly verifiable enterprise-effect data built on the Claude Agent SDK was found, and no attempt was made to fill the gap.
6. Functional boundary of Managed Agents: it is a different product from the Agent SDK; no dedicated search was done this time, and its pricing and quotas are marked [To be verified].

8. References

1. Effective harnesses for long-running agents — Anthropic Engineering, 2025. https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
2. Agent SDK overview — Anthropic (Claude Code Docs). https://platform.claude.com/docs/en/agent-sdk/overview
3. Intercept and control agent behavior with hooks — Anthropic (Claude Code Docs). https://code.claude.com/docs/en/agent-sdk/hooks
4. Equipping agents for the real world with Agent Skills — Anthropic Engineering, 2025. https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
5. Claude Agent SDK — Agent Patterns Catalog (component list and licensing terms). https://www.agentpatternscatalog.org/compositions/claude-agent-sdk
6. Claude Agent SDK — Anthropic's Framework for Production AI Agents — Cybernauten. https://cybernauten.com/tools/claude-agent-sdk
7. Claude Agent SDK: Features, Pricing & Alternatives — AI Coolies. https://aicoolies.com/tools/claude-agent-sdk
8. New tools for building agents — OpenAI (as a contemporaneous reference for the formalization of the orchestration layer). https://openai.com/blog/new-tools-for-building-agents
9. R01-Overview research report (Harness definition, MCP timeline, Skills release milestones) — this project's internal research report.
10. Project parameter card v1.0 (six-layer capability model and conceptual boundaries) — this project's internal baseline document.