Agent SDK Reference

The Claude Agent SDK provides a Python framework for building autonomous AI agents with the same capabilities as Claude Code.

Installation

uv add claude-agent-sdk  # Requires Python 3.10+

Quick Start

from claude_agent_sdk import query
import anyio

async def main():
    async for msg in query("Analyze this codebase"):
        print(msg)

anyio.run(main())

Stateful Client

For multi-turn conversations:

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
import anyio

async def main():
    options = ClaudeAgentOptions(
        model="claude-opus-4-5",
        allowed_tools=["Read", "Write", "Edit", "Bash"],
        permission_mode="ask"
    )

    async with ClaudeSDKClient(options) as client:
        await client.query("Read the config file")
        async for msg in client.receive_response():
            print(msg)

        await client.query("Explain what you found")
        async for msg in client.receive_response():
            print(msg)

anyio.run(main())

Configuration Options

Option	Type	Description
`model`	string	Model ID (e.g., `claude-opus-4-5`)
`system_prompt`	string	Custom system prompt
`setting_sources`	array	`["local", "project", "user"]` - loads `.claude/settings.json`
`permission_mode`	string	`"allow"`, `"deny"`, `"ask"`, `"bypass"`
`allowed_tools`	array	Tools to enable (e.g., `["Read", "Write"]`)
`mcp_servers`	object	MCP server configurations
`max_tokens`	number	Maximum response tokens

Custom MCP Tools

from claude_agent_sdk import tool, create_sdk_mcp_server

@tool("multiply", "Multiply two numbers", {"a": float, "b": float})
async def multiply_tool(args: dict) -> dict:
    return {
        "content": [{"type": "text", "text": f"Result: {args['a'] * args['b']}"}]
    }

calculator = create_sdk_mcp_server(
    name="calculator",
    version="1.0.0",
    tools=[multiply_tool]
)

options = ClaudeAgentOptions(
    mcp_servers={"calc": calculator},
    allowed_tools=["mcp__calc__multiply"]
)

Tool return format: { "content": [{"type": "text", "text": "result"}], "is_error": false }

Platform Support

# Anthropic API (default)
export ANTHROPIC_API_KEY="your-key"

# AWS Bedrock
export CLAUDE_CODE_USE_BEDROCK=1

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1