Claude Code Agent SDK: The Complete Developer's Guide (2026)

Anthropic's Agent SDK turns Claude Code from a terminal assistant into a programmable, automatable AI agent you can embed in your own workflows. This guide covers everything: installation, the agent loop, tool integration, MCP servers, subagent orchestration, and the capability gaps you need to fill for production use.

What Is the Claude Code Agent SDK?

The Claude Code Agent SDK (also called the Claude Agent SDK or Claude Code SDK) is Anthropic's Python and TypeScript library for building autonomous AI agents powered by Claude. It wraps the same agent loop, tool system, and sandboxed execution environment that powers Claude Code the CLI — making it available as an SDK you can call from your own code.

The SDK was released in early 2026 as part of Anthropic's push to make AI agents programmable, not just interactive.

What Makes It Different From Using the Claude API Directly

If you're currently using the Claude API and writing your own agent loop with manual tool handling, the Agent SDK replaces hundreds of lines of boilerplate.

Installation and Setup

Prerequisites

• Python 3.10+ or TypeScript/Node.js 20+
• Anthropic API key (or Claude Code Pro/Max/Enterprise subscription)
• Claude Code CLI installed (the SDK uses it as a runtime)

Step 1: Install Claude Code CLI

npm install -g @anthropic-ai/claude-code

Or use the native installer from claude.ai/download.

Step 2: Install the Agent SDK

Python:

pip install claude-agent-sdk

TypeScript:

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

Step 3: Authenticate

claude login

Follow the OAuth flow. Your API key is stored locally and used by the SDK automatically.

Your First Agent: Bug Finder

Here's a minimal Python agent that scans a directory for bugs:

from claude_agent_sdk import Agent, tool

@tool
def read_file(path: str) -> str:
    """Read a file and return its contents."""
    with open(path, 'r') as f:
        return f.read()

@tool  
def list_files(directory: str = ".") -> list:
    """List all files in a directory."""
    import os
    return os.listdir(directory)

agent = Agent(
    system_prompt="You are a code reviewer. Find bugs, suggest fixes.",
    tools=[read_file, list_files],
    model="claude-sonnet-4-20250514"
)

result = agent.run("Review the code in ./src for security issues")
print(result.output)

What Happens Under the Hood

1. The agent receives the task and reads your system prompt
2. It calls list_files("./src") to discover the codebase
3. It calls read_file(path) for each source file
4. It analyzes the code using Claude's reasoning
5. It returns findings with line numbers and fix suggestions

The SDK handles the entire loop — you don't write any of the plan-act-observe logic.

Core Concepts

The Agent Loop

Task → Plan → Tool Call → Observe Result → Re-plan → ... → Final Answer

Each iteration:

1. Claude decides what to do next (plan)
2. It calls tools as needed (act)
3. It receives tool outputs (observe)
4. It decides whether to continue or finish

The SDK manages context window limits automatically through compaction (summarizing older turns) and subagent delegation.

Tools and the Tool Decorator

Tools are functions you expose to the agent. The SDK provides several built-in tools:

# Built-in file operations (auto-available)
agent = Agent(
    tools=["read", "write", "edit", "glob", "grep", "bash", "task"]
)

Custom tools use the @tool decorator:

from claude_agent_sdk import tool

@tool
def search_docs(query: str, max_results: int = 5) -> str:
    """Search internal documentation for a given query."""
    # Your search implementation
    return results

agent = Agent(tools=[search_docs])

Subagents: Parallel Processing

Subagents let you spawn independent Claude instances for parallel work:

agent = Agent(
    system_prompt="You are a tech lead reviewing a codebase.",
    tools=["task"]  # enables subagent spawning
)

result = agent.run("""
    Review ./frontend/ and ./backend/ in parallel. 
    Use subagents for each directory, then combine findings.
""")

Subagents run in isolated contexts and return results independently. This is how Claude Code itself handles large-scale operations.

MCP Server Integration

The SDK supports Model Context Protocol (MCP) servers — external services that expose tools to your agent:

agent = Agent(
    mcp_servers=[
        {
            "command": "npx",
            "args": ["-y", "@anthropic-ai/mcp-server-filesystem"],
            "env": {"ALLOWED_DIRECTORIES": "/project"}
        }
    ]
)

MCP servers can add database access, API integrations, third-party services, and more.

What the Agent SDK Can't Do (And How to Fill the Gaps)

The Claude Code Agent SDK gives your agents file access, shell execution, and code manipulation. But it has five major capability gaps:

1. Image Generation

Your agent can write code that calls image APIs, but it can't generate or see images directly. For an agent building a UI, prototyping a design, or creating documentation — this is a real limitation.

Solution: Give your agent a capability runtime that handles image generation. With one configuration line, your agent can generate images from text, iterate on designs, and embed the results.

2. Video Generation

Video is even further out of reach. Your agent can write ffmpeg commands but can't generate new video content.

3. Web Search with Grounded Results

Claude Code agents can use curl or fetch APIs, but they can't perform semantic web searches with grounded (cited) results. This matters for research agents, content agents, and any workflow needing up-to-date information.

4. Cloud Storage and File Sharing

The SDK's file system access is local-only. For agents that need to store outputs, share files with humans, or persist data across sessions, you need cloud storage.

5. Publishing and Deployment

Your agent builds the artifact, but getting it online — a web page, a shareable report, a deployed app — requires separate infrastructure.

The One-Command Fix

Rather than configuring five separate MCP servers (each with its own API key, maintenance burden, and token overhead), you can use a capability runtime — a single CLI tool that bundles image generation, video, web search, cloud storage, and publishing behind one endpoint.

For example, AnyCap gives agents five capabilities in one CLI — image generation, video, web search, cloud storage, and page publishing — so you spend minutes configuring, not hours.

Production Considerations

Context Window Management

The Agent SDK automatically handles context compaction, but for long-running agents (100+ turns), you should:

• Use subagents for large parallel tasks instead of sequential processing
• Keep system prompts concise — every token in system prompt is overhead on every turn
• Avoid loading large files into context when tools can return summaries instead

Cost Control

A typical agent session with the SDK costs $0.50-$3.00 depending on task complexity. To control costs:

• Set max_turns to prevent runaway loops
• Use Haiku for simple subagents and Sonnet for the main agent
• Monitor usage through Anthropic's console dashboard

Security

The SDK runs commands in a sandbox, but you should still:

• Restrict file system access with ALLOWED_DIRECTORIES
• Never give production agents access to credentials or .env files
• Review agent actions in non-interactive mode

Claude Code SDK vs Claude Agent SDK: What's the Difference?

These terms are often used interchangeably, but there is a distinction:

In practice, most developers use the Agent SDK as the entry point. The lower-level SDK APIs are for advanced use cases like custom session management.

When to Use the Agent SDK (vs Claude Code CLI)

The rule of thumb: if you're typing commands, use the CLI. If you're writing code that needs to call Claude, use the SDK.

Summary

The Claude Code Agent SDK transforms Claude from a terminal companion into a programmable agent runtime. With built-in file operations, shell access, subagent orchestration, and MCP server support, it handles the heavy lifting of agent infrastructure.

But an agent that can only read files and run bash is half an agent. To build agents that can search the web, generate images and video, store outputs in the cloud, and publish results — you need a capability layer. The SDK gives your agent the brain; a capability runtime like AnyCap gives it eyes, hands, and a voice.