The Claude Agent SDK provides a higher-level interface for building AI agents with built-in tools, safety features, and agentic capabilities.
\npip install claude-agent-sdk\nimport anyio\nfrom claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage\n\nasync def main():\n async for message in query(\n prompt=\"Explain this codebase\",\n options=ClaudeAgentOptions(allowed_tools=[\"Read\", \"Glob\", \"Grep\"])\n ):\n if isinstance(message, ResultMessage):\n print(message.result)\n\nanyio.run(main)\n| Tool | \nDescription | \n
|---|---|
| Read | \nRead files in the workspace | \n
| Write | \nCreate new files | \n
| Edit | \nMake precise edits to existing files | \n
| Bash | \nExecute shell commands | \n
| Glob | \nFind files by pattern | \n
| Grep | \nSearch files by content | \n
| WebSearch | \nSearch the web for information | \n
| WebFetch | \nFetch and analyze web pages | \n
| AskUserQuestion | \nAsk user clarifying questions | \n
| Agent | \nSpawn subagents | \n
query() — Simple One-Shot UsageThe query() function is the simplest way to run an agent. It returns an async iterator of messages.
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage\n\nasync for message in query(\n prompt=\"Explain this codebase\",\n options=ClaudeAgentOptions(allowed_tools=[\"Read\", \"Glob\", \"Grep\"])\n):\n if isinstance(message, ResultMessage):\n print(message.result)\nClaudeSDKClient — Full ControlClaudeSDKClient provides full control over the agent lifecycle. Use it when you need custom tools, hooks, streaming, or the ability to interrupt execution.
import anyio\nfrom claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, AssistantMessage, TextBlock\n\nasync def main():\n options = ClaudeAgentOptions(allowed_tools=[\"Read\", \"Glob\", \"Grep\"])\n async with ClaudeSDKClient(options=options) as client:\n await client.query(\"Explain this codebase\")\n async for message in client.receive_response():\n if isinstance(message, AssistantMessage):\n for block in message.content:\n if isinstance(block, TextBlock):\n print(block.text)\n\nanyio.run(main)\nClaudeSDKClient supports:
async with) for automatic resource cleanupclient.query(prompt) to send a prompt to the agentreceive_response() for streaming messages until completioninterrupt() to stop agent execution mid-taskfrom claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage\n\nasync for message in query(\n prompt=\"Refactor the authentication module\",\n options=ClaudeAgentOptions(\n allowed_tools=[\"Read\", \"Edit\", \"Write\"],\n permission_mode=\"acceptEdits\" # Auto-accept file edits\n )\n):\n if isinstance(message, ResultMessage):\n print(message.result)\nPermission modes:
\n\"default\": Prompt for dangerous operations\"plan\": Planning only, no execution\"acceptEdits\": Auto-accept file edits\"dontAsk\": Don't prompt (useful for CI/CD)\"bypassPermissions\": Skip all prompts (requires allow_dangerously_skip_permissions=True in options)from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage\n\nasync for message in query(\n prompt=\"Open example.com and describe what you see\",\n options=ClaudeAgentOptions(\n mcp_servers={\n \"playwright\": {\"command\": \"npx\", \"args\": [\"@playwright/mcp@latest\"]}\n }\n )\n):\n if isinstance(message, ResultMessage):\n print(message.result)\nCustomize agent behavior with hooks using callback functions:
\nfrom claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, ResultMessage\n\nasync def log_file_change(input_data, tool_use_id, context):\n file_path = input_data.get('tool_input', {}).get('file_path', 'unknown')\n print(f\"Modified: {file_path}\")\n return {}\n\nasync for message in query(\n prompt=\"Refactor utils.py\",\n options=ClaudeAgentOptions(\n permission_mode=\"acceptEdits\",\n hooks={\n \"PostToolUse\": [HookMatcher(matcher=\"Edit|Write\", hooks=[log_file_change])]\n }\n )\n):\n if isinstance(message, ResultMessage):\n print(message.result)\nAvailable hook events: PreToolUse, PostToolUse, PostToolUseFailure, Notification, UserPromptSubmit, SessionStart, SessionEnd, Stop, SubagentStart, SubagentStop, PreCompact, PermissionRequest, Setup, TeammateIdle, TaskCompleted, ConfigChange
query() takes a top-level prompt (string) and an options object (ClaudeAgentOptions):
async for message in query(prompt=\"...\", options=ClaudeAgentOptions(...)):\n| Option | \nType | \nDescription | \n
|---|---|---|
cwd | \nstring | \nWorking directory for file operations | \n
allowed_tools | \nlist | \nTools the agent can use (e.g., [\"Read\", \"Edit\", \"Bash\"]) | \n
tools | \nlist | \nBuilt-in tools to make available (restricts the default set) | \n
disallowed_tools | \nlist | \nTools to explicitly disallow | \n
permission_mode | \nstring | \nHow to handle permission prompts | \n
allow_dangerously_skip_permissions | \nbool | \nMust be True to use permission_mode=\"bypassPermissions\" | \n
mcp_servers | \ndict | \nMCP servers to connect to | \n
hooks | \ndict | \nHooks for customizing behavior | \n
system_prompt | \nstring | \nCustom system prompt | \n
max_turns | \nint | \nMaximum agent turns before stopping | \n
max_budget_usd | \nfloat | \nMaximum budget in USD for the query | \n
model | \nstring | \nModel ID (default: determined by CLI) | \n
agents | \ndict | \nSubagent definitions (dict[str, AgentDefinition]) | \n
output_format | \ndict | \nStructured output schema | \n
thinking | \ndict | \nThinking/reasoning control | \n
betas | \nlist | \nBeta features to enable (e.g., [\"context-1m-2025-08-07\"]) | \n
setting_sources | \nlist | \nSettings to load (e.g., [\"project\"]). Default: none (no CLAUDE.md files) | \n
env | \ndict | \nEnvironment variables to set for the session | \n
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage, SystemMessage\n\nasync for message in query(\n prompt=\"Find TODO comments\",\n options=ClaudeAgentOptions(allowed_tools=[\"Read\", \"Glob\", \"Grep\"])\n):\n if isinstance(message, ResultMessage):\n print(message.result)\n elif isinstance(message, SystemMessage) and message.subtype == \"init\":\n session_id = message.session_id # Capture for resuming later\nfrom claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ResultMessage\n\nasync for message in query(\n prompt=\"Use the code-reviewer agent to review this codebase\",\n options=ClaudeAgentOptions(\n allowed_tools=[\"Read\", \"Glob\", \"Grep\", \"Agent\"],\n agents={\n \"code-reviewer\": AgentDefinition(\n description=\"Expert code reviewer for quality and security reviews.\",\n prompt=\"Analyze code quality and suggest improvements.\",\n tools=[\"Read\", \"Glob\", \"Grep\"]\n )\n }\n )\n):\n if isinstance(message, ResultMessage):\n print(message.result)\nfrom claude_agent_sdk import query, ClaudeAgentOptions, CLINotFoundError, CLIConnectionError, ResultMessage\n\ntry:\n async for message in query(\n prompt=\"...\",\n options=ClaudeAgentOptions(allowed_tools=[\"Read\"])\n ):\n if isinstance(message, ResultMessage):\n print(message.result)\nexcept CLINotFoundError:\n print(\"Claude Code CLI not found. Install with: pip install claude-agent-sdk\")\nexcept CLIConnectionError as e:\n print(f\"Connection error: {e}\")\ncwd for file operations\"default\" and only escalate when neededResultMessage to get agent output