mirror of
https://github.com/anthropics/skills.git
synced 2026-08-02 13:05:28 +08:00
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.
This commit is contained in:
Lance Martin
@@ -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."}
|
||||
|
||||
@@ -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`.
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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" |
|
||||
|
||||
@@ -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: "<level>"}`, 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: "<level>"}`, 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
|
||||
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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="/"):
|
||||
|
||||
@@ -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={
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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**.
|
||||
|
||||
@@ -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"},
|
||||
|
||||
@@ -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. `<thinking>` tags can leak into the visible response.** The model may emit `<thinking>` 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 `<thinking>` 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:
|
||||
|
||||
> ```
|
||||
> <tone_preference>
|
||||
> Keep outputs reasonably concise.
|
||||
> </tone_preference>
|
||||
> ```
|
||||
|
||||
**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 `<tone_preference>` 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 `<thinking>` 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 `<thinking>` 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
|
||||
```
|
||||
|
||||
@@ -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` |
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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 `<system-reminder>` 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 `<system-reminder>` 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 `<system-reminder>` 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",
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user