Back to Hub

Certification Study Notes

Claude Platform & API

Production engineering on the Claude Messages API: choosing a model and effort level, request shape and roles, explicit criteria and few-shot examples, the tool-use loop and its pairing rules, stop_reason handling, streaming events, structured outputs and schema design, validation and retry loops, adaptive thinking, context windows, compaction and prompt caching, preserving facts in long sessions, Message Batches, multi-pass review, retriable vs. terminal errors, evals and cost levers, human review and confidence calibration, deployment platforms and data residency, and security for apps that read untrusted content.

Author: Michaël Bettan

Track: Anthropic / Applied AI

Test Yourself: Claude API Practice Quiz →

import anthropic
client = anthropic.Anthropic()          # reads ANTHROPIC_API_KEY from the environment

resp = client.messages.create(
    model=PINNED_MODEL_ID,
    max_tokens=1024,
    system="You are a support assistant for Acme. Answer only from the provided policy.",
    messages=[
        {"role": "user", "content": "Can I return an opened item?"},
    ],
)
if resp.stop_reason == "end_turn":
    answer = next(b.text for b in resp.content if b.type == "text")

<examples>
  <example>
    <code>if user.is_admin or True:</code>
    <finding>{"location": "auth.py:42", "issue": "condition is always true, so the admin check is bypassed",
              "severity": "critical", "suggested_fix": "remove 'or True'"}</finding>
  </example>
  <example>
    <code>for i in range(len(items)):   # idiom used across this repo</code>
    <finding>none: style preference consistent with the codebase, not reported</finding>
  </example>
</examples>

messages.append({"role": "assistant", "content": resp.content})   # echo unchanged
results = []
for block in resp.content:
    if block.type == "tool_use":
        try:
            out = run_tool(block.name, block.input)                    # your authz + validation inside
            results.append({"type": "tool_result", "tool_use_id": block.id, "content": out})
        except ToolError as e:
            results.append({"type": "tool_result", "tool_use_id": block.id,
                            "content": f"lookup failed: {e.short}", "is_error": True})
messages.append({"role": "user", "content": results})                # all results, one turn, first

resp = client.messages.create(
    model=PINNED_MODEL_ID, max_tokens=1024,
    messages=[{"role": "user", "content": email_text}],
    output_config={"format": {"type": "json_schema", "schema": {
        "type": "object",
        "properties": {"name": {"type": "string"}, "demo_requested": {"type": "boolean"}},
        "required": ["name", "demo_requested"],
        "additionalProperties": False}}},
)
if resp.stop_reason == "end_turn":                      # check before parsing
    data = json.loads(next(b.text for b in resp.content if b.type == "text"))

• Forced choice (any / tool) errors with manual extended thinking, and some of the newest models reject it with a 400. There, use auto + strict: true + a prompt that says when to call the tool, or output_config.format.
• Where forced use is accepted, the response starts with the tool call and contains no thinking block.

record_invoice = {
    "name": "record_invoice", "strict": True,
    "description": "Record fields from ONE invoice. Use null when a field is not stated.",
    "input_schema": {"type": "object", "additionalProperties": False,
        "properties": {
            "invoice_number":  {"type": "string"},
            "due_date":        {"type": ["string", "null"], "description": "YYYY-MM-DD, or null if absent"},
            "category":        {"type": "string", "enum": ["hardware", "software", "services", "other"]},
            "category_detail": {"type": ["string", "null"]},
            "stated_total":    {"type": "number"}},
        "required": ["invoice_number", "due_date", "category", "category_detail", "stated_total"]}}

resp = client.messages.create(model=PINNED_MODEL_ID, max_tokens=1024, tools=[record_invoice],
                              tool_choice={"type": "tool", "name": "record_invoice"},
                              messages=[{"role": "user", "content": invoice_text}])
record = next(b for b in resp.content if b.type == "tool_use").input   # dict, schema-valid

def extract_with_retry(doc, max_retries=2):
    messages = [{"role": "user", "content": doc}]
    for attempt in range(max_retries + 1):
        resp = client.messages.create(model=PINNED_MODEL_ID, max_tokens=2048, tools=[record_invoice],
                                      tool_choice={"type": "tool", "name": "record_invoice"}, messages=messages)
        call = next(b for b in resp.content if b.type == "tool_use")
        errors = validate(call.input)            # sums, ranges, cross-field business rules
        if not errors:
            return call.input
        messages += [{"role": "assistant", "content": resp.content},
                     {"role": "user", "content": [{"type": "tool_result", "tool_use_id": call.id, "is_error": True,
                         "content": "Validation failed:\n" + "\n".join(errors) +
                                    "\nRe-read the document and fix only these fields. Use null if the value is not in it."}]}]
    return route_to_review(doc, call.input, errors)  # don't loop forever on absent data

case_facts = {"customer_id": "C-1029",
              "issues": {"A-7731": {"amount": 1240.18, "ask": "refund", "promised_by": "2026-03-14",
                                    "status": "return label sent"}}}
system = [{"type": "text", "text": STATIC_POLICY, "cache_control": {"type": "ephemeral"}},
          {"type": "text", "text": "<case_facts>\n" + json.dumps(case_facts) + "\n</case_facts>"}]

• Independence comes from context, not model choice; the reviewer can be the same model (a different tier is optional).
• Per-file passes are independent, so run them in parallel: sync for pre-merge checks, Message Batches for overnight audits (§12).
• See §10 (Builder–Reviewer separation) for the context contract, and the Claude Agent SDK guide for orchestrating reviewers inside agent loops.

resp = client.messages.create(
    model=NEW_PINNED_ID, max_tokens=4096,
    temperature=0,                                            # (a)
    thinking={"type": "enabled", "budget_tokens": 8000},      # (b)
    tools=TOOLS, messages=messages,
)
messages.append({"role": "assistant",                         # (c)
                 "content": [b for b in resp.content if b.type != "thinking"]})
call = next(b for b in resp.content if b.type == "tool_use")
try:
    out = run_tool(call.name, call.input)
except Exception:
    out = ""                                                  # (d)
messages.append({"role": "user", "content": [
    {"type": "text", "text": "Here is the result:"},          # (e)
    {"type": "tool_result", "tool_use_id": call.id, "content": out},
]})