Whetstone.
Designing a Claude ApplicationFour ways to build a Claude app
Module 2, Lesson 126 min

Four ways to build a Claude app

There are four ways to put Claude in a product, and the exam cares that you can tell them apart. This is design-domain material, worth more than any syntax question, and the distinctions are genuinely subtle.

The useful axis is how much of the loop you are still holding. At one end you write every turn yourself; at the other, execution has left your infrastructure entirely. Everything else follows from where on that axis you land.

The four shapes

Client SDK. You call the Messages API. You get back stop_reason: "tool_use", you execute the tool, you append the result, you call again. The loop is yours. Maximum control, maximum code, and every retry, timeout and budget check is something you wrote.

Tool Runner. client.beta.messages.tool_runner loops over tools you define. You still own the tool implementations; you stop owning the plumbing that shuttles results back in. It is the smallest step up from the raw SDK and the one people underrate.

Claude Agent SDK. The docs describe this one as Claude Code as a library. Python and TypeScript only. It is not a loop helper, it is the whole harness: the agent, its tooling, its file access, its behaviour, packaged so you can embed it. If you want the thing that Claude Code is, without building the thing that Claude Code is, this is it.

Managed Agents. Server-hosted, behind the beta header managed-agents-2026-04-01, billed at 0.08 dollars per session-hour on top of token costs. And the line the docs draw explicitly: it is a separate product from the Agent SDK.

How to actually pick

Three questions, in this order.

Do you need to intervene between turns? Approval gates, per-user spend caps, audit logging of every tool call, custom retry on a flaky internal service. If yes, you want the loop in your hands, which means Client SDK, or Tool Runner if the intervention fits its hooks. A harness that hides the loop hides the place your logic needs to go.

Are your tools the interesting part, or is the agent? If the value is in five well-defined functions against your own systems, Tool Runner. If the value is an agent that explores a repository and decides what to do, the Agent SDK already contains that behaviour and rebuilding it is months you do not have.

Who runs it? Managed Agents moves execution server-side, which changes your operational story completely: no long-running process of your own, and a per-session-hour charge instead. That is a real trade, not a free upgrade, and the trade is worth naming out loud in a design review.

Note the unit on that charge, because it is unusual. Per session-hour means a session that sits idle for forty minutes waiting on a slow downstream service costs the same as forty minutes of hard work. Your latency profile is now a line item.

The trap in the question

Exam questions in this area usually describe a requirement and ask which approach fits. The distractor is almost always the more powerful option for a problem that does not need it. A five-tool internal lookup service does not need an agent harness, and picking one because it sounds more capable is exactly the judgement error the design sub-skill is testing.

The other direction is a trap too. If the requirement says “must approve every destructive action before it runs”, any answer that hands the loop away is wrong no matter how modern it sounds.

Practice

Try it yourself

Recall

The four build shapes, distinguished

This is the highest-value distinction in the whole Applications and Integration domain. Get it clean.

Name the four ways to build on Claude and say, in one sentence each, what you are actually getting.

Reveal answer

Client SDK: raw Messages API access where you implement the tool loop yourself. Tool Runner (client.beta.messages.tool_runner): the SDK runs the loop for you over tools that you define. Claude Agent SDK: described by the docs as Claude Code as a library, Python and TypeScript only, shipping the whole agent harness rather than just a loop. Managed Agents: explicitly a separate product from the Agent SDK, server-hosted, behind the beta header managed-agents-2026-04-01 and billed an extra 0.08 dollars per session-hour on top of tokens.

Quiz

Is the Agent SDK GA or beta

A colleague asks whether the Claude Agent SDK is generally available. What is the correct answer?

  1. AIt is GA, because the docs list no beta header for it and beta features always carry one
  2. BThe documentation states no GA or beta classification for it, so asserting either is wrong
  3. CIt is beta, gated by the skills-2025-10-02 header that Agent Skills also requires
  4. DIt is beta, gated by the managed-agents-2026-04-01 header used by Managed Agents
Show answer

Correct answer: B — The documentation states no GA or beta classification for it, so asserting either is wrong

The docs do not classify the Agent SDK as GA or beta, and inventing a classification is the error being tested. Absence of a beta header is tempting evidence for GA but it is not the same thing, and the two headers offered are real headers belonging to Agent Skills and to Managed Agents respectively, which are different features. When a source is silent, the honest answer is that it is silent.

Quiz

Managed Agents and the Agent SDK

How do Managed Agents relate to the Claude Agent SDK?

  1. AManaged Agents is the hosted deployment target for Agent SDK code
  2. BManaged Agents is the Python-only variant of the Agent SDK
  3. CThey are two names for the same thing, with Managed Agents being the newer name
  4. DManaged Agents is a separate product from the Agent SDK
Show answer

Correct answer: D — Managed Agents is a separate product from the Agent SDK

The documentation draws this line explicitly: Managed Agents is a separate product from the Agent SDK. The tempting answer is that one hosts the other, because that is how these things usually relate and because Managed Agents does carry a per-session-hour charge that smells like hosting. But the docs do not describe it as a deployment target for Agent SDK code, and repeating that would be inventing a relationship.

Quiz

One requirement that eliminates two options

The requirement is stated in the contract: every destructive action must be approved by a named human before it executes, and the approval must be logged. Which build shape does this force?

  1. AClient SDK or Tool Runner, because the approval gate has to sit inside the loop you control
  2. BManaged Agents, because server-hosted execution gives you a central audit log
  3. CThe Agent SDK, because it already contains permission handling
  4. DAny of the four, because approval is a UI concern rather than an architecture one
Show answer

Correct answer: A — Client SDK or Tool Runner, because the approval gate has to sit inside the loop you control

An approval gate is code that has to run between the model asking for a tool call and that tool call executing, which means you need to own the point in the loop where that happens. The Managed Agents answer is genuinely tempting, because central hosting really does make audit logging easier and the requirement mentions logging, but the logging is the easy half. The hard half is interception, and a harness that runs the loop for you is a harness that owns the moment you need to interrupt. Reading the requirement as a UI concern is the classic error, since a UI approval that the backend does not enforce is decoration.

Quiz

Settling a release-status question fast

You are in a design review and someone claims the Agent SDK is GA. You have the documentation open. Which page settles it most directly?

  1. AThe Agent SDK quickstart, since a GA product would say so in the introduction
  2. BThe pricing page, since GA products are the ones with published prices
  3. CThe changelog, since GA transitions are announced there
  4. DThe beta features list, checked for whether the Agent SDK appears with a dated header
Show answer

Correct answer: D — The beta features list, checked for whether the Agent SDK appears with a dated header

The beta list is the enumerated, checkable surface, and its usefulness here is that it can return a clean negative: if the Agent SDK carries no dated beta header, you have established one specific fact rather than a vibe. The quickstart is the tempting answer because it is the page about the thing, but the absence of the word GA in an introduction proves nothing at all, and it is that inference gap the question is testing. Note the honest limit of the beta-list check too, which is that no beta header is not the same claim as GA.

Do

Pick a shape for one real integration

Take an integration you would plausibly build and choose between the four, on paper, in a scratch file. No code, no accounts, nothing to install.

  • Write one sentence describing the integration and who calls it.
  • List every tool it needs and mark each one as yours to execute or server-side.
  • Decide whether the loop needs custom behaviour between turns, such as logging, approval gates, or budget checks.
  • Pick one of the four shapes and write the sentence that justifies it.
  • Write the sentence that says what you gave up by not picking each of the other three.
Done whenFour sentences of justification exist, one per shape, and the chosen one names a concrete property of your integration rather than a preference.
Sign in to track your progress →