CCDV-F quick reference

Current model IDs, prices and limits change; read them from docs.anthropic.com. This sheet covers the structure and rules that stay stable.

1. Agents and Workflows

Concept	Remember
Agent loop	call API, read stop_reason, run tools, append assistant content + tool_result user message, repeat
end_turn / tool_use / max_tokens	finished / run tools and call again / truncated, never execute a half-formed tool call
pause_turn / refusal	resend conversation unchanged / stop and log
Workflow vs agent	code decides steps vs model decides steps; start with the simplest
Patterns	chaining (sequential), routing (classify then dispatch), parallelisation (sectioning or voting), orchestrator-workers (runtime decomposition), evaluator-optimiser (generate, grade, loop)
Three build options	manual loop (own everything), SDK tool runner (loop automated, your tools only), Claude Agent SDK (Claude Code harness with built-in tools)
Agent SDK options	allowed_tools, permission_mode (default, acceptEdits, plan, bypassPermissions), system_prompt, mcp_servers, cwd, max_turns, hooks, resume

2. Applications and Integration

• Required request fields: model, max_tokens, messages. system is top-level, not a role.
• Roles: first message is user; consecutive same-role messages merge; the API is stateless so resend full history.
• Response: content array of typed blocks (text, tool_use, thinking), stop_reason, usage.
• Raw HTTP headers: x-api-key, anthropic-version, content-type; betas via anthropic-beta.
• SDK client: zero-arg constructor reads ANTHROPIC_API_KEY; max_retries default 2; timeout seconds (Python) vs milliseconds (TypeScript).
• Typed errors: AuthenticationError 401, RateLimitError 429, APIStatusError other; branch on class, not message text.
• Images: image block, source base64 | url | file; JPEG, PNG, GIF, WebP; image before text.
• PDFs: document block, application/pdf; text plus page images, so more tokens than text; optional citations: {enabled: true} (all docs or none; not with structured output).
• Files API: client.files.upload once, reference by file_id; storage ops free, content billed as input; uploads not downloadable.
• Streaming events in order: message_start → content_block_start → content_block_delta* → content_block_stop → message_delta (stop_reason, output usage) → message_stop; ping keep-alives; error can arrive mid-stream.
• Delta types: text_delta, input_json_delta (partial_json, concatenate then parse), thinking_delta.
• Helpers: client.messages.stream() → get_final_message() / finalMessage(); large max_tokens requires streaming.
• Batches: messages.batches.create(requests=[{custom_id, params}]); poll processing_status until ended; results in any order keyed by custom_id; outcomes succeeded / errored / canceled / expired; 24 h window, results kept 29 days; discounted; everything except streaming supported.
• Chat apps: key only on backend; store full assistant content; stable system for caching; trim history in whole pairs; persist after finalMessage(); opaque metadata.user_id.

3. Claude Code

Item	Key fact
CLAUDE.md	auto-loaded memory; user → project (shared) → CLAUDE.local.md → subdirectory; /init creates it
Settings	~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json; managed policy overrides
Permissions	allow/deny rules like Bash(npm test), Edit(src/**); modes default, acceptEdits, plan, bypassPermissions
Commands	built-ins /init /clear /compact /model /permissions /mcp; custom in .claude/commands/*.md with $ARGUMENTS
Hooks	PreToolUse, PostToolUse, UserPromptSubmit, Stop; exit 2 blocks
MCP	`claude mcp add --transport stdio
Headless	`claude -p "..." --output-format json

4. Eval, Testing and Debugging

• Build evals from real inputs; version them with the prompt; grow from production failures.
• Graders: code-based (preferred when checkable) → model-based with rubric and spot checks → human for high stakes.
• Mock the client in unit tests, including tool_use and max_tokens responses; separate small integration suite.
• Log id / request-id, usage, stop_reason, prompt version and model on every call.
• Symptoms: cut-off text = max_tokens; cache never hits = volatile prefix; 404 = model ID; role-alternation 400 = history bug; tool_use_id 400 = results not adjacent.

5. Model Selection and Optimisation

Topic	Rule
Tiers	Opus (most capable) > Sonnet (balanced) > Haiku (fastest, cheapest); verify with evals
IDs	alias → latest snapshot; dated snapshot is fixed; pin in production; client.models.list() shows access
Pricing	per million tokens; output ≫ input; tier-dependent; cache write premium, cache read discount; batch discount; thinking billed as output
usage sum	prompt size = input_tokens + cache_creation_input_tokens + cache_read_input_tokens
count_tokens	free, model-specific, includes system + tools + messages; never use third-party tokenisers
Caching	prefix match over tools → system → messages; cache_control: {type: "ephemeral"}; ≤ 4 breakpoints; 5 min default, ttl: "1h" optional; refreshed on read; minimum prefix length per model; top-level cache_control = automatic placement
Cache proof	cache_read_input_tokens > 0 on repeat; zero means timestamp, ID, unsorted JSON, varying tools or model switch
Rate limits	RPM, ITPM, OTPM per org and model; rise with tier; OTPM estimated from max_tokens; cache reads mostly exempt from ITPM; headers retry-after, x-ratelimit-*
Errors	400 fix request · 401 key · 403 permission · 404 model/path · 413 too large · 429 wait retry-after · 500/529 backoff
Latency	TTFT grows with input, generation with output; stream, cache, trim, smaller model, lower effort, parallelise

6. Prompt and Context Engineering

• Instructions and persona in system; task and data in user message; data wrapped in XML tags like <document>.
• Be specific, give reasons, say what to do instead of only what not to do; 2 to 5 diverse <example>s fix format.
• stop_sequences end generation; temperature where supported; assistant prefill is rejected on current models.
• Structured output: output_config: {format: {type: "json_schema", schema}} (replaces deprecated output_format); messages.parse() with Pydantic / Zod → parsed_output.
• Schema rules: additionalProperties: false, every property in required, subset of JSON Schema; validate ranges in code; check stop_reason before parsing.
• strict: true on a tool guarantees valid tool_use.input.
• Context: measure with count_tokens; truncate whole pairs; summarise old turns; limit tool result size at source; server-side context editing (clears) and compaction (summarises, echo the block back); edits invalidate cache from that point.

7. Security and Safety

Area	Rule
Keys	server-side only; env var or secret manager; never in client code, git, logs or URLs; workspaces per environment; spend limits; rotate create → deploy → verify → disable
Admin keys	sk-ant-admin... for Admin API only; cannot call Messages
Injection	direct (user) vs indirect (documents, web, tool and MCP results); defences: tagged untrusted data, system prompt stays trusted, least-privilege tools, human approval via your UI, validate inputs and outputs, sandbox, iteration caps, logging
Moderation	fast model + structured verdict on input/output/retrieved content; deterministic checks first; stop_reason: "refusal" with stop_details is terminal, do not loop rephrasings
Usage Policy	universal prohibitions; high-risk domains need qualified human oversight and disclosure; consumer products disclose AI and protect minors; operator enforces on users; no circumventing safeguards
Data	API data not used for training under commercial terms; retention windows documented; zero data retention available with feature caveats

8. Tools and MCPs

• Definition: name (^[a-zA-Z0-9_-]{1,64}$), description (what, when, when not, returns), input_schema (object, described properties, required); rendered before system in the cache prefix.
• tool_choice: auto (default), any, tool + name, none; disable_parallel_tool_use: true; forced forms rejected by some newest models (use auto + prompt or structured output).
• Call: stop_reason: "tool_use", block {type: "tool_use", id, name, input}; read input as an object.
• Result: user message of {type: "tool_result", tool_use_id, content, is_error?}; all results for a turn in one message immediately after the assistant turn; content may include text and image blocks.
• Never execute a tool call from a max_tokens response; return failures with is_error: true.
• Streaming tools: content_block_start (id, name) → input_json_delta fragments → content_block_stop → parse.
• SDK helpers: @beta_tool (Python), betaZodTool (TypeScript); tool runner loops for you but you still check stop reasons.
• Anthropic-defined: versioned type (bash, text editor) run client-side; server tools (web search, web fetch, code execution) run on Anthropic's side.
• MCP vocabulary: host, client, server; tools, resources, prompts; transports stdio (local) and streamable HTTP (remote).
• MCP connector: client.beta.messages.create(betas=[...], mcp_servers=[{type: "url", url, name, authorization_token?}], tools=[{type: "mcp_toolset", mcp_server_name}]); both halves required; remote only.
• Own client: list tools → map to Messages tools → dispatch tool_use → callTool → tool_result; SDK anthropic[mcp] helpers mcp_tool / async_mcp_tool.
• Agent SDK / Claude Code: mcp_servers option or claude mcp add; tools mcp__<server>__<tool> must be allow-listed; MCP results are untrusted; never hand a server your Anthropic key.