The Claude Agent SDK is a Python library that runs the Claude Code agent loop inside your own process. An application gets the same built-in tools, context management, sessions, subagents, and permission handling that the CLI uses, so you can build an agent without writing the tool-calling loop yourself. A TypeScript library covers the same surface, and other languages can drive the loop by running the CLI as a subprocess with -p and --output-format json.

There are two entry points. query() is an async function that takes a prompt and returns an async iterator of response messages, configured through ClaudeAgentOptions for the system prompt, turn limits, working directory, and tool permissions. ClaudeSDKClient adds bidirectional, interactive conversations and is the path that supports custom tools and hooks.

A custom tool is a Python function offered to the model, declared with the @tool decorator and registered through createsdkmcp_server. These are Model Context Protocol servers that run in-process rather than as a separate subprocess, and external stdio MCP servers can be mixed into the same configuration. A hook is a function the application invokes at a fixed point in the agent loop, such as PreToolUse, and it can return a permission decision that denies a tool call with a reason.

Tool permissions are layered: allowedtools auto-approves the tools it lists, unlisted tools fall through to permissionmode and canusetool, and disallowedtools blocks specific tools. The package needs Python 3.10 or later and bundles the Claude Code CLI, with clipath available to point at a separate installation. Typed errors distinguish a missing CLI, connection failures, process failures, terminal result errors, and JSON decode failures.

Features

Agent loop as a library: the Claude Code loop, tools, and context management run in your own Python process
Two client shapes: query() streams messages for one-shot prompts; ClaudeSDKClient holds an interactive session
In-process tools: Python functions become MCP tools with no subprocess, IPC, or extra deployment step
Hooks: application code runs at agent-loop events such as PreToolUse and can deny a tool call with a stated reason
Permission layers: allowlist, permission mode, a canusetool callback, and an explicit blocklist
Mixed MCP servers: in-process SDK servers and external stdio servers coexist in one options object
Bundled CLI: the Claude Code CLI ships in the wheel, with an option to use a system installation instead
Typed errors: distinct exception types for missing CLI, connection, process, result, and JSON decode failures