How To Build Agentic AI With Claude, A Practical Guide To The Agent SDK
Agentic AI gets thrown around as a buzzword more than it gets explained. This guide breaks down what an agent actually is, how Claude's Agent SDK gives you one without building a tool loop from scratch, and how to run your first autonomous agent end to end.
Marcus Webb
July 20, 2026
Agentic AI Is Not Just A Chatbot With Extra Steps
Every product page uses the word agentic right now, and most of them are describing a chatbot with a plugin. A genuine agent is different in one specific way. It does not just answer a question, it decides what to do next based on what happened after its last action, and it keeps going through that loop without a human clicking continue after every step. Read a file, notice a bug, edit the file, run the tests, read the failure, try again. That loop is the whole point, and it is what Claude's Agent SDK gives you without you having to build the loop yourself.
The simplest test for whether something is actually agentic. Can it recover from an unexpected result without a person stepping back in? If yes, you are looking at an agent. If a person has to approve every single step, you are looking at a very capable chatbot wearing an agent's name.
What The Claude Agent SDK Actually Is
The Claude Agent SDK is Anthropic's official library for building autonomous agents in Python or TypeScript. It gives you the same agent loop, built in tools and context management that power Claude Code itself, so your own program can read files, run shell commands, search the web and edit code without you writing the tool execution logic from scratch. It used to be called the Claude Code SDK before it was renamed in late 2025, so if you run into an older tutorial that imports from claude_code_sdk or uses a class called ClaudeCodeOptions, that guide is out of date, the current package is claude_agent_sdk and the options class is ClaudeAgentOptions.
- Built in tools for reading files, running Bash commands, searching the web and editing code, ready to use without you writing a tool loop
- Runs on top of Claude Code as its runtime, so it inherits the same context management that makes Claude Code handle large codebases well
- Supports the same filesystem based configuration as Claude Code, including project memory, custom skills and slash commands
- Can connect to MCP servers, so an agent can reach tools like Slack, GitHub or Google Drive without you writing custom integration code
- Available on Amazon Bedrock, Google Vertex AI and Microsoft Foundry, not just the direct Anthropic API
Setting It Up
The SDK uses Claude Code as its runtime, so that gets installed first, then the SDK package for whichever language you are working in, then an API key from the Claude Platform Console.
# Install Claude Code, the runtime the SDK sits on top of
npm install -g @anthropic-ai/claude-code
# Install the Python SDK
pip install claude-agent-sdk
# Set your API key from the Console
export ANTHROPIC_API_KEY=your-api-keyIf your organization already runs on Bedrock, Vertex AI or Foundry, you can authenticate through those instead of a raw API key by setting the matching environment variable before you run your agent.
# Use Amazon Bedrock instead of a direct API key
export CLAUDE_CODE_USE_BEDROCK=1
# Use Google Vertex AI instead
export CLAUDE_CODE_USE_VERTEX=1
# Use Microsoft Foundry instead
export CLAUDE_CODE_USE_FOUNDRY=1Your First Agent, Start To Finish
Here is the smallest working example, an agent that looks at your current directory and reports what it finds using the SDK's built in tools. This is the exact shape the official docs use, and it is worth running as is before you customize anything.
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="What files are in this directory?",
options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"])
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())Once that runs, the more useful version is an agent that finds and fixes an actual bug, which is closer to what most people actually want an agent for.
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) # Claude reads the file, finds the bug, edits it
asyncio.run(main())Notice what is not in this code. There is no while loop checking whether the task is done, no manual parsing of a tool call response, no code deciding whether to try again after a failure. The allowed_tools list is the only real decision you are making, everything else is the agent loop the SDK already handles.
What Kind Of Agents People Actually Build With This
The bug fixing example is the classic demo, but it is not the ceiling. The same loop of gather context, take action, verify the result, repeat, applies to a lot of work that has nothing to do with code.
- Deep research agents that search across a large set of documents, cross reference facts between them and produce a written report
- Email assistants that read a thread, draft a reply that matches your tone, and file it for review
- Large scale code migration agents, the kind Anthropic itself has used internally to move code across frameworks at a scale no team would do by hand
- Security review agents that read through a codebase, score files by risk, and generate proof of concept tests for anything suspicious
- Internal support agents that resolve the routine tickets end to end and only hand off the ones a human actually needs to see
Agent SDK Versus Claude Code Versus The Raw API
People mix these three up constantly, so here is the actual difference. Claude Code is the finished product, an interactive terminal tool you use directly. The raw Anthropic API is the other extreme, you send prompts and you implement the tool execution loop yourself from nothing. The Agent SDK sits in the middle, it gives you Claude Code's engine, the agent loop, tool execution and context management, but lets you drive it from your own program instead of typing into a terminal.
An agent is not always the right tool. If you can hardcode the exact steps a task needs, a plain script will be faster, cheaper and more predictable than handing the same steps to an agent. Save the agent loop for problems where the steps genuinely cannot be known in advance.
What It Costs In 2026
The SDK itself is free and open source, what you pay for is the Claude API usage it generates. If you authenticate with a raw API key, standard pay as you go token rates apply, the same pricing that covers any other use of the Claude API.
Since June 15, 2026, Claude subscription plans also come with a separate monthly Agent SDK credit, so people building on a Pro, Max, Team or Enterprise plan are not forced onto pay as you go just to experiment. Pro includes a $20 monthly credit, Max 5x includes $100, and Max 20x includes $200, roughly €18 to €185, £16 to £160, or ₹1,660 to ₹16,600 depending on the tier. This credit is separate from your normal interactive usage limits for Claude Code and Claude chat, and it drains before anything else, falling back to standard usage credits once it runs out, if you have those enabled.
Good to know before you scale up. The monthly credit is sized for individual experimentation and small automations. If you are running shared production workloads across a team, Anthropic's own guidance points toward the Claude Platform with an API key instead, since that gives you predictable pay as you go billing rather than a shared credit that several people are drawing down at once.
Where To Actually Start
Install Claude Code and the SDK, run the file listing example exactly as written above so you know your setup works, then swap the prompt for a real task on a project you do not mind an agent touching. Keep the allowed_tools list tight while you are learning, an agent with fewer tools is easier to reason about and far easier to trust with something that actually matters.