How to Build a Claude Agent
Four approaches, and how to tell which one you actually need
A practical guide to building production agents on Anthropic's Claude: the four ways to do it, the axis that separates them, how to design a tool surface, and what determines whether the thing survives contact with real usage.
How do you build an agent with Claude?
Four ways, separated by two questions: who supplies the harness (the agent loop and context management), and who supplies the deployment. Write the loop yourself against the Messages API. Use the Anthropic SDK's Tool Runner, which drives the loop over tools you define. Use Managed Agents, where Anthropic runs the loop and hosts a per-session sandbox. Or use the Claude Agent SDK, which is Claude Code packaged as a library with built-in file and bash tools. Only Managed Agents supplies both harness and deployment; the other three leave hosting to you.
Key Facts:
- Manual loop: you build the harness, you host. Maximum control
- Tool Runner: SDK drives the loop over your tools, you host. Most common choice
- Managed Agents: Anthropic runs the loop and hosts the sandbox
- Claude Agent SDK: Claude Code as a library, built-in tools, you host
- Tool Runner and Claude Agent SDK are different packages, not the same thing
Before Anything Else: Should This Be an Agent?
The agent loop is not free. It costs more tokens, more latency, and considerably more unpredictability than a single model call, and a large share of the disappointment in this space comes from reaching for it when a simpler build would have worked.
There is a reasonable four-part test. Is the task genuinely multi-step and hard to fully specify in advance, or is it one well-defined operation? Does the outcome justify the higher cost and latency? Is Claude actually capable at this task type? And can errors be caught and recovered through tests, review, or rollback?
If any of those is a no, drop a tier. Classification, extraction, summarization and structured question-answering are single calls. Multi-step pipelines where your code controls the sequence are workflows, not agents: you orchestrate, the model does the language work at each step. Reserve the agent pattern for open-ended, model-directed exploration, which is the only thing it does that the simpler tiers cannot.
Turning down the agent pattern is not a failure of ambition. Most production AI that actually earns its cost is a single call or a workflow.
The Four Approaches
The two columns that matter are who supplies the harness and who supplies the deployment. Options one, two and four all leave hosting to you; only Managed Agents adds managed deployment.
| Approach | You write | Harness & deployment | Tools available | Choose it when |
|---|---|---|---|---|
| Manual loop | The loop itself: call, check for tool use, execute, append result, repeat | You build the harness; you host | Only tools you define | You want to own the entire loop, avoid a beta dependency, or have control flow the Tool Runner's hooks do not fit |
| Tool Runner | Just the tool functions | SDK supplies the loop (harness only); you host | Only tools you define | You want a custom-tool agent without hand-writing the loop. This covers most cases |
| Managed Agents | Agent config, plus results for your own tools | Anthropic supplies the harness and hosts a per-session sandbox | Anthropic-hosted sandbox (bash, files, code execution) plus Skills, MCP, and your tools | You want Anthropic to run the loop and host the workspace; you need persisted, versioned configs or long-running sessions |
| Claude Agent SDK | A prompt and some options | SDK supplies the Claude Code harness and built-in tools; you host | Built-in read, write, edit, bash, glob, grep, search, plus MCP and subagents | You want a batteries-included coding or filesystem agent running on your own infrastructure |
The Claude Agent SDK is a separate product from the Anthropic API SDK, with its own package and its own documentation. Everything else in this table is the Messages API.
The Distinction Everyone Gets Wrong
Tool Runner and Claude Agent SDK are not the same thing.
These two get conflated constantly, including in a lot of published writing, and the confusion costs people real time because they reach for one expecting the other's behavior.
The Tool Runner is part of the regular Anthropic API SDK. You reach it through the client, and it automates the request, execute, loop cycle for tools you define. It ships no built-in tools, no filesystem access, and no sandbox. You supply every tool and you host the compute. Think of it as a thin, well-designed helper over the Messages API that saves you writing a while loop.
The Claude Agent SDK is a different package entirely. It is Claude Code packaged as a library: built-in file read, write and edit, bash, grep and web search, the full agent loop, context management, hooks, subagents, permissions and sessions. You give it a prompt and options and it drives everything.
Why the difference matters in practice
If you want an agent that operates on a codebase or a filesystem, the Agent SDK gives you that on day one and the Tool Runner means writing every file tool yourself. If you want an agent that calls your internal APIs and nothing else, the Agent SDK's built-in tools are surface area you did not ask for and the Tool Runner is the cleaner fit.
Both are harness-only. Neither gives you managed deployment, which is the thing that actually distinguishes Managed Agents from all three of the others.
Rule of thumb: filesystem or coding agent, reach for the Claude Agent SDK. Agent over your own APIs, reach for the Tool Runner. Want someone else to host the sandbox and run the loop, reach for Managed Agents.
Designing the Tool Surface
This is where agent projects are won or lost, and it is a security design exercise as much as an engineering one.
Start with bash, then promote
A bash tool gives the model enormous programmatic reach, which is why it is a good starting point. But it gives your harness only an opaque command string, identical in shape for every action, so it cannot gate or audit anything meaningfully.
Promote on reversibility
Actions that are hard to undo (sending a message, deleting data, calling an external API, moving money) deserve their own tool. A dedicated tool gives the harness typed arguments it can intercept and require approval for. Gating a send_email tool is easy; gating a curl inside a bash string is not.
Promote for staleness and rendering
A dedicated edit tool can reject a write if the file changed since the model last read it, an invariant bash cannot enforce. And actions that need custom UI, like asking the user a question, need to be tools so the harness can render and block on them.
Promote for parallelism
Read-only tools can be marked parallel-safe. When the same actions go through bash, the harness cannot distinguish a safe concurrent search from an unsafe write, so it has to serialize everything.
Write descriptions that say when
The model decides whether to call a tool largely from its description. Prescriptive descriptions that state the trigger condition, not just what the tool does, measurably improve how often it gets called at the right moment.
Keep the set focused
Too many tools degrades selection quality. If you genuinely have a large library, tool search lets the model discover relevant schemas on demand instead of carrying all of them in context.
Context and Cost on Long-Running Agents
The context problem
An agent that runs for a long time accumulates history: old tool results, completed reasoning, superseded findings. Left alone it will eventually exhaust the context window, and long before that it will be spending money re-reading things that no longer matter.
There are three distinct mechanisms and they solve different problems. Context editing prunes, clearing stale tool results or thinking blocks outright. Compaction summarizes, condensing earlier history when you approach the limit. Memory persists across sessions, letting the agent write notes it can read in a future run. Long-running agents often use all three.
Prompt caching is the cost lever people miss
Caching is a prefix match. Any byte that changes anywhere in the prefix invalidates everything after it, and the render order is tools, then system prompt, then messages.
The practical consequence is that a timestamp interpolated into your system prompt makes the entire conversation uncacheable, forever, on every request. So does a per-request UUID, non-deterministic JSON key ordering, or a tool list that varies between users. Keep the stable content first and frozen, put anything volatile after the last cache breakpoint, and verify by checking whether cache reads are actually happening rather than assuming.
On a high-volume agent this is not a micro-optimization. Cache reads cost a fraction of full-price input tokens, and a silently broken cache can multiply your bill several times over with no other symptom.
Effort and task budgets
Effort controls how deeply the model reasons and, importantly, how much it does: lower effort produces fewer and more consolidated tool calls, less preamble, and terser output. It is the first lever to reach for on both cost and latency, and the right setting is workload-specific enough that it is worth sweeping rather than guessing.
Task budgets are different. They tell the model roughly how many tokens it has for a whole agentic loop so it paces itself and finishes gracefully rather than being cut off mid-thought. That is a suggestion the model can see and plan against, unlike a hard output cap, which it cannot.
The Four Ways Agent Projects Fail
In roughly the order we see them.
It should not have been an agent
The task was a single call or a workflow, and the agent pattern added cost and unpredictability without adding capability. This is the most common failure and the cheapest to avoid, because the four-part test takes ten minutes.
No evaluation harness
It was tested by trying it a few times. Agents fail in ways conventional testing does not surface, and without measurement against real cases you find out in production.
The tool surface was an afterthought
Everything went through one broad tool, so nothing could be gated, audited, or parallelized, and the first time the agent did something surprising there was no seam to intervene at.
Nobody budgeted the run cost
The build was funded and the ongoing model, infrastructure and maintenance spend was not. This one is especially cruel because it scales with adoption: the more successful the agent, the faster it becomes a budget problem.
Building Claude Agents, FAQ
Common questions from engineers building their first production agent.
Building one and want a second opinion?
We build production Claude agents and stay to run them. Bring us the architecture, the workflow, or the thing that is not working, and we will give you a straight read.
Related Services
Explore our other technical consulting services
Tell us what you're building.
Bring us the problem you're solving. We'll tell you how we'd build it, what it takes, and how Simple Engineers can help your business scale its technology.
Get in Touch
hello@simpleengineers.com
We typically respond within 2-4 hours
Phone
+1 (888) 966-0773
Mon-Fri 9AM-6PM EST
Location
Global Remote Team
Serving clients worldwide
Response Time
Within 24 hours
Emergency support available
Why Partner with Simple Engineers?
- Senior engineers who build and ship, not just advise
- We stay on to run and grow what we build
- You own everything: your code, your cloud, your keys
- Scaling companies from startup to enterprise since 2016
Send Us a Message
Tell us about your project or goals and we'll get back to you within one business day.