The most expensive mistake in agent development is not a bad prompt. It is picking the wrong layer of the stack, then spending weeks hand-building things a layer above you already ships. I have built agents at several of these layers, including the open projects on my GitHub (nexa and my-ai-crew, under github.com/mejba13) and client systems that run unattended, and my position has hardened into one sentence: if your agent needs to read files, run commands, and work in a repository, start with the Claude Agent SDK, because it is Claude Code's production harness handed to you as a library. Build lower only when you can name the specific control you need that it does not expose.
A naming note before anything else, because search still lags reality: this is the SDK people find by searching "Anthropic Agent SDK." Its actual packages are claude-agent-sdk on PyPI and @anthropic-ai/claude-agent-sdk on npm, and it was renamed from the Claude Code SDK when Anthropic generalized it beyond coding.
The decision that matters: who supplies the harness, who supplies the deployment
Every "agent framework" conversation untangles once you separate two questions. Who supplies the harness, meaning the loop, the context management, the tool plumbing? And who supplies the deployment, meaning the infrastructure it runs on? Four honest options exist on Anthropic's stack:
| Approach | Harness | Deployment | You write |
|---|---|---|---|
| Raw Messages API, manual loop | You | You | Everything, including the while stop_reason == "tool_use" loop |
| API tool runner | SDK loop over your tools | You | Just the tool functions |
| Claude Agent SDK | Full Claude Code harness, built-in tools | You | A prompt plus options |
| Managed Agents | Anthropic | Anthropic | Agent config plus your custom tool results |
The Agent SDK's slot in that table explains both its power and its limits. You get the whole Claude Code machine: built-in Read, Write, Edit, Bash, Glob, Grep, WebSearch and WebFetch tools, the agentic loop, permission gates, hooks, session management, subagents, and MCP support. You still own hosting, which for most of my client work is a feature, not a gap, because the agent runs inside infrastructure the client already trusts.
When I built my multi-agent crew project, the draft on the raw API meant writing file tools, a permission model, and context management from scratch, and every one of those is a place to introduce subtle bugs. The Agent SDK version deleted that entire category of code. The raw API earns its place lower in the stack when the agent has a narrow, non-filesystem tool surface, which is a different design conversation about tool calling entirely.
The minimal working agent
In Python:
from claude_agent_sdk import query
async for message in query(
prompt="Audit ./app for N+1 query patterns and write findings to report.md"
):
print(message)
That short snippet is misleading in a useful way: the model behind it can now grep the codebase, read files, reason across them, and write the report, because the harness supplies the tools. Your real work as an agent developer moves from plumbing to three design surfaces: what the agent knows (memory), what it may do (permissions and tools), and how it is checked (verification).
Memory: three tiers, used differently
This is the design area where I see the most confusion, and where the SDK's Claude Code heritage gives you a working pattern for free:
- Always-loaded context:
CLAUDE.md. Conventions, commands, constraints that apply to every run. Keep it small; every token here is paid on every request. Mine carry things like "verification is mandatory" and stack-specific gotchas. - On-demand knowledge: skills. Folders of instructions the agent loads only when the task matches. My SEO agents load a content skill when writing and a programmatic-SEO skill when generating pages at scale, and neither pollutes the other's context. Skills are where domain expertise lives, and building them well is its own craft.
- Persistent state: plain files. Anything the agent should remember across sessions goes on disk as Markdown or JSON that the agent reads and writes with its normal tools. No vector database required for most agents. My longest-running automations keep a simple
state/directory, and it has outlived two framework fashions already.
The discipline that makes this work: information flows downward only when it earns it. A lesson learned in one run gets written to a file; if it keeps mattering, it gets promoted into a skill; only if it applies to every single run does it touch CLAUDE.md.
The cost traps, from someone who paid them
The API is stateless, and history compounds. Every turn re-sends the conversation so far. An agent that chats with itself through forty tool calls is re-buying its own transcript forty times. Mitigations, in order of leverage: prompt caching on the stable prefix (the SDK's harness benefits from this automatically when your system context stays byte-stable, so do not interpolate timestamps into it), aggressive session boundaries (finish a task, start clean), and subagents.
Subagents are a cost tool, not just a parallelism tool. A subagent gets a fresh context, does the read-heavy work, and returns only its conclusion. When my security scanner agent audits a repository, category-specific subagents each read hundreds of files, and the orchestrating context only ever sees findings. Without that split, the main context would blow through its window and its budget on file contents it needed once.
Model choice per role. The orchestrator that plans and judges deserves the strongest model. Workers that scan and extract usually do not. This single routing decision has cut my per-run costs more than any prompt optimization ever has.
Instrument before you scale. Log tokens per run from day one. My rule of thumb: know your cost per completed task, not per API call, because agents that retry intelligently can have expensive calls and cheap outcomes, and the reverse.
Where the Agent SDK is the wrong answer
Honesty about the boundaries, since the marketing will not provide it. If you need Anthropic to host the loop and the sandbox, that is Managed Agents, not this. If your agent must run in a browser-only environment or you cannot ship a Node or Python runtime, the SDK does not fit. And if the task is a deterministic pipeline where every input fully determines the output, you do not need an agent at all; you need code, with perhaps one model call at the genuinely ambiguous step. I have talked more than one client out of an agent project on exactly those grounds, and the resulting plain script has been running without incident since.
If you are newer to this stack, the on-ramp order that works: get fluent driving Claude Code interactively first, because it is the same harness with a human in the loop. Everything you learn about CLAUDE.md, skills, permissions, and verification transfers to the SDK one-to-one; the SDK is just that machine with your code where your keyboard was.
See what this looks like shipped
The agent systems I reference here are not demos in a slide deck. The open-source ones live on my GitHub, and the production builds, from monitoring platforms to content pipelines, are documented with architecture notes in my project portfolio. If you are evaluating whether an Agent SDK build fits a real problem you own, looking at finished systems will answer more than any tutorial section can.
