Python SDK reference

This is the full reference for the claude-agent-sdk Python package. It is organised so you can jump to what you need: functions first, then the client class, then options, messages, errors, hooks, tool schemas and sandbox settings. Task-focused guides live on the other Agent SDK pages and are linked throughout.

Note: Fragments on this page that use async for or await at top level are illustrative. Wrap them in async def main(): ... and call asyncio.run(main()) to run them.

Installing

System Python on recent Debian, Ubuntu and Homebrew installs refuses pip install with error: externally-managed-environment, so use a virtual environment:

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

The quickstart covers uv, Windows PowerShell and API key setup.

query() or ClaudeSDKClient?

Functions

query()

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

Returns an async iterator of Message objects. Each call starts a fresh session unless continue_conversation=True or resume is set. See sessions.

from claude_agent_sdk import query, ClaudeAgentOptions

opts = ClaudeAgentOptions(system_prompt="You are a careful Django reviewer.", permission_mode="plan")
async for msg in query(prompt="Review the views in orders/ for N+1 queries", options=opts):
    print(msg)

tool()

Decorator that turns an async function into an in-process MCP tool.

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]]

The schema can take three forms:

In the mapping and TypedDict forms, Annotated[type, "description"] sets a field description.

from typing import Annotated, Any, NotRequired, TypedDict
from claude_agent_sdk import tool

class StockArgs(TypedDict):
    sku: Annotated[str, "Product SKU, e.g. TEA-EB-250"]
    warehouse: NotRequired[Annotated[str, "Warehouse code; defaults to MAN"]]

@tool("check_stock", "Return units on hand for a SKU", StockArgs)
async def check_stock(args: dict[str, Any]) -> dict[str, Any]:
    wh = args.get("warehouse", "MAN")
    units = await inventory.lookup(args["sku"], wh)
    return {"content": [{"type": "text", "text": f"{units} units of {args['sku']} at {wh}"}]}

The handler returns a dict with a content list of MCP content blocks. More in custom tools.

ToolAnnotations

Optional hints passed as annotations. It extends the MCP SDK's mcp.types.ToolAnnotations with maxResultSizeChars. You can write hints in camelCase or snake_case (readOnlyHint=True or read_only_hint=True). When reading back, use the spelling your installed mcp package declares (.readOnlyHint on mcp 1.x, .read_only_hint on 2.x); .maxResultSizeChars works on both. A plain mcp.types.ToolAnnotations is accepted too.

Snake_case names and the typed maxResultSizeChars need SDK 0.2.140+. Versions 0.1.31 to 0.2.139 re-export the MCP class unchanged; from 0.1.55 you can still pass maxResultSizeChars as a keyword and it is forwarded. Hints are advisory and must not be relied on for security.

create_sdk_mcp_server()

def create_sdk_mcp_server(
    name: str,
    version: str = "1.0.0",
    tools: list[SdkMcpTool[Any]] | None = None,
) -> McpSdkServerConfig

Bundles decorated tools into a server that runs inside your process. Register it in mcp_servers; tool names become mcp__<key>__<tool>.

from claude_agent_sdk import create_sdk_mcp_server, ClaudeAgentOptions

warehouse = create_sdk_mcp_server("warehouse", "1.2.0", tools=[check_stock])
opts = ClaudeAgentOptions(
    mcp_servers={"wh": warehouse},
    allowed_tools=["mcp__wh__check_stock"],
)

Session helpers

These are synchronous and read transcripts from disk.

Notes:

• Omitting directory searches every project.
• include_worktrees includes sessions from all worktrees when directory is inside a git repo.
• rename_session and tag_session append entries, so repeat calls are safe and the latest wins. Pass tag=None to clear. Both raise ValueError for a non-UUID ID or an empty title or tag (tags are Unicode-sanitised first) and FileNotFoundError if the session is missing.

SDKSessionInfo

SessionMessage

from claude_agent_sdk import list_sessions, tag_session

for s in list_sessions(directory="/srv/repos/storefront", limit=20):
    if "refund" in (s.first_prompt or "").lower():
        tag_session(s.session_id, "billing")

ClaudeSDKClient

Holds one conversation open across many exchanges. It is what you reach for in chat interfaces.

Use it as an async context manager to connect and disconnect automatically:

from claude_agent_sdk import ClaudeSDKClient, AssistantMessage, TextBlock

async with ClaudeSDKClient() as client:
    await client.query("Which module in this repo handles VAT?")
    async for m in client.receive_response():
        if isinstance(m, AssistantMessage):
            print("".join(b.text for b in m.content if isinstance(b, TextBlock)))

    await client.query("Does it handle the reverse charge for EU B2B sales?")
    async for m in client.receive_response():
        ...

Warning: Avoid break inside these loops: it can cause asyncio clean-up problems. Let the loop finish, or set a flag.

Streaming input with the client

client.query() accepts an async iterable of user message dicts, useful for building content at send time or attaching images. Claude starts replying to the first yielded message straight away, and receive_response() stops at the result for that reply, so put everything Claude needs into one message and pair each query() with its own receive_response() loop.

async def build_prompt():
    readings = await sensors.latest()
    yield {"type": "user", "message": {"role": "user",
           "content": f"Spot anomalies in these readings: {readings}"}}

async with ClaudeSDKClient() as client:
    await client.query(build_prompt())
    async for m in client.receive_response():
        ...

Interrupting

async with ClaudeSDKClient(ClaudeAgentOptions(allowed_tools=["Bash"])) as client:
    await client.query("Run the full integration suite")
    await asyncio.sleep(5)
    await client.interrupt()

    async for m in client.receive_response():      # drain the interrupted turn
        if isinstance(m, ResultMessage):
            print(m.terminal_reason)               # "aborted_streaming" or "aborted_tools"

    await client.query("Just run tests/unit instead")
    async for m in client.receive_response():
        ...

interrupt() does not clear the buffer. The interrupted turn's messages, including its ResultMessage, are still waiting. Drain them before reading the next reply, or you will read the old turn's output by mistake.

Custom permission logic

from claude_agent_sdk.types import PermissionResultAllow, PermissionResultDeny, ToolPermissionContext

async def gatekeeper(tool_name: str, data: dict, ctx: ToolPermissionContext):
    path = data.get("file_path", "")
    if tool_name in ("Write", "Edit") and path.startswith("/srv/releases/"):
        return PermissionResultDeny(message="Release artefacts are read-only", interrupt=True)
    if tool_name == "Write" and path.endswith(".env"):
        return PermissionResultAllow(updated_input={**data, "file_path": path + ".example"})
    return PermissionResultAllow(updated_input=data)

opts = ClaudeAgentOptions(can_use_tool=gatekeeper)

Do not also list gated tools in allowed_tools: allow rules approve calls before can_use_tool is ever consulted. See permissions.

Types: dataclass or TypedDict?

The SDK uses both, and it matters at runtime:

• Dataclasses (ResultMessage, AgentDefinition, TextBlock, ...) are objects. Use attributes: msg.result.
• TypedDicts (ThinkingConfigEnabled, McpStdioServerConfig, SyncHookJSONOutput, ...) are plain dicts. Use keys: cfg["budget_tokens"].

ClassName(field=value) works for both, but only dataclasses give you attributes.

ClaudeAgentOptions

Tools and permissions

Prompt, model and reasoning

Limits

Sessions

Environment and process

Configuration sources and extensions

Stream shape

Timeouts for slow APIs

Pass these through env:

With include_partial_messages on, a gateway that holds a response open with keep-alives produces ping StreamEvents; treat them as signs of life (before v2.1.257 they stopped after five minutes).

Settings sources

SettingSource = Literal["user", "project", "local"]

When setting_sources is unset and skills is unset, query() loads all three, like the CLI. Endpoint-managed policy always loads; server-managed settings are fetched when authenticating with an organisation credential on an eligible configuration. Claude Code features in the SDK lists inputs that load regardless.

Precedence, highest first: local, project, user. Programmatic options (agents, allowed_tools, settings) beat all three; managed policy beats programmatic options.

CLAUDE.md loads with the project source. setting_sources=[] is the right choice for SDK-only apps that define everything in code.

Note: In Python SDK 0.1.59 and earlier, an empty list behaved like None and did not disable anything. Upgrade if you rely on [].

System prompt types

• exclude_dynamic_sections moves per-user context such as the auto memory location into the first user message so the prompt caches across users.
• snapshot: False rebuilds the prompt every request instead of reusing the one recorded on the first request (SDK 0.2.153+).
• String and custom prompts travel as a command-line argument. On Linux a single argument over roughly 128 KB fails with Argument list too long; on Windows the whole command line is capped near 32 KB. Use the file form for big prompts.

Details in modifying system prompts.

AgentDefinition

@dataclass
class AgentDefinition:
    description: str
    prompt: str
    tools: list[str] | None = None
    disallowedTools: list[str] | None = None
    model: str | None = None
    skills: list[str] | None = None
    memory: Literal["user", "project", "local"] | None = None
    mcpServers: list[str | dict[str, Any]] | None = None
    initialPrompt: str | None = None
    maxTurns: int | None = None
    background: bool | None = None
    effort: EffortLevel | int | None = None
    permissionMode: PermissionMode | None = None

Warning: These field names are camelCase to match the wire format, unlike the snake_case ClaudeAgentOptions. Passing max_turns= raises a TypeError. There is no omitClaudeMd field in Python; that is TypeScript-only. See subagents.

Enumerations

PermissionMode = Literal["default", "acceptEdits", "plan", "dontAsk", "bypassPermissions", "auto"]
EffortLevel = Literal["low", "medium", "high", "xhigh", "max"]   # xhigh falls back to high where unsupported
SdkBeta = Literal["context-1m-2025-08-07"]

Warning: On the Claude API the context-1m-2025-08-07 beta is retired for Sonnet 4.5 and Sonnet 4; passing it with those models makes over-200K requests fail. For a 1M window, use a model that has it by default, such as claude-sonnet-5-5 or claude-opus-5-5, or append [1m] to a model that offers a 1M variant, such as claude-opus-4-6[1m].

ThinkingConfig

Three TypedDict variants (plain dicts at runtime):

display is "summarized" or "omitted". On Opus 4.7 and later the API defaults to "omitted", so set "summarized" to get text in ThinkingBlocks. Some providers (Amazon Bedrock, Google Cloud's Agent Platform) do not receive your display, so Opus 4.7+ thinking blocks come back empty there regardless.

ClaudeAgentOptions(thinking={"type": "enabled", "budget_tokens": 16000, "display": "summarized"})

Other small types

Permission callback types

CanUseTool = Callable[[str, dict[str, Any], ToolPermissionContext], Awaitable[PermissionResult]]
PermissionResult = PermissionResultAllow | PermissionResultDeny

The callback stands in for the interactive prompt and runs only when the evaluation flow reaches one. For a check on every call, use a PreToolUse hook.

ToolPermissionContext

PermissionResultAllow: behavior="allow", updated_input: dict | None, updated_permissions: list[PermissionUpdate] | None.

PermissionResultDeny: behavior="deny", message: str = "", interrupt: bool = False (stop the whole turn).

PermissionUpdate

MCP configuration types

McpServerConfig = McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig

Status types

get_mcp_status() returns McpStatusResponse: {"mcpServers": list[McpServerStatus]}.

ContextUsageResponse

What get_context_usage() returns: the same payload as /context, including display fields such as color and gridRows. Building it makes several token-counting API requests that do not appear in the stream (not billed on the Anthropic API).

deferredBuiltinTools, systemTools and systemPromptSections are declared but left unset.

Messages

Message = UserMessage | AssistantMessage | SystemMessage | ResultMessage | StreamEvent | RateLimitEvent | ConversationResetMessage

UserMessage

For results from an external MCP server that contain resource_link blocks, tool_use_result has a resourceLinks list (SDK 0.2.150+, Claude Code 2.1.257+). Claude sees each link as a line of text; read resourceLinks to render them. Absent when there are no links and on subagent results; capped at 50 links or 64 KiB of JSON. In-process tool() tools never produce it, because their links are flattened to text.

AssistantMessage

AssistantMessageError lists authentication_failed, billing_error, rate_limit, invalid_request, server_error and unknown, but the CLI can emit others such as max_output_tokens. Treat unlisted values like unknown.

SystemMessage

subtype: str and data: dict. Subtypes without their own class arrive as this. With CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS=1, read data["state"] on session_state_changed messages. Those can arrive after a result, so use receive_messages() rather than receive_response() to see them.

ResultMessage

The final message of a query() (or of each turn in streaming input mode).

Fields that do not apply to a subtype are None.

usage keys: input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens. Subagents are excluded, so prefer model_usage.

model_usage covers the main loop, subagents, compaction and Workflow agents; helper calls outside that pipeline (the permission classifier, token counting) are excluded. It is cumulative across turns in streaming mode and includes restored totals on resume. Each value is a ModelUsage (from claude_agent_sdk.types import ModelUsage) with camelCase keys:

StreamEvent

Only with include_partial_messages=True. Import from claude_agent_sdk.types. Fields: uuid, session_id, event (the raw API stream event) and parent_tool_use_id, which is always None because stream events are main-session only.

RateLimitEvent and RateLimitInfo

Emitted when rate-limit status changes. rate_limit_info carries:

ConversationResetMessage

Emitted when the conversation is replaced without disconnecting, for example after /clear (SDK 0.2.137+). Fields: new_conversation_id (opaque, not the next session_id), uuid, and session_id (the session that was reset). Messages afterwards carry a new session_id.

Background task messages

A background task is a backgrounded Bash command, a Monitor watch, a subagent or a remote agent. (Nothing to do with the old Task tool name.)

All three subclass SystemMessage and include uuid and session_id. TaskUsage is {"total_tokens", "tool_uses", "duration_ms"}.

When the CLI backgrounds a long MCP tool call, the tool result holds a placeholder and the real result comes in the completed notification, with a resource_links list in message.data (SDK 0.2.150+, Claude Code 2.1.257+). Match it to the call by tool_use_id.

Content blocks

ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock | ServerToolUseBlock | ServerToolResultBlock

Errors

ResultError attributes: subtype, errors (list, possibly empty), result, api_error_status, terminal_reason, session_id, data (raw payload). Check terminal_reason before subtype: a failed final request such as an API error comes through with subtype="success" and terminal_reason="api_error", while your own limits produce error_* subtypes.

from claude_agent_sdk import query, CLINotFoundError, ResultError, ProcessError, CLIJSONDecodeError

try:
    async for m in query(prompt="Tidy the README"):
        ...
except CLINotFoundError:
    print("Claude Code missing: pip install --force-reinstall claude-agent-sdk")
except ResultError as e:                 # before ProcessError
    print("Run failed:", e.terminal_reason or e.subtype, e)
except ProcessError as e:
    print("Process exited", e.exit_code)
except CLIJSONDecodeError as e:
    print("Bad output line:", e.line)

The troubleshooting page maps each error message to a fix.

Hook types

Full guide: hooks in the SDK.

HookEvent = Literal["PreToolUse", "PostToolUse", "PostToolUseFailure", "UserPromptSubmit",
                    "Stop", "SubagentStop", "PreCompact", "Notification",
                    "SubagentStart", "PermissionRequest"]

HookCallback = Callable[[HookInput, str | None, HookContext], Awaitable[HookJSONOutput]]

TypeScript supports many more events. SessionStart and SessionEnd are only available to Python as shell hooks in settings files.

HookMatcher: matcher: str | None (tool name or pattern such as "Write|Edit"), hooks: list[HookCallback], timeout: float | None in seconds (defaults per event: 600 for most, 30 for UserPromptSubmit).

HookContext: {"signal": None}, reserved.

Hook inputs

Every input includes session_id, transcript_path, cwd and optionally permission_mode, plus hook_event_name.

is_interrupt is true when the failure reached Claude Code as an abort rather than a tool-reported error. Cancelling a tool with interrupt() does not fire this hook at all.

Hook outputs

HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput

SyncHookJSONOutput

hookSpecificOutput by event (always include hookEventName):

AsyncHookJSONOutput: async_: True (sent as async) and optional asyncTimeout in milliseconds.

async def block_force_push(data, tool_use_id, ctx):
    cmd = data["tool_input"].get("command", "")
    if "git push" in cmd and ("--force" in cmd or " -f" in cmd):
        return {"hookSpecificOutput": {"hookEventName": "PreToolUse",
                "permissionDecision": "deny",
                "permissionDecisionReason": "Force pushes are not allowed from agents"}}
    return {}

opts = ClaudeAgentOptions(hooks={"PreToolUse": [HookMatcher(matcher="Bash", hooks=[block_force_push], timeout=60)]})

Built-in tool schemas

The Python SDK does not export types for these, but this is the shape of tool_use input and of UserMessage.tool_use_result output for each tool. Keys appear exactly as Claude Code emits them; optional keys are omitted when they do not apply.

Agent

Name Agent (Task accepted as an alias; the init message's tools list still says Task).

Output is discriminated on status:

• completed: agentId, agentType, content (text blocks with optional citations), resolvedModel (Claude Code 2.1.174+), modelsUsed (only set when the model was swapped mid-run), totalToolUseCount, totalDurationMs, totalTokens and usage (both from the final API request, not the whole run), toolStats (readCount, searchCount, bashCount, editFileCount, linesAdded, linesRemoved, otherToolCount, frameCount), prompt, and worktreePath / worktreeBranch if a worktree was kept. usage includes output_tokens_details.thinking_tokens (SDK 0.2.136+) and fallback_credit (SDK 0.2.162+).
• async_launched: isAsync, agentId, description, resolvedModel (at the backgrounding point), modelsUsed, prompt, outputFile, canReadOutputFile.
• remote_launched: taskId, sessionUrl, description, prompt, outputFile.

AskUserQuestion

Input: questions (1 to 4), each with question, header (up to 12 characters), options (2 to 4, each label of 1 to 5 words, description, optional preview) and multiSelect. Also answers (filled by the permission system; multi-select answers are comma-joined), annotations (per question, preview and notes) and metadata.

Output: questions, answers (question text to answer), response (a free-form reply instead of answers; Claude then sees The user responded: ...), annotations, and afkTimeoutMs when the dialog auto-resolved after inactivity. See user input.

Bash

Input: command, timeout (ms; foreground capped at 600000 by default; with run_in_background on Claude Code 2.1.285+ it is the background limit, default 1800000, capped at 7200000 unless raised), description, run_in_background.

Output: stdout (stdout and stderr interleaved), stderr (notices from the tool itself), interrupted, isImage, backgroundTaskId.

Monitor

Input: exactly one of command (each stdout line is an event) or ws ({"url", "protocols"}; each text frame is an event; Claude Code 2.1.195+), plus description and timeout_ms (default 300000, max 3600000, effective at most 1800000). Commands follow Bash permissions; WebSocket watches prompt separately.

Output: taskId, timeoutMs, persistent (false: every watch has a deadline).

Edit

Input: file_path, old_string, new_string, replace_all.

Output: filePath, oldString, newString, originalFile, structuredPatch (hunks with oldStart, oldLines, newStart, newLines, lines), userModified, replaceAll, gitDiff (filename, status modified or added, additions, deletions, changes, patch, repository).

Read

Input: file_path, offset, limit.

Output varies by type:

Write

Input: file_path, content.

Output: type (create or update), filePath, content, structuredPatch (empty for new files or skipped diffs), originalFile (None for new or very large files), gitDiff, userModified.

Glob

Input: pattern, path.

Output: durationMs, numFiles, filenames, truncated (100-file limit), totalMatches and countIsComplete (Claude Code 2.1.191+).

Grep

Input: pattern, path, glob, type, output_mode (content, files_with_matches, count), -i, -n, -B, -A, -C, context, -o, head_limit, offset, multiline.

Output: mode, numFiles (0 in content mode), filenames, content, numLines, numMatches, totalFiles (2.1.208+), totalLines (2.1.210+), appliedLimit, appliedOffset.

NotebookEdit

Input: notebook_path, cell_id, new_source, cell_type (code or markdown), edit_mode (replace, insert, delete).

Output: new_source, old_source, cell_id, cell_type, language, edit_mode, error, notebook_path, original_file, updated_file.

WebFetch and WebSearch

Task list tools

Available by default only on Claude 3.x, Opus 4 to 4.7, Sonnet 4 to 4.6 and Haiku 4.5 (Claude Code 2.1.268+). Elsewhere, opt in as described in todo tracking. CLAUDE_CODE_ENABLE_TASKS=0 swaps the four Task tools for TodoWrite.

Background task tools

• TaskStop (aliases KillShell, KillBash). Input: task_id (or deprecated shell_id). Output: message, task_id, task_type, command.
• TaskOutput was removed in Claude Code 2.1.277 (as was its BashOutput alias). Claude reads a background task's output file with Read. Deny rules naming either are silently ignored.

ExitPlanMode

Input: plan. Output: plan, isAgent, filePath, hasTaskTool, planWasEdited, awaitingLeaderApproval, requestId.

MCP resources

A complete chat loop

A small terminal chat that keeps context across turns and supports new and interrupt:

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, AssistantMessage, TextBlock

async def chat():
    client = ClaudeSDKClient(ClaudeAgentOptions(allowed_tools=["Read", "Grep"], permission_mode="default"))
    await client.connect()
    try:
        while True:
            line = await asyncio.to_thread(input, "\nyou> ")
            if line == "exit":
                break
            if line == "new":
                await client.disconnect()
                await client.connect()
                print("(fresh session)")
                continue
            if line == "interrupt":
                await client.interrupt()
                continue
            await client.query(line)
            async for m in client.receive_response():
                if isinstance(m, AssistantMessage):
                    print("".join(b.text for b in m.content if isinstance(b, TextBlock)), end="")
    finally:
        await client.disconnect()

asyncio.run(chat())

Sandbox

SandboxSettings

The sandbox needs platform support, and on Linux bubblewrap and socat. If it cannot start, Python's default is to run unsandboxed with a warning on stderr (TypeScript defaults to failing). Add "failIfUnavailable": True to stop instead: it is not declared on the TypedDict but is forwarded and honoured, and the run ends in an error_during_execution result with the reason in errors.

opts = ClaudeAgentOptions(sandbox={
    "enabled": True,
    "failIfUnavailable": True,
    "network": {"allowedDomains": ["pypi.org", "files.pythonhosted.org"], "allowLocalBinding": True},
})

SandboxNetworkConfig

Applies to sandboxed Bash only, not WebFetch (which uses permission rules).

Warning: Allowing /var/run/docker.sock effectively hands over the whole host through the Docker API. The built-in proxy also filters by requested hostname without inspecting TLS, so domain fronting can get round it; see secure deployment.

Handling unsandboxed requests

When allowUnsandboxedCommands is on and the model sets dangerouslyDisableSandbox: True, the call goes to can_use_tool, so you can decide. Note that can_use_tool needs streaming input, and a PreToolUse hook that simply returns {"continue_": True} keeps the stream open for it:

async def gate(tool, data, ctx):
    if tool == "Bash" and data.get("dangerouslyDisableSandbox"):
        if data.get("command", "").startswith("docker compose "):
            return PermissionResultAllow()
        return PermissionResultDeny(message="Unsandboxed execution not permitted")
    return PermissionResultAllow()

async def keep_open(data, tid, ctx):
    return {"continue_": True}

async def prompt():
    yield {"type": "user", "message": {"role": "user", "content": "Bring up the dev stack"}}

async for m in query(prompt=prompt(), options=ClaudeAgentOptions(
        sandbox={"enabled": True, "allowUnsandboxedCommands": True},
        permission_mode="default",
        can_use_tool=gate,
        hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[keep_open])]})):
    ...

Warning: With bypassPermissions and allowUnsandboxedCommands together, the model can leave the sandbox without asking anyone, apart from the actions no mode auto-approves. Do not combine them.

Related

• TypeScript SDK reference
• Agent SDK quickstart
• Custom tools
• Permissions in the SDK
• Agent SDK troubleshooting