Claude Agent SDK

Provides patterns and best practices for building production AI agents using the Claude Agent SDK (Python: claude-agent-sdk , TypeScript: @anthropic-ai/claude-agent-sdk ).

Installation

TypeScript

npm install @anthropic-ai/claude-agent-sdk

Python (uv — recommended)

uv add claude-agent-sdk

Python (pip)

pip install claude-agent-sdk

Set the API key before running any agent:

export ANTHROPIC_API_KEY=your-api-key

Third-party providers are also supported: set CLAUDE_CODE_USE_BEDROCK=1 , CLAUDE_CODE_USE_VERTEX=1 , or CLAUDE_CODE_USE_FOUNDRY=1 alongside the respective cloud credentials.

Core Pattern: The query() Function

Every agent is built around query() , which returns an async iterator of streamed messages:

import asyncio from claude_agent_sdk import query, ClaudeAgentOptions

async def main(): async for message in query( prompt="Find and fix the bug in auth.py", options=ClaudeAgentOptions( allowed_tools=["Read", "Edit", "Glob"], permission_mode="acceptEdits", ), ): if hasattr(message, "result"): print(message.result)

asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({ prompt: "Find and fix the bug in auth.py", options: { allowedTools: ["Read", "Edit", "Glob"], permissionMode: "acceptEdits" } })) { if ("result" in message) console.log(message.result); }

The loop ends when Claude finishes or hits an error. The SDK handles tool execution, context management, and retries internally.

Built-in Tools

Grant only the tools the agent actually needs — principle of least privilege:

Tool Purpose

Read

Read any file in the working directory

Write

Create new files

Edit

Make precise edits to existing files

Bash

Run terminal commands, scripts, git operations

Glob

Find files by pattern (/*.ts , src//*.py )

Grep

Search file contents with regex

WebSearch

Search the web for current information

WebFetch

Fetch and parse web page content

AskUserQuestion

Ask the user clarifying questions

Task

Spawn subagents (required when using subagents)

Recommended tool sets by use case

Use case Tools

Read-only analysis Read , Glob , Grep

Code modification Read , Edit , Write , Glob , Grep

Full automation Read , Edit , Write , Bash , Glob , Grep

Web-augmented Add WebSearch , WebFetch to any set

Subagent orchestration Add Task to the parent agent's set

Permission Modes

Set permissionMode / permission_mode in options:

Mode Behavior Best for

default

Delegates unresolved requests to canUseTool callback Custom approval flows

acceptEdits

Auto-approves file edits and filesystem ops Trusted dev workflows

bypassPermissions

Runs all tools without prompts CI/CD pipelines

plan

No tool execution — planning only Pre-review before changes

Best practice: use acceptEdits for interactive development; use bypassPermissions only in isolated, sandboxed environments. Never use bypassPermissions in multi-tenant or user-facing applications.

Permission mode changes mid-session are supported — start restrictive, loosen after reviewing Claude's plan:

q = query(prompt="Refactor auth module", options=ClaudeAgentOptions(permission_mode="plan")) await q.set_permission_mode("acceptEdits") # Switch after plan is approved async for message in q: ...

Permission evaluation order

• Hooks — run first; can allow, deny, or pass through

• Permission rules — declarative allow/deny in settings.json

• Permission mode — global fallback setting

• canUseTool callback — runtime user approval (when mode is default )

Session Management

Capture session ID

session_id = None async for message in query(prompt="Analyze auth module", options=ClaudeAgentOptions(...)): if hasattr(message, "subtype") and message.subtype == "init": session_id = message.data.get("session_id")

let sessionId: string | undefined; for await (const message of query({ prompt: "Analyze auth module", options: { ... } })) { if (message.type === "system" && message.subtype === "init") { sessionId = message.session_id; } }

Resume a session

Pass resume / resume in options to continue with full prior context:

async for message in query( prompt="Now find all callers of that function", options=ClaudeAgentOptions(resume=session_id), ): ...

Fork a session

Set fork_session=True / forkSession: true to branch without modifying the original:

Explore a different approach without losing the original session

async for message in query( prompt="Redesign this as GraphQL instead", options=ClaudeAgentOptions(resume=session_id, fork_session=True), ): ...

Forking preserves the original session; both branches can be resumed independently.

MCP Integration

Connect external services through the Model Context Protocol:

options = ClaudeAgentOptions( mcp_servers={ "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]} } )

MCP tool names follow the pattern mcp__{server_name}__{tool_name} . List them explicitly in allowed_tools to restrict access:

allowed_tools=["mcp__playwright__browser_click", "mcp__playwright__browser_screenshot"]

Message Handling

Filter the stream for meaningful output. Raw messages include system init and internal state:

from claude_agent_sdk import AssistantMessage, ResultMessage

async for message in query(...): if isinstance(message, AssistantMessage): for block in message.content: if hasattr(block, "text"): print(block.text) # Claude's reasoning elif hasattr(block, "name"): print(f"Tool: {block.name}") # Tool being called elif isinstance(message, ResultMessage): print(f"Result: {message.subtype}") # "success" or "error"

for await (const message of query({ ... })) { if (message.type === "assistant") { for (const block of message.message.content) { if ("text" in block) console.log(block.text); else if ("name" in block) console.log(Tool: ${block.name}); } } else if (message.type === "result") { console.log(Result: ${message.subtype}); } }

System Prompts

Provide a system_prompt / systemPrompt to give Claude a persona or project-specific context:

options = ClaudeAgentOptions( system_prompt="You are a senior Python developer. Always follow PEP 8. Prefer explicit error handling over bare excepts.", allowed_tools=["Read", "Edit", "Glob"], permission_mode="acceptEdits", )

Keep system prompts concise and focused on constraints the LLM doesn't already know.

Best Practices

Tool selection

• Grant only the tools the task requires — no Bash for read-only analysis

• Verify tool set is sufficient before launching; a missing tool causes the agent to stall

• Include Task in the parent's allowed_tools when defining subagents

Prompts

• Write prompts as specific task instructions, not open-ended descriptions

• Name files explicitly when they are the target ("Review auth.py" vs "Review some code" )

• Use explicit subagent invocation when precision matters: "Use the code-reviewer agent to..." )

Error handling

• Always handle ResultMessage with subtype == "error" — never assume success

• Catch exceptions around the async for loop, not inside it

• Avoid bare except in hook callbacks; a swallowed exception can silently halt the agent

Security

• Never use bypassPermissions in production systems with user-supplied prompts

• Use PreToolUse hooks to block access to sensitive paths (.env , /etc , secrets)

• Restrict subagent tools — subagents do not inherit parent permissions automatically

Sessions

• Store session IDs persistently if the workflow spans multiple process runs

• Fork sessions when exploring alternative approaches to avoid losing a good baseline

• Subagent transcripts persist separately; clean up via cleanupPeriodDays setting

Performance

• Prefer streaming (async for ) over collecting all messages; it shows progress and allows early exit

• Use subagents to parallelise independent tasks (security scan + style check simultaneously)

• Use plan mode first for expensive or irreversible operations — review before executing

Additional Resources

• references/hooks.md — Lifecycle hooks: blocking tools, modifying inputs, audit logging

• references/subagents.md — Defining, invoking, and resuming subagents; parallelisation patterns

• references/custom-tools.md — Building in-process MCP tools with createSdkMcpServer