Claude Agent SDK vs LangGraph (2026): When Each Wins

Quick answer (2026): The Claude Agent SDK and LangGraph solve two different layers of the same problem. The Claude Agent SDK is a batteries-included agent loop, the same loop that powers Claude Code, packaged as a Python and TypeScript library with 10+ built-in tools, permissions, sessions, and subagents. LangGraph is a lower-level, provider-agnostic graph runtime for building stateful, long-running agents where you draw the control flow yourself. Pick the Claude Agent SDK when you want a capable coding or ops agent shipping in minutes on Claude models. Pick LangGraph when you need custom control flow, durable multi-agent orchestration, or model provider flexibility. This tutorial builds the same agent in both so you can decide from code, not marketing.

This is the third leg of our Claude Agent SDK cluster. If you have not read it yet, start with Claude Agent SDK vs building the agent loop yourself, which explains why you would reach for a framework at all. Here we assume you have already decided to use one and are choosing between the two most common picks in 2026.

What is the Claude Agent SDK?

The Claude Agent SDK is a library that gives you the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript (Anthropic docs, 2026). You hand Claude a prompt and a set of allowed tools, and Claude runs the read-decide-act loop on its own until the job is done.

Install it and set your key:

# Python 3.10+
pip install claude-agent-sdk

# TypeScript (bundles the native binary as an optional dependency)
npm install @anthropic-ai/claude-agent-sdk

export ANTHROPIC_API_KEY=your-api-key

What you get out of the box, verified against the 2026 docs:

• Built-in tools: Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, Monitor, and AskUserQuestion. You do not implement tool execution yourself.
• Permissions: pre-approve safe tools with allowed_tools, or set a permission_mode such as acceptEdits.
• Sessions: resume a session by id, or fork it to explore a different path. Session state is JSONL on your filesystem.
• Subagents: spawn specialized agents through the built-in Agent tool and an AgentDefinition.
• MCP: connect external systems (databases, browsers, APIs) through Model Context Protocol servers.
• Hooks: run custom code at lifecycle points such as PreToolUse, PostToolUse, and SessionEnd.
• Model authentication: Anthropic API by default, plus Amazon Bedrock, Google Cloud, and Microsoft Foundry via environment variables.

The SDK targets Claude models specifically. That is the deliberate trade: less flexibility on the model, far less wiring on the tools.

What is LangGraph?

LangGraph is described in its own docs as "a low-level orchestration framework and runtime for building, managing, and deploying long-running, stateful agents" (LangGraph docs, 2026). Instead of one built-in loop, you model the agent as a graph: nodes do work, edges decide what runs next, and a shared state object flows through the whole thing.

# Python
pip install -U langgraph

Core abstractions, from the 2026 docs:

• StateGraph: the graph you build from nodes and edges, with START and END markers.
• State: a typed object (often a MessagesState) that every node reads and updates.
• Persistence / checkpointer: agents can persist through failures and resume from where they stopped, which is what makes them "durable".
• Human-in-the-loop: you can pause, inspect, and modify agent state at any point in the graph.
• Streaming: token and step streaming for real-time output.
• Provider-agnostic: LangGraph works with any model and can be used without LangChain. LangChain is the higher-level agent framework built on top of the LangGraph runtime.

The trade here is the mirror image of the SDK: maximum control over flow and model choice, in exchange for wiring the tools and the graph yourself.

Claude Agent SDK vs LangGraph: the decision matrix

Year-tagged to the 2026 docs for both projects.

Scroll to see more

Axis	Claude Agent SDK	LangGraph
Core idea	Batteries-included agent loop (the Claude Code loop) as a library	Low-level graph runtime for stateful, long-running agents
Languages	Python 3.10+ and TypeScript	Python primary; JS/TS available
Model support	Claude models (API, Bedrock, Vertex, Foundry)	Provider-agnostic, any supported model
Tools	10+ built-in tools, no wiring	You define every tool
Control model	High level: Claude runs the loop and picks tool order	Low level: you draw nodes, edges, and control flow
State and durability	Sessions, resume and fork, JSONL on disk	Checkpointer persistence, resume-after-failure, human-in-the-loop
Multi-agent	Subagents via the Agent tool	First-class multi-agent topologies via graphs
Fastest to ship	Coding, file, and ops agents on Claude	Custom flows and orchestration you fully own

Build the same agent in both

The task: give the agent one job and let it decide when to use a tool. We use Python for an apples-to-apples read.

With the Claude Agent SDK

The SDK ships the tools, so a file-reading agent needs almost no setup. You give it a goal and the tools it may use, then iterate the async stream.

# pip install claude-agent-sdk   (Python 3.10+)
# export ANTHROPIC_API_KEY=...
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Read report.txt and summarize it in three bullet points",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob"]),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

Claude opens the file, reads it, and writes the summary without you ever handling the tool call. To add your own tool instead of a built-in one, you register an in-process function with the SDK MCP helpers; see the Anthropic Agent SDK overview for create_sdk_mcp_server.

With LangGraph

LangGraph does not ship application tools, so you define the tool as a plain Python function and let the prebuilt agent wire it into the loop. Note that the model is provider-agnostic here.

# pip install -U langgraph "langchain[anthropic]"
from langgraph.prebuilt import create_react_agent

MODEL = "anthropic:claude-sonnet-5"  # swap in your current Claude model alias, or any provider


def get_weather(city: str) -> str:
    """Return the current weather for a city."""
    return f"It is 22C and sunny in {city}."


agent = create_react_agent(
    model=MODEL,
    tools=[get_weather],
    prompt="You are a concise weather assistant.",
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "What is the weather in Lisbon?"}]}
)
print(result["messages"][-1].content)

create_react_agent is the shortcut. The moment you need branching, retries with a checkpointer, or a second agent, you drop down to a full StateGraph and wire the nodes and edges yourself. That is the point of LangGraph: the low-level control is always there when the shortcut runs out.

Read the difference

In the SDK example, the tool is Read, a first-party capability you did not write. In the LangGraph example, the tool is get_weather, a function you wrote and registered. That single line is the whole philosophy gap. The SDK optimizes for "the agent already knows how to touch a filesystem and a shell"; LangGraph optimizes for "you decide exactly what the agent can do and how the graph flows".

When should you use the Claude Agent SDK?

• You are building a coding, file, or operations agent and want the Claude Code tool set immediately.
• You are on Claude models and are comfortable staying there.
• You want to ship in an afternoon and add subagents, hooks, and MCP later without re-architecting.
• You value the built-in permission and session model over building your own.

If you are new to the SDK, our Python quickstart walks the first agent end to end.

When should you use LangGraph?

• You need custom control flow: branching, loops with explicit exit conditions, or conditional edges the model does not decide.
• You need durable, long-running agents that resume after a crash via a checkpointer.
• You are orchestrating multiple agents as an explicit topology, not a single delegating parent.
• You want to swap model providers, or mix providers inside one workflow.

Can you use them together?

Yes, and it is a reasonable architecture. LangGraph owns the outer graph and the durable state, and a node inside that graph calls the Claude Agent SDK to do a self-contained coding or file task. You get LangGraph's orchestration and persistence on the outside and the SDK's built-in tools on the inside. The cost is two dependency trees and two mental models, so only reach for the combination when a single framework genuinely cannot express what you need.

For an independent, reproducible scoreboard of agent frameworks and builders, the neutral benchmarks at BuilderProof are a useful second opinion before you commit.

FAQ

Answered below and mirrored in the page FAQ schema.

Limitations and open questions

• Both projects move fast. Every version, install command, and model alias here is tagged to the 2026 docs; re-check the Agent SDK overview and the LangGraph overview before you pin dependencies, and prefer a model alias over a dated model id so your code does not go stale.
• The create_react_agent shortcut hides most of LangGraph's real surface area. A fair "hard mode" comparison would rebuild the same agent as an explicit StateGraph with a checkpointer; that is a follow-up tutorial, not this one.
• We did not benchmark latency, token cost, or reliability under load. Those depend on your model, your tools, and your traffic, and deserve their own measured post rather than a claim here.
• Provider lock-in is a real axis we treated briefly. If multi-provider portability is a hard requirement for you, weight it more heavily than this matrix does.