The Claude Agent SDK in production.
Most Claude Agent SDK guides stop at a working demo. This one covers the part that decides whether the agent survives contact with a real business: the handbook, the files, the tools, and the logs.
Building the agent is the easy part. Keeping it alive is the job.
You can get a working Claude Agent SDK demo in about twenty minutes. Install the package, write a tool, hand it a task, watch it loop until the work is done. That part genuinely is that easy, and it is why so many teams now have an agent that impressed everyone in a meeting and has not been opened since.
The gap between that demo and something a business actually runs on is not model quality. It is everything around the model. We have put agents into purchase order processing, vendor risk review, and phone systems, and every single time the hard part was the same four things.
A loop that runs until the work is done.
The Claude Agent SDK is Anthropic's toolkit for agents that finish tasks instead of answering messages. Claude picks a tool, the SDK runs it, the result goes back into context, and the cycle repeats until the job is complete or a limit is hit. It ships for TypeScript and Python.
What you are really buying is the loop, plus the things you would otherwise write badly yourself: session state across turns, subagents for work that deserves its own context, permission hooks so a human can approve an action before it happens, and context compaction so a long task does not fall off the end of the window.
It is the same engine that runs Claude Code. That matters more than it sounds. The loop has been beaten on by a large number of engineers doing real work in messy repositories, which is not something you can say about most agent frameworks.
Not every problem is an agent problem.
The most common mistake we see is reaching for an agent loop when a single API call would do. Loops cost more, take longer, and fail in more interesting ways. Pick from the actual shape of the work.
| What you need | What to use | Why |
|---|---|---|
| Classify, extract, or summarize one thing | Messages API | One call in, one answer out. An agent loop here is cost and latency you do not need. |
| Multi-step work with an unknown number of steps | Agent SDK | This is exactly what the loop is for. Let the SDK own it instead of hand-rolling retries. |
| Answer questions over your documents | Agent SDK plus a retrieval tool | Retrieval as a tool the agent chooses to call beats stuffing every document into context. |
| A persistent build-time crew for your own team | Managed Agents | Anthropic hosts the sandbox and the state. Good internally. Not what you ship to a client. |
| A customer-facing agent inside your own product | Agent SDK in your app | You keep the key, the bill, the brand, and the URL. Nobody is renting your customer relationship. |
An agent is not magic. It is four parts working together.
This is the frame we use on every build, and the thing we check first when someone else's agent is misbehaving. The model is the smallest part of it. Three of the four are decisions you make, not code you write.
The Handbook
How the job is done here, written down.
This is the system prompt, but thinking of it as a prompt is what gets people into trouble. It is the onboarding document you would hand a new hire on day one. What this role owns. What good output looks like. Which edge cases come up and what to do about them. Who to escalate to and when. If a competent new employee could not do the job from what you wrote, neither can the agent.
Agents with thin handbooks improvise. They are confident and wrong, and nobody can tell you why.
The Files
The context it is allowed to read.
Policies, past decisions, the price list, the contract, last quarter's exceptions. Retrieval is where most agent quality actually comes from, and it is also where most of the risk lives. Scope the files to the job. An agent that can read everything is an agent that can leak anything, and it will also drown in irrelevant context long before it leaks.
Too few files and it guesses. Too many and it cites the wrong one with total confidence.
The Tools
What it can actually do, not just describe.
A tool is a function with a name, a description, and a typed input schema. Claude reads the description to decide when to call it, so the description is prompt engineering, not documentation. Keep each tool narrow and make the dangerous ones ask first. The split that matters most is read from write: an agent that can only read is a research assistant, and an agent that can write is an employee.
Vague tool descriptions cause the wrong tool to fire. Broad tools cause the wrong thing to happen.
The Logs
The receipts, so a human can check the work.
Every run should record what the agent read, which tools it called with which arguments, what came back, and what it concluded. Not for debugging, though it helps. For trust. The first question any operations lead asks is how they will know it is right, and the only good answer is that they can look. This is also the raw material for improving the handbook, because every wrong answer tells you exactly which instruction was missing.
No logs means no trust, and no trust means the agent gets switched off in month two.
Where the SDK meets a real runtime.
The Agent SDK assumes a filesystem and a process that stays alive. Most modern hosting gives you neither by default, and this is the single most common place a working local agent falls over on its first deploy.
On Vercel, functions do give you a writable temporary directory and a 300 second ceiling, which covers the large majority of agent turns. The rule we work to is simple. If a turn finishes inside that window, run it in the function. If it does not, put it on a queue and let a worker own it. If it needs no loop at all, drop back to the Messages API and save everyone the latency.
The other half of deployment is whose key it is. When we build an agent for a client it runs inside the client's own application, on the client's own Anthropic key, on the client's own domain. They own the bill, the brand, and the customer relationship. An agent you can only reach through someone else's platform is a dependency, not an asset.
Five failures we have seen more than once.
None of these show up in a demo. All of them show up in week two, which is why the gap between a prototype and a production agent is measured in judgment rather than code.
01The demo that cannot say no
An agent with no defined boundary will answer anything, including questions it has no basis to answer. Every agent needs an explicit list of what it does not do and what it says when asked. The sentence 'that is outside what I handle, here is who to ask' is a feature, and it has to be written into the handbook because the model will not invent it.
02Tools that do too much
One tool called update_record that can change any field on any object is the agent equivalent of handing someone root. Split it. Narrow tools produce narrow mistakes, and narrow mistakes are recoverable.
03The lethal trifecta
Access to private data, exposure to untrusted content, and the ability to send data out. Any one is fine. All three in a single agent is a data exfiltration path that a well-crafted email can trigger. Split it into two agents that pass a typed contract between them, with an allowlist on anything outbound.
04No human gate on the expensive action
Reading is cheap to get wrong. Sending, paying, deleting, and posting are not. Put a person in front of the irreversible ones until the logs have earned the trust to remove them. Gates you can remove later are much easier than trust you have to rebuild.
05Measuring the model instead of the work
Token counts and latency tell you nothing about whether the agent is doing the job. Pick the number the business already cares about, the hours, the error rate, the days in the cycle, and measure that before you start so you can measure it again at ninety days.
The questions that come up on every first call.
What is the Claude Agent SDK?
The Claude Agent SDK is Anthropic's toolkit for building agents that run a task to completion rather than answering a single message. It handles the agent loop for you: Claude decides which tool to call, the SDK runs it, feeds the result back, and repeats until the work is done. You write the tools and the instructions. It ships for TypeScript and Python.
How is the Agent SDK different from the Messages API?
The Messages API is one request and one response. If you want a loop, you write it: parse the tool call, execute it, append the result, call again, handle the errors. The Agent SDK owns that loop, plus session state, subagents, permission hooks, and context compaction. Use the Messages API for a single classification or extraction. Use the Agent SDK when the work has steps and you cannot predict how many.
Do I need LangChain or LlamaIndex with the Claude Agent SDK?
No. The Agent SDK covers the agent loop, tool calling, and session handling that those frameworks were built to provide. Adding one on top means two abstractions competing over the same control flow, and it makes the traces much harder to read when something goes wrong. Reach for a separate framework only when you need a specific piece it has and the SDK does not.
Can the Claude Agent SDK run on Vercel?
Yes, with one caveat worth knowing before you build. The SDK expects a filesystem and a long-lived process. Vercel functions give you a writable /tmp and a 300 second ceiling, which covers most agent turns. Anything genuinely long-running should move to a queue or a background worker, and anything that needs no loop at all is cheaper on the Messages API.
What does an AI agent actually need to work in a business?
Four things, and the model is only involved in one of them. A handbook that says how the job is done here, the files it is allowed to read, the tools it can act with, and logs that let a human check the reasoning before trusting the answer. An agent missing any one of these will demo well and fail in week two.
How long does it take to put an agent into production?
For a single well-scoped process with clean system access, days rather than months. The build is rarely the constraint. The constraint is deciding what the agent is allowed to do, getting credentials to the systems it needs, and agreeing what a wrong answer costs.
Bring us your worst process.
Thirty minutes, no deck and no discovery phase. Tell us the thing your team does by hand that everybody complains about, and we will tell you straight whether an agent should be doing it and roughly what that takes. If the answer is no, you will hear that too.