$catMANUAL||~54 min

Claude Agent SDK: Building AI Agents That Actually Do Stuff

advertisement

Claude Agent SDK: Building AI Agents That Actually Do Stuff

I spent a day messing around with Anthropic's new Claude Agent SDK, and honestly, it's a different beast from LangChain, CrewAI, or anything else I've tried. In short, it packages up Claude Code's core abilities — reading files, running commands, editing code, searching the web — into a programmable library. You don't implement tool calling logic yourself. The SDK handles it.

This post covers my hands-on experience, the gotchas I hit, and how it stacks up against other agent frameworks. If you're thinking about building automation with Claude, this should save you some time.

What Is Claude Agent SDK

Let me be clear about what it's NOT. It's not another LangChain. It's not another CrewAI. It's not another AutoGen.

The positioning is straightforward: it exposes Claude Code's capabilities as a library. Claude Code itself is a terminal-based AI coding assistant that can read code, edit code, run tests, and search the web. The Agent SDK wraps all that in Python or TypeScript so you can call it from your own programs.

The key difference? Frameworks like LangChain require you to define tools yourself, then let the LLM decide which to call. Agent SDK ships with tools built in. Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch — all ready to go. You don't write def read_file(path): .... It just works.

What does that mean in practice? Building an agent that automatically fixes bugs might take 20 lines of code.

Installation and Quick Start

Installation is simple. Python needs 3.10+, TypeScript needs Node.js 18+.

For Python:

bash
1
pip install claude-agent-sdk

Or with uv (recommended, faster):

bash
1
uv add claude-agent-sdk

For TypeScript:

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

You'll need an Anthropic API key. Sign up at platform.claude.com.

First mistake I made: forgot to set the environment variable and got an auth error. Make sure to export it:

bash
1
export ANTHROPIC_API_KEY="sk-ant-..."

Minimal Working Example

Create a buggy Python file utils.py:

python
1
def calculate_average(numbers):
2
    total = 0
3
    for num in numbers:
4
        total += num
5
    return total / len(numbers)
6
7
def get_user_name(user):
8
    return user["name"].upper()

Both functions have issues: calculate_average([]) divides by zero, get_user_name(None) throws a TypeError.

Then write the agent code agent.py:

python
1
import asyncio
2
from claude_agent_sdk import query, ClaudeAgentOptions
3
4
async def main():
5
    options = ClaudeAgentOptions(
6
        allowed_tools=["Read", "Edit", "Glob"],
7
        permission_mode="acceptEdits",
8
    )
9
10
    async for message in query(
11
        prompt="Read utils.py, find all bugs, and fix them with proper error handling.",
12
        options=options,
13
    ):
14
        if hasattr(message, "content") and message.content:
15
            print(message.content)
16
17
asyncio.run(main())

Run it:

bash
1
python agent.py

You'll see the agent automatically read utils.py, analyze the logic, and edit the file to add error handling. No manual intervention needed.

After it finishes, utils.py looks like this:

python
1
def calculate_average(numbers):
2
    if not numbers:
3
        return 0
4
    total = 0
5
    for num in numbers:
6
        total += num
7
    return total / len(numbers)
8
9
def get_user_name(user):
10
    if user is None or "name" not in user:
11
        return ""
12
    return user["name"].upper()

I'll be honest — the first time I saw this, I was impressed. Not because Claude can fix bugs (any LLM can do that), but because it decides on its own which file to read, what to change, and how to fix it. The entire tool loop is orchestrated by the SDK behind the scenes. You just provide a prompt.

Built-in Tools Breakdown

The built-in tools are the biggest selling point. No custom implementation needed:

  • Read: Read any file in the working directory
  • Write: Create new files
  • Edit: Precise edits to existing files (not full rewrites, targeted edits)
  • Bash: Run terminal commands, scripts, git operations
  • Monitor: Watch a background script and react to each output line as an event
  • Glob: Find files by pattern (like **/*.ts, 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

These tools aren't just for show. Real example — I had the agent find all TODO comments in a project:

python
1
async for message in query(
2
    prompt="Find all TODO comments in the codebase and list them with file paths and line numbers.",
3
    options=ClaudeAgentOptions(
4
        allowed_tools=["Grep", "Read"],
5
        permission_mode="acceptEdits",
6
    ),
7
):
8
    ...

The agent uses Grep to search for TODO, then Read to open each file and confirm context. Fully automatic.

The Power of Tool Combinations

Individual tools are boring. Combinations are where it gets interesting. Example: adding type annotations to a Python project.

python
1
prompt = """
2
1. Use Glob to find all .py files in the src/ directory
3
2. Read each file
4
3. Add type hints to all function signatures
5
4. Run mypy to check for type errors
6
5. Fix any errors mypy reports
7
"""

The agent follows this flow step by step: find files, read them, add type hints, run mypy, fix errors. If mypy reports new errors, it iterates automatically. This loop is managed by Agent SDK — you don't write a while loop.

Permission Control: Don't Let the Agent Nuke Your Server

This is the part I'd take seriously. The agent has a Bash tool, meaning it can run arbitrary commands. Without controls, it could theoretically execute rm -rf / (low probability, but not zero).

Agent SDK provides several permission modes:

  • acceptEdits: Auto-approves file edits and common filesystem commands, asks for everything else. Good for local development.
  • dontAsk: Denies anything not in allowed_tools. Good for headless agents.
  • auto (TypeScript only): Uses a model classifier to approve or deny each tool call. Autonomous agents with safety guardrails.
  • bypassPermissions: Approves everything. Only use in sandboxed or fully trusted environments.
  • default: Requires a canUseTool callback for custom approval flows.

I started with bypassPermissions because it was easy. Then the agent executed some Bash commands I didn't expect (it decided to pip install a package on its own). Switched to acceptEdits immediately.

My recommendation: Use acceptEdits for local dev, bypassPermissions for CI/CD (only if the CI environment is isolated), and default + custom callbacks for production.

Fine-Grained Control with allowed_tools

Beyond permission modes, you can use allowed_tools to control exactly which tools the agent can access:

python
1
# Read-only agent: can analyze but not modify
2
options = ClaudeAgentOptions(
3
    allowed_tools=["Read", "Glob", "Grep"],
4
    permission_mode="acceptEdits",
5
)
6
7
# Code modification agent: can read and edit, but no shell access
8
options = ClaudeAgentOptions(
9
    allowed_tools=["Read", "Write", "Edit", "Glob", "Grep"],
10
    permission_mode="acceptEdits",
11
)
12
13
# Full agent: everything goes
14
options = ClaudeAgentOptions(
15
    allowed_tools=["Read", "Write", "Edit", "Bash", "Glob", "Grep", "WebSearch", "WebFetch"],
16
    permission_mode="acceptEdits",
17
)

My personal rule: least privilege. Give Read only if that's all you need. Add Bash only when you need to run tests, and pair it with Hooks for auditing (more on that below).

Hooks: Agent Lifecycle Callbacks

Hooks are another killer feature. They let you insert your own code at key points during agent execution.

Available hook events:

  • PreToolUse: Before a tool call. Can intercept, modify arguments, or deny.
  • PostToolUse: After tool execution. Can log, modify return values.
  • Stop: When the agent stops executing. Can save state.
  • SubagentStart / SubagentStop: Subagent lifecycle events.
  • Notification: Agent status messages. Can forward to Slack or other notification systems.

Practical Example: Blocking Dangerous Operations

I wrote a Hook to prevent the agent from editing .env files (to avoid leaking secrets):

python
1
from claude_agent_sdk import query, ClaudeAgentOptions, HookResult
2
3
def block_env_edit(input_data, tool_use_id, context):
4
    file_path = input_data.get("tool_input", {}).get("file_path", "")
5
    if ".env" in file_path:
6
        return HookResult(
7
            permission_decision="deny",
8
            permission_decision_reason="Editing .env files is not allowed for security reasons.",
9
        )
10
    return HookResult()
11
12
options = ClaudeAgentOptions(
13
    allowed_tools=["Read", "Write", "Edit"],
14
    permission_mode="acceptEdits",
15
    hooks={
16
        "PreToolUse": [
17
            {"matcher": "Write|Edit", "hooks": [block_env_edit]}
18
        ]
19
    },
20
)

When the agent tries to edit .env, it gets blocked with a friendly rejection message.

Practical Example: Logging All File Changes

Audit requirements are common — you want to know exactly what the agent changed:

python
1
def log_file_changes(input_data, tool_use_id, context):
2
    tool_name = input_data.get("tool_name", "")
3
    tool_input = input_data.get("tool_input", {})
4
    if tool_name in ("Write", "Edit"):
5
        file_path = tool_input.get("file_path", "unknown")
6
        with open("audit.log", "a") as f:
7
            f.write(f"[{tool_use_id}] {tool_name}: {file_path}\n")
8
    return HookResult()

This logs every file modification to audit.log with tool name, file path, and call ID. Useful for debugging.

Subagents: Let the Agent Delegate Work

Subagents are an advanced feature. The main agent can spawn subagents for subtasks, and subagents report back with results.

This is similar to Hermes Agent's delegate_task. The main agent handles task decomposition and result aggregation; subagents handle execution.

python
1
from claude_agent_sdk import query, ClaudeAgentOptions, SubAgent
2
3
code_reviewer = SubAgent(
4
    name="code-reviewer",
5
    instructions="You are a code review specialist. Review code for bugs, security issues, and style problems.",
6
    allowed_tools=["Read", "Grep", "Glob"],
7
)
8
9
test_writer = SubAgent(
10
    name="test-writer",
11
    instructions="You are a test writing specialist. Write comprehensive unit tests using pytest.",
12
    allowed_tools=["Read", "Write", "Edit", "Bash"],
13
)
14
15
options = ClaudeAgentOptions(
16
    allowed_tools=["Read", "Write", "Edit", "Bash", "Agent"],
17
    permission_mode="acceptEdits",
18
    sub_agents=[code_reviewer, test_writer],
19
)
20
21
async for message in query(
22
    prompt="Review the code in src/ and write unit tests for all public functions.",
23
    options=options,
24
):
25
    ...

The main agent dispatches code-reviewer to review code, gets the results, then dispatches test-writer to write tests. Automatic orchestration.

Subagent Gotchas

One gotcha I hit: subagent allowed_tools must be configured separately. I forgot to add Bash to the test-writer subagent, so it wrote tests but couldn't run them. Subagents don't inherit the main agent's tool list — you must specify explicitly.

Another note: subagent messages include a parent_tool_use_id field for tracking which subagent is doing what. Very useful for debugging.

Sessions: Maintaining Context Across Calls

By default, each query() call is a fresh conversation. Some scenarios need context across multiple calls — like a long-running task that might need to pause and resume.

Agent SDK's Sessions solve this:

python
1
# First call, capture session_id
2
session_id = None
3
async for message in query(
4
    prompt="Analyze the codebase architecture and create a summary.",
5
    options=options,
6
    session_id=session_id,
7
):
8
    if hasattr(message, "session_id"):
9
        session_id = message.session_id
10
    print(message.content)
11
12
# Subsequent calls reuse the same session_id
13
async for message in query(
14
    prompt="Based on your previous analysis, identify the top 3 refactoring priorities.",
15
    options=options,
16
    session_id=session_id,
17
):
18
    print(message.content)

On the second call, the agent remembers what it analyzed before. No need to re-read files. Session data is stored as JSONL on the local filesystem.

This is particularly useful for multi-turn conversational agents. Think of a code assistant where the user asks things in sequence: "check this file" → "modify that function" → "run the tests". Each turn needs context from the previous one.

MCP Integration: Connecting External Systems

If you've used MCP (Model Context Protocol), you know it lets AI connect to various external tools and data sources. Agent SDK has native MCP support:

python
1
options = ClaudeAgentOptions(
2
    allowed_tools=["Read", "Write", "Edit", "Bash"],
3
    permission_mode="acceptEdits",
4
    mcp_servers={
5
        "memory": {
6
            "command": "npx",
7
            "args": ["-y", "@modelcontextprotocol/server-memory"],
8
        },
9
        "filesystem": {
10
            "command": "npx",
11
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
12
        },
13
    },
14
)

The agent can now use additional tools from MCP servers. The memory server provides persistent memory, the filesystem server provides safe filesystem access.

I tried connecting a PostgreSQL MCP server to have the agent query databases and generate reports. Worked well, but one gotcha: MCP tool names follow the pattern mcp__<server>__<action>. When matching in Hooks, use regex ^mcp__ instead of exact matches.

Comparison with Other Agent Frameworks

After using it for a while, here's how Agent SDK stacks up:

Agent SDK vs LangChain

LangChain is a general-purpose agent framework. You define tools yourself, write prompt templates, manage memory. Its strength is flexibility — supports nearly every LLM. Its weakness is that it's TOO flexible — the number of configuration options is overwhelming.

Agent SDK is Claude-exclusive. No custom tool definitions needed (built-in), no prompt templates (Claude knows how to use tools), no memory management (Sessions handle it). The downside: locked to Claude, can't swap to GPT or Gemini.

When to choose: If Claude is your primary model, Agent SDK's developer experience is far better than LangChain. If you need multi-model switching, LangChain is more suitable.

Agent SDK vs CrewAI

CrewAI is a multi-agent collaboration framework centered on "roles" and "tasks." You define agent roles (like "researcher," "writer," "editor") and assign tasks for them to collaborate on.

Agent SDK also has Subagents, but the approach is different. CrewAI's agents collaborate as peers; Agent SDK uses a master-subordinate pattern — the main agent assigns tasks, subagents execute and report back.

When to choose: Complex multi-role collaboration flows, go with CrewAI. One main agent with helpers, go with Agent SDK.

Agent SDK vs OpenAI Agents SDK

OpenAI also has its own Agent SDK (evolved from Swarm). Both have similar design philosophies — built-in tools, streaming output, handoff support.

The differences: Agent SDK has Claude Code's full tool suite (file operations, code editing, Bash), while OpenAI's leans more toward API calls and function execution. Agent SDK has Hooks and Sessions; OpenAI's is more lightweight.

When to choose: Code-related agents (auto bug-fixing, code review, automated testing), Agent SDK is stronger. API orchestration and business process automation, OpenAI Agents SDK is cleaner.

Real-World Use Cases

After a day of tinkering, here's where I think Agent SDK shines:

1. Automated Code Review in CI/CD

Run an agent in GitHub Actions to automatically review PRs:

python
1
async def review_pr(pr_diff):
2
    options = ClaudeAgentOptions(
3
        allowed_tools=["Read", "Grep", "Glob"],
4
        permission_mode="acceptEdits",
5
        system_prompt="You are a senior code reviewer. Focus on security issues, performance problems, and code style.",
6
    )
7
8
    review_comments = []
9
    async for message in query(
10
        prompt=f"Review this PR diff and identify issues:\n\n{pr_diff}",
11
        options=options,
12
    ):
13
        if hasattr(message, "content") and message.content:
14
            review_comments.append(message.content)
15
16
    return review_comments

2. Automated Test Generation

Given a source file, automatically generate corresponding tests:

python
1
prompt = """
2
Read src/api/users.py, then:
3
1. Create tests/test_users.py with comprehensive pytest tests
4
2. Cover all public functions
5
3. Include edge cases (empty input, None, invalid types)
6
4. Run the tests and fix any failures
7
"""

3. Codebase Documentation Generation

Have the agent traverse the entire project and auto-generate README and API docs:

python
1
prompt = """
2
Analyze the entire codebase:
3
1. Use Glob to find all source files
4
2. Read each file and understand the architecture
5
3. Generate a comprehensive README.md with:
6
   - Project overview
7
   - Installation instructions
8
   - API documentation
9
   - Usage examples
10
"""

4. Data Processing Pipelines

Agents don't just write code — they run it. You can have them handle data processing:

python
1
prompt = """
2
1. Read data/raw/sales.csv
3
2. Write a Python script to clean the data (remove duplicates, handle missing values)
4
3. Run the script
5
4. Generate a summary report with key statistics
6
5. Save the report to reports/sales_summary.md
7
"""

Gotchas and Lessons Learned

Gotcha 1: API Version Compatibility

Claude Opus 4.7 changed thinking.type.enabled to thinking.type.adaptive. Older SDK versions throw this error with Opus 4.7:

code
1
API Error: 400 {"type":"invalid_request_error","message":"\"thinking.type.enabled\" is not supported for this model."}

Fix: upgrade to Agent SDK v0.2.111+.

Gotcha 2: Python and TypeScript SDK Feature Parity

Some Hook events only exist in the TypeScript version. SessionStart, SessionEnd, MessageDisplay, PostToolBatch — Python doesn't support these yet.

If you need these advanced Hook features, you might have to use the TypeScript version. Or wait for Python to catch up.

Gotcha 3: Default Permission Mode Behavior

When you don't specify permission_mode, the SDK uses default mode, which requires a canUseTool callback. If you don't provide one, the agent hangs after reading a file, waiting for permission. First time I ran into this, I waited for ages before realizing it was waiting for a permission callback.

Gotcha 4: Subagent Tool Inheritance

Mentioned above — subagents don't inherit the main agent's allowed_tools. Must configure separately.

Gotcha 5: Session File Cleanup

Session data accumulates as JSONL files on the local filesystem. Clean up regularly, or use the SessionEnd Hook for automatic cleanup.

Deploying to Production

Local experimentation is fine, but the real value is production deployment. Agent SDK supports multiple deployment options:

Docker

Simplest approach — package as a Docker image:

dockerfile
1
FROM python:3.12-slim
2
WORKDIR /app
3
COPY requirements.txt .
4
RUN pip install -r requirements.txt
5
COPY . .
6
CMD ["python", "agent.py"]

Note: agents in Docker containers can only access the container's filesystem. Mount volumes if you need host filesystem access.

CI/CD Integration

Using Agent SDK in GitHub Actions:

yaml
1
- name: Run AI Code Review
2
  env:
3
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
4
  run: |
5
    pip install claude-agent-sdk
6
    python review_agent.py

Relationship with Managed Agents

Anthropic also offers Managed Agents — a hosted REST API where Anthropic runs the agent and sandbox for you. Agent SDK runs in your own process; Managed Agents run on Anthropic's infrastructure.

The official recommended path: prototype locally with Agent SDK, deploy to Managed Agents for production. That way you don't manage infrastructure yourself.

Wrapping Up

Claude Agent SDK isn't everything to everyone, but within its sweet spot — building Claude-based automation agents — it's the most hassle-free option I've used. Built-in tools eliminate tons of boilerplate, Hooks provide sufficient control, and Sessions solve context persistence.

Compared to LangChain, it's less flexible but way more productive. Compared to CrewAI, it's not suited for complex multi-role collaboration, but the single-agent-plus-subagents pattern covers most scenarios.

If you already use Claude Code, there's almost zero learning curve — they share the same tools and concepts. If you haven't used Claude Code, Agent SDK is a great entry point.

Next I'm planning to build an automated code review bot with Agent SDK, hooked into GitHub PR webhooks. I'll write that up when it's done. Questions? Drop them in the comments.

  • Written June 2026, based on the latest Claude Agent SDK. The SDK updates frequently — check the official docs for the latest.*

advertisement

Claude Agent SDK: Building AI Agents That Actually Do Stuff — AI Hub