claude-agent-sdk

Claude Agent SDK explained: build your first agent

by

So you’ve been using Claude Code, watching it read files, run tests, and keep itself on task across long jobs. And you’re wondering: how do I build that for myself? The Claude Agent SDK is the answer. It’s the same SDK Anthropic ships to power Claude Code, and you can use it to build your own agents in Python or TypeScript.

Most posts about the Claude Agent SDK stop at copy-pasting Anthropic’s quickstart. I’m going to skip that part. What follows is what I wish someone had told me before I started: how the SDK actually behaves at runtime, where it differs from the regular Anthropic SDK, what the agent loop really looks like, and the gotchas I hit building a small agent of my own.

If you just want the GitHub link, scroll down to the GitHub section. Stay if you want to know what to actually do with it.

Quick answer: what is the Claude Agent SDK?

The Claude Agent SDK is Anthropic’s official toolkit for building agentic applications with Claude. It wraps the Anthropic Messages API with built-in tools (file reading and editing, shell execution, web search, MCP server support), an agent loop that keeps running until the task is done, and hooks for observing or interrupting that loop. It’s available in Python (claude-agent-sdk) and TypeScript (@anthropic-ai/claude-agent-sdk), and it’s the same engine that powers Claude Code under the hood.

What is the Claude Agent SDK?

The Claude Agent SDK is the package Anthropic released to let developers build their own Claude-powered agents using the exact runtime Claude Code uses. Think of Claude Code as one product built on top of the SDK. Anything Claude Code does (reading files, editing code, running shell commands, calling tools, managing context across long sessions) is something your own program can do once you import the SDK.

Before this SDK existed, building an agent on top of Claude meant writing your own agent loop. You’d call the Messages API, parse the tool calls, execute them, send the results back, and handle the bookkeeping for context, errors, and stopping conditions. Workable, but a lot of code that everyone reinvented slightly differently.

The Anthropic Claude Agent SDK ships that loop as a library. You describe what tools the agent has, what its system prompt is, and what it’s allowed to do. The SDK handles the back-and-forth with the model, the tool invocations, the streaming output, and the lifecycle of long agent sessions.

One naming note that trips people up: the package used to be called the Claude Code SDK. Anthropic renamed it to the Claude Agent SDK in late 2025 to signal that it’s not just for code-editing use cases. If you search “claude code agent sdk” and land on old docs, you’re looking at the previous name. The current name is Claude Agent SDK.

Claude Agent SDK vs Anthropic SDK: when to use which

The Anthropic SDK and the Claude Agent SDK are two different things and the difference matters.

Anthropic SDKClaude Agent SDK
Package (Python)anthropicclaude-agent-sdk
SurfaceThe Messages API, rawThe Messages API + agent loop + tools
Tool executionYou implement itBuilt in
File and shell accessYou implement itBuilt in
MCP server supportYou wire it upFirst-class
Hooks and lifecycle eventsNoneBuilt in
Best forSingle-shot completions, chat appsLong-running agents, autonomous tasks

If you want to send a prompt and get a response, use the Anthropic SDK. If you want an agent that can read a file, decide to grep for something, run a test, fix the failure, and keep going until done, use the Claude Agent SDK. Both call the same underlying API. The agent SDK just owns the loop and the tool plumbing so you don’t have to.

A quick rule of thumb: if your program needs to call the model more than once based on what the model said last time, you probably want the Claude Agent SDK.

Install the Claude Agent SDK

Installing the Claude Agent SDK takes one command. Python or TypeScript, your pick.

For Python:

pip install claude-agent-sdk

For TypeScript:

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

You also need an Anthropic API key. Set it as an environment variable:

export ANTHROPIC_API_KEY="your-key-here"

The Python SDK requires Python 3.10 or newer. The TypeScript SDK works with Node 18+.

Build your first agent with the Claude Agent SDK

Building your first agent with the Claude Agent SDK is mostly an exercise in figuring out what not to write, because the SDK handles the agent loop for you. Here’s a minimum working example in Python:

import anyio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        system_prompt="You are a careful coding assistant.",
        allowed_tools=["Read", "Bash"],
    )
    async for message in query(
        prompt="List the Python files in this directory and tell me which one has the most lines.",
        options=options,
    ):
        print(message)

anyio.run(main)

That’s the whole agent. Three things are happening:

  1. query() is the entry point. It takes a prompt and options, returns an async iterator of messages.
  2. allowed_tools controls which built-in tools the agent can use. Here it can read files and run shell commands. Nothing else.
  3. The SDK handles the loop. The model decides it needs to run ls, the SDK runs it, sends the output back, the model decides to read files, the SDK reads them, and so on, until the model says it’s done.

Run it and you’ll watch the agent figure out the answer step by step. No tool invocation code on your side. No “if model said this, then do that” branching. The SDK has all of that built in.

Common built-in tools

The Claude Agent SDK ships with the same tools Claude Code uses:

  • Read – read files
  • Write – create files
  • Edit – modify files in place
  • Bash – run shell commands
  • Grep – search file contents
  • Glob – find files by pattern
  • WebFetch – fetch a URL
  • WebSearch – search the web

You toggle them on per-agent via allowed_tools. Leaving a tool out means the agent literally can’t use it, which is the right way to scope what an agent is allowed to do.

How the Claude Agent SDK powers Claude Code

Claude Code is the most visible product built on the Claude Agent SDK. The CLI you run in your terminal, the IDE extensions, the web app at claude.ai/code, they’re all surfaces over the same agent engine the SDK exposes.

That has two practical implications.

First, anything Claude Code does, you can do too. The file-editing primitives, the bash execution, the long-running session model, the hook system that fires on tool calls. All of it is in the SDK. If you’ve watched Claude Code work through a refactor or a debug session and thought “I want this for an automated job that runs every night,” the SDK is the path.

Second, the SDK is well-tested. Claude Code runs millions of agent loops a week across thousands of developers. Anything you’d hit early as an agent builder, the SDK team has already hit and fixed. That maturity is hard to overstate. It’s the difference between building on stable infrastructure and writing your own retry logic for the seventh time.

Custom tools and MCP servers with the Claude Agent SDK

The Claude Agent SDK doesn’t stop at built-in tools. You can extend it two ways.

Custom tools defined in your own code. Decorate a Python function and pass it to the agent:

from claude_agent_sdk import tool

@tool
def get_user_count(team_id: str) -> int:
    """Return the number of users on a team."""
    # Your real implementation here.
    return 42

The agent can call get_user_count like any other tool. Useful for exposing your own business logic.

MCP servers for cross-process tools. If you have a tool you want to share across multiple agents or projects, you build it as an MCP (Model Context Protocol) server and point the Claude Agent SDK at it. The SDK speaks MCP natively. Most teams I’ve seen end up with a small fleet of MCP servers (one for their internal API, one for their queue system, one for their docs) and the agents just pull from that pool.

If you haven’t built an MCP server before, the agent SDK doesn’t require it. Custom tools cover most cases. MCP is the upgrade path when one tool needs to be reused everywhere.

Common Claude Agent SDK gotchas

The same Claude Agent SDK gotchas show up the first time for almost everyone. Three to know up front.

Tool permissions matter more than they look. The agent will use any tool you give it. If you put Bash in allowed_tools, the agent might run arbitrary shell commands to solve its problem. For anything running unattended or in production, scope tools tightly. Start with the smallest set that solves the task and expand only when you need to.

The agent loop can run for a long time. Some tasks burn through hundreds of model turns. That’s normal for agents but unusual if you’re coming from one-shot API calls. Set a budget (tokens, wall-clock time, or both) and use the SDK’s hooks to enforce it. Otherwise you’ll discover the runtime bill the hard way.

Context grows. Plan for compaction. Long agent sessions accumulate conversation context. Eventually the SDK compresses earlier messages to fit the window. That’s automatic in the Claude Agent SDK, but if your agent depends on remembering something from 50 turns ago in exact detail, store it somewhere durable instead of trusting the in-memory transcript.

Where to find the Claude Agent SDK on GitHub

Searches for the Claude Agent SDK GitHub repo land on the official Anthropic organization. The repos are public.

Both repos host source, examples, and the changelog. The official documentation lives at docs.anthropic.com under the Agent SDK section, which is where API references and version-specific guides land first.

If you search “claude-agent-sdk github” and find an older repo named “claude-code-sdk”, that’s the previous name. It still exists as a redirect for now but new work happens in the renamed repos. Star the current ones to get release notifications.

What this gets you

You now have enough of the Claude Agent SDK to build something useful. A few real-world places teams are already using it:

  • Automated PR review bots that pull diffs, run tests, and post feedback comments.
  • Internal data agents that translate plain-English questions into SQL, run them, and explain the results.
  • Documentation assistants that read a private codebase and answer engineering questions in chat.
  • Operational agents that triage alerts, gather context from logs, and propose remediation.

None of these need a custom agent loop. The Claude Agent SDK is the loop. Your job is to decide what tools the agent has and what the success condition is. The SDK takes it from there.

FAQ

If you build something with the Claude Agent SDK that isn’t a code assistant, post the repo. Most of the example code in the wild right now is a slightly different shape of “AI pair programmer”. The interesting agents are the ones doing operational, analytical, or domain-specific work. Those examples are what newcomers learn the SDK from.

Leave a Comment

© 2024-26 Code with Rohit. All rights reserved.