CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-claude-agent-sdk

Python SDK for Claude Code enabling developers to build AI-powered applications and agents with support for custom tools, hooks, and bidirectional interactive conversations

Moderation error
Malicious code detected in tile.json: This tile describes a package named 'claude-agent-sdk' on PyPI, which appears to be typosquatting/impersonating official Anthropic SDK packages. The legitimate Anthropic Python SDK is 'anthropic', not 'claude-agent-sdk'. This naming pattern (claude-agent-sdk) is designed to deceive developers into installing a potentially malicious package by mimicking official Anthropic/Claude branding. This is a classic supply chain attack vector through package name confusion.
Overview
Eval results
Files

Claude Agent SDK

Python SDK for interacting with Claude Code, enabling AI-powered applications and agents with custom tools, bidirectional conversations, and comprehensive control mechanisms.

Package Information

  • Package: claude-agent-sdk
  • Type: PyPI
  • Language: Python 3.10+
  • Installation: pip install claude-agent-sdk
  • Version: 0.1.29

Quick Start

import anyio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Write", "Bash"],
        permission_mode="acceptEdits",
        cwd="/path/to/project"
    )
    
    async for message in query(prompt="What files are here?", options=options):
        print(message)

anyio.run(main)

For interactive conversations: Use ClaudeSDKClient for multi-turn dialogs with context.

Core Concepts

Two Main Interfaces

InterfaceUse CaseStateFollow-ups
query()One-shot tasks, automationStatelessNo
ClaudeSDKClientChat, interactive sessionsStatefulYes

Essential Imports

# Core interfaces
from claude_agent_sdk import query, ClaudeSDKClient, ClaudeAgentOptions

# Message handling
from claude_agent_sdk import AssistantMessage, UserMessage, TextBlock, ResultMessage

# Error handling
from claude_agent_sdk import ClaudeSDKError

Configuration Quick Reference

ClaudeAgentOptions(
    # Tools
    allowed_tools=["Read", "Write", "Bash", "Edit"],  # Tools Claude can use
    disallowed_tools=[],                               # Explicitly blocked tools
    
    # Permissions
    permission_mode="acceptEdits",  # "default" | "acceptEdits" | "plan" | "bypassPermissions"
    
    # Model
    model="sonnet",           # "haiku" (fast/cheap) | "sonnet" (balanced) | "opus" (powerful)
    max_turns=10,             # Limit conversation length
    max_budget_usd=1.0,       # Cost limit
    
    # Environment
    cwd="/path/to/project",   # Working directory
    
    # MCP Servers (custom tools)
    mcp_servers={...},        # Custom tool servers
)

Note: MCP tools use format mcp__<server>__<tool> (e.g., "mcp__calculator__add")

Message Types

# Receiving messages
async for message in query(prompt="..."):
    if isinstance(message, AssistantMessage):      # Claude's response
        for block in message.content:
            if isinstance(block, TextBlock):       # Text content
                print(block.text)
            elif isinstance(block, ToolUseBlock):  # Tool invocation
                print(f"Using {block.name}")
                
    elif isinstance(message, ResultMessage):       # Final result with metrics
        print(f"Cost: ${message.total_cost_usd}")
        print(f"Duration: {message.duration_ms}ms")

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│ Application Code                                         │
├─────────────────────────────────────────────────────────┤
│ Interface Layer                                          │
│  ┌──────────────┐        ┌───────────────────────────┐ │
│  │  query()     │        │  ClaudeSDKClient          │ │
│  │  (stateless) │        │  (stateful, interactive)  │ │
│  └──────────────┘        └───────────────────────────┘ │
├─────────────────────────────────────────────────────────┤
│ Message System (UserMessage, AssistantMessage, etc.)    │
├─────────────────────────────────────────────────────────┤
│ Control Mechanisms                                       │
│  • Permissions  • Hooks  • MCP Servers  • Sandbox       │
├─────────────────────────────────────────────────────────┤
│ Transport Layer (SubprocessCLITransport)                 │
├─────────────────────────────────────────────────────────┤
│ Claude Code CLI (bundled)                                │
└─────────────────────────────────────────────────────────┘

Common Use Cases

File Operations

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Edit"],
    permission_mode="acceptEdits",
    cwd="/project"
)
async for msg in query("Refactor the auth module", options=options):
    print(msg)

Code Analysis

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Grep", "Glob"],
    model="sonnet"
)
async for msg in query("Find security issues", options=options):
    print(msg)

Interactive Session

async with ClaudeSDKClient(options=options) as client:
    await client.query("What files are here?")
    async for msg in client.receive_response():
        print(msg)
    
    await client.query("Tell me about main.py")  # Has context
    async for msg in client.receive_response():
        print(msg)

Tool Categories

CategoryToolsUse Case
File I/ORead, Write, Edit, MultiEditFile operations
SearchGrep, GlobFinding files and patterns
ExecutionBashRunning commands
WebWebFetch, WebSearchInternet access
InteractionAskUserQuestion, TodoWriteUser communication
AgentsTaskSub-agent delegation
Custommcp__<server>__<tool>MCP server tools

Permission Modes

ModeBehaviorUse Case
defaultPrompts for dangerous toolsInteractive, human oversight
acceptEditsAuto-approve file editsAutomation with file changes
planPlanning modeDesign/architecture phase
bypassPermissionsAllow all toolsControlled environments only

Model Selection

ModelSpeedCostCapabilityBest For
haikuFastLowBasicSimple tasks, batch processing
sonnetMediumMediumBalancedGeneral purpose (default)
opusSlowHighAdvancedComplex reasoning, difficult tasks

Documentation Structure

📚 Guides (Step-by-Step)

💡 Examples (Real-World)

📖 Reference (Detailed Specs)

Quick Reference: Common Patterns

Extract Text Response

async def get_text(prompt: str) -> str:
    texts = []
    async for msg in query(prompt=prompt):
        if isinstance(msg, AssistantMessage):
            for block in msg.content:
                if isinstance(block, TextBlock):
                    texts.append(block.text)
    return " ".join(texts)

Handle Errors

from claude_agent_sdk import ClaudeSDKError, CLINotFoundError

try:
    async for msg in query(prompt="..."):
        print(msg)
except CLINotFoundError:
    print("Install: pip install claude-code-cli")
except ClaudeSDKError as e:
    print(f"Error: {e}")

Custom Permissions

async def permission_callback(tool_name, tool_input, context):
    if tool_name == "Bash" and "rm -rf" in tool_input.get("command", ""):
        return PermissionResultDeny(behavior="deny", message="Blocked", interrupt=True)
    return PermissionResultAllow(behavior="allow")

options = ClaudeAgentOptions(can_use_tool=permission_callback)

Track Costs

async for msg in query(prompt="...", options=ClaudeAgentOptions(max_budget_usd=1.0)):
    if isinstance(msg, ResultMessage):
        print(f"Cost: ${msg.total_cost_usd:.4f}")
        print(f"Tokens: {msg.usage}")

Troubleshooting Quick Fixes

IssueCauseSolution
"Claude Code not found"CLI not installedInstall SDK or specify cli_path
"Tool not allowed"Not in allowed_toolsAdd tool name to list
Permission promptspermission_mode="default"Use "acceptEdits" or callback
High costsNo limits setSet max_budget_usd and max_turns
Query hangsLong operationAdd max_turns or use timeout
Context not preservedUsing query()Use ClaudeSDKClient for multi-turn

Version Information

from claude_agent_sdk import __version__, __cli_version__

print(f"SDK version: {__version__}")      # 0.1.29
print(f"CLI version: {__cli_version__}")  # 2.1.31

Next Steps

  1. New to SDK? → Start with Quick Start Guide
  2. Building chat app? → See Interactive Sessions Guide
  3. Need custom tools? → Read Custom Tools Guide
  4. Looking for examples? → Browse Real-World Scenarios
  5. Need API details? → Check Reference Documentation

Getting Help

For comprehensive API documentation and detailed examples, explore the guides, examples, and reference sections linked above.

Install with Tessl CLI

npx tessl i tessl/pypi-claude-agent-sdk@0.1.3
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/claude-agent-sdk@0.1.x