Claude Agent SDK
ClaudeAgentOptions (Python)
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
options = ClaudeAgentOptions(
model="claude-sonnet-4-5",
system_prompt="You are a code review expert.",
allowed_tools=["Read", "Glob", "Grep", "Bash(npm test *)"],
disallowed_tools=["WebFetch"],
permission_mode="default", # default|acceptEdits|dontAsk|bypassPermissions|plan
max_turns=20,
cwd="/path/to/project",
mcp_servers={"github": {"command": "npx", "args": ["-y", "@mcp/server-github"]}},
env={"GITHUB_TOKEN": "xxx"},
include_partial_messages=True,
fork_session=False, # True = isolated context
)
client = ClaudeSDKClient()
async for event in client.query("Review the auth module", options=options):
if event.type == "text":
print(event.text)
elif event.type == "tool_use":
print(f"Using: {event.tool_name}")
Custom Tools via @tool Decorator
from claude_agent_sdk import tool, create_sdk_mcp_server
@tool("search_jira", "Search Jira issues", {
"query": {"type": "string", "description": "JQL query"},
"limit": {"type": "integer", "description": "Max results", "default": 10}
})
def search_jira(args: dict) -> dict:
results = jira_client.search(args["query"], max_results=args.get("limit", 10))
return {"content": [{"type": "text", "text": format_issues(results)}]}
server = create_sdk_mcp_server(
name="jira-tools", version="1.0.0",
tools=[search_jira]
)
TypeScript
import { tool, createSdkMcpServer } from "claude-agent-sdk";
const searchJira = tool(
"search_jira", "Search Jira issues",
{ query: { type: "string" }, limit: { type: "integer", default: 10 } },
async (args) => ({ content: [{ type: "text", text: "Results..." }] })
);
const server = createSdkMcpServer({
name: "jira-tools", version: "1.0.0",
tools: [searchJira]
});
Tool Use API
Tool Definition
{
"name": "get_weather",
"description": "Get current weather at a location",
"input_schema": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "City and state"},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
},
"required": ["location"]
}
}
Flow
Request → Claude returns tool_use blocks (stop_reason: "tool_use")
→ Execute tools locally
→ Return tool_result blocks
→ Claude generates final response
Parallel Tool Use
Claude can return multiple tool_use blocks. Return ALL tool_result blocks in a single user message.
tool_choice
{"type": "auto"}— default, Claude decides{"type": "any"}— must use a tool{"type": "tool", "name": "get_weather"}— specific tool
Error Handling
{"type": "tool_result", "tool_use_id": "...", "is_error": true,
"content": "File not found. Available: main.py, utils.py"}
Extended Thinking
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 10000},
messages=[{"role": "user", "content": "Analyze this algorithm..."}]
)
for block in response.content:
if block.type == "thinking":
print(f"[Thinking] {block.thinking}")
elif block.type == "text":
print(f"[Response] {block.text}")
budget_tokens must be < max_tokens. All Claude 4.5/4.6 models support it.
Sub-Agents
| Type | Model | Tools | Purpose |
|---|---|---|---|
| Explore | Haiku | Read-only | File discovery, code search |
| Plan | Inherited | Read-only | Architecture planning |
| general-purpose | Inherited | All | Complex multi-step tasks |
Custom Sub-Agent Definition
---
name: code-reviewer
description: Reviews code for quality
tools: Read, Glob, Grep
model: sonnet
---
Review code for bugs, security issues, and style violations.
Store in .claude/agents/ or ~/.claude/agents/.
Built-in Tool Types
| Type | Purpose |
|---|---|
computer_20250124 |
Computer use (screenshot, click, type) |
text_editor_20250124 |
File editing |
bash_20250124 |
Shell commands |
tool_search_* |
Search over large tool lists (~85% token savings) |
code_execution_* |
Programmatic tool calling (~37% savings) |
memory_20250818 |
Persistent state |