Agent SDK Cheat Sheet

The Claude Agent SDK (claude-agent-sdk, renamed from “Claude Code SDK”) exposes the Claude Code agent harness programmatically: the agentic loop, tools, hooks, permissions, subagents and MCP servers. You host it — contrast Managed Agents, where Anthropic hosts the loop and sandbox.

Install

pip install claude-agent-sdk          # Python
npm install @anthropic-ai/claude-agent-sdk   # TypeScript

Quickstart

import anyio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        model="claude-opus-5",
        system_prompt="You are a precise refactoring assistant.",
        allowed_tools=["Read", "Edit", "Bash"],
        permission_mode="acceptEdits",
        cwd="/repo",
    )
    async for message in query(prompt="Rename getUserName to getUsername repo-wide, then run tests.",
                               options=options):
        print(message)

anyio.run(main)

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

for await (const message of query({
  prompt: 'Rename getUserName to getUsername repo-wide, then run tests.',
  options: {
    model: 'claude-opus-5',
    systemPrompt: 'You are a precise refactoring assistant.',
    allowedTools: ['Read', 'Edit', 'Bash'],
    permissionMode: 'acceptEdits',
    cwd: '/repo',
  },
})) {
  console.log(message);
}

Options

Permission modes

Programmatic permission callback

Fine-grained control beyond allow/deny lists — decide per call:

async def can_use_tool(tool_name, tool_input, context):
    if tool_name == "Bash" and "rm -rf" in tool_input.get("command", ""):
        return {"behavior": "deny", "message": "destructive command blocked"}
    if tool_name == "Edit" and tool_input.get("file_path", "").endswith(".env"):
        return {"behavior": "deny", "message": "secrets are read-only"}
    return {"behavior": "allow"}

options = ClaudeAgentOptions(can_use_tool=can_use_tool, allowed_tools=["Read", "Edit", "Bash"])

const options = {
  allowedTools: ['Read', 'Edit', 'Bash'],
  canUseTool: async (toolName: string, input: Record<string, unknown>) => {
    if (toolName === 'Bash' && String(input.command).includes('rm -rf'))
      return { behavior: 'deny', message: 'destructive command blocked' };
    return { behavior: 'allow' };
  },
};

Hooks

Same lifecycle events as Claude Code (PreToolUse, PostToolUse, UserPromptSubmit, Stop, SessionStart, SubagentStop, PreCompact, Notification), registered in code. A PreToolUse hook returning a deny decision blocks the tool — the deterministic enforcement mechanism.

async def block_destructive(input_data, tool_use_id, context):
    cmd = input_data.get("tool_input", {}).get("command", "")
    if any(bad in cmd for bad in ("rm -rf", "git push --force", "drop table")):
        return {"decision": "block", "reason": "destructive command"}
    return {}

options = ClaudeAgentOptions(
    hooks={"PreToolUse": [{"matcher": "Bash", "hooks": [block_destructive]}]})

Subagents

Define delegated agents with isolated context, their own tools and model:

options = ClaudeAgentOptions(
    agents={
        "security-reviewer": {
            "description": "Reviews diffs for injection, secrets, authz. Use after auth edits.",
            "prompt": "Report findings only: file:line, severity, fix. Do not edit.",
            "tools": ["Read", "Grep", "Glob"],
            "model": "claude-sonnet-5",
        }
    })

Subagents receive only what the parent passes; never assume inheritance. Use a cheaper model for mechanical delegated work.

MCP servers

options = ClaudeAgentOptions(
    mcp_servers={
        "orders": {"command": "python", "args": ["orders_server.py"]},          # stdio
        "linear": {"type": "http", "url": "https://mcp.linear.app/mcp"},        # remote
    },
    allowed_tools=["mcp__orders__get_order", "mcp__linear__list_issues"])

MCP tools are namespaced mcp__<server>__<tool>; allowlist them explicitly.

Streaming events

query() yields a stream of typed messages mirroring the SSE flow: a system init message, assistant messages (text/tool_use blocks), user messages (tool_result), and a final result message carrying stop_reason, usage and cost.

async for message in query(prompt="…", options=options):
    if message.type == "assistant":
        for block in message.content:
            if block.type == "text":
                print(block.text, end="")
    elif message.type == "result":
        print(message.stop_reason, message.usage, message.total_cost_usd)

Branch on the result message’s stop_reason, not on parsing assistant text.

Headless patterns

# CI gate sketch
import sys
async def review():
    async for m in query(prompt="Review the diff for security issues; output PASS or FAIL.",
                         options=ClaudeAgentOptions(permission_mode="plan",
                                                    allowed_tools=["Read", "Grep", "Bash(git diff:*)"])):
        if m.type == "result":
            sys.exit(0 if "PASS" in (m.result or "") else 1)

Agent SDK vs Managed Agents vs Messages API loop

Common misconceptions

Scenario walkthrough

A platform team wants a self-hosted CI agent that reviews PRs for security issues, must never edit files, must run inside their VPC (data locality), and must fail the build on a finding.

1. Self-hosted + VPC data locality → Agent SDK, not Managed Agents (which is hosted). A Messages API loop would mean rebuilding the harness.
2. Must never edit → permission_mode="plan" (read-only) and a tool allowlist without Edit/Write.
3. Security focus → a security-reviewer subagent on claude-sonnet-5 (cheaper, sufficient), tools Read, Grep, Bash(git diff:*).
4. Enforcement → a PreToolUse deny for any write, deterministic, not a prompt sentence.
5. Fail the build → parse the result message; sys.exit(1) on a finding.
6. Cost/loop safety → cap max_turns; log total_cost_usd; still branch on stop_reason.

Rejected alternatives: Managed Agents (violates data locality), bypassPermissions (excessive agency), enforcing read-only via the system prompt (prompt-as-enforcement), and using a turn cap as the completion signal (iteration-cap anti-pattern).

Key takeaways

• The Agent SDK is self-hosted; Managed Agents is Anthropic-hosted; pick on runtime/data-control vs ops-burden.
• Loop termination is stop_reason; max_turns is only a runaway guard.
• Enforce rules with hooks / can_use_tool, never with prompt text.
• Subagents get only explicitly-passed context; give them their own (often cheaper) model and a tight tool allowlist.
• MCP tools are mcp__server__tool; allowlist them and keep the set small.
• bypassPermissions is for sandboxed CI only.