How to Build Your First Agent with Claude Agent SDK
The Claude Agent SDK is Anthropic’s library for building agents that use tools, with TypeScript and Python packages. It gives you the same loop that powers Claude Code — read files, run commands, call tools — so you write tools and prompts instead of orchestration plumbing.
Before this existed, building a tool-using agent meant writing your own loop: parse model output, detect a tool call, execute it, feed the result back, repeat. The SDK handles that cycle. That is the entire value proposition, and it is a real time saver once you have built one of these loops by hand.
What does the SDK actually provide?
An agent runner that manages the conversation loop, a tool interface, permission handling for dangerous operations, and session management so an agent can persist state across turns. Both TypeScript and Python packages are available.
The loop is the important part. You define tools as functions with schemas; the SDK exposes them to the model and executes the calls.
How do you get a minimal agent running?
- Install the package for your language:
npm install @anthropic-ai/claude-agent-sdkor the Python equivalent. - Export your Anthropic API key as an environment variable.
- Define one tool — a simple calculator or a file reader is enough.
- Create an agent with a system prompt and your tool list.
- Send a prompt that requires the tool and inspect the transcript.
Start with exactly one tool. Agents with six tools fail in confusing ways on the first day, and debugging tool selection is harder than debugging a single call.
What does running an agent cost?
You pay Claude API token rates, plus input for the system prompt and tool schemas on every turn. A modest agent with three tools and a 500-token system prompt sends maybe 1,500-2,000 input tokens per turn. Ten turns is 20,000 input tokens. Multiply by your traffic and the number gets real, so instrument token usage from day one.
How does this differ from calling the API directly?
| Approach | You write | Best when |
|---|---|---|
| Raw API calls | Whole loop + tool parsing | You need full control |
| Claude Agent SDK | Tools + prompt | Standard agent patterns |
| Hosted agent builders | Config only | No code deployment needed |
The SDK sits in a useful middle: less control than a hand-rolled loop, far less code than one. If your agent behaves like most agents, use it.
What should you watch out for?
Permission handling. The SDK can run commands and touch files, so an agent with shell access plus a bad prompt is a genuine risk. Default to denying dangerous tools and grant them explicitly per task.
Also, agent loops can spin. Always set a maximum turn count, even in a quick prototype, or a confused agent will burn tokens until you notice.
Good fit: developers building internal automation, coding tools, or data agents who want control without writing a framework. Bad fit: non-developers wanting a no-code agent builder.
Quick Summary
- The Claude Agent SDK provides the agent loop behind Claude Code, in TypeScript and Python.
- You define tools and a system prompt; the SDK runs the tool-call cycle.
- Include permission handling and deny dangerous tools by default.
- Costs are Claude token rates; input tokens repeat every turn.
- Always cap maximum turns to prevent runaway loops.
