Registry / llm-agents / claude-agent-sdk

claude-agent-sdk

library0.2.145pypypi✓ verified 26d ago

The Claude Agent SDK for Python provides tools to build and interact with Claude-powered agents. It facilitates agent lifecycle management, tool execution, and advanced prompt configuration. As of version 0.1.58, it is under active development with frequent releases, often including updates to its bundled Claude CLI component.

llm-agents ai-ml

pip install claude-agent-sdk==0.1.58

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · CLAUDE-AGENT-SDK

claude-agent-sdk

llm-agentspythonv0.2.145

Install

7.5s avg

Import

3333ms

Disk

169MB

Pass rate

8/ 10

Env Coverage8 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.1.58 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✓ —

✓ 9.2s

py 3.11

✓ —

✓ 7.6s

py 3.12

✓ —

✓ 6.6s

py 3.13

✓ —

✓ 6.8s

py 3.9

✕ build_error

169MB installed

● package 169MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ClaudeSDKClient

✓ from claude_agent_sdk import ClaudeSDKClient

✗ from claude_agent import ClaudeSDKClient

ClaudeAgentOptions

✓ from claude_agent_sdk import ClaudeAgentOptions

AgentDefinition

✓ from claude_agent_sdk import AgentDefinition

Initializes the ClaudeSDKClient and performs a simple query. It demonstrates asynchronous event streaming and requires the ANTHROPIC_API_KEY environment variable.

import os import asyncio from claude_agent import ClaudeSDKClient async def main(): api_key = os.environ.get('ANTHROPIC_API_KEY') if not api_key: print("Error: ANTHROPIC_API_KEY environment variable not set.") return client = ClaudeSDKClient(api_key=api_key) print("Starting a query...") async with client.query("Hello, Claude!") as result: async for event in result.events(): if event.type == 'tool_call': print(f"Tool Call: {event.tool_name}({event.tool_arguments})") elif event.type == 'message': print(f"Agent Message: {event.text}") print("Query finished.") if __name__ == '__main__': asyncio.run(main())

claude --version

Debug

Known issues

gotchaThe SDK is pre-1.0 and API stability is not guaranteed. Breaking changes, while usually minor, can be introduced in new minor versions (e.g., from 0.1.X to 0.2.Y). Always review release notes when upgrading.

fix

Pin the version in your requirements (e.g., `claude-agent-sdk==0.1.58`) and carefully review release notes before updating. Keep an eye on the official GitHub repository for breaking change announcements.

affects: 0.x.x

gotchaAuthentication requires the `ANTHROPIC_API_KEY` environment variable to be set, or passed directly to `ClaudeSDKClient(api_key=...)`. Without it, the client will fail to connect to the Claude API.

fix

Ensure `export ANTHROPIC_API_KEY='your_api_key'` is run in your shell or the key is provided programmatically. The key format typically starts with 'sk-ant-'.

affects: All versions

gotchaMany SDK methods, including `query()` and related event streams, are asynchronous. They must be awaited within an `async` function and typically run using `asyncio.run()` or within an existing `asyncio` event loop.

fix

Wrap your SDK interactions in `async def` functions and use `await` calls. For top-level execution, use `asyncio.run(your_async_function())`.

affects: All versions

gotchaThe SDK bundles a specific version of the Claude CLI (e.g., v2.1.97 in 0.1.58). This internal dependency means the SDK might behave unexpectedly or require specific CLI functionalities that are only present in its bundled version. External CLI usage or mismatches could cause issues.

fix

Rely on the SDK's internal CLI management where possible. If you are using external Claude CLI tools, ensure their versions are compatible with the SDK's bundled version, or be aware of potential behavioral differences.

affects: All versions

Upgrade

Version history

0.2.145latest on PyPI · released Aug 27, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

47 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/anthropics/claude-agent-sdk-python ↗

packagehttps://pypi.org/project/claude-agent-sdk/ ↗

docshttps://docs.anthropic.com/en/docs/claude-code/sdk ↗