Agent SDK reference - Python
agent-sdk/python
History
agent-sdk/python First recorded · 3633 lines, first recorded
# 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()` #### Parameters #### Returns #### Example ### `list_sessions()` #### Parameters #### Return type: `SDKSessionInfo` #### Example ### `get_session_messages()` #### Parameters #### Return type: `SessionMessage` #### Example ### `get_session_info()` #### Parameters #### Example ### `rename_session()` #### Parameters #### Example ### `tag_session()` #### Parameters #### Example ## Classes ### `ClaudeSDKClient` #### Methods #### Context Manager Support #### Example - Continuing a conversation #### Example - Streaming input with ClaudeSDKClient #### Example - Using interrupts #### Example - Advanced permission control ## Types ### `SdkMcpTool` ### `Transport` ### `ClaudeAgentOptions` #### Handle slow or stalled API responses ### `OutputFormat` ### `SystemPromptPreset` ### `SystemPromptFile` ### `SettingSource` #### Default behavior #### Why use setting\_sources #### Settings precedence ### `AgentDefinition` ### `PermissionMode` ### `EffortLevel` ### `CanUseTool` ### `ToolPermissionContext` ### `PermissionResult` ### `PermissionResultAllow` ### `PermissionResultDeny` ### `PermissionUpdate` ### `PermissionRuleValue` ### `ToolsPreset` ### `ThinkingConfig` ### `TaskBudget` ### `SdkBeta` ### `McpSdkServerConfig` ### `McpServerConfig` #### `McpStdioServerConfig` #### `McpSSEServerConfig` #### `McpHttpServerConfig` ### `McpServerStatusConfig` ### `McpStatusResponse` ### `McpServerStatus` ### `SdkPluginConfig` ## Message Types ### `Message` ### `UserMessage` ### `AssistantMessage` ### `AssistantMessageError` ### `SystemMessage` ### `ResultMessage` ### `StreamEvent` ### `RateLimitEvent` ### `RateLimitInfo` ### `ConversationResetMessage` ### `TaskStartedMessage` ### `TaskUsage` ### `TaskProgressMessage` ### `TaskNotificationMessage` ## Content Block Types ### `ContentBlock` ### `TextBlock` ### `ThinkingBlock` ### `ToolUseBlock` ### `ToolResultBlock` ## Error Types ### `ClaudeSDKError` ### `CLINotFoundError` ### `CLIConnectionError` ### `ProcessError` ### `CLIJSONDecodeError` ## Hook Types ### `HookEvent` ### `HookCallback` ### `HookContext` ### `HookMatcher` ### `HookInput` ### `BaseHookInput` ### `PreToolUseHookInput` ### `PostToolUseHookInput` ### `PostToolUseFailureHookInput` ### `UserPromptSubmitHookInput` ### `StopHookInput` ### `SubagentStopHookInput` ### `PreCompactHookInput` ### `NotificationHookInput` ### `SubagentStartHookInput` ### `PermissionRequestHookInput` ### `HookJSONOutput` #### `SyncHookJSONOutput` #### `HookSpecificOutput` #### `AsyncHookJSONOutput` ### Hook Usage Example ## Tool Input/Output Types ### Agent ### AskUserQuestion ### Bash ### Monitor ### Edit ### Read ### Write ### Glob ### Grep ### NotebookEdit ### WebFetch ### WebSearch ### TodoWrite ### TaskCreate ### TaskUpdate ### TaskGet ### TaskList ### TaskOutput ### TaskStop ### ExitPlanMode ### ListMcpResources ### ReadMcpResource ## Advanced Features with ClaudeSDKClient ### Building a Continuous Conversation Interface ### Using Hooks for Behavior Modification ### Real-time Progress Monitoring ## Example Usage ### Basic file operations (using query) ### Error handling ### Using custom tools with ClaudeSDKClient ## Sandbox Configuration ### `SandboxSettings` #### Example usage ### `SandboxNetworkConfig` ### `SandboxIgnoreViolations` ### Permissions Fallback for Unsandboxed Commands ## See also
The first capture of this source. The page was already there, and this is what it said.
# Agent SDK reference - Python
> Complete API reference for the Python Agent SDK, including all functions, types, and classes.
## 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`.
```bash theme={null}
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](/docs/en/agent-sdk/quickstart#setup).
## 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
<Note>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())`.</Note>
### `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`](#claudeagentoptions). See [Sessions](/docs/en/agent-sdk/sessions).
```python theme={null}
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
```python theme={null}
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.
```python theme={null}
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`](#toolannotations)` \| None` | Optional MCP tool annotations providing behavioral hints to clients |
#### Input schema options
1. **Simple type mapping** (recommended):
```python theme={null}
{"text": str, "count": int, "enabled": bool}
```
2. **JSON Schema format** (for complex validation):
```python theme={null}
{
"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
```python theme={null}
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) |
```python theme={null}
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.
```python theme={null}
def create_sdk_mcp_server(
name: str,
version: str = "1.0.0",
tools: list[SdkMcpTool[Any]] | None = None
) -> McpSdkServerConfig
```
#### Parameters
| Parameter | Type | Default | Description |
| :-------- | :------------------------------ | :-------- | :---------------------------------------------------- |
| `name` | `str` | - | Unique identifier for the server |
| `version` | `str` | `"1.0.0"` | Server version string |
| `tools` | `list[SdkMcpTool[Any]] \| None` | `None` | List of tool functions created with `@tool` decorator |
#### Returns
Returns an `McpSdkServerConfig` object that can be passed to `ClaudeAgentOptions.mcp_servers`.
#### Example
```python theme={null}
from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions
@tool("add", "Add two numbers", {"a": float, "b": float})
async def add(args):
return {"content": [{"type": "text", "text": f"Sum: {args['a'] + args['b']}"}]}
@tool("multiply", "Multiply two numbers", {"a": float, "b": float})
async def multiply(args):
return {"content": [{"type": "text", "text": f"Product: {args['a'] * args['b']}"}]}
calculator = create_sdk_mcp_server(
name="calculator",
version="2.0.0",
tools=[add, multiply], # Pass decorated functions
)
# Use with Claude
options = ClaudeAgentOptions(
mcp_servers={"calc": calculator},
allowed_tools=["mcp__calc__add", "mcp__calc__multiply"],
)
```
### `list_sessions()`
Lists past sessions with metadata. Filter by project directory or list sessions across all projects. Synchronous; returns immediately.
```python theme={null}
def list_sessions(
directory: str | None = None,
limit: int | None = None,
offset: int = 0,
include_worktrees: bool = True
) -> list[SDKSessionInfo]
```
#### Parameters
| Parameter | Type | Default | Description |
| :------------------ | :------------ | :------ | :----------------------------------------------------------------------------------------------- |
| `directory` | `str \| None` | `None` | Directory to list sessions for. When omitted, returns sessions across all projects |
| `limit` | `int \| None` | `None` | Maximum number of sessions to return |
| `offset` | `int` | `0` | Number of sessions to skip from the start of the sorted results. Use with `limit` for pagination |
| `include_worktrees` | `bool` | `True` | When `directory` is inside a git repository, include sessions from all worktree paths |
#### Return type: `SDKSessionInfo`
| Property | Type | Description |
| :-------------- | :------------ | :------------------------------------------------------------------- |
| `session_id` | `str` | Unique session identifier |
| `summary` | `str` | Display title: custom title, auto-generated summary, or first prompt |
| `last_modified` | `int` | Last modified time in milliseconds since epoch |
| `file_size` | `int \| None` | Session file size in bytes (`None` for remote storage backends) |
| `custom_title` | `str \| None` | User-set session title |
| `first_prompt` | `str \| None` | First meaningful user prompt in the session |
| `git_branch` | `str \| None` | Git branch at the end of the session |
| `cwd` | `str \| None` | Working directory for the session |
| `tag` | `str \| None` | User-set session tag (see [`tag_session()`](#tag_session)) |
| `created_at` | `int \| None` | Session creation time in milliseconds since epoch |
#### Example
Print the 10 most recent sessions for a project. Results are sorted by `last_modified` descending, so the first item is the newest. Omit `directory` to search across all projects.
```python theme={null}
from claude_agent_sdk import list_sessions
for session in list_sessions(directory="/path/to/project", limit=10):
print(f"{session.summary} ({session.session_id})")
```
### `get_session_messages()`
Retrieves messages from a past session. Synchronous; returns immediately.
```python theme={null}
def get_session_messages(
session_id: str,
directory: str | None = None,
limit: int | None = None,
offset: int = 0
) -> list[SessionMessage]
```
#### Parameters
| Parameter | Type | Default | Description |
| :----------- | :------------ | :------- | :---------------------------------------------------------------- |
| `session_id` | `str` | required | The session ID to retrieve messages for |
| `directory` | `str \| None` | `None` | Project directory to look in. When omitted, searches all projects |
| `limit` | `int \| None` | `None` | Maximum number of messages to return |
| `offset` | `int` | `0` | Number of messages to skip from the start |
#### Return type: `SessionMessage`
| Property | Type | Description |
| :------------------- | :----------------------------- | :------------------------ |
| `type` | `Literal["user", "assistant"]` | Message role |
| `uuid` | `str` | Unique message identifier |
| `session_id` | `str` | Session identifier |
| `message` | `Any` | Raw message content |
| `parent_tool_use_id` | `None` | Reserved for future use |
Cut at 300 lines.