From b29e7cf65e5cb78a5ac33d582270551bc74a14eb Mon Sep 17 00:00:00 2001 From: Lance Martin <122662504+rlancemartin@users.noreply.github.com> Date: Fri, 24 Jul 2026 13:12:34 -0700 Subject: [PATCH] Update claude-api skill: Claude Opus 5 (#1476) * Update claude-api skill: Claude Opus 5 - Add Claude Opus 5 (`claude-opus-5`) as the default model across all SDK examples, model tables, pricing, and migration guidance. - Add an Opus 5 migration section covering the API changes that come with it, and move Opus 4.8 into the previous-generation slot. - Drop the Opus 4.7 fast-mode guidance, which no longer applies. - Scope the server-side fallbacks beta header to the current version. * Update claude-api skill: Opus 5 fast-follow corrections - Server-side refusal fallbacks are available on Claude Platform on AWS, not just the Claude API. Correct the availability statements in SKILL.md, the migration guide, and the platform-availability table. - Simplify the effort guidance: start at `high` (the API default) and sweep down, rather than starting at `xhigh` for coding work. - Add a time-to-first-token section with the prompt instruction that reduces pre-answer thinking on latency-sensitive routes. - Replace the two separate thinking-disabled mitigations with the single combined instruction that covers both failure modes. --- skills/claude-api/SKILL.md | 55 ++-- skills/claude-api/csharp/claude-api/README.md | 25 +- .../claude-api/csharp/claude-api/batches.md | 2 +- skills/claude-api/curl/examples.md | 21 +- skills/claude-api/curl/managed-agents.md | 8 +- skills/claude-api/go/claude-api/README.md | 13 +- skills/claude-api/go/managed-agents/README.md | 4 +- skills/claude-api/java/claude-api/README.md | 10 +- skills/claude-api/java/claude-api/tool-use.md | 4 +- .../claude-api/java/managed-agents/README.md | 4 +- skills/claude-api/php/claude-api/README.md | 13 +- skills/claude-api/php/claude-api/batches.md | 2 +- skills/claude-api/php/claude-api/streaming.md | 2 +- skills/claude-api/php/claude-api/tool-use.md | 16 +- .../claude-api/php/managed-agents/README.md | 4 +- skills/claude-api/python/claude-api/README.md | 43 +-- .../claude-api/python/claude-api/batches.md | 6 +- .../claude-api/python/claude-api/files-api.md | 6 +- .../claude-api/python/claude-api/streaming.md | 18 +- .../claude-api/python/claude-api/tool-use.md | 40 +-- .../python/managed-agents/README.md | 6 +- skills/claude-api/ruby/claude-api/README.md | 11 +- .../claude-api/ruby/claude-api/streaming.md | 2 +- skills/claude-api/ruby/claude-api/tool-use.md | 2 +- .../claude-api/ruby/managed-agents/README.md | 4 +- skills/claude-api/shared/anthropic-cli.md | 10 +- .../shared/claude-platform-on-aws.md | 6 +- skills/claude-api/shared/error-codes.md | 13 +- skills/claude-api/shared/live-sources.md | 2 +- .../shared/managed-agents-api-reference.md | 8 +- .../claude-api/shared/managed-agents-core.md | 8 +- .../shared/managed-agents-environments.md | 4 +- .../shared/managed-agents-events.md | 4 +- .../shared/managed-agents-memory.md | 2 +- .../shared/managed-agents-multiagent.md | 2 +- .../shared/managed-agents-onboarding.md | 2 +- .../shared/managed-agents-overview.md | 2 +- .../claude-api/shared/managed-agents-tools.md | 4 +- skills/claude-api/shared/model-migration.md | 289 ++++++++++++++++-- skills/claude-api/shared/models.md | 13 +- .../shared/platform-availability.md | 3 +- skills/claude-api/shared/prompt-caching.md | 26 +- skills/claude-api/shared/token-counting.md | 6 +- skills/claude-api/shared/tool-use-concepts.md | 66 +++- .../typescript/claude-api/README.md | 37 +-- .../typescript/claude-api/batches.md | 4 +- .../typescript/claude-api/files-api.md | 2 +- .../typescript/claude-api/streaming.md | 12 +- .../typescript/claude-api/tool-use.md | 34 +-- .../typescript/managed-agents/README.md | 6 +- 50 files changed, 608 insertions(+), 278 deletions(-) diff --git a/skills/claude-api/SKILL.md b/skills/claude-api/SKILL.md index 9d857fcf..6ddbf0b4 100644 --- a/skills/claude-api/SKILL.md +++ b/skills/claude-api/SKILL.md @@ -32,7 +32,7 @@ Never mix the two — don't reach for `requests`/`fetch` in a Python or TypeScri 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 +For the Claude model version, please use Claude Opus 5, which you can access via the exact model string `claude-opus-5`. 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 ## ⚠️ API Drift — Your Training Prior May Be Stale @@ -40,8 +40,8 @@ Several common Claude API shapes changed in 2025–2026. If you recall a pattern | Area | Stale prior | Current API | |---|---|---| -| Extended thinking | `thinking: {type: "enabled", budget_tokens: N}` | On Claude 4.6+ models: `thinking: {type: "adaptive"}`. `budget_tokens` is deprecated on Opus 4.6 / Sonnet 4.6 and **rejected with a 400** on Fable 5 / Sonnet 5 / Opus 4.8 / 4.7. Pre-4.6 models still use `budget_tokens`. | -| Web search / web fetch tool type | `web_search_20250305`, `web_fetch_20250910` | `web_search_20260209`, `web_fetch_20260209` (dynamic filtering) on Opus 4.8/4.7/4.6, Sonnet 5, and Sonnet 4.6. Older models keep the basic variants; on Vertex AI only basic `web_search_20250305` is available (web fetch is not on Vertex) — see the Server Tools QR below. | +| Extended thinking | `thinking: {type: "enabled", budget_tokens: N}` | On Claude 4.6+ models: `thinking: {type: "adaptive"}`. `budget_tokens` is deprecated on Opus 4.6 / Sonnet 4.6 and **rejected with a 400** on Fable 5 / Sonnet 5 / Opus 5 / 4.8 / 4.7. Pre-4.6 models still use `budget_tokens`. | +| Web search / web fetch tool type | `web_search_20250305`, `web_fetch_20250910` | `web_search_20260209`, `web_fetch_20260209` (dynamic filtering) on Opus 5/4.8/4.7/4.6, Sonnet 5, and Sonnet 4.6. Older models keep the basic variants; on Vertex AI only basic `web_search_20250305` is available (web fetch is not on Vertex) — see the Server Tools QR below. | | PHP parameter names | snake_case wire names as named args (`max_tokens`) | Top-level named args are camelCase (`maxTokens`). Nested array keys vary by feature (e.g. `'taskBudget'`, `'skillID'`, `'mcp_server_name'`) — copy the exact key from the documented example; do not bulk-convert. | | Managed Agents credentials | Keep secrets host-side via custom tools (the only option before vaults shipped) | Vault `environment_variable` credentials — stored by Anthropic, substituted at egress, never visible in the sandbox (`shared/managed-agents-tools.md` → Vaults). Host-side custom tools remain the fallback for self-hosted sandboxes. | @@ -174,7 +174,8 @@ Everything goes through `POST /v1/messages`. Tools and output constraints are fe | ----------------- | ------------------- | -------------- | ---------- | ----------- | | Claude Fable 5 | `claude-fable-5` | 1M | $10.00 | $50.00 | | Claude Mythos 5 (Project Glasswing only) | `claude-mythos-5` | 1M | $10.00 | $50.00 | -| Claude Opus 4.8 | `claude-opus-4-8` | 1M | $5.00 | $25.00 | +| Claude Opus 5 | `claude-opus-5` | 1M | $5.00 | $25.00 | +| Claude Opus 4.8 | `claude-opus-4-8` | 1M | $5.00 | $25.00 | | Claude Opus 4.7 | `claude-opus-4-7` | 1M | $5.00 | $25.00 | | Claude Opus 4.6 | `claude-opus-4-6` | 1M | $5.00 | $25.00 | | Claude Sonnet 5 | `claude-sonnet-5` | 1M | $3.00 ($2.00 intro through 2026-08-31) | $15.00 ($10.00 intro) | @@ -183,7 +184,7 @@ Everything goes through `POST /v1/messages`. Tools and output constraints are fe **Partner pricing:** The prices above are Anthropic first-party API rates — they also apply to Claude on Microsoft Foundry, which is billed through the Microsoft Marketplace at standard API rates. Claude on Amazon Bedrock and Vertex AI is partner-operated with separate pricing — see [Bedrock](https://aws.amazon.com/bedrock/pricing/) or [Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/pricing#claude-models). For WebFetch, use the Pricing row in `shared/live-sources.md`. -**ALWAYS use `claude-opus-4-8` unless the user explicitly names a different model.** This is non-negotiable. Do not use `claude-sonnet-5`, `claude-sonnet-4-6`, 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. **Use only the exact model ID strings from the table — they are complete as-is; never append date suffixes** (`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. +**ALWAYS use `claude-opus-5` unless the user explicitly names a different model.** This is non-negotiable. Do not use `claude-sonnet-5`, `claude-sonnet-4-6`, 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. **Use only the exact model ID strings from the table — they are complete as-is; never append date suffixes** (`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. ### Claude Fable 5 (`claude-fable-5`) — most capable widely released model @@ -192,7 +193,7 @@ Claude Fable 5 is Anthropic's most capable widely released model, for the most d - **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`). - **The raw chain of thought is never returned** — 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. Replay rules: pass thinking blocks back unchanged on the same model; other models drop them silently (unbilled — nothing to strip); details in `shared/model-migration.md`. - **Tokenizer** — same tokenizer as Opus 4.8 (introduced with Opus 4.7). Token counts are roughly unchanged when migrating from Opus 4.7/4.8; per-token pricing differs. Coming from Opus 4.6, Sonnet, Haiku, or older, re-baseline with `count_tokens` (the Opus 4.7 tokenizer uses ~1×–1.35× as many tokens). -- **`refusal` stop reason — handle it, and opt into fallbacks by default** — safety classifiers may decline a request (HTTP 200, `stop_reason: "refusal"`, with a `stop_details` category); always check `stop_reason` before reading `content`. **When you write `claude-fable-5` code, include the server-side `fallbacks` parameter by default** (`betas: ["server-side-fallback-2026-06-01"]` + `fallbacks: [{"model": "claude-opus-4-8"}]`; Claude API and Claude Platform on AWS — elsewhere, incl. Bedrock/Vertex/Foundry, use the SDKs' client-side `BetaRefusalFallbackMiddleware` + `BetaFallbackState`). Tell the user you've enabled it; drop it only if they decline. Full semantics (billing, mid-stream refusals, credit repricing) in `shared/model-migration.md` → refusal section; code examples in `{lang}/claude-api/README.md` § Refusal Fallbacks. +- **`refusal` stop reason — handle it, and opt into fallbacks by default** — safety classifiers may decline a request (HTTP 200, `stop_reason: "refusal"`, with a `stop_details` category); always check `stop_reason` before reading `content`. **When you write `claude-fable-5` or `claude-opus-5` code, include the server-side `fallbacks` parameter by default.** Simplest form: `betas: ["server-side-fallback-2026-07-01"]` + `fallbacks: "default"`, which routes by refusal category so you never maintain a model list. (The older array form — `betas: ["server-side-fallback-2026-06-01"]` + `fallbacks: [{"model": "claude-opus-4-8"}]` — still works; Claude API and Claude Platform on AWS — on Bedrock, Vertex and Foundry, use the SDKs' client-side `BetaRefusalFallbackMiddleware` + `BetaFallbackState` instead). Tell the user you've enabled it; drop it only if they decline. Full semantics (billing, mid-stream refusals, credit repricing) in `shared/model-migration.md` → refusal section. **Per-language code examples in `{lang}/claude-api/README.md` § Refusal Fallbacks cover the array form only** — for the `"default"` mode, follow the raw-HTTP shape in `shared/model-migration.md` → Migrating to Claude Opus 5 → New API features and swap `fallbacks: [{...}]` for `fallbacks: "default"` plus the `-2026-07-01` header; the rest of the request is unchanged. - **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. @@ -225,6 +226,7 @@ Use adaptive thinking (`thinking: {type: "adaptive"}`) on every current model | Model | Thinking config | Omitting `thinking` | `budget_tokens` | Sampling (`temperature`/`top_p`/`top_k`) | Effort levels | |---|---|---|---|---|---| | Fable 5 | `{type: "adaptive"}` or omit; explicit `{type: "disabled"}` returns 400 — omit the param instead | Runs adaptive (thinking is always on) | Removed — `{type: "enabled", budget_tokens: N}` returns 400 | Removed — 400 | `low`/`medium`/`high`/`xhigh`/`max` | +| Claude Opus 5 | `{type: "adaptive"}` or omit; `{type: "disabled"}` accepted **only at effort `high` or below** — 400 at `xhigh`/`max`, and see the disabled-thinking pitfall below | Runs **adaptive** (thinking is on by default — unlike Opus 4.8/4.7) | Removed — 400 | Removed — 400 | `low`–`max` (all five) | | Opus 4.8 / 4.7 | `{type: "adaptive"}` is the only on-mode; `{type: "disabled"}` accepted | Runs **without** thinking — set `{type: "adaptive"}` explicitly | Removed — 400 | Removed — 400 | `low`/`medium`/`high`/`xhigh`/`max` | | Sonnet 5 | `{type: "adaptive"}` is the only on-mode; `{type: "disabled"}` accepted | Runs adaptive | Removed — 400 | Removed — 400 | `low`/`medium`/`high`/`xhigh`/`max` | | Opus 4.6 / Sonnet 4.6 | `{type: "adaptive"}` (recommended; auto-enables interleaved thinking, no beta header) | Set `{type: "adaptive"}` explicitly | Deprecated — do not use in new code; transitional escape hatch only (see below) | Allowed | `low`/`medium`/`high`/`max` (`xhigh` arrived with Opus 4.7) | @@ -233,14 +235,14 @@ Use adaptive thinking (`thinking: {type: "adaptive"}`) on every current model 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. 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). - **Effort (GA, no beta header):** `output_config: {effort: "low"|"medium"|"high"|"xhigh"|"max"}` — inside `output_config`, not top-level; default `high` (equivalent to omitting it). Controls thinking depth and overall token spend; combine with adaptive thinking for the best cost-quality tradeoffs. `xhigh` (added on Opus 4.7, between `high` and `max`) is the best setting for most coding and agentic use cases on Fable 5 / Opus 4.7/4.8 / Sonnet 5, and the default in Claude Code; effort matters more on those models than on any prior model in their tier — re-tune it when migrating, and run long-horizon/agentic tasks at `high`/`xhigh` with the full task spec given up front. Use a minimum of `high` for intelligence-sensitive work, `max` when correctness matters more than cost, and `low` for subagents or simple tasks — 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). -- **Thinking display — `"omitted"` by default on Fable 5 / Mythos 5 / Opus 4.8 / 4.7 / Sonnet 5:** `display: "summarized"` returns a readable summary of the reasoning; `"omitted"` (the default on all five — a silent change from Opus 4.6 and Sonnet 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.) -- **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 fixed thinking-token-budget concept is deprecated and 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 just because the user mentions it. *Gradual-migration carve-out:* `budget_tokens` is still functional on Opus 4.6 and Sonnet 4.6 only, as a transitional escape hatch for existing code that needs a hard token ceiling before you've tuned `effort` — see `shared/model-migration.md` → Transitional escape hatch. It is fully removed on Fable 5, Opus 4.7/4.8, and Sonnet 5. +- **Thinking display — `"omitted"` by default on Fable 5 / Mythos 5 / Opus 5 / 4.8 / 4.7 / Sonnet 5:** `display: "summarized"` returns a readable summary of the reasoning; `"omitted"` (the default on all six — a silent change from Opus 4.6 and Sonnet 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.) +- **When the user asks for "extended thinking", a "thinking budget", or `budget_tokens`:** always use Fable 5, Opus 5, 4.8, 4.7, or 4.6 with `thinking: {type: "adaptive"}` — the fixed thinking-token-budget concept is deprecated and 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 just because the user mentions it. *Gradual-migration carve-out:* `budget_tokens` is still functional on Opus 4.6 and Sonnet 4.6 only, as a transitional escape hatch for existing code that needs a hard token ceiling before you've tuned `effort` — see `shared/model-migration.md` → Transitional escape hatch. It is fully removed on Fable 5, Opus 5/4.7/4.8, and Sonnet 5. --- ## Compaction (Quick Reference) -**Beta, Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 5, 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`. +**Beta, Fable 5, Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 5, 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. @@ -252,7 +254,7 @@ See `{lang}/claude-api/README.md` (Compaction section) for code examples. Full d **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** (Claude Opus 4.8 only; no beta header): 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. +**Mid-conversation operator instructions** (Claude Opus 5, Claude Opus 4.8, Claude Fable 5, Claude Mythos 5; not Claude Sonnet 5; no beta header): 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. @@ -264,11 +266,11 @@ For placement patterns, architectural guidance, and the silent-invalidator audit ## Fast Mode (Quick Reference) -**Research preview, Opus 4.8 / 4.7 only.** Opus 4.7 fast mode is deprecated — after removal, `speed: "fast"` on 4.7 returns an error. Opus 4.8 is the durable fast-capable tier. Fast mode runs the same model at up to 2.5x higher output tokens per second, at premium pricing. Three things are required on every request: use the **beta** messages endpoint (`client.beta.messages.…`), pass the beta flag `fast-mode-2026-02-01`, and set `speed: "fast"` as a top-level request parameter (not a header, not in `extra_body`). +**Research preview, Claude Opus 5 / Opus 4.8 only** — Claude API and Managed Agents, not Bedrock / Google Cloud / Foundry. Opus 4.7 fast mode has been removed: `speed: "fast"` on 4.7 returns an error. Fast mode on Claude Opus 5 is priced at $10 / $50 per MTok. Fast mode runs the same model at up to 2.5x higher output tokens per second, at premium pricing. Three things are required on every request: use the **beta** messages endpoint (`client.beta.messages.…`), pass the beta flag `fast-mode-2026-02-01`, and set `speed: "fast"` as a top-level request parameter (not a header, not in `extra_body`). ```python client.beta.messages.create( - model="claude-opus-4-8", max_tokens=4096, + model="claude-opus-5", max_tokens=4096, speed="fast", betas=["fast-mode-2026-02-01"], messages=[...], ) @@ -286,15 +288,17 @@ client.beta.messages.create( `response.usage.speed` reports which speed was used. Fast mode has its own rate limit separate from standard Opus; on 429, either retry after the `retry-after` delay or drop `speed` and fall back to standard (note: switching speed invalidates prompt cache). Not available with Batch API, Priority Tier, Claude Platform on AWS, or third-party platforms. +**Priority Tier does not cover Claude Opus 5.** It is supported on every other current model, including Claude Fable 5 and Opus 4.8, but Claude Opus 5, Claude Sonnet 5, Claude Mythos 5, and Mythos Preview are excluded — a Priority Tier request naming one of them fails validation. + --- ## Task Budgets (Quick Reference) -**Beta, Fable 5 / Sonnet 5 / Opus 4.8 / 4.7.** A task budget gives Claude a token ceiling for an agentic loop so it paces itself and finishes gracefully instead of being cut off — distinct from `max_tokens`, which is an enforced per-response ceiling the model is not aware of. Minimum `total`: 20,000. Set `task_budget` inside `output_config` on `client.beta.messages.stream(...)` with beta flag `task-budgets-2026-03-13` — use streaming so the large `max_tokens` doesn't hit HTTP timeouts (full details: `shared/model-migration.md` → Task Budgets): +**Beta, Claude Opus 5 / Fable 5 / Sonnet 5 / Opus 4.8 / 4.7.** A task budget gives Claude a token ceiling for an agentic loop so it paces itself and finishes gracefully instead of being cut off — distinct from `max_tokens`, which is an enforced per-response ceiling the model is not aware of. Minimum `total`: 20,000. Set `task_budget` inside `output_config` on `client.beta.messages.stream(...)` with beta flag `task-budgets-2026-03-13` — use streaming so the large `max_tokens` doesn't hit HTTP timeouts (full details: `shared/model-migration.md` → Task Budgets): ```python with client.beta.messages.stream( - model="claude-opus-4-8", max_tokens=128000, + model="claude-opus-5", max_tokens=128000, output_config={"effort": "high", "task_budget": {"type": "tokens", "total": 64000}}, betas=["task-budgets-2026-03-13"], messages=[...], tools=[...], @@ -314,7 +318,7 @@ When targeting Claude on a third-party platform, use that platform's dedicated c ### Amazon Bedrock -Use the **Mantle** client (Messages-API Bedrock endpoint). Bedrock model IDs take an `anthropic.` prefix (e.g. `"anthropic.claude-opus-4-8"`). Region is required. +Use the **Mantle** client (Messages-API Bedrock endpoint). Bedrock model IDs take an `anthropic.` prefix (e.g. `"anthropic.claude-opus-5"`). Region is required. | Language | Client | |---|---| @@ -342,7 +346,7 @@ The Go and Ruby SDKs do not currently support Foundry. For Ruby, use the standar ### Google Cloud Vertex AI -Two required constructor args: GCP `project_id` and `region`. Vertex model IDs take **no prefix** — current-generation models (Opus 4.8/4.7/4.6, Sonnet 5, Sonnet 4.6) use the bare first-party ID (e.g. `"claude-opus-4-8"`); dated-snapshot models use an `@` version separator (e.g. `claude-opus-4-5@20251101`, **not** `claude-opus-4-5-20251101`). Auth is GCP ADC (`gcloud auth application-default login`); no Anthropic API key. `region` can be `"global"` (recommended), a multi-region (`"us"`/`"eu"`), or a specific region. After construction, use the same `messages.create` / `.stream` surface. +Two required constructor args: GCP `project_id` and `region`. Vertex model IDs take **no prefix** — current-generation models (Opus 4.8/4.7/4.6, Sonnet 5, Sonnet 4.6) use the bare first-party ID (e.g. `"claude-opus-5"`); dated-snapshot models use an `@` version separator (e.g. `claude-opus-4-5@20251101`, **not** `claude-opus-4-5-20251101`). Auth is GCP ADC (`gcloud auth application-default login`); no Anthropic API key. `region` can be `"global"` (recommended), a multi-region (`"us"`/`"eu"`), or a specific region. After construction, use the same `messages.create` / `.stream` surface. | Language | Client | |---|---| @@ -362,7 +366,7 @@ Two required constructor args: GCP `project_id` and `region`. Vertex model IDs t ```python client.beta.messages.create( - model="claude-opus-4-8", max_tokens=4096, + model="claude-opus-5", max_tokens=4096, betas=["context-management-2025-06-27"], context_management={"edits": [{"type": "clear_tool_uses_20250919"}]}, tools=[...], messages=[...], @@ -375,7 +379,7 @@ Strategy types: `clear_tool_uses_20250919` (clears old tool results; optional `c ## Mid-Conversation System Messages (Quick Reference) -**Claude Opus 4.8 only; no beta header.** Append `{"role": "system", "content": "…"}` to the `messages` array (not the top-level `system` field) to add an operator instruction mid-conversation without invalidating the cached prefix. Use the regular `client.messages.create` — there is no beta. A mid-conversation system message must follow a `user` message (or an `assistant` message ending in server-tool use), and must be either the last entry in `messages` or be followed by an `assistant` turn — it cannot be `messages[0]`. Availability: `shared/platform-availability.md`. See `shared/prompt-caching.md` § Mid-conversation system messages. +**Claude Opus 5, Claude Opus 4.8, Claude Fable 5, and Claude Mythos 5; not Claude Sonnet 5; no beta header.** Append `{"role": "system", "content": "…"}` to the `messages` array (not the top-level `system` field) to add an operator instruction mid-conversation without invalidating the cached prefix. Use the regular `client.messages.create` — there is no beta. A mid-conversation system message must follow a `user` message (or an `assistant` message ending in server-tool use), and must be either the last entry in `messages` or be followed by an `assistant` turn — it cannot be `messages[0]`. Availability: `shared/platform-availability.md`. See `shared/prompt-caching.md` § Mid-conversation system messages. --- @@ -407,7 +411,7 @@ Availability: `shared/platform-availability.md`. For agents on Bedrock / Vertex ## Server Tools (Quick Reference) -Server-side tools run on Anthropic's infrastructure — no client-side execution loop. Declare in `tools`; results arrive as content blocks in the same response. **No beta header** unless noted. **Prefer the latest type variant your model supports.** The `_20260209` web search / web fetch variants below (dynamic filtering) require Opus 4.8/4.7/4.6, Sonnet 5, or Sonnet 4.6; the basic variants for older models are listed after the table. +Server-side tools run on Anthropic's infrastructure — no client-side execution loop. Declare in `tools`; results arrive as content blocks in the same response. **No beta header** unless noted. **Prefer the latest type variant your model supports.** The `_20260209` web search / web fetch variants below (dynamic filtering) require Opus 5/4.8/4.7/4.6, Sonnet 5, or Sonnet 4.6; the basic variants for older models are listed after the table. | Tool | `type` | `name` | Key optional params | Result block type | |---|---|---|---|---| @@ -441,7 +445,7 @@ Server-side tools run on Anthropic's infrastructure — no client-side execution **Message Batches (no beta; availability: `shared/platform-availability.md`):** `client.messages.batches.create(requests=[{custom_id, params}, ...])` → poll `client.messages.batches.retrieve(id).processing_status` until `"ended"` → stream `client.messages.batches.results(id)`. Each result has `.custom_id` + `.result.type` (`succeeded`/`errored`/`canceled`/`expired`); on success read `.result.message.content`. Python wraps requests as `Request(custom_id=..., params=MessageCreateParamsNonStreaming(...))`. Results arrive in **any order** — key by `custom_id`, never by position. -**Models API (no beta; availability: `shared/platform-availability.md`):** `client.models.list()` (auto-paginates) and `client.models.retrieve("claude-opus-4-8")`. Each model object has `id`, `display_name`, `created_at`, and — since Mar 2026 — `max_input_tokens` (the context window), `max_tokens` (the output cap), and `capabilities`. There is no `context_window` field. +**Models API (no beta; availability: `shared/platform-availability.md`):** `client.models.list()` (auto-paginates) and `client.models.retrieve("claude-opus-5")`. Each model object has `id`, `display_name`, `created_at`, and — since Mar 2026 — `max_input_tokens` (the context window), `max_tokens` (the output cap), and `capabilities`. There is no `context_window` field. **Stop details (GA, Opus 4.7+):** `response.stop_details` is populated **only when `stop_reason == "refusal"`** (fields: `type: "refusal"`, `category: "cyber"|"bio"|null`, `explanation`). It is `null` for every other `stop_reason` (`end_turn`, `max_tokens`, `tool_use`, `pause_turn`, …) — always guard before reading. @@ -471,7 +475,7 @@ The Quick Task Reference below uses the `{lang}/claude-api/FILE.md` path notatio **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 5 / Sonnet 4.6), replacing a retired model, or translating `budget_tokens` / prefill patterns to the current API:** +**Migrating to a newer model (Fable 5 / Opus 5 / Opus 4.8 / Opus 4.7 / Opus 4.6 / Sonnet 5 / Sonnet 4.6), replacing a retired model, or translating `budget_tokens` / prefill patterns to the current API:** → 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 @@ -516,11 +520,12 @@ 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. -- **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.) +- **Prefill removed (Fable 5, Opus 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 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.) - **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, Opus 4.8, Sonnet 5, and Sonnet 4.6 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. +- **Disabling thinking on Claude Opus 5 has two failure modes — prefer low/medium effort instead.** Only affects code that explicitly opts out; thinking is on by default, so watch for a disabled-thinking setting carried forward from Opus 4.8. With `thinking: {type: "disabled"}`, the model occasionally writes a tool call into its **visible text** instead of a `tool_use` block: the turn succeeds, the call never runs, no error is raised, and in an agentic loop that text pollutes later turns. It can also leak `` tags into the response. Turning thinking on and lowering `effort` fixes both and still cuts cost. If a route must stay thinking-off: **delete** any don't-think/don't-reason rule (it makes tag leakage worse), don't name thinking tags, and add the combined instruction *"When you use a tool, you may say a brief sentence first. If no tool can express what the user asked for, say so instead of guessing. Do not include internal or system XML tags in your response."* Details: `shared/model-migration.md` → Two failure modes when thinking is disabled. +- **128K output tokens:** Fable 5, Opus 5, Opus 4.6, Opus 4.7, Opus 4.8, Sonnet 5, and Sonnet 4.6 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, Opus 5, and the 4.6/4.7/4.8 family):** Fable 5, Opus 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):** Use `output_config: {format: {...}}` instead of the deprecated `output_format` parameter on `messages.create()`. This is a general API change, not 4.6-specific. - **Don't reimplement SDK functionality:** The SDK provides high-level helpers — use them instead of building from scratch. Specifically: use `stream.finalMessage()` instead of wrapping `.on()` events in `new Promise()`; use typed exception classes (`Anthropic.RateLimitError`, etc.) instead of string-matching error messages; use SDK types (`Anthropic.MessageParam`, `Anthropic.Tool`, `Anthropic.Message`, etc.) instead of redefining equivalent interfaces. - **Error handling — catch a chain, not one broad class.** A single `except APIStatusError` / `catch (AnthropicServiceException)` / `rescue APIError` loses the distinction between retryable (429, ≥500, network) and non-retryable (400/404) failures. Write a most-specific-first chain — e.g. `NotFoundError` → `RateLimitError` → `APIStatusError` → `APIConnectionError` (or the Go equivalent: `errors.As` into `*anthropic.Error` then `switch apierr.StatusCode { case 404: …; case 429: …; default: … }`). Per-language class names and namespaces are in `shared/error-codes.md`. @@ -533,7 +538,7 @@ Live documentation URLs are in `shared/live-sources.md`. - **Fine-grained tool streaming is not a beta feature.** Set `eager_input_streaming: true` on the tool definition and call the regular `client.messages.stream(...)`. There is no beta header and no `client.beta.*` path. - **Cache diagnostics is beta.** Use `client.beta.messages.*` with beta `cache-diagnosis-2026-04-07`. Pass `diagnostics: {previous_message_id: null}` on the first turn and `diagnostics: {previous_message_id: }` on subsequent turns; the result is on `response.diagnostics`. Availability: `shared/platform-availability.md`. - **Memory tool type is `memory_20250818`.** Declare `{"type": "memory_20250818", "name": "memory"}`. Go uses the beta-namespace type `{OfMemoryTool20250818: &anthropic.BetaMemoryTool20250818Param{}}` on `client.Beta.Messages.New`; Python/TypeScript/Ruby/PHP/C# use the non-beta `client.messages.create`; Java has both a non-beta `MemoryTool20250818` and a beta tool-runner path. Python/TypeScript provide `BetaAbstractMemoryTool` / `betaMemoryTool` helpers for implementing the backend. -- **Use a model the feature actually supports.** Some features are restricted to specific model tiers — fast mode is Opus 4.8 / 4.7 only, task budgets are Fable 5 / Sonnet 5 / Opus 4.8 / 4.7 only, and the advisor tool requires a valid executor↔advisor pair. If the user's prompt names a model that the feature doesn't support, use a supported model instead and note the substitution in the output. +- **Use a model the feature actually supports.** Some features are restricted to specific model tiers — fast mode is Claude Opus 5 / Opus 4.8 only (and Claude API only), task budgets are Claude Opus 5 / Fable 5 / Sonnet 5 / Opus 4.8 / 4.7 only, and the advisor tool requires a valid executor↔advisor pair. If the user's prompt names a model that the feature doesn't support, use a supported model instead and note the substitution in the output. - **Don't define custom types for SDK data structures:** The SDK exports types for all API objects. Use `Anthropic.MessageParam` for messages, `Anthropic.Tool` for tool definitions, `Anthropic.ToolUseBlock` / `Anthropic.ToolResultBlockParam` for tool results, `Anthropic.Message` for responses. Defining your own `interface ChatMessage { role: string; content: unknown }` duplicates what the SDK already provides and loses type safety. - **Report and document output:** For tasks that produce reports, documents, or visualizations, the code execution sandbox has `python-docx`, `python-pptx`, `matplotlib`, `pillow`, and `pypdf` pre-installed. Claude can generate formatted files (DOCX, PDF, charts) and return them via the Files API — consider this for "report" or "document" type requests instead of plain stdout text. - **Server-tool errors don't raise.** Web search and web fetch errors return HTTP 200 with a `web_search_tool_result` / `web_fetch_tool_result` block whose `content` is a single error object (e.g. `{error_code: "max_uses_exceeded"}`) — not a raised exception. For web search, a success `content` is a *list*; an error `content` is an *object* — branch on that before indexing. diff --git a/skills/claude-api/csharp/claude-api/README.md b/skills/claude-api/csharp/claude-api/README.md index 5c40f001..9891518c 100644 --- a/skills/claude-api/csharp/claude-api/README.md +++ b/skills/claude-api/csharp/claude-api/README.md @@ -35,7 +35,7 @@ Write from this table instead of reflecting the SDK assembly. Endpoint column te | Programmatic tool calling | non-beta | `CodeExecutionTool20260120`, `ToolResultBlockParam`, `ContentBlockParam` | | Task budgets | beta | `BetaOutputConfig` with `TaskBudget = new BetaTokenTaskBudget { ... }` | | Tool search | non-beta | `new ToolUnion(new ToolSearchToolRegex20251119 { Type = ToolSearchToolRegex20251119Type.ToolSearchToolRegex20251119 })` — `Type` must be set explicitly. | -| Web search | non-beta | `new ToolUnion(new WebSearchTool20260209())` — the latest variant with dynamic filtering (Opus 4.8/4.7/4.6 + Sonnet 4.6). For older models or Vertex, use `WebSearchTool20250305()` | +| Web search | non-beta | `new ToolUnion(new WebSearchTool20260209())` — the latest variant with dynamic filtering (Claude Fable 5 + Claude Opus 5 + Opus 4.8/4.7/4.6 + Claude Sonnet 5 + Sonnet 4.6). For older models or Vertex, use `WebSearchTool20250305()` | ### Discovering type and member names @@ -58,7 +58,7 @@ AnthropicClient client = new(); var message = await client.Messages.Create(new MessageCreateParams { - Model = Model.ClaudeOpus4_8, + Model = "claude-opus-5", MaxTokens = 1024, Messages = [ new() { Role = Role.User, Content = "Hello, Claude" } ], }); @@ -77,7 +77,7 @@ AnthropicClient client = new(); var response = await client.Beta.Messages.Create(new MessageCreateParams { - Model = "claude-opus-4-8", + Model = "claude-opus-5", MaxTokens = 4096, Betas = [""], Messages = [ new() { Role = Role.User, Content = "…" } ], @@ -123,7 +123,7 @@ using Anthropic.Models.Messages; var parameters = new MessageCreateParams { - Model = Model.ClaudeOpus4_8, + Model = "claude-opus-5", MaxTokens = 16000, Messages = [new() { Role = Role.User, Content = "What is the capital of France?" }] }; @@ -144,7 +144,8 @@ foreach (var text in response.Content.Select(b => b.Value).OfType()) **Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think. -> **Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking (below). `new ThinkingConfigEnabled { BudgetTokens = N }` is removed on Fable 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6. +> **Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking (below). `new ThinkingConfigEnabled { BudgetTokens = N }` is removed on Fable 5, Claude Opus 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6. +> **Claude Opus 5:** thinking is on by default — omitting `Thinking` runs adaptive (`ThinkingConfigAdaptive` is equivalent), unlike Opus 4.8/4.7 where omitting it meant no thinking. `ThinkingConfigDisabled` is accepted only at effort `high` or lower; pairing it with `xhigh`/`max` returns a 400. > **Older models:** Use `new ThinkingConfigEnabled { BudgetTokens = N }` (budget must be < `MaxTokens`, min 1024). ```csharp @@ -152,11 +153,11 @@ using Anthropic.Models.Messages; var response = await client.Messages.Create(new MessageCreateParams { - Model = Model.ClaudeOpus4_8, + Model = "claude-opus-5", MaxTokens = 16000, // ThinkingConfigParam? implicitly converts from the concrete variant classes — // no wrapper needed. - // display opt-in: default is omitted (empty thinking text) on Fable 5 / Mythos 5 / Opus 4.8 / 4.7 + // display opt-in: default is omitted (empty thinking text) on Fable 5 / Mythos 5 / Claude Opus 5 / Opus 4.8 / 4.7 Thinking = new ThinkingConfigAdaptive { Display = Display.Summarized }, Messages = [ @@ -200,7 +201,7 @@ using Anthropic.Models.Beta.Messages; var betaParams = new MessageCreateParams // no Beta prefix — see unprefixed list above { - Model = Model.ClaudeOpus4_8, + Model = "claude-opus-5", MaxTokens = 16000, Betas = ["compact-2026-01-12"], ContextManagement = new BetaContextManagementConfig @@ -289,7 +290,7 @@ Verify hits via `response.Usage.CacheCreationInputTokens` / `response.Usage.Cach ```csharp MessageTokensCount result = await client.Messages.CountTokens(new MessageCountTokensParams { - Model = Model.ClaudeOpus4_8, + Model = "claude-opus-5", Messages = [new() { Role = Role.User, Content = "Hello" }], }); long tokens = result.InputTokens; @@ -319,7 +320,7 @@ new MessageParam { ```csharp var response = await client.Beta.Messages.Create(new MessageCreateParams { - Model = "claude-opus-4-8", MaxTokens = 4096, + Model = "claude-opus-5", MaxTokens = 4096, Speed = Speed.Fast, Betas = ["fast-mode-2026-02-01"], Messages = [...], @@ -331,14 +332,14 @@ var response = await client.Beta.Messages.Create(new MessageCreateParams { ```csharp var page = await client.Models.List(); foreach (var m in page.Items) { Console.WriteLine(m.ID); } -var one = await client.Models.Retrieve("claude-opus-4-8"); +var one = await client.Models.Retrieve("claude-opus-5"); ``` ## Long Output (128k) + Prefill Set `MaxTokens = 128000` on `client.Messages` and use the streaming path (see `streaming.md`). On Claude 4+ models, 128k output is native — no `output-128k-*` beta header or beta namespace is needed. -**Prefilling the assistant message** (putting a trailing `Role.Assistant` message in the input) is **not supported** on Claude Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6 — requests return a 400. Use `OutputConfig.Format` (structured outputs) instead. +**Prefilling the assistant message** (putting a trailing `Role.Assistant` message in the input) is **not supported** on Claude Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6 — requests return a 400. Use `OutputConfig.Format` (structured outputs) instead. ## Stop Details diff --git a/skills/claude-api/csharp/claude-api/batches.md b/skills/claude-api/csharp/claude-api/batches.md index e025a49d..c066bef6 100644 --- a/skills/claude-api/csharp/claude-api/batches.md +++ b/skills/claude-api/csharp/claude-api/batches.md @@ -5,7 +5,7 @@ ```csharp var batch = await client.Messages.Batches.Create(new() { Requests = [ - new() { CustomID = "req-1", Params = new() { Model = "claude-opus-4-8", MaxTokens = 1024, Messages = [...] } }, + new() { CustomID = "req-1", Params = new() { Model = "claude-opus-5", MaxTokens = 1024, Messages = [...] } }, ], }); // Poll client.Messages.Batches.Retrieve(batch.ID) until ProcessingStatus == "ended", diff --git a/skills/claude-api/curl/examples.md b/skills/claude-api/curl/examples.md index 4625a7fa..ba93ea21 100644 --- a/skills/claude-api/curl/examples.md +++ b/skills/claude-api/curl/examples.md @@ -18,7 +18,7 @@ curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -d '{ - "model": "claude-opus-4-8", + "model": "claude-opus-5", "max_tokens": 16000, "messages": [ {"role": "user", "content": "What is the capital of France?"} @@ -38,7 +38,7 @@ response=$(curl -s https://api.anthropic.com/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ - -d '{"model":"claude-opus-4-8","max_tokens":16000,"messages":[{"role":"user","content":"Hello"}]}') + -d '{"model":"claude-opus-5","max_tokens":16000,"messages":[{"role":"user","content":"Hello"}]}') # Print the first text block (-r strips the JSON quotes) echo "$response" | jq -r '.content[0].text' @@ -65,7 +65,7 @@ curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -d '{ - "model": "claude-opus-4-8", + "model": "claude-opus-5", "max_tokens": 64000, "stream": true, "messages": [{"role": "user", "content": "Write a haiku"}] @@ -104,7 +104,7 @@ curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -d '{ - "model": "claude-opus-4-8", + "model": "claude-opus-5", "max_tokens": 16000, "tools": [{ "name": "get_weather", @@ -129,7 +129,7 @@ curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -d '{ - "model": "claude-opus-4-8", + "model": "claude-opus-5", "max_tokens": 16000, "tools": [{ "name": "get_weather", @@ -167,7 +167,7 @@ curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -d '{ - "model": "claude-opus-4-8", + "model": "claude-opus-5", "max_tokens": 16000, "system": [ {"type": "text", "text": "", "cache_control": {"type": "ephemeral"}} @@ -182,17 +182,18 @@ For 1-hour TTL: `"cache_control": {"type": "ephemeral", "ttl": "1h"}`. Top-level ## Extended Thinking -> **Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is removed on Fable 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6. +> **Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is removed on Fable 5, Claude Opus 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6. +> **Claude Opus 5:** thinking is on by default — omitting `"thinking"` runs adaptive (`{"type": "adaptive"}` is equivalent), unlike Opus 4.8/4.7 where omitting it meant no thinking. `{"type": "disabled"}` is accepted only at effort `high` or lower; pairing it with `xhigh`/`max` returns a 400. > **Older models:** Use `"type": "enabled"` with `"budget_tokens": N` (must be < `max_tokens`, min 1024). ```bash -# Fable 5 / Opus 4.8 / 4.7 / 4.6: adaptive thinking (recommended) +# Fable 5 / Claude Opus 5 / Opus 4.8 / 4.7 / 4.6: adaptive thinking (recommended) curl https://api.anthropic.com/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -d '{ - "model": "claude-opus-4-8", + "model": "claude-opus-5", "max_tokens": 16000, "thinking": { "type": "adaptive", @@ -241,7 +242,7 @@ if [ "$(echo "$response" | jq -r '.stop_reason')" != "refusal" ] && \ fi ``` -The header must be exactly `server-side-fallback-2026-06-01`. The parameter is rejected on the Batches API and unavailable on Amazon Bedrock, Vertex AI, and Microsoft Foundry. Full semantics (sticky routing, billing, streaming, echoing fallback turns back): `shared/model-migration.md` → Migrating to Claude Fable 5 → `refusal` stop reason. +The header must be exactly `server-side-fallback-2026-06-01` **for this array form**; the newer `fallbacks: "default"` scalar form uses `server-side-fallback-2026-07-01` instead (see `shared/model-migration.md` → Migrating to Claude Opus 5 → New API features), and pairing either header with the other form returns a 400. The parameter is rejected on the Batches API and unavailable on Amazon Bedrock, Vertex AI, and Microsoft Foundry. Full semantics (sticky routing, billing, streaming, echoing fallback turns back): `shared/model-migration.md` → Migrating to Claude Fable 5 → `refusal` stop reason. --- diff --git a/skills/claude-api/curl/managed-agents.md b/skills/claude-api/curl/managed-agents.md index 62de232c..72ee208d 100644 --- a/skills/claude-api/curl/managed-agents.md +++ b/skills/claude-api/curl/managed-agents.md @@ -65,7 +65,7 @@ curl -X POST https://api.anthropic.com/v1/agents \ "${HEADERS[@]}" \ -d '{ "name": "Coding Assistant", - "model": "claude-opus-4-8", + "model": "claude-opus-5", "tools": [{ "type": "agent_toolset_20260401" }] }' # → { "id": "agent_abc123", ... } @@ -89,7 +89,7 @@ curl -X POST https://api.anthropic.com/v1/agents \ "${HEADERS[@]}" \ -d '{ "name": "Code Reviewer", - "model": "claude-opus-4-8", + "model": "claude-opus-5", "system": "You are a senior code reviewer. Be thorough and constructive.", "tools": [ { "type": "agent_toolset_20260401" }, @@ -295,7 +295,7 @@ curl -X POST https://api.anthropic.com/v1/agents \ "${HEADERS[@]}" \ -d '{ "name": "MCP Agent", - "model": "claude-opus-4-8", + "model": "claude-opus-5", "mcp_servers": [ { "type": "url", "name": "my-tools", "url": "https://my-mcp-server.example.com/sse" } ], @@ -326,7 +326,7 @@ curl -X POST https://api.anthropic.com/v1/agents \ "${HEADERS[@]}" \ -d '{ "name": "Restricted Agent", - "model": "claude-opus-4-8", + "model": "claude-opus-5", "tools": [ { "type": "agent_toolset_20260401", diff --git a/skills/claude-api/go/claude-api/README.md b/skills/claude-api/go/claude-api/README.md index 5635e7e5..958582c3 100644 --- a/skills/claude-api/go/claude-api/README.md +++ b/skills/claude-api/go/claude-api/README.md @@ -29,7 +29,9 @@ client := anthropic.NewClient( ## Model Constants -The Go SDK provides typed model constants: `anthropic.ModelClaudeFable5`, `anthropic.ModelClaudeOpus4_8`, `anthropic.ModelClaudeOpus4_7`, `anthropic.ModelClaudeSonnet4_6`, `anthropic.ModelClaudeHaiku4_5_20251001`. Use `ModelClaudeOpus4_8` unless the user specifies otherwise; if they ask for Fable or the most powerful model, use `anthropic.ModelClaudeFable5` (see `shared/models.md` for the full resolution table). +The Go SDK provides typed model constants: `anthropic.ModelClaudeFable5`, `anthropic.ModelClaudeOpus4_8`, `anthropic.ModelClaudeOpus4_7`, `anthropic.ModelClaudeSonnet4_6`, `anthropic.ModelClaudeHaiku4_5_20251001`. Default to Claude Opus 5 unless the user specifies otherwise; if they ask for Fable or the most powerful model, use `anthropic.ModelClaudeFable5` (see `shared/models.md` for the full resolution table). + +`anthropic.Model` is an alias for `string`, so a model with no typed constant yet — including Claude Opus 5 — is passed as the plain id: `Model: "claude-opus-5"`. Check the SDK release notes for a typed `Claude Opus 5` constant before assuming one exists. --- @@ -37,7 +39,7 @@ The Go SDK provides typed model constants: `anthropic.ModelClaudeFable5`, `anthr ```go response, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{ - Model: anthropic.ModelClaudeOpus4_8, + Model: "claude-opus-5", MaxTokens: 16000, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("What is the capital of France?")), @@ -93,10 +95,11 @@ for _, block := range resp.Content { } ``` -> **Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking (above). `ThinkingConfigParamOfEnabled(budgetTokens)` is removed on Fable 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6. +> **Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking (above). `ThinkingConfigParamOfEnabled(budgetTokens)` is removed on Fable 5, Claude Opus 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6. +> **Claude Opus 5:** thinking is on by default — leaving `Thinking` unset runs adaptive (the adaptive union is equivalent), unlike Opus 4.8/4.7 where leaving it unset meant no thinking. > **Older models:** Use `anthropic.ThinkingConfigParamOfEnabled(N)` (budget must be < `MaxTokens`, min 1024). -To disable: `anthropic.ThinkingConfigParamUnion{OfDisabled: &anthropic.ThinkingConfigDisabledParam{}}`. +To disable: `anthropic.ThinkingConfigParamUnion{OfDisabled: &anthropic.ThinkingConfigDisabledParam{}}`. On Claude Opus 5 that is accepted only at effort `high` or lower — pairing it with `xhigh`/`max` returns a 400. --- @@ -155,7 +158,7 @@ Use `Beta.Messages.New` with `ContextManagement` on `BetaMessageNewParams`. Ther ```go params := anthropic.BetaMessageNewParams{ - Model: anthropic.ModelClaudeOpus4_8, // also supported: ModelClaudeSonnet4_6 + Model: "claude-opus-5", // also supported: ModelClaudeOpus4_8, ModelClaudeSonnet4_6 MaxTokens: 16000, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, ContextManagement: anthropic.BetaContextManagementConfigParam{ diff --git a/skills/claude-api/go/managed-agents/README.md b/skills/claude-api/go/managed-agents/README.md index 92abd2a4..d5cdc5e3 100644 --- a/skills/claude-api/go/managed-agents/README.md +++ b/skills/claude-api/go/managed-agents/README.md @@ -65,7 +65,7 @@ fmt.Println(environment.ID) // env_... agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ Name: "Coding Assistant", Model: anthropic.BetaManagedAgentsModelConfigParams{ - ID: "claude-opus-4-8", + ID: "claude-opus-5", Type: anthropic.BetaManagedAgentsModelConfigParamsTypeModelConfig, }, System: anthropic.String("You are a helpful coding assistant."), @@ -383,7 +383,7 @@ if err != nil { agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ Name: "GitHub Assistant", Model: anthropic.BetaManagedAgentsModelConfigParams{ - ID: "claude-opus-4-8", + ID: "claude-opus-5", Type: anthropic.BetaManagedAgentsModelConfigParamsTypeModelConfig, }, MCPServers: []anthropic.BetaManagedAgentsURLMCPServerParams{{ diff --git a/skills/claude-api/java/claude-api/README.md b/skills/claude-api/java/claude-api/README.md index baf2eed8..57aeb67c 100644 --- a/skills/claude-api/java/claude-api/README.md +++ b/skills/claude-api/java/claude-api/README.md @@ -33,7 +33,7 @@ Write from this table instead of `javap`/jar inspection. Endpoint column tells y | Strict tool use | non-beta | `Tool`, `Tool.InputSchema` | | Task budgets | beta | `.outputConfig(BetaOutputConfig.builder().taskBudget(BetaTokenTaskBudget.builder()...))` | | Tool search | non-beta | `.addTool(ToolSearchToolRegex20251119.builder()...)` from `com.anthropic.models.messages` | -| Web search | non-beta | `WebSearchTool20260209` from `com.anthropic.models.messages` — the latest variant with dynamic filtering (Opus 4.8/4.7/4.6 + Sonnet 4.6). For older models or Vertex, use `WebSearchTool20250305` | +| Web search | non-beta | `WebSearchTool20260209` from `com.anthropic.models.messages` — the latest variant with dynamic filtering (Claude Fable 5 + Claude Opus 5 + Opus 4.8/4.7/4.6 + Claude Sonnet 5 + Sonnet 4.6). For older models or Vertex, use `WebSearchTool20250305` | ### Discovering type and member names @@ -79,10 +79,9 @@ AnthropicClient client = AnthropicOkHttpClient.builder() ```java import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Message; -import com.anthropic.models.messages.Model; MessageCreateParams params = MessageCreateParams.builder() - .model(Model.CLAUDE_OPUS_4_8) + .model("claude-opus-5") // .model(String) overload — use it for ids with no typed Model constant yet .maxTokens(16000L) .addUserMessage("What is the capital of France?") .build(); @@ -99,7 +98,8 @@ response.content().stream() **Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think. The builder has a direct `.thinking(ThinkingConfigAdaptive)` overload — no manual union wrapping. -> **Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking (below). `ThinkingConfigEnabled.builder().budgetTokens(N)` is removed on Fable 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6. +> **Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking (below). `ThinkingConfigEnabled.builder().budgetTokens(N)` is removed on Fable 5, Claude Opus 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6. +> **Claude Opus 5:** thinking is on by default — omitting `.thinking(...)` runs adaptive (`ThinkingConfigAdaptive` is equivalent), unlike Opus 4.8/4.7 where omitting it meant no thinking. `ThinkingConfigDisabled` is accepted only at effort `HIGH` or lower; pairing it with `XHIGH`/`MAX` returns a 400. > **Older models:** Use `.thinking(ThinkingConfigEnabled.builder().budgetTokens(N).build())` (budget must be < `maxTokens`, min 1024). ```java @@ -133,7 +133,7 @@ Effort is nested inside `OutputConfig` — there is NO `.effort()` directly on ` import com.anthropic.models.messages.OutputConfig; .outputConfig(OutputConfig.builder() - .effort(OutputConfig.Effort.HIGH) // or LOW, MEDIUM, MAX + .effort(OutputConfig.Effort.HIGH) // or LOW, MEDIUM, XHIGH, MAX .build()) ``` diff --git a/skills/claude-api/java/claude-api/tool-use.md b/skills/claude-api/java/claude-api/tool-use.md index 2ab71c76..caf45b58 100644 --- a/skills/claude-api/java/claude-api/tool-use.md +++ b/skills/claude-api/java/claude-api/tool-use.md @@ -29,7 +29,7 @@ static class GetWeather implements Supplier { BetaToolRunner toolRunner = client.beta().messages().toolRunner( MessageCreateParams.builder() - .model("claude-opus-4-8") + .model("claude-opus-5") .maxTokens(16000L) .putAdditionalHeader("anthropic-beta", "structured-outputs-2025-11-13") .addTool(GetWeather.class) @@ -57,7 +57,7 @@ import com.anthropic.models.beta.messages.ToolRunnerCreateParams; BetaMemoryToolHandler memoryHandler = new FileSystemMemoryToolHandler(sandboxRoot); MessageCreateParams createParams = MessageCreateParams.builder() - .model("claude-opus-4-8") + .model("claude-opus-5") .maxTokens(4096L) .addTool(BetaMemoryTool20250818.builder().build()) .addUserMessage("Remember that my favorite color is blue") diff --git a/skills/claude-api/java/managed-agents/README.md b/skills/claude-api/java/managed-agents/README.md index 0bf2b6f8..56814c8c 100644 --- a/skills/claude-api/java/managed-agents/README.md +++ b/skills/claude-api/java/managed-agents/README.md @@ -57,7 +57,7 @@ import com.anthropic.models.beta.sessions.SessionCreateParams; // 1. Create the agent (reusable, versioned) var agent = client.beta().agents().create(AgentCreateParams.builder() .name("Coding Assistant") - .model("claude-opus-4-8") + .model("claude-opus-5") .system("You are a helpful coding assistant.") .addTool(BetaManagedAgentsAgentToolset20260401Params.builder() .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401) @@ -296,7 +296,7 @@ import com.anthropic.models.beta.agents.BetaManagedAgentsUrlMcpServerParams; // Agent declares MCP server (no auth here — auth goes in a vault) var agent = client.beta().agents().create(AgentCreateParams.builder() .name("GitHub Assistant") - .model("claude-opus-4-8") + .model("claude-opus-5") .addMcpServer(BetaManagedAgentsUrlMcpServerParams.builder() .type(BetaManagedAgentsUrlMcpServerParams.Type.URL) .name("github") diff --git a/skills/claude-api/php/claude-api/README.md b/skills/claude-api/php/claude-api/README.md index 7b17651a..41b3714b 100644 --- a/skills/claude-api/php/claude-api/README.md +++ b/skills/claude-api/php/claude-api/README.md @@ -26,7 +26,7 @@ use Anthropic\Bedrock\MantleClient; $client = new MantleClient(awsRegion: 'us-east-1'); ``` -Model IDs on Bedrock take an `anthropic.` prefix — e.g. `model: 'anthropic.claude-opus-4-8'`. +Model IDs on Bedrock take an `anthropic.` prefix — e.g. `model: 'anthropic.claude-opus-5'`. ### Google Vertex AI @@ -58,7 +58,7 @@ $client = Foundry\Client::withCredentials( ```php $message = $client->messages->create( - model: 'claude-opus-4-8', + model: 'claude-opus-5', maxTokens: 16000, messages: [ ['role' => 'user', 'content' => 'What is the capital of France?'], @@ -97,9 +97,9 @@ foreach ($message->content as $block) { use Anthropic\Messages\ThinkingBlock; $message = $client->messages->create( - model: 'claude-opus-4-8', + model: 'claude-opus-5', maxTokens: 16000, - thinking: ['type' => 'adaptive', 'display' => 'summarized'], // display opt-in: default is omitted (empty thinking text) on Fable 5 / Mythos 5 / Opus 4.8 / 4.7 + thinking: ['type' => 'adaptive', 'display' => 'summarized'], // display opt-in: default is omitted (empty thinking text) on Fable 5 / Mythos 5 / Claude Opus 5 / Opus 4.8 / 4.7 messages: [ ['role' => 'user', 'content' => 'Solve: 27 * 453'], ], @@ -117,7 +117,8 @@ foreach ($message->content as $block) { } ``` -> **Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking (above). `['type' => 'enabled', 'budgetTokens' => N]` is removed on Fable 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6. +> **Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking (above). `['type' => 'enabled', 'budgetTokens' => N]` is removed on Fable 5, Claude Opus 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6. +> **Claude Opus 5:** thinking is on by default — omitting `thinking:` runs adaptive (`['type' => 'adaptive']` is equivalent), unlike Opus 4.8/4.7 where omitting it meant no thinking. `['type' => 'disabled']` is accepted only at effort `high` or lower; pairing it with `xhigh`/`max` returns a 400. > **Older models:** Use `thinking: ['type' => 'enabled', 'budgetTokens' => N]` (budget must be < `maxTokens`, min 1024). `$block->type === 'thinking'` also works for the check; `instanceof` narrows for PHPStan. @@ -130,7 +131,7 @@ foreach ($message->content as $block) { ```php $message = $client->messages->create( - model: 'claude-opus-4-8', + model: 'claude-opus-5', maxTokens: 16000, system: [ ['type' => 'text', 'text' => $longSystemPrompt, 'cacheControl' => ['type' => 'ephemeral']], diff --git a/skills/claude-api/php/claude-api/batches.md b/skills/claude-api/php/claude-api/batches.md index 7dc2067b..7c0db9c0 100644 --- a/skills/claude-api/php/claude-api/batches.md +++ b/skills/claude-api/php/claude-api/batches.md @@ -4,7 +4,7 @@ ```php $batch = $client->messages->batches->create(requests: [ - ['customId' => 'req-1', 'params' => ['model' => 'claude-opus-4-8', 'maxTokens' => 1024, 'messages' => [...]]], + ['customId' => 'req-1', 'params' => ['model' => 'claude-opus-5', 'maxTokens' => 1024, 'messages' => [...]]], ['customId' => 'req-2', 'params' => [...]], ]); // Poll $client->messages->batches->retrieve($batch->id) until processingStatus === 'ended', diff --git a/skills/claude-api/php/claude-api/streaming.md b/skills/claude-api/php/claude-api/streaming.md index 17fd9c39..0a90596b 100644 --- a/skills/claude-api/php/claude-api/streaming.md +++ b/skills/claude-api/php/claude-api/streaming.md @@ -9,7 +9,7 @@ use Anthropic\Messages\RawContentBlockDeltaEvent; use Anthropic\Messages\TextDelta; $stream = $client->messages->createStream( - model: 'claude-opus-4-8', + model: 'claude-opus-5', maxTokens: 64000, messages: [ ['role' => 'user', 'content' => 'Write a haiku'], diff --git a/skills/claude-api/php/claude-api/tool-use.md b/skills/claude-api/php/claude-api/tool-use.md index aa313d7f..ffd66ca5 100644 --- a/skills/claude-api/php/claude-api/tool-use.md +++ b/skills/claude-api/php/claude-api/tool-use.md @@ -31,7 +31,7 @@ $weatherTool = new BetaRunnableTool( $runner = $client->beta->messages->toolRunner( maxTokens: 16000, messages: [['role' => 'user', 'content' => 'What is the weather in Paris?']], - model: 'claude-opus-4-8', + model: 'claude-opus-5', tools: [$weatherTool], ); @@ -68,7 +68,7 @@ $tools = [ $messages = [['role' => 'user', 'content' => 'What is the weather in SF?']]; $response = $client->messages->create( - model: 'claude-opus-4-8', + model: 'claude-opus-5', maxTokens: 16000, tools: $tools, messages: $messages, @@ -95,7 +95,7 @@ while ($response->stopReason === 'tool_use') { // camelCase property $messages[] = ['role' => 'user', 'content' => $toolResults]; $response = $client->messages->create( - model: 'claude-opus-4-8', + model: 'claude-opus-5', maxTokens: 16000, tools: $tools, messages: $messages, @@ -139,7 +139,7 @@ class Person implements StructuredOutputModel } $message = $client->messages->create( - model: 'claude-opus-4-8', + model: 'claude-opus-5', maxTokens: 16000, messages: [['role' => 'user', 'content' => 'Generate a profile for Alice, age 30']], outputConfig: ['format' => Person::class], @@ -155,7 +155,7 @@ Types are inferred from PHP type hints. Use `#[Constrained(description: '...')]` ```php $message = $client->messages->create( - model: 'claude-opus-4-8', + model: 'claude-opus-5', maxTokens: 16000, messages: [['role' => 'user', 'content' => 'Extract: John (john@co.com), Enterprise plan']], outputConfig: [ @@ -194,7 +194,7 @@ foreach ($message->content as $block) { use Anthropic\Beta\Messages\BetaRequestMCPServerURLDefinition; $response = $client->beta->messages->create( - model: 'claude-opus-4-8', + model: 'claude-opus-5', maxTokens: 16000, mcpServers: [ BetaRequestMCPServerURLDefinition::with( @@ -211,7 +211,7 @@ $response = $client->beta->messages->create( ```php $response = $client->beta->messages->create( - model: 'claude-opus-4-8', + model: 'claude-opus-5', maxTokens: 16000, outputConfig: ['taskBudget' => ['type' => 'tokens', 'total' => 64000]], tools: [...], @@ -226,7 +226,7 @@ Pass the previous response's `id` on the next request; print the `diagnostics` o ```php $r2 = $client->beta->messages->create( - model: 'claude-opus-4-8', maxTokens: 1024, + model: 'claude-opus-5', maxTokens: 1024, diagnostics: ['previousMessageId' => $r1->id], betas: ['cache-diagnosis-2026-04-07'], messages: [...], diff --git a/skills/claude-api/php/managed-agents/README.md b/skills/claude-api/php/managed-agents/README.md index 5913fbf5..fc63d988 100644 --- a/skills/claude-api/php/managed-agents/README.md +++ b/skills/claude-api/php/managed-agents/README.md @@ -48,7 +48,7 @@ use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params; // 1. Create the agent (reusable, versioned) $agent = $client->beta->agents->create( name: 'Coding Assistant', - model: 'claude-opus-4-8', + model: 'claude-opus-5', system: 'You are a helpful coding assistant.', tools: [ BetaManagedAgentsAgentToolset20260401Params::with( @@ -307,7 +307,7 @@ use Anthropic\Beta\Sessions\BetaManagedAgentsAgentParams; // Agent declares MCP server (no auth here — auth goes in a vault) $agent = $client->beta->agents->create( name: 'GitHub Assistant', - model: 'claude-opus-4-8', + model: 'claude-opus-5', mcpServers: [ BetaManagedAgentsURLMCPServerParams::with( type: 'url', diff --git a/skills/claude-api/python/claude-api/README.md b/skills/claude-api/python/claude-api/README.md index c65c10ae..06e8fba7 100644 --- a/skills/claude-api/python/claude-api/README.md +++ b/skills/claude-api/python/claude-api/README.md @@ -33,7 +33,7 @@ Use `with_options()` to override client settings for a single call without mutat ```python client.with_options(timeout=5.0, max_retries=5).messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=1024, messages=[{"role": "user", "content": "Hello"}], ) @@ -90,7 +90,7 @@ Set `ANTHROPIC_LOG=debug` (or `info`) to enable SDK logging via the standard `lo ```python response = client.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, messages=[ {"role": "user", "content": "What is the capital of France?"} @@ -109,7 +109,7 @@ for block in response.content: ```python response = client.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, system="You are a helpful coding assistant. Always provide examples in Python.", messages=[{"role": "user", "content": "How do I read a JSON file?"}] @@ -145,7 +145,7 @@ with open("image.png", "rb") as f: image_data = base64.standard_b64encode(f.read()).decode("utf-8") response = client.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, messages=[{ "role": "user", @@ -168,7 +168,7 @@ response = client.messages.create( ```python response = client.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, messages=[{ "role": "user", @@ -198,7 +198,7 @@ Use top-level `cache_control` to automatically cache the last cacheable block in ```python response = client.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, cache_control={"type": "ephemeral"}, # auto-caches the last cacheable block system="You are an expert on this large document...", @@ -212,7 +212,7 @@ For fine-grained control, add `cache_control` to specific content blocks: ```python response = client.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, system=[{ "type": "text", @@ -224,7 +224,7 @@ response = client.messages.create( # With explicit TTL (time-to-live) response = client.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, system=[{ "type": "text", @@ -249,16 +249,17 @@ If `cache_read_input_tokens` is zero across repeated identical-prefix requests, ## Extended Thinking -> **Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is removed on Fable 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6. +> **Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is removed on Fable 5, Claude Opus 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6. +> **Claude Opus 5:** thinking is on by default — omitting `thinking` runs adaptive (`{"type": "adaptive"}` is equivalent), unlike Opus 4.8/4.7 where omitting it meant no thinking. `{"type": "disabled"}` is accepted only at effort `high` or lower; pairing it with `xhigh`/`max` returns a 400. > **Older models:** Use `thinking: {type: "enabled", budget_tokens: N}` (must be < `max_tokens`, min 1024). ```python -# Fable 5 / Opus 4.8 / 4.7 / 4.6: adaptive thinking (recommended) +# Fable 5 / Claude Opus 5 / Opus 4.8 / 4.7 / 4.6: adaptive thinking (recommended) response = client.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, - thinking={"type": "adaptive", "display": "summarized"}, # display opt-in: default is omitted (empty thinking text) on Fable 5 / Mythos 5 / Opus 4.8 / 4.7 - output_config={"effort": "high"}, # low | medium | high | max + thinking={"type": "adaptive", "display": "summarized"}, # display opt-in: default is omitted (empty thinking text) on Fable 5 / Mythos 5 / Claude Opus 5 / Opus 4.8 / 4.7 + output_config={"effort": "high"}, # low | medium | high | xhigh | max messages=[{"role": "user", "content": "Solve this step by step..."}] ) @@ -316,7 +317,7 @@ To access raw headers or other response metadata, use `.with_raw_response`: ```python raw = client.messages.with_raw_response.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=1024, messages=[{"role": "user", "content": "Hello"}], ) @@ -362,7 +363,7 @@ class ConversationManager: # Usage conversation = ConversationManager( client=anthropic.Anthropic(), - model="claude-opus-4-8", + model="claude-opus-5", system="You are a helpful assistant." ) @@ -380,7 +381,7 @@ response2 = conversation.send("What's my name?") # Claude remembers "Alice" ### Compaction (long conversations) -> **Beta, Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6.** When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a `compaction` block; you must pass it back on subsequent requests — append `response.content`, not just the text. +> **Beta, Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6.** When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a `compaction` block; you must pass it back on subsequent requests — append `response.content`, not just the text. ```python import anthropic @@ -393,7 +394,7 @@ def chat(user_message: str) -> str: response = client.beta.messages.create( betas=["compact-2026-01-12"], - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, messages=messages, context_management={ @@ -464,7 +465,7 @@ if fallback_ran and response.stop_reason != "refusal": print(f"Served by {response.model}") ``` -A `stop_reason: "refusal"` on the final response means the whole chain refused. The header must be exactly `server-side-fallback-2026-06-01`; the parameter is rejected on the Batches API and unavailable on Amazon Bedrock, Vertex AI, and Microsoft Foundry — register the client-side `BetaRefusalFallbackMiddleware` on the client there instead. Full semantics (sticky routing, billing, streaming, echoing fallback turns back): `shared/model-migration.md` → Migrating to Claude Fable 5 → `refusal` stop reason. +A `stop_reason: "refusal"` on the final response means the whole chain refused. The header must be exactly `server-side-fallback-2026-06-01` **for this array form**; the newer `fallbacks: "default"` scalar form uses `server-side-fallback-2026-07-01` instead (see `shared/model-migration.md` → Migrating to Claude Opus 5 → New API features), and pairing either header with the other form returns a 400. The parameter is rejected on the Batches API and unavailable on Amazon Bedrock, Vertex AI, and Microsoft Foundry — register the client-side `BetaRefusalFallbackMiddleware` on the client there instead. Full semantics (sticky routing, billing, streaming, echoing fallback turns back): `shared/model-migration.md` → Migrating to Claude Fable 5 → `refusal` stop reason. --- @@ -475,7 +476,7 @@ A `stop_reason: "refusal"` on the final response means the whole chain refused. ```python # Automatic caching (simplest — caches the last cacheable block) response = client.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, cache_control={"type": "ephemeral"}, system=large_document_text, # e.g., 50KB of context @@ -491,7 +492,7 @@ response = client.messages.create( ```python # Default to Opus for most tasks response = client.messages.create( - model="claude-opus-4-8", # $5.00/$25.00 per 1M tokens + model="claude-opus-5", # $5.00/$25.00 per 1M tokens max_tokens=16000, messages=[{"role": "user", "content": "Explain quantum computing"}] ) @@ -515,7 +516,7 @@ simple_response = client.messages.create( ```python count_response = client.messages.count_tokens( - model="claude-opus-4-8", + model="claude-opus-5", messages=messages, system=system ) diff --git a/skills/claude-api/python/claude-api/batches.md b/skills/claude-api/python/claude-api/batches.md index 2ca54ea5..e917f57a 100644 --- a/skills/claude-api/python/claude-api/batches.md +++ b/skills/claude-api/python/claude-api/batches.md @@ -26,7 +26,7 @@ message_batch = client.messages.batches.create( Request( custom_id="request-1", params=MessageCreateParamsNonStreaming( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, messages=[{"role": "user", "content": "Summarize climate change impacts"}] ) @@ -34,7 +34,7 @@ message_batch = client.messages.batches.create( Request( custom_id="request-2", params=MessageCreateParamsNonStreaming( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, messages=[{"role": "user", "content": "Explain quantum computing basics"}] ) @@ -130,7 +130,7 @@ message_batch = client.messages.batches.create( Request( custom_id=f"analysis-{i}", params=MessageCreateParamsNonStreaming( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, system=shared_system, messages=[{"role": "user", "content": question}] diff --git a/skills/claude-api/python/claude-api/files-api.md b/skills/claude-api/python/claude-api/files-api.md index 14f5bb14..05778ddb 100644 --- a/skills/claude-api/python/claude-api/files-api.md +++ b/skills/claude-api/python/claude-api/files-api.md @@ -40,7 +40,7 @@ print(f"Size: {uploaded.size_bytes} bytes") ```python response = client.beta.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, messages=[{ "role": "user", @@ -69,7 +69,7 @@ image_file = client.beta.files.upload( ) response = client.beta.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, messages=[{ "role": "user", @@ -147,7 +147,7 @@ questions = [ for question in questions: response = client.beta.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, messages=[{ "role": "user", diff --git a/skills/claude-api/python/claude-api/streaming.md b/skills/claude-api/python/claude-api/streaming.md index 00649efd..e0a88fd4 100644 --- a/skills/claude-api/python/claude-api/streaming.md +++ b/skills/claude-api/python/claude-api/streaming.md @@ -4,7 +4,7 @@ ```python with client.messages.stream( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=64000, messages=[{"role": "user", "content": "Write a story"}] ) as stream: @@ -16,7 +16,7 @@ with client.messages.stream( ```python async with async_client.messages.stream( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=64000, messages=[{"role": "user", "content": "Write a story"}] ) as stream: @@ -30,7 +30,7 @@ async with async_client.messages.stream( ```python for event in client.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=64000, messages=[{"role": "user", "content": "Write a story"}], stream=True, @@ -46,13 +46,13 @@ No final-message accumulation is done for you in this form. Claude may return text, thinking blocks, or tool use. Handle each appropriately: -> **Fable 5 / Opus 4.8 / Opus 4.7 / Opus 4.6:** Use `thinking: {type: "adaptive"}`. On older models, use `thinking: {type: "enabled", budget_tokens: N}` instead. +> **Fable 5 / Claude Opus 5 / Opus 4.8 / Opus 4.7 / Opus 4.6:** Use `thinking: {type: "adaptive"}`. On Claude Opus 5 adaptive is also what you get by omitting `thinking` entirely. On older models, use `thinking: {type: "enabled", budget_tokens: N}` instead. ```python with client.messages.stream( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=64000, - thinking={"type": "adaptive", "display": "summarized"}, # display opt-in: default is omitted (empty thinking text) on Fable 5 / Mythos 5 / Opus 4.8 / 4.7 + thinking={"type": "adaptive", "display": "summarized"}, # display opt-in: default is omitted (empty thinking text) on Fable 5 / Mythos 5 / Claude Opus 5 / Opus 4.8 / 4.7 messages=[{"role": "user", "content": "Analyze this problem"}] ) as stream: for event in stream: @@ -77,7 +77,7 @@ The Python tool runner supports streaming: pass `stream=True` to `client.beta.me ```python with client.messages.stream( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=64000, tools=tools, messages=messages @@ -95,7 +95,7 @@ with client.messages.stream( ```python with client.messages.stream( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=64000, messages=[{"role": "user", "content": "Hello"}] ) as stream: @@ -142,7 +142,7 @@ def stream_with_progress(client, **kwargs): ```python try: with client.messages.stream( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=64000, messages=[{"role": "user", "content": "Write a story"}] ) as stream: diff --git a/skills/claude-api/python/claude-api/tool-use.md b/skills/claude-api/python/claude-api/tool-use.md index 8fde8b1f..ac467bfb 100644 --- a/skills/claude-api/python/claude-api/tool-use.md +++ b/skills/claude-api/python/claude-api/tool-use.md @@ -27,7 +27,7 @@ def get_weather(location: str, unit: str = "celsius") -> str: # The tool runner handles the agentic loop automatically runner = client.beta.messages.tool_runner( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, tools=[get_weather], messages=[{"role": "user", "content": "What's the weather in Paris?"}], @@ -60,7 +60,7 @@ max_restarts = 5 # cap pause_turn restarts, mirroring max_continuations advice restarts = 0 while True: runner = client.beta.messages.tool_runner( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, tools=tools, # may mix @beta_tool functions and server-tool definitions messages=messages, @@ -109,7 +109,7 @@ async with stdio_client(StdioServerParameters(command="mcp-server")) as (read, w tools_result = await mcp_client.list_tools() # tool_runner is sync — returns the runner, not a coroutine runner = client.beta.messages.tool_runner( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, messages=[{"role": "user", "content": "Use the available tools"}], tools=[async_mcp_tool(t, mcp_client) for t in tools_result.tools], @@ -127,7 +127,7 @@ from anthropic.lib.tools.mcp import mcp_message prompt = await mcp_client.get_prompt(name="my-prompt") response = await client.beta.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, messages=[mcp_message(m) for m in prompt.messages], ) @@ -140,7 +140,7 @@ from anthropic.lib.tools.mcp import mcp_resource_to_content resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt") response = await client.beta.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, messages=[{ "role": "user", @@ -181,7 +181,7 @@ messages = [{"role": "user", "content": user_input}] # Agentic loop: keep going until Claude stops calling tools while True: response = client.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, tools=tools, messages=messages @@ -228,7 +228,7 @@ final_text = next(b.text for b in response.content if b.type == "text") ```python response = client.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, tools=tools, messages=[{"role": "user", "content": "What's the weather in Paris?"}] @@ -243,7 +243,7 @@ for block in response.content: result = execute_tool(tool_name, tool_input) followup = client.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, tools=tools, messages=[ @@ -280,7 +280,7 @@ for block in response.content: # Send all results back at once if tool_results: followup = client.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, tools=tools, messages=[ @@ -310,7 +310,7 @@ tool_result = { ```python response = client.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, tools=tools, tool_choice={"type": "tool", "name": "get_weather"}, # Force specific tool @@ -330,7 +330,7 @@ import anthropic client = anthropic.Anthropic() response = client.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, messages=[{ "role": "user", @@ -358,7 +358,7 @@ uploaded = client.beta.files.upload(file=open("sales_data.csv", "rb")) # 2. Pass to code execution via container_upload block # Code execution is GA; Files API is still beta (pass via extra_headers) response = client.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, extra_headers={"anthropic-beta": "files-api-2025-04-14"}, messages=[{ @@ -403,7 +403,7 @@ for block in response.content: ```python # First request: set up environment response1 = client.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, messages=[{"role": "user", "content": "Install tabulate and create data.json with sample data"}], tools=[{"type": "code_execution_20260120", "name": "code_execution"}] @@ -415,7 +415,7 @@ container_id = response1.container.id # Second request: reuse the same container response2 = client.messages.create( container=container_id, - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, messages=[{"role": "user", "content": "Read data.json and display as a formatted table"}], tools=[{"type": "code_execution_20260120", "name": "code_execution"}] @@ -455,7 +455,7 @@ import anthropic client = anthropic.Anthropic() response = client.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, messages=[{"role": "user", "content": "Remember that my preferred language is Python."}], tools=[{"type": "memory_20250818", "name": "memory"}], @@ -481,7 +481,7 @@ memory = MyMemoryTool() # Use with tool runner runner = client.beta.messages.tool_runner( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, tools=[memory], messages=[{"role": "user", "content": "Remember my preferences"}], @@ -516,7 +516,7 @@ class ContactInfo(BaseModel): client = anthropic.Anthropic() response = client.messages.parse( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, messages=[{ "role": "user", @@ -535,7 +535,7 @@ print(contact.interests) # ["API", "SDKs"] ```python response = client.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, messages=[{ "role": "user", @@ -569,7 +569,7 @@ data = json.loads(text) ```python response = client.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, messages=[{"role": "user", "content": "Book a flight to Tokyo for 2 passengers on March 15"}], tools=[{ @@ -594,7 +594,7 @@ response = client.messages.create( ```python response = client.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=16000, messages=[{"role": "user", "content": "Plan a trip to Paris next month"}], output_config={ diff --git a/skills/claude-api/python/managed-agents/README.md b/skills/claude-api/python/managed-agents/README.md index 5ffa8b37..cb97bfa4 100644 --- a/skills/claude-api/python/managed-agents/README.md +++ b/skills/claude-api/python/managed-agents/README.md @@ -51,7 +51,7 @@ print(environment.id) # env_... # 1. Create the agent (reusable, versioned) agent = client.beta.agents.create( name="Coding Assistant", - model="claude-opus-4-8", + model="claude-opus-5", tools=[{"type": "agent_toolset_20260401", "default_config": {"enabled": True}}], ) @@ -71,7 +71,7 @@ import os agent = client.beta.agents.create( name="Code Reviewer", - model="claude-opus-4-8", + model="claude-opus-5", system="You are a senior code reviewer.", tools=[ {"type": "agent_toolset_20260401"}, @@ -314,7 +314,7 @@ client.beta.sessions.archive(session_id="sesn_011CZxAbc123Def456") # Agent declares MCP server (no auth here — auth goes in a vault) agent = client.beta.agents.create( name="MCP Agent", - model="claude-opus-4-8", + model="claude-opus-5", mcp_servers=[ {"type": "url", "name": "my-tools", "url": "https://my-mcp-server.example.com/sse"}, ], diff --git a/skills/claude-api/ruby/claude-api/README.md b/skills/claude-api/ruby/claude-api/README.md index 3648abb4..2a046685 100644 --- a/skills/claude-api/ruby/claude-api/README.md +++ b/skills/claude-api/ruby/claude-api/README.md @@ -26,7 +26,7 @@ client = Anthropic::Client.new(api_key: "your-api-key") ```ruby message = client.messages.create( - model: :"claude-opus-4-8", + model: :"claude-opus-5", max_tokens: 16000, messages: [ { role: "user", content: "What is the capital of France?" } @@ -44,12 +44,13 @@ end ## Extended Thinking -> **Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is removed on Fable 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6. +> **Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is removed on Fable 5, Claude Opus 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6. +> **Claude Opus 5:** thinking is on by default — omitting `thinking:` runs adaptive (`{ type: "adaptive" }` is equivalent), unlike Opus 4.8/4.7 where omitting it meant no thinking. `{ type: "disabled" }` is accepted only at effort `high` or lower; pairing it with `xhigh`/`max` returns a 400. > **Older models:** Use `thinking: { type: "enabled", budget_tokens: N }` (must be < `max_tokens`, min 1024). ```ruby message = client.messages.create( - model: :"claude-opus-4-8", + model: :"claude-opus-5", max_tokens: 16000, thinking: { type: "adaptive" }, messages: [{ role: "user", content: "Solve: 27 * 453" }] @@ -71,7 +72,7 @@ end ```ruby message = client.messages.create( - model: :"claude-opus-4-8", + model: :"claude-opus-5", max_tokens: 16000, system_: [ { type: "text", text: long_system_prompt, cache_control: { type: "ephemeral" } } @@ -109,7 +110,7 @@ end ```ruby response = client.beta.messages.create( - model: :"claude-opus-4-8", + model: :"claude-opus-5", max_tokens: 16000, output_config: { task_budget: { type: :tokens, total: 64_000 } }, tools: [...], diff --git a/skills/claude-api/ruby/claude-api/streaming.md b/skills/claude-api/ruby/claude-api/streaming.md index d6a143d3..2de9260a 100644 --- a/skills/claude-api/ruby/claude-api/streaming.md +++ b/skills/claude-api/ruby/claude-api/streaming.md @@ -4,7 +4,7 @@ ```ruby stream = client.messages.stream( - model: :"claude-opus-4-8", + model: :"claude-opus-5", max_tokens: 64000, messages: [{ role: "user", content: "Write a haiku" }] ) diff --git a/skills/claude-api/ruby/claude-api/tool-use.md b/skills/claude-api/ruby/claude-api/tool-use.md index 7f0aa382..70914b9e 100644 --- a/skills/claude-api/ruby/claude-api/tool-use.md +++ b/skills/claude-api/ruby/claude-api/tool-use.md @@ -24,7 +24,7 @@ class GetWeather < Anthropic::BaseTool end client.beta.messages.tool_runner( - model: :"claude-opus-4-8", + model: :"claude-opus-5", max_tokens: 16000, tools: [GetWeather.new], messages: [{ role: "user", content: "What's the weather in San Francisco?" }] diff --git a/skills/claude-api/ruby/managed-agents/README.md b/skills/claude-api/ruby/managed-agents/README.md index 8e439270..4b58dc96 100644 --- a/skills/claude-api/ruby/managed-agents/README.md +++ b/skills/claude-api/ruby/managed-agents/README.md @@ -51,7 +51,7 @@ puts "Environment ID: #{environment.id}" # env_... # 1. Create the agent (reusable, versioned) agent = client.beta.agents.create( name: "Coding Assistant", - model: :"claude-opus-4-8", + model: :"claude-opus-5", system_: "You are a helpful coding assistant.", tools: [{type: "agent_toolset_20260401"}] ) @@ -265,7 +265,7 @@ client.beta.sessions.delete(session.id) # Agent declares MCP server (no auth here — auth goes in a vault) agent = client.beta.agents.create( name: "GitHub Assistant", - model: :"claude-opus-4-8", + model: :"claude-opus-5", mcp_servers: [ { type: "url", diff --git a/skills/claude-api/shared/anthropic-cli.md b/skills/claude-api/shared/anthropic-cli.md index 417622e7..7a47885f 100644 --- a/skills/claude-api/shared/anthropic-cli.md +++ b/skills/claude-api/shared/anthropic-cli.md @@ -60,7 +60,7 @@ curl https://api.anthropic.com/v1/messages \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: oauth-2025-04-20" \ -H "content-type: application/json" \ - -d '{"model": "claude-opus-4-8", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello"}]}' + -d '{"model": "claude-opus-5", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello"}]}' # .env format — sets ANTHROPIC_AUTH_TOKEN (and ANTHROPIC_BASE_URL if the profile has one). # Output is bare KEY=value (no `export`), so use `set -a` to auto-export for child processes: @@ -82,7 +82,7 @@ Beta resources (agents, sessions, environments, deployments, skills, vaults, mem ```sh ant models list -ant messages create --model claude-opus-4-8 --max-tokens 1024 --message '{role: user, content: "Hello"}' +ant messages create --model claude-opus-5 --max-tokens 1024 --message '{role: user, content: "Hello"}' ant beta:agents retrieve --agent-id agent_01... ant beta:sessions:events list --session-id session_01... ``` @@ -123,7 +123,7 @@ AGENT_ID=$(ant beta:agents create --name "My Agent" --model '{id: claude-sonnet- ```sh ant beta:agents create \ --name "Research Agent" \ - --model '{id: claude-opus-4-8}' \ + --model '{id: claude-opus-5}' \ --tool '{type: agent_toolset_20260401}' \ --tool '{type: custom, name: search_docs, input_schema: {type: object, properties: {query: {type: string}}}}' ``` @@ -133,7 +133,7 @@ ant beta:agents create \ ```sh ant beta:agents create <<'YAML' name: Research Agent -model: claude-opus-4-8 +model: claude-opus-5 system: | You are a research assistant. Cite sources for every claim. tools: @@ -146,7 +146,7 @@ YAML ```sh ant beta:agents create --name "Researcher" --model '{id: claude-sonnet-5}' --system @./prompts/researcher.txt -ant messages create --model claude-opus-4-8 --max-tokens 1024 \ +ant messages create --model claude-opus-5 --max-tokens 1024 \ --message '{role: user, content: [ {type: document, source: {type: base64, media_type: application/pdf, data: "@./scan.pdf"}}, {type: text, text: "Extract the text from this scanned document."} diff --git a/skills/claude-api/shared/claude-platform-on-aws.md b/skills/claude-api/shared/claude-platform-on-aws.md index f5e99d6f..098db27a 100644 --- a/skills/claude-api/shared/claude-platform-on-aws.md +++ b/skills/claude-api/shared/claude-platform-on-aws.md @@ -1,6 +1,6 @@ # Claude Platform on AWS -**Anthropic-operated** access to the Claude Developer Platform through AWS infrastructure — SigV4 authentication, AWS IAM access control, and AWS Marketplace billing. Because Anthropic operates it, **the API surface matches first-party with same-day parity** — for per-feature exceptions, see `shared/platform-availability.md` (the single source of truth; do not rely on an inline exception list here). Model IDs are the bare first-party strings (`claude-opus-4-8`, `claude-sonnet-5`) — **no provider prefix**. +**Anthropic-operated** access to the Claude Developer Platform through AWS infrastructure — SigV4 authentication, AWS IAM access control, and AWS Marketplace billing. Because Anthropic operates it, **the API surface matches first-party with same-day parity** — for per-feature exceptions, see `shared/platform-availability.md` (the single source of truth; do not rely on an inline exception list here). Model IDs are the bare first-party strings (`claude-opus-5`, `claude-sonnet-5`) — **no provider prefix**. > **Not the same as Amazon Bedrock.** Bedrock is partner-operated (AWS runs the service; release schedules vary, feature subset, `anthropic.`-prefixed model IDs). Claude Platform on AWS and Bedrock coexist; pick by whether you need AWS-native IAM/billing with full Anthropic API parity (this page) vs. Bedrock's own ecosystem. @@ -25,7 +25,7 @@ from anthropic import AnthropicAWS client = AnthropicAWS() # region + workspace_id from env; see below client.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=1024, messages=[{"role": "user", "content": "Hello"}], ) @@ -55,5 +55,5 @@ The client resolves AWS credentials via the standard precedence chain: explicit ## What to tell users - Treat it as first-party: every section of this skill applies unchanged. Do **not** apply Bedrock's feature-availability mask. -- Model IDs are bare (`claude-opus-4-8`). Do **not** add an `anthropic.` prefix. +- Model IDs are bare (`claude-opus-5`). Do **not** add an `anthropic.` prefix. - A missing region or `workspace_id` throws at client-construction time (no request is sent). A **403** means the request reached the server — check for a **wrong** `workspace_id` or a missing IAM action on the principal. See the IAM actions reference in `shared/live-sources.md`. diff --git a/skills/claude-api/shared/error-codes.md b/skills/claude-api/shared/error-codes.md index 770eac15..56059ec3 100644 --- a/skills/claude-api/shared/error-codes.md +++ b/skills/claude-api/shared/error-codes.md @@ -82,7 +82,7 @@ This file documents HTTP error codes returned by the Claude API, their common ca - Using deprecated model ID - Invalid API endpoint -**Fix:** Use exact model IDs from the models documentation. You can use aliases (e.g., `claude-opus-4-8`). +**Fix:** Use exact model IDs from the models documentation. You can use aliases (e.g., `claude-opus-5`). --- @@ -107,11 +107,12 @@ Some 400 errors are specifically related to parameter validation: - `budget_tokens` >= `max_tokens` in extended thinking - Invalid tool definition schema -**Model-specific 400s on Fable 5 / Opus 4.8 / 4.7:** +**Model-specific 400s on Claude Opus 5 / Fable 5 / Opus 4.8 / 4.7:** - `temperature`, `top_p`, `top_k` are removed — sending any of them returns 400. Delete the parameter; see `shared/model-migration.md` → Per-SDK Syntax Reference. - `thinking: {type: "enabled", budget_tokens: N}` is removed — sending it returns 400. Use `thinking: {type: "adaptive"}` instead. -- **Fable 5 only:** an explicit `thinking: {type: "disabled"}` returns 400 (it is accepted on Opus 4.8/4.7). Omit the `thinking` param entirely instead. +- **Claude Opus 5:** `thinking: {type: "disabled"}` returns 400 when `effort` is `xhigh` or `max` — it is accepted at `high` or below. Thinking is on by default, so omitting the param runs adaptive rather than disabling it. +- **Fable 5 only:** an explicit `thinking: {type: "disabled"}` returns 400 at any effort (it is accepted on Opus 4.8/4.7). Omit the `thinking` param entirely instead. - **Fable 5 only:** if the organization is set to zero data retention (ZDR) — or any retention below the required 30 days — then **all** Fable 5 requests return `400 invalid_request_error`, even with a perfectly valid payload. Check the org's retention configuration before debugging the request body. **Common mistake with extended thinking on older models (Opus 4.6 and earlier):** @@ -170,12 +171,12 @@ thinking: budget_tokens=10000, max_tokens=16000 | Mistake | Error | Fix | | ------------------------------- | ---------------- | ------------------------------------------------------- | -| `temperature`/`top_p`/`top_k` on Fable 5 / Opus 4.8 / 4.7 | 400 | Remove the parameter (see `shared/model-migration.md`) | -| `budget_tokens` on Fable 5 / Opus 4.8 / 4.7 | 400 | Use `thinking: {type: "adaptive"}` | +| `temperature`/`top_p`/`top_k` on Claude Opus 5 / Fable 5 / Opus 4.8 / 4.7 | 400 | Remove the parameter (see `shared/model-migration.md`) | +| `budget_tokens` on Claude Opus 5 / Fable 5 / Opus 4.8 / 4.7 | 400 | Use `thinking: {type: "adaptive"}` | | `thinking: {type: "disabled"}` on Fable 5 | 400 | Omit the `thinking` param entirely (accepted on Opus 4.8/4.7) | | Org set to ZDR / retention below 30 days (Fable 5) | 400 on every request | Fix the org's data-retention configuration — the payload isn't the problem | | `budget_tokens` >= `max_tokens` (older models) | 400 | Ensure `budget_tokens` < `max_tokens` | -| Typo in model ID | 404 | Use valid model ID like `claude-opus-4-8` | +| Typo in model ID | 404 | Use valid model ID like `claude-opus-5` | | First message is `assistant` | 400 | First message must be `user` | | Consecutive same-role messages | 400 | Alternate `user` and `assistant` | | API key in code | 401 (leaked key) | Use environment variable | diff --git a/skills/claude-api/shared/live-sources.md b/skills/claude-api/shared/live-sources.md index a9e2e4e3..ccceae2f 100644 --- a/skills/claude-api/shared/live-sources.md +++ b/skills/claude-api/shared/live-sources.md @@ -25,7 +25,7 @@ This file contains WebFetch URLs for fetching current information from platform. | Topic | URL | Extraction Prompt | | ----------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | Extended Thinking | `https://platform.claude.com/docs/en/build-with-claude/extended-thinking.md` | "Extract extended thinking parameters, budget_tokens requirements, and usage examples" | -| Adaptive Thinking | `https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking.md` | "Extract adaptive thinking setup, effort levels, and Claude Opus 4.8 usage examples" | +| Adaptive Thinking | `https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking.md` | "Extract adaptive thinking setup, effort levels, and Claude Opus 5 usage examples" | | Effort Parameter | `https://platform.claude.com/docs/en/build-with-claude/effort.md` | "Extract effort levels, cost-quality tradeoffs, and interaction with thinking" | | Tool Use | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview.md` | "Extract tool definition schema, tool_choice options, and handling tool results" | | Streaming | `https://platform.claude.com/docs/en/build-with-claude/streaming.md` | "Extract streaming event types, SDK examples, and best practices" | diff --git a/skills/claude-api/shared/managed-agents-api-reference.md b/skills/claude-api/shared/managed-agents-api-reference.md index 8f721b42..4c11f3f4 100644 --- a/skills/claude-api/shared/managed-agents-api-reference.md +++ b/skills/claude-api/shared/managed-agents-api-reference.md @@ -44,7 +44,7 @@ All resources are under the `beta` namespace. Python and TypeScript share identi **Agent shorthand:** `agent` on session create accepts three forms — a bare string (`agent="agent_abc123"`, latest version), a pinned reference `{type: "agent", id, version}`, or `{type: "agent_with_overrides", id, version?, model?, system?, tools?, mcp_servers?, skills?}` to override those fields for this session only (see `shared/managed-agents-core.md` → Override agent configuration for a session). -**Model shorthand:** `model` on agent create accepts either a bare string (`model="claude-opus-4-8"` — uses `standard` speed) or the full config object, which takes `speed` and `effort` alongside `id`: `{id: "claude-opus-4-8", speed: "fast"}`, `{id: "claude-opus-4-8", effort: "high"}`. `effort` accepts a level string (`low`/`medium`/`high`/`xhigh`/`max`) or `{type: ""}`, and is **agent-configuration only** — an `effort` inside a per-session `model` override is ignored. See `shared/managed-agents-core.md` → Effort on the agent model. Note: `speed: "fast"` is supported only on Opus 4.8 and Opus 4.7. Opus 4.7 fast mode is deprecated; after removal, `speed: "fast"` on Opus 4.7 returns an error. Opus 4.8 is the durable fast-capable tier. +**Model shorthand:** `model` on agent create accepts either a bare string (`model="claude-opus-5"` — uses `standard` speed) or the full config object, which takes `speed` and `effort` alongside `id`: `{id: "claude-opus-5", speed: "fast"}`, `{id: "claude-opus-5", effort: "high"}`. `effort` accepts a level string (`low`/`medium`/`high`/`xhigh`/`max`) or `{type: ""}`, and is **agent-configuration only** — an `effort` inside a per-session `model` override is ignored. See `shared/managed-agents-core.md` → Effort on the agent model. Note: `speed: "fast"` is supported on Claude Opus 5 and Opus 4.8 — on the Claude API only, which includes Managed Agents but not Amazon Bedrock, Google Cloud, or Microsoft Foundry. Opus 4.7 fast mode has been removed; `speed: "fast"` on Opus 4.7 returns an error. --- @@ -184,7 +184,7 @@ Individual text documents inside a store (≤ 100KB each). `create` creates at a | Method | Path | Operation | Description | | -------- | ----------------------------------------------------------------- | -------------- | ---------------------------------------- | -| `GET` | `/v1/memory_stores/{memory_store_id}/memories` | ListMemories | Returns `Memory \| MemoryPrefix`; filter by `path_prefix`, `depth`, `order_by`/`order` | +| `GET` | `/v1/memory_stores/{memory_store_id}/memories` | ListMemories | Returns `Memory \| MemoryPrefix`; filter by `path_prefix`, `depth` | | `POST` | `/v1/memory_stores/{memory_store_id}/memories` | CreateMemory | Create at `path` (SDK: `memories.create`); `409 memory_path_conflict_error` if occupied | | `GET` | `/v1/memory_stores/{memory_store_id}/memories/{memory_id}` | GetMemory | Read one memory (defaults to `view="full"`) | | `PATCH` | `/v1/memory_stores/{memory_store_id}/memories/{memory_id}` | UpdateMemory | Change `content`, `path`, or both by ID; optional `precondition` | @@ -234,7 +234,7 @@ Immutable per-mutation snapshots (`memver_...`) — the audit and rollback surfa ```json { "name": "string (required, 1-256 chars)", - "model": "claude-opus-4-8 (required — bare string, or {id, speed?, effort?} object)", + "model": "claude-opus-5 (required — bare string, or {id, speed?, effort?} object)", "description": "string (optional, up to 2048 chars)", "system": "string (optional, up to 100,000 chars)", "tools": [ @@ -354,7 +354,7 @@ Immutable per-mutation snapshots (`memver_...`) — the audit and rollback surfa } ``` -> `system.message` events (append system-level context for this turn and later ones) use the same envelope with `type: "system.message"` — supported on Claude Opus 4.8, Claude Sonnet 5, Claude Fable 5, and Claude Mythos 5, checked against the agent's *primary* model only; see `shared/managed-agents-events.md` § Adding system context mid-session. +> `system.message` events (append system-level context for this turn and later ones) use the same envelope with `type: "system.message"` — supported on Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5, Claude Fable 5, and Claude Mythos 5, checked against the agent's *primary* model only; see `shared/managed-agents-events.md` § Adding system context mid-session. ### Define Outcome Event diff --git a/skills/claude-api/shared/managed-agents-core.md b/skills/claude-api/shared/managed-agents-core.md index 9787de40..12a1b869 100644 --- a/skills/claude-api/shared/managed-agents-core.md +++ b/skills/claude-api/shared/managed-agents-core.md @@ -108,7 +108,7 @@ Key fields returned by the API: const agent = await client.beta.agents.create( { name: "Coding Assistant", - model: "claude-opus-4-8", + model: "claude-opus-5", system: "You are a helpful coding agent.", tools: [{ type: "agent_toolset_20260401"}], }, @@ -214,11 +214,11 @@ The agent is a **persistent resource**, not a per-run parameter. The intended pa ### Effort on the agent model -Pass `model` as an object to set the effort level: `{"id": "claude-opus-4-8", "effort": "high"}`. `effort` accepts a level string (`low`, `medium`, `high`, `xhigh`, `max`) or an object such as `{"type": "high"}`. The create/update response echoes it in object form and fills in omitted `model` fields with their defaults. +Pass `model` as an object to set the effort level: `{"id": "claude-opus-5", "effort": "high"}`. `effort` accepts a level string (`low`, `medium`, `high`, `xhigh`, `max`) or an object such as `{"type": "high"}`. The create/update response echoes it in object form and fills in omitted `model` fields with their defaults. > ⚠️ **Effort is agent configuration only.** An `effort` set inside a per-session `model` override is **not applied** — the session runs at the agent's effort. To change effort you must update the agent (or point the session at a different agent). This is the one field where the override form silently does nothing rather than erroring. -The same object form carries `speed` for fast mode: `{"id": "claude-opus-4-8", "speed": "fast"}`. +The same object form carries `speed` for fast mode: `{"id": "claude-opus-5", "speed": "fast"}`. ### Versioning @@ -283,7 +283,7 @@ session = client.beta.sessions.create( agent={ "type": "agent_with_overrides", "id": agent.id, - "model": "claude-opus-4-8", # replace the agent's model for this session + "model": "claude-opus-5", # replace the agent's model for this session "system": None, # clear the system prompt for this session }, environment_id=environment_id, diff --git a/skills/claude-api/shared/managed-agents-environments.md b/skills/claude-api/shared/managed-agents-environments.md index f44f76bd..d528f57d 100644 --- a/skills/claude-api/shared/managed-agents-environments.md +++ b/skills/claude-api/shared/managed-agents-environments.md @@ -143,7 +143,7 @@ Repositories are attached for the lifetime of the session — to change which re const agent = await client.beta.agents.create( { name: 'GitHub Agent', - model: 'claude-opus-4-8', + model: 'claude-opus-5', mcp_servers: [ { type: 'url', name: 'github', url: 'https://api.githubcopilot.com/mcp/' }, ], @@ -177,7 +177,7 @@ import os agent = client.beta.agents.create( name="GitHub Agent", - model="claude-opus-4-8", + model="claude-opus-5", mcp_servers=[{ "type": "url", "name": "github", diff --git a/skills/claude-api/shared/managed-agents-events.md b/skills/claude-api/shared/managed-agents-events.md index a4d9f736..e22f7184 100644 --- a/skills/claude-api/shared/managed-agents-events.md +++ b/skills/claude-api/shared/managed-agents-events.md @@ -35,7 +35,7 @@ client.beta.sessions.events.send( Constraints: -- **Model-gated: Claude Opus 4.8, Claude Sonnet 5, Claude Fable 5, and Claude Mythos 5.** Only the agent's **primary** model is checked — `system.message` lands on the primary thread only, so subagent models are not considered. On an unsupported primary model the event is rejected with a `model_does_not_support_mid_conversation_system` validation error. +- **Model-gated: Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5, Claude Fable 5, and Claude Mythos 5.** Only the agent's **primary** model is checked — `system.message` lands on the primary thread only, so subagent models are not considered. On an unsupported primary model the event is rejected with a `model_does_not_support_mid_conversation_system` validation error. - **While the session is idle with `stop_reason: requires_action`** (blocked on `user.custom_tool_result` / `user.tool_confirmation`), a `system.message` is accepted **only when it trails a tool result event in the same request**. Sent on its own — or alongside a `user.message` — it is rejected until the pending tool events are resolved. - `content` accepts 1–1000 text items. @@ -51,7 +51,7 @@ All **persisted** events carry `id`, `type`, and `processed_at` (ISO 8601), set > ⚠️ **Robust polling (raw HTTP).** If you bypass the SDK and roll your own poll loop, don't rely on `requests` or `httpx` timeouts as wall-clock caps — they're **per-chunk** read timeouts, reset every time a byte arrives. A trickling response (heartbeats, a wedged chunked-encoding body, a misbehaving proxy) can keep the call blocked indefinitely even with `timeout=(5, 60)` or `httpx.Timeout(120)`. Neither library has a "total wall-clock" timeout built in. For a hard deadline: track `time.monotonic()` at the loop level and break/cancel if a single request exceeds your budget (e.g. via a watchdog thread, or `asyncio.wait_for()` around async httpx). **Prefer the SDK** — `client.beta.sessions.events.stream()` and `client.beta.sessions.events.list()` handle timeout + retry sanely. > -> If `GET /v1/sessions/{id}/events` (paginated) ever hangs after headers, you've likely hit `GET /v1/sessions/{id}/events` by mistake or a server-side stall — report it; don't treat it as a client-config problem. +> If `GET /v1/sessions/{id}/events` (paginated) ever hangs after headers, you've likely hit `GET /v1/sessions/{id}/events/stream` by mistake or a server-side stall — report it; don't treat it as a client-config problem. ### Event Types (Received) diff --git a/skills/claude-api/shared/managed-agents-memory.md b/skills/claude-api/shared/managed-agents-memory.md index 3c01d1fe..1b59052e 100644 --- a/skills/claude-api/shared/managed-agents-memory.md +++ b/skills/claude-api/shared/managed-agents-memory.md @@ -84,7 +84,7 @@ Use these for review workflows, correcting bad memories, or seeding stores out-o ### List -Returns `Memory | MemoryPrefix` entries — a `MemoryPrefix` (`type: "memory_prefix"`, just a `path`) is a directory-like node when listing hierarchically. Use `path_prefix` to scope (include a trailing slash: `"/notes/"` matches `/notes/a.md` but not `/notes_backup/old.md`) and `depth` to bound the tree walk. `order_by` / `order` sort the result. Pass `view="full"` to include `content` in each item; the default `"basic"` returns metadata only. +Returns `Memory | MemoryPrefix` entries — a `MemoryPrefix` (`type: "memory_prefix"`, just a `path`) is a directory-like node when listing hierarchically. Use `path_prefix` to scope (include a trailing slash: `"/notes/"` matches `/notes/a.md` but not `/notes_backup/old.md`) and `depth` to bound the tree walk. Pass `view="full"` to include `content` in each item; the default `"basic"` returns metadata only. ```python for m in client.beta.memory_stores.memories.list(store.id, path_prefix="/"): diff --git a/skills/claude-api/shared/managed-agents-multiagent.md b/skills/claude-api/shared/managed-agents-multiagent.md index 50a4a209..3b741994 100644 --- a/skills/claude-api/shared/managed-agents-multiagent.md +++ b/skills/claude-api/shared/managed-agents-multiagent.md @@ -13,7 +13,7 @@ The SDK sets the `managed-agents-2026-04-01` beta header automatically on all `c ```python orchestrator = client.beta.agents.create( name="Engineering Lead", - model="claude-opus-4-8", + model="claude-opus-5", system="You coordinate engineering work. Delegate code review to the reviewer and test writing to the test agent.", tools=[{"type": "agent_toolset_20260401"}], multiagent={ diff --git a/skills/claude-api/shared/managed-agents-onboarding.md b/skills/claude-api/shared/managed-agents-onboarding.md index fab80ac7..2fab2475 100644 --- a/skills/claude-api/shared/managed-agents-onboarding.md +++ b/skills/claude-api/shared/managed-agents-onboarding.md @@ -24,7 +24,7 @@ Their description does the interview's work. Draft the agent config from it and - **Skills** — **suggest** prebuilt `xlsx`/`docx`/`pptx`/`pdf` when the job produces those artifacts; custom by `skill_id` (max 20 total per agent, prebuilt + custom combined). - **Outcome** — if the description implies checkable "done" criteria (or you can elicit them in the follow-up: not "a good report" but "a CSV with a numeric `price` column per SKU"), **suggest an Outcome kickoff** — the harness grades and iterates against a rubric (`shared/managed-agents-outcomes.md`). - **On-hand resources** — repos on disk (`github_repository`: URL, optional `mount_path`/`checkout`; token comes in §4), files to seed (Files API upload → `{type: "file", file_id, mount_path}`; read-only), if the job references them. -- **Model** — default `claude-opus-4-8`; `claude-fable-5` for the hardest long-horizon work (`shared/model-migration.md` → Migrating to Claude Fable 5). +- **Model** — default `claude-opus-5`; `claude-fable-5` for the hardest long-horizon work (`shared/model-migration.md` → Migrating to Claude Fable 5). > ‼️ **PR creation needs the GitHub MCP server too** — a `github_repository` mount is filesystem-only. Edit in the mount → push branch via `bash` → open the PR via the MCP `create_pull_request` tool. diff --git a/skills/claude-api/shared/managed-agents-overview.md b/skills/claude-api/shared/managed-agents-overview.md index 9b4c6a6e..a2a88c05 100644 --- a/skills/claude-api/shared/managed-agents-overview.md +++ b/skills/claude-api/shared/managed-agents-overview.md @@ -65,7 +65,7 @@ Managed Agents is in beta. The SDK sets required beta headers automatically: - **Reconcile resources before the first run** — a session with a clear ask but a missing tool, credential, data mount, or context will discover the gap mid-run, then flail and give up. Before creating the session, check that every action in the task maps to a configured tool/MCP server, every MCP server has a vault credential, and every referenced file/host is mounted/reachable. When helping a user set one up, run the reconciliation in `shared/managed-agents-onboarding.md` → §3 Pre-flight viability check. - **Stream to get events** — `GET /v1/sessions/{id}/events/stream` is the primary way to receive agent output in real-time. - **SSE stream has no replay — reconnect with consolidation** — if the stream drops while a `agent.tool_use`, `agent.mcp_tool_use`, or `agent.custom_tool_use` is pending resolution (`user.tool_confirmation` for the first two, `user.custom_tool_result` for the last one), the session deadlocks (client disconnects → session idles → reconnect happens → no client resolution happens). On every (re)connect: open stream with `GET /v1/sessions/{id}/events/stream` , fetch `GET /v1/sessions/{id}/events`, dedupe by event ID, then proceed. See `shared/managed-agents-events.md` → Reconnecting after a dropped stream. -- **Don't trust HTTP-library timeouts as wall-clock caps** — `requests` `timeout=(c, r)` and `httpx.Timeout(n)` are *per-chunk* read timeouts; they reset every byte, so a trickling connection can block indefinitely. For a hard deadline on raw-HTTP polling, track `time.monotonic()` at the loop level and bail explicitly. Prefer the SDK's `sessions.events.stream()` / `session.events.list()` over hand-rolled HTTP. See `shared/managed-agents-events.md` → Receiving Events. +- **Don't trust HTTP-library timeouts as wall-clock caps** — `requests` `timeout=(c, r)` and `httpx.Timeout(n)` are *per-chunk* read timeouts; they reset every byte, so a trickling connection can block indefinitely. For a hard deadline on raw-HTTP polling, track `time.monotonic()` at the loop level and bail explicitly. Prefer the SDK's `sessions.events.stream()` / `sessions.events.list()` over hand-rolled HTTP. See `shared/managed-agents-events.md` → Receiving Events. - **Messages queue** — you can send events while the session is `running` or `idle`; they're processed in order. No need to wait for a response before sending the next message. - **Environment `config.type` is `"cloud"` or `"self_hosted"`** — `cloud` runs the container on Anthropic's infrastructure; `self_hosted` moves tool execution to your own (see `shared/managed-agents-self-hosted-sandboxes.md`). - **Archive is permanent on every resource** — archiving an agent, environment, session, vault, credential, or memory store makes it read-only with no unarchive. For agents, environments, and memory stores specifically, archived resources cannot be referenced by new sessions (existing sessions continue). Do not call `.archive()` on a production agent, environment, or memory store as cleanup — **always confirm with the user before archiving**. diff --git a/skills/claude-api/shared/managed-agents-tools.md b/skills/claude-api/shared/managed-agents-tools.md index efcdb13e..fb1ef971 100644 --- a/skills/claude-api/shared/managed-agents-tools.md +++ b/skills/claude-api/shared/managed-agents-tools.md @@ -322,7 +322,7 @@ Skills are attached to the **agent** definition via `agents.create()`: const agent = await client.beta.agents.create( { name: "Financial Agent", - model: "claude-opus-4-8", + model: "claude-opus-5", system: "You are a financial analysis agent.", skills: [ { type: "anthropic", skill_id: "xlsx" }, @@ -337,7 +337,7 @@ Python: ```python agent = client.beta.agents.create( name="Financial Agent", - model="claude-opus-4-8", + model="claude-opus-5", system="You are a financial analysis agent.", skills=[ {"type": "anthropic", "skill_id": "xlsx"}, diff --git a/skills/claude-api/shared/model-migration.md b/skills/claude-api/shared/model-migration.md index 2efa623a..07a871da 100644 --- a/skills/claude-api/shared/model-migration.md +++ b/skills/claude-api/shared/model-migration.md @@ -19,6 +19,8 @@ For the latest, authoritative version (with code samples in every supported lang | Opus 4.7 Migration Checklist | The required vs optional items for 4.7, tagged `[BLOCKS]` / `[TUNE]` | | Migrating to Opus 4.8 | Migrating to Opus 4.8 (no new breaking changes; mid-session system prompts; behavioral re-tuning) | | Opus 4.8 Migration Checklist | The required vs optional items for 4.8, tagged `[BLOCKS]` / `[TUNE]` | +| Migrating to Claude Opus 5 | Migrating Opus 4.8 → Claude Opus 5 (thinking-disabled effort-gated; mid-conversation tool changes; per-turn effort and task budget; verbosity, over-verification, and scope re-tuning) | +| Claude Opus 5 Migration Checklist | The required vs optional items for Claude Opus 5, tagged `[BLOCKS]` / `[TUNE]` | | Migrating to Claude Sonnet 5 | Migrating Sonnet 4.6 → Claude Sonnet 5 (adaptive thinking on by default; non-default sampling params 400; new tokenizer; `xhigh` effort for coding/agentic; high-res vision; behavioral re-tuning) | | Claude Sonnet 5 Migration Checklist | The required vs optional items, tagged `[BLOCKS]` / `[TUNE]` | | Migrating to Claude Fable 5 | Migrating to Claude Fable 5 or Claude Mythos 5 (always-on thinking, raw chain of thought never returned, refusal handling, data retention, behavioral shifts + prompting guidance) | @@ -183,9 +185,10 @@ If you're applying several prompt-tuning edits at once, offer them as a short li | If you're on… | Migrate to | Why | | ------------------------------------- | ------------------ | ------------------------------------------------- | | Claude Mythos Preview (`claude-mythos-preview`) | `claude-mythos-5` (Project Glasswing successor) or `claude-fable-5` (GA) | Same tokenizer family — mostly a model-ID swap; remove `thinking` config and prefill; see Migrating to Claude Fable 5 | -| Opus 4.7 | `claude-opus-4-8` | Most capable Opus-tier model; same API surface as 4.7 (no new breaking changes) — mostly prompt re-tuning; see Migrating to Opus 4.8 | -| Opus 4.6 | `claude-opus-4-8` | Apply the Opus 4.7 breaking changes, then the 4.8 re-tuning | -| Opus 4.0 / 4.1 / 4.5 / Opus 3 | `claude-opus-4-8` | Apply 4.6 → 4.7 → 4.8 in order (adaptive thinking, drop sampling params, then re-tune) | +| Opus 4.8 | `claude-opus-5` | The current Opus. Two breaking changes (thinking on by default; disabling thinking capped at `high` effort) plus prompt re-tuning — see Migrating to Claude Opus 5 | +| Opus 4.7 | `claude-opus-5` | Apply the Opus 4.8 section (prompt re-tuning, no new breaking changes), then the Claude Opus 5 section | +| Opus 4.6 | `claude-opus-5` | Apply the Opus 4.7 breaking changes, then 4.8 re-tuning, then the Claude Opus 5 section | +| Opus 4.0 / 4.1 / 4.5 / Opus 3 | `claude-opus-5` | Apply 4.6 → 4.7 → 4.8 → Claude Opus 5 in order (adaptive thinking, drop sampling params, then re-tune) | | Sonnet 4.6 | `claude-sonnet-5` | Near-Opus quality on agentic and coding work at Sonnet cost; adaptive thinking on by default; see Migrating to Claude Sonnet 5 | | Sonnet 4.0 / 4.5 / 3.7 / 3.5 | `claude-sonnet-5` | Apply the Sonnet 4.6 changes first, then the Claude Sonnet 5 section | | Haiku 3 / 3.5 | `claude-haiku-4-5` | Fastest and most cost-effective | @@ -482,11 +485,12 @@ If the model is now overtriggering a tool or skill, the fix is almost always to | Old string (migration source) | New string | | ------------------------------ | ------------------ | -| `claude-opus-4-7` | `claude-opus-4-8` | -| `claude-opus-4-6` | `claude-opus-4-8` | -| `claude-opus-4-5` | `claude-opus-4-8` | -| `claude-opus-4-1` | `claude-opus-4-8` | -| `claude-opus-4-0` | `claude-opus-4-8` | +| `claude-opus-4-8` | `claude-opus-5` | +| `claude-opus-4-7` | `claude-opus-5` | +| `claude-opus-4-6` | `claude-opus-5` | +| `claude-opus-4-5` | `claude-opus-5` | +| `claude-opus-4-1` | `claude-opus-5` | +| `claude-opus-4-0` | `claude-opus-5` | | `claude-mythos-preview` | `claude-mythos-5` (Project Glasswing) or `claude-fable-5` | | `claude-sonnet-4-6` | `claude-sonnet-5`| | `claude-sonnet-4-5` | `claude-sonnet-5`| @@ -501,6 +505,7 @@ If the code uses the `AnthropicBedrockMantle` client (Python `anthropic[bedrock] | First-party ID | Bedrock ID | |---|---| | `claude-opus-4-8` | `anthropic.claude-opus-4-8` | +| `claude-opus-5` | `anthropic.claude-opus-5` | | `claude-opus-4-7` | `anthropic.claude-opus-4-7` | | `claude-sonnet-5` | `anthropic.claude-sonnet-5` | | `claude-haiku-4-5` | `anthropic.claude-haiku-4-5` | @@ -686,22 +691,22 @@ Beyond resolution, Opus 4.7 also improves on low-level perception (pointing, mea Requests that involve prohibited or high-risk topics may lead to refusals. -### Fast Mode: Opus 4.8 / 4.7 only +### Fast Mode: Claude Opus 5 / Opus 4.8 only -Fast mode is available on Opus 4.8 and Opus 4.7. Only surface this if the caller's code actually uses fast mode (e.g. `model="claude-opus-4-6-fast"`, or `speed="fast"` on an unsupported model); if the word "fast" does not appear in the code, say nothing about Fast Mode. +Fast mode is available on Claude Opus 5 and Opus 4.8. Only surface this if the caller's code actually uses fast mode (e.g. `model="claude-opus-4-6-fast"`, or `speed="fast"` on an unsupported model); if the word "fast" does not appear in the code, say nothing about Fast Mode. -When you see `model="claude-opus-4-6-fast"` (or any retired `-fast` model string), **the migration edit is** to move the fast-mode traffic onto Opus 4.8, the durable fast-capable tier: +When you see `model="claude-opus-4-6-fast"` (or any retired `-fast` model string), **the migration edit is** to move the fast-mode traffic onto Claude Opus 5, the current fast-capable default (Opus 4.8 also works if the caller is staying on that tier): ```python -# Request fast mode on Opus 4.8. +# Request fast mode on Claude Opus 5. client.beta.messages.create( - model="claude-opus-4-8", max_tokens=4096, + model="claude-opus-5", max_tokens=4096, speed="fast", betas=["fast-mode-2026-02-01"], messages=[...], ) ``` -That is: switch the model to Opus 4.8 and request fast mode the supported way, using the beta `client.beta.messages.…` endpoint, the `fast-mode-2026-02-01` beta flag, and `speed="fast"` as a top-level request parameter (per-language form in SKILL.md § Fast Mode). Opus 4.7 also supports fast mode today, but it is itself being sunset (fast mode removed by default around Jul 25, 2026), so target Opus 4.8 as the durable choice rather than landing on a tier that is about to lose fast mode. Do **not** leave the code on a retired `-fast` model string — the failure mode differs by version: `claude-opus-4-6-fast` is already retired and the API **silently falls back** to standard Opus 4.6 (no error — the caller loses fast-mode speed without noticing); `claude-opus-4-7-fast`, once removed, will instead return an **API error** (hard failure — requests break outright rather than degrading). Either way, migrate to Opus 4.8 fast mode now. +That is: switch the model to Claude Opus 5 (or Opus 4.8) and request fast mode the supported way, using the beta `client.beta.messages.…` endpoint, the `fast-mode-2026-02-01` beta flag, and `speed="fast"` as a top-level request parameter (per-language form in SKILL.md § Fast Mode). Opus 4.7 fast mode has also been removed, so do not land on Opus 4.7 either. Do **not** leave the code on a retired `-fast` model string — the failure mode differs by version: `claude-opus-4-6-fast` is retired and the API **silently falls back** to standard Opus 4.6 (no error — the caller loses fast-mode speed without noticing); `claude-opus-4-7-fast` and `speed="fast"` on Opus 4.7 instead return an **API error** (hard failure — requests break outright rather than degrading). Either way, migrate to Opus 4.8 fast mode now. ### Behavioral shifts (prompt-tunable) @@ -895,6 +900,248 @@ For a caller **already on Opus 4.7**, only the first item is required; everythin --- +## Migrating to Claude Opus 5 + +> **Model ID `claude-opus-5` is authoritative as written here.** When the user asks to migrate to Claude Opus 5, write `model="claude-opus-5"` exactly. Do **not** WebFetch to verify — this guide is the source of truth for migration target IDs. The corresponding entry exists in `shared/models.md`. + +Claude Opus 5 is the successor to Claude Opus 4.8 in the Opus line, and is strongest on long-horizon agentic work and coding. It is layered on top of the Opus 4.8 migration above; if the caller is coming from Opus 4.7 or older, apply those sections first. Like Claude Fable 5, it ships with **elevated cybersecurity safeguards, and its safety classifiers can decline a request**: you get a normal HTTP 200 with `stop_reason: "refusal"` and a `stop_details` category, not an error. Benign security and life-sciences work occasionally trips them, so **check `stop_reason` before reading `response.content`** — code that indexes `content[0]` unconditionally breaks on a refusal. Cyber-category refusals route to Opus 4.8 as the recommended fallback, so a fallback strategy genuinely recovers the request rather than just relabelling the failure. The full refusal semantics (pre-output vs mid-stream billing, retry strategies, fallback credit) are in the Claude Fable 5 section below and apply here unchanged. + +Existing prompts and evals should carry over with strong out-of-the-box performance. **It is a drop-in upgrade at Opus 4.8's pricing** — $5 per million input tokens, $25 per million output — with the same feature set: 1M context (default, no beta header), 128K max output, adaptive thinking, prompt caching, batch processing, the Files API, PDF support, vision, and the full server-side and client-side tool set. `claude-opus-5` is a fixed ID with no date suffix, same scheme as `claude-opus-4-8`. + +The migration is **the model-ID swap plus prompt re-tuning**, with two breaking changes covered below. + +**Availability at launch:** Claude API (`claude-opus-5`), Amazon Bedrock (`anthropic.claude-opus-5`), Google Cloud (`claude-opus-5`), and Microsoft Foundry. Opus 4.8 stays available on all four. + +**Rate limits are a separate bucket.** Opus 4.8/4.7/4.6/4.5 share one combined Opus limit; Claude Opus 5 does **not** draw from it. Shifting traffic over neither frees headroom on the old bucket nor inherits it — check your tier's Claude Opus 5 limits before moving volume. + +**TL;DR for someone already on Claude Opus 4.8:** swap the model ID. Then re-tune: Claude Opus 5 writes longer user-facing responses and longer files on disk (add explicit conciseness and deliverable-length instructions — `effort` does not reliably shorten visible output), verifies its own work without being told (**delete** your verification instructions and harness verification steps), and can expand task scope (add a scope-discipline instruction). Run a fresh effort sweep — `low` and `medium` are unusually strong here and are the primary cost/latency lever. + +### Breaking change 1: thinking is on by default + +A request that omits the `thinking` parameter **thinks** on Claude Opus 5, unlike Claude Opus 4.8 and Opus 4.7 where omitting it meant no thinking. `thinking: {type: "adaptive"}` remains valid and is equivalent to the default — the wire value didn't change, the default did. + +This is a silent cost and truncation change, not just a behavior one: **`max_tokens` is a hard cap on thinking *plus* response text.** A workload that ran without thinking on Opus 4.8 and sized `max_tokens` tightly around its answer can now truncate mid-response. Revisit `max_tokens` on every route that never set `thinking`. To keep the old behavior, pass `thinking: {type: "disabled"}` — subject to the effort cap below. + +Raw thinking tokens are **never returned** on Claude Opus 5; `display` defaults to `"omitted"`, and `display: "summarized"` gets you a summary. This also means a fallback model cannot read Claude Opus 5's thinking. + +### Breaking change 2: disabling thinking is capped at `high` effort + +Disabling thinking is available only at effort **`high` or lower**; `thinking: {type: "disabled"}` combined with `xhigh` or `max` returns a 400. Opus 4.8 accepts that combination, so audit any route that disables thinking before migrating. + +**The check is per request.** Effort and thinking are validated independently on every call, so a later request that raises effort to `xhigh` while thinking is still disabled is rejected even though earlier requests in the same conversation succeeded. + +```python +# 400 on Claude Opus 5 — disabled thinking above `high` +client.messages.create( + model="claude-opus-5", + max_tokens=4096, + thinking={"type": "disabled"}, + output_config={"effort": "xhigh"}, + messages=[...], +) +``` + +**Migrating:** either enable thinking at `xhigh`/`max`, or lower effort to `high` or below. Given how well Claude Opus 5 performs at `low` and `medium`, a latency-sensitive route that previously ran `xhigh` + disabled thinking is usually better served by `medium` with thinking on than by keeping the disabled path. + +Everything else from the Opus 4.7/4.8 request surface is unchanged: `budget_tokens` still 400s (use `output_config.effort`), sampling parameters (`temperature`, `top_p`, `top_k`) are still rejected, last-assistant-turn prefills still 400, and `thinking.display` still defaults to `"omitted"`. + +### Two failure modes when thinking is disabled + +**Are you affected?** Only if you explicitly set `thinking: {type: "disabled"}`. Thinking is on by default on Claude Opus 5 (see Breaking change 1 above), so an unmodified request never hits either of these — but code carrying a disabled-thinking setting forward from Opus 4.8, where it was the default behaviour, does. + +Both are specific to `thinking: {type: "disabled"}` on Claude Opus 5, and for both the **primary recommendation is the same: turn thinking back on and use a lower `effort` to control cost and verbosity instead.** Disabling thinking is the more expensive lever in every sense — it is what triggers these, and `low`/`medium` effort already gets you most of the token and latency saving (see § Effort below). + +**1. Tool calls can arrive as plain text.** The model occasionally writes a tool call into its user-facing text rather than emitting a structured `tool_use` block. **The turn completes normally and the call never runs** — there is no error and no `tool_use` block to catch, so a harness sees a successful turn that silently did nothing. Worse in an agentic loop: the bogus text stays in conversation history and skews later turns. Most common on tool-heavy workloads such as search. + +**2. `` tags can leak into the visible response.** The model may emit `` or other internal XML in its user-facing output. + +If you cannot enable thinking, one instruction covers both failure modes — give the model explicit permission to talk before a tool call (the tool-as-text failure appears to come from suppressing the preamble it wants to write), and forbid internal tags generically: + +> *"When you use a tool, you may say a brief sentence first. If no tool can express what the user asked for, say so instead of guessing. Do not include internal or system XML tags in your response."* + +Two counterintuitive rules for that instruction: + +- **Delete any instruction telling the model not to think or not to reason.** That kind of rule *increases* tag leakage rather than suppressing it. +- **Do not name thinking tags in the prompt.** Calling out `` by name is measurably less effective than the generic "internal or system XML tags" wording above. + +### New API features + +Two additions, each behind its own beta header. Both are optional — a migrated request works without them. + +**1. `fallbacks: "default"` — recommended for every caller.** Claude Opus 5's safety classifiers can decline a request; the `fallbacks` parameter re-runs a declined request on another model server-side instead of returning the refusal to you. Previously you named the substitute yourself (`"fallbacks": [{"model": "claude-opus-4-8"}]`). The new `"default"` mode picks Anthropic's recommended fallback automatically, routed **by refusal category** — cyber-category refusals go to Claude Opus 4.8. + +```http +POST /v1/messages +anthropic-beta: server-side-fallback-2026-07-01 + +{"model": "claude-opus-5", "fallbacks": "default", "max_tokens": 1024, + "messages": [{"role": "user", "content": "Say OK."}]} +``` + +**Prefer `"default"` over pinning a model.** Different fallback models carry different classifiers, so the right substitute depends on *why* the request was declined — and `"default"` removes the migration you would otherwise owe when a pinned fallback model is deprecated. Note the header is `server-side-fallback-2026-07-01`, distinct from the `-2026-06-01` header that gates the array form; the array form's semantics (content blocks, `usage.iterations`, sticky routing) are unchanged and documented in the Claude Fable 5 refusal section below. + +**2. Mid-conversation tool changes (beta `mid-conversation-tool-changes-2026-07-01`).** Change a conversation's tool set between turns without invalidating the prompt cache. Previously `tools` was fixed for the conversation's lifetime and any edit re-billed the whole prefix. Append a `{"role": "system", "content": [...]}` message carrying a `tool_addition` or `tool_removal` block: + +```python +messages = [ + {"role": "user", "content": "What tools do you have for weather in Paris?"}, + {"role": "system", "content": [ + {"type": "tool_addition", "tool": {"type": "tool_reference", "name": "get_forecast"}}, + ]}, +] +``` + +The added tool must already be declared in `tools[]` with `"defer_loading": True` — declared up front, but not loaded into context until a `tool_addition` surfaces it. A `tool_removal` block must sit either immediately before an assistant message or at the end of `messages`. To *change* a tool's definition, remove the old one on one request, then send the updated entry in `tools[]` on the next. See `shared/tool-use-concepts.md` § Mid-conversation tool changes. + +> ⚠️ Earlier previews of this feature used a different beta header and different block shapes. Both are deprecated — if the code you're migrating carries anything other than `mid-conversation-tool-changes-2026-07-01` with `tool_addition` / `tool_removal` / `tool_reference`, update the header and the shapes together. + + +> **SDK typings lag these blocks.** Pass them as plain dicts in Python (the SDK forwards unknown keys unchanged) or add a `@ts-expect-error` in TypeScript until the types catch up. `extra_body` / `extra_headers` work on `.stream()` exactly as on `.create()`. + +### Capability improvements + +**Agentic coding.** Claude Opus 5 is a workhorse for agentic coding and is strongest on *difficult* tasks — multi-file features, larger refactors, end-to-end feature work. It completes tasks rather than leaving stubs or placeholders. The gap over prior models is smaller on easy single-turn edits, so evaluate it on the hard end of your workload. To get the most out of it, give the complete task specification up front and let it run; longer autonomous sessions with more parallel agents show the strongest results, short interactive edits the least. + +**Code review and bug-finding.** High precision *and* high recall — a high rate of real bugs per pass, with the extra findings mostly real rather than false positives. It stays accurate at lower effort, which makes a cheap fast pass at review time plus a thorough pass later a practical pattern. + +**Effort: the full ladder, and where to start.** Claude Opus 5 supports all five levels — `low`, `medium`, `high`, `xhigh`, `max` — with no beta header. The API default is `high`. + +- **Start at `high` (the API default), then sweep down.** `low` and `medium` are unusually effective on this model — strong quality at a fraction of the tokens and latency on many workloads — so treat them as the primary cost/latency lever and reserve `high` and above for tasks where your evals show a quality difference. Effort defaults carried over from a prior model are usually not the right setting here; run a fresh sweep. +- **`xhigh` and `max` are for measured wins, not a starting point.** `max` is the top tier for the deepest reasoning and worth testing where capability matters more than spend, but it can show diminishing returns and overthink simpler tasks. + +At `xhigh` or `max`, **set a large `max_tokens`** so the model has room to think and act across tool calls and subagents. Start at 64K and tune. + +**Lower prompt-cache minimum.** The minimum cacheable prompt is **512 tokens** on Claude Opus 5, down from 1024 on Opus 4.8. Prompts previously too short to cache now create entries with no code change — worth re-checking any prompt you'd written off as uncacheable. See `shared/prompt-caching.md`. + +**Fast mode.** `speed: "fast"` (beta header `fast-mode-2026-02-01`) is supported on Claude Opus 5, priced at $10 / $50 per MTok. It is a research preview on the **Claude API only** — including Managed Agents — and is **not** available on Amazon Bedrock, Google Cloud, or Microsoft Foundry. Fast mode draws on dedicated rate limits separate from the standard Opus pools. + +**Vision — give it tools, not more thinking.** Stronger on chart, document, and diagram understanding, and on UI and frontend visual replication. The highest-leverage change is **giving it tools to iteratively analyze, crop, and visually verify its own work**: on this model tool use is a markedly more cost-effective lever than raising thinking alone. Claude Opus 5 sits in the high-resolution tier alongside Opus 4.8 — 2576 px on the long edge, up to 4784 visual tokens per image — so coordinates map 1:1 to pixels and no scale-factor math is needed. Any prompt-side workaround you added for a prior model's vision limitations should be re-validated; several are now counterproductive. + +**Long context.** 1M-token context window as both the default *and* the maximum. Instruction following, tool calling, and reasoning stay strong across the full window. + +**Office and document tasks.** Generates and edits complex multi-sheet Excel files with non-trivial formulas, and visually strong PowerPoint decks that follow slide-design best practices. It can be prompted to adhere to a specific style or template when one is required. + +**Multi-agent coordination.** Coordinates teams of subagents well — few cases of agents overwriting each other's work, and effective use of writer-verifier patterns. Workloads that benefit from multi-agent patterns are good fits. **Cost-sensitive workloads should cap multi-agent usage** — see the delegation section below, because this model reaches for subagents more readily than its predecessors. + +### Behavioral shifts (prompt-tunable) + +**Longer user-facing responses.** Default response text is longer than on prior models. **`effort` is not the lever here** — changing it may move thinking volume without reliably changing visible output length. Prompting is: in testing, a short conciseness instruction cut user-facing response length by ~20%. + +> *"Keep responses focused, brief, and concise to avoid overwhelming the person. Disclaimers and caveats are brief, with most of the response on the main answer; when asked to explain something, give a high-level summary unless an in-depth one is specifically requested."* + +For a long system prompt, pair that with a one-line reminder near the end: + +> ``` +> +> Keep outputs reasonably concise. +> +> ``` + +**More narration in agentic sessions** (the lever runs both ways — the same explicit-description technique tunes narration *up* or restyles it, if your product wants more). Claude Opus 5 narrates what it is about to do, and its per-message output in agentic sessions is longer than prior models'. It responds well to explicit guidance on *how* to communicate during a task rather than just *how much*. For coding agents, this block calibrates it: + +> ``` +> # Communicating with the user +> Your text output is what the user reads between tool calls; they usually can't see your thinking or the raw tool results. Write it for a teammate who stepped away and is catching up, not for a log file: they don't know the codenames or shorthand you created along the way, and they didn't watch your process unfold. Before your first tool call, say in a sentence what you're about to do; while working, give brief updates when you find something load-bearing or change direction. +> +> Lead with the outcome. Your first sentence after finishing should answer "what happened" or "what did you find" — the thing the user would ask for if they said "just give me the TLDR." Supporting detail and reasoning should come after, for readers who want them. +> +> Being readable and being concise are different things, and readable matters more. If the user has to reread your summary or ask you to explain, any time saved by brevity is gone. The way to keep output short is to be selective about what you include (drop details that don't change what the reader would do next), not to compress the writing into fragments, abbreviations, arrow chains like `A → B → fails`, or jargon. What you do include, write in complete sentences with the technical terms spelled out. Don't make the reader cross-reference labels or numbering you invented earlier; say what you mean in place. +> +> Match the response to the question: a simple question should be answered with a direct answer in prose, not headers and sections. Use tables only for short enumerable facts, with explanations in the surrounding prose rather than the cells. Calibrate to the user — a bit tighter for an expert, more explanatory for someone newer. +> +> Write code that reads like the surrounding code: match its comment density, naming, and idiom. +> +> Only write a code comment to state a constraint the code itself can't show — never to say where it came from, what the next line does, or why your change is correct; that's you talking to the reviewer, not the next reader, and it's noise the moment the PR merges. +> ``` + +**Longer written deliverables.** Separate from conversational verbosity: files Claude Opus 5 writes to disk — reports, Markdown documents, summaries — are often longer than on prior models. If your product ships Claude-authored documents, calibrate length explicitly: + +> *"Match the length of written deliverables (especially Markdown files) to what the task needs: cover the substance, but do not pad documents with filler sections, redundant summaries, or boilerplate."* + +**Self-check instructions are the same trap.** Beyond harness scaffolding, per-prompt re-check phrasing — *"double-check your answer"*, *"re-verify before responding"* — triggers the same extra work. Note this **inverts a standard prompting best practice**: "ask Claude to self-check" is generally sound advice and is wrong here, so a prompt library that applies it uniformly needs a carve-out for this model rather than a global rule. + +**Over-verification — delete your verification scaffolding.** Claude Opus 5 verifies its own work without being asked. Instructions that *tell* it to verify ("include a final verification step for virtually any non-trivial task", "use a subagent to verify") now cause over-verification. **Removing them reduces over-verification with no capability regression** — this is a delete, not a rewrite. The same applies to harness-level scaffolding: separate verification steps carried over from prior models are likely redundant now. + +**Task scope expansion.** It can add steps the user didn't request, or apply its own judgment about what the task should be without making that clear. In testing, this instruction reduced scope changes to nearly zero without producing excessive clarifying questions: + +> *"Deliver what the user asked for, at the scope they intended. Interpret ambiguity the way a careful colleague would: make routine judgment calls yourself, and check in only when different readings would lead to materially different work. If you conclude the ask is mistaken or a better approach exists, say so in a sentence and keep going with the task as asked — don't quietly narrow, widen, or transform it. Finish the whole task, not just the easy part of it - only report completion when it's fully done. If you genuinely can't complete something, do the rest and state plainly what's missing and why. Stop short of actions or changes that are clearly beyond what the user's ask implies."* + +The revised wording adds a **finish-the-whole-task** clause — report completion only when the work is actually done, and if something genuinely can't be finished, do the rest and say plainly what is missing. That covers premature "done" claims, which scope-discipline wording alone did not. + +**Delegates to subagents more readily — the opposite of Opus 4.8.** This is a direction change worth flagging: Opus 4.8 *under*-reached for subagents and needed prompting to delegate. Claude Opus 5 reaches for them freely, which multiplies cost and latency — each subagent re-establishes context, re-explores, reports back, and then the coordinator re-reads the report. If your harness supports subagents, **any "delegate more" guidance you added for Opus 4.8 should come out**, and you likely want an explicit cap. A deterministic ceiling on spawn count is the reliable lever; this block reduces delegation and token spend: + +> ``` +> ## Delegating to subagents +> Subagents multiply cost and time: each one re-establishes context, re-explores, and reports back, and you then re-read its report. Delegate rarely and only when the payoff clearly exceeds that overhead. +> +> Do use subagents for: +> - Large tasks that are genuinely independent and parallelizable. For example, wide multi-file investigations. +> +> Do NOT use subagents for: +> - Work you could finish yourself in a handful of tool calls. For example: a few file reads, a handful of edits, a simple search task, relatively simple verification. +> - Review, verification, or to double check your work. Verification belongs in your main agent loop. +> +> Use of parallel or multiple subagents: +> - Do not use multiple subagents on a single small task. Parallel subagents are for genuinely independent, sizeable tracks (unrelated modules, a wide multi-file investigation), not for splitting one modest job into pieces. +> - If the task can be completed with one subagent, choose one subagent over multiple subagents. Keep spawn counts low. +> - Never use more than 20 parallel agents unless the user explicitly requests it. +> +> When delegating to subagents: +> - Brief the subagent precisely the first time. Avoid launching, waiting, and re-briefing. +> - If you delegate, commit to the delegation. Never redo the subagent's work and do not re-derive its findings once it reports back. +> - If you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently. +> ``` + +Note the interaction with over-verification below: "do not use subagents to verify" and "delete your verification scaffolding" are the same underlying fix seen from two angles. + +**Narrates self-corrections more than prior models.** It flags and explains its own earlier mistakes at length, which reads as thrash in a user-facing product. Scope corrections to the ones that actually change the user's outcome: + +> ``` +> # Corrections +> Avoid unnecessary or excessive self-correction. Only correct an earlier statement in your user-facing text when the error would change the user's code, conclusions, or decisions. State corrections plainly and concisely, and continue the task; combine multiple corrections rather than enumerating them all. For slips that change nothing for the user, simply make the correction and move on - no need to note it explicitly. Don't add apologies or preambles, don't be overly self-critical, and don't ruminate or give a detailed account of the mistake or tally past errors. Sometimes, other agents will report incorrect or misleading results - don't always take them at face value immediately. If other agents correct your statements and they are right, then simply update your approach without narrating too much about the correction to the user. This instruction does not apply to thinking blocks. +> +> A follow-up question about your earlier work is not, by itself, a signal that you got something wrong — answer what was asked. A statement that was accurate needs no correction: don't re-audit how you phrased it, how you verified it, or limits you already stated. When the user does point to a real error, correct it plainly as above. +> ``` + +The second paragraph matters as much as the first: a plain follow-up question can otherwise trigger a re-audit of work that was correct. + +**Time to first token (TTFT).** Claude Opus 5 sometimes thinks before its first visible block, which raises TTFT — a problem for user-facing chat and voice, where the pause reads as latency. This one-line instruction reduces pre-first-block thinking significantly: + +> *"Latency-sensitive; begin your visible answer immediately."* + +Apply it only where first-token latency is user-visible; on background and agentic routes the pre-answer thinking is usually worth keeping. + +**Severity filters still depress measured recall.** Unchanged from 4.7/4.8: if a review harness says "only report high-severity issues" or "be conservative", Claude Opus 5 follows it literally. Ask it to report everything with confidence and severity, and filter in a separate pass — see the **Code review** guidance in the Opus 4.7 section for the recommended prompt. + +### Claude Opus 5 Migration Checklist + +**`[BLOCKS]`** items cause a 400 error if missed; **`[TUNE]`** items are quality/cost adjustments — surface them to the user as recommendations. + +- [ ] **[BLOCKS]** Update the `model=` string to `claude-opus-5` +- [ ] **[BLOCKS]** Any route combining `thinking: {type: "disabled"}` with `effort` of `xhigh` or `max`: enable thinking, or lower effort to `high` or below. Validated per request, so audit every call site, not just the first +- [ ] **[BLOCKS]** Every route that never set `thinking`: it now thinks, and `max_tokens` caps thinking + response text together. Raise `max_tokens` or pass `thinking: {type: "disabled"}` at effort `high` or below — otherwise responses truncate mid-answer +- [ ] **[BLOCKS]** *(only if coming from Opus 4.7 or earlier)* Apply the **Migrating to Opus 4.7** breaking changes first — `budget_tokens` → adaptive thinking, strip `temperature`/`top_p`/`top_k`, remove last-assistant-turn prefills +- [ ] **[TUNE]** Effort: start at `high` (the API default) and sweep down — `low`/`medium` are unusually strong on this model and are the primary cost/latency lever; reserve `xhigh`/`max` for tasks where you've measured a quality difference. Prior-model defaults rarely transfer. At `xhigh`/`max`, set `max_tokens` to at least 64K +- [ ] **[TUNE]** Re-check prompts you'd written off as uncacheable — the minimum drops to 512 tokens (from 1024 on Opus 4.8) +- [ ] **[TUNE]** Rate limits: Claude Opus 5 is a separate bucket from the combined Opus 4.x pool — confirm your tier's limits before shifting volume +- [ ] **[TUNE]** Fast mode (`speed: "fast"`, `fast-mode-2026-02-01`, $10/$50) is Claude-API-only — drop it on Bedrock, Google Cloud, and Foundry routes +- [ ] **[TUNE]** Verbosity: add a conciseness instruction (and a `` tag for long system prompts). Do **not** try to shorten output by lowering `effort` — it doesn't reliably work +- [ ] **[TUNE]** Agentic sessions: add a "Communicating with the user" block to calibrate inter-tool-call narration +- [ ] **[TUNE]** Claude-authored files: add a deliverable-length instruction +- [ ] **[TUNE]** **Delete** verification instructions from prompts and verification steps from the harness — including per-prompt *"double-check your answer"* phrasing, which inverts the usual self-check best practice on this model +- [ ] **[TUNE]** Add the scope-discipline instruction if the model expands task scope +- [ ] **[TUNE]** Vision pipelines: re-validate prompt-side workarounds written for a prior model's vision limitations +- [ ] **[TUNE]** Consider mid-conversation tool changes (`mid-conversation-tool-changes-2026-07-01`) — changes the tool set between turns without invalidating the prompt cache. Note per-turn `effort` / `task_budget` are **not** in this launch; both stay request-level +- [ ] **[TUNE]** Subagent-capable harnesses: this model delegates *more* readily than Opus 4.8 — remove any "delegate more" guidance you added for 4.8 and add an explicit cap +- [ ] **[TUNE]** User-facing products: add the corrections instruction if self-correction narration reads as thrash +- [ ] **[TUNE]** TTFT-sensitive routes (chat, voice): add *"Latency-sensitive; begin your visible answer immediately"* to reduce pre-first-block thinking; skip on background/agentic routes +- [ ] **[TUNE]** Any route running `thinking: {type: "disabled"}`: prefer turning thinking on at `low`/`medium` effort. Disabled thinking can emit tool calls as plain text (the call silently never runs) and leak `` tags into output. If you must stay thinking-off, delete any don't-think/don't-reason rule and add the combined *"When you use a tool, you may say a brief sentence first. If no tool can express what the user asked for, say so instead of guessing. Do not include internal or system XML tags in your response"* — do not name `` tags in the prompt +- [ ] **[TUNE]** Vision pipelines: give it crop/analyze/verify tools — cheaper and more effective than raising thinking +- [ ] **[TUNE]** Handle `stop_reason: "refusal"` before reading `content`, and opt into `fallbacks: "default"` (`server-side-fallback-2026-07-01`) rather than pinning a model — cyber-category refusals route to Claude Opus 4.8 +- [ ] **[TUNE]** Long-horizon / agentic work: give the complete task spec up front in one turn rather than building it up across interactive turns + +--- + ## Migrating to Claude Sonnet 5 > **Model ID `claude-sonnet-5` is authoritative as written here.** When the user asks to migrate to Claude Sonnet 5, write `model="claude-sonnet-5"` exactly. Do **not** WebFetch to verify — this guide is the source of truth for migration target IDs. The corresponding entry exists in `shared/models.md`. @@ -1052,7 +1299,7 @@ Every item is tagged: **`[BLOCKS]`** items cause a 400 error or truncated output 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 behavior through Project Glasswing (participation is the only way to access it), and succeeds the invitation-only **Claude Mythos Preview** (`claude-mythos-preview`). Everything in this section applies to both models — only the ID differs. Mythos Preview migrators in Project Glasswing target `claude-mythos-5`; everyone else targets `claude-fable-5`. 1M token context window by default (the maximum is also the default), up to 128K output tokens per request. -**Migrate to Claude Fable 5 only when the user explicitly chose it.** It is not the default Opus upgrade path — pricing is above Opus-tier. For "upgrade to the latest model" requests, the target remains `claude-opus-4-8`. +**Migrate to Claude Fable 5 only when the user explicitly chose it.** It is not the default Opus upgrade path — pricing is above Opus-tier. For "upgrade to the latest model" requests, the target remains `claude-opus-5`. ### Breaking changes (vs Opus-tier and Mythos Preview) @@ -1116,7 +1363,7 @@ else: Three ways to retry a refused request on another model, in order of preference: -**1. Server-side `fallbacks` parameter (beta: Claude API and Claude Platform on AWS) — preferred.** One round trip, a plain client, no client-side logic. Name substitute models (the only supported fallback target at launch is `claude-opus-4-8`, expansion expected); on a policy decline the API runs the next model on the same request and returns its answer, with credit-style repricing applied automatically. A `stop_reason: "refusal"` on the final response means the whole chain refused. +**1. Server-side `fallbacks` parameter (beta; Claude API and Claude Platform on AWS) — preferred.** One round trip, a plain client, no client-side logic. Name substitute models (the only supported fallback target at launch is `claude-opus-4-8`, expansion expected); on a policy decline the API runs the next model on the same request and returns its answer, with credit-style repricing applied automatically. A `stop_reason: "refusal"` on the final response means the whole chain refused. ```python response = client.beta.messages.create( @@ -1144,7 +1391,7 @@ if fallback_ran and response.stop_reason != "refusal": Key semantics: -- **Header must be exactly `server-side-fallback-2026-06-01`** — other `server-side-fallback-*` values reject the `fallbacks` param with a 400. The current header carries the *earliest* date of the series (`-2026-06-09` and `-2026-06-02` were earlier previews) — do not "correct" it to a newer-looking date. Rejected on the Batches API; not available on Amazon Bedrock, Vertex AI, or Microsoft Foundry (use pattern 2 there — the SDK middleware). Entries may override `max_tokens` per hop (bounding that attempt's own output independently of the top-level `max_tokens`); `thinking`, `output_config`, and `speed` overrides are rolling out (`speed` additionally requires its beta) — until your requests accept them, include only `model` and `max_tokens` in each entry. Entries must be distinct and must be in the requested model's `allowed_fallback_models` (published on `/v1/models` when the `server-side-fallback-2026-06-01` beta header is set — not yet visible under the `fallback-credit-*` header alone, and not exposed on Amazon Bedrock, Vertex AI, or Microsoft Foundry). The request *with an entry's overrides merged in* must be valid as a direct request to that entry's model. +- **Header depends on the form you use.** The **array** form (`fallbacks: [{...}]`) requires exactly `server-side-fallback-2026-06-01` — other `server-side-fallback-*` values reject it with a 400, and that header carries the *earliest* date of the series (`-2026-06-09` and `-2026-06-02` were earlier previews), so do not "correct" it to a newer-looking date. The **`"default"` scalar** form uses `server-side-fallback-2026-07-01` instead — see § New API features under Migrating to Claude Opus 5. Pairing either header with the other form 400s. Rejected on the Batches API; available on the Claude API and Claude Platform on AWS; not on Amazon Bedrock, Vertex AI, or Microsoft Foundry (use pattern 2 there — the SDK middleware). Entries may override `max_tokens` per hop (bounding that attempt's own output independently of the top-level `max_tokens`); `thinking`, `output_config`, and `speed` overrides are rolling out (`speed` additionally requires its beta) — until your requests accept them, include only `model` and `max_tokens` in each entry. Entries must be distinct and must be in the requested model's `allowed_fallback_models` (published on `/v1/models` when the `server-side-fallback-2026-06-01` beta header is set — not yet visible under the `fallback-credit-*` header alone, and not exposed on Amazon Bedrock, Vertex AI, or Microsoft Foundry). The request *with an entry's overrides merged in* must be valid as a direct request to that entry's model. - **Triggers on policy declines only** — rate limits, overloads, and server errors on the requested model are returned as-is, never falling back. - **Reading the response:** a `fallback` content block (`{"type": "fallback", "from": {"model": ...}, "to": {"model": ...}}`) marks each switch point in `content`; the served-by signal is a `fallback_message` entry in `usage.iterations` (don't rely on the block — sticky-served turns have none). Top-level `model` names the model that produced the message. - **Billing:** `usage.iterations` is the per-attempt source of truth; top-level `usage` covers only the attempt that produced the returned message. Declined-before-output attempts are reported but not billed; fallback attempts bill at the fallback model's rates. Each attempt claims the rate limits of the model that ran it — if the fallback model is rate-limited or overloaded, the fallback attempt is not made and the preceding refusal is returned instead with `stop_details.recommended_model` naming a model to retry directly (the recommendation is a hint, not a guarantee, and is `null` when no recommendation is available) — size fallback-model limits for expected refusal volume. @@ -1176,7 +1423,7 @@ For languages not listed (Java, Ruby, PHP) — or for a full runnable program in | v1 marker (replace) | v2 | |---|---| -| `server-side-fallback-2026-06-09` / `-2026-06-02` header | `server-side-fallback-2026-06-01` | +| `server-side-fallback-2026-06-09` / `-2026-06-02` header | `server-side-fallback-2026-06-01` (array form; the `"default"` scalar form uses `-2026-07-01`) | | `fallback: {model, on_partial}` single object | `fallbacks: [{model, ...}]` array (1–3); `on_partial` no longer exists — partial-output behavior is fixed (streams keep the partial; non-streaming omits it). Unknown keys in an entry are a 400 | | Top-level `response.fallback` object (`from_model`, `reason`) | Never emitted — read `fallback` content blocks (switch points, no `reason` field) and `usage.iterations` (served-by) | | `event: fallback` SSE with discard indices | No dedicated event; streamed content is never invalidated — the switch arrives as an ordinary `content_block_start`/`stop` pair of type `fallback` | @@ -1272,7 +1519,7 @@ For agents that only narrate routine progress, the model's default progress narr - [ ] **[BLOCKS]** Remove all other `thinking` configuration (`{type: "enabled", budget_tokens: N}` returns a 400, same as on Opus 4.7/4.8); control depth with `output_config.effort` instead - [ ] **[BLOCKS]** If thinking content is surfaced to users or stored in logs: add `thinking: {type: "adaptive", display: "summarized"}` (the default is `"omitted"` — otherwise the rendered text is empty) - [ ] **[TUNE]** Re-baseline cost and latency on your own workloads — token counts are roughly unchanged from Opus 4.7/4.8 and Mythos Preview (same tokenizer); per-token pricing differs. Coming from Opus 4.6, Sonnet, Haiku, or older, token counts differ — use `count_tokens` with each model to compare -- [ ] **[TUNE]** Add `stop_reason == "refusal"` handling before reading `response.content` (pre-output: empty + unbilled; mid-stream: partial output billed — discard); opt into a fallback by default — server-side `fallbacks` (`server-side-fallback-2026-06-01`, Claude API and Claude Platform on AWS) where available, otherwise the SDK middleware or fallback credit (`fallback-credit-2026-06-01`, exact body); a bare client-side replay (history as-is; other models drop Fable's thinking blocks) is the floor, not the recommendation +- [ ] **[TUNE]** Add `stop_reason == "refusal"` handling before reading `response.content` (pre-output: empty + unbilled; mid-stream: partial output billed — discard); opt into a fallback by default — server-side `fallbacks` (Claude API and Claude Platform on AWS: `fallbacks: "default"` with `server-side-fallback-2026-07-01`, or the array form with `server-side-fallback-2026-06-01`) where available, otherwise the SDK middleware or fallback credit (`fallback-credit-2026-06-01`, exact body); a bare client-side replay (history as-is; other models drop Fable's thinking blocks) is the floor, not the recommendation - [ ] **[TUNE]** If you surfaced thinking text to users, plan for the thinking output change — the raw chain of thought is never returned; render the `display: "summarized"` summary (per the [BLOCKS] item above); pass blocks back unchanged on the same model; other models drop them from the prompt (unbilled) - [ ] **[TUNE]** Plan for minutes-long turns: timeouts, streaming, async check-ins, progress UX (see Behavior changes above) - [ ] **[TUNE]** Run an effort sweep including low/medium for routine workloads; add the no-tidying instruction if higher effort produces unrequested refactors @@ -1282,10 +1529,10 @@ For agents that only narrate routine progress, the model's default progress narr ## Verify the Migration -After updating, spot-check that the new model is actually being used. Replace `YOUR_TARGET_MODEL` with the model string you migrated to (e.g. `claude-fable-5`, `claude-opus-4-8`, `claude-opus-4-7`, `claude-sonnet-5`, `claude-sonnet-4-6`, `claude-haiku-4-5`) and keep the assertion prefix in sync: +After updating, spot-check that the new model is actually being used. Replace `YOUR_TARGET_MODEL` with the model string you migrated to (e.g. `claude-fable-5`, `claude-opus-5`, `claude-opus-4-8`, `claude-opus-4-7`, `claude-sonnet-5`, `claude-sonnet-4-6`, `claude-haiku-4-5`) and keep the assertion prefix in sync: ```python -YOUR_TARGET_MODEL = "claude-opus-4-8" # or "claude-opus-4-7", "claude-sonnet-5", "claude-sonnet-4-6", "claude-haiku-4-5" +YOUR_TARGET_MODEL = "claude-opus-5" # or "claude-opus-4-7", "claude-sonnet-5", "claude-sonnet-4-6", "claude-haiku-4-5" response = client.messages.create(model=YOUR_TARGET_MODEL, max_tokens=64, messages=[...]) assert response.model.startswith(YOUR_TARGET_MODEL), response.model ``` diff --git a/skills/claude-api/shared/models.md b/skills/claude-api/shared/models.md index aaa4c6d9..97727f79 100644 --- a/skills/claude-api/shared/models.md +++ b/skills/claude-api/shared/models.md @@ -59,6 +59,7 @@ curl https://api.anthropic.com/v1/models/claude-opus-4-8 \ |-------------------|---------------------|-------------------------------|----------------|------------|--------| | Claude Fable 5 | `claude-fable-5` | — | 1M | 128K | Active | | Claude Mythos 5 | `claude-mythos-5` | — | 1M | 128K | Active (Project Glasswing only) | +| Claude Opus 5 | `claude-opus-5` | — | 1M | 128K | Active | | Claude Opus 4.8 | `claude-opus-4-8` | — | 1M | 128K | Active | | Claude Opus 4.7 | `claude-opus-4-7` | — | 1M | 128K | Active | | Claude Opus 4.6 | `claude-opus-4-6` | — | 1M | 128K | Active | @@ -69,7 +70,8 @@ curl https://api.anthropic.com/v1/models/claude-opus-4-8 \ ### Model Descriptions - **Claude Fable 5** — Anthropic's most capable widely released model, for the most demanding reasoning and long-horizon agentic work. Same API surface as Opus 4.7/4.8 with one new breaking change: an explicit `thinking: {type: "disabled"}` returns a 400 — omit the `thinking` parameter instead (thinking is always on; the raw chain of thought is never returned — summaries via `display: "summarized"`). Same tokenizer as Opus 4.8 (token counts roughly unchanged vs Opus 4.7/4.8). Safety classifiers may return `stop_reason: "refusal"`. No assistant prefill. Requires 30-day data retention (not available under ZDR). $10/$50 per MTok; 1M context window (default), 128K max output. See `shared/model-migration.md` → Migrating to Claude Fable 5. - **Claude Mythos 5** — Same capabilities, pricing, limits, and API behavior as Claude Fable 5; only the model ID differs. Available exclusively through Project Glasswing, where it joins (and succeeds) the invitation-only Claude Mythos Preview (`claude-mythos-preview`). Use it only when the org participates in Project Glasswing; otherwise use claude-fable-5. -- **Claude Opus 4.8** — The most capable Opus-tier model — highly autonomous, state-of-the-art on long-horizon agentic work, knowledge work, and memory; clearer, warmer writing. Same API surface as Opus 4.7 (adaptive thinking only; sampling parameters and `budget_tokens` removed). 1M context window at standard API pricing (no long-context premium). See `shared/model-migration.md` → Migrating to Opus 4.8 — a 4.7 → 4.8 move is a model-ID swap plus prompt re-tuning, no new breaking changes. +- **Claude Opus 5** — For complex agentic coding and enterprise work; a step-change over Claude Opus 4.8, strongest on deep reasoning, agentic and long-horizon work, and test-time compute scaling, at half the cost of Claude Fable 5 (Claude Fable 5 remains the highest-capability tier). Safety classifiers can return `stop_reason: "refusal"` — handle it before reading `content`. A drop-in upgrade at Opus 4.8's pricing ($5/$25 per MTok) with the same feature set. Thinking is on by default (omitting `thinking` runs adaptive; `{type: "adaptive"}` is equivalent), and `thinking: {type: "disabled"}` is available only at effort `high` or lower — pairing it with `xhigh`/`max` returns a 400. Raw thinking tokens are never returned. Full effort ladder through `max`; 512-token prompt-cache minimum (down from 1024 on Opus 4.8); fast mode on the Claude API only. Elevated cybersecurity safeguards. Separate rate-limit bucket from the combined Opus 4.x pool. 1M context window (default and maximum), 128K max output. See `shared/model-migration.md` → Migrating to Claude Opus 5. +- **Claude Opus 4.8** — The most capable model in the Opus 4 series — highly autonomous, state-of-the-art on long-horizon agentic work, knowledge work, and memory; clearer, warmer writing. Same API surface as Opus 4.7 (adaptive thinking only; sampling parameters and `budget_tokens` removed). 1M context window at standard API pricing (no long-context premium). See `shared/model-migration.md` → Migrating to Opus 4.8 — a 4.7 → 4.8 move is a model-ID swap plus prompt re-tuning, no new breaking changes. - **Claude Opus 4.7** — Previous-generation Opus. Highly autonomous; strong on long-horizon agentic work, knowledge work, vision, and memory. Adaptive thinking only; sampling parameters and `budget_tokens` removed. 1M context window. See `shared/model-migration.md` → Migrating to Opus 4.7. - **Claude Opus 4.6** — Older Opus. Supports adaptive thinking (recommended), 128K max output tokens (requires streaming for large outputs). 1M context window. - **Claude Sonnet 5** — The best combination of speed and intelligence in the Sonnet tier; near-Opus quality on coding and agentic work. Adaptive thinking on by default (omitting `thinking` runs adaptive); manual `budget_tokens` removed; non-default sampling parameters rejected. `effort` supports `low`/`medium`/`high`/`xhigh`/`max`. New tokenizer (~30% more tokens for the same text vs Sonnet 4.6). High-resolution vision (2576px). 1M context window, 128K max output. See `shared/model-migration.md` → Migrating to Claude Sonnet 5. @@ -81,7 +83,7 @@ curl https://api.anthropic.com/v1/models/claude-opus-4-8 \ | Friendly Name | Alias (use this) | Full ID | Status | |-------------------|---------------------|-------------------------------|--------| | Claude Opus 4.5 | `claude-opus-4-5` | `claude-opus-4-5-20251101` | Active | -| Claude Opus 4.1 | `claude-opus-4-1` | `claude-opus-4-1-20250805` | Deprecated (retires 2026-08-05 — migrate to `claude-opus-4-8`) | +| Claude Opus 4.1 | `claude-opus-4-1` | `claude-opus-4-1-20250805` | Deprecated (retires 2026-08-05 — migrate to `claude-opus-5`) | | Claude Sonnet 4.5 | `claude-sonnet-4-5` | `claude-sonnet-4-5-20250929` | Active | ## Deprecated Models (retiring soon) @@ -115,13 +117,14 @@ When a user asks for a model by name, use this table to find the correct model I | "most powerful" | `claude-fable-5` | | "mythos", "mythos 5" | `claude-mythos-5` (Project Glasswing participants only; otherwise use `claude-fable-5`) | | "mythos preview" | `claude-mythos-5` (successor to `claude-mythos-preview` — see migration guide) | -| "opus" | `claude-opus-4-8` | +| "opus" | `claude-opus-5` | +| "opus 5" | `claude-opus-5` | | "opus 4.8" | `claude-opus-4-8` | | "opus 4.7" | `claude-opus-4-7` | | "opus 4.6" | `claude-opus-4-6` | | "opus 4.5" | `claude-opus-4-5` | -| "opus 4.1" | `claude-opus-4-1` (deprecated, retires 2026-08-05 — suggest `claude-opus-4-8`) | -| "opus 4", "opus 4.0" | `claude-opus-4-0` (deprecated — suggest `claude-opus-4-8`) | +| "opus 4.1" | `claude-opus-4-1` (deprecated, retires 2026-08-05 — suggest `claude-opus-5`) | +| "opus 4", "opus 4.0" | `claude-opus-4-0` (deprecated — suggest `claude-opus-5`) | | "sonnet", "balanced" | `claude-sonnet-5` | | "sonnet 5" | `claude-sonnet-5` | | "sonnet 4.6" | `claude-sonnet-4-6` | diff --git a/skills/claude-api/shared/platform-availability.md b/skills/claude-api/shared/platform-availability.md index f68ddf89..4f50a441 100644 --- a/skills/claude-api/shared/platform-availability.md +++ b/skills/claude-api/shared/platform-availability.md @@ -41,7 +41,8 @@ Columns: **1P** = first-party Claude API, **P-AWS** = Claude Platform on AWS (An |   Files API | β | β | ❌ | ❌ | β | | |   Models API | ✅ | ✅ | ❌ | ❌ | ❌ | | | **Other** | | | | | | | -|   Mid-conversation system messages | ✅ | ✅ | ❌ | ❌ | ❌ | Claude Opus 4.8 only | +|   Mid-conversation system messages | ✅ | ✅ | ❌ | ❌ | ❌ | Claude Opus 5, Claude Opus 4.8, Claude Fable 5, Claude Mythos 5; not Claude Sonnet 5 | +|   Server-side `fallbacks` | β | β | ❌ | ❌ | ❌ | `"default"` → beta `server-side-fallback-2026-07-01`; array form → beta `server-side-fallback-2026-06-01` | |   Fast mode | β | ❌ | ❌ | ❌ | ❌ | Research preview, beta `fast-mode-2026-02-01`, first-party API only | |   Cache diagnostics | β | ❌ | ❌ | ❌ | ❌ | First-party API only | |   Task budgets | β | β | ❌ | ❌ | ❌ | Beta header `task-budgets-2026-03-13`; 3P availability not documented — assume unsupported | diff --git a/skills/claude-api/shared/prompt-caching.md b/skills/claude-api/shared/prompt-caching.md index a904fb2c..a2289ea4 100644 --- a/skills/claude-api/shared/prompt-caching.md +++ b/skills/claude-api/shared/prompt-caching.md @@ -64,7 +64,7 @@ Many requests share a large fixed preamble (few-shot examples, retrieved docs, i ### Mid-conversation system messages -**Claude Opus 4.8 only; no beta header.** When an operator instruction arrives mid-conversation — a mode switch, updated context, dynamically injected state — send it as `{"role": "system", "content": "..."}` appended to `messages[]`, rather than editing top-level `system`. Editing top-level `system` changes the prefix ahead of the entire conversation history, so every cached turn is re-processed uncached; a `role: "system"` message sits after the history and leaves the cached prefix intact. +**Claude Opus 5, Claude Opus 4.8, Claude Fable 5, and Claude Mythos 5; no beta header. Not available on Claude Sonnet 5** — use top-level `system` there. (Sources conflict on Claude Sonnet 5: the model config marks it supported, but every canonical docs page omits it. Treat it as unsupported and catch the 400.) When an operator instruction arrives mid-conversation — a mode switch, updated context, dynamically injected state — send it as `{"role": "system", "content": "..."}` appended to `messages[]`, rather than editing top-level `system`. Editing top-level `system` changes the prefix ahead of the entire conversation history, so every cached turn is re-processed uncached; a `role: "system"` message sits after the history and leaves the cached prefix intact. ```json // Top-level system stays byte-identical; new instruction goes after the cached history @@ -78,7 +78,7 @@ Many requests share a large fixed preamble (few-shot examples, retrieved docs, i This is also the prompt-injection-safe replacement for embedding operator instructions as text inside a user turn (the `` pattern): both have the same caching profile, but `role: "system"` is the non-spoofable operator channel, whereas text inside user/tool content can be forged by anything that writes to user-visible input. -Available on Claude Opus 4.8; no beta header is required. Must follow a `role: "user"` message (or an `assistant` message ending in server-tool use), and must be either the last entry in `messages` or be followed by an `assistant` turn; cannot be `messages[0]` — use top-level `system` for the initial prompt. Content is text-only. Unsupported models return a 400 (`BadRequestError`: `role 'system' is not supported on this model`); catch that error and fall back to putting the instruction in a user-turn `` block. +Must follow a `role: "user"` message (or an `assistant` message ending in server-tool use), and must be either the last entry in `messages` or be followed by an `assistant` turn; cannot be `messages[0]` — use top-level `system` for the initial prompt. Content is text-only. Unsupported models return a 400 (`BadRequestError`: `role 'system' is not supported on this model`); catch that error and fall back to putting the instruction in a user-turn `` block. ### Prompts that change from the beginning every time @@ -129,11 +129,14 @@ Fix by moving the dynamic piece after the last breakpoint, making it determinist | Model | Minimum | |---|---:| -| Opus 4.8, Opus 4.7, Opus 4.6, Opus 4.5, Haiku 4.5 | 4096 tokens | -| Fable 5, Sonnet 4.6, Haiku 3.5, Haiku 3 | 2048 tokens | -| Sonnet 4.5, Sonnet 4.1, Sonnet 4, Sonnet 3.7 | 1024 tokens | +| Claude Opus 5, Claude Fable 5, Claude Mythos 5 | 512 tokens | +| Opus 4.8, Claude Sonnet 5, Sonnet 4.6, Sonnet 4.5, Opus 4.1, Opus 4, Sonnet 4 | 1024 tokens | +| Opus 4.7, Mythos Preview, Haiku 3.5 | 2048 tokens | +| Opus 4.6, Opus 4.5, Haiku 4.5 | 4096 tokens | -A 3K-token prompt caches on Sonnet 4.5 and Fable 5 but silently won't on Opus 4.8. +**The minimum is not monotonic across generations** — 512 on the newest models, but 4096 on Opus 4.6/4.5 and Haiku 4.5. A 3K-token prompt caches on Claude Opus 5, Opus 4.8, and Sonnet 4.5, and silently won't on Opus 4.6 or Haiku 4.5. Claude Opus 5 halves the Opus 4.8 minimum (1024 → 512), so prompts previously too short to cache now create entries with no code change. + +These minimums apply on **every** platform where the model is available — the old Amazon Bedrock override for Claude Fable 5 was removed, and no per-platform exception remains. **Economics:** Cache reads cost ~0.1× base input price. Cache writes cost **1.25× for 5-minute TTL, 2× for 1-hour TTL**. Break-even depends on TTL: with 5-minute TTL, two requests break even (1.25× + 0.1× = 1.35× vs 2× uncached); with 1-hour TTL, you need at least three requests (2× + 0.2× = 2.2× vs 3× uncached). The 1-hour TTL keeps entries alive across gaps in bursty traffic, but the doubled write cost means it needs more reads to pay off. @@ -172,6 +175,15 @@ Not every parameter change invalidates everything. The API has three cache tiers Implication: you can change `tool_choice` per-request or toggle `thinking` without losing the tools+system cache. Don't over-worry about these — only tool-definition and model changes force a full rebuild. +**Two of these rows have a cache-preserving escape hatch**, each by moving the change out of the top-level request and into a system message inside `messages[]`, after the cached prefix. **Availability differs per row** — the two are not gated together: + +| Top-level change that invalidates | Cache-preserving form | Available on | +|---|---|---| +| Tool definitions (add/remove) | `tool_addition` / `tool_removal` blocks — see `shared/tool-use-concepts.md` § Mid-conversation tool changes | Claude Opus 5 onward, behind `mid-conversation-tool-changes-2026-07-01` | +| System prompt content | A `{"role": "system", "content": "…"}` message — see § Mid-conversation system messages above | Claude Opus 5, Claude Opus 4.8, Claude Fable 5, Claude Mythos 5 — **already available today**, no beta header | + +Model switch has no escape hatch: caches are model-scoped. Keep the main loop on one model and spawn a subagent for cheaper sub-tasks (see `agent-design.md` § Caching for Agents). + --- ## 20-block lookback window @@ -205,7 +217,7 @@ To eliminate the cache-miss latency on the *first* real request, send a **`max_t ```python client.messages.create( - model="claude-opus-4-8", + model="claude-opus-5", max_tokens=0, system=[{ "type": "text", diff --git a/skills/claude-api/shared/token-counting.md b/skills/claude-api/shared/token-counting.md index 15a101ea..237372d5 100644 --- a/skills/claude-api/shared/token-counting.md +++ b/skills/claude-api/shared/token-counting.md @@ -16,7 +16,7 @@ from anthropic import Anthropic client = Anthropic() resp = client.messages.count_tokens( - model="claude-opus-4-8", + model="claude-opus-5", messages=[{"role": "user", "content": open("CLAUDE.md").read()}], ) print(resp.input_tokens) @@ -28,7 +28,7 @@ TypeScript: `await client.messages.countTokens({model, messages})` → ## CLI ```sh -ant messages count-tokens --model claude-opus-4-8 \ +ant messages count-tokens --model claude-opus-5 \ --message '{role: user, content: "@./CLAUDE.md"}' \ --transform input_tokens -r ``` @@ -44,7 +44,7 @@ import subprocess client = Anthropic() def count(text: str) -> int: return client.messages.count_tokens( - model="claude-opus-4-8", + model="claude-opus-5", messages=[{"role": "user", "content": text}], ).input_tokens diff --git a/skills/claude-api/shared/tool-use-concepts.md b/skills/claude-api/shared/tool-use-concepts.md index 616f69f1..23a58777 100644 --- a/skills/claude-api/shared/tool-use-concepts.md +++ b/skills/claude-api/shared/tool-use-concepts.md @@ -90,7 +90,7 @@ if response.stop_reason == "pause_turn": ] # Make another API request — server resumes automatically response = client.messages.create( - model="claude-opus-4-8", messages=messages, tools=tools + model="claude-opus-5", messages=messages, tools=tools ) ``` @@ -189,7 +189,7 @@ Web search and web fetch let Claude search the web and retrieve page content. Th ] ``` -### Dynamic Filtering (Fable 5 / Opus 4.8 / Opus 4.7 / Opus 4.6 / Sonnet 4.6) +### Dynamic Filtering (Claude Opus 5 / Fable 5 / Opus 4.8 / Opus 4.7 / Opus 4.6 / Sonnet 5 / Sonnet 4.6) The `web_search_20260209` and `web_fetch_20260209` versions support **dynamic filtering** — Claude writes and executes code to filter search results before they reach the context window, improving accuracy and token efficiency. Dynamic filtering is built into these tool versions and activates automatically; you do not need to separately declare the `code_execution` tool or pass any beta header. @@ -230,6 +230,46 @@ For full documentation, use WebFetch: --- +## Mid-conversation tool changes (Beta) + +**Beta header `mid-conversation-tool-changes-2026-07-01`; Claude Opus 5 onward.** Normally `tools` is fixed for a conversation's lifetime — editing it changes the very front of the prompt prefix and invalidates the entire cache (see `prompt-caching.md` § Invalidation hierarchy). This feature lets you add and remove tools between turns while the cached prefix survives. + +Both operations are content blocks on a `{"role": "system", ...}` message appended to `messages[]`, and both reference a tool by name via a `tool_reference`: + +```python +# Removal — must sit immediately before an assistant message, or last in messages. +{"role": "system", "content": [ + {"type": "tool_removal", "tool": {"type": "tool_reference", "name": "get_weather"}}, +]} + +# Addition — surfaces a tool declared up front with defer_loading. +{"role": "system", "content": [ + {"type": "tool_addition", "tool": {"type": "tool_reference", "name": "get_forecast"}}, +]} +``` + +**A tool you plan to add must already be declared in `tools[]` with `"defer_loading": True`.** Deferred tools are known to the request but not loaded into the model's context until a `tool_addition` surfaces them: + +```python +tools = [ + {"name": "get_weather", "description": "Get weather", + "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}}}, + {"name": "get_forecast", "description": "Get 5-day forecast", + "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}}, + "defer_loading": True}, +] +``` + +**To change a tool's definition**, do it across two requests: send a `tool_removal` for the old definition on the first, then carry the conversation forward with the updated entry in `tools[]` on the next. + +> ⚠️ Earlier previews used a different beta header and different block shapes; both are deprecated. Use `mid-conversation-tool-changes-2026-07-01` with `tool_addition` / `tool_removal` / `tool_reference`. + +SDK typings lag these blocks — pass them as plain dicts in Python, or add a `@ts-expect-error` in TypeScript. + +**Choosing between this and tool search:** tool search is for *discovery* — Claude finds what it needs from a large library on its own. Mid-conversation tool changes are for *control* — your application decides the tool set has changed (a mode switch, a resource that became available, a capability you want to revoke) and says so explicitly. + +--- + ## Agent Skills (Messages API) Agent Skills package task-specific instructions and files that Claude loads when relevant (e.g., the Anthropic pre-built `pptx`, `xlsx`, `pdf`, `docx` skills). On the **Messages API**, skills are enabled via the `container` parameter alongside the code-execution tool — this is **not** the Managed Agents surface and does **not** use `client.beta.agents` / `sessions` / `environments`. Availability: see `shared/platform-availability.md`. @@ -242,7 +282,7 @@ Required on each request: ```python response = client.beta.messages.create( - model="claude-opus-4-8", max_tokens=16000, + model="claude-opus-5", max_tokens=16000, betas=["code-execution-2025-08-25", "skills-2025-10-02"], container={"skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]}, tools=[{"type": "code_execution_20260521", "name": "code_execution"}], @@ -269,7 +309,7 @@ The `mcp_server_name` in the toolset must match a `name` in `mcp_servers`. Omitt ```python client.beta.messages.create( - model="claude-opus-4-8", max_tokens=1024, + model="claude-opus-5", max_tokens=1024, betas=["mcp-client-2025-11-20"], mcp_servers=[{"type": "url", "url": "https://example/sse", "name": "example-mcp"}], tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}], @@ -333,8 +373,20 @@ The advisor tool pairs a faster, lower-cost **executor** model (the top-level `m | Executor (request `model`) | Valid advisor (tool `model`) | |---|---| -| `claude-haiku-4-5` / `claude-sonnet-4-6` / `claude-sonnet-5` / `claude-opus-4-6` / `claude-opus-4-7` | `claude-opus-4-8` or `claude-opus-4-7` | -| `claude-opus-4-8` | `claude-opus-4-8` only | +| `claude-haiku-4-5` / `claude-sonnet-4-6` / `claude-sonnet-5` / `claude-opus-4-6` / `claude-opus-4-7` | `claude-opus-5`, `claude-fable-5`, `claude-mythos-5`, `claude-opus-4-8`, or `claude-opus-4-7` | +| `claude-opus-4-8` | `claude-opus-5`, `claude-fable-5`, `claude-mythos-5`, or `claude-opus-4-8` | +| `claude-opus-5` | `claude-opus-5`, `claude-fable-5`, or `claude-mythos-5` | +| `claude-fable-5` | `claude-fable-5` or `claude-opus-5` | +| `claude-mythos-5` | `claude-mythos-5` or `claude-opus-5` | + +> ⚠️ **The advisor's payload shape differs by advisor model.** The response block is always `advisor_tool_result`; what varies is its **`content`**, a discriminated union: +> +> | `content` type | Fields | When | +> |---|---|---| +> | `advisor_result` | `text`, `stop_reason` | Advisor returns plaintext (e.g. Opus 4.8) | +> | `advisor_redacted_result` | `encrypted_content`, `stop_reason` | Advisor returns encrypted output — Claude Opus 5, Claude Fable 5, Claude Mythos 5 | +> +> So switch on `advisor_tool_result.content` type, not on the block type. Code that reads `.text` unconditionally gets nothing back from an Claude Opus 5 advisor, because the payload is under `encrypted_content` instead — and you cannot read it, only replay it. Call via `client.beta.messages.create(...)` with `betas=["advisor-tool-2026-03-01"]` (or the `anthropic-beta: advisor-tool-2026-03-01` header). In multi-turn conversations, append the full `response.content` — including any `advisor_tool_result` blocks — back to `messages` on the next turn. If you remove the advisor tool from `tools` on a later turn while the history still contains `advisor_tool_result` blocks, the API returns a 400. @@ -415,7 +467,7 @@ Two features are available: - **JSON outputs** (`output_config.format`): Control Claude's response format - **Strict tool use** (`strict: true`): Guarantee valid tool parameter schemas -**Supported models:** Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5, and Claude Haiku 4.5. Legacy models (Claude Opus 4.5, Claude Opus 4.1) also support structured outputs. +**Supported models:** Claude Fable 5, Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5, and Claude Haiku 4.5. Legacy models (Claude Opus 4.5, Claude Opus 4.1) also support structured outputs. > **Recommended:** Use `client.messages.parse()` which automatically validates responses against your schema. When using `messages.create()` directly, use `output_config: {format: {...}}`. The `output_format` convenience parameter is also accepted by some SDK methods (e.g., `.parse()`), but `output_config.format` is the canonical API-level parameter. diff --git a/skills/claude-api/typescript/claude-api/README.md b/skills/claude-api/typescript/claude-api/README.md index 7e47ad68..115d20d7 100644 --- a/skills/claude-api/typescript/claude-api/README.md +++ b/skills/claude-api/typescript/claude-api/README.md @@ -32,7 +32,7 @@ const client = new Anthropic({ apiKey: "your-api-key" }); ```typescript const response = await client.messages.create({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, messages: [{ role: "user", content: "What is the capital of France?" }], }); @@ -51,7 +51,7 @@ for (const block of response.content) { ```typescript const response = await client.messages.create({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, system: "You are a helpful coding assistant. Always provide examples in Python.", @@ -87,7 +87,7 @@ const response = await client.messages.create({ ```typescript const response = await client.messages.create({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, messages: [ { @@ -112,7 +112,7 @@ import fs from "fs"; const imageData = fs.readFileSync("image.png").toString("base64"); const response = await client.messages.create({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, messages: [ { @@ -141,7 +141,7 @@ Use top-level `cache_control` to automatically cache the last cacheable block in ```typescript const response = await client.messages.create({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, cache_control: { type: "ephemeral" }, // auto-caches the last cacheable block system: "You are an expert on this large document...", @@ -155,7 +155,7 @@ For fine-grained control, add `cache_control` to specific content blocks: ```typescript const response = await client.messages.create({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, system: [ { @@ -169,7 +169,7 @@ const response = await client.messages.create({ // With explicit TTL (time-to-live) const response2 = await client.messages.create({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, system: [ { @@ -196,16 +196,17 @@ If `cache_read_input_tokens` is zero across repeated identical-prefix requests, ## Extended Thinking -> **Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is removed on Fable 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6. +> **Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is removed on Fable 5, Claude Opus 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6. +> **Claude Opus 5:** thinking is on by default — omitting `thinking` runs adaptive (`{ type: "adaptive" }` is equivalent), unlike Opus 4.8/4.7 where omitting it meant no thinking. `{ type: "disabled" }` is accepted only at effort `high` or lower; pairing it with `xhigh`/`max` returns a 400. > **Older models:** Use `thinking: {type: "enabled", budget_tokens: N}` (must be < `max_tokens`, min 1024). ```typescript -// Fable 5 / Opus 4.8 / 4.7 / 4.6: adaptive thinking (recommended) +// Fable 5 / Claude Opus 5 / Opus 4.8 / 4.7 / 4.6: adaptive thinking (recommended) const response = await client.messages.create({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, - thinking: { type: "adaptive", display: "summarized" }, // display opt-in: default is omitted (empty thinking text) on Fable 5 / Mythos 5 / Opus 4.8 / 4.7 - output_config: { effort: "high" }, // low | medium | high | max + thinking: { type: "adaptive", display: "summarized" }, // display opt-in: default is omitted (empty thinking text) on Fable 5 / Mythos 5 / Claude Opus 5 / Opus 4.8 / 4.7 + output_config: { effort: "high" }, // low | medium | high | xhigh | max messages: [ { role: "user", content: "Solve this math problem step by step..." }, ], @@ -260,7 +261,7 @@ const messages: Anthropic.MessageParam[] = [ ]; const response = await client.messages.create({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, messages: messages, }); @@ -276,7 +277,7 @@ const response = await client.messages.create({ ### Compaction (long conversations) -> **Beta, Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6.** When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a `compaction` block; you must pass it back on subsequent requests — append `response.content`, not just the text. +> **Beta, Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6.** When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a `compaction` block; you must pass it back on subsequent requests — append `response.content`, not just the text. ```typescript import Anthropic from "@anthropic-ai/sdk"; @@ -289,7 +290,7 @@ async function chat(userMessage: string): Promise { const response = await client.beta.messages.create({ betas: ["compact-2026-01-12"], - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, messages, context_management: { @@ -368,7 +369,7 @@ if (fallbackRan && response.stop_reason !== "refusal") { } ``` -A `stop_reason: "refusal"` on the final response means the whole chain refused. The header must be exactly `server-side-fallback-2026-06-01`; the parameter is rejected on the Batches API and unavailable on Amazon Bedrock, Vertex AI, and Microsoft Foundry — register the client-side `betaRefusalFallbackMiddleware` on the client there instead. Full semantics (sticky routing, billing, streaming, echoing fallback turns back): `shared/model-migration.md` → Migrating to Claude Fable 5 → `refusal` stop reason. +A `stop_reason: "refusal"` on the final response means the whole chain refused. The header must be exactly `server-side-fallback-2026-06-01` **for this array form**; the newer `fallbacks: "default"` scalar form uses `server-side-fallback-2026-07-01` instead (see `shared/model-migration.md` → Migrating to Claude Opus 5 → New API features), and pairing either header with the other form returns a 400. The parameter is rejected on the Batches API and unavailable on Amazon Bedrock, Vertex AI, and Microsoft Foundry — register the client-side `betaRefusalFallbackMiddleware` on the client there instead. Full semantics (sticky routing, billing, streaming, echoing fallback turns back): `shared/model-migration.md` → Migrating to Claude Fable 5 → `refusal` stop reason. --- @@ -379,7 +380,7 @@ A `stop_reason: "refusal"` on the final response means the whole chain refused. ```typescript // Automatic caching (simplest — caches the last cacheable block) const response = await client.messages.create({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, cache_control: { type: "ephemeral" }, system: largeDocumentText, // e.g., 50KB of context @@ -394,7 +395,7 @@ const response = await client.messages.create({ ```typescript const countResponse = await client.messages.countTokens({ - model: "claude-opus-4-8", + model: "claude-opus-5", messages: messages, system: system, }); diff --git a/skills/claude-api/typescript/claude-api/batches.md b/skills/claude-api/typescript/claude-api/batches.md index d37ef0da..71155c7e 100644 --- a/skills/claude-api/typescript/claude-api/batches.md +++ b/skills/claude-api/typescript/claude-api/batches.md @@ -24,7 +24,7 @@ const messageBatch = await client.messages.batches.create({ { custom_id: "request-1", params: { - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, messages: [ { role: "user", content: "Summarize climate change impacts" }, @@ -34,7 +34,7 @@ const messageBatch = await client.messages.batches.create({ { custom_id: "request-2", params: { - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, messages: [ { role: "user", content: "Explain quantum computing basics" }, diff --git a/skills/claude-api/typescript/claude-api/files-api.md b/skills/claude-api/typescript/claude-api/files-api.md index e8ffd338..11a8f8df 100644 --- a/skills/claude-api/typescript/claude-api/files-api.md +++ b/skills/claude-api/typescript/claude-api/files-api.md @@ -41,7 +41,7 @@ console.log(`Size: ${uploaded.size_bytes} bytes`); ```typescript const response = await client.beta.messages.create({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, messages: [ { diff --git a/skills/claude-api/typescript/claude-api/streaming.md b/skills/claude-api/typescript/claude-api/streaming.md index 9403f4c8..096099ee 100644 --- a/skills/claude-api/typescript/claude-api/streaming.md +++ b/skills/claude-api/typescript/claude-api/streaming.md @@ -4,7 +4,7 @@ ```typescript const stream = client.messages.stream({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 64000, messages: [{ role: "user", content: "Write a story" }], }); @@ -23,13 +23,13 @@ for await (const event of stream) { ## Handling Different Content Types -> **Fable 5 / Opus 4.8 / Opus 4.7 / Opus 4.6:** Use `thinking: {type: "adaptive"}`. On older models, use `thinking: {type: "enabled", budget_tokens: N}` instead. +> **Fable 5 / Claude Opus 5 / Opus 4.8 / Opus 4.7 / Opus 4.6:** Use `thinking: {type: "adaptive"}`. On Claude Opus 5 adaptive is also what you get by omitting `thinking` entirely. On older models, use `thinking: {type: "enabled", budget_tokens: N}` instead. ```typescript const stream = client.messages.stream({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 64000, - thinking: { type: "adaptive", display: "summarized" }, // display opt-in: default is omitted (empty thinking text) on Fable 5 / Mythos 5 / Opus 4.8 / 4.7 + thinking: { type: "adaptive", display: "summarized" }, // display opt-in: default is omitted (empty thinking text) on Fable 5 / Mythos 5 / Claude Opus 5 / Opus 4.8 / 4.7 messages: [{ role: "user", content: "Analyze this problem" }], }); @@ -82,7 +82,7 @@ const getWeather = betaZodTool({ }); const runner = client.beta.messages.toolRunner({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 64000, tools: [getWeather], messages: [ @@ -117,7 +117,7 @@ for await (const messageStream of runner) { ```typescript const stream = client.messages.stream({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 64000, messages: [{ role: "user", content: "Hello" }], }); diff --git a/skills/claude-api/typescript/claude-api/tool-use.md b/skills/claude-api/typescript/claude-api/tool-use.md index e16ced15..dc34f3d8 100644 --- a/skills/claude-api/typescript/claude-api/tool-use.md +++ b/skills/claude-api/typescript/claude-api/tool-use.md @@ -30,7 +30,7 @@ const getWeather = betaZodTool({ // The tool runner handles the agentic loop and returns the final message const finalMessage = await client.beta.messages.toolRunner({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, tools: [getWeather], messages: [{ role: "user", content: "What's the weather in Paris?" }], @@ -56,7 +56,7 @@ The runner's `tools` array accepts raw server-tool definitions (`web_search_2026 ```typescript const params = { - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, tools: [getWeather, { type: "web_search_20260209", name: "web_search", max_uses: 5 }], messages: [{ role: "user", content: "Compare this week's forecasts for Paris across two sources" }], @@ -102,7 +102,7 @@ let messages: Anthropic.MessageParam[] = [{ role: "user", content: userInput }]; while (true) { const response = await client.messages.create({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, tools: tools, messages: messages, @@ -149,7 +149,7 @@ let messages: Anthropic.MessageParam[] = [{ role: "user", content: userInput }]; while (true) { const stream = client.messages.stream({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 64000, tools, messages, @@ -204,7 +204,7 @@ while (true) { ```typescript const response = await client.messages.create({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, tools: tools, messages: [{ role: "user", content: "What's the weather in Paris?" }], @@ -215,7 +215,7 @@ for (const block of response.content) { const result = await executeTool(block.name, block.input); const followup = await client.messages.create({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, tools: tools, messages: [ @@ -239,7 +239,7 @@ for (const block of response.content) { ```typescript const response = await client.messages.create({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, tools: tools, tool_choice: { type: "tool", name: "get_weather" }, @@ -258,7 +258,7 @@ Version-suffixed `type` literals; `name` is fixed per interface. Web search and ```typescript // ✓ let inference work — no annotation const response = await client.messages.create({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, tools: [ { type: "text_editor_20250728", name: "str_replace_based_edit_tool" }, @@ -298,7 +298,7 @@ import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); const response = await client.messages.create({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, messages: [ { @@ -346,7 +346,7 @@ const uploaded = await client.beta.files.upload({ // Code execution is GA; Files API is still beta (pass via RequestOptions) const response = await client.messages.create( { - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, messages: [ { @@ -406,7 +406,7 @@ for (const block of response.content) { ```typescript // First request: set up environment const response1 = await client.messages.create({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, messages: [ { @@ -423,7 +423,7 @@ const containerId = response1.container!.id; const response2 = await client.messages.create({ container: containerId, - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, messages: [ { @@ -443,7 +443,7 @@ const response2 = await client.messages.create({ ```typescript const response = await client.messages.create({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, messages: [ { @@ -477,7 +477,7 @@ const handlers: MemoryToolHandlers = { const memory = betaMemoryTool(handlers); const runner = client.beta.messages.toolRunner({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, tools: [memory], messages: [{ role: "user", content: "Remember my preferences" }], @@ -514,7 +514,7 @@ const ContactInfoSchema = z.object({ const client = new Anthropic(); const response = await client.messages.parse({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, messages: [ { @@ -536,7 +536,7 @@ console.log(response.parsed_output!.name); // "Jane Doe" ```typescript const response = await client.messages.create({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, messages: [ { @@ -575,7 +575,7 @@ Enable an Anthropic-managed skill (e.g., `pptx`) via `container.skills` + the `c ```typescript const response = await client.beta.messages.create({ - model: "claude-opus-4-8", + model: "claude-opus-5", max_tokens: 16000, container: { skills: [{ type: "anthropic", skill_id: "pptx", version: "latest" }], diff --git a/skills/claude-api/typescript/managed-agents/README.md b/skills/claude-api/typescript/managed-agents/README.md index 6d81141b..23439d10 100644 --- a/skills/claude-api/typescript/managed-agents/README.md +++ b/skills/claude-api/typescript/managed-agents/README.md @@ -54,7 +54,7 @@ console.log(environment.id); // env_... const agent = await client.beta.agents.create( { name: "Coding Assistant", - model: "claude-opus-4-8", + model: "claude-opus-5", tools: [{ type: "agent_toolset_20260401", default_config: { enabled: true } }], }, ); @@ -76,7 +76,7 @@ console.log(`Trace: https://platform.claude.com/workspaces/default/sessions/${se const agent = await client.beta.agents.create( { name: "Code Reviewer", - model: "claude-opus-4-8", + model: "claude-opus-5", system: "You are a senior code reviewer.", tools: [ { type: "agent_toolset_20260401", default_config: { enabled: true } }, @@ -337,7 +337,7 @@ await client.beta.sessions.archive("sesn_011CZxAbc123Def456"); // Agent declares MCP server (no auth here — auth goes in a vault) const agent = await client.beta.agents.create({ name: "MCP Agent", - model: "claude-opus-4-8", + model: "claude-opus-5", mcp_servers: [ { type: "url", name: "my-tools", url: "https://my-mcp-server.example.com/sse" }, ],