Claude API

Building LLM-Powered Applications with Claude

When to use (agent triggers)

TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, anthropic, @anthropic-ai, claude-*, us.anthropic.*, [1m]); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens).

SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama' over the project hits (run this grep FIRST if no provider named — don't Read the file).

This skill helps you build LLM-powered applications with Claude. Choose the right surface based on your needs, detect the project language, then read the relevant language-specific documentation.

Before You Start

Scan the target file (or, if no target file, the prompt and project) for non-Anthropic provider markers — import openai, from openai, langchain_openai, OpenAI(, gpt-4, gpt-5, file names like agent-openai.py or *-generic.py, or any explicit instruction to keep the code provider-neutral. If you find any, stop and tell the user that this skill produces Claude/Anthropic SDK code; ask whether they want to switch the file to Claude or want a non-Claude implementation. Do not edit a non-Anthropic file with Anthropic SDK calls.

Output Requirement

When the user asks you to add, modify, or implement a Claude feature, your code must call Claude through one of:

1. The official Anthropic SDK for the project's language (anthropic, @anthropic-ai/sdk, com.anthropic.*, etc.). This is the default whenever a supported SDK exists for the project.
2. Raw HTTP (curl, requests, fetch, httpx, etc.) — only when the user explicitly asks for cURL/REST/raw HTTP, the project is a shell/cURL project, or the language has no official SDK.

Never mix the two — don't reach for requests/fetch in a Python or TypeScript project just because it feels lighter. Never fall back to OpenAI-compatible shims.

Never guess SDK usage. Function names, class names, namespaces, method signatures, and import paths must come from explicit documentation — either the {lang}/ files in this skill or the official SDK repositories or documentation links listed in shared/live-sources.md. If the binding you need is not explicitly documented in the skill files, WebFetch the relevant SDK repo from shared/live-sources.md before writing code. Do not infer Ruby/Java/Go/PHP/C# APIs from cURL shapes or from another language's SDK.

Defaults

Unless the user requests otherwise:

For the Claude model version, please use Claude Opus 4.8, which you can access via the exact model string claude-opus-4-8. Please default to using adaptive thinking (thinking: {type: "adaptive"}) for anything remotely complicated. And finally, please default to streaming for any request that may involve long input, long output, or high max_tokens — it prevents hitting request timeouts. Use the SDK's .get_final_message() / .finalMessage() helper to get the complete response if you don't need to handle individual stream events

Subcommands

If the User Request at the bottom of this prompt is a bare subcommand string (no prose), search every Subcommands table in this document — including any in sections appended below — and follow the matching Action column directly. This lets users invoke specific flows via /claude-api <subcommand>. If no table in the document matches, treat the request as normal prose.

Language Detection

Before reading code examples, determine which language the user is working in:

1. Look at project files to infer the language:

   • *.py, requirements.txt, pyproject.toml, setup.py, Pipfile → Python — read from python/
   • *.ts, *.tsx, package.json, tsconfig.json → TypeScript — read from typescript/
   • *.js, *.jsx (no .ts files present) → TypeScript — JS uses the same SDK, read from typescript/
   • *.java, pom.xml, build.gradle → Java — read from java/
   • *.kt, *.kts, build.gradle.kts → Java — Kotlin uses the Java SDK, read from java/
   • *.scala, build.sbt → Java — Scala uses the Java SDK, read from java/
   • *.go, go.mod → Go — read from go/
   • *.rb, Gemfile → Ruby — read from ruby/
   • *.cs, *.csproj → C# — read from csharp/
   • *.php, composer.json → PHP — read from php/

2. If multiple languages detected (e.g., both Python and TypeScript files):

   • Check which language the user's current file or question relates to
   • If still ambiguous, ask: "I detected both Python and TypeScript files. Which language are you using for the Claude API integration?"

3. If language can't be inferred (empty project, no source files, or unsupported language):

   • Use AskUserQuestion with options: Python, TypeScript, Java, Go, Ruby, cURL/raw HTTP, C#, PHP
   • If AskUserQuestion is unavailable, default to Python examples and note: "Showing Python examples. Let me know if you need a different language."

4. If unsupported language detected (Rust, Swift, C++, Elixir, etc.):

   • Suggest cURL/raw HTTP examples from curl/ and note that community SDKs may exist
   • Offer to show Python or TypeScript examples as reference implementations

5. If user needs cURL/raw HTTP examples, read from curl/.

Language-Specific Feature Support

Managed Agents code examples: dedicated language-specific READMEs are provided for Python, TypeScript, Go, Ruby, PHP, Java, and cURL ({lang}/managed-agents/README.md, curl/managed-agents.md). Read your language's README plus the language-agnostic shared/managed-agents-*.md concept files. Agents are persistent — create once, reference by ID. Store the agent ID returned by agents.create and pass it to every subsequent sessions.create; do not call agents.create in the request path. The Anthropic CLI (ant) is one convenient way to create agents and environments from version-controlled YAML — see shared/anthropic-cli.md. If a binding you need isn't shown in the README, WebFetch the relevant entry from shared/live-sources.md rather than guess. C# has beta Managed Agents support via client.Beta.Agents and related namespaces.

Which Surface Should I Use?

Start simple. Default to the simplest tier that meets your needs. Single API calls and workflows handle most use cases — only reach for agents when the task genuinely requires open-ended, model-driven exploration.

Note: Managed Agents is the right choice when you want Anthropic to run the agent loop and host the container where tools execute — file ops, bash, code execution all run in the per-session workspace. If you want to host the compute yourself or run your own custom tool runtime, Claude API + tool use is the right choice — use the tool runner for automatic loop handling, or the manual loop for fine-grained control (approval gates, custom logging, conditional execution).

Cloud-provider access. Claude Platform on AWS is Anthropic-operated with same-day API parity — Managed Agents and every feature in this skill work there, except self-hosted sandboxes (see shared/claude-platform-on-aws.md). Amazon Bedrock, Google Vertex AI, and Microsoft Foundry do not support Managed Agents or Anthropic server-side tools; use Claude API + tool use on those.

Decision Tree

What does your application need?

0. Which provider?
   ├── First-party API or Claude Platform on AWS → continue (full surface available).
   └── Amazon Bedrock, Google Vertex AI, or Microsoft Foundry → Claude API (+ tool use for agents); Managed Agents not available there.

1. Single LLM call (classification, summarization, extraction, Q&A)
   └── Claude API — one request, one response

2. Do you want Anthropic to run the agent loop and host a per-session
   container where Claude executes tools (bash, file ops, code)?
   └── Yes → Managed Agents — server-managed sessions, persisted agent configs,
       SSE event stream, Skills + MCP, file mounts.
       Examples: "stateful coding agent with a workspace per task",
                 "long-running research agent that streams events to a UI",
                 "agent with persisted, versioned config used across many sessions"

3. Workflow (multi-step, code-orchestrated, with your own tools)
   └── Claude API with tool use — you control the loop

4. Open-ended agent (model decides its own trajectory, your own tools, you host the compute)
   └── Claude API agentic loop (maximum flexibility)

Should I Build an Agent?

Before choosing the agent tier, check all four criteria:

• Complexity — Is the task multi-step and hard to fully specify in advance? (e.g., "turn this design doc into a PR" vs. "extract the title from this PDF")
• Value — Does the outcome justify higher cost and latency?
• Viability — Is Claude capable at this task type?
• Cost of error — Can errors be caught and recovered from? (tests, review, rollback)

If the answer is "no" to any of these, stay at a simpler tier (single call or workflow).

Architecture

Everything goes through POST /v1/messages. Tools and output constraints are features of this single endpoint — not separate APIs.

User-defined tools — You define tools (via decorators, Zod schemas, or raw JSON), and the SDK's tool runner handles calling the API, executing your functions, and looping until Claude is done. For full control, you can write the loop manually.

Server-side tools — Anthropic-hosted tools that run on Anthropic's infrastructure. Code execution is fully server-side (declare it in tools, Claude runs code automatically). Computer use can be server-hosted or self-hosted.

Structured outputs — Constrains the Messages API response format (output_config.format) and/or tool parameter validation (strict: true). The recommended approach is client.messages.parse() which validates responses against your schema automatically. Note: the old output_format parameter is deprecated; use output_config: {format: {...}} on messages.create().

Supporting endpoints — Batches (POST /v1/messages/batches), Files (POST /v1/files), Token Counting (POST /v1/messages/count_tokens — see shared/token-counting.md), and Models (GET /v1/models, GET /v1/models/{id} — live capability/context-window discovery) feed into or support Messages API requests.

Current Models (cached: 2026-06-04)

ALWAYS use claude-opus-4-8 unless the user explicitly names a different model. This is non-negotiable. Do not use claude-sonnet-4-6, claude-sonnet-4-5, or any other model unless the user literally says "use sonnet" or "use haiku". Never downgrade for cost — that's the user's decision, not yours. Use claude-fable-5 only when the user explicitly asks for Claude Fable 5, "fable", or Anthropic's most capable model — it has different API behavior than the Opus family (see below) and pricing that exceeds Opus-tier.

Claude Fable 5 (claude-fable-5) — most capable widely released model

Claude Fable 5 is Anthropic's most capable widely released model, for the most demanding reasoning and long-horizon agentic work. Claude Mythos 5 (claude-mythos-5) offers the same capabilities, pricing, and API surface through Project Glasswing (participation is the only way to access it), succeeding the invitation-only Claude Mythos Preview (claude-mythos-preview) — everything below applies to both models. 1M context window (the maximum is also the default), 128K max output. Key API differences from Opus-tier — see shared/model-migration.md → Migrating to Claude Fable 5 for details:

• Thinking is always on — omit the thinking parameter entirely (or send {type: "adaptive"}). Any other explicit configuration is rejected: {type: "disabled"} and {type: "enabled", budget_tokens: N} both return a 400. Control depth with output_config.effort (supports low through xhigh and max).
• Protected thinking = the raw chain of thought, not the summary — responses carry regular thinking blocks (not redacted_thinking): display: "summarized" returns a readable summary, "omitted" (the default) leaves the thinking field as an empty string; the raw chain of thought is never exposed on any model. Replay rules: pass thinking blocks back exactly as received on the same model (including empty-text blocks — the API rejects modified blocks, not read ones); a different model silently ignores them (not an error), but ignored blocks still bill input tokens — strip them when switching models for good.
• New tokenizer — the same content tokenizes to roughly 30% more tokens than on Opus-tier models. Don't reuse token counts or max_tokens settings measured on other models; re-baseline with count_tokens.
• refusal stop reason — safety classifiers may decline a request (HTTP 200, stop_reason: "refusal", with a stop_details category). A pre-output refusal has an empty content array and is not billed at all; a mid-stream refusal bills the already-streamed output — discard the partial output. Always check stop_reason before reading content. To retry on another model: the beta fallbacks parameter (Claude API and Claude Platform on AWS) retries server-side in one round trip; the GA SDKs' BetaRefusalFallbackMiddleware + BetaFallbackState handle client-side retry everywhere else (incl. Bedrock/Vertex); fallback credit refunds the cache-switch cost of client-side retries. See the migration guide's refusal section.
• No assistant prefill — same as the rest of the 4.6+ family.
• 30-day data retention required — Claude Fable 5 is not available under zero data retention; requests from an org whose retention configuration doesn't meet the requirement return 400 invalid_request_error.
• Longer turns, different prompting — single requests on hard tasks can run many minutes (plan timeouts/streaming/progress UX); effort sweeps should include low/medium for routine work; prompts written for prior models are often too prescriptive and reduce output quality. See shared/model-migration.md → Migrating to Claude Fable 5 → Behavioral shifts (prompt-tunable) for the recommended prompt snippets (anti-overplanning, no-tidying, grounded progress claims, boundaries, async sub-agents, memory, send_to_user).

CRITICAL: Use only the exact model ID strings from the table above — they are complete as-is. Do not append date suffixes. For example, use claude-sonnet-4-6, never claude-sonnet-4-6-20251114 or any other date-suffixed variant you might recall from training data. If the user requests an older model not in the table (e.g., "opus 4.5", "sonnet 3.7"), read shared/models.md for the exact ID — do not construct one yourself.

A note: if any of the model strings above look unfamiliar to you, that's to be expected — that just means they were released after your training data cutoff. Rest assured they are real models; we wouldn't mess with you like that.

Live capability lookup: The table above is cached. When the user asks "what's the context window for X", "does X support vision/thinking/effort", or "which models support Y", query the Models API (client.models.retrieve(id) / client.models.list()) — see shared/models.md for the field reference and capability-filter examples.

Thinking & Effort (Quick Reference)

Fable 5 / Opus 4.8 / 4.7 — Adaptive thinking only: Use thinking: {type: "adaptive"}. thinking: {type: "enabled", budget_tokens: N} returns a 400 — adaptive is the only on-mode. On Opus 4.8 and 4.7, {type: "disabled"} and omitting thinking both work; on Fable 5, an explicit {type: "disabled"} returns a 400 — omit the thinking param entirely instead. Sampling parameters (temperature, top_p, top_k) are also removed and will 400. Opus 4.8 keeps the same request surface as 4.7 (no new breaking changes) — see shared/model-migration.md → Migrating to Opus 4.8 for the behavioral re-tuning, and → Migrating to Opus 4.7 for the full breaking-change list when coming from 4.6 or earlier. Note: with thinking disabled, Opus 4.8 may write longer reasoning into the visible response — leave adaptive thinking on, or add a final-answer-only instruction (see the migration guide). Opus 4.6 — Adaptive thinking (recommended): Use thinking: {type: "adaptive"}. Claude dynamically decides when and how much to think. No budget_tokens needed — budget_tokens is deprecated on Opus 4.6 and Sonnet 4.6 and should not be used for new code. Adaptive thinking also automatically enables interleaved thinking (no beta header needed). When the user asks for "extended thinking", a "thinking budget", or budget_tokens: always use Fable 5, Opus 4.8, 4.7, or 4.6 with thinking: {type: "adaptive"}. The concept of a fixed token budget for thinking is deprecated — adaptive thinking replaces it. Do NOT use budget_tokens for new 4.6/4.7/4.8 code and do NOT switch to an older model. Gradual-migration carve-out: budget_tokens is still functional on Opus 4.6 and Sonnet 4.6 as a transitional escape hatch — if you're migrating existing code and need a hard token ceiling before you've tuned effort, see shared/model-migration.md → Transitional escape hatch. Note: this carve-out does not apply to Fable 5, Opus 4.7 or 4.8 — budget_tokens is fully removed there. Effort parameter (GA, no beta header): Controls thinking depth and overall token spend via output_config: {effort: "low"|"medium"|"high"|"max"} (inside output_config, not top-level). Default is high (equivalent to omitting it). max is supported on Fable 5, Opus 4.6 and later, and Sonnet 4.6 (not Haiku or earlier Sonnets). Opus 4.7 added "xhigh" (between high and max) — the best setting for most coding and agentic use cases on Fable 5 / Opus 4.7/4.8, and the default in Claude Code; use a minimum of high for most intelligence-sensitive work. Works on Fable 5, Opus 4.5, Opus 4.6, Opus 4.7, Opus 4.8, and Sonnet 4.6. Will error on Sonnet 4.5 / Haiku 4.5. On Fable 5, Opus 4.7 and 4.8, effort matters more than on any prior Opus — re-tune it when migrating, and run long-horizon/agentic tasks at high/xhigh with the full task spec given up front. Combine with adaptive thinking for the best cost-quality tradeoffs. Lower effort means fewer and more-consolidated tool calls, less preamble, and terser confirmations — high is often the sweet spot balancing quality and token efficiency; use max when correctness matters more than cost; use low for subagents or simple tasks.

Thinking display — "omitted" by default on Fable 5 / Mythos 5 / Opus 4.8 / 4.7: display: "summarized" returns a readable summary of the reasoning; "omitted" (the default on all four — a silent change from Opus 4.6, where it was "summarized") streams thinking blocks with empty text. display controls visibility only — thinking happens and is billed the same under every setting; the raw chain of thought is never exposed on any model. If you stream reasoning to users, the default looks like a long pause before output — set thinking: {type: "adaptive", display: "summarized"} explicitly. (Independent of display, echo thinking blocks back unchanged when continuing on the same model; other models silently ignore them — see the migration guide.)

Task Budgets (beta, Fable 5 / Opus 4.7 / 4.8): output_config: {task_budget: {type: "tokens", total: N}} tells the model how many tokens it has for a full agentic loop — it sees a running countdown and self-moderates (minimum 20,000; beta header task-budgets-2026-03-13). Distinct from max_tokens, which is an enforced per-response ceiling the model is not aware of. See shared/model-migration.md → Task Budgets.

Sonnet 4.6: Supports adaptive thinking (thinking: {type: "adaptive"}). budget_tokens is deprecated on Sonnet 4.6 — use adaptive thinking instead.

Older models (only if explicitly requested): If the user specifically asks for Sonnet 4.5 or another older model, use thinking: {type: "enabled", budget_tokens: N}. budget_tokens must be less than max_tokens (minimum 1024). Never choose an older model just because the user mentions budget_tokens — use Opus 4.8 with adaptive thinking instead.

Compaction (Quick Reference)

Beta, Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6. For long-running conversations that may exceed the 1M context window, enable server-side compaction. The API automatically summarizes earlier context when it approaches the trigger threshold (default: 150K tokens). Requires beta header compact-2026-01-12.

Critical: Append response.content (not just the text) back to your messages on every turn. Compaction blocks in the response must be preserved — the API uses them to replace the compacted history on the next request. Extracting only the text string and appending that will silently lose the compaction state.

See {lang}/claude-api/README.md (Compaction section) for code examples. Full docs via WebFetch in shared/live-sources.md.

Prompt Caching (Quick Reference)

Prefix match. Any byte change anywhere in the prefix invalidates everything after it. Render order is tools → system → messages. Keep stable content first (frozen system prompt, deterministic tool list), put volatile content (timestamps, per-request IDs, varying questions) after the last cache_control breakpoint.

Mid-conversation operator instructions (beta header mid-conversation-system-2026-04-07, on supporting models): append {"role": "system", ...} to messages[] instead of editing top-level system. Preserves the cached history prefix and is the prompt-injection-safe operator channel. See shared/prompt-caching.md § Mid-conversation system messages.

Top-level auto-caching (cache_control: {type: "ephemeral"} on messages.create()) is the simplest option when you don't need fine-grained placement. Max 4 breakpoints per request. Minimum cacheable prefix is ~1024 tokens — shorter prefixes silently won't cache.

Verify with usage.cache_read_input_tokens — if it's zero across repeated requests, a silent invalidator is at work (datetime.now() in system prompt, unsorted JSON, varying tool set).

For placement patterns, architectural guidance, and the silent-invalidator audit checklist: read shared/prompt-caching.md. Language-specific syntax: {lang}/claude-api/README.md (Prompt Caching section).

Managed Agents (Beta)

Managed Agents is a third surface: server-managed stateful agents with Anthropic-hosted tool execution. You create a persisted, versioned Agent config (POST /v1/agents), then start Sessions that reference it. Each session provisions a container as the agent's workspace — bash, file ops, and code execution run there; the agent loop itself runs on Anthropic's orchestration layer and acts on the container via tools. The session streams events; you send messages and tool results back.

Managed Agents is available on the first-party API and Claude Platform on AWS. It is not available on Amazon Bedrock, Google Vertex AI, or Microsoft Foundry — for agents there, use Claude API + tool use.

Mandatory flow: Agent (once) → Session (every run). model/system/tools live on the agent, never the session. See shared/managed-agents-overview.md for the full reading guide, beta headers, and pitfalls.

Beta headers: managed-agents-2026-04-01 — the SDK sets this automatically for all client.beta.{agents,environments,sessions,vaults,memory_stores,deployments,deployment_runs}.* calls. Skills API uses skills-2025-10-02 and Files API uses files-api-2025-04-14, but you don't need to explicitly pass those in for endpoints other than /v1/skills and /v1/files.

Subcommands — invoke directly with /claude-api <subcommand>:

Reading guide: Start with shared/managed-agents-overview.md, then the topical shared/managed-agents-*.md files (core, environments, tools, events, outcomes, multiagent, webhooks, memory, scheduled-deployments, client-patterns, onboarding, api-reference). For Python, TypeScript, Go, Ruby, PHP, and Java, read {lang}/managed-agents/README.md for code examples. For cURL, read curl/managed-agents.md. Agents are persistent — create once, reference by ID. Store the agent ID returned by agents.create and pass it to every subsequent sessions.create; do not call agents.create in the request path. The Anthropic CLI (ant) is one convenient way to create agents and environments from version-controlled YAML — see shared/anthropic-cli.md. If a binding you need isn't shown in the language README, WebFetch the relevant entry from shared/live-sources.md rather than guess. C# has beta Managed Agents support via client.Beta.Agents and related namespaces.

When the user wants to set up a Managed Agent from scratch (e.g. "how do I get started", "walk me through creating one", "set up a new agent"): read shared/managed-agents-onboarding.md and run its interview — same flow as the managed-agents-onboard subcommand.

When the user asks "how do I write the client code for X": reach for shared/managed-agents-client-patterns.md — covers lossless stream reconnect, processed_at queued/processed gate, interrupt, tool_confirmation round-trip, the correct idle/terminated break gate, post-idle status race, stream-first ordering, file-mount gotchas, keeping credentials host-side via custom tools, etc.

When the user wants the agent to run on a schedule (cron, "every night", "weekly report"): read shared/managed-agents-scheduled-deployments.md — deployments fire sessions autonomously on a cron cadence, with run records, retries, and auto-pause.

Reading Guide

After detecting the language, read the relevant files based on what the user needs:

Quick Task Reference

Single text classification/summarization/extraction/Q&A: → Read only {lang}/claude-api/README.md

Chat UI or real-time response display: → Read {lang}/claude-api/README.md + {lang}/claude-api/streaming.md

Long-running conversations (may exceed context window): → Read {lang}/claude-api/README.md — see Compaction section Migrating to a newer model (Fable 5 / Opus 4.8 / Opus 4.7 / Opus 4.6 / Sonnet 4.6) or replacing a retired model: → Read shared/model-migration.md Prompting or tuning Fable 5 (long turns, effort, verbosity, autonomous runs, sub-agents): → Read shared/model-migration.md → Migrating to Fable 5 → Behavioral shifts (prompt-tunable) + Long-running agent recommendations Prompt caching / optimize caching / "why is my cache hit rate low": → Read shared/prompt-caching.md + {lang}/claude-api/README.md (Prompt Caching section) Count tokens in a file / prompt / diff ("how many tokens is X"): → Read shared/token-counting.md — use messages.count_tokens, never tiktoken

Function calling / tool use / agents: → Read {lang}/claude-api/README.md + shared/tool-use-concepts.md + {lang}/claude-api/tool-use.md

Agent design (tool surface, context management, caching strategy): → Read shared/agent-design.md

Batch processing (non-latency-sensitive): → Read {lang}/claude-api/README.md + {lang}/claude-api/batches.md

File uploads across multiple requests: → Read {lang}/claude-api/README.md + {lang}/claude-api/files-api.md

Managed Agents (server-managed stateful agents with workspace): → Read shared/managed-agents-overview.md + the rest of the shared/managed-agents-*.md files. For Python, TypeScript, Go, Ruby, PHP, and Java, read {lang}/managed-agents/README.md for code examples. For cURL, read curl/managed-agents.md. Agents are persistent — create once, reference by ID. Store the agent ID returned by agents.create and pass it to every subsequent sessions.create; do not call agents.create in the request path. The Anthropic CLI (ant) is one convenient way to create agents and environments from version-controlled YAML — see shared/anthropic-cli.md. If a binding you need isn't shown in the language README, WebFetch the relevant entry from shared/live-sources.md rather than guess. C# has beta Managed Agents support — see csharp/claude-api.md for details, or curl/managed-agents.md for raw HTTP reference.

Claude API (Full File Reference)

Read the language-specific Claude API folder ({language}/claude-api/):

1. {language}/claude-api/README.md — Read this first. Installation, quick start, common patterns, error handling.
2. shared/tool-use-concepts.md — Read when the user needs function calling, code execution, memory, or structured outputs. Covers conceptual foundations.
3. shared/agent-design.md — Read when designing an agent: bash vs. dedicated tools, programmatic tool calling, tool search/skills, context editing vs. compaction vs. memory, caching principles.
4. {language}/claude-api/tool-use.md — Read for language-specific tool use code examples (tool runner, manual loop, code execution, memory, structured outputs).
5. {language}/claude-api/streaming.md — Read when building chat UIs or interfaces that display responses incrementally.
6. {language}/claude-api/batches.md — Read when processing many requests offline (not latency-sensitive). Runs asynchronously at 50% cost.
7. {language}/claude-api/files-api.md — Read when sending the same file across multiple requests without re-uploading.
8. shared/prompt-caching.md — Read when adding or optimizing prompt caching. Covers prefix-stability design, breakpoint placement, and anti-patterns that silently invalidate cache.
9. shared/error-codes.md — Read when debugging HTTP errors or implementing error handling.
10. shared/model-migration.md — Read when upgrading to newer models, replacing retired models, or translating budget_tokens / prefill patterns to the current API.
11. shared/live-sources.md — WebFetch URLs for fetching the latest official documentation.

Note: For Java, Go, Ruby, C#, PHP, and cURL — these have a single file each covering all basics. Read that file plus shared/tool-use-concepts.md and shared/error-codes.md as needed.

Note: For the Managed Agents file reference, see the ## Managed Agents (Beta) section above — it lists every shared/managed-agents-*.md file and the language-specific READMEs.

When to Use WebFetch

Use WebFetch to get the latest documentation when:

• User asks for "latest" or "current" information
• Cached data seems incorrect
• User asks about features not covered here

Live documentation URLs are in shared/live-sources.md.

Common Pitfalls

• Don't truncate inputs when passing files or content to the API. If the content is too long to fit in the context window, notify the user and discuss options (chunking, summarization, etc.) rather than silently truncating.
• Fable 5 / Opus 4.8 / 4.7 thinking: Adaptive only. thinking: {type: "enabled", budget_tokens: N} returns 400 — budget_tokens is fully removed (along with temperature, top_p, top_k). Use thinking: {type: "adaptive"}. Opus 4.8 inherits this surface from 4.7 with no new breaking changes; Fable 5 adds one — an explicit thinking: {type: "disabled"} returns a 400 (accepted on 4.7/4.8); omit the param instead.
• Opus 4.6 / Sonnet 4.6 thinking: Use thinking: {type: "adaptive"} — do NOT use budget_tokens for new 4.6 code (deprecated on both Opus 4.6 and Sonnet 4.6; for gradual migration of existing code, see the transitional escape hatch in shared/model-migration.md — note this carve-out does not apply to Fable 5, Opus 4.7 or 4.8). For older models, budget_tokens must be less than max_tokens (minimum 1024). This will throw an error if you get it wrong.
• Prefill removed (Fable 5 and the 4.6/4.7/4.8 family): Assistant message prefills (last-assistant-turn prefills) return a 400 error on Fable 5, Opus 4.6, Opus 4.7, Opus 4.8, and Sonnet 4.6. Use structured outputs (output_config.format) or system prompt instructions to control response format instead. (One exception: the fallback-credit prefill claim — when redeeming a credit with fallback_has_prefill_claim: true, the server accepts the echoed assistant message; see the migration guide's refusal section.)
• Fable 5 refusal stop reason: Safety classifiers may decline a request — a successful HTTP 200 with stop_reason: "refusal" (pre-output: empty content, nothing billed; mid-stream: partial output billed — discard it). Check stop_reason before reading response.content[0], or you'll hit index errors on refused requests. To retry on another model, replaying history as-is works — other models silently ignore the refused model's thinking blocks — but ignored blocks still bill input tokens, so strip them when switching for good (exception: a fallback-credit redemption must echo the refused body exactly, thinking blocks included).
• Fable 5 tokenizer: ~30% more tokens for the same content vs Opus-tier models. Token counts, context-window budgets, and max_tokens values measured on other models don't transfer — re-measure with count_tokens passing model: "claude-fable-5" (the response includes counts under both tokenizers).
• Confirm migration scope before editing: When a user asks to migrate code to a newer Claude model without naming a specific file, directory, or file list, ask which scope to apply first — the entire working directory, a specific subdirectory, or a specific set of files. Do not start editing until the user confirms. Imperative phrasings like "migrate my codebase", "move my project to X", "upgrade to Sonnet 4.6", or bare "migrate to Opus 4.8" are still ambiguous — they tell you what to do but not where, so ask. Proceed without asking only when the prompt names an exact file, a specific directory, or an explicit file list ("migrate app.py", "migrate everything under services/", "update a.py and b.py"). See shared/model-migration.md Step 0.
• max_tokens defaults: Don't lowball max_tokens — hitting the cap truncates output mid-thought and requires a retry. For non-streaming requests, default to ~16000 (keeps responses under SDK HTTP timeouts). For streaming requests, default to ~64000 (timeouts aren't a concern, so give the model room). Only go lower when you have a hard reason: classification (~256), cost caps, deliberately short outputs, or max_tokens: 0 for cache pre-warming (see shared/prompt-caching.md → Pre-warming).
• 128K output tokens: Fable 5, Opus 4.6, Opus 4.7, and Opus 4.8 support up to 128K max_tokens, but the SDKs require streaming for values that large to avoid HTTP timeouts. Use .stream() with .get_final_message() / .finalMessage().
• Tool call JSON parsing (Fable 5 and the 4.6/4.7/4.8 family): Fable 5, Opus 4.6, Opus 4.7, Opus 4.8, and Sonnet 4.6 may produce different JSON string escaping in tool call input fields (e.g., Unicode or forward-slash escaping). Always parse tool inputs with json.loads() / JSON.parse() — never do raw string matching on the serialized input.
• **Structured outputs (all models)

…(truncated)