Claude Agent SDK cheat sheet

$ pip install claude-agent-sdk

$ export ANTHROPIC_API_KEY=your-api-key

import anyio
from claude_agent_sdk import query

async def main():
    async for message in query(prompt="What is 2 + 2?"):
        print(message)

anyio.run(main)

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

for await (const message of query({ prompt: "What is 2 + 2?" })) {
  console.log(message);
}

Sources: Agent SDK quickstart · Python SDK reference · TypeScript SDK reference · claude-agent-sdk on PyPI · @anthropic-ai/claude-agent-sdk on npm

Anthropic ships four ways to work with Claude. They differ in who runs the agent and what comes built in. Find the row that matches how you want to build and run yours.

• This sheet

  Embed the Claude Code agent in your own Python or TypeScript app, in a process you run

  Agent SDK

  A library that runs the Claude Code binary, with built in tools, permissions, sessions and hooks.

• Work interactively or run one off tasks from a terminal

  Claude Code CLI

  The terminal interface, built for daily interactive use.

• Call the Claude API directly from your own code

  Client SDK

  Direct access to the API. You write the tool loop yourself, or let the beta tool runner drive it.

• Have Anthropic host the agent, configured through the Claude API

  Managed Agents

  A hosted agent harness that runs the loop, with sessions in an Anthropic managed sandbox or one you host.

To drive the same agent loop from another language, run the CLI as a subprocess with the -p flag and --output-format json.

What the Agent SDK gives you

• Built in toolsRead, write and edit files, run commands and search the web.
• HooksRun your code at key points in the agent lifecycle.
• SubagentsSpawn specialized agents for focused subtasks.
• MCPConnect external tools and data through the Model Context Protocol.
• PermissionsControl which tools run on their own and which need approval.
• SessionsKeep context across exchanges, then resume or fork later.
• Skills, commands and memoryLoad automatically from your project .claude/ folder and from ~/.claude/, the same as Claude Code.
• PluginsPackage skills, agents, hooks and MCP servers and load them by local path.

Sources: Agent SDK overview

Anthropic describes the feedback loop Claude Code runs, and offers it as a way to think about agents you build with the SDK: gather context -> take action -> verify work -> repeat. Every option on this sheet changes one of the four steps, so it helps to know which.

1. 01

   Gather context

   What the agent can see before it acts.

   • cwd
   • tools
   • mcp_servers
   • setting_sources
   • system_prompt
2. 02

   Take action

   Which calls run, and who approves them.

   • allowed_tools
   • permission_mode
   • can_use_tool
   • hooks
3. 03

   Verify work

   Checks that catch a wrong result before it ships.

   • PostToolUse hooks
   • output_format
   • agents
4. 04

   Repeat or stop

   How the loop ends, and how you tell why.

   • max_turns
   • max_budget_usd
   • ResultMessage.subtype

One lap of the loop

1. 1Gather contextClaude reads files, runs searches or calls read only tools to find what it needs.
2. 2Take actionIt calls a tool such as Bash, Edit or one of yours. Permissions decide whether the call runs.
3. 3Verify workLint or rule checks, a judging subagent or a PostToolUse hook can check the work. An output schema validates the final answer.
4. 4Repeat or stopThe loop ends on success, a turn cap, a budget cap or an error. Read the result subtype.

Sources: Building agents with the Claude Agent SDK · How the agent loop works

Python has 49 option fields and the TypeScript docs list 66. These are the ones that change behavior in practice.

Sources: Python SDK reference · TypeScript SDK reference

Eight behaviors that surprise people, with the one line fix for each. Python names are shown. TypeScript spells them in camelCase: allowed_tools is allowedTools, mcp_servers is mcpServers, can_use_tool is canUseTool, fork_session is forkSession, max_turns is maxTurns and max_budget_usd is maxBudgetUsd.

1. Python and TypeScript

   01

   allowed_tools is not a whitelist

   It only pre approves. Tools you leave out stay available and fall through to your permission mode and callback.

   Do thisTo remove a tool, use tools or disallowed_tools. Keep allowed_tools for skipping prompts.

   Python SDK reference

2. Python and TypeScript

   02

   Settings load by default

   Leave setting_sources unset and user, project and local settings load, including CLAUDE.md, skills and slash commands. If you also set skills, only user and project load. An empty list skips those three sources, but managed policy settings and auto memory still apply. Early 0.1.0 notes say the opposite, but the migration guide records that default as reverted.

   Do thisPass setting_sources=[] (settingSources: [] in TypeScript) for a clean, repeatable run.

   Migration guide · Python SDK reference

3. Python and TypeScript

   03

   The system prompt is minimal

   With no system_prompt you get a short prompt that covers tool calling and leaves out the rest of the Claude Code preset, including its safety instructions.

   Do thisAsk for the claude_code preset, and use append for your own rules.

   Modifying system prompts

4. Python and TypeScriptChanged Oct 16

   04

   The permission default is deny

   From Claude Code v2.1.302, an app with no permission mode, and no permissions.defaultMode in its settings files, starts in default mode, which denies any call that needs approval unless a rule, hook or callback approves it. TypeScript 0.3.286 to 0.3.301 started in auto mode in some setups, then reversed.

   Do thisSet permission_mode on purpose, or supply a can_use_tool callback.

   Permissions · TypeScript SDK changelog

5. Python and TypeScript

   05

   Cost fields are estimates

   total_cost_usd comes from a price table inside the SDK. Parallel tool calls share one message id, so count each id once. usage leaves out subagents. A resumed session already includes its earlier spend.

   Do thisBill from the Usage and Cost API or the Console. Never add results across a resume.

   Cost tracking

6. Python and TypeScript

   06

   A single call raises after an error result

   When a query() call ends in an error result such as hitting max_turns, the SDK yields that result, then raises. Streaming input sessions stay alive after an error result.

   Do thisWrap the loop in try and catch, and read the result subtype.

   How the agent loop works · Python SDK reference

7. Python

   07

   In Python, drain the stream after interrupt()

   On ClaudeSDKClient, interrupt() does not clear buffered messages. The old messages, including the interrupted ResultMessage, are still waiting. The docs also warn that a break inside the iteration loop can cause asyncio cleanup problems.

   Do thisRead receive_response() to its result before you send the next query.

   Python SDK reference

8. Python and TypeScript

   08

   env merges in Python and replaces in TypeScript

   In Python, env is merged over the inherited environment. In TypeScript, env replaces it, so the subprocess loses PATH and your key unless you pass them.

   Do thisIn TypeScript, always spread process.env: env: { ...process.env, MY_VAR: "1" }.

   Python SDK reference · TypeScript SDK reference

TypeScript has one function. Pass an async iterable as the prompt to enter streaming input mode, which keeps the session open and unlocks interrupt(), setModel() and setPermissionMode() on the returned Query.

import asyncio
from claude_agent_sdk import ClaudeSDKClient, AssistantMessage, TextBlock

async def ask(client, question):
    await client.query(question)
    async for message in client.receive_response():
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text)

async def main():
    async with ClaudeSDKClient() as client:
        await ask(client, "What's the capital of France?")
        # Same session, so the follow up keeps the context
        await ask(client, "What's the population of that city?")

asyncio.run(main())

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

// Streaming input mode: the prompt is an async iterable, so the session stays open
async function* userTurns() {
  yield {
    type: "user" as const,
    message: { role: "user" as const, content: "What's the capital of France?" },
    parent_tool_use_id: null,
  };
  // await the first answer here, then yield the follow up
}

const session = query({ prompt: userTurns() });

for await (const message of session) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}
// While it runs, session.interrupt() and session.setPermissionMode() are available

Read the stream

import asyncio
from claude_agent_sdk import (
    query, ClaudeAgentOptions, AssistantMessage, TextBlock, ResultMessage,
)

async def main():
    options = ClaudeAgentOptions(allowed_tools=["Read", "Glob"])
    async for message in query(prompt="List the Python files here", options=options):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text)
        elif isinstance(message, ResultMessage):
            print(message.subtype, message.num_turns, message.session_id)

asyncio.run(main())

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

for await (const message of query({
  prompt: "List the TypeScript files here",
  options: { allowedTools: ["Read", "Glob"] },
})) {
  if (message.type === "assistant") {
    for (const block of message.message.content) {
      if (block.type === "text") console.log(block.text);
    }
  } else if (message.type === "result") {
    console.log(message.subtype, message.num_turns, message.session_id);
  }
}

Sources: Python SDK reference · TypeScript SDK reference · How the agent loop works

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

schema = {
    "type": "object",
    "properties": {
        "title": {"type": "string"},
        "severity": {"type": "string", "enum": ["low", "medium", "high"]},
    },
    "required": ["title", "severity"],
}

options = ClaudeAgentOptions(
    output_format={"type": "json_schema", "schema": schema},
)

async def main():
    async for message in query(prompt="Triage: login page returns 500", options=options):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.structured_output)   # a dict that matches the schema

asyncio.run(main())

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

const schema = {
  type: "object",
  properties: {
    title: { type: "string" },
    severity: { type: "string", enum: ["low", "medium", "high"] },
  },
  required: ["title", "severity"],
} as const;

for await (const message of query({
  prompt: "Triage: login page returns 500",
  options: { outputFormat: { type: "json_schema", schema } },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.structured_output); // an object that matches the schema
  }
}

Three ways to widen what Claude can do: your own functions, servers you connect, and specialist agents you hand work to.

Recipe 1

Give Claude your own tool

A custom tool is a function wrapped in an in process MCP server.

Plugging in a tool

1. 1DefineWrap an async function with a name, a description and an input schema.
2. 2ServePass it to create_sdk_mcp_server and register the server under a key in mcp_servers.
3. 3CallClaude sees mcp__key__name. List that name in allowed_tools to skip the prompt.

PythonTypeScript

Copy

import asyncio
from claude_agent_sdk import (
    tool, create_sdk_mcp_server, query, ClaudeAgentOptions, ResultMessage,
)

@tool("add", "Add two numbers", {"a": float, "b": float})
async def add(args):
    return {"content": [{"type": "text", "text": f"Sum: {args['a'] + args['b']}"}]}

calculator = create_sdk_mcp_server(name="calculator", version="1.0.0", tools=[add])

options = ClaudeAgentOptions(
    mcp_servers={"calc": calculator},          # the key sets the tool prefix
    allowed_tools=["mcp__calc__add"],          # pre-approves the call
)

async def main():
    async for message in query(prompt="What is 12.5 plus 30?", options=options):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)

asyncio.run(main())

• The key in mcp_servers sets the prefix. Key calc and tool add give mcp__calc__add. Dots and spaces in the key become underscores.
• The handler must be async and return a dict with a content list. Set is_error (isError in TypeScript) to report a failure. An uncaught exception comes back to Claude as an error and the loop continues.
• Mark a tool read only (readOnlyHint) and Claude can run it in parallel. Custom tools run one at a time otherwise.
• TypeScript tools take a Zod schema, so install zod alongside the SDK.

Sources: Custom tools · Python SDK reference · TypeScript SDK reference

Recipe 2

Connect an MCP server

Point the SDK at a local process or a remote server, then allow its tools by prefix.

PythonTypeScript

Copy

import os
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    mcp_servers={
        # A local process: the SDK starts it and talks to it over stdio
        "docs": {"command": "node", "args": ["./my-mcp-server.js"]},
        # A remote server over HTTP
        "search": {
            "type": "http",
            "url": "https://example.com/mcp",
            "headers": {"Authorization": f"Bearer {os.environ.get('MCP_TOKEN', '')}"},
        },
    },
    # The key becomes the prefix, so mcp__docs__* allows every tool from that server
    allowed_tools=["mcp__docs__*", "mcp__search__*"],
)

• The key in mcp_servers becomes the tool prefix, so mcp__docs__* allows every tool from the docs server.
• A local server needs a command, with optional args and env. A remote one needs a url, with type set to http or sse, and optional headers.
• strict_mcp_config (strictMcpConfig in TypeScript) makes the SDK use only the servers you pass. It ignores .mcp.json, user settings, plugin servers and claude.ai connectors.
• In the TypeScript SDK, MCP servers connect in the background by default since 0.3.142 in mid May 2026. Set MCP_CONNECTION_NONBLOCKING=0 to wait up to 5 seconds before the first query again.

Sources: Connect to external tools with MCP · Custom tools · Python SDK reference · TypeScript SDK reference · TypeScript SDK changelog

Recipe 3

Hand work to a subagent

Define a specialist in code and Claude delegates to it through the Agent tool.

Delegating to subagents

1. 1MatchClaude matches the task to an agent by its description.
2. 2Hand offIt calls the Agent tool with a prompt written for that agent.
3. 3Report backThe subagent works with its own tools and context, then reports back.

PythonTypeScript

Copy

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Review the authentication module for security issues",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Grep", "Glob", "Agent"],
            agents={
                "code-reviewer": AgentDefinition(
                    description="Expert code review specialist. Use for security and quality reviews.",
                    prompt="You are a code review specialist. Report issues with file and line.",
                    tools=["Read", "Grep", "Glob"],   # read only
                    model="sonnet",
                ),
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

• The description tells Claude when to use the agent. The tools list limits what it can do. Leave tools out and it inherits every tool a subagent can use.
• Every docs example puts Agent in allowed_tools. A subagent starts with a fresh context and receives only the prompt Claude writes for it, unless Claude starts a fork.
• A programmatic agent wins over a same named file in .claude/agents. In Python, AgentDefinition fields are camelCase, and a snake_case keyword raises a TypeError.
• Agents spawn up to depth 3 and 20 at once by default (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH and CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS).

Sources: Subagents · Python SDK reference · TypeScript SDK reference

from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(
    system_prompt={
        "type": "preset",
        "preset": "claude_code",                # restores the Claude Code prompt
        "append": "Answer in two sentences.",   # your own rules go on top
    },
    setting_sources=["project"],                # [] loads no filesystem settings
    env={"ENABLE_PROMPT_CACHING_1H": "1"},      # merged over the parent environment
)

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

for await (const message of query({
  prompt: "Explain what this repo does",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code", // restores the Claude Code prompt
      append: "Answer in two sentences.", // your own rules go on top
    },
    settingSources: ["project"], // [] loads no filesystem settings
    // TypeScript replaces the environment, so spread process.env yourself
    env: { ...process.env, ENABLE_PROMPT_CACHING_1H: "1" },
  },
})) {
  if ("result" in message) console.log(message.result);
}

Sources: Agent SDK overview · Python SDK reference · TypeScript SDK reference

Sources: Permissions · Python SDK reference

Recipe 6

Ask before risky calls

A permission callback sees each call that is not already approved and answers allow or deny.

The approval gate

1. 1A call arrivesClaude asks to run a tool with some input.
2. 2The checks runHooks, deny rules, ask rules, the mode and allow rules decide first, in that order.
3. 3Your callbackIf nothing decided, can_use_tool answers allow or deny.

PythonTypeScript

Copy

import asyncio
from claude_agent_sdk import (
    query, ClaudeAgentOptions, PermissionResultAllow, PermissionResultDeny,
    ToolPermissionContext,
)

async def gate(tool_name: str, tool_input: dict, context: ToolPermissionContext):
    command = tool_input.get("command", "")
    if tool_name == "Bash" and "rm " in command:
        return PermissionResultDeny(message="Deletes are not allowed here")
    return PermissionResultAllow()

# Do not also list Bash in allowed_tools: allow rules run before the callback
options = ClaudeAgentOptions(can_use_tool=gate)

async def main():
    async for message in query(prompt="Clean up the temp files", options=options):
        print(message)

asyncio.run(main())

• The callback runs only when the permission flow falls through to a prompt. Calls approved by allowed_tools, allow rules or the mode never reach it.
• Do not also list the gated tool in allowed_tools. Allow rules approve the call before your callback runs, and the SDK warns about the overlap.
• In default mode with no callback, anything that needs approval is denied.

Sources: Permissions · Python SDK reference

Sources: Hooks · Python SDK reference · TypeScript SDK reference

Recipe 7

Block a command with a hook

A PreToolUse hook runs before the tool and can deny it with a reason Claude sees.

A hook at the scanner

1. 1Claude picks a callThe matcher checks the tool name, such as Bash.
2. 2Your hook looksA PreToolUse hook receives the tool input and can inspect it.
3. 3Allow or denyReturn a deny with a reason Claude can read, or an empty object ({}) to let the call continue.

PythonTypeScript

Copy

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher

async def block_rm_rf(input_data, tool_use_id, context):
    command = input_data["tool_input"].get("command", "")
    if "rm -rf" in command:
        return {
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "deny",
                "permissionDecisionReason": "Dangerous command blocked",
            }
        }
    return {}  # allow, no changes

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

async def main():
    async for message in query(prompt="Remove the build folder", options=options):
        print(message)

asyncio.run(main())

• Return an empty dict to allow with no changes.
• If several hooks disagree, deny beats defer, defer beats ask, and ask beats allow.
• A matcher filters on the tool name only, not on file paths. Check paths inside the callback.
• Hooks may not fire when the agent stops at max_turns.

Sources: Hooks · Python SDK reference

Aliases for the model option

Aliases move as new models ship and differ by provider (Bedrock and Google Cloud resolve sonnet to Sonnet 4.5 today). Pin a full ID such as claude-opus-5-5 when you need repeatable behavior.

Sources: Models overview · Pricing · Model configuration · Agent SDK configuration

• Use API key authentication, or a cloud provider, in anything you ship. Anthropic does not allow third party developers to offer claude.ai login or its rate limits in their products unless previously approved.
• Anthropic also bars routing requests through Free, Pro or Max plan credentials on behalf of your users, and bars collecting or storing claude.ai credentials or session tokens.
• Your own scripts are different. When you are signed in with your own plan, the SDK and claude -p still draw from the limits of that plan. On Oct 7, 2026 the Help Center added that Max and Team plans include monthly API credits for the SDK and claude -p when they run with a Console API key.
• Credential order, simplified: cloud provider variables first, then ANTHROPIC_AUTH_TOKEN, then ANTHROPIC_API_KEY, then other helpers, and subscription login last.

Sources: Legal and compliance · Use the Claude Agent SDK with your Claude plan · Authentication · Agent SDK quickstart · Agent SDK overview

Sources: Hosting the Agent SDK · Securely deploying agents · Subagents

Using Claude branding is optional. Your product should keep its own branding and not look like Claude Code or any Anthropic product.

Use of the SDK is governed by Anthropic Commercial Terms of Service, including when it powers products you offer to your own customers, except where a component or dependency carries its own license.

Sources: Agent SDK overview

1. Aug 4 · Python 0.2.129

   Breaking. Skill names are validated, so wildcards raise ValueError. Use skills="all" or a Skill rule in allowed_tools. Python SDK changelog

2. Aug 18 · Python 0.2.140

   ResultError added. can_use_tool works with query() and a string prompt. forward_subagent_text added. In process MCP servers support MCP 2.x. Python SDK changelog

3. Sep 22 to 23 · TypeScript 0.3.280, Python 0.2.158

   verbatim_prompts option: prompts are delivered as written, with no @path expansion or slash command dispatch. TypeScript SDK changelogPython SDK changelog

4. Sep 24 · TypeScript 0.3.282

   New smaller entry point, @anthropic-ai/claude-agent-sdk/core, and an alpha prewarm(). TypeScript SDK changelog

5. Sep 29 to 30 · Claude Code 2.1.285, TypeScript 0.3.286

   claude -p and Python SDK sessions with no permission mode started in auto mode on third party providers or with telemetry off. TypeScript followed the next day. Claude Code changelogTypeScript SDK changelog

6. Oct 7 · Help Center

   Max and Team plans now include monthly API credits that cover the SDK and claude -p when run with a Console API key. Use the Claude Agent SDK with your Claude plan

7. Oct 9 · Claude Code 2.1.296

   SDK cost estimates price Sonnet 5.5 cache reads at $0.10 per million tokens, down from $0.20. Claude Code changelog

8. Oct 14 · Python 0.2.166

   Typed hook output classes and a SystemInitData type. Python SDK changelog

9. Oct 16 · Claude Code 2.1.302

   No permission mode means default mode again, reversing Sep 29. Fork subagents are on by default. Claude Code changelog

10. Oct 26 · TypeScript 0.3.311

    Minimum Node version raised from 18.0.0 to 18.14.0. TypeScript SDK changelog

All dates are 2026. Both SDKs release almost daily, and most releases only bump the bundled Claude Code version. Read the changelogs before you take a minor release.

Package versions come from the PyPI and npm registries. Behavior, prices and dates come from Anthropic's official docs and changelogs, all read on Oct 28, 2026. The code examples were checked against the versions at the top of the page.

• Agent SDK overview
• Agent SDK quickstart
• Python SDK reference
• TypeScript SDK reference
• How the agent loop works
• Custom tools
• Permissions
• Hooks
• Subagents
• Sessions
• Structured outputs
• Cost tracking
• Hosting the Agent SDK
• Securely deploying agents
• Modifying system prompts
• Migration guide
• Models overview
• Pricing
• Model configuration
• Legal and compliance
• Use the Claude Agent SDK with your Claude plan
• claude-agent-sdk on PyPI
• @anthropic-ai/claude-agent-sdk on npm
• Python SDK changelog
• TypeScript SDK changelog
• Claude Code changelog
• Connect to external tools with MCP
• Agent SDK configuration
• Authentication
• Building agents with the Claude Agent SDK