The Agent SDK saves writing an agent loop and brings Claude Code's tools, at the cost of a CLI process per session and Claude models only. This guide sets out when that trade pays, when your own Messages API loop or Claude Managed Agents fits better, and when a multi-provider framework is the right call.
When you need this
- A team is choosing the runtime for its first production agent on Claude.
- An SDK prototype works on a laptop, and the production target is a multi-tenant web backend.
- Engineers disagree about adopting a harness or writing their own loop.
Evaluation criteria
Tools the agent needs
Does the agent work in files and a shell?
Look forThe SDK's value is Claude Code's built-in tools, subagents, and compaction. A GitLab reviewer, a UAT agent driving Playwright, and Omnara's mobile client all lean on them. An agent that only calls your APIs gains less.
Where it runs
Can your runtime host one process per session?
Look forContainers per task or internal services host the subprocess well. One team building a web assistant found the subprocess, file-based sessions, and memory growth a poor fit for its Python backend and weighed the Messages API instead.
Tenancy
Does one service handle many users' sessions?
Look forTeams building multi-tenant web products report rebuilding sandboxing, streaming, threads, and approval UI around the SDK. Claude Managed Agents hosts the loop in Anthropic's cloud, and the Messages API with the tool runner keeps the loop in your stateless code.
Model choice
Will you need other model providers?
Look forThe SDK runs Claude only, through Anthropic or the major clouds. Builders who needed other providers wrote vendor-neutral harnesses. LangGraph, Pydantic AI, the OpenAI Agents SDK with adapters, and the Vercel AI SDK each work across providers.
Control over the prompt and settings
Does the agent need its own identity and sampling settings?
Look forA custom system prompt replaces Claude Code's, but the SDK still adds an identity line, and temperature is not exposed. Teams that need full control of the request write the loop on the API.
Exit path
Could you leave the SDK later?
Look forKeep business logic in your own tools, exposed as MCP servers, so a loop on the API or another framework can reuse them. One team dropped the SDK after spawn bugs and called the CLI binary directly.
Questions to ask vendors
- Which of our agents need file and shell tools, and which only call our APIs?
- Does our runtime allow spawning processes, and what does a session cost in memory?
- Will any agent need a model outside Claude in the next year?
- Who owns sessions, sandboxing, and approvals if we adopt the SDK for a web product?
Red flags
- Adopting the SDK for a stateless web backend without budgeting the session and sandbox work.
- Writing a custom loop and then rebuilding compaction, subagents, and permissions by hand.
- Business logic coupled to Claude Code's prompt so it cannot move to another runtime.
Products in this piece
Sources
- Official documentation
- 7
- Public source
- 10
- Agent SDK docs: Overview (capabilities, login policy, license)
- Agent SDK docs: Hosting (subprocess model, session patterns, sizing)
- Agent SDK docs: Quickstart (requirements and model providers)
- Agent SDK docs: Modifying system prompts
- Agent SDK docs: Custom tools (in-process MCP servers)
- Claude API docs: Claude Managed Agents overview
- Agent SDK docs: Python reference
- Hacker News comment on a GitLab code reviewer built on the SDK (Feb 20, 2026)
- Hacker News comment on a user acceptance testing agent built on the SDK (Jul 2, 2026)
- Hacker News comment by Omnara's co-founder on replacing terminal parsing with the SDK (Feb 12, 2026)
- Hacker News: Ask HN, Claude Agent SDK vs. Messages API for a production AI assistant (Apr 7, 2026)
- Hacker News comment on rebuilding sessions, sandboxing, and approvals around the SDK for a multi-tenant web product (Apr 7, 2026)
- Hacker News comment on a vendor-agnostic replacement for the SDK (May 1, 2026)
- Hacker News post on OpenHarness, written after finding the SDK too heavy to embed (Mar 31, 2026)
- Claude Agent SDK Python issue #273: setting temperature through the SDK (Oct 20, 2025)
- Claude Agent SDK TypeScript issue #468: no way to omit the injected SDK identity line (Sep 22, 2026)
- validate.qa on X: dropping the SDK after spawn bugs in 0.2.139 (Jun 13, 2026)