Blog
8 min read

Claude Agent SDK vs LangGraph: Agent Harness or Orchestration Framework, and When to Use Both

Claude Agent SDK vs LangGraph compared: what each does, models, state and persistence, human-in-the-loop, auth and billing, when to pick which, and using both.

The Claude Agent SDK is Claude Code's agent loop as a Python or TypeScript library: you give it a task and a set of permissions, and Claude decides the steps, using built-in tools for files, shell commands and web search. LangGraph is LangChain's open source framework for building agents and workflows as graphs: you define the steps, the state and the branches, plug in any model, and get checkpointing, durable execution and human-in-the-loop pauses. The SDK gives you a capable agent quickly, as long as Claude is your model. LangGraph gives you explicit control over a process you design. They work at different layers, and they combine well.

Checked against the Agent SDK docs and Anthropic's Help Center, the LangGraph docs, and PyPI and npm package metadata in November 2026.

At a glance

Claude Agent SDK LangGraph
Made by Anthropic LangChain
What it is A ready-made agent harness (the Claude Code engine) A low-level orchestration framework and runtime
Languages Python (claude-agent-sdk), TypeScript (@anthropic-ai/claude-agent-sdk) Python (langgraph), JavaScript/TypeScript (@langchain/langgraph)
Models Claude, via the Anthropic API or Claude on AWS, Google Cloud or Microsoft Foundry Any model you can call
Control flow The model plans its own steps in a loop You define nodes and edges; the model works inside them
Built-in tools Yes: read, write and edit files, run commands, search the web None; you supply tools
State and persistence Session transcripts on local disk, resumable and forkable; optional SessionStore Checkpointers (in-memory, SQLite, Postgres) save graph state per thread
Human approval Permission modes, a per-tool-call callback, hooks interrupt() anywhere in a node, resume later
Runtime shape Spawns a claude CLI subprocess with a shell and working directory A normal library in your process
Licence / terms Governed by Anthropic's Commercial Terms MIT

What the Claude Agent SDK gives you

The Agent SDK packages the same tools, agent loop and context management that power Claude Code. You call query() with a prompt and options, and it streams back messages as Claude reads files, runs commands and edits code until the task is done:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def main():
    async for message in query(
        prompt="Find why tests/test_cart.py fails and fix it.",
        options=ClaudeAgentOptions(
            cwd="/srv/projects/shop",
            allowed_tools=["Read", "Grep", "Glob", "Edit", "Bash"],
            permission_mode="acceptEdits",
            max_turns=30,
        ),
    ):
        if isinstance(message, ResultMessage):
            print(message.subtype, message.total_cost_usd)

asyncio.run(main())

Around that loop you get Claude Code's features: permissions, hooks that run your code before or after tool calls, subagents, MCP servers, sessions you can resume or fork, and skills and CLAUDE.md memory from .claude/ directories. The Claude Agent SDK guide covers the API in more depth.

Two architectural facts matter when you plan around it:

  • It runs a subprocess. Each session is a claude CLI process that owns a shell, a working directory and JSONL transcripts on local disk. Anthropic's hosting guide suggests 1 GiB RAM, 5 GiB disk and 1 CPU per agent as a starting point, and notes that none of that local state survives a container restart unless you add a SessionStore or a volume.
  • Sessions persist the conversation, not the filesystem. Resuming a session restores what Claude knew. File changes are whatever is on disk; the SDK offers file checkpointing separately.

What LangGraph gives you

LangGraph describes itself as "a low-level orchestration framework and runtime for long-running, stateful agents", and its docs state that it does not require LangChain. You model your agent as a graph: a typed state object, nodes that read and update it, and edges (including conditional ones) between them. A node can call a model, a tool, an API or plain code.

from typing import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.types import interrupt, Command

class State(TypedDict, total=False):
    ticket: str
    draft: str
    approved: bool

def draft_reply(state: State):
    return {"draft": write_draft(state["ticket"])}   # your model call, any provider

def human_review(state: State):
    return {"approved": interrupt({"draft": state["draft"]})}

builder = StateGraph(State)
builder.add_node(draft_reply)
builder.add_node(human_review)
builder.add_edge(START, "draft_reply")
builder.add_edge("draft_reply", "human_review")
builder.add_edge("human_review", END)
graph = builder.compile(checkpointer=InMemorySaver())

config = {"configurable": {"thread_id": "ticket-4812"}}
graph.invoke({"ticket": "Refund request for order 8812"}, config)  # pauses at review
graph.invoke(Command(resume=True), config)                          # continues

What LangGraph does well:

  • Persistence and durable execution. A checkpointer saves graph state per thread_id. The docs name InMemorySaver for experiments, SqliteSaver for local development and PostgresSaver for production. A run can resume after a crash, a deploy or a pause of days.
  • Human-in-the-loop anywhere. interrupt() stops the graph inside any node and saves state; Command(resume=...) continues it, and the resume value becomes the return value of interrupt(). Note that the node re-runs from its start on resume, so code before the interrupt() call runs twice.
  • Model independence. Each node can use a different provider, or no model at all.
  • Predictable structure. Branches, retries, parallel steps and approval gates are code you can read and test, not behaviour you hope the model follows.

Observability and hosted deployment come from LangSmith, a separate commercial LangChain product. LangGraph itself is an MIT-licensed library.

Auth and billing

LangGraph has no billing of its own. You pay whichever model providers your nodes call, plus LangSmith if you use it.

The Agent SDK needs Claude access. The documented options are an ANTHROPIC_API_KEY from the Claude Console (billed per token at API rates), or environment flags for Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform and Microsoft Foundry.

Using a Claude subscription instead of an API key is where people get confused, so here is Anthropic's stated position as of November 2026:

  • For products you ship to others: the Agent SDK docs say that, unless previously approved, Anthropic does not allow third-party developers to offer claude.ai login or rate limits in their products, including agents built on the SDK. Use API key authentication.
  • For your own use while signed in with your plan: Anthropic's Help Center says Agent SDK and claude -p usage draws from your subscription's usage limits. A planned move to a separate monthly credit was paused in June 2026. Since October 2026, Max, Ultra and Team plans also include monthly API credits that apply when you use the SDK with an API key from a linked Console organisation.

This has changed several times in 2026, so check the Help Center before budgeting around it.

When to pick which

Pick the Claude Agent SDK when:

  • The work looks like what Claude Code does: reading and changing a codebase, running tests, operating on files, using a shell.
  • You want a capable agent this week, not an architecture project, and you're happy committing to Claude models.

Pick LangGraph when:

  • The process has a known shape (intake, classify, draft, approve, send) and you want it enforced in code.
  • You need runs that pause for hours or days and survive restarts, with state in Postgres.
  • You need different models for different steps, or want freedom to switch provider.
  • Your agent mostly calls APIs and databases rather than a filesystem and shell, so a subprocess with a working directory is overhead.

Using both together

The two compose naturally, because a LangGraph node can run any code, including an Agent SDK query(). A common pattern is LangGraph for the outer workflow and the Agent SDK for the step that needs a hands-on agent:

  1. A LangGraph node triages an incoming bug report with a cheap model.
  2. The next node calls the Agent SDK with cwd set to a checkout of the repo, allowed_tools limited to what the fix needs, and a max_turns cap. It returns the diff and summary into graph state.
  3. An interrupt() node waits for a human to approve the change.
  4. A final node opens the pull request.

Two cautions. LangGraph checkpoints between nodes, not inside the Agent SDK's run, so if the process dies mid-agent the node starts again; make that step safe to repeat, for example by working in a fresh branch or worktree. And the Agent SDK step still needs a real filesystem, so the worker running that node needs one.

For tracing, LangSmith has a native Claude Agent SDK integration (configure_claude_agent_sdk() in Python) that records agent runs, tool calls and model calls, so both layers can show up in one place.

If you'd rather not operate SDK subprocesses at all, Anthropic's Managed Agents host the agent loop for you.

The short answer

If your agent is a worker that needs hands (files, shell, a codebase), start with the Claude Agent SDK. If your agent is a process that needs structure (steps, approvals, durable state, several models), start with LangGraph. If it's both, put the SDK inside a LangGraph node. For the bigger picture of what makes something an agent at all, see what is agentic AI, and for scripted Claude Code runs without either library, headless mode may be enough.


Agent SDK agents need a working directory, a shell and somewhere for their state to survive between runs. EasySpawn gives each server a persistent, isolated VM with Claude Code, a managed database and a live URL per branch, which suits the "worker with hands" side of this comparison. It doesn't replace LangGraph's orchestration. See how it works or join the waitlist.

Related: The Claude Agent SDK: Building Your Own Agents on Claude Code's Engine · What Is Agentic AI? A Plain-English Explanation (With Examples) · Running Claude Code Headless: claude -p in Scripts, Cron, and CI · How to Build an AI Agent: The Loop, the Tools, and the Guardrails

Keep reading