This page is for people who write software. If that isn’t you, the one sentence worth taking is that Claude Code’s engine is available as a library, so the tools your engineering team builds internally can have the same agent inside them that you use in the app — and then move on. Nothing elsewhere on this site depends on the rest.
For everyone else: there are three distinct rungs here, they’re often confused, and picking the wrong one is the most common way this work gets harder than it needed to be.
The three rungs
The raw Anthropic API is the direct line to the model. You send messages, you get a reply. It is excellent and it is a single exchange — classify this, summarise that, extract these fields.
Headless mode is Claude Code run as a command rather than a conversation: claude -p "…" takes a prompt, does the work, prints a result. Anything that can run a command can now run an agent. (There’s a hands-on walk-through of it in the Power Track.)
The Agent SDK gives your own program the full Claude Code engine as a library — for TypeScript or Python. The agent loop, the tools, the permission system, context management, MCP, hooks, subagents. In Python, the surface is about this small:
from claude_agent_sdk import query
async for message in query(prompt="Find and fix the failing test in this repo"):
print(message)Those few lines start an agent that reads files, runs commands, fixes the test and reports back — the same loop you’ve been driving by hand, now inside your program.
The distinction that matters: API vs SDK
This is the one worth being precise about, because reaching for the API when you wanted the SDK means rebuilding, badly, something that already exists.
The raw API answers once. If you want the model to actually run something, read what came back, and decide what to do next, you have to build that loop — call the tool, feed the output back in, ask again, handle the errors, decide when to stop. That loop is not a detail. It is most of the hard work in any agent, and it’s where homegrown agents usually break: not on the prompting, on the plumbing.
The raw API gives you the brain. The Agent SDK gives you the brain plus the body — the loop, the tools, the permission system, context management — already built and already load-bearing in a product people use daily.
| You want… | Reach for… |
|---|---|
| One question, one answer — classify, summarise, extract | the raw Anthropic API |
| A one-off agentic task inside a script or a job | headless mode |
| An agent as a component of a real program — custom tools, your own UI, branching logic | the Agent SDK |
The SDK is, almost literally, Claude Code with the front door removed so you can wire your own onto the same room.
Where headless ends and the SDK begins
It’s a spectrum, not a wall, and the honest rule of thumb is: don’t reach for the SDK until headless mode is visibly straining.
A one-off task in a script — regenerate this report, triage these files, run this check on a schedule — is headless mode’s job, and wrapping it in an SDK integration buys you nothing but code to maintain. You’ve outgrown headless when the agent stops being the whole program and becomes a part of one: you need your own tools exposed to it, your own UI around it, logic that branches on what it found, or several agents coordinating.
Most people never need the SDK. That’s not a failure to graduate — it’s headless mode being genuinely sufficient for most repeatable work.
What people actually build
The examples share a shape: a repeatable, agentic job too specific for a plain claude -p and too involved to babysit by hand.
- A custom reviewer inside a company’s own platform that reads a diff and posts findings where the team already works.
- A support agent that reads a customer ticket, digs through the codebase, and drafts a fix for a human to approve.
- A migration tool that walks a hundred repositories and applies the same change to each — the case where doing it by hand isn’t hard, just impossible at that count.
Where these things run: CI
The most common host for an unattended Claude is CI — the automated checks a project runs on every pull request. It’s a natural fit, because CI is already the place where a rule becomes team policy rather than personal habit: a check that runs there runs for everyone, every time, whether or not they remembered.
It also changes the risk profile, and it’s worth being deliberate about that. An agent in CI runs with nobody watching — there’s no approval prompt to catch a bad idea, because there’s no one at the keyboard to answer it. That makes two things load-bearing that you can be casual about interactively: the permission scope you hand it, and the blast radius of the environment it runs in. The useful instinct is to give an unattended agent the narrowest reach that still lets it do its job, and to prefer jobs whose output is a proposal — a comment, a draft PR — over jobs that land changes directly. Permissions and staying in control covers the reasoning; it applies with more force here, not less.
Where this sits
If you got here looking for “how do I make Claude run without me sitting there”, the mechanisms that fire on an event or a clock — hooks, schedules, loops — are hooks, schedules and loops. This page is the rung above: not triggering Claude automatically, but putting it inside something you’re building.
And the question of whether the thing you build is actually reliable — how you verify agent-written work rather than hope about it — is building reliably with agents, which is the concern that outlives whichever rung you picked here.
The words
- Agent SDK Claude Agent SDK
- A toolkit for TypeScript or Python that gives your own program the full Claude Code engine as a library — the agent loop, tools, permissions, context management, MCP, hooks and subagents — instead of a chat window around it.
- Headless mode claude -p
- Running Claude as a one-shot command instead of a conversation: you pass a prompt in, it does the work and prints a result, with no interactive session. In the CLI that's
claude -p "…". - CI continuous integration
- The automated checks a project runs on every change — typically on every pull request. Tests, linting, a build, sometimes a review pass. They run on someone else's machine, not yours, and report back pass or fail on the PR.
Questions people ask
- Should I use the Anthropic API or the Agent SDK?
- The API if you want one question and one answer — classify this, summarise that, extract these fields. The Agent SDK if you want something that explores, runs tools and iterates, because then you need the loop: call the tool, feed the result back, decide what's next, handle errors. That loop is most of the hard work in an agent, and the SDK is it, already built.
- When is headless mode enough, and when do I need the SDK?
- Headless mode (
claude -p) is enough for a one-off task inside a script or a scheduled job — and wrapping that in an SDK integration buys you nothing but code to maintain. You've outgrown it when the agent stops being the whole program and becomes a part of one: your own tools exposed to it, your own UI, logic that branches on what it found. Most people never cross that line. - What's different about running Claude in CI?
- Nobody is watching. There's no approval prompt to catch a bad idea because there's no one at the keyboard to answer it, which makes two things load-bearing that you can be casual about interactively: the permission scope you grant, and the blast radius of the environment. Prefer jobs whose output is a proposal — a comment, a draft PR — over jobs that land changes directly.