claude-agent-sdk-python

Claude Agent SDK — Python Guide

Production guidance for building AI agents with the Claude Agent SDK in Python.

Naming: The Claude Code SDK was renamed to the Claude Agent SDK (v0.1.0+). Package: pip install claude-agent-sdk · Import: from claude_agent_sdk import ...

Message Types

All message types for type checking and isinstance() checks:

from claude_agent_sdk import (
    AssistantMessage,     # Claude's text/tool responses
    ResultMessage,        # Final result with subtype (success/error/cancelled)
    SystemMessage,        # System events (session_id, etc.)
    UserMessage,          # User prompts
    ToolUseMessage,       # Tool invocation requests
    ToolResultMessage,    # Tool execution results
)

Quick Reference — Two Interaction Modes

1. query() — Stateless, One-Shot

Best for: independent tasks, automation scripts, CI pipelines.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def main():
    async for message in query(
        prompt="Review utils.py for bugs. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],
            permission_mode="acceptEdits",
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")

asyncio.run(main())

2. ClaudeSDKClient — Stateful, Multi-Turn

Best for: conversations, follow-up questions, interactive apps.

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

async with ClaudeSDKClient(
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Write", "Bash"],
        permission_mode="acceptEdits",
    )
) as client:
    await client.query("Analyze the codebase structure")
    async for msg in client.receive_messages():
        print(msg)
    # Continue the conversation with context preserved
    await client.query("Now refactor the largest file you found")
    async for msg in client.receive_messages():
        print(msg)