Verdict
Adopt the Claude Agent SDK when your agent's job overlaps Claude Code's shape - filesystem access, bash, code editing, research over files - because you get a production-hardened loop with context compaction, subagents, hooks, permissions, and MCP support for free, and the SDK itself costs nothing beyond token usage. Write a custom loop when your tools are entirely your own (no filesystem, no bash), when you need portability across model providers, or when the harness's static overhead is material: community measurements of the Claude Code harness the SDK packages put the system prompt plus built-in tool definitions at roughly 14k-18k tokens before your prompt does anything (claudecodecamp's teardown: ~2.3k-3.6k system prompt, ~14k-17k tool schemas; a separate 2026 comparison trace measured ~33k tokens on an initial request once every tool and scaffolding block loads, per developersdigest.tech). Two more facts should anchor the decision. First, the middle path exists: the regular Anthropic SDK's Tool Runner drives the request→execute→loop cycle for tools you define, with none of the built-in-tool overhead - most 'custom loop' projects should actually start there. Second, billing risk is real but currently parked: Anthropic announced that from June 15, 2026 Agent SDK and headless usage would stop drawing on Pro/Max subscription limits and move to a separate monthly credit pool ($20 Pro / $100 Max 5x / $200 Max 20x at standard API rates), then paused the change on June 15 itself - the update stated the billing split was 'no longer happening' and usage would keep counting against subscription limits 'for now' - API-key workloads were never affected, but any product built on subscription-billed SDK usage is building on a policy Anthropic has already tried to change once.
The two options differ in who supplies the harness. The Agent SDK (claude-agent-sdk on PyPI, @anthropic-ai/claude-agent-sdk on npm) is Claude Code packaged as a library: you call query(prompt, options) and it drives the full loop with built-in Read/Write/Edit/Bash/Glob/Grep/WebSearch/WebFetch tools, automatic context compaction, subagent spawning, lifecycle hooks, permission policies, session management, and MCP client support (code.claude.com/docs/en/agent-sdk/overview). The library is free; you pay only model tokens - at current Anthropic list prices that's $5/$25 per million input/output tokens for Claude Opus 5 and $3/$15 for Sonnet 5 (a promotional $2/$10 runs through August 31, 2026), per platform.claude.com pricing. A custom loop on the Messages API starts from zero: the while stop_reason == "tool_use" loop is twenty lines, but production ownership means retries and backoff, parallel tool-result ordering, context-window management (compaction or pruning), cost accounting, permission gating, and subagent orchestration - each a solved problem inside the SDK and an open ticket in your backlog. The overhead trade is quantifiable: the SDK's static harness costs roughly 14k-18k tokens per session by community measurement, but prompt caching collapses the recurring cost - Anthropic bills cache reads at 0.1x input price, so an ~18k-token harness prefix costs about $0.054 once at Sonnet 5's $3/MTok standard rate and roughly $0.005 per subsequent cached call (arithmetic on published prices). What caching cannot fix is fit: if your agent never touches a filesystem, you're hauling tool schemas you'll never call, and trimming them means fighting the harness instead of writing your own.
Decision Table
| Criterion | Edge | Explanation |
|---|---|---|
| Time to a production-grade loop | Claude Agent SDK (Claude Code's harness as a library - built-in tools, compaction, subagents, hooks, MCP) Best edge | The SDK ships the loop that runs Claude Code in production: agentic iteration, built-in tools, error handling, session persistence, permission prompts, and automatic compaction when context approaches limits (code.claude.com/docs/en/agent-sdk/overview). A custom loop reaches 'demo' in an afternoon and 'production' in weeks - the naive while-loop omits retries, parallel tool-result batching, context management, and budget aborts, and each omission is a production incident with a date on it. If the agent's job resembles coding/filesystem/research work, the SDK's head start is decisive. |
| Token overhead per session | Custom agent loop on the Messages API (you own the while-loop, tools, retries, and context management) Best edge | A bare Messages API call carries only your prompt and your tool schemas. The SDK carries Claude Code's harness: community teardowns measure the system prompt at ~2.3k-3.6k tokens and built-in tool definitions at ~14k-17k (claudecodecamp.com 'Inside Claude Code's System Prompt'), with a separate 2026 trace (developersdigest.tech's overhead comparison) putting a fully-loaded initial request at ~33k tokens once all tool definitions and scaffolding are counted, and the Piebald-AI/claude-code-system-prompts repo tracking the prompts across versions. Prompt caching blunts the recurring cost (0.1x input price on cache reads - about $0.005 per call on an 18k prefix at Sonnet 5's standard $3/MTok, vs ~$0.054 uncached), but cache writes, cache-TTL misses, and the first call of every session still pay full or 1.25x freight. For a high-volume agent with three custom tools and no filesystem, a lean custom loop's prompt can be 20x smaller. |
| Context management on long-running tasks | Claude Agent SDK (Claude Code's harness as a library - built-in tools, compaction, subagents, hooks, MCP) Best edge | The SDK inherits Claude Code's context engineering: automatic compaction summarizes history as the window fills, so multi-hour sessions don't die at the context limit. A custom loop must implement this - either client-side summarization you write and eval yourself, or wiring the API's server-side compaction beta (compact-2026-01-12) and correctly preserving compaction blocks across turns, which is exactly the kind of subtle contract (append full response.content, not just text) that silently breaks when hand-rolled. This is the single most underestimated line in the 'what you still owe' column. |
| Cross-provider portability | Custom agent loop on the Messages API (you own the while-loop, tools, retries, and context management) Best edge | A custom loop is yours: swap Anthropic for a local model behind an OpenAI-compatible endpoint, route by cost, or A/B providers - the loop doesn't care. The Agent SDK is Claude-shaped end to end: its harness, tool formats, and behaviors target Claude models. Worth naming honestly, though: if portability is the requirement but you don't want to own a loop, a third-party provider-agnostic harness (Vercel AI SDK's agent loop, OpenAI's Agents SDK with custom model providers, or LiteLLM under your own loop) beats both sides of this page - that's a different comparison, but pretending the choice is binary would be wrong. |
| Billing and platform-policy risk | Custom agent loop on the Messages API (you own the while-loop, tools, retries, and context management) Best edge | A custom loop on API keys has one billing mode: metered tokens at published prices. The Agent SDK straddles two: API-key usage (same deal) and subscription-billed usage via Claude Pro/Max credentials - and the latter moved under Anthropic's feet in 2026. The announced June 15 change would have carved Agent SDK, claude -p, and GitHub Actions usage out of subscription limits into a separate monthly credit pool ($20 Pro, $100 Max 5x, $200 Max 20x, metered at standard API rates) - then Anthropic paused it on the effective date, with the June 15 update saying the split was 'no longer happening' and subscription limits would keep applying 'for now'. Nothing changed yet, but a product whose unit economics depend on flat-rate subscription tokens through the SDK has a repriceable dependency. Custom loops never had this exposure. |
| Multi-agent and subagent support | Claude Agent SDK (Claude Code's harness as a library - built-in tools, compaction, subagents, hooks, MCP) Best edge | Subagents are a built-in SDK primitive: define specialized workers, and the harness handles spawning, context isolation, and result return. Hand-rolling multi-agent means designing inter-agent messaging, context budgets per child, and failure propagation yourself - a genuinely hard distributed-systems problem wearing an AI costume. If your roadmap includes fan-out research or parallel workstreams, this row alone can justify the SDK. |
| Simple custom-tool agents (the middle path) | Tie | For an agent with a handful of your own tools and no filesystem needs, the right answer is neither the Agent SDK nor a hand-written loop: the Anthropic SDK's Tool Runner (client.beta.messages.tool_runner in Python, toolRunner in TypeScript) drives the loop for tools you define, with per-turn hooks for approval gates, error interception, and retries - no built-in-tool overhead, no loop code to own. It's the standard-SDK feature most build-vs-buy posts on this query ignore, and it dissolves a large share of the decision: 'custom loop' projects that are really 'custom tools' projects should start there and only graduate to a manual loop when the runner's hooks genuinely can't express the control flow. |
Choose Claude Agent SDK (Claude Code's harness as a library - built-in tools, compaction, subagents, hooks, MCP) if...
- Coding, refactoring, and CI agents that need Read/Write/Edit/Bash/Glob/Grep out of the box with permission gating.
- Long-horizon tasks where automatic compaction and session resume decide whether the run finishes at all.
- Teams that want Claude Code's battle-tested behaviors (hooks, subagents, MCP servers) without maintaining harness code.
- Prototype-to-production paths where shipping this quarter beats owning the runtime layer.
Choose Custom agent loop on the Messages API (you own the while-loop, tools, retries, and context management) if...
- Agents with fully custom tool surfaces - API orchestration, database workflows, domain tools - where built-in filesystem tools are dead weight in every prompt.
- Multi-provider platforms that route across Anthropic, open-weights, and local models and cannot accept a Claude-shaped harness.
- Cost-obsessed high-volume services where a hand-tuned 1-2k-token prompt is a competitive advantage over a ~14k-18k-token harness floor.
- Teams with existing durable-execution infrastructure (queues, workflow engines) that already solves retries and state better than an in-process harness can.
Decision rules
- 01Agent shaped like Claude Code (filesystem, bash, code edits, repo research) → Agent SDK; you would spend months re-deriving compaction, permissions, and subagents that it ships today.
- 02Only custom tools, no filesystem/bash → skip both: use the Anthropic SDK's Tool Runner and inherit the loop without the ~14k-18k-token harness.
- 03Hard multi-provider requirement (local models, routing, provider A/B) → custom loop or a provider-agnostic third-party harness; the Agent SDK is Claude-native by design.
- 04High-volume, latency- and cost-sensitive per-call workloads → measure first: the harness's static prefix costs ~$0.054 per Sonnet 5 session uncached and ~$0.005 per cached call (published $3/MTok and 0.1x cache-read pricing); if your custom prompt is 1k tokens, the SDK's floor is your ceiling.
- 05Building a commercial product on subscription-billed SDK usage → treat the paused June 15, 2026 credit-pool split ($20/$100/$200 monthly at API rates) as a preview of policy direction; price your product against API rates, not subscription flat rates.
- 06You still owe, whichever loop you run: cost caps and budget aborts, tool-input validation, audit logging, and eval harnesses - the SDK covers the loop, not your production obligations (that's our cost-guardrail and observability material).
Migration Notes
- Custom loop → Agent SDK: your tools survive as MCP servers or custom tool definitions; your loop code doesn't. Budget the migration around re-testing behavior under the SDK's system prompt - the harness prompt changes model behavior, not just cost.
- Agent SDK → custom loop: the painful re-derivations are compaction and subagents, not the while-loop. Wire the API's server-side compaction beta before writing your own summarizer, and steal the SDK's permission-gate semantics rather than redesigning them.
- Either direction, keep a provider-shaped seam: isolate 'call the model' behind one function from day one, so the harness decision stays reversible instead of load-bearing.
- If you're leaving the SDK over token overhead, first check what caching already saves you: an 18k harness prefix at 0.1x cache-read pricing is ~$0.005 per call on Sonnet 5 - measure your actual cache hit rate before rebuilding a runtime over a cost that may round to zero.