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 →

Installation and setup

claude-agent-sdk is the PyPI package that installs the Agent SDK and, on most platforms, a copy of the Claude Code binary it drives. One install line covers every lesson in this course, and none of them needs an API key.

Last updated: 20 Oct, 2026 · Claude Agent SDK

The Claude Agent SDK overview described what the library does. This lesson gets it onto your machine at the version every page here was run against, and shows the two errors that stop most first installs.

Checking your Python version

The package declares Requires-Python >=3.10, and the documentation's Quickstart names the same floor: Node.js 18+ or Python 3.10+. Older interpreters cannot install it at all. Open a terminal, on Windows PowerShell from the Start menu and on macOS the Terminal app, and ask Python what it is:

python3 --version

Anything from 3.10 up is fine; these pages were run on 3.12. If the command prints 3.9 or lower, or is not found, install a current Python from python.org and tick Add python.exe to PATH in the Windows installer, or take the uv route below, which fetches a suitable Python for the project itself.

Installing claude-agent-sdk

Pick one route. pip into your current interpreter is the shortest. uv makes a project folder with its own environment, so this pin never clashes with other Python work on the same machine. Colab needs no setup beyond the install cell, and every lesson in this course runs there, because none of them starts a real process.

python3 -m pip install "claude-agent-sdk==0.2.157"

What the install brings with it

  • mcp, the Model Context Protocol library. Your own tools are served to Claude through it, which is why the tools part of this course talks about an MCP server running inside your process.
  • anyio and sniffio, the asynchronous plumbing the SDK runs on.
  • jsonschema, which validates a tool's arguments and a structured output against its schema.
  • A Claude Code binary, on most platforms. The agent loop page states that both SDKs bundle a native Claude Code binary, so most installs need no separate Claude Code install. The Quickstart names the exceptions: an install that falls back to the source distribution, for example on ARM64 Windows, has no bundled binary and the SDK looks for claude on your PATH instead.
  • Pinning the version matters. The SDK ships often, and 0.2.157 is what every output on these pages came from. A newer release will add fields and may rename one.

Reading the version check

Save this as check_setup.py and run it with python3 check_setup.py, py check_setup.py or uv run python check_setup.py, or paste it into a notebook cell:

Examplecheck_setup.py, run on the course's own install
import sys
from importlib.metadata import version

import claude_agent_sdk
from claude_agent_sdk._cli_version import __cli_version__

# the installed distribution and the module's own constant should agree
print("python          ", sys.version.split()[0])
print("claude-agent-sdk", version("claude-agent-sdk"))
print("agent sdk       ", claude_agent_sdk.__version__)
print("bundled claude  ", __cli_version__)
  • The two version lines agree. importlib.metadata.version reads the installed distribution and claude_agent_sdk.__version__ reads the module's own constant. A mismatch means two copies of the package on your path.
  • The bundled Claude Code version is separate from the SDK's. It is the binary the SDK starts, and it moves on its own release schedule.
  • _cli_version starts with an underscore, so it is something to read when you are checking an install, not something to build a program on.
  • Nothing here contacted Anthropic. Reading a version number starts no process and spends nothing.

Running an asynchronous example

Every call into the SDK is asynchronous. The examples in this course use await and async for at the top level, which a Jupyter or Colab cell allows. In a plain .py file the same lines are a syntax error:

python
from claude_agent_sdk import query

async for message in query(prompt="Hello"):
    print(message)
bash
$ python3 hello.py
  File "/home/you/hello.py", line 3
    async for message in query(prompt="Hello"):
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
SyntaxError: 'async for' outside async function

The fix is two lines: put the body inside async def main(): and end the file with asyncio.run(main()). Every example in this course works in a file written that way.

python
import asyncio

from claude_agent_sdk import query


async def main():
    # the SDK is asynchronous all the way down, so the body needs a coroutine
    async for message in query(prompt="Hello"):
        print(message)

asyncio.run(main())

That file is correct Python, and it is also the one snippet in this lesson that would reach Anthropic, so it is shown rather than run: without a key and a working Claude Code binary it stops at the error the When the CLI will not start lesson takes apart. From the next part onwards the examples pass a stand-in and run with nothing configured.

Installing a version that does not exist

The other common failure is a pin pip cannot satisfy, whether the version is wrong or your Python is too old for the wheel:

bash
$ python3 -m pip install "claude-agent-sdk==0.2.999"
ERROR: Could not find a version that satisfies the requirement claude-agent-sdk==0.2.999
  (from versions: 0.0.23, 0.1.0, ... 0.2.167, 0.2.168)
ERROR: No matching distribution found for claude-agent-sdk==0.2.999

Read the version list in the brackets. If it holds the pin you asked for, your Python is too old for that wheel and the floor above is the fix. If it stops short of the pin, the version does not exist and the list tells you what does.

What <code>ANTHROPIC_API_KEY</code> is for

A real run costs money, and the Claude Code process the SDK starts needs credentials for it. The Quickstart says to get a key from the Claude Console and set it in the shell that runs your program, and states that the SDK reads the key from the environment of the process that runs your agent; it does not load .env files automatically. If you keep the key in a file, load it yourself before calling the SDK.

Setting the key, if you want a real runOptional

export ANTHROPIC_API_KEY=your-api-key

No lesson in this course needs it. The runnable examples hand the SDK a stand-in for the Claude Code process, so there is nothing to authenticate against and nothing to pay for. The Quickstart also lists four other routes for teams that already buy Claude elsewhere: Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform and Microsoft Foundry, each turned on with its own environment variable.

pip against uv for this course

pipuv
Where the package landsThe interpreter you ran pip withA .venv inside the project folder
Python versionWhatever is already installedFetched and pinned per project
Exact versions recordedOnly what you typeduv.lock, which you can commit
Clash with other workPossible: one set of versions for everythingNone, the environment belongs to the project
Running a lessonpython3 agent.pyuv run python agent.py

Where the install choice matters

  • Following this course on a work laptop, where another project pins a different mcp and the two cannot both win.
  • Shipping an agent in a container, where the bundled binary has to match the image's architecture. The hosting lesson comes back to this.
  • Working in Colab, where there is no terminal to install Claude Code into and the bundled binary is the only one you get.
Watch out. Installing with a bare pip while running code with a different interpreter is the most common setup failure, and it reads like a library bug: the install says it succeeded and the import still fails. Always install with python3 -m pip or py -m pip, so the install and the run use the same Python.
Try it yourself
  • Run python3 -m pip show claude-agent-sdk and find mcp in its Requires line.
  • Print claude_agent_sdk.__file__ and look for the bundled binary in a folder beside it.
  • Save the four-line snippet above as hello.py, run it, and read the SyntaxError. Then wrap it in async def main() and run it again to see the error change.
PreviousClaude Agent SDK overview

Little by little, you're building something great.