Agent or workflow? Surfaces, tiers and effort

When an agent is justified at all, which surface to build it on, and how to tune spend.

5 min read · Lesson 9 of 12 in this domain

Before choosing how to build, decide whether to build an agent at all. Agents trade cost, latency and predictability for the ability to handle work you cannot fully specify — a bad trade when you can specify it. Once you have decided you need one, the surfaces differ mainly in how much of the harness you own: the manual loop gives you everything and nothing, the tool runner drives the loop over tools you define, and the Agent SDK hands you the whole Claude Code harness with built-in tools. All three run on your infrastructure; the difference is how much you write yourself.

• Build an agent only when all four hold: complexity (multi-step, hard to specify up front), value (justifies cost and latency), viability (the model is capable here), and recoverable cost of error. Any "no" means stay at a simpler tier.
• Claude Agent SDK — Claude Code as a library: built-in tools (read/write/edit/bash/glob/grep/web), the agent loop, context management, hooks, subagents, sessions. You host it.
• Tool runner — an SDK helper that drives the loop over tools you define. No built-in tools, no filesystem. Still supports approval gates and per-turn intervention, so "I need control" is rarely a reason to hand-write the loop.
• Manual loop — when you want to own everything, or avoid a beta dependency.
• effort lives inside output_config and tunes thinking depth and overall token spend. It is not a hard cap — max_tokens is.
• Adaptive thinking lets Claude decide when and how much to think, including between tool calls.

Source: Claude Docs — Agent SDK overview · Independent study aid, not affiliated with or endorsed by Anthropic.