Claude Agent SDK: we built a coding agent and tested it

The Claude Agent SDK lets you put Claude Code's AI agent inside your own program. An agent is an AI that plans its own steps: it reads files, changes code and runs commands until a job is done. We installed the SDK, built a small coding agent of about 30 lines, and gave it the same secret coding jobs as our Claude Code tests. It passed every check, in every setup. But out of the box, it also loaded our own personal Claude Code settings, which made each job about 18% more expensive.

What is the Claude Agent SDK?

An SDK is a set of building blocks for programmers. The Claude Agent SDK gives you the agent behind Claude Code as a library. You get the same tools to read and edit files and run commands, and the same permission rules. You also get the same loop in which the AI keeps working until the job is done. Anthropic's overview says it "runs the Claude Code binary". So under the hood, your program starts Claude Code and talks to it.

Anthropic has four ways to build with Claude. The Claude Code CLI is the tool you use yourself in a terminal. The Client SDK talks to the Claude API directly, but then you write the tool loop yourself. Managed Agents run on Anthropic's own computers. The Agent SDK sits in between: you get Claude Code's ready-made agent, but it runs inside your own app, script or pipeline.

It used to be called the Claude Code SDK. Anthropic renamed it because it can build agents "beyond coding tasks".

How to install it

You need Node.js 18 or newer for TypeScript, or Python 3.10 or newer for Python. Then one command is enough:

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

We installed version 0.3.296 for TypeScript and 0.2.165 for Python. Both bring their own copy of Claude Code, about 260 MB on Windows, so you do not have to install Claude Code separately.

To log in, the quickstart says to set an API key from the Claude Console as ANTHROPIC_API_KEY. An API key is a secret code for the paid connection between your program and Claude. You then pay per token: the small pieces of text an AI reads and writes. You can also go through Amazon Bedrock, Google Cloud or Microsoft Foundry. The SDK does not read .env files by itself, so load your key yourself.

Our agent in 30 lines

This is the whole agent we built. It reads the job from a file called TASK.md, lets Claude work on it, prints each tool Claude uses, and ends with the cost:

// A small coding agent with the Claude Agent SDK: it reads the job in TASK.md,
// changes the code, runs the tests with node, and reports what it cost.
// Run inside a project folder:  npx tsx agent.ts
import { readFileSync } from "node:fs";
import { query } from "@anthropic-ai/claude-agent-sdk";

const job = readFileSync("TASK.md", "utf8");

for await (const message of query({
  prompt: job,
  options: {
    model: "claude-sonnet-5-5",
    effort: "medium",
    settingSources: [], // do not load your own ~/.claude settings, skills or CLAUDE.md
    permissionMode: "dontAsk", // never ask; refuse every tool that is not listed below
    allowedTools: ["Read", "Edit", "Write", "Glob", "Grep", "Bash(node:*)"],
  },
})) {
  if (message.type === "assistant") {
    for (const block of message.message.content) {
      if (block.type === "tool_use") console.log(`tool: ${block.name}`);
    }
  }
  if (message.type === "result") {
    console.log(`done: ${message.subtype}, ${message.num_turns} turns, $${message.total_cost_usd.toFixed(3)}`);
  }
}

The important part is query(). You give it a prompt and options, and it sends back messages while Claude works: its thoughts, each tool it uses, and at the end a result with the cost. Three options matter most:

• allowedTools: which tools may run without asking. We allowed reading, editing, writing and running node.
• permissionMode: what happens with everything else. dontAsk refuses it, so the agent can never run another program. We tested what the other modes do in our skip-permissions test.
• settingSources: which of your own settings to load. More on that below.

We ran this agent in TypeScript and the same agent in Python on one of our jobs: splitting a bill. Both versions read the files, wrote the solution and tests, ran the tests and finished in 9 steps. Afterwards both passed all 17 secret checks. The Python run cost more ($0.16 against $0.09) because it used a slightly different version of Claude Code. Its cache, the short-term memory that makes repeated text cheap, was still empty.

How we tested

We used our secret test set: three small JavaScript jobs. Job D fixes a bug in a money reader. Job E splits a bill. Job F reads a CSV file. Each job came with a short note, and our secret checks only ran after the agent had finished. Our test page shows the jobs and how the checks work.

We ran each job three times through the TypeScript SDK with Sonnet 5.5, in three setups: 1. Default: no extra options. This is what you get if you copy the quickstart. 2. Isolated: settingSources: [] and an empty settings folder, so none of our own settings were loaded. 3. Isolated with the Claude Code prompt: like 2, plus the system prompt (the hidden instructions) that Claude Code itself uses. By default the SDK uses a much shorter one.

All three got the same tools and the same "medium" effort as our Claude Code runs. We compared them with Claude Code itself: the clean runs of our CLAUDE.md test on 10 October.

Did it work? Yes, every time

All four setups passed all 186 secret checks in all nine tries:

The isolated SDK agent was the cheapest: about 11 cents per job, against 14 cents for Claude Code itself. Part of that seems to be the shorter system prompt: with Claude Code's own prompt, the SDK agent cost $0.121. The rest may come from the newer Claude Code version inside the SDK. Speed was about the same everywhere: half a minute per job.

The cost is what the tokens would cost at Anthropic's list prices. The SDK reports this itself in total_cost_usd, and our own sum gave exactly the same number. For a bigger picture of prices, see our AI API price comparison.

Watch out: by default it loads your own setup

This was the biggest surprise. With the default options, the SDK loaded the personal Claude Code setup of the computer it ran on. That was the site owner's own CLAUDE.md file, 37 extra skills and one extra plugin. That is 7,700 extra tokens before the agent did anything, in every job.

In our test this did not change the score, but each job cost about 18% more. The bigger risk is that your agent behaves differently on each computer, because it follows the personal rules of whoever runs it. The 22 skills in the isolated setup are the ones built into Claude Code itself.

How to keep your agent clean

Anthropic's docs say it plainly: when you leave out settingSources, the SDK "reads the same filesystem settings as the Claude Code CLI". That includes CLAUDE.md files and the skills in .claude/ folders. So add one line to your options:

settingSources: [],

Two things are still read even then, the docs say: the global ~/.claude.json file and settings managed by a company. If you want to be fully sure, also point CLAUDE_CONFIG_DIR to an empty folder, as we did in our isolated setup. And if your agent needs project rules, load them on purpose with settingSources: ["project"] instead of everything.

Is the Claude Agent SDK free?

The SDK itself costs nothing. You pay for the AI model it uses: per token with an API key, or through Amazon, Google or Microsoft. In our test that was about 11 cents per small coding job with Sonnet 5.5. Bigger jobs read more text and cost more. Our Claude Code pricing article explains how those token costs add up.

"Free" does not mean open source. The Python code has an MIT licence. The TypeScript package says "All rights reserved" and points to Anthropic's terms, and its GitHub page lists no licence. The copy of Claude Code inside both falls under Anthropic's terms too.

If you build a product for other people, Anthropic says it must use an API key: you may not offer people a login with their claude.ai subscription, unless Anthropic agrees.

How we checked

We read Anthropic's Agent SDK pages on 11 October 2026: the overview, the quickstart, the TypeScript and Python references and the page about Claude Code features. We installed both SDKs in a separate test folder on our Windows 11 PC.

We ran the 27 SDK jobs on 11 October 2026 with Sonnet 5.5 and effort "medium". The SDK started its own Claude Code 2.1.296. For our test, the agent logged in with a token from the site owner's own Claude plan. We run all our Claude Code tests that way, so we did not pay per use. That is fine for your own tests, but for a product Anthropic wants an API key (see the screenshot). Costs are worked out from the token counts the SDK reported and Anthropic's list prices. The Claude Code comparison runs are from 10 October 2026, with Claude Code 2.1.280.

This was a small test: three short jobs, one model. The charts were made by us. The screenshots are real and cropped. None of the images was made by AI.