claude-agent-sdk

Claude Agent SDK

The Agent SDK provides Claude with autonomous tool execution. Unlike the Messages API where you implement the tool loop, agents execute tools automatically.

Quick Start

Python:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Find and fix the bug in auth.py",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"])
    ):
        print(message)

asyncio.run(main())

TypeScript:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Find and fix the bug in auth.py",
  options: { allowedTools: ["Read", "Edit", "Bash"] }
})) {
  console.log(message);
}

When to Use Agent SDK vs Messages API

Scenario	Use
Autonomous multi-step tasks	Agent SDK
File operations, code editing	Agent SDK
Simple Q&A, text generation	Messages API
Custom tool execution control	Messages API
Browser automation, web tasks	Agent SDK

Core APIs

query() - One-off Tasks

Creates new session each time. Best for independent tasks.

async for message in query(
    prompt="Your task here",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Write", "Edit", "Bash"],
        permission_mode="acceptEdits"  # Auto-approve edits
    )
):
    if hasattr(message, 'result'):
        print(message.result)

ClaudeSDKClient - Conversations

Maintains context across exchanges. Use for interactive applications.

async with ClaudeSDKClient(options=options) as client:
    await client.connect()                    # Establish connection
    await client.query("Read the auth module")
    async for msg in client.receive_messages():  # Stream all messages
        print(msg)

    await client.query("Now refactor it")     # Remembers context
    async for msg in client.receive_messages():
        print(msg)

    await client.interrupt()                  # Cancel current operation
    await client.rewind_files()               # Restore file checkpoints
    status = await client.get_mcp_status()    # Check MCP server status
    await client.disconnect()                 # Clean up