TokenMix Research Lab · 2026-04-25

Anthropic Claude Agent SDK: Quick Start Guide (2026)

Anthropic Claude Agent SDK: Quick Start Guide (2026)

Anthropic's Claude Agent SDK gives you Claude with built-in tool execution — file reading, shell commands, code editing — without implementing the tool-call loop yourself. The TypeScript SDK bundles a native Claude Code binary as an optional dependency, so you can build coding agents that read repos, find bugs, and fix them with minimal glue code. The main entry point is query, an async iterator that streams messages as Claude works. This guide covers installation, the quickstart pattern, advanced configuration (custom tools, hooks, MCP integration), and deployment across Anthropic direct, AWS Bedrock, Google Vertex AI, and Microsoft Azure. Verified against Claude Agent SDK docs as of April 2026.

Table of Contents

What the Claude Agent SDK Is

An SDK for building Claude-powered agents that can:

Two SDK variants:

Both expose similar APIs, both bundle Claude Code binary capability.

Installation

TypeScript:

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

The npm package bundles a native Claude Code binary for your platform as an optional dependency. No separate Claude Code install needed.

Python:

pip install claude-agent-sdk

Requirements:

Quickstart: Build a Bug-Fixing Agent

The canonical Agent SDK example — an agent that reads code, finds bugs, and fixes them:

TypeScript:

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

const result = query({
  prompt: "Find the bug in ./src/calculator.ts and fix it. Run the tests to verify.",
  options: {
    allowed_tools: ["Read", "Edit", "Glob", "Bash"],
    permission_mode: "acceptEdits",  // auto-approve file changes
  },
});

for await (const message of result) {
  console.log(message);
}

Python:

from claude_agent_sdk import query

async for message in query(
    prompt="Find the bug in src/calculator.py and fix it",
    options={
        "allowed_tools": ["Read", "Edit", "Glob", "Bash"],
        "permission_mode": "acceptEdits",
    },
):
    print(message)

The agent:

  1. Starts with Claude Opus 4.7 (or configured default)
  2. Uses tools to explore your codebase
  3. Identifies problems
  4. Makes fixes
  5. Runs tests to verify
  6. Streams each step back as messages

Built-in Tools

By default, Claude has access to the full Claude Code toolset:

Tool Purpose
Read Read file contents
Write Create new files
Edit Modify existing files
Bash Execute shell commands
Glob Find files by pattern
Grep Search file contents
WebSearch Search the internet

Tool restriction: pass allowed_tools in options to whitelist specific tools — critical for security in production.

Configuration Options

Key options for query:

allowed_tools: string[] — whitelist of tools. Pass only the subset your agent needs.

permission_mode:

model: choose Claude variant. Defaults to latest Opus.

options: {
  model: "claude-opus-4-7",  // or claude-sonnet-4-6, claude-haiku-4-5
  allowed_tools: ["Read", "WebSearch"],
  permission_mode: "acceptEdits",
}

working_directory: sandbox file operations to specific directory.

max_turns: cap agent loop depth to prevent runaway execution.

Custom Tools via MCP

Custom tools are implemented as in-process MCP servers — Python functions or TypeScript handlers defined directly in your app. No separate MCP server deployment needed.

Python example:

from claude_agent_sdk import ClaudeSDKClient

def fetch_customer_data(customer_id: str) -> dict:
    # Your business logic
    return {"id": customer_id, "name": "..."}

client = ClaudeSDKClient(
    custom_tools=[fetch_customer_data],
)

async for message in client.query(
    prompt="Look up customer 42 and summarize their recent orders",
):
    print(message)

Claude sees the function signature and docstring, decides when to call it, and receives the return value.

Why MCP-based custom tools matter:

Supported LLM Providers and Model Routing

Claude Agent SDK uses Anthropic models. Accessible via:

For teams running agent workflows across Claude and non-Claude models, TokenMix.ai provides OpenAI-compatible access to Claude Opus 4.7, Sonnet 4.6, Haiku 4.5, GPT-5.5, DeepSeek V4-Pro, Kimi K2.6, Gemini 3.1 Pro, and 300+ other models through a single API key. The Claude Agent SDK uses Anthropic-native auth for Claude specifically, but for polyglot agent stacks, route non-Claude calls through an aggregator.

Multi-Cloud Deployment

Agent SDK supports major cloud providers via environment variables:

AWS Bedrock:

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
# AWS credentials via standard AWS auth

Google Vertex AI:

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-central1
export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project

Anthropic Direct:

export ANTHROPIC_API_KEY=sk-ant-api03-...

Switch between providers without code changes — useful for cost optimization, compliance, or multi-region deployment.

Advanced: ClaudeSDKClient and Hooks

ClaudeSDKClient is the full-feature class for custom agent logic:

Hooks let you intercept agent behavior:

from claude_agent_sdk import ClaudeSDKClient

async def before_tool_hook(tool_name: str, tool_args: dict):
    # Log, validate, or modify before execution
    print(f"About to call {tool_name}")
    return tool_args

client = ClaudeSDKClient(
    hooks={"before_tool": before_tool_hook},
)

Use cases for hooks:

Known Limitations

1. Claude-specific. SDK is built for Claude models. For multi-model agents, use a framework like LangGraph or CrewAI with Claude as one backend.

2. Built-in tools are OS-level. Read/Write/Edit/Bash affect host filesystem. Sandbox appropriately (Docker, dedicated VMs).

3. bypassPermissions is dangerous. Skipping permission prompts in unsandboxed environments lets the agent modify anything. Only use in controlled contexts.

4. Async-only. SDK is async-native. Sync wrappers exist but some features require async context.

5. Tool visibility limited. For deep tool-call tracing, pair with observability tools (LangSmith, Langfuse, Helicone).

6. Claude Code binary is bundled. Adds ~50-150 MB to installed package size.

FAQ

Is Claude Agent SDK the same as Claude Code?

Related but not identical. Claude Code is the end-user CLI; Claude Agent SDK is the programmatic library that Claude Code is built on. You can build custom agents with Agent SDK that look nothing like Claude Code.

Do I need to install Claude Code separately?

No. The TypeScript SDK bundles the Claude Code binary as an optional dependency. Python SDK manages its own execution environment.

Can I use this with Claude Haiku 4.5?

Yes. Set model: "claude-haiku-4-5" in options. Useful for cost-sensitive agent loops where Haiku's quality is adequate.

How does this compare to LangGraph?

LangGraph is a framework for building agents from scratch with full control. Claude Agent SDK is opinionated — built for Claude-specific agent patterns with faster time-to-first-agent. Pick based on control vs convenience.

Can I use my own MCP servers?

Yes. Register external MCP servers alongside or instead of in-process custom tools.

Is this production-ready?

Yes. Claude Agent SDK is used in production at Anthropic customers. Follow standard agent deployment practices (sandboxing, observability, rate limits).

How do I debug agent runs?

Stream messages from the query iterator — each step is a separate message. For deeper debugging, integrate LangSmith or Langfuse for trace visualization.

Can I combine Claude Agent SDK with GPT-5.5?

Not directly. Agent SDK is Claude-specific. For cross-model agents, use LangGraph with Claude as one node and GPT-5.5 as another — both via TokenMix.ai aggregator for unified billing.

What's the async iterator pattern?

Modern async Python/TypeScript pattern. async for processes each agent step as it completes, without waiting for full run. Enables real-time UI updates during agent execution.

Where can I see examples?

Anthropic's official quickstart docs, the claude-agent-sdk GitHub repo, and Promptfoo's provider docs (link in sources). Sample projects on GitHub as the ecosystem grows.

Related Articles

Author: TokenMix Research Lab | Last Updated: April 25, 2026 | Data Sources: Claude Agent SDK overview, Claude Agent SDK Quickstart, claude-agent-sdk-python GitHub, @anthropic-ai/claude-agent-sdk npm, Promptfoo Claude Agent SDK provider, TokenMix.ai multi-model agent routing