Build on the Agent SDK when the loop is the product.
Most framework-choice searches return a list ranked by GitHub stars. That is not a decision rule. Here is one.
The short version
4 things that decide this
- 01Use the Claude Agent SDK when the agent's own loop is the thing you are shipping. Reading files, running commands, calling tools across many turns.
- 02Use an orchestration framework like LangGraph when the agent is one node inside a bigger graph. Multiple agents, branching state, a workflow that outlives one conversation.
- 03Plain API code is the right build when the task is a single well-shaped call. No loop, no state to persist, no framework needed.
- 04The wrong pick shows up later as either fighting the SDK's opinions or reassembling, by hand, the parts an orchestration framework already gives you for free.
The listicle answer ranks tools. The real question ranks jobs
Search "claude agent sdk vs langgraph" and most results compare features side by side. This one has hooks, that one has checkpointers, this one supports more languages. Feature tables answer a question nobody actually asked.
The question that matters is where the agent sits in your system. That single fact predicts which tool fits better than any feature list. The two tools were built to solve different placement problems, not the same problem with different APIs.
The agent loop is the product
Some products are, at their core, one agent working through a task. It reads files, runs commands, edits code, searches the web, and decides its next step from what it just found. Nothing else in the system matters as much as that loop running well.
The Claude Agent SDK is built for exactly this shape. It hands you the same loop, tools and context management that run Claude Code, as a library you call from Python or TypeScript. The part that actually decides whether this ships is the permission system: which tools run unattended and which stop and wait for a person. Get that split wrong and you either have a demo too cautious to be useful, or an agent that deletes something nobody approved.
Writing this loop from scratch, permission checks and tool-call logging included, is a week you will spend twice. Once to get it working. Once to get it safe.
The agent is one step in a larger graph
Other systems need more than one agent. Or one agent that pauses for a human approval, resumes hours later, and holds state across a conversation that might crash halfway through. Here the interesting problem is not the loop itself. It is the state: what got decided, what is waiting on a human, what needs to survive a server restart.
This is what an orchestration framework like LangGraph is for. It models the system as a graph of nodes and edges, with checkpointing that persists state between steps. Say your agent needs to pause for a human sign-off and pick up correctly after. That resume behaviour is the product LangGraph sells. Building it yourself means reinventing a checkpointer.
A single Claude Agent SDK loop dropped into one node of that graph is a reasonable combination. Neither tool replaces the other; they answer different questions about the same system.
- One agent, many turnsLoop is the whole product. Agent SDK.
- Multiple agents, shared stateOrchestration framework, e.g. LangGraph.
- One request, one answerPlain API call. No framework.
- Wrong pick, either directionYou rebuild the missing half by hand.
Placement decides the tool. Feature comparisons decide nothing.
Neither is true: write plain code
A surprising number of "agent" projects are one API call with a system prompt. No multi-turn loop, no tool use across steps, no state to persist between requests. Anthropic's own guidance for this case is the Client SDK. Direct API access, where you implement the request yourself, because there is no loop to hand off.
Reaching for either framework here adds a runtime and a dependency for a job that a well-shaped prompt and one function call already do. The tell is simple. If you cannot describe what the agent does across multiple steps, it is not a loop yet.
The wrong pick shows up as work you didn't plan for
Pick the Agent SDK for multi-agent orchestration, and you end up building your own state graph on top of it, badly. Pick an orchestration framework for a single agent loop, and you carry a checkpointing layer for a problem that had no state to check-point.
Both mistakes are recoverable, and both cost weeks. Naming the shape before writing code is cheaper than discovering it from the rebuild.
Questions this raises
01Claude Agent SDK or LangGraph?
Use the Claude Agent SDK when one agent's own loop, reading files, running commands, calling tools across turns, is the product. Use LangGraph when the system needs multiple agents, branching state, or a pause-and-resume flow that has to survive a crash. A single SDK loop can sit inside one node of a larger LangGraph graph; the two are not competing for the same job.
02When should we use the Claude Agent SDK in production?
When the agent needs to act, reading and writing files, running commands, using tools over many turns, with permission controls deciding what runs unattended. If the task is one request with no multi-step loop, the Client SDK and a direct API call are the simpler build.
03What does production experience with the Agent SDK actually involve?
Mostly the permission model, not the loop. Deciding which tool calls run automatically and which stop for a human is the design work that determines whether the agent is safe to deploy. The loop itself, reading files and calling tools, is close to solved out of the box.
Related
- Claude Agent SDK review →What it gives you over a plain API loop, and where it is the wrong shape.
- LangGraph review →What checkpointers buy you and when a plain state machine beats the graph.
- Best AI agent frameworks →The wider field, ranked by what survives production.
- Hire Claude Agent SDK developers →Engineers who have shipped agent loops with real permission design.
