Claude Agent SDK vs LangGraph: Which to Build Agents With?

Choosing between the Claude Agent SDK and LangGraph comes down to one question: should the model decide what happens next, or should your code? The Claude Agent SDK hands your application the same agent loop that runs inside Claude Code, so Claude picks its own tools and steps. LangGraph gives you a state machine instead. You draw the nodes and edges, and the model does the work at each stop. Both build capable AI agents. They just disagree about who holds the steering wheel.

This comparison looks at control flow, tools, state, human approval, model choice, and production costs, so you can pick one before you write a thousand lines of the wrong thing.

The Short Answer

If your agent is mostly "give a capable model good tools and let it work," start with the Claude Agent SDK. If your agent is a workflow with fixed stages, branches, retries, and audit points, start with LangGraph. Most of the confusion fades once you sort your project into one of those two shapes.

Here is the side-by-side before the details:

💡 Rule of thumb: count the steps you can write down ahead of time. If you can list them on a napkin, draw a graph. If the honest answer is "it depends on what the agent finds," use the loop.

What Each Framework Is

Claude Agent SDK in Brief

Anthropic first shipped this as the Claude Code SDK and later renamed it the Claude Agent SDK, because people were using it for far more than coding. You install claude-agent-sdk for Python or @anthropic-ai/claude-agent-sdk for TypeScript, call query() with a prompt and some options, and stream messages back as the agent works.

Underneath sits the same harness that powers Claude Code. It sends context to Claude, runs whichever tools Claude asks for, feeds the results back, and repeats until Claude decides the job is finished. What you get without writing it yourself:

• Built-in tools: Read, Write, Edit, Bash, Glob, Grep, WebSearch, and WebFetch
• Context management: the harness compacts older turns when the window fills up
• Subagents: specialized helpers with their own prompts and tool lists
• Hooks: your code runs before or after a tool call
• MCP support: plug in Model Context Protocol servers for databases, browsers, and internal APIs
• Permissions: modes and rules that decide which tool calls need approval
• Project instructions: CLAUDE.md files and skills loaded from the filesystem

LangGraph in Brief

LangGraph comes from the LangChain team and is built for long-running, stateful agents. It reached its 1.0 release in late 2025. You define a state schema, write nodes as ordinary functions, connect them with fixed or conditional edges, and compile the result into a runnable graph.

The graph is the product. Every step reads the shared state and returns an update, so you can see exactly where a run stands at any moment. Checkpointers save that state after each step, which is what makes pausing, resuming, and replaying possible. LangGraph is model-agnostic: any chat model with a LangChain integration slots into a node, and LangSmith adds tracing when you want to watch runs.

Agent Loop vs Explicit Graph

Who Picks the Next Step

This is the real fork in the road. In the SDK, Claude chooses the next move on every turn: read another file, run a command, search the web, or stop. In LangGraph, edges choose, and the model only decides inside the node it was handed.

Neither approach is wrong. A loop handles surprises, such as a bug report that turns out to be a config problem. A graph guarantees process, such as "always validate the address before charging the card."

The Same Task in Both

Take a plain job: audit an auth module and report the riskiest functions. Here it is with the Claude Agent SDK:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Grep", "Glob"],
        system_prompt="You review code for security risks.",
    )
    async for message in query(
        prompt="Audit the auth module and list the three riskiest functions.",
        options=options,
    ):
        print(message)

asyncio.run(main())

Copy Prompt

That is the whole program. Claude decides which files to open, in what order, and when it has seen enough.

Now the same job in LangGraph, with a guaranteed review step. The helpers run_audit and passes_checks are placeholders for your own code:

from typing import TypedDict
from langgraph.graph import StateGraph, START, END

class State(TypedDict):
    question: str
    report: str
    approved: bool

def audit(state: State) -> dict:
    return {"report": run_audit(state["question"])}

def review(state: State) -> dict:
    return {"approved": passes_checks(state["report"])}

def route(state: State) -> str:
    return "done" if state["approved"] else "retry"

builder = StateGraph(State)
builder.add_node("audit", audit)
builder.add_node("review", review)
builder.add_edge(START, "audit")
builder.add_edge("audit", "review")
builder.add_conditional_edges("review", route, {"done": END, "retry": "audit"})
graph = builder.compile()

Copy Prompt

Here you wrote the process: every report gets reviewed, and a failed review always routes back. The model never gets to skip the review. The price is plumbing: more code, more decisions, and a graph to maintain.

Multi-Agent Setups

The SDK handles delegation with subagents. You define each helper with a description, a prompt, and a restricted tool list, and the main agent hands work to them. Each subagent runs in its own context, which keeps the parent's window clean. It is quick to set up, and the delegation decisions stay with Claude.

LangGraph models the same thing as subgraphs or a supervisor node that routes to worker nodes. Handoffs are explicit, shared state is typed, and you can test each worker alone. When five agents must cooperate in a fixed order, that explicitness pays off. When the agents are loose specialists, it can feel like paperwork.

Tools, State, and Memory

Built-In Tools vs Custom Nodes

The SDK arrives with a full toolbox, which is why it feels productive on day one. An agent that can read a repository, edit files, and run tests works the moment you pass allowed_tools. Custom tools join through in-process MCP servers or any external MCP server. Restricting the box matters as much as stocking it: Bash is powerful, so give it only to agents that need it.

LangGraph starts with an empty bench. Tools are functions you bind to a model inside a node, and a prebuilt tool node executes the calls. That means more setup and more freedom: a tool can be anything Python or JavaScript can call, and you decide what each node may touch.

Sessions vs Checkpoints

The SDK tracks a session. Every run has an ID, and you can resume it later with the full conversation history, or fork it to try another direction. The harness compacts old turns so long jobs do not choke on context.

LangGraph tracks a checkpoint for each step, grouped by thread. You can resume a thread after a crash, replay from an earlier step, or edit the state and branch from there. A separate store holds long-term memory shared across threads, such as user preferences.

💡 The difference: a session remembers the conversation. A checkpoint remembers where the workflow stands. If your agent must restart at step four of seven on a different server, checkpoints are the natural fit.

Human Approval and Control

Agents that touch money, production data, or customer email need a person in the loop. Both tools support it, in different places.

Permissions and Hooks

The SDK guards actions. Permission modes range from asking before everything, to auto-accepting file edits, to a read-only planning mode. You can allow or deny tools by name, supply a callback that approves each call, and attach hooks that run before a tool executes and can block or rewrite it. A hook that refuses any shell command containing rm -rf is a short function.

Interrupts and Resume

LangGraph guards stages. A node calls interrupt(), the graph stops, and the checkpointer stores everything. Hours or days later, a person responds, you resume with a Command, and the run continues from the same spot, even on a different machine. That makes approval queues, such as refunds above a threshold, straightforward to build.

Which is better? If you worry about what the agent is allowed to do, the SDK's permissions fit. If you worry about when a human must sign off in a business process, LangGraph's interrupts fit.

Model Choice and Production Reality

Model Lock-In

The Claude Agent SDK runs Claude models. You can reach them through Anthropic's API or through cloud providers such as Amazon Bedrock and Google Vertex AI, but you cannot swap in a different vendor. If Claude is your choice anyway, that is a feature, because the harness is tuned to how Claude uses tools.

LangGraph is neutral. You can run one node on a fast, cheap model for routing, another on a strong reasoning model, and swap either with a config change. Before you commit, run the same agent prompt through several models on PicassoIA: Claude Sonnet 5 for balanced coding and tool use, Claude Opus 4.7 for harder reasoning, Claude Fable 5 for complex coding tasks, GPT 5.6 Sol, Gemini 3.1 Pro, and Kimi K2.6, which is pitched at building agents. If one vendor clearly wins your task, the lock-in question answers itself.

Observability and Deployment

An SDK agent runs the Claude Code runtime, so deploy it where that runtime can live, typically a container with a locked-down filesystem. Because the agent can run shell commands, sandboxing is not optional. For visibility you get the message stream, saved transcripts, and hooks that log every tool call.

LangGraph agents are plain services. LangSmith traces each node, a visual studio lets you step through state, and a hosted deployment option exists for long-running graphs. Durable execution through checkpoints means a redeploy or a crash does not erase a run in progress.

Cost and Latency

Both are free to install. The bill is model tokens plus hosting. Loops tend to cost more when a task is vague, because the model may open ten files where three would do. Graphs let you cap that: send easy steps to a small model, limit retries with a recursion limit, and skip the model entirely for deterministic steps. The flip side is that a loop often reaches a working result sooner on open-ended work, because nobody has to design the graph first.

Which One to Pick

Pick Claude Agent SDK When

• The agent works on files, code, or the shell, and the built-in tools already match the job
• The path through the task cannot be predicted ahead of time
• You are committed to Claude and want its tool-use behavior inside your product
• You want a working prototype in an afternoon, not a week
• Your safety story is about which actions are allowed, not which stages run

Pick LangGraph When

• The process has ordered stages, branches, and retries that must happen every time
• You need to mix models from several vendors or swap them freely
• Runs must pause for days and resume exactly where they stopped
• Auditors want the state at every step
• Several teams own different agents that must hand work to each other

Run Both Together

They are not mutually exclusive. A common pattern uses LangGraph as the outer workflow, with one node that calls the Claude Agent SDK for the open-ended part, such as "fix the failing tests." The graph handles routing, approval, and retries. The SDK handles the messy middle.

💡 Worth remembering: both projects ship changes quickly. Check each one's release notes before relying on any detail here, especially option names and defaults.

Your Turn: Create With Picasso IA

The best way to settle a framework debate is to try it on something small. The same goes for visuals. Your agent project will need a hero image for the README, a photo for the launch post, or a moodboard for the product page, and Picasso IA makes that quick.

Prototype your agent prompt with Claude Sonnet 5 on PicassoIA:

1. Open the Claude Sonnet 5 page.
2. Paste your draft system prompt and one realistic task.
3. Ask the model to list, in order, the tools it would call and why.
4. Run the same text through Claude Opus 4.7 or Gemini 3.1 Pro and compare the plans.
5. Keep the plan that matches the steps you would have drawn in a graph. That tells you which framework fits.

Then make something to go with it. Describe a scene, such as a software team at a whiteboard in soft morning light, shot on 35mm film, and generate it in seconds. Browse every available model at picassoia.com/en/all-models, try three or four prompts, and see how far a single sentence takes you. Your next agent deserves a good-looking launch.