AnthropicClaude Certified Architect – Professional2026-100 Prerequisites
Make Messages an explicit service contract
Completed by the knowledge check
Learning objective
Read Messages API requests and responses: system prompts, roles, content blocks, stop reasons, and usage fields.
Core idea
The Messages API exchanges typed content and requires the application to supply conversational history on each stateless call. At Professional level, the decision is who owns the request and response contract so that a model response cannot silently become a completed business operation.
Your service needs distinct owners for context assembly, response interpretation, and business acceptance. A display adapter that extracts text cannot take over the other two responsibilities merely because the API returned successfully.
How it works
Read a Messages exchange as a set of responsibilities. The following fields identify the relevant boundaries:
| Boundary | Fields to inspect | Architectural responsibility |
|---|---|---|
| Request assembly | model, max_tokens, top-level system, messages | Select the model, set instructions, and assemble the intended history and evidence. |
| Conversation structure | role, content, block type | Preserve speaker identity and typed content separately from display text. |
| Response interpretation | id, model, content, stop_reason | Identify the generated message and decide what processing remains. |
| Resource accounting | usage.input_tokens, usage.output_tokens, cache fields | Record consumed tokens independently of visible answer length. |
The conversation record preserves message role and content-block type; rendered text is a view of that record. Assign the instruction contract to the prompt owner (see 2.2.1), the tool protocol to its executor (see 0.4), and the separation of inference from execution to the service architecture (see 1.2.2).
Interpret stop_reason before accepting a result. end_turn means generation ended naturally, not that a business rule passed. tool_use means tool processing remains; max_tokens means the output reached its generation limit. For a truncated response, raise the allowance or use the documented continuation approach rather than accepting a partial answer. The other stop reasons distinguish interruption paths your adapter must handle:
| Stop reason | Cause | Response action |
|---|---|---|
stop_sequence | Claude generated one of your stop_sequences. | Read stop_sequence to identify which sequence fired. |
pause_turn | A server-tool loop reached its iteration limit. | Send the assistant content back to continue. |
refusal | Claude declined to respond. | Read stop_details and retry on a fallback model. |
model_context_window_exceeded | The response filled the model’s context window. | Treat the response as truncated. |
See 1.2.3 for result validation and 4.6.1 for recording stop reasons.
For accounting, total input is input_tokens + cache_creation_input_tokens + cache_read_input_tokens. The cached portions still occupy context. API token accounting does not map one-to-one to visible text; preserve usage rather than estimating consumption from rendered characters. See 4.5.1 for cost baselines and 2.4.3 for long-history management.
Key distinctions and trade-offs
Keeping structured content lets the executor interpret blocks and the interface render text from the same record. Flattening early simplifies display but loses information those consumers need. Likewise, an HTTP success establishes successful API processing, while stop_reason and semantic validation answer different completion questions.
Architecture / decision scenario
A healthcare provider pilots a policy-answering assistant with a three-second response target. Clinical reviewers approve explanations before staff act on them; the assistant has no authority to change patient records.
You assign the integration team the initial system, role-preserving history, and full content record. The adapter routes blocks by type, checks stop_reason, and sends naturally completed explanations to the review queue. A max_tokens response remains incomplete and uses the documented recovery path. A refusal enters the approved fallback path after the adapter inspects stop_details; any resulting explanation still needs clinical review. The cost dashboard includes cache token fields, so the team can compare reuse savings without claiming that cached policies disappear from context.
Common exam traps
Watch for these contract errors:
- Treating
pause_turnas a failed request instead of a continuation point. - Reading
end_turnas proof of business acceptance. - Counting only
usage.input_tokenswhen cached input is present.
What to remember
Assign owners to assembly, interpretation, and acceptance. Preserve typed content, check why generation stopped, and retain complete usage accounting before a response becomes a business outcome.
Knowledge check
A research assistant uses the web_search server tool. The adapter logs every response with stop_reason: "pause_turn" as a failure and retries the original request. What should the adapter do instead?
tool_result blocks for the pending server tool callsmax_tokens and resend the original requestpause_turn means a server-tool loop reached its iteration limit; it is a continuation point, not a failure, and you continue by sending the assistant content back. tool_result blocks answer a client tool’s tool_use stop, and a raised max_tokens addresses truncation, which is a different stop reason.An insurer’s adapter receives HTTP 200 with stop_reason: "end_turn" for a drafted claim decision. Policy requires an adjuster to approve every decision before payment. What should the adapter do with this response?
end_turn says generation ended naturally; neither says a business rule passed. The stated review policy still applies, so route the draft to the adjuster rather than infer approval or a recovery path from HTTP success.A cost dashboard sums usage.input_tokens per request. After the team enables prompt caching, input consumption appears to fall by 80%, and the team concludes the cached policies no longer occupy the context window. Which correction should you make?
input_tokens plus both cache token fields as total inputinput_tokens alone as the measure of total inputinput_tokens minus cache_read_input_tokens as total inputinput_tokens + cache_creation_input_tokens + cache_read_input_tokens , and all three count toward the context window. Caching changes how input is split and billed, not whether it is in context; token counts also do not map one-to-one to visible characters, so keep usage rather than estimating.A contract-summarization adapter receives a response with stop_reason: "refusal". Which handling path should it route the response to?
stop_details ; retry on a fallback modelmax_tokens and resend the same requeststop_details identifies why, and the documented path is a retry on a fallback model. Sending content back is the pause_turn path and raising max_tokens is the truncation path, so neither fits a refusal.References
- Anthropic, Create a Message
- Anthropic, Using the Messages API
- Anthropic, Handling stop reasons
- Anthropic, Tool use with Claude
- Anthropic, Context windows