Reference · appendix consolidation

API & SDK Essentials

Every primitive named in the Exam Guide appendix, in one place — including the small ones the lessons only touch (max_tokens, system prompts, stop_reason values, Pydantic).

Claude API — the request/response primitives

PrimitiveWhat to know for the exam
stop_reasonWhy generation stopped. Values you should recognize: "tool_use" (wants a tool → continue the loop), "end_turn" (done → stop), "max_tokens" (hit the output cap — output is truncated, not complete; not a normal completion), plus stop-sequence. Loop control keys off tool_use/end_turn.
max_tokensUpper bound on tokens the model may generate in one response. If output is cut off you'll see stop_reason: "max_tokens". It does not control what the model can see (that's the context window) and does not fix attention-dilution or memory issues — a recurring distractor.
System promptTop-level instructions/role/criteria. Powerful, but probabilistic — never the answer when a hard guarantee is required (use a hook/gate). Watch for keyword-sensitive wording that can override well-written tool descriptions.
tool_useThe content block where the model requests a tool. With a JSON schema it's the most reliable route to schema-valid structured output (kills syntax errors, not semantic ones).
tool_choice"auto" (may answer in text) · "any" (must call some tool) · forced {"type":"tool","name":"X"} (must call X). See D2·L3.

Claude Agent SDK

Agentic loop
Send → inspect stop_reason → run tool + append result → repeat until end_turn. Stateless calls: results must be appended to history. (D1·L1)
AgentDefinition
Declarative config for a subagent type: a description (when the coordinator should use it), a system prompt (its role/behavior), and tool restrictions (its scoped toolset). Distinct per subagent type; this is how you enforce least-privilege per role and how the coordinator knows which subagent fits a task. (D1·L2)
Task tool + allowedTools
Spawns subagents; coordinator's allowedTools must include "Task". Multiple Task calls in one response = parallel subagents.
Hooks
PostToolUse (transform results before the model sees them) and tool-call interception (block/redirect outgoing calls). Deterministic — use for guarantees. (D1·L3)
Sessions
--resume <name>, fork_session, fresh+summary. (D1·L4)

Model Context Protocol (MCP)

Tools vs resources
Tools act; resources expose content catalogs to cut exploratory calls.
isError + structured metadata
Signal failures with errorCategory, isRetryable, human-readable text.
Config scope
Project .mcp.json (shared, ${ENV} expansion) vs user ~/.claude.json. All configured servers' tools are discovered at connection time and available simultaneously.

Message Batches API

Profile
~50% cheaper · up to 24h · no latency SLA · no multi-turn tool calling in a single request · custom_id correlates request/response. Good for overnight/weekly; wrong for blocking pre-merge. (D4·L3)

Schema & validation

JSON Schema
Required vs optional, enum types, nullable fields, "other"+detail patterns, strict mode eliminates syntax errors only.
Pydantic
Python schema-validation library commonly used to validate extraction output. It catches both schema violations and (via validators) semantic checks; a failed Pydantic validation is what you feed back into a retry-with-error-feedback loop. Retries fix format/structural errors, never information that's absent from the source. (D4·L2)

Claude Code CLI

-p / --print
Non-interactive: process, print to stdout, exit. Required in CI to avoid hangs.
--output-format json + --json-schema
Machine-parseable structured findings for automated PR comments.
/memory, /compact
Inspect loaded memory files; compress context in long sessions.
Out of scope — don't over-studyFine-tuning/training, API auth/billing, MCP server hosting/infra, Claude internals/RLHF/Constitutional AI, embeddings/vector DBs, computer use, vision, streaming/SSE, rate limits/quotas/pricing, OAuth/key rotation, cloud-provider configs, benchmarking, prompt-caching internals, tokenization specifics.