The Claude Agent SDK

1 · What the Claude Agent SDK is essential

Back in Agents from scratch you wrote the loop yourself: send a message, read the tool call Claude asked for, run the tool, feed the result back, repeat until Claude stops. That loop is the beating heart of every agent — and once you've written it a few times you notice it's always the same shape. Parsing tool-use blocks, appending results, capping the turns, gating dangerous actions, remembering the conversation: plumbing you rewrite on every project.

The Claude Agent SDK is Anthropic's official library for building agents in code — it runs that loop for you. It's the claude-agent-sdk Python package (it was called the "Claude Code SDK" earlier — same lineage), and it is the programmatic engine behind the Claude Code CLI. You hand it a prompt, a set of tools, a permission policy, and a system prompt; it drives the perceive → act → observe cycle, manages the session, enforces permissions, and can spin up subagents — all the machinery you hand-rolled in ch04, but maintained by the people who build Claude.

Think of it as the layer you reach for when the CLI is too packaged (you want it embedded in your program, driven by your code) but the raw loop is too much undifferentiated plumbing (you don't want to own tool dispatch and permission gating by hand).

2 · Three ways to build with Claude essential

Before any code, get the map straight. There are three levels at which you can build on Claude, and the Agent SDK is the middle one. Read this left to right — each step hands more of the agent loop to Anthropic and asks less wiring of you:

On the left (ch04) you own everything: the loop, tool dispatch, the turn cap, permission checks, memory. Maximum control, maximum plumbing. In the middle — the Agent SDK — the SDK owns the loop and the machinery; you declare tools, permissions, and a system prompt through an options object and let it run. On the right (Claude Code) everything is packaged into a terminal program you drive by talking to it — no code at all. The SDK is what the CLI is built on: same engine, exposed as a library so you can embed it in your own application.

3 · Install & requirements essential

The SDK is a thin Python layer that drives the Claude Code CLI under the hood, which in turn talks to the Anthropic API. So you need three things, not one:

What to install

1. The Python package: pip install claude-agent-sdk.
2. The Claude Code CLI on your PATH — the SDK launches it as a subprocess. Install it per the Claude Code docs (typically via npm install -g @anthropic-ai/claude-code, but check the current instructions).
3. Credentials: an ANTHROPIC_API_KEY in your environment (or another auth method the CLI supports). The key is read from the environment — it never appears in your code.

setup.sh# needs: pip install claude-agent-sdk + Claude Code CLI + ANTHROPIC_API_KEY;
# API names evolve — verify in docs (claude-agent-sdk Python reference).
# 1. the SDK (Python)
pip install claude-agent-sdk

# 2. the Claude Code CLI it drives (verify the current install command in the docs)
npm install -g @anthropic-ai/claude-code

# 3. your key, in the environment (never in code)
export ANTHROPIC_API_KEY="sk-ant-..."

4 · Recipe 1 — the high-level query() essential

The simplest way in is the async query() function. You give it a prompt, and it returns an async stream of messages — the SDK runs the whole agent loop internally and yields each message (Claude's text, tool calls, tool results, a final result) as it happens. This is the same loop you wrote by hand in ch04, collapsed to one call.

recipe1_query.py# needs: pip install claude-agent-sdk + Claude Code CLI + ANTHROPIC_API_KEY;
# API names evolve — verify in docs (claude-agent-sdk Python reference).
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    # query() is async and returns an async iterator of messages.
    # The SDK runs the agent loop for you and yields messages as they arrive.
    async for message in query(
        prompt="List the Python files in this folder and summarize what each does.",
        options=ClaudeAgentOptions(
            system_prompt="You are a concise coding assistant.",
            allowed_tools=["Read", "Glob", "Grep"],   # read-only: no edits, no shell
        ),
    ):
        # Message/block class names evolve — verify in the docs. The final
        # result typically arrives as a message carrying a `.result` string.
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

5 · Recipe 2 — tools, prompt & permissions via options intermediate

Everything you configure about the agent goes on the options object — ClaudeAgentOptions. This is where the SDK earns its keep: instead of hand-writing a tool dispatcher and a permission gate (ch04, Lab 4.4), you declare them. Custom tools are defined with the @tool decorator and bundled into an in-process MCP server with create_sdk_mcp_server(...); the SDK handles the dispatch.

recipe2_tools.py# needs: pip install claude-agent-sdk + Claude Code CLI + ANTHROPIC_API_KEY;
# API names evolve — verify in docs (claude-agent-sdk Python reference).
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, tool, create_sdk_mcp_server

# @tool(name, description, input_schema) — the schema shape here is {arg_name: type}.
# Verify the exact input_schema form + return shape in the docs; names evolve.
@tool("get_weather", "Get the current weather for a city", {"city": str})
async def get_weather(args):
    city = args["city"]
    # ... your real implementation (call a weather API, read a DB, etc.) ...
    return {"content": [{"type": "text", "text": f"{city}: 22C and sunny"}]}

# Bundle your tools into an in-process MCP server the SDK can call.
weather = create_sdk_mcp_server(name="weather", version="1.0.0", tools=[get_weather])

options = ClaudeAgentOptions(
    system_prompt="You are a travel assistant. Use tools before you guess.",
    mcp_servers={"weather": weather},
    # tool names are namespaced mcp__<server>__<tool> — verify the prefix in the docs
    allowed_tools=["mcp__weather__get_weather"],
    permission_mode="default",   # default | acceptEdits | plan | dontAsk | bypassPermissions | auto
)

async def main():
    async for message in query(prompt="What should I pack for Lisbon?", options=options):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

6 · Recipe 3 — sessions & multi-turn intermediate

query() is one-shot: each call is a fresh conversation. For a back-and-forth session that remembers — the multi-turn memory you built by hand in ch04's Lab 4.5 — use ClaudeSDKClient. You open it once, send turns with .query(...), and read each reply by iterating .receive_response(); the client keeps the history for you.

recipe3_session.py# needs: pip install claude-agent-sdk + Claude Code CLI + ANTHROPIC_API_KEY;
# API names evolve — verify in docs (claude-agent-sdk Python reference).
import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(system_prompt="You are a helpful research assistant.")

    # The client keeps the conversation alive across turns — no manual history list.
    async with ClaudeSDKClient(options=options) as client:
        await client.query("What is the capital of Portugal?")
        async for message in client.receive_response():
            # reading the text off a message: block/class names evolve — verify in docs
            print(message)

        # follow-up in the SAME session; "that city" resolves because state is kept
        await client.query("What is the population of that city?")
        async for message in client.receive_response():
            print(message)

asyncio.run(main())

7 · Recipe 4 — subagents advanced

A single agent's context fills up fast when it reads dozens of files. Subagents fix that: each is a separate agent instance with its own fresh context, its own system prompt, and its own restricted tool set. The main agent delegates a focused subtask, the subagent does the work in isolation, and only its final message comes back — the intermediate noise never pollutes the parent. Define them programmatically with AgentDefinition on the agents option; Claude invokes them through the built-in Agent tool.

recipe4_subagents.py# needs: pip install claude-agent-sdk + Claude Code CLI + ANTHROPIC_API_KEY;
# API names evolve — verify in docs (claude-agent-sdk Python reference).
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Review the auth module for security issues.",
        options=ClaudeAgentOptions(
            # the parent needs the Agent tool to be allowed to delegate
            allowed_tools=["Read", "Grep", "Glob", "Agent"],
            agents={
                "code-reviewer": AgentDefinition(
                    description="Security & quality review specialist. Use for code reviews.",
                    prompt="You are a code reviewer. Flag security and correctness issues, concisely.",
                    tools=["Read", "Grep", "Glob"],   # read-only: this subagent can't edit
                    model="sonnet",                    # optional per-subagent model override
                ),
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

8 · Recipe 5 — decide: raw loop vs SDK vs CLI (runs offline) advanced

The most valuable skill here isn't SDK syntax — it's picking the right level for the job. The helper below is pure stdlib and runs with a plain python file.py (no API key, no network, no install). Answer a few yes/no questions about your situation and it recommends the raw loop, the Agent SDK, or the CLI, with a reason.

decide.pydef choose_build_level(*, embed_in_app, need_full_control_of_loop,
                       terminal_is_fine, learning_how_agents_work):
    """Recommend raw messages loop vs Claude Agent SDK vs Claude Code CLI.
    All inputs are booleans describing your situation."""
    if learning_how_agents_work or need_full_control_of_loop:
        pick = "raw messages loop"
        why = "you want to own the loop end-to-end (control, or learning the mechanics)."
    elif terminal_is_fine and not embed_in_app:
        pick = "Claude Code CLI"
        why = "a packaged terminal agent is enough; no need to embed it in code."
    elif embed_in_app:
        pick = "Claude Agent SDK"
        why = "you want the agent loop inside your program without hand-writing the plumbing."
    else:
        pick = "Claude Agent SDK"
        why = "the safe default: managed loop, your tools and permissions."
    return {"pick": pick, "why": why}

scenarios = {
    "Embed an agent in our web backend": dict(
        embed_in_app=True, need_full_control_of_loop=False,
        terminal_is_fine=False, learning_how_agents_work=False),
    "Quick coding help in my terminal": dict(
        embed_in_app=False, need_full_control_of_loop=False,
        terminal_is_fine=True, learning_how_agents_work=False),
    "Teach myself how agent loops work": dict(
        embed_in_app=False, need_full_control_of_loop=False,
        terminal_is_fine=False, learning_how_agents_work=True),
}

for name, situation in scenarios.items():
    r = choose_build_level(**situation)
    print(f"{name}\n  -> {r['pick']} ({r['why']})")

Embed an agent in our web backend
  -> Claude Agent SDK (you want the agent loop inside your program without hand-writing the plumbing.)
Quick coding help in my terminal
  -> Claude Code CLI (a packaged terminal agent is enough; no need to embed it in code.)
Teach myself how agent loops work
  -> raw messages loop (you want to own the loop end-to-end (control, or learning the mechanics).)

9 · Production concerns professional

Letting an SDK drive a loop that can read files, run shell commands, and spend money is powerful and risky in equal measure. Three concerns turn a demo into something you'd run for real:

Production checklist

1. Permissions & sandboxing. Keep allowed_tools as small as the task allows, prefer read-only tools, and use permission_mode deliberately — never bypassPermissions outside a sandbox. For fine-grained control, pass a can_use_tool callback that inspects each call and returns allow/deny (verify the exact result types in the docs). Run untrusted work in a container or throwaway workspace.
2. Cost. An agent loop makes many API calls, and subagents multiply that into a tree. Cap it: set a spend limit (max_budget_usd) and bound subagent depth/concurrency (via the SDK's env options). Prefer a cheap model for routine subagent work.
3. Observability. The message stream is your trace — log every tool call, tool result, and the final result/usage. You cannot debug or price an agent you can't see. Persist the stream (or key events) so a failed run is diagnosable after the fact.

10 · Tech-lead — where the SDK fits tech-lead

A lead's job is to place each build on the right rung and keep the team off the wrong ones. The Agent SDK is the right default for "an agent embedded in our product": it gives you the managed loop, session handling, permissions, and subagents without a bespoke framework you'd have to maintain — and because it's the same engine as the CLI, behavior you validate in the terminal transfers to production.

Steer by these lines. Reach down to the raw loop only when you need control the SDK doesn't expose, or you're deliberately teaching the mechanics — accept that you now own the plumbing forever. Reach up to the CLI for developer-facing terminal work where embedding buys nothing. Sit on the SDK for everything in between. And treat the honest caveat as a standing rule: this surface is young and moving — pin your claude-agent-sdk version, read the changelog before upgrading, and verify class and option names against the current docs rather than trusting a snippet (including these).

import asyncio
from claude_agent_sdk import query

async def main():
    async for message in query(prompt="List three uses for a hash map."):
        # messages stream in; print any text blocks
        for block in getattr(message, "content", []) or []:
            if getattr(block, "type", None) == "text":
                print(block.text)

asyncio.run(main())

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

opts = ClaudeAgentOptions(
    system_prompt="You are a careful code reviewer. Never edit files.",
    allowed_tools=["Read", "Grep"],       # read-only
    permission_mode="default",
)

async def main():
    async for m in query(prompt="Summarize what src/ contains.", options=opts):
        for b in getattr(m, "content", []) or []:
            if getattr(b, "type", None) == "text":
                print(b.text)

asyncio.run(main())

from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions

@tool("add", "Add two numbers", {"a": float, "b": float})
async def add(args):
    total = args["a"] + args["b"]
    return {"content": [{"type": "text", "text": str(total)}]}

server = create_sdk_mcp_server(name="calc", version="1.0.0", tools=[add])

opts = ClaudeAgentOptions(
    mcp_servers={"calc": server},
    allowed_tools=["mcp__calc__add"],
)
# offline check of the tool contract:
import asyncio
print(asyncio.run(add({"a": 2, "b": 3})))   # {'content': [{'type':'text','text':'5.0'}]}

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

async def main():
    async with ClaudeSDKClient(options=ClaudeAgentOptions()) as client:
        await client.query("My name is Ada. Remember it.")
        async for _ in client.receive_response():
            pass
        await client.query("What is my name?")   # same session -> remembers
        async for m in client.receive_response():
            for b in getattr(m, "content", []) or []:
                if getattr(b, "type", None) == "text":
                    print(b.text)

asyncio.run(main())

from claude_agent_sdk import ClaudeAgentOptions, AgentDefinition

reviewer = AgentDefinition(
    description="Reviews diffs for bugs; read-only.",
    prompt="You are a strict reviewer. Report issues; never edit.",
    tools=["Read", "Grep"],
    model="sonnet",                 # per-agent model override
)

opts = ClaudeAgentOptions(
    agents={"reviewer": reviewer},
    system_prompt="Delegate code review to the reviewer subagent.",
)
print(opts.agents["reviewer"].model)   # sonnet

def choose_build_level(need_custom_tools, want_managed_loop,
                       want_zero_code, need_fine_control):
    if want_zero_code and not need_fine_control:
        return "claude-code-cli"         # fully packaged, no code
    if need_fine_control and not want_managed_loop:
        return "raw-loop"                # you own the perceive-act-observe loop
    return "agent-sdk"                   # SDK runs the loop, you supply tools

# A team wanting custom tools + a managed loop, some control:
rec = choose_build_level(need_custom_tools=True, want_managed_loop=True,
                         want_zero_code=False, need_fine_control=False)
print(rec)   # agent-sdk
# Justification: custom tools + managed loop = SDK; CLI is too opaque for
# an embeddable library, a raw loop is needless maintenance here.

Knowledge check check yourself