Found something good?

If you've used Claude Code, you've seen what an AI agent can actually do: read files, run commands, edit code, figure out the steps to accomplish a task.

And you know it doesn't just help you write code, it takes ownership of problems and works through them the way a thoughtful engineer would.

The Claude Agent SDK is the same engine, yours to point at whatever problem you want, so you can easily build agents of your own.

It's the infrastructure behind Claude Code, exposed as a library. You get the agent loop, the built-in tools, the context management, basically everything you'd otherwise have to build yourself.

This guide walks through building a code review agent from scratch. By the end, you'll have something that can analyze a codebase, find bugs and security issues, and return structured feedback.

More importantly, you'll understand how the SDK works so you can build whatever you actually need.

What we're building

Our code review agent will:

The stack

• Runtime - Claude Code CLI
• SDK - @anthropic-ai/claude-agent-sdk
• Language - TypeScript
• Model - Claude Opus 4.5

What the SDK gives you

If you've built agents with the raw API, you know the pattern: call the model, check if it wants to use a tool, execute the tool, feed the result back, repeat until done. This can get tedious when building anything non-trivial.

The SDK handles that loop:

You also get working tools out of the box:

• Read - read any file in the working directory
• Write - create new files
• Edit - make precise edits to existing files
• Bash - run terminal commands
• Glob - find files by pattern
• Grep - search file contents with regex
• WebSearch - search the web
• WebFetch - fetch and parse web pages

You don't have to implement any of this yourself.

Prerequisites

Getting started

Step 1: Install Claude Code CLI

The Agent SDK uses Claude Code as its runtime:

After installing, run claude in your terminal and follow the prompts to authenticate.

Step 2: Create your project

Step 3: Set your API key

Your first agent

Create agent.ts:

Run it:

Claude will use the Glob tool to list files and tell you what it found.

Understanding the message stream

The query() function returns an async generator that streams messages as Claude works. Here are the key message types:

Building a code review agent

Now let's build something useful. Create review-agent.ts:

Testing It Out

Create a file with some intentional issues. Create example.ts:

Run the review:

Claude will identify the bugs, security issues, and suggest fixes.

Adding Structured Output

For programmatic use, you'll want structured data. The SDK supports JSON Schema output:

Handling permissions

By default, the SDK asks for approval before executing tools. You can customize this:

Permission modes

Custom permission handler

For fine-grained control, use canUseTool:

Creating subagents

For complex tasks, you can create specialized subagents:

Session management

For multi-turn conversations, capture and resume sessions:

Using hooks

Hooks let you intercept and customize agent behavior:

Custom tool calling

Tools are how agents interact with the world - reading files, calling APIs, querying databases, running code. The SDK includes built-in tools for common operations (filesystem, shell, web), but most agents will need custom tools to access your own systems.

The raw API pattern

Without the SDK, you manage the tool loop yourself:

Key points:

What the SDK handles

When you use built-in tools like `allowedTools: ["Read", "Glob"]`, the SDK manages all of this automatically - definitions, execution, and the loop.

For custom tools, you need a way to define them so the SDK can do the same. That's what MCP provides.

Adding custom tools with MCP

Extend Claude with custom tools using Model Context Protocol:

Cost tracking

Track API costs for billing:

Production code review agent

Here's a production-ready agent that ties everything together:

Run it:

What's next

The code review agent covers the essentials: query(), allowedTools, structured output, subagents, and permissions.

If you want to go deeper:

More capabilities

Production deployment

Full reference

This guide covers V1 of the SDK. V2 is currently in development. I will update this guide with V2 once it's released and stable. If you're interested in building verifiable agents, check out the work we're doing at @eigencloud here.