Skip to main content

Decision brief

Claude Agent SDK Review: Claude Code's Agent Loop as a Library

Who the Claude Agent SDK fits, what its bundled CLI subprocess means for hosting, and the session, cost, and billing decisions to settle before agents built on it reach users.

Reading time
5 min read
Sources
22 cited
In this piece
Claude Agent SDK+52 Strong positive

GILD verdict

Choose the Claude Agent SDK when your agents run on Claude, need files and a shell with approval steps, and you can host one Claude Code process per session.

The workflow
A team building Claude agents into internal tools or per-task containers, where the agent reads and edits files, runs commands, and asks before risky actions.17
The decisive evidence
  • DocumentedThe SDK exposes Claude Code's built-in tools, hooks, subagents, MCP, permission rules, and sessions that resume or fork, so the team writes no tool loop or context compaction of its own.135
  • DocumentedEach session is a claude CLI subprocess that owns a shell, a working directory, and transcripts on local disk, sized from 1 GiB RAM and 1 CPU per agent. Transcripts survive a container only through a SessionStore adapter.46
  • DocumentedTelemetry comes from the CLI process through OpenTelemetry, with traces in beta, and the SDK's cost fields are estimates that can drift from the bill.910
  • ReportedThomson Reuters rebuilt CoCounsel Legal around the SDK in 2026, and Spotify runs its Honk agent on it in Kubernetes pods. Moon Banking rolled back a release whose cost logs tripled, which Anthropic traced to older versions undercounting, and a team measured headless SDK runs using about 1.8 times more of a Max plan's 5-hour window than Claude Code on Sep 25, 2026.19202122
  • GILD analysisOf the 98 public accounts on this product's Signals page, all 21 that discuss the harness praise it. The CLI subprocess and Claude Code's defaults each draw concerns in 12, and local sessions in 10. The decision turns on how the team hosts it more than on what the agent can do, and whether Anthropic will meter SDK runs against plan limits like Claude Code is unresolved.
The tradeoff
You trade control for a working harness. It supports Claude models only, uses Claude Code's prompt unless you write your own, and needs a process per session to host. Anthropic revised its Claude-plan billing terms in June and again on October 7, 2026.2812
What would change the call
The call changes if the agent must serve many tenants from a stateless web backend or run models from other providers. Then a loop on the Claude API, Claude Managed Agents, or a multi-provider framework fits better.415

Claude Agent SDK

Agent Framework by Anthropic

+52 Strong positive
Product page

Fit and limits

Who it fits

  • The agent needs Claude Code's file, shell, and web tools, and the team would rather not write a tool loop and context compaction.
  • Work runs as internal tools, background jobs, or one container per task, where a process per session is easy to host.
  • The team wants hooks and permission rules that decide which tool calls run, with a callback for approvals.
  • The organization has settled on Claude and can buy it through the Anthropic API, Amazon Bedrock, Google Cloud, or Microsoft Foundry.

Where it falls short

  • Stateless, multi-tenant web backends: each session needs a subprocess, memory, and a session store, which the team builds and operates.
  • Teams that need other model providers, or sampling settings such as temperature, which the SDK's option reference does not list.
  • Agents that need their own persona: a custom system prompt replaces the claude_code preset, and the team then owns the tool guidance and safety rules it carried.
  • Teams that cannot absorb frequent releases: the Python package shipped 139 releases in the year to Oct 28, 2026, and the TypeScript package passed 0.3.300. Moon Banking rolled back from 0.1.60 to 0.1.30 in December 2025 when logged costs tripled, which Anthropic traced to older versions undercounting.
  • Teams paying through a Claude plan: builders measured SDK runs using 1.7 to 1.8 times more of the 5-hour window than the same work in Claude Code in September and October 2026, and one found a hit quota returned as a successful result.

Implementation reality

  1. Pick a hosting pattern first

    Anthropic documents ephemeral containers per task, long-running containers that hold many sessions, and hybrid containers that hydrate from a SessionStore. Size each host from the documented floor of 1 GiB RAM, 5 GiB disk, and 1 CPU per agent, then measure peak memory on a session of real length.

  2. Move transcripts off the host

    Configure a SessionStore so another host can resume a session, and store memory files and working-directory artifacts separately. Capture session IDs from the init message and resume by ID in multi-user apps.

  3. Gate tools before you grant them

    Hooks run first, then deny rules, ask rules, the permission mode, and the canUseTool callback. Start with read-only tools, deny shell patterns you never want, and route writes and network calls through the callback or a sandbox.

  4. Cap turns and watch spend

    Set a turn limit on every query and a budget per run, export usage through OpenTelemetry, and reconcile against the Usage and Cost API, because the SDK's cost fields are estimates. Pin the SDK version and retest cost after each upgrade.

What to measure in your pilot

  • How much memory a long-running SDK session reaches under real tool load, against the documented 1 GiB floor.
  • Whether the October 7, 2026 plan credits settle how teams pay for SDK agents, or the terms change again.
  • How OpenTelemetry traces, still in beta, compare with third-party instrumentation for debugging subagents.
  • Whether Anthropic changes how SDK runs count against a Claude plan's 5-hour window, after builders measured them at 1.7 to 1.8 times Claude Code's rate in September and October 2026.

Sources

Official documentation
18
Public source
4
  1. Agent SDK docs: Overview (capabilities, login policy, license)Official documentationcode.claude.com
  2. Agent SDK docs: Quickstart (requirements and model providers)Official documentationcode.claude.com
  3. Agent SDK docs: How the agent loop worksOfficial documentationcode.claude.com
  4. Agent SDK docs: Hosting (subprocess model, session patterns, sizing)Official documentationcode.claude.com
  5. Agent SDK docs: Work with sessionsOfficial documentationcode.claude.com
  6. Agent SDK docs: Persist sessions to external storageOfficial documentationcode.claude.com
  7. Agent SDK docs: Configure permissionsOfficial documentationcode.claude.com
  8. Agent SDK docs: Modifying system promptsOfficial documentationcode.claude.com
  9. Agent SDK docs: Track cost and usageOfficial documentationcode.claude.com
  10. Agent SDK docs: Observability with OpenTelemetryOfficial documentationcode.claude.com
  11. Agent SDK docs: Migrate to Claude Agent SDK (rename from the Claude Code SDK)Official documentationcode.claude.com
  12. Claude Help Center: Use the Claude Agent SDK with your Claude plan (updated Oct 7, 2026)Official documentationsupport.claude.com
  13. Claude Help Center: Monthly API credits for Max and Team plansOfficial documentationsupport.claude.com
  14. Claude API docs: PricingOfficial documentationplatform.claude.com
  15. Claude API docs: Claude Managed Agents overviewOfficial documentationplatform.claude.com
  16. Claude Agent SDK for Python on GitHub (MIT license)Official documentationgithub.com
  17. Claude Agent SDK for TypeScript on GitHub (Commercial Terms)Official documentationgithub.com
  18. claude-agent-sdk on PyPI (release history)Official documentationpypi.org
  19. Thomson Reuters Innovation blog: CoCounsel Legal, Reimagined, rebuilt around the Claude Agent SDK (Mar 10, 2026)Public sourcethomsonreuters.com
  20. Spotify Engineering: Coding Is No Longer the Constraint, on Honk and the Agent SDK (Jun 3, 2026)Public sourceengineering.atspotify.com
  21. Claude Agent SDK TypeScript issue #93: cost tripled between 0.1.30 and 0.1.60 (Dec 6, 2025)Public sourcegithub.com
  22. Claude Code issue #97074: headless SDK runs use about 1.8 times more of the 5-hour window (Sep 25, 2026)Public sourcegithub.com

Keep reading

  1. Buyer guideClaude Agent SDK Production PlaybookPick a hosting pattern and a session store, gate tools with permissions and hooks, then set turn limits, track cost, and add tracing before users arrive.
  2. Buyer guideClaude Agent SDK or Your Own Loop on the Claude APIWhen Claude Code's harness earns its subprocess, and when a loop on the Messages API, Managed Agents, or another framework fits better.
  3. ResearchClaude Agent SDK in Practice: What Builders ReportIn 100 public accounts, teams from Thomson Reuters, Spotify and PostHog to solo developers report what the SDK's harness does well and where its subprocess, sessions, cost, and plan limits cause trouble.
Read the research