Agent Construction with Claude

Four ways to own the loop

Construction starts after the 1.1 decision. If the path is a workflow, you do not need an agent runtime. If it is an agent, you still choose how much of the harness you write.

The Messages API is the request. It does not store a session and it does not run tools. A custom harness is your loop on top of that API. The Claude Agent SDK is that loop, plus tool dispatch and session handling, running in your process while you still execute tools. Claude Managed Agents is the furthest step: Anthropic runs the harness, and the session executes in a sandbox you configure as Anthropic-hosted or self-hosted.

• Messages API: one call. You hold history. You run tools.
• Custom harness: you own stopping, retries, telemetry, and where hooks sit.
• Agent SDK: you own instructions, tools, and permissions. The SDK owns the loop in your process.
• Managed Agents: you own the agent definition and the environment choice. Anthropic owns the loop and the sandbox lifecycle.

What you declare

An agent definition answers three questions. The system prompt says what the agent is for and how it should behave. The tools say what it can call, each with a name, a description, and an input schema. Permissions, often an allowed-tool list, say which of those tools this run may actually use. The SDK and Managed Agents both need that definition. Neither one invents it for you.

A vague prompt or a blurry tool description still produces a bad agent on a perfect loop. Adopting the SDK to "fix tool choice" misses the split: the SDK automates mechanics, not judgment. Whether filesystem configuration such as CLAUDE.md and Skills loads under the SDK is a setting you set explicitly (settingSources), not something to assume.

The custom loop

A custom loop is the same cycle the SDK runs, written where you can see it. Send the messages. Inspect stop_reason. On tool_use, run every tool_use block, append the assistant message, append a user message of tool_result blocks, and continue. On end_turn, return. Any other stop_reason is a specific failure: max_tokens means the output was cut, refusal means the model declined, and context-window exhaustion means the history does not fit. None of those are end_turn.

You build this when the product needs control the SDK does not expose: a custom retry budget, a trace shaped like the rest of your platform, a stop rule that is not "the model ended," or a side effect that must pause for a person before the tool binary runs. The cost is that you now own every bug in the harness.

if (response.stop_reason === "tool_use") {
  messages.push({ role: "assistant", content: response.content });
  const results = await Promise.all(
    toolUses(response).map(async (block) => ({
      type: "tool_result" as const,
      tool_use_id: block.id,
      content: await gatedRun(block),
    })),
  );
  messages.push({ role: "user", content: results });
}

Tool execution inside the harness

The model requests a tool. Your process runs it. The harness is responsible for matching tool_use ids, timeouts, and what goes back into the transcript. A tool error should return as a tool_result the model can read, with enough structure to distinguish a transient timeout from a validation reject, so the next turn can repair or stop. Swallowing the error and continuing with a stale result is how the loop lies.

Least privilege is a construction choice. Do not register a refund tool on an agent whose job is summarising URLs. A capability the process never holds cannot be prompted into existence. When the tool must exist, a hook is the gate, not a sentence in the prompt.

Managed deployment

Claude Managed Agents is the option when you want the loop, tool runtime, and sandbox without operating them. A session is a running agent in an environment. Events are the user turns, tool results, and status updates your application exchanges with that session. The harness also applies built-in caching and compaction, which matters on long investigations.

The environment is the deployment choice the exam cares about. An Anthropic-hosted cloud sandbox minimises infrastructure: packages, network, and the execution host are Anthropic's. Session state and outputs are stored server-side, so this option is the wrong fit for a contract that requires Zero Data Retention or a HIPAA BAA. A self-hosted sandbox keeps execution on infrastructure you control for residency or compliance, while you still use the managed harness rather than writing the loop. Pick the sandbox from the data constraint, not from a preference for "cloud."

Hooks, deterministic actions, and people

A hook is code at a lifecycle boundary. PreToolUse runs before the tool. It can allow, deny, or rewrite the input. The side effect has not happened yet, so this is where a refund ceiling, a path allowlist, or a production delete ban belongs. PostToolUse runs after the tool and can normalise what the model will see. It cannot undo the delete. A prompt that says "never refund above $200" remains probabilistic.

Some decisions are not a rule. A human checkpoint pauses the loop and routes to a person: before an irreversible send, after a plan and before its side effects, or when a tool result is outside the range a retry would responsibly handle. The harness must actually wait. Asking the model to "check with the user" inside the prompt is not a checkpoint, because the model can skip the sentence.

Pair stop_reason with an explicit budget. A cap on turns, tokens, or money ends a loop that keeps requesting tools. The cap is the safety net. Completion is still end_turn.

Lifecycle and errors

A practical lifecycle is define, start, loop, gate, stop, and record. Define the prompt, tools, and permissions. Start a session or a message list. Loop on the model. Gate side effects with hooks or approvals. Stop on end_turn or on the budget. Record the trace so the next failure is diagnosable.

Handle errors at the layer that owns them. Transient tool failures retry in the harness with a limit. Validation failures go back to the model as a tool result so it can correct the arguments. Permission failures stop that tool and surface a reason; they are not a cue to try a more privileged tool. An unhandled stop_reason fails closed: return the error to the caller instead of appending empty success.

Wrong tool, SDK blamed

An agent calls search_customer when the user asked for an invoice. The team plans to "switch to the Agent SDK so it handles the logic." The SDK will not repair a tool description that says "looks up customer things" on two different tools. Keep the SDK if the loop is the pain. Rewrite the descriptions and the allowed-tool list if the pain is selection.

Shell access and a prompt

A coding agent can run a shell. The safeguard is a system line: "Never delete outside the workspace." Tests look clean. The design is still wrong, because a prompt is not a guarantee. Intercept the shell tool, reject any delete whose path is outside the workspace, and return that refusal as the tool result. The model can continue. The filesystem does not.

Residency decides the sandbox

A bank wants a long research agent and must keep execution in its own VPC. Managed Agents with a self-hosted sandbox matches that constraint. The Anthropic-hosted sandbox would move the session onto infrastructure the bank cannot accept. Writing a custom loop is only necessary if the bank also rejects the managed harness, not merely the hosted sandbox.