Claude Agent SDKclaude-agent-sdk 0.2.157 · Python 3.10+
Dashboard
0%
1
Curious builder0 XP earned · 300 to level 2
0 daysFinish a lesson to begin
Badge collection0 of 6 unlocked
46 small wins to finish your pathNext lesson →

Claude Agent SDK logoClaude Agent SDK overview

The Claude Agent SDK is a Python library that runs Claude Code's agent loop inside your own program: the same built-in tools, the same loop and the same context management that drive the Claude Code terminal app, started from your code, with your own tools, permission rules and hooks wrapped around it.

Last updated: 20 Oct, 2026 · Claude Agent SDK

Anthropic publishes it on PyPI as claude-agent-sdk, with a TypeScript twin. Every page here runs against the Python package at version 0.2.157. The overview page of the documentation defines an agent as an application that completes a task by planning its own steps and calling tools that read files, run commands or edit code. The SDK hands you that application's engine and leaves the decisions to you.

Seeing where the SDK sits

The SDK does not call the Claude API itself. It starts the Claude Code binary as a separate process and exchanges JSON lines with it. Claude Code runs the loop: it sends your prompt to Claude, runs the tools Claude asks for, and repeats until Claude answers. Along the way it asks your program questions, such as whether a tool may run, and streams every step back.

What happens when you call query()
Your programquery() and your codeThe Agent SDKparses and routesClaude Coderuns the agent loopClaudedecides each step
Hover or tap a piece to see what it is and which lesson built it.
Follow a question

Pick one to watch it run, step by step.

Follow the trace above and watch one question travel out and back. Your side of that conversation is the part you write: the tools Claude can call, which run inside your own process, the permission rules and callback that decide whether a call may run, the hooks that watch or block each step, and the code that reads the messages as they arrive.

What comes built in

These are the Claude Code capabilities the overview page lists as available in the SDK, and this course works through each one:

  • Built-in tools that read, write and edit files, run commands and search the web, with no code from you.
  • Permissions, which decide the tool calls that run without asking and the ones that need approval.
  • Hooks, your own code running at fixed points in the agent's lifecycle.
  • MCP, the Model Context Protocol, which is how both your own functions and outside servers become tools.
  • Subagents, a fresh agent spawned for a focused subtask so the main conversation stays short.
  • Sessions, which hold context across exchanges and can be resumed or forked later.
  • Skills, commands and memory, loaded from a project's .claude/ folder the way Claude Code loads them.
  • Plugins, which package skills, agents, hooks and MCP servers behind one local path.

What you will build

One example grows through the whole course: a support desk for a small online shop. Order A17 shipped on 3 March, order B22 does not exist, and a refund needs a person's approval. By the end the desk looks orders up through tools you wrote, refuses a refund until someone approves it, logs every tool call, stops a runaway loop, holds a conversation across several questions and hands work to a subagent.

It runs with no API key. The course supplies a stand-in for the Claude Code binary, a small Python class that speaks the same JSON lines and makes the same decisions from a script instead of a model. Every output printed in this course came from a real run of the SDK against that stand-in, on any machine, for free. The one lesson that needs a key is the switch to the real Claude Code, and it is shown rather than run.

Everything in this course, and where it is going
1. The Agent SDK2. Running an agent3. Tools4. Permissions5. Hooks6. Conversations and sessions7. Shaping the agent8. Operating it9. The projectClaude Agent SDK overviewInstallation and setupHow the agent loop worksSDK, CLI and Client SDKThe messages you get backquery() and ClaudeAgentOptionsThe result messageStreaming outputStreaming inputWhen the CLI will not startThe built-in toolsCustom tools with @toolAn in-process MCP serverA tool that raisesWhich tools Claude can seeExternal MCP serversTool searchPermission modesAllow and deny rulescan_use_toolHandling approvalsTurn and budget limitsHooks: PreToolUseHooks that change a callThe hook eventsClaudeSDKClientResuming a sessionForking a sessionSession storageFile checkpointingSystem promptsClaude Code featuresSkillsCommandsPluginsSubagentsStructured outputModel, thinking and effortCost and usageObservabilityTodo trackingHosting the SDKSecure deploymentThe project and its toolsThe project's rulesRunning the project
Hover or tap a piece to see what it is and which lesson built it.

Nine parts, forty-seven lessons. The map above is the whole route; the table below is the same route with every lesson linked.

The nine parts

PartLessons
1. What the Agent SDK isClaude Agent SDK overview, Installation and setup, How the agent loop works, SDK, CLI and Client SDK compared, The messages you get back
2. Running an agentquery() and ClaudeAgentOptions, The result message, Streaming output, Streaming input, When the CLI will not start
3. ToolsThe built-in tools, Custom tools with @tool, An in-process MCP server, A tool that raises, Which tools Claude can see, External MCP servers, Tool search for large tool sets
4. PermissionsPermission modes, Allow and deny rules, Asking your code with can_use_tool, Handling approvals and questions, Turn and budget limits
5. HooksHooks: PreToolUse, Hooks that change a call, The hook events
6. Conversations and sessionsA conversation with ClaudeSDKClient, Resuming a session, Forking a session, Session storage of your own, File checkpointing
7. Shaping the agentSystem prompts, Claude Code features in the SDK, Skills, Commands, Plugins, Subagents, Structured output, Model, thinking and effort
8. Operating itCost and usage, Observability with OpenTelemetry, Todo tracking, Hosting the SDK, Secure deployment
9. The projectThe project and its tools, The project's rules, Running the project

Who this course is for

  • A Python developer who wants an agent in a product, rather than an agent in a terminal, and needs the tool, permission and session machinery to be someone else's problem.
  • Anyone who already uses the Claude Code terminal app and wants the same behaviour driven from code: the same tools, the same loop, decisions made by your program instead of by a person at a prompt.
  • An engineer evaluating agent frameworks, who needs to know what this SDK gives for free and where its boundaries are before committing to it.

What to know first

  • Python 3.10 or newer, including functions, classes and dictionaries.
  • async def and await. Every call into the SDK is asynchronous, and the examples use await and async for at the top level, the way a notebook cell allows. The install lesson shows the two lines a plain .py file needs instead.
  • No API key, no cloud account and no GPU. The install lesson says what ANTHROPIC_API_KEY is for and why no lesson here reads it.
  • Some idea of what an agent is. If the word is new, the next lessons define it before any code runs.

What you will be able to do

  • Start a session with query() and read every message it yields
  • Give an agent your own tools and serve them from an in-process MCP server
  • Decide which tool calls run, which are refused and which come to your code for approval
  • Watch, change and block any step of the loop with hooks
  • Hold a conversation, resume it tomorrow and fork it into a second approach
  • Shape the agent with a system prompt, skills, commands, plugins and subagents
  • Read what a run cost, trace it, host it and deploy it without handing it your filesystem

How a lesson reads

  • A definition first, then why the thing exists, then the build in small pieces with a comment on the parts that are not obvious.
  • Code you can paste. Every runnable block was run against claude-agent-sdk 0.2.157, and the output under it is what that run printed.
  • The installed version wins. Where the documentation and the shipped package disagree, the lesson shows what the package does and names the difference.
  • An ending you can change: two or three small edits to try, so the next run is yours rather than a copy.

The documentation this course follows

Every claim about how the SDK behaves comes from one of these pages, checked while the lesson was written. Keep the first two open alongside the course:

Where this course stops. It builds agents on Claude Code from Python. Driving the Claude Code terminal app by hand is a different job, and the Claude Code course covers that. Calling the Claude API without an agent harness around it is different again, and the lesson on how the SDK compares with the Client SDK says when that is the better choice.
Back toAll frameworks

Every expert started right here.