The Claude Agent SDK

1 · What the Claude Agent SDK is essential

Here's a moment that repeats in every agent project. Your first agent works — you hand-wrote the loop, it calls a tool, it answers. So you build a second one, and a third, and somewhere around the third you catch yourself copy-pasting: the same tool-dispatch switch, the same "stop after N turns" guard, the same try/except around a tool that might throw. You're not writing agent logic anymore; you're re-typing the same scaffolding. That itch — "I've built this exact plumbing before" — is precisely the itch the Claude Agent SDK scratches.

Think of it like the difference between wiring a house and buying an appliance. You could run your own copper for every socket, and if you're an electrician learning the trade you should — but for the fridge you just want a plug that works, built to code, maintained by someone else. The SDK is the appliance: the agent loop, packaged, standardized, and kept current by the people who build Claude itself. You still decide what the agent does; you stop re-soldering the wiring behind it.

The mistake to avoid is thinking the SDK is a different way to build agents — some rival abstraction you have to learn from zero. It isn't. It's the same perceive → act → observe loop from ch04, with the mechanical parts lifted out and given a clean surface. Everything you already understand about tool calls, turn caps, and message history is still true; the SDK just stops making you write it out by hand. Read the rest of this section as "here's the loop you know, now managed for you," not "here's a new thing to memorize."

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

Most wasted effort in agent projects comes from picking the wrong altitude, not writing bad code. A team hand-rolls a raw loop for something the CLI already does in one line; another team fights to embed a terminal program into a web backend where it was never meant to live. Both wrote fine code — they just built it at the wrong level. So before a single import, the highest-leverage thing you can do is place your task on the right rung.

The cleanest way to picture the three levels is a set of Russian nesting dolls. The smallest, innermost doll is the raw messages loop — the bare API call and your own code around it. Wrap that in a managed loop with tools and permissions and you get the Agent SDK. Wrap that in a finished terminal program and you get the Claude Code CLI. Crucially, it's the same doll all the way down: the CLI is the SDK with a terminal bolted on, and the SDK is the messages loop with the plumbing filled in. You're not choosing between three different engines — you're choosing how much of the same engine comes pre-assembled.

The common mistake is to reach for the level you're most comfortable with rather than the one the job wants. Engineers who love control default to the raw loop and then drown in maintenance; people who fear code default to the CLI and then can't embed it where the product needs it. The fix is a single question, and the diagram below is built around it: who writes the loop — you, the SDK, or the CLI? Answer that honestly and the right rung usually names itself.

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

This is the section people skim, and it's the section that eats their first afternoon. The trap is a quiet one: pip install claude-agent-sdk succeeds, import claude_agent_sdk succeeds, and everything looks installed — until you actually call the agent and it dies with an error about a missing subprocess. The import working fooled you into thinking setup was done. It wasn't, and knowing why up front saves you the confused debugging session.

The reason is that the SDK isn't a self-contained library the way requests or numpy is. Picture it as a remote control, not the television. The Python package is a tidy remote with nice buttons, but the actual device doing the work is the Claude Code CLI running as a separate program — the SDK shells out to it, and it in turn talks to the Anthropic API. A remote with no TV in the room presses buttons into the void. That's exactly what a Python-only install is: buttons that connect to nothing at runtime.

So the mental model for setup is three parts, not one, and each has to be genuinely present: the Python package (the remote), the CLI on your PATH (the television), and an API key in the environment (the electricity that powers the whole thing). Miss any one and the failure shows up not at install time but the first time you press play. Keep the three-part picture in mind as you read the steps below — the point of the section is less "type these commands" and more "understand why one command was never going to be enough."

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

Remember the whole loop you wrote in ch04? The send, the parse-the-tool-call, the run-it, the feed-the-result-back, the "am I done yet" check, over and over. Now watch it collapse into a single function call. That compression is the moment the SDK's value becomes concrete instead of abstract — query() is the one line that swallows a page of your hand-written plumbing.

Here's the mental shift that trips people, and it's worth naming before the code. An ordinary function call gives you back one answer when it's done. query() doesn't work that way — it hands you a live feed, like a sports commentary rather than a final score. As the agent thinks, calls a tool, reads the result, and thinks again, each of those steps streams out to you as a separate message: here's Claude's text, here's a tool call, here's the tool's result, and finally here's the wrapped-up answer. You don't wait for a return value; you loop over the events as they arrive. That streaming shape is exactly why a whole multi-step agent can hide behind one call — the call isn't a single round-trip, it's the entire conversation playing out through an iterator.

The beginner mistake is to treat query() like client.messages.create() and expect a tidy response object you can print. You'll instead get an async iterator, and if you forget the async for (or forget to run it inside asyncio.run) nothing happens at all — no error, no output, just a coroutine you created and never awaited. So the shape of the code below isn't ceremony: async for message in query(...) inside an async def, kicked off by asyncio.run(main()), is the minimum honest way to consume a stream. Get that skeleton in your fingers and every later recipe is a variation on it.

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

An agent with the default toolbox is a stranger you've handed the keys to your house. It can read, write, edit, and run shell — useful, and also exactly how a well-meaning agent deletes a file it shouldn't have touched. The difference between a demo and something you'd let near real data is almost entirely what you allow it to do, and in the SDK that decision lives in one place: the options object.

The shift here is from writing behavior to declaring it. In ch04 you hand-built a tool dispatcher (a switch that matched a tool name to a function) and a permission gate (an if that asked before anything dangerous). With the SDK you don't write either — you fill in a ClaudeAgentOptions form and hand it over. Think of it like the settings panel on a new phone: you don't code the camera permission, you flip a switch that says "this app may use the camera." system_prompt sets the agent's persona, allowed_tools is the list of switches flipped on, and permission_mode decides how cautious the whole thing is by default. The SDK reads the form and enforces it.

Two ideas in the code below deserve a heads-up so they don't feel like magic. First, giving the agent your own code as a tool: the @tool decorator turns a plain async function into something the agent can call, and create_sdk_mcp_server(...) bundles those tools into a tiny server that runs inside your process — no separate service, no network hop, despite the "server" name. Second, the naming: custom tools show up under a namespaced mcp__<server>__<tool> label, which is the string you list in allowed_tools. The mistake to sidestep is treating allowed_tools as a nice-to-have you'll tighten later — it is the security boundary, so start it as small and as read-only as the task tolerates and widen only when something genuinely can't be done. An empty list is a perfectly valid, perfectly safe starting point.

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

Try to build a chatbot on query() and you'll hit a wall by the second message. "What's the capital of Portugal?" → "Lisbon." "What's its population?" → and the agent has no idea what "its" refers to, because the second call started life with total amnesia. Every query() is a fresh conversation with someone who's never met you. For anything that has to remember — which is most real assistants — that's a dealbreaker, and it's the whole reason this section exists.

The fix is a shift from a vending machine to a phone call. query() is the vending machine: each transaction is complete and independent, you get your snack, it forgets you instantly. ClaudeSDKClient is the phone call: you dial once, and for the length of the call both sides remember what was already said, so "that city" resolves without you re-explaining. Under the hood the client is keeping the running message history for you — the exact bookkeeping you hand-assembled as a growing list in ch04's Lab 4.5 — but you never see or manage that list. You just keep talking on the same line.

The shape of the code follows that phone-call metaphor closely, and two habits keep it correct. You open the line with async with ClaudeSDKClient(...) so it's guaranteed to hang up cleanly when you're done; inside, each turn is a .query(...) to speak followed by draining .receive_response() to hear the full reply. The mistake beginners make is firing the next .query() before fully consuming the previous response — the equivalent of talking over the other person — which scrambles the turn order. Finish reading one reply, then send the next turn. Get that rhythm right and the session state does the remembering for free, which is the entire payoff of reaching past query().

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

Watch what happens to a single agent asked to review a whole codebase. It reads a file, then another, then twenty more, and every one of those files is now sitting in its context window — thousands of lines of code it mostly doesn't need anymore, crowding out the actual reasoning and driving up cost on every turn. By the time it forms an opinion, its "memory" is a landfill of half-relevant file dumps. The agent didn't get dumber; its workspace got buried. Subagents are the answer to that specific failure.

The intuition is delegation, exactly as a good manager does it. You don't personally read all forty files — you hand a focused brief to a specialist ("review the auth module for security issues"), they go off and do the messy reading on their own desk, and they come back with a one-paragraph verdict. All the clutter — the forty files, the dead ends, the intermediate notes — stayed on their desk and never landed on yours. In SDK terms each subagent is a separate agent instance with its own fresh context, its own system prompt, and its own restricted toolset; the parent sees only the subagent's final message. That's context isolation, and it's the headline benefit.

There are two more wins worth having in view before the code. Because subagents are independent, they can run in parallel — a review can fan out a security pass, a style pass, and a test-coverage pass at once — and because each has its own tools list, a read-only reviewer physically cannot edit a file even if it wanted to, which is a safety guarantee, not a polite request. You wire them up by declaring AgentDefinition entries on the agents option; Claude then invokes them on its own through the built-in Agent tool. The one gotcha that stops delegation cold: the parent must have Agent in its own allowed_tools, or it has no way to hand work down — a subtle omission that makes a perfectly-defined subagent simply never get called.

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

Here's the skill that outlasts any particular API. The query() signature will drift, class names will get renamed (they already have once), whole methods will come and go — but the judgment of which level to build at is durable. A year from now you won't remember whether it was receive_response or read_reply; you'll still remember that a terminal task wants the CLI and an embedded one wants the SDK. This recipe trains the part that doesn't expire.

The reason to encode the decision as a function rather than a paragraph of advice is that a function forces you to be honest about your inputs. It's easy to hand-wave "I think the SDK feels right"; it's harder to fool yourself once you have to answer four blunt yes/no questions — am I embedding this in an app, do I need full control of the loop, is a plain terminal enough, am I here to learn the mechanics — and let the branches decide. Writing the criteria down turns a gut feeling into a repeatable rule you can point a teammate at, which is exactly what a tech lead needs when the whole team keeps asking "which one should I use?"

One friendly note about this particular lab: unlike every other code block in the lesson, it runs offline — pure standard library, no API key, no CLI, no network. That's deliberate. The decision is logic, not a call to Claude, so you can actually execute it, tweak the branch order, and watch the recommendation change. Don't over-read the output, though — the function is a thinking aid, not an oracle; real projects have nuances (compliance, existing infra, team skill) no four booleans capture. Use it to make your reasoning explicit, then apply judgment on top.

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

The gap between "it worked in my terminal" and "we run this in production" is where the scary stories live. An agent that reads files, runs shell commands, and spends real money on every turn is, from an operations standpoint, an autonomous process with a credit card and a keyboard. In a demo that's thrilling. Pointed at a real repository, a real database, and a real billing account, the same autonomy is a liability you have to actively contain. This section is the containment.

The mental model to carry in is defense in depth, the same layered idea a bank uses: a locked door, then a vault, then a camera, then an alarm — not one perfect wall but several imperfect ones, so a failure in any single layer isn't catastrophic. The three concerns below map onto three layers. Permissions decide what the agent is even allowed to touch (the locked door). Cost caps bound how much damage a runaway loop can do to your bill before someone notices (the vault limit). Observability is the camera — it doesn't prevent anything, but without it you can't debug, price, or explain what the agent did after the fact.

The costly mistake is treating these as things you'll "add later," because later usually means after the incident. The good news is the SDK gives you the levers cheaply and up front: a tight allowed_tools and a sane permission_mode cost you nothing but a moment's thought; a spend cap is one option; and the message stream you're already looping over is your audit log if you just persist it. Wire the guardrails in on day one, when they're a few lines, rather than on the day you're explaining to someone why an agent ran Bash against production. The checklist below is the day-one version.

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

An individual engineer picks the right tool for one task; a tech lead picks the right default for a hundred tasks they'll never personally see. That's a different and harder problem. Left to their own instincts, ten engineers will make ten different calls — some hand-rolling loops, some fighting to embed the CLI — and six months later you have a codebase with three ways to talk to Claude and nobody who understands all of them. The lead's job here isn't to make the clever choice once; it's to set a standard that keeps the team out of the ditches on either side.

The useful frame is a highway with guardrails, not a maze. The Agent SDK is the main lane, and it should be the boring default for the most common request you'll get — "put an agent inside our product" — because it hands you the managed loop, sessions, permissions, and subagents without a bespoke framework someone will have to maintain after they've left the company. The guardrails are the two exits: reach down to the raw loop only when you need control the SDK genuinely doesn't expose (and accept you now own that plumbing forever), and reach up to the CLI for developer-facing terminal work where embedding buys nothing. Naming those exits explicitly is what stops an engineer from taking one out of mere preference.

The trap a lead must actively manage is this surface's youth. The SDK has already been renamed once and its class and option names keep moving — which means a snippet that worked last quarter (including the ones in this very lesson) can quietly rot. Treat that as a standing policy, not a footnote: pin the claude-agent-sdk version, read the changelog before any upgrade, and make the official Python reference — never memory, never a blog post, never this page — the source of truth for names. A team that pins and verifies ships calmly through the churn; a team that trusts snippets debugs the same rename three times. The rest of this section is that discipline spelled out.

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