Claude Agent SDK

• Library for building production AI agents using the same engine that powers Claude Code
• Available in Python (claude-agent-sdk) and TypeScript (@anthropic-ai/claude-agent-sdk)
• Provides built-in tools, agent loop, and context management out of the box
• Agents can autonomously read files, run commands, search the web, and edit code
• Eliminates the need to implement your own tool-execution loop (unlike the Anthropic Client SDK)
• Runs inside your own process / infrastructure, not Anthropic-hosted
• Governed by Anthropic’s Commercial Terms of Service

Setup

• Install (TypeScript): npm install @anthropic-ai/claude-agent-sdk
• Install (Python): pip install claude-agent-sdk
• TypeScript SDK bundles a native Claude Code binary — no separate install needed
• Authenticate with: export ANTHROPIC_API_KEY=your-api-key
• Third-party auth supported via environment variables:
  • Amazon Bedrock → CLAUDE_CODE_USE_BEDROCK=1
  • Claude Platform on AWS → CLAUDE_CODE_USE_ANTHROPIC_AWS=1 + ANTHROPIC_AWS_WORKSPACE_ID
  • Google Vertex AI → CLAUDE_CODE_USE_VERTEX=1
  • Microsoft Azure → CLAUDE_CODE_USE_FOUNDRY=1
• claude.ai login / subscription rate limits are not allowed for third-party agents, use API keys
• Starting June 15, 2026: Agent SDK and claude -p usage on subscription plans draws from a separate monthly Agent SDK credit.

Architecture

• Core function: query() — returns an async iterable of messages
• Configuration object: ClaudeAgentOptions (Python) / options (TypeScript)
• The SDK handles the agentic loop internally (tool calls → results → continue)

• Session state stored as JSONL on your filesystem
• Loads filesystem-based config from .claude/ (working dir) and ~/.claude/ (user dir)
• Use setting_sources / settingSources to restrict which config sources load

Capabilities

Built-in Tools

• 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
• Monitor — watch a background script, react to each output line
• Glob — find files by pattern (e.g., **/*.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 with multiple-choice options
• Agent — required in allowed_tools to invoke subagents

Hooks

• Run custom code at key points in the agent lifecycle

• Use callbacks to validate, log, block, or transform agent behavior

• Available hooks:

  • PreToolUse — before a tool runs

  • PostToolUse — after a tool returns

  • Stop — agent ends its turn

  • SessionStart — session begins

  • SessionEnd — session terminates

  • UserPromptSubmit — user sends a message

• Use HookMatcher to scope hooks to specific tools (e.g., matcher="Edit|Write")

Subagents

• Spawn specialized agents to handle focused subtasks
• Defined via AgentDefinition with: description, prompt, and scoped tools
• Main agent delegates work; subagents report back results
• Must include Agent in main agent’s allowed_tools
• Subagent messages carry a parent_tool_use_id field for tracing
• Each subagent gets an isolated context window (key reliability pattern)

MCP (Model Context Protocol)

• Connect agents to external systems: databases, browsers, APIs, etc.
• Configured via mcp_servers (Python) / mcpServers (TypeScript)
• Each MCP server defined with command and args
• Hundreds of community MCP servers available
• Example: Playwright MCP → adds browser automation capability

Permissions

• Control exactly which tools the agent can use
• allowed_tools / allowedTools → pre-approve safe tools
• permission_mode / permissionMode controls approval behavior
  • acceptEdits → auto-approve file edits
  • Other modes available for prompting / blocking
• Least-privilege per agent is the recommended pattern

Sessions

• Maintain context across multiple query() calls
• Capture session_id from the SystemMessage with subtype == “init”
• Resume with resume=session_id option
• Can be forked to explore different approaches
• Persists files read, analysis done, and conversation history

Claude Code Features (filesystem-based)

• Skills → .claude/skills/*/SKILL.md (specialized capabilities in Markdown)
• Slash commands → .claude/commands/*.md (custom commands for common tasks)
• Memory → CLAUDE.md or .claude/CLAUDE.md (project context and instructions)
• Plugins → programmatic via plugins option (extend with commands, agents, MCP servers)

Agent SDK vs Other Claude Tools

vs Anthropic Client SDK

• Client SDK → you implement the tool execution loop manually
• Agent SDK → Claude handles tools autonomously
• Use Agent SDK when you want built-in tools and the agent loop

vs Claude Code CLI

• Same capabilities, different interface
• CLI → interactive development, one-off tasks
• SDK → CI/CD pipelines, custom applications, production automation
• Workflows translate directly between CLI and SDK

vs Managed Agents

• Agent SDK → runs in your process / your infrastructure
• Managed Agents → hosted REST API on Anthropic-managed infrastructure
• Agent SDK = local files, in-process custom tools, filesystem state
• Managed Agents = sandbox per session, event log hosted by Anthropic
• Common path: prototype with Agent SDK → move to Managed Agents for production

Common Use Cases

• Bug-fixing agents (Read + Edit + Bash)
• Codebase analysis (Read + Glob + Grep)
• Code review (read-only subagent for context isolation)
• Browser automation (with Playwright MCP)
• Research agents (WebSearch + WebFetch)
• CI/CD pipeline integration
• Email assistants and developer productivity tools

Branding Guidelines (for partners)

• Allowed: “Claude Agent”, “Claude” (inside Agents menu), “{YourAgent} Powered by Claude”
• Not permitted: “Claude Code” or “Claude Code Agent”
• Do not mimic Claude Code visual elements or ASCII art
• Maintain your own product branding

Final Remarks

• The Claude Agent SDK is Anthropic’s recommended path for building production-grade autonomous agents in Python or TypeScript
• It packages the same engine as Claude Code — agent loop, tools, context management — into a library you can embed in any application
• Mastery of the SDK requires fluency in four core primitives: built-in tools, hooks, subagents, and sessions
• Permissions and subagent context isolation are the two patterns most tested for production reliability
• Choose Agent SDK when you need control, custom tools, and local execution; choose Managed Agents when you want Anthropic to handle infrastructure
• For the CCA-F exam, expect scenario questions on: allowed_tools scoping, hook lifecycle, subagent delegation, session resumption, and MCP server integration
• Combine this cheat sheet with hands-on practice (build a small bug-fixing or research agent) — the exam rewards practical judgment, not memorization alone
• Always default to the principle of least privilege: smallest tool set, smallest context, smallest blast radius