AnthropicClaude Certified Architect – Foundations2026-101.1 Design and implement agentic loops for autonomous task execution
Assign ownership of the execution loop
Completed by the knowledge check
Learning objective
Choose between an application-owned Messages API loop and Agent SDK-managed execution, including who controls tools, permissions, hooks, and stopping limits.
Core idea
Choose a harness by the execution responsibilities you want to implement and operate. An application-owned Messages API loop gives you direct control over requests, conversation history, and client-tool dispatch. The Agent SDK embeds Claude Code’s loop in a process you operate, handling model/tool round trips while you configure its behavior and consume its results.
The Agent SDK runs in a process you operate; Anthropic separately offers Managed Agents as a hosted harness. SDK-managed execution does not transfer your business policy to Anthropic. The host still chooses the environment, available capabilities, permission rules, and acceptance criteria. Conversely, an application-owned loop does not require you to invent a model protocol: the Messages API already defines tool calls, results, and stop reasons.
The choice is between implementing the harness around the API and configuring a harness supplied by the Agent SDK. It is not a choice between having control and surrendering it.
Neither harness is needed when the application can supply every piece of evidence before the call: one POST /v1/messages request returns the answer for the application to validate, with no tool selection by the model. Anthropic recommends the simplest solution that works, noting that for many applications optimizing single LLM calls with retrieval and in-context examples is usually enough.
How it works
Own the Messages API control path
In a manual loop, call the Messages API with messages and tools, inspect stop_reason, execute authorized client calls, and return their results. Your application owns the saved assistant content and matching tool_result messages. See 1.1.1 and 1.1.2 for those mechanics.
Client tools are implementations you run. Your executor chooses the dispatch table, validates inputs, checks authorization, schedules calls, and handles failures. Server tools are an exception to that execution location: Anthropic runs them, while your application still handles the response and continuation protocol.
A manual client-tool loop also owns its policy interception points. If every database mutation needs a tenant check, place that check before the executor invokes the mutation. This is application code, not an Agent SDK PreToolUse event supplied automatically by the Messages API. Record the call’s identity and policy decision so you can explain why a requested operation ran or was denied.
The application supplies job-level limits and outcome handling. max_tokens constrains one response’s generation; it is not a maximum number of tool rounds for an entire agent job. Define job deadlines and round budgets separately, and distinguish exhausted safeguards from completed work as in 1.1.4.
Anthropic’s client SDK also offers a beta tool runner that automates parts of a Messages API loop. That is a separate abstraction from the Agent SDK’s Claude Code harness; this comparison concerns a deliberately application-owned loop.
Configure the Agent SDK harness
The Agent SDK supports Python and TypeScript and runs Claude Code’s agent loop. In the TypeScript interface, query({ prompt, options }) yields messages as execution proceeds. The harness runs tools and feeds their results back to Claude. The host consumes the stream rather than rebuilding API history after each tool call.
The following controls assign responsibilities within that harness. The names in this list are TypeScript Options fields:
toolsconfigures built-in tool availability using a list of tool names or the Claude Code preset.mcpServersconnects additional tool providers; custom tools can be exposed through an SDK MCP server.allowedToolspre-approves listed tools. It does not restrict the agent to that list.disallowedToolsdenies listed tools or matching rules.permissionModeaccepts"default","acceptEdits","bypassPermissions","plan","dontAsk", or"auto". If omitted, the session can start in"auto", where a model classifier reviews actions such as shell commands and network requests. Set the mode deliberately. For a headless agent that must deny calls requiring approval unless pre-approved, choose"dontAsk"; operations that need no approval can still run, and calls requiring user interaction remain denied.canUseToolsupplies the host’s permission callback when evaluation reaches a permission prompt.hooksregisters callbacks for lifecycle events such asPreToolUseandPostToolUse.maxTurnsandmaxBudgetUsdlimit tool-use rounds and estimated spend.
Do not treat allowedTools: ["Read", "Grep"] as proof that all other capabilities are unavailable. Unlisted tools can still reach the active permission mode and callback. Scope availability with tools, use disallowedTools for denials, and review the complete tool configuration rather than interpreting a pre-approval list as an allowlist.
canUseTool is not a universal interceptor: calls already approved by the permission flow do not invoke it. If a policy must inspect every matching operation, register a PreToolUse hook. To deny a call, the hook returns hookSpecificOutput with hookEventName: "PreToolUse" and permissionDecision: "deny", optionally with permissionDecisionReason. The harness enforces that hook decision before executing the tool. See subsection 1.5 for interception details.
Both SDK languages support PreToolUse and PostToolUse, but the full event sets differ. Do not assume every TypeScript hook exists in Python. Python also spells options differently, including allowed_tools, disallowed_tools, permission_mode, can_use_tool, max_turns, and max_budget_usd; use that language’s documented interface when implementing the design.
Consume the terminal result explicitly
In TypeScript, a final message has type: "result". Check subtype before reading result: the text result is present on the success variant. Limit exhaustion yields error_max_turns or error_max_budget_usd; execution failures use error_during_execution. These are harness outcomes, not successful answers to relabel for convenience.
A single-shot query() yields an error result and then throws. Handle both the structured outcome and the exception path; a connection or process failure can occur without a result message. Progress messages alone cannot establish that execution reached a valid terminal result.
Even subtype: "success" does not replace business acceptance. Validate the required artifacts or evidence before marking a job fulfilled. The harness manages execution; your application owns what “fulfilled” means.
Key distinctions and trade-offs
The two approaches move work between your application and the supplied harness:
| Responsibility | Application-owned Messages loop | Agent SDK-managed execution |
|---|---|---|
| Model/tool round trips | Your request and response-state logic | SDK loop |
| Client-tool execution | Your dispatcher and implementations | Harness built-ins and configured integrations |
| Permissions | Your executor’s authorization checks | Configured rules, mode, callback, and hooks |
| Policy interception | Your code before and after dispatch | hooks at supported lifecycle events |
| Job stopping limits | Your job-level counters and deadlines | Configured turn and estimated-spend limits, plus host policy |
| Business acceptance | Your application | Your application |
A manual loop fits a specialized service that needs exact control over domain operations and transcript storage. It also makes your team responsible for adjacency, batching, continuation, and failure handling. The Agent SDK fits tasks that benefit from Claude Code’s built-in working-environment capabilities and a reusable execution harness. Its configuration and process boundaries still need deliberate operational design.
Architecture / decision scenario
A support backend invokes tenant-scoped order and account services. The team chooses a manual Messages API loop because it needs its own domain dispatcher and authorization transaction around every client call. It preserves API history, resolves each request, and supplies job limits. Its policy checks are executor code, not fictional SDK hook events.
A developer-productivity service instead needs repository search, file inspection, edits, and test execution. It chooses the Agent SDK and configures TypeScript tools for the intended built-ins. It sets permissionMode: "default", pre-approves appropriate operations with allowedTools, and handles prompts through canUseTool. A PreToolUse hook denies writes to protected paths even when another rule would otherwise pre-approve the operation.
The service configures maxTurns and maxBudgetUsd as safeguards, consumes the final result message, and handles exceptions. A capped run is incomplete; a normal result proceeds to artifact validation. Both architectures retain ownership of permissions and business success, while only one requires the application to implement the model/tool round trip itself.
Common exam traps
- Confusing the Messages client SDK with the Agent SDK.
- Confusing the locally operated Agent SDK harness with hosted Managed Agents.
- Treating
allowedToolsas a restriction to only listed tools. - Assuming
canUseToolchecks every auto-approved call. - Adding a second manual tool loop around SDK-managed execution.
- Equating a progress message or a capped run with a successful result.
- Copying TypeScript option names into Python unchanged.
Where the exam guide differs
The exam guide treats allowedTools as the list that makes a tool callable: a coordinator’s allowedTools “must include “Task”” before it can invoke subagents. In the Agent SDK, allowedTools (Python allowed_tools) adds allow rules that pre-approve the listed tools; unlisted tools still exist, and calls that need approval fall through to the permission mode and canUseTool. The guide’s Task tool is the Agent tool, renamed in Claude Code v2.1.63 with Task kept as an alias. In an exam item, read a tool listed in allowedTools as one the agent may use without a prompt, and do not infer that unlisted tools are unavailable; see 1.3.2 for delegation.
What to remember
Choose the harness by the responsibilities it should own. Direct API control requires an explicit executor and transcript protocol; the Agent SDK supplies that loop with configurable tools, permissions, hooks, and limits. Your host always owns the execution environment and business acceptance.
Knowledge check
A support backend calls tenant-scoped order and account services. Each call must run inside the team’s own authorization transaction, and the team stores the transcript in its own format. The agent needs no file or shell access. Which harness fits?
allowedTools for the servicesA headless Agent SDK reviewer must be able to call only Read and Grep. The team sets allowedTools: ["Read", "Grep"] and leaves everything else at its defaults. Which change limits the agent to those two tools?
canUseTool callback that denies every other toolallowedTools with path patternspermissionMode to "dontAsk" with the same listtools to ["Read", "Grep"] in the same optionsallowedTools pre-approves the listed tools; other tools still exist and fall through to the permission mode and callback, while tools sets which built-in tools are available at all. A callback sees only calls no earlier step resolved, and dontAsk denies calls that need approval while letting calls that need none run.A developer-productivity agent pre-approves Edit through allowedTools. Security requires that every write under infra/ be denied, including pre-approved ones, while other edits keep running without prompts. Where should the check live?
canUseTool callback that denies edits to paths under infra/disallowedTools , with the Edit tool added to the denied listPreToolUse hook that returns a "deny" decision for those pathsinfra/canUseTool , so a check there is silently skipped for pre-approved edits; a PreToolUse hook runs for every matching call, and the harness enforces its deny before the tool executes. Denying Edit outright blocks the edits that must keep running, and a prompt rule is not enforcement.A TypeScript host consumes query() and reads result from the final type: "result" message to decide whether a migration job finished. Some jobs hit maxBudgetUsd. What should the host do first with the final message?
result and mark the job fulfilled when the text is not emptysubtype and read result only on the success variantsuccess variant; error_max_budget_usd , error_max_turns and error_during_execution are harness outcomes meaning the job stopped early. Even success still needs business validation of the job’s artifacts, and streamed progress text cannot establish a valid terminal result.References
- Anthropic, Agent SDK overview
- Anthropic, Agent loop
- Anthropic, TypeScript SDK reference
- Anthropic, Python SDK reference
- Anthropic, Configure permissions
- Anthropic, Create custom subagents
- Anthropic, Control execution with hooks
- Anthropic, Tool use with Claude
- Anthropic, Tool runner (SDK)
- Anthropic, Building effective agents
- Anthropic, Claude Certified Architect – Foundations Exam Guide