Agent SDK reference - Python - Claude Code Docs

Installation

Install the package into a virtual environment. On recent Debian, Ubuntu, and Homebrew Python installs, running pip install against system Python fails with error: externally-managed-environment.

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

For uv, Windows PowerShell, and API key setup, see Setup in the Agent SDK quickstart.

Choosing between `query()` and `ClaudeSDKClient`

The Python SDK provides two ways to interact with Claude Code:

Feature	`query()`	`ClaudeSDKClient`
Session	Creates a new session by default	Reuses same session
Conversation	Single exchange	Multiple exchanges in same context
Connection	Managed automatically	Manual control
Streaming Input	✅ Supported	✅ Supported
Interrupts	❌ Not supported	✅ Supported
Hooks	✅ Supported	✅ Supported
Custom Tools	✅ Supported	✅ Supported
Continue Chat	Manual via `continue_conversation` or `resume`	✅ Automatic
Use Case	One-off tasks	Continuous conversations

Use ClaudeSDKClient for interactive applications such as chat interfaces, or when the next action depends on Claude’s response.

Functions

Signature blocks and bare async for / async with fragments on this page are illustrative. To run them, wrap the body in async def main(): ... and call asyncio.run(main()).

`query()`

Creates a new session for each interaction with Claude Code by default. Returns an async iterator that yields messages as they arrive. Each call to query() starts fresh with no memory of previous interactions unless you pass continue_conversation=True or resume in ClaudeAgentOptions. See Sessions.

async def query(
    *,
    prompt: str | AsyncIterable[dict[str, Any]],
    options: ClaudeAgentOptions | None = None,
    transport: Transport | None = None
) -> AsyncIterator[Message]

Parameters

Parameter	Type	Description
`prompt`	`str \| AsyncIterable[dict]`	The input prompt as a string or async iterable for streaming mode
`options`	`ClaudeAgentOptions \| None`	Optional configuration object (defaults to `ClaudeAgentOptions()` if None)
`transport`	`Transport \| None`	Optional custom transport for communicating with the CLI process

Returns

Returns an AsyncIterator[Message] that yields messages from the conversation.

Example - With options

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    options = ClaudeAgentOptions(
        system_prompt="You are an expert Python developer",
        permission_mode="acceptEdits",
    )

    async for message in query(prompt="Create a Python web server", options=options):
        print(message)


asyncio.run(main())

`tool()`

Decorator for defining MCP tools with type safety.

def tool(
    name: str,
    description: str,
    input_schema: type | dict[str, Any],
    annotations: ToolAnnotations | None = None
) -> Callable[[Callable[[Any], Awaitable[dict[str, Any]]]], SdkMcpTool[Any]]

Parameters

Parameter	Type	Description
`name`	`str`	Unique identifier for the tool
`description`	`str`	Human-readable description of what the tool does
`input_schema`	`type \| dict[str, Any]`	Schema defining the tool’s input parameters (see below)
`annotations`	`ToolAnnotations` `\| None`	Optional MCP tool annotations providing behavioral hints to clients

Input schema options

Simple type mapping (recommended):

{"text": str, "count": int, "enabled": bool}

JSON Schema format (for complex validation):

{
    "type": "object",
    "properties": {
        "text": {"type": "string"},
        "count": {"type": "integer", "minimum": 0},
    },
    "required": ["text"],
}

Returns

A decorator function that wraps the tool implementation and returns an SdkMcpTool instance.

Example

from claude_agent_sdk import tool
from typing import Any


@tool("greet", "Greet a user", {"name": str})
async def greet(args: dict[str, Any]) -> dict[str, Any]:
    return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]}

`ToolAnnotations`

Re-exported from mcp.types (also available as from claude_agent_sdk import ToolAnnotations). All fields are optional hints; clients should not rely on them for security decisions.

Field	Type	Default	Description
`title`	`str \| None`	`None`	Human-readable title for the tool
`readOnlyHint`	`bool \| None`	`False`	If `True`, the tool does not modify its environment
`destructiveHint`	`bool \| None`	`True`	If `True`, the tool may perform destructive updates (only meaningful when `readOnlyHint` is `False`)
`idempotentHint`	`bool \| None`	`False`	If `True`, repeated calls with the same arguments have no additional effect (only meaningful when `readOnlyHint` is `False`)
`openWorldHint`	`bool \| None`	`True`	If `True`, the tool interacts with external entities (for example, web search). If `False`, the tool’s domain is closed (for example, a memory tool)

from claude_agent_sdk import tool, ToolAnnotations
from typing import Any


@tool(
    "search",
    "Search the web",
    {"query": str},
    annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
)
async def search(args: dict[str, Any]) -> dict[str, Any]:
    return {"content": [{"type": "text", "text": f"Results for: {args['query']}"}]}

`create_sdk_mcp_server()`

Create an in-process MCP server that runs within your Python application.

def create_sdk_mcp_server(

Agent SDK

Build agents

Core concepts

Input and output

Extend with tools

Customize behavior

Control and observability

Deployment

SDK references

Agent SDK reference - Python

Installation

Choosing between `query()` and `ClaudeSDKClient`

Functions

`query()`

Parameters

Returns

Example - With options

`tool()`

Parameters

Input schema options

Returns

Example

`ToolAnnotations`

`create_sdk_mcp_server()`

​Installation

​Choosing between query() and ClaudeSDKClient

​Functions

​query()

​Parameters

​Returns

​Example - With options

​tool()

​Parameters

​Input schema options

​Returns

​Example

​ToolAnnotations

​create_sdk_mcp_server()

Installation

Choosing between `query()` and `ClaudeSDKClient`

Functions

`query()`

Parameters

Returns

Example - With options

`tool()`

Parameters

Input schema options

Returns

Example

`ToolAnnotations`

`create_sdk_mcp_server()`