Start Here — From Terminal User to Architect

You have used Claude Code in a terminal. It writes code, fixes bugs and answers questions. Maybe that is the only Claude product you have used. This page is a ladder. It takes you from "I use a coding assistant" to "I design agent systems". You climb one step (rung) at a time. Each rung has a short story that explains why the next thing exists.

Why take a certification at all?

Here is an honest answer for two different readers.

If you are newer: when you learn from random blog posts, you collect separate pieces of knowledge with hidden gaps between them. You may know some prompting tricks but not why the agent loop stops. You may have heard "MCP" but not be able to say what problem it solves. A certification blueprint (the official list of exam topics) is a map of the whole area. It tells you what a complete practitioner knows. Your learning then follows a plan instead of moving at random. If you study the blueprint properly, the certificate comes as a side result. The real value is the structure.

If you are experienced: you probably know 70% of this well, but you have never named the other 30%. The blueprint shows you your blind spots. For most experienced engineers these are MCP primitives, how caching works, and the official vocabulary. In interviews, "I build this every day" plus a current certificate is stronger than either one alone. The certificate is independent proof that your experience matches the shared language of the industry.

In both cases: the exam changes about once a year (the certificate is valid for 12 months), because the field moves fast. An architect treats it as a regular refresh habit, and that habit is itself part of the job.

Rung 1 · What is actually happening when you use Claude Code?

You already know this story. You type "fix the failing test". Claude Code searches (greps) the codebase, reads files and edits one. Then it runs the test again and reports success.

What you saw was an agent loop. It is the most important concept in the whole certification:

flowchart TD
  Y[You: fix the failing test] --> M[🧠 Claude decides: run the test first]
  M --> T[Claude Code executes: npm test]
  T --> O[Output appended to the conversation]
  O --> M2[🧠 Claude decides: read auth.ts]
  M2 --> T2[Executes: Read auth.ts]
  T2 --> M3[🧠 …edit → rerun → done]

Notice two things. The whole exam depends on them:

1. Claude never ran anything. The model only asked for each action. Claude Code's own program (the harness) checked permissions and then ran the action. The model decides; the harness executes.
2. The loop stopped because a condition was met: the test passed. A loop needs stop conditions, budgets and gates (checks that allow or block an action). That is what "architecture" means here.

Rung 2 · The same brain, called from Python

This change in thinking makes everything below easier: Claude is a thinking partner, not a vending machine. You bring everything the model cannot supply by itself: the context, the objective, the stage, the goals and the rules. Claude Code feels magical because Anthropic already built all five of these for coding work. The rest of this ladder teaches you to build them yourself, for any kind of work.

Claude Code is one harness (the software that runs and controls the model) around the model. The Claude API lets you build your own harness. It is Anthropic's Messages endpoint: the HTTPS service that carries every model call in this guide. It does not matter whether Claude Code makes the call or your Python script does. Here is the whole secret, the Claude API call under everything else:

import anthropic
client = anthropic.Anthropic()          # ANTHROPIC_API_KEY in env
# Abridged: commit_log is a placeholder for your real commit text.

resp = client.messages.create(
    model="YOUR_SUPPORTED_MODEL",
    max_tokens=1024,
    system="You are a concise release-notes writer.",
    messages=[{"role": "user",
               "content": "Summarize these commits:\n" + commit_log}],
)
print(resp.content[0].text)

import os
import subprocess

import anthropic

MODEL = os.environ.get("CLAUDE_MODEL", "claude-sonnet-5")
client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from the environment


def read_commit_log(since_tag: str) -> str:
    """Return one line per commit since the given tag."""
    return subprocess.run(
        ["git", "log", f"{since_tag}..HEAD", "--pretty=format:%h %s"],
        capture_output=True, text=True, check=True,
    ).stdout


def write_release_notes(since_tag: str) -> str:
    commit_log = read_commit_log(since_tag)
    if not commit_log.strip():
        return f"No changes since {since_tag}."
    resp = client.messages.create(
        model=MODEL,
        max_tokens=1024,
        system="You are a concise release-notes writer.",
        messages=[{"role": "user",
                   "content": "Summarize these commits:\n<commits>\n" + commit_log + "\n</commits>"}],
    )
    if resp.stop_reason == "max_tokens":
        raise RuntimeError("Notes were cut off: raise max_tokens or send fewer commits.")
    if resp.stop_reason == "refusal":
        raise RuntimeError("The model declined; a person must review this run.")
    return "".join(b.text for b in resp.content if b.type == "text")


if __name__ == "__main__":
    print(write_release_notes(os.environ.get("SINCE_TAG", "v1.0.0")))

That is all. Claude Code, the Claude apps and the agent products built on Anthropic's models are all programs that do three things. They build a messages array. They call this endpoint (or a supported Bedrock/Vertex route). Then they do something with the response.

🧭 One page describes every field of that request and of the response it returns: The Messages API Spec. Read it once, and every SDK call in this guide becomes easy to read. The SDK is only a convenient layer over those two JSON shapes.

Why would you move from Claude Code down to the Claude API? Here is the story. Your team likes that Claude Code writes release notes when someone asks. Now you want release notes created automatically on every merge, inside CI (your continuous-integration pipeline), with no person at a keyboard. That is no longer an assistant. It is a feature of your product. You build features on the Claude API (or on the Agent SDK, see rung 4).

Rung 3 · Giving the model hands — tools

You reach the model only through the Claude API, and the model can only talk. To let it act, you declare tools. A tool is a JSON description of a function that your code implements. The model requests the tool. Your code runs it. Your code then sends the result back to the model.

# Abridged/pseudocode: MODEL and my_real_lookup() are placeholders for your model id + lookup function.
tools = [{
  "name": "get_order_status",
  "description": "Look up one order's shipping status by order id.",
  "input_schema": {"type": "object",
                   "required": ["order_id"],
                   "properties": {"order_id": {"type": "string"}},
                   "additionalProperties": False}
}]

resp = client.messages.create(model=MODEL, max_tokens=500, tools=tools,
    messages=[{"role": "user", "content": "Where is order A-1042?"}])

# resp.stop_reason == "tool_use" → the model WANTS the tool run:
block = next(b for b in resp.content if b.type == "tool_use")
result = my_real_lookup(block.input["order_id"])     # ← YOUR code acts
# …return a tool_result message, call the Claude API again, get the final answer.

import os
from typing import Annotated

import anthropic
from anthropic import beta_tool
from pydantic import Field

from app.orders import service as orders  # your own code: repository / service layer

MODEL = os.environ.get("CLAUDE_MODEL", "claude-sonnet-5")
client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from the environment


@beta_tool(name="get_order_status", description="Look up one order's shipping status by order id.")
def get_order_status(order_id: Annotated[str, Field(description="The order id, e.g. A-1042.")]) -> str:
    return orders.get_status(order_id)  # YOUR code acts; raise on failure


def answer(question: str) -> str:
    runner = client.beta.messages.tool_runner(
        model=MODEL,
        max_tokens=500,
        tools=[get_order_status],  # the function itself, not a dict
        messages=[{"role": "user", "content": question}],
        max_iterations=5,  # hard stop for a runaway loop
    )
    final = runner.until_done()  # the last message the model returned
    if final.stop_reason != "end_turn":  # tool_use = limit hit; max_tokens; refusal
        raise RuntimeError(f"Agent did not finish: {final.stop_reason}")
    return "".join(b.text for b in final.content if b.type == "text")

{
  "name": "get_order_status",
  "description": "Look up one order's shipping status by order id.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": {"type": "string", "description": "The order id, e.g. A-1042.", "title": "Order Id"}
    },
    "required": ["order_id"],
    "additionalProperties": false
  }
}

This cycle (the model requests, your code runs, your code returns the result) is the agent loop from Rung 1. Now it runs in your own code. You have now seen the topics behind 27% of the exam.

resp.content == [
    {"type": "text",     "text": "Let me look that up."},          # ← optional prose
    {"type": "tool_use", "id": "toolu_01…", "name": "get_order_status",
                         "input": {"order_id": "A-1042"}},        # ← the request
]

# resp.stop_reason == "tool_use" → the model WANTS the tool run:

if resp.stop_reason == "tool_use":
    block = next(b for b in resp.content if b.type == "tool_use")
    ...
elif resp.stop_reason == "end_turn":
    # model is done — print the text block(s)

block = next(b for b in resp.content if b.type == "tool_use")

block.name    # "get_order_status"  → which of YOUR functions to dispatch to
block.input   # {"order_id": "A-1042"} → validated against your input_schema
block.id      # "toolu_01…"          → you MUST echo this back as tool_use_id

result = my_real_lookup(block.input["order_id"])   # ← YOUR code acts

messages.append({"role": "assistant", "content": resp.content})   # echo the model's turn
messages.append({"role": "user", "content": [{
    "type": "tool_result",
    "tool_use_id": block.id,          # ← pairs the answer to the request
    "content": str(result),
}]})
# …call the Claude API again with the same tools → final answer, stop_reason "end_turn"

tool_results = []
for b in resp.content:
    if b.type == "tool_use":
        tool_results.append({"type": "tool_result", "tool_use_id": b.id,
                             "content": str(dispatch(b.name, b.input))})

Rung 4 · The Agent SDK — Claude Code's engine, as a library

Writing the loop, permissions, file tools and retries yourself becomes tiring. The Claude Agent SDK (Python/TypeScript) is the same engine that Claude Code runs on, packaged as a library for your programs. It includes the loop, the Read/Write/Bash/Grep tools, permissions, hooks, subagents and MCP.

When do you use the Claude API, and when the SDK? Here is the story version:

• You are building a support bot for your product that reads your docs and creates tickets → Agent SDK (you want the SDK to manage the loop and tools for you).
• You are adding one AI feature, such as "summarize this page" or "classify this email" → plain Claude API (one call, no loop needed; the SDK would be like using a truck to buy a few groceries).
• You are at a terminal writing software → Claude Code itself.

The model is the same at every level. You only choose how much of the harness you want already built.

The decision table (save this; it answers "SDK or API?" for every project):

One point confuses many people. pip install anthropic gives you the client library. It is a thin helper layer (client.messages.create(...)), and using it still counts as "using the Claude API" in every sense above: your code owns the loop. The Agent SDK is a different, higher-level product: the engine. There are three layers, from the bottom up: raw HTTPS → client library (nicer syntax, same responsibilities) → Agent SDK (the loop machinery, already built).

The warning sign: you may notice that you are writing tool dispatch, permission checks or compaction logic by hand. Then you are rebuilding the Agent SDK yourself, one bug at a time. Stop and use the SDK. The opposite warning sign: if your "agent" never loops, you did not need an agent engine. You needed one well-designed API call. (Mixing both is normal and good. For example, an agent runs on the SDK, and its harness also makes cheap raw-API calls for small classification tasks.)

Rung 5 · MCP — when your tools need to be plugs, not wiring

At Rung 3 you connected one tool to one program by hand. Now the story grows. Your company has a CRM, a ticket system and a wiki. You want all three in Claude Code, in Claude Desktop, and in the support bot you built with the SDK. Connecting them by hand means 3 systems × 3 apps = 9 integrations, and you must maintain each one forever.

MCP (Model Context Protocol) removes this multiplication. Each system provides one MCP server. Each app already speaks MCP as a client. That makes 3 + 3 = 6 pieces, and any new app gets all the servers at once. Think of it as USB-C for AI tools.

"Is MCP just a REST API?" — the comparison everyone needs

An MCP server is often a wrapper of about 100 lines around an existing REST API. Its value is the standard plug, not new functions.

Rung 6 · From "it works" to "it's an architecture"

The last rung is the real subject of the exam. You take rungs 1–5 and make them safe, cheap and reliable. That means guardrails the model cannot get around, budgets that stop an agent that runs out of control, caching that cuts costs by 90%, evaluations (evals) that catch regressions, and human approval wherever money moves. Those are Domains 1–5. You now have enough background to read them in order.

Your path from here

You now have the ladder in your head. So where do you start? Find the row that describes you and follow it:

🎯 Tip for every path: terms with a dotted underline in this guide are clickable. Each one opens a card with the definition, how it looks in code, and a story about when to use it. Use them often; that is why they exist.