Skip to main content

Claude Agent SDK for Python

Build powerful AI agents with Claude Code. Create bidirectional conversations, add custom tools, and integrate MCP servers—all with a simple Python SDK.

Get StartedAPI Reference

Quick Start

Get up and running with Claude Agent SDK in minutes

1

Install the package

Install the Claude Agent SDK using pip:
pip install claude-agent-sdk
The SDK requires Python 3.10 or higher and automatically bundles the Claude Code CLI—no separate installation needed.
2

Write your first query

Create a simple Python script to query Claude:
import anyio
from claude_agent_sdk import query

async def main():
    async for message in query(prompt="What is 2 + 2?"):
        print(message)

anyio.run(main)
The query() function provides a simple way to send one-shot requests to Claude.
3

Run your script

Execute your script to see Claude’s response:
python your_script.py
You’ll receive a stream of messages including Claude’s response:
AssistantMessage(content=[TextBlock(text='2 + 2 equals 4')])
ResultMessage(stop_reason='end_turn', total_cost_usd=0.0012)
4

Explore advanced features

Try interactive conversations with ClaudeSDKClient, create custom tools with @tool, or implement hooks for fine-grained control.Check out the interactive conversations guide or browse the examples.

Explore by topic

Jump to the content that matters most to you

Core Concepts

Understand the difference between query() and ClaudeSDKClient, message types, and configuration options

Custom Tools

Create in-process MCP servers with Python functions that Claude can invoke

Hooks System

Customize agent behavior at specific points in the conversation loop

Interactive Conversations

Build bidirectional chat interfaces with ClaudeSDKClient

Permission Controls

Manage tool permissions and implement safety controls

Examples

Real-world code examples demonstrating common patterns

Key features

Everything you need to build production-ready AI agents

Simple Query Function

Use the query() function for one-shot interactions. Perfect for automation scripts and batch processing.

Bidirectional Conversations

ClaudeSDKClient enables interactive, stateful conversations with full control over message flow and interrupts.

In-Process MCP Servers

Create custom tools as Python functions that run in-process. No subprocess management, better performance, easier debugging.

Permission Controls

Fine-grained control over tool execution with permission modes, custom callbacks, and hooks.

Session Management

Track conversation history, checkpoint file states, and rewind to previous points in time.

Type Safety

Comprehensive type definitions for all message types, content blocks, and configuration options.

Ready to build AI agents?

Install the Claude Agent SDK and start building powerful AI applications with Claude Code in minutes.

Get Started

Build docs developers (and LLMs) love

Get started for freeTalk to us