Building Claude Agents with the Agent SDK, Custom Loops, and Frameworks

Implement a chosen Claude agent architecture by defining its control-loop contract first, then selecting the runtime that owns the right amount of machinery. Use the Claude Agent SDK when its documented agent loop and capabilities fit the application; build a custom loop when the team needs explicit control over messages, tool dispatch, state, and recovery; adopt a third-party framework only when a verified abstraction reduces real orchestration work; and consider Claude Managed Agents only under its current beta contract when managed long-running execution fits the workload. In every case, keep objectives, tools, context, durable state, hooks, budgets, stop conditions, approvals, traces, and recovery responsibilities explicit.

The runtime does not determine whether the architecture is safe or effective. A library can execute a loop, a framework can organize transitions, and a managed service can operate infrastructure, but the application still owns success criteria, authority, data policy, tool consequences, evaluation, and failure handling. Start from the architecture selected in Claude Agent and Workflow Architecture Decision Framework, then map that decision to an implementation surface without adding autonomy merely because the surface supports it.

Architecture Overview: Separate the Agent into Reviewable Layers

Anthropic's building effective agents guidance recommends simple, composable patterns and distinguishes predefined workflows from model-directed agents. Construction should preserve that control decision rather than hide it inside a runtime.

Layer	Required responsibility	Evidence needed for review
Objective contract	Define outcome, completion evidence, prohibited effects, and escalation	Task version, acceptance criteria, evaluator reference
Control loop	Decide who selects the next step and when execution stops	Transition trace, stop reason, call and time budgets
Tool boundary	Expose focused capabilities and execute through trusted policy	Tool-set version, call/result identifiers, authorization and approval records
Context boundary	Assemble the active working set for each step	Selected sources, context version, pruning or handoff record
State boundary	Persist workflow progress and durable application facts	Session or run ID, checkpoints, state version, ownership and retention
Control hooks	Run deterministic checks or operational actions at supported boundaries	Hook version, input, outcome, failure or bypass behavior
Deployment boundary	Place compute, credentials, storage, queues, and recovery ownership	Runtime version, environment, dependency and service contract
Evaluation boundary	Decide whether the complete agent is fit to release	Scenario set, trajectory and outcome results, release decision

These layers may be implemented in one process, several services, an SDK, a framework, or managed infrastructure. Their responsibilities should remain observable even when an abstraction combines them.

Translate the Chosen Pattern into an Execution Skeleton

Construction begins by making the architecture's control ownership executable.

Deterministic workflow

Application code selects each stage and branch. Claude performs bounded judgments inside those stages, while code controls routing, validation, approval, retries, and completion. Model calls should not rediscover a fixed process already known to the application.

The implementation needs typed inputs and outputs for each stage, persisted stage status, explicit transition rules, and narrow retry boundaries. A workflow can still use the Agent SDK or a framework, but those tools must not silently turn fixed transitions into model-selected ones.

Single-agent loop

The model selects the next permitted action from current observations. The harness supplies the objective, active context, available tools, and execution limits; receives a model response; resolves any requested tool calls through application policy; returns bounded results; and repeats until a verified completion, escalation, failure, or budget stop.

The loop must distinguish a final response from a request for capability and from a controlled stop. Fluency is not completion evidence. Application code should verify the expected result and record why the loop ended.

Manager and bounded workers

The manager owns decomposition, dispatch, aggregation, conflict handling, and the final completion decision. Each worker receives one bounded task with allowed sources, tools, permissions, budget, output contract, provenance requirements, and escalation rules. Workers return evidence packages rather than unbounded transcripts.

Persist task identities and status outside model prose. The manager should be able to tell whether a task is queued, running, completed, failed, timed out, cancelled, or awaiting approval without asking a model to infer operational state.

Implement the Tool-Use Loop as an Application Contract

The current tool-use flow establishes the essential client loop: the application sends tools with the conversation, Claude can return tool_use content blocks, the application executes approved client tools, and matching tool_result blocks are supplied in the next user message so Claude can continue.

Whether an SDK, custom harness, or framework carries the messages, preserve these responsibilities:

Build the request from authorized context and the tools allowed for this actor, task, and step.
Call Claude and retain the complete assistant response required for the next turn.
Inspect every capability request and map only registered names to handlers.
Validate structure and business meaning, resolve trusted identity and target, authorize, and obtain any required approval.
Execute with least privilege, timeouts, idempotency, and bounded output.
Return a result or safe error matched to the originating call.
Evaluate progress, update application-owned state, and either continue, complete, escalate, or stop.

Do not bury authorization inside a tool description or framework callback. Tool schema design, approval binding, error taxonomies, result ordering, and safe retry mechanics belong to the dedicated tool implementation procedure. At this construction layer, ensure the chosen runtime exposes the necessary boundaries rather than bypassing them.

Choose the Implementation Surface by Ownership

The best implementation surface is the one whose owned behavior matches what the team is prepared to delegate and verify.

Surface	Prefer it when	Team still owns	Main review question
Claude Agent SDK	The documented Claude agent loop and capabilities fit the application and reduce custom harness work	Objective, configuration, permissions, context, tools, deployment, evaluation, and upgrades	Can the team observe and control every consequential boundary it needs?
Custom loop or harness	Exact message, dispatch, state, policy, recovery, or portability control is necessary	The complete loop, protocol handling, tool broker, persistence, tracing, compatibility, and operations	Is the added control worth the implementation and maintenance burden?
Third-party framework	A verified abstraction removes repeated orchestration work and matches existing operational needs	Framework evaluation, dependency governance, adapters, hidden defaults, migrations, security, and escape paths	Does the abstraction preserve required state, control, and evidence boundaries?
Claude Managed Agents	The current beta managed execution contract suits long-running or asynchronous work and the beta risk is acceptable	Task design, data and tool authority, evaluation, integration, policy, and provider-contract review	Which operational responsibilities move, and which remain with the application?

Claude Agent SDK

The current Claude Agent SDK documentation describes Anthropic's development surface for building agents with Claude Code's agent loop and capabilities. Choose it when that loop is the desired foundation and its current interfaces, deployment expectations, permissions, session behavior, and extension surfaces fit the workload.

Using the SDK does not eliminate architecture work. Pin and record the dependency and compatible model configuration, wrap application-specific identity and policy outside model judgment, decide which state is authoritative, and test interruption, upgrade, tool failure, and permission denial. Treat documented defaults as versioned behavior rather than permanent assumptions.

Custom loop or harness

A custom harness makes the loop and state machine directly visible. It is appropriate when the application needs a narrow protocol surface, custom orchestration, a particular persistence or queue model, strict policy placement, or recovery behavior that an existing abstraction cannot provide cleanly.

That visibility creates responsibility. The team must correctly preserve message history, content blocks, tool-call/result correlation, model and API compatibility, stop handling, concurrency, retries, observability, and upgrades. Custom code should be smaller than the problem it solves; duplicating a mature abstraction without a specific control need increases defect and maintenance risk.

Third-party framework abstraction

The CCDV-F blueprint names Strands, LangGraph, and PydanticAI as examples of frameworks that can embody agent patterns. Treat them here as conceptual examples, not as verified claims about current APIs or features. This article's closed source inventory does not establish their present interfaces, persistence guarantees, security defaults, or compatibility.

Evaluate any framework against the same neutral questions: How does it represent state and transitions? Where are model requests and tool effects observable? Can the application enforce identity, authorization, approvals, budgets, and stop conditions? What is persisted, and under whose retention policy? Can traces be exported and failures resumed? How are dependencies pinned, upgraded, rolled back, or replaced?

Adopt a framework only when verified behavior answers those questions and the abstraction measurably reduces work. Do not choose one because its vocabulary makes the architecture diagram look complete.

Claude Managed Agents beta

Claude Managed Agents is a beta managed agent harness for long-running and asynchronous work as verified on 2026-08-28. Its current contract requires the managed-agents-2026-04-01 beta header on every endpoint. Availability, interfaces, pricing, limits, and behavior are time-sensitive and must be rechecked before adoption.

Managed execution can shift some runtime and operational mechanics to Anthropic, but it does not transfer business accountability. The application still determines what data may enter, which tools and credentials are exposed, which effects require approval, how results are validated, what evidence is retained, and whether the system meets its evaluation and incident-response requirements. Compare that responsibility split with self-hosted SDK, custom-harness, or framework operation rather than treating “managed” as “automatically safe.”

Keep Sessions, Context, Memory, and State Distinct

An agent run needs continuity, but four different mechanisms should not be collapsed into one “memory” field:

Session or run identity correlates events for one execution and supports resume or inspection.
Transient workflow state records steps, pending work, tool outcomes, budgets, and approvals for the active operation.
Active context is the bounded set of instructions, messages, evidence, and tool results supplied to a model call.
Durable application memory stores approved reusable facts or preferences outside the model under access, provenance, retention, and deletion controls.

The runtime may provide session conveniences, but the application must identify the authoritative store and lifecycle for each state class. A session identifier is not proof that a side effect completed, and a transcript is not automatically an authorized durable-memory record.

Use the architecture in Context and Memory Management for Claude Applications and Agents to select, prune, compact, retrieve, and isolate context. This construction article only requires that the loop call those policies at defined boundaries and record the resulting state versions.

Use Hooks Without Hiding Policy or Model Judgment

Hooks can attach checks, logging, normalization, approval gates, cleanup, or other actions to supported lifecycle boundaries. They are useful when the control must run consistently regardless of how the model phrases its next step.

Keep authoritative identity and authorization in application or policy controls. Where the selected runtime offers command hooks, prompt hooks, or agent hooks, distinguish deterministic executable checks from model-based judgments and verify the exact current event and failure semantics. Experimental or model-driven hook behavior should not become the only control protecting a consequential action.

Every hook needs a version, owner, minimal privileges, validated input, timeout, defined failure posture, observable outcome, and bypass analysis. A hook should make a boundary easier to audit, not conceal a transition inside an opaque callback. The layered security model is covered in Securing Claude Applications with Guardrails, Hooks, and Secret Management.

Bound Execution and Define Recovery

An agent loop needs limits that are enforceable outside the model. Set budgets appropriate to the task for model calls, tool calls, elapsed time, tokens, service cost, retries, delegation depth, parallel workers, and data volume. Define what happens as a limit approaches: return the best verified partial result, persist a checkpoint, request more authority, or stop safely.

Record a machine-readable stop reason such as completed, user-cancelled, approval-denied, budget-exhausted, no-progress, tool-failed, policy-blocked, or outcome-uncertain. Do not convert every stop into a polished “success” response.

Recovery requires application-owned facts:

a run and configuration version;
the last committed state transition;
completed and pending tool operations;
idempotency keys and uncertain outcomes;
worker task states and deadlines;
active approvals and their scope or expiry; and
the context or compacted handoff needed to resume safely.

Retry only the smallest safe boundary. Reconcile external state before repeating a call whose outcome is uncertain. When state cannot be trusted, stop and escalate rather than asking the model to reconstruct truth from incomplete conversation history.

Build Observability and Evaluation into the Loop

Capture enough application-owned evidence to reconstruct the trajectory: request and run identifiers, configuration versions, context-source references, model responses, tool requests and bounded results, policy and approval decisions, state transitions, hook outcomes, resource usage, stop reason, and final validation result. Redact secrets and sensitive payloads according to policy.

Evaluation must cover both final outcomes and trajectories. A useful result reached through unauthorized access, excessive retries, an ignored denial, or an unrecoverable state is not a passing agent. Compare representative normal, boundary, adversarial, interruption, and dependency-failure cases before release.

This article defines the evidence the runtime should expose. Dataset design, evaluators, regression thresholds, trace diagnosis, and release gates remain in the dedicated evaluation and debugging guidance.

A Construction Sequence That Preserves Boundaries

Freeze the chosen workflow, single-agent, or manager-and-worker control architecture and its success criteria.
Specify the loop states, transitions, tool contract, completion evidence, budgets, stop reasons, and approval boundaries independent of a library.
Compare the Agent SDK, a custom harness, verified framework behavior, and any managed option against those requirements.
Implement one thin end-to-end path with observable model, tool, state, hook, and failure boundaries.
Add session persistence, context assembly, idempotency, checkpoints, and recovery before expanding autonomy or delegation.
Test denied actions, malformed calls, timeouts, duplicate effects, cancellation, budget exhaustion, and interrupted resume.
Add bounded workers only when independent evaluation shows that specialization or isolation improves the selected architecture.
Version the complete runtime configuration and hand its traces and outcomes to the formal evaluation gate.

The sequence keeps the implementation reversible. If an abstraction obscures a required boundary, narrow its role, add an explicit adapter, or choose a surface that exposes the control.

Common Agent Construction Mistakes

Choosing a runtime before defining the loop. The library should implement the required control architecture, not invent it.
Treating the SDK as the security boundary. Application identity, authorization, approvals, and data policy remain separate responsibilities.
Implementing a custom harness without a specific need. More visible code also means more protocol, state, recovery, and upgrade obligations.
Attributing unverified capabilities to a framework. Verify the exact version and official documentation before relying on an abstraction.
Using a transcript as durable state. Persist operational facts and approved memory under explicit ownership and lifecycle controls.
Letting hooks hide critical transitions. Version, observe, test, and fail them according to the risk of the action.
Stopping only when the model says it is done. Enforce budgets and verify completion in application code.
Retrying after an uncertain side effect. Reconcile by the owning system and idempotency record before repeating execution.
Calling managed execution generally available. Preserve the beta header, date, and change risk until current documentation says otherwise.
Evaluating only final text. Review tool use, policy decisions, cost, stop behavior, recovery, and the complete trajectory.

Relevance to Claude Certified Developer – Foundations

The Claude Certified Developer – Foundations Exam Guide v1.0 includes constructing agents with the Claude Agent SDK or a custom loop, comparing self-hosted and managed operation, using hooks for controls, and implementing tool loops, subagents, memory, context management, and framework patterns within Agent Construction with Claude and Agent Patterns and Frameworks.

The durable skill is mapping one selected control architecture to an implementation without losing ownership. SDKs, custom harnesses, frameworks, and managed services can move code and operational work, but they do not remove the need for explicit tools, state, context, controls, evaluation, and recovery.

Conclusion

Build a Claude agent by defining its loop and state contract before choosing its runtime. The Claude Agent SDK can supply a documented agent foundation, a custom harness can expose exact application control, a verified framework can reduce repeated orchestration, and Claude Managed Agents can be considered under its current qualified beta contract for suitable managed execution.

Whichever surface you choose, keep tool effects authorized, context and memory governed, hooks observable, budgets enforceable, stops truthful, recovery application-owned, and trajectories evaluable. An abstraction is useful only when it preserves those boundaries while reducing the work required to operate them reliably.