Claude Agent SDK: Build Production AI Agents for Free (Complete Guide 2026)

What Is the Claude Agent SDK?

If you have been building with the Claude API, you know the pattern: send a message, get a response, parse it, maybe call a tool, send the result back. It works, but building a real agent — one that can read your codebase, run shell commands, search the web, and fix its own mistakes — requires hundreds of lines of orchestration code.

The Claude Agent SDK eliminates all of that. It packages everything that powers Claude Code (the CLI tool) into a library you can import into your own Python or TypeScript applications. One function call, one prompt, and you have a fully autonomous agent with 10+ built-in tools, MCP server connections, lifecycle hooks, and the ability to spawn subagents for parallel work.

Here is what makes this different from the standard Anthropic Python/TypeScript SDK: the Agent SDK is not a thin API wrapper. It is the same engine that runs Claude Code — file I/O, shell execution, web access, code editing, and multi-step reasoning are all built in. You are not building agent infrastructure. You are using the infrastructure Anthropic already built and tested at scale.

The SDK is free and open source. You pay only for the API tokens your agents consume. No license fees. No per-agent charges. No usage caps from the SDK side. If you have an Anthropic API key, you already have everything you need.

Key Features That Matter

The Claude Agent SDK is not a minimal wrapper — it ships with a serious feature set. Here is what you get out of the box, and why each piece matters for building production agents.

Built-in Tools (10+)

Every agent you build gets immediate access to these tools without any configuration:

• Read — Read any file from the filesystem, including images, PDFs, and Jupyter notebooks
• Write — Create new files or completely rewrite existing ones
• Edit — Surgical string replacements in existing files (send only the diff, not the full file)
• Bash — Execute shell commands with configurable timeouts and background mode
• Glob — Fast file pattern matching across any codebase size
• Grep — Content search powered by ripgrep with regex, type filtering, and context lines
• WebSearch — Search the web and get current information beyond the training cutoff
• WebFetch — Fetch and process web page content with built-in HTML-to-markdown conversion
• Monitor — Stream stdout from background processes as event notifications
• Agent — Spawn subagents for parallel task execution with their own tool access

MCP Integration

MCP (Model Context Protocol) is Anthropic's standard for connecting AI models to external data sources and tools. The Agent SDK has native MCP support, which means your agent can connect to any MCP server — databases, cloud APIs, SaaS platforms, custom services — and use those tools alongside the built-in ones. You configure MCP servers in the SDK options, and your agent sees them as additional tools it can call.

Hooks System

Hooks let you inject custom logic at specific points in the agent lifecycle. You can run code before or after tool calls, when a session starts, when the agent stops, before context compaction, and more. This is critical for production deployments where you need audit logging, permission checks, cost tracking, or custom validation.

For example, you can create a hook that blocks file writes to specific directories, logs every Bash command to an audit trail, or sends a Slack notification when the agent completes a task. Hooks execute as shell scripts or inline functions, and they can modify or abort the tool call.

Subagents

The Agent tool lets your primary agent spawn child agents that work in parallel. Each subagent gets its own context, its own tool access, and can work on a separate part of the problem. The parent agent coordinates the results. This is how you build agents that can, for example, analyze 10 files simultaneously, or research a topic from multiple angles, or run tests while writing code at the same time.

Session Management

Agents can maintain persistent sessions, which means they remember context across multiple interactions. You can resume a session, continue a conversation, or build long-running workflows where the agent picks up where it left off. Session IDs are returned after each interaction, and you can pass them back to continue.

Multi-Cloud Support

You are not locked into the Anthropic API. The Agent SDK works with AWS Bedrock, Google Vertex AI, and Azure. If your organization already has a cloud agreement with one of these providers, you can run Claude agents through that provider's infrastructure. Same SDK, same tools, different billing pathway.

Getting Started: Install to First Agent

Step 1: Install the SDK

Choose your language:

You also need Claude Code installed globally (npm install -g @anthropic-ai/claude-code) since the SDK uses it as the runtime engine.

Step 2: Set Your API Key

Step 3: Build Your First Agent (Python)

import asyncio
from claude_code_sdk import claude, ClaudeCodeOptions, query

async def main():
    # Simple one-shot agent
    result = await query(
        prompt="Analyze this Python project. Find all TODO comments, "
               "check for security issues, and write a summary report.",
        options=ClaudeCodeOptions(
            max_turns=10,
            model="claude-sonnet-4-6-20260416",
        )
    )

    # Process the results
    for message in result:
        if message.type == "text":
            print(message.content)

asyncio.run(main())

That is it. The agent will autonomously navigate your project, read files, run grep searches, and produce a report. No tool definitions needed — the 10+ built-in tools are already available.

Step 3b: TypeScript Version

import { claude, type ClaudeCodeOptions } from "@anthropic-ai/claude-code-sdk";

const options: ClaudeCodeOptions = {
  maxTurns: 10,
  model: "claude-sonnet-4-6-20260416",
};

for await (const message of claude("Analyze this project and find all bugs", options)) {
  if (message.type === "text") {
    console.log(message.content);
  }
}

Building Real Agents (Code Examples)

The quickstart examples above are simple. Here is what production agents actually look like — with MCP servers, hooks, permissions, and real-world prompts.

Code Review Agent

This agent reviews a pull request, checks for security issues, and posts comments:

from claude_code_sdk import query, ClaudeCodeOptions

result = await query(
    prompt="""Review PR #42 on this repo. Check for:
    1. Security vulnerabilities (SQL injection, XSS, auth bypass)
    2. Performance regressions
    3. Missing error handling
    4. Breaking API changes
    Write your findings as a markdown report.""",
    options=ClaudeCodeOptions(
        max_turns=15,
        allowed_tools=["Read", "Grep", "Glob", "Bash"],
        system_prompt="You are a senior security engineer reviewing code.",
    )
)

Data Pipeline Agent with MCP

Connect your agent to a database via MCP and let it run analytics:

result = await query(
    prompt="Query our production database for user signups "
           "this month. Compare to last month. Generate a "
           "chart and save it to reports/monthly-signups.png",
    options=ClaudeCodeOptions(
        max_turns=20,
        mcp_servers={
            "postgres": {
                "command": "npx",
                "args": ["-y", "@modelcontextprotocol/server-postgres"],
                "env": {"DATABASE_URL": "postgres://..."}
            }
        }
    )
)

Multi-Agent Orchestration

Build a pipeline where one agent manages multiple subagents:

result = await query(
    prompt="""You are a project manager agent. You have 3 tasks:
    1. Use the Agent tool to spawn a subagent that audits
       all dependencies for security vulnerabilities
    2. Use the Agent tool to spawn a subagent that runs
       the test suite and reports failures
    3. Use the Agent tool to spawn a subagent that checks
       code quality metrics
    Wait for all three, then write a combined report.""",
    options=ClaudeCodeOptions(
        max_turns=30,
        model="claude-opus-4-7-20260416",
    )
)

Agent SDK vs CLI vs Client SDK

There are three ways to work with Claude for coding and agent tasks. Here is how they compare:

When to use which:

• Agent SDK — You are building an automated pipeline, CI/CD integration, or any system where an AI agent needs to work autonomously
• Client SDK — You need maximum control over every API call and want to build your own tool execution layer
• CLI — You are a developer working interactively, pair-programming with Claude in your terminal

Pricing: What It Actually Costs

The Agent SDK has a beautifully simple pricing model: the SDK is free, you pay for tokens.

In practice, a typical agent run that analyzes a medium codebase (reading 10-20 files, running a few commands, producing a report) costs between $0.05 and $0.50 depending on the model and context size. Haiku 4.5 is absurdly cheap for lightweight agents. Sonnet 4.6 is the sweet spot for most production use cases. Opus 4.7 is for complex multi-step reasoning where accuracy matters more than cost.

If you use Claude Code Routines to run agents on a schedule, the API costs are the same — there is no additional charge for the scheduling infrastructure if you are on a Pro or Max plan.

FAQ

Video Explainer Slides

Key frames from the Claude Agent SDK video explainer.

AI Agent Development Framework Guide

What to Build Next

The Claude Agent SDK opens up a category of software that was previously impossible to build without massive infrastructure investment. Here are some high-impact projects to start with:

1. PR Review Bot — Trigger an agent on every pull request that does security review, style checking, and performance analysis
2. Codebase Documentation Agent — Point it at your repo and generate comprehensive docs, API references, and architecture diagrams
3. Automated Test Writer — An agent that reads your code and writes unit tests, integration tests, and edge case tests
4. Monitoring and Incident Response — An agent that watches logs, detects anomalies, and creates incident reports with root cause analysis
5. Content Pipeline — An agent that researches topics, writes drafts, generates images, and publishes to your CMS

The SDK documentation at docs.anthropic.com has full API references, and the GitHub repository has example agents to study. The barrier to entry is the lowest it has ever been for building production AI agents. The SDK is free. The tools are built in. The only limit is what you decide to build.

If you are exploring the broader AI coding tool landscape, check out our coverage of Claude Code, Cursor, Windsurf, and Claude Code Scheduled Tasks and Routines for the full picture of what is possible with AI-powered development in 2026.