Claude Agent SDK Tutorial: Build Autonomous AI Workers

The Claude Agent SDK (previously called the Claude Code SDK) is Anthropic’s toolkit for building AI agents that can autonomously read files, run commands, search the web, and execute real work on their own. If you’ve used Claude Code and wished you could build a custom version tailored to your specific workflow, the Agent SDK is how you do it. This tutorial walks through what it is, what it’s good for, and how to get your first agent running.

Source material for this guide: Anthropic’s official Agent SDK documentation, which is the authoritative reference for anything not covered here.

What the Agent SDK Actually Is

Per Anthropic’s docs, the Agent SDK lets you “build production AI agents with Claude Code as a library.” In practical terms: it’s the same agent loop, built-in tools, and context management that power the Claude Code CLI — but exposed as Python and TypeScript libraries you can import into your own applications.

The simplest way to think about it: the Claude Code CLI is a product. The Agent SDK is the engine. If you want to build your own product or internal tool that operates like Claude Code — reading files, running commands, working autonomously — the SDK is what you use.

Important naming note: The SDK was recently renamed from “Claude Code SDK” to “Claude Agent SDK.” If you’re reading older tutorials that reference the old name, the APIs are compatible but package names have changed. Anthropic maintains a migration guide for moving from the old SDK.

What You Can Build With It

The Agent SDK is designed for autonomous agents — workers that take a goal and figure out the steps themselves. Some examples from Anthropic’s own demo repo and real-world use cases:

• Code review agents that automatically review pull requests, flag issues, and suggest improvements
• Research agents that take a research question, search the web, read papers, and produce synthesized reports
• Email triage agents that categorize inbound email, draft replies, and route messages
• Data migration agents that read from one database, transform data, and write it elsewhere
• Bug-fixing agents that take an error report, trace the issue, and ship a fix via pull request
• Content generation pipelines that turn raw data (transcripts, logs, customer tickets) into polished output (blog posts, summaries, reports)
• Documentation bots that monitor a codebase and keep docs in sync with code changes

The key insight: these are all tasks where you want Claude to do work, not just tell you how to do work. That’s the difference between the Agent SDK and the regular Anthropic API.

Agent SDK vs. the Client SDK: What’s the Difference?

Anthropic offers two SDKs, and picking the right one matters.

The Anthropic Client SDK gives you direct API access. You send a prompt, Claude sends back a response. If Claude needs a tool, you implement the tool execution yourself and pass the result back. You control the loop. This is right when you need fine-grained control or you’re building something where tool use is minimal.

The Agent SDK gives you Claude with built-in tool execution. File reading, file editing, bash commands, web search, and web fetching all work out of the box. You describe the goal, Claude figures out the tool use autonomously. This is right when you want an agent that operates independently.

Rule of thumb: if the task involves more than 3 tool calls or you’d otherwise spend time implementing a tool loop, use the Agent SDK.

Getting Started: Your First Agent in 5 Minutes

The Agent SDK is available in Python and TypeScript. Pick whichever matches your existing codebase. Here’s the quickstart, adapted from Anthropic’s official quickstart guide.

Step 1: Install the SDK

For Python: pip install claude-agent-sdk

For TypeScript: npm install @anthropic-ai/claude-agent-sdk

Step 2: Get an API Key

Sign up at the Anthropic Console, create an API key, and set it as an environment variable: export ANTHROPIC_API_KEY=your-key-here. The SDK also supports authentication via Amazon Bedrock, Google Vertex AI, and Microsoft Azure if your company uses those platforms.

Step 3: Write Your First Agent

Here’s a minimal Python example from Anthropic’s docs:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Find and fix the bug in auth.py",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
    ):
        print(message)


asyncio.run(main())

That’s a complete working agent. It reads files, edits code, runs commands, and reports back. No tool loop to implement, no boilerplate.

Built-in Tools You Get for Free

The Agent SDK ships with the same tools that power Claude Code. According to Anthropic’s documentation, the key built-ins include:

• Read — Read any file in the working directory
• Write — Create new files
• Edit — Make precise edits to existing files
• Bash — Run terminal commands, scripts, git operations
• Glob — Find files by pattern like **/*.ts or src/**/*.py
• Grep — Search file contents with regex
• WebSearch — Search the web for current information
• WebFetch — Fetch and parse web page content
• AskUserQuestion — Ask the user clarifying questions with multiple choice options

You control which tools your agent is allowed to use by setting allowed_tools. This matters for safety: you probably don’t want a content generation agent running arbitrary bash commands.

Advanced Features Worth Knowing About

Hooks

Hooks let you run custom code at specific points in the agent lifecycle: before a tool runs, after it completes, when the agent finishes, when a user submits a prompt. Useful for audit logging, validation, blocking unsafe operations, or transforming inputs/outputs. Full hooks documentation.

Subagents

You can spawn specialized agents to handle focused subtasks. A lead agent coordinates the work, assigns subtasks to subagents with specific instructions, and merges the results. This is how you build complex multi-step workflows without cramming everything into one prompt. Subagent docs.

MCP (Model Context Protocol)

The Agent SDK supports the Model Context Protocol, an open standard for connecting AI to external services. Want your agent to use a browser? Connect the Playwright MCP server. Want it to query your database? Connect a database MCP server. There are hundreds of MCP servers available covering most common integrations.

Sessions

Sessions let you maintain context across multiple queries. Your agent can read a file in one query and then reason about it in the next without re-reading. For long-running tasks, this is essential. Sessions docs.

Permissions

Fine-grained control over what your agent can do. Pre-approve safe operations, block dangerous ones, or require interactive approval for sensitive actions. Critical for any production deployment. Permissions docs.

When to Use the Agent SDK vs. Claude Code CLI

Same capabilities, different use cases. From Anthropic’s docs:

• Interactive development → Claude Code CLI
• CI/CD pipelines → Agent SDK
• Custom applications → Agent SDK
• One-off tasks → CLI
• Production automation → Agent SDK

Many teams use both — CLI for daily development, SDK for production deployment. The prompts and workflows translate directly between them.

Pricing and Costs

The Agent SDK itself is free. You pay for Claude API usage, which scales with how much your agent reads, thinks, and writes. For Claude Sonnet 4.6 (the most common choice for agents), pricing is $3 per million input tokens and $15 per million output tokens. A typical small agent task might cost a few cents. See Anthropic’s pricing page for full details.

For volume usage, Anthropic offers batch pricing, prompt caching discounts, and priority service tiers. Worth looking at if you’re planning production deployment.

Resources and Next Steps

• Agent SDK Overview (Anthropic) — The authoritative documentation
• Quickstart: Build a Bug-Fixing Agent — Hands-on tutorial from Anthropic
• Example Agents on GitHub — Real working agents you can study and fork
• Python SDK Source — View the code and changelog
• TypeScript SDK Source — View the code and changelog
• Anthropic Developer Discord — Community support

If you’re new to Claude Code, start with our beginners guide to get comfortable with the CLI before moving to the SDK. The patterns you learn in the CLI translate directly to SDK code, and it’s a lower-friction way to internalize how Claude-based agents work.

Once you’re comfortable, the Agent SDK is what unlocks production automation at scale. You can build internal tools, customer-facing products, or pipelines that handle work autonomously while you sleep.

You May Also Like

• Claude Code: Complete Beginners Guide
• How to Use Claude AI: The Complete Beginners Guide
• Claude Code for Content Creators
• The 44% Rule: Find 44% More AI Use Cases in Your Business
• AI Content Repurposer: Turn One Article Into 10 Pieces of Content