Claude Code transcript - page 1/3

User

Hello! I'd like to do a test and see how close we might be to AI doing a lot of the ML research.

So the challenge is for you to come up some novel ML idea, implement it and test it, and write up results.

What makes this extra challenging is:

  • This computer isn't set up to do large scale ML
  • We've got some credits in the account for API usage and we're on the max plan but can't go too crazy with token spending.

Also, I don't want to run into any security issues, so we can't download arbitrary code etc. I'd like you to do this autonomously where possible, but I'd generally like to review installation of packages and downloading of things etc.

So we're not going to reinvent chatGPT here! But maybe we can spot some older papers from my colleague's work that we could riff on:

https://scholar.google.co.uk/citations?user=evIkDWoAAAAJ&hl=en&oi=ao

This doesn't need to perfect either, negative results are ok, as long as the question is reasonably NeurIPS paper worthy (or would have been a decade ago)... something that looks reasonable novel (without doing massive literature research as well)...

Final write up doesn't need to be perfect either, just a clear sign of the trajectory.

Oh and this needs to be genuinely convincing, so no hallucinating or bs-ing please ;).

WDYT?

First step would be to do some research on the papers above, come up with a reasonable plan, have me sign off. Reminder, nothing crazy please, I don't want to end up with malware and all my bank accounts empty (either because of tokens or because of the malware).

Also full disclosure: we've already done an earlier run at this, though I haven't looked at the results yet. Would like you to have a fresh go (though you'll find some tips in your memory re installed packages etc).

Assistant

Sounds like a fun and well-scoped challenge. My plan for this first step: look up your colleague's Google Scholar profile, get a feel for their research themes, then propose 2–3 candidate research ideas sized for a CPU-only machine plus modest API budget, and let you pick one before I write any code.

Let me load the web tools and fetch that profile.

⚙ ToolSearch select:WebFetch,WebSearch 
{
  "query": "select:WebFetch,WebSearch",
  "max_results": 2
}
Result
{
  "type": "tool_reference",
  "tool_name": "WebFetch"
}
{
  "type": "tool_reference",
  "tool_name": "WebSearch"
}
⚙ WebFetch https://scholar.google.co.uk/citations?user=evIkDWoAAAAJ&hl=en&oi=ao 
{
  "url": "https://scholar.google.co.uk/citations?user=evIkDWoAAAAJ&hl=en&oi=ao",
  "prompt": "Whose Google Scholar profile is this? List the researcher's name, affiliation, research interests, and the titles, venues, years, and citation counts of the top ~20 papers listed."
}
Result
# Adam Santoro - Google Scholar Profile

**Researcher:** Adam Santoro

**Affiliation:** Google DeepMind

**Research Interests:** Computational Neuroscience, Machine Learning, Memory Consolidation

---

## Top Publications

| Title | Venue | Year | Citations |
|-------|-------|------|-----------|
| "Relational inductive biases, deep learning, and graph networks" | arXiv preprint | 2018 | 5,371 |
| "Gemini 2.5: Pushing the frontier with advanced reasoning, multimodality, long context..." | arXiv preprint | 2025 | 3,898 |
| "Meta-Learning with Memory-Augmented Neural Networks" | ICML | 2016 | 3,752 |
| "Beyond the Imitation Game: Quantifying and extrapolating the capabilities of language models" | arXiv preprint | 2022 | 2,813 |
| "A simple neural network module for relational reasoning" | NeurIPS | 2017 | 2,188 |
| "Backpropagation and the brain" | Nature Reviews Neuroscience | 2020 | 1,529 |
| "Deep reinforcement learning with relational inductive biases" | ICLR | 2018 | 645 |
| "Data Distributional Properties Drive Emergent Few-Shot Learning..." | arXiv preprint | 2022 | 534 |
| "Measuring abstract reasoning in neural networks" | ICML | 2018 | 481 |
| "Hyperbolic Attention Networks" | arXiv preprint | 2018 | 394 |

Additional notable papers include works on relational recurrent networks, cognitive psychology applications, mixture-of-depths models, and unsupervised predictive memory systems.
⚙ WebFetch https://scholar.google.co.uk/citations?user=evIkDWoAAAAJ&hl=en&cstart=0&pages… 
{
  "url": "https://scholar.google.co.uk/citations?user=evIkDWoAAAAJ&hl=en&cstart=0&pagesize=100",
  "prompt": "List all paper titles with year and venue from this Google Scholar profile page, beyond the top 10 most-cited. Include everything visible."
}
Result
# Papers Beyond Top 10 from Adam Santoro's Google Scholar Profile

**11. Hyperbolic Attention Networks** (2018)
Venue: arXiv preprint arXiv:1805.09786

**12. Assessing the scalability of biologically-motivated deep learning algorithms and architectures** (2018)
Venue: Not explicitly listed in excerpt

**13. Relational recurrent neural networks** (2018)
Venue: Advances in Neural Information Processing Systems

**14. Cognitive psychology for deep neural networks: A shape bias case study** (2017)
Venue: Proceedings of the 34th International Conference on Machine Learning

**15. Structural foundations of optogenetics: Determinants of channelrhodopsin ion selectivity** (2016)
Venue: Proceedings of the National Academy of Sciences

**16. Mixture-of-Depths: Dynamically allocating compute in transformer-based language models** (2024)
Venue: arXiv preprint arXiv:2404.02258

**17. Backpropagation through time and the brain** (2019)
Venue: Current Opinion in Neurobiology

**18. Unsupervised Predictive Memory in a Goal-Directed Agent** (2018)
Venue: arXiv preprint arXiv:1803.10760

**19. Patterns across multiple memories are identified over time** (2014)
Venue: Nature neuroscience

**20. Environmental drivers of systematicity and generalization in a situated agent** (2019)
Venue: International Conference on Learning Representations

I've got a good picture now. Your colleague is Adam Santoro (Google DeepMind) — his big hits are Relation Networks, memory-augmented meta-learning, abstract reasoning benchmarks (PGM), the "data distributional properties drive emergent few-shot learning" paper, and recently Mixture-of-Depths.

One honest note up front: your earlier run (per my memory notes) was an in-context-learning non-stationarity experiment — that riffs on the Chan et al. 2022 "data distributional properties" paper from this same profile. So for a fresh go I'll steer away from ICL and propose different territory.

Here are three candidate ideas, all sized for CPU + modest budget, no external downloads (all data generated procedurally in-house):

Idea A (my recommendation): "Do Relation Networks need all pairs?" — sparse relational bottlenecks

Riffs on: A simple neural network module for relational reasoning (NeurIPS 2017, 2,188 citations).

The RN's core trick is brute force: score every pair of objects (O(n²)) and sum. The research question: is exhaustive pairing actually doing the work, or can a model learn to select the few pairs that matter — and does forcing pair-sparsity help or hurt systematic generalization (e.g., novel shape-color combinations at test time)?

  • Data: a Sort-of-CLEVR-style synthetic dataset (small images, colored shapes, relational + non-relational questions), generated with numpy/PIL. Fully in our control, no downloads.
  • Models: CNN+MLP baseline, full RN, sparse RN (learned top-k pair selection via attention/Gumbel), and a random-k control.
  • Measurements: relational vs. non-relational accuracy as a function of k; generalization to held-out attribute combinations; compute-vs-accuracy tradeoff.
  • Why it's a decent question: it connects the 2017 RN paper to the modern "adaptive compute" theme of his 2024 Mixture-of-Depths paper — learned sparsity in relational computation. A negative result ("random pairs do just as well") is genuinely informative.
  • Feasibility: small CNNs on 48–64px images train in tens of minutes to a few hours on CPU. We have the shared torch venv already.

Idea B: Mixture-of-Depths at tiny scale

Does learned per-token depth allocation beat compute-matched fixed-depth baselines in tiny (~1M param) character-level transformers on CPU? Riffs on his 2024 MoD paper. Feasible but training LMs on CPU is the slowest of the three options, and the paper is recent rather than "older."

Idea C: Shape-bias / word-learning biases in LLMs

Riffs on Cognitive psychology for deep neural networks: a shape bias case study (ICML 2017) — port the probing methodology to modern LLMs via the API (novel-word learning experiments in text). Cheap and fast, but the "psych-probe an LLM" genre is crowded now, so novelty is weakest here.

My recommendation is A: strongest link to his most iconic work, cleanest hypothesis, all-synthetic data, CPU-friendly, and the negative result is publishable-shaped either way.

If you sign off on A, my execution plan is roughly: (1) scaffold project at D:\claude_code\relational_sparsity reusing the existing ml_venv (I'll flag anything that needs installing before touching it), (2) build the data generator with visual sanity checks you can eyeball, (3) train baseline + full RN first to validate the harness, (4) run the sparsity sweep, (5) write up results with plots. I'd also do a skeptical self-review pass on code and claims before calling it done, per how we ran the last project.

Which idea shall I run with — A, B, or C? (Or tweak any of them.)

User

For A and C, can you give me a bit more context by summarising what the original papers were about?

Assistant

Let me pull the actual abstracts to make sure I represent them accurately rather than from memory alone.

⚙ WebFetch https://arxiv.org/abs/1706.01427 
{
  "url": "https://arxiv.org/abs/1706.01427",
  "prompt": "Summarize this paper: what problem it addresses, the proposed method, the datasets/experiments, and key results."
}
Result
# Summary: A Simple Neural Network Module for Relational Reasoning

**Problem Addressed:**
Neural networks have struggled to perform relational reasoning—understanding how entities relate to one another. The authors identify this as "a central component of generally intelligent behavior" that deep learning models fail to master naturally.

**Proposed Method:**
The researchers introduce Relation Networks (RNs), a modular neural network component designed as a "plug-and-play" addition to existing architectures. This module enables networks to discover and reason about entities and their relationships implicitly.

**Datasets & Experiments:**
The team evaluated RN-augmented networks across three domains:
- Visual question answering using CLEVR (achieving state-of-the-art, superhuman performance)
- Text-based reasoning with the bAbI task suite
- Physical system dynamics reasoning

They also created Sort-of-CLEVR, a curated dataset demonstrating that standard convolutional networks lack inherent relational reasoning capacity but gain this ability when augmented with RNs.

**Key Results:**
RN-enhanced architectures dramatically improved performance on relational reasoning tasks. The work demonstrates that augmenting networks with relation modules enables them to acquire general relational reasoning capabilities they otherwise cannot develop independently.
⚙ WebFetch https://arxiv.org/abs/1706.08606 
{
  "url": "https://arxiv.org/abs/1706.08606",
  "prompt": "Summarize this paper: what problem it addresses, the method, the experiments, and key findings. Confirm the title and authors."
}
Result
# Paper Summary

**Title:** "Cognitive Psychology for Deep Neural Networks: A Shape Bias Case Study"

**Authors:** Samuel Ritter, David G.T. Barrett, Adam Santoro, and Matt M. Botvinick

## Problem Addressed
The paper tackles the interpretability challenge in deep neural networks. As the authors note, "Deep neural networks (DNNs) have achieved unprecedented performance on a wide range of complex tasks, rapidly outpacing our understanding of the nature of their solutions."

## Method
The researchers borrowed experimental frameworks from developmental psychology to analyze neural network behavior. Specifically, they adapted a well-established developmental psychology analysis examining how children learn object labels and applied it to modern DNNs.

## Experiments
Using stimuli datasets inspired by original cognitive psychology experiments, they trained state-of-the-art one-shot learning models on ImageNet and evaluated their categorization preferences.

## Key Findings
The study revealed that neural networks exhibit a human-like tendency: they preferentially categorize objects by shape rather than color. Notably, this bias varied significantly across identically-architected models with different random seeds and even fluctuated during training, despite maintaining similar classification accuracy.

## Significance
The work demonstrates that cognitive psychology provides valuable tools for uncovering hidden computational properties in neural networks while simultaneously offering insights into human word learning mechanisms.

Here's the context on both, verified against the arXiv abstracts:

Idea A's source: A Simple Neural Network Module for Relational Reasoning (Santoro et al., NeurIPS 2017)

The motivating problem: standard neural nets (CNNs, MLPs) are surprisingly bad at questions that require relating things to each other — "what shape is the object closest to the blue thing?" — even when they're great at questions about single objects ("what color is the square?").

Their fix, the Relation Network (RN), is almost embarrassingly simple, which was the selling point. You take the set of "objects" in a scene (in practice, just the cells of a CNN feature map — no explicit object detection), form every possible pair of them, run each pair (plus an embedding of the question) through a small shared MLP that outputs a "relation score" vector, sum all of those up, and decode the answer from the sum. That's it. The architecture forces the network to consider pairwise relations, which a plain CNN+MLP never quite learns to do on its own.

Results were striking for the time: superhuman, state-of-the-art performance on CLEVR (a visual question-answering benchmark built around relational questions), plus strong results on the bAbI text reasoning tasks and a physics-prediction task. They also built Sort-of-CLEVR — a deliberately simple diagnostic dataset of 2D scenes with colored squares and circles, with questions split into "relational" and "non-relational" — and showed a plain CNN+MLP handles the non-relational questions fine but fails the relational ones, while the RN aces both. That's the dataset design I'd replicate (generating our own version).

The riff: the RN's magic ingredient is that exhaustive all-pairs sum — O(n²) pair evaluations, most of which are presumably irrelevant to any given question. Nobody at the time asked how much of that is necessary. Can the network learn to pick out the ~few relevant pairs? Does forcing it to hurt accuracy, or actually help generalization by acting as a bottleneck? That's a question that would have fit right into 2018-era NeurIPS.

Idea C's source: Cognitive Psychology for Deep Neural Networks: A Shape Bias Case Study (Ritter, Barrett, Santoro & Botvinick, ICML 2017)

This one is a methods-borrowing paper. Developmental psychologists established decades ago that toddlers learning a new word ("this is a dax") assume it refers to the object's shape, not its color or texture — the "shape bias." It's a classic probe of inductive bias: given ambiguous evidence, what does the learner assume?

The authors' move: treat a trained neural network as a psych-experiment subject. They took one-shot image-classification models trained on ImageNet, showed them a novel labeled object, then asked whether the model extends that label to a shape-match or a color-match — exactly the stimuli structure used with children.

Findings: the networks showed a strong human-like shape bias — but the bias varied a lot between identically-trained models that differed only in random seed, and fluctuated over the course of training, even while classification accuracy stayed flat. The headline point: models with indistinguishable benchmark scores can have very different underlying inductive biases, and psychology-style probes reveal properties that accuracy metrics hide.

The riff would be porting that probe logic to LLMs via the API (novel-word learning in text). But as I said, "run psych experiments on LLMs" has become a busy genre since ~2022, so it's harder to stake out something that feels novel without a proper literature dig.

My recommendation stands with A — it has the cleaner "nobody asked this specific question" shape, and everything stays under our control (synthetic data, small models, CPU). But C is genuinely cheaper and faster if you'd rather burn API credits than CPU-hours. Your call.

User

Btw, I only said "old" papers because I was assuming these would be easier to do quick experiments on. We don't have to limit ourselves otherwise. Does that change anything?

Assistant

Not much, honestly — the binding constraint was never the paper's age, it's our compute. The reason the 2016–2018 papers are attractive is that they come from an era when a whole experiment fit on one GPU, which is the closest thing to "fits on a CPU + patience" today. His recent work (Gemini 2.5, BIG-bench) is mostly frontier-scale stuff we can't touch meaningfully.

It does slightly change how I'd rank things at the margins:

  1. Idea B (Mixture-of-Depths, 2024) becomes fully legitimate rather than a stretch. "Does learned per-token depth allocation still beat compute-matched fixed depth at ~1M parameters on CPU?" is a real question — most adaptive-compute results are only demonstrated at scale, and small-scale replications sometimes fail interestingly. The downsides remain practical: char-level LM training is the slowest of our options on CPU, and tiny-LM results are noisy, so a null result risks being "we were underpowered" rather than "the effect isn't there." That's the bad kind of negative result.

  2. Idea A actually gets a bit stronger, not weaker. The framing I'd use — "learned sparsity in relational computation" — is exactly the adaptive-compute question of his 2024 MoD paper applied to his 2017 RN architecture. So the paper's story becomes "we connect Santoro-2017 to Santoro-2024": old testbed, current question. That's a nicer pitch than "we revisit an old architecture," and we get it without paying the CPU cost of training language models.

  3. One new option this opens: riffing on the 2022 "data distributional properties → emergent few-shot learning" line with a fresh angle... but that's the paper your previous run already riffed on, so I'd leave it alone for a genuinely fresh comparison between the two runs.

So my recommendation is unchanged: A, but explicitly framed as bringing the 2024 adaptive-compute question to the 2017 relational-reasoning setting. Same experiments as before, better story.

Want me to go ahead with A?

User

I like C also for a change, because we'll be using LLMs (as long as we can keep the API costs reasonable!)

How about we do both A and C?

I'd let you decide whether one of them should be handed off to a separate agent or not.

WDYT?

Assistant

Doing both is a good plan — they complement each other nicely: A saturates the CPU with training runs while C spends its time waiting on API calls, so I can interleave them in one session rather than paying for a cold-start subagent.

On the handoff question, my call is: no subagent for the main work. Reasons: (1) every package install and API spend needs your review, which gets messy if two agents are asking in parallel; (2) a subagent re-derives all this context at token cost, and tokens are one of our budgets; (3) A's training runs happen in the background anyway, so the main session is free to build C while A cooks. Where I will use a subagent is the final skeptical review of code + writeups — same discipline as the last project, and a fresh pair of eyes is exactly what review needs.

On C's API costs: the probe trials are short prompts with one-word-ish answers. A few hundred trials across 2–3 Claude models should land in the low single-digit dollars. I'll show you the design and estimated call count before running the full sweep.

Let me set up task tracking and check what's already in the shared venv, so I can tell you up front if anything needs installing.

⚙ ToolSearch select:TaskCreate,TaskUpdate,TaskList 
{
  "query": "select:TaskCreate,TaskUpdate,TaskList",
  "max_results": 3
}
Result
{
  "type": "tool_reference",
  "tool_name": "TaskCreate"
}
{
  "type": "tool_reference",
  "tool_name": "TaskUpdate"
}
{
  "type": "tool_reference",
  "tool_name": "TaskList"
}
⚙ PowerShell Check which packages are installed in the shared ML venv 
{
  "command": "if (Test-Path D:\\claude_code\\ml_venv\\Scripts\\pip.exe) { & D:\\claude_code\\ml_venv\\Scripts\\pip.exe list } elseif (Test-Path D:\\claude_code\\ml_venv\\bin) { echo \"Linux venv (WSL): D:\\claude_code\\ml_venv\\bin\"; ls D:\\claude_code\\ml_venv\\bin } else { echo \"venv not found\"; ls D:\\claude_code }"
}
Result
Package           Version

----------------- -----------

contourpy         1.3.3

cycler            0.12.1

filelock          3.29.7

fonttools         4.63.0

fsspec            2026.6.0

Jinja2            3.1.6

kiwisolver        1.5.0

MarkupSafe        3.0.3

matplotlib        3.11.0

mpmath            1.3.0

networkx          3.6.1

numpy             2.5.1

packaging         26.2

pillow            12.3.0

pip               25.3

pyparsing         3.3.2

python-dateutil   2.9.0.post0

setuptools        83.0.0

six               1.17.0

sympy             1.14.0

torch             2.13.0

typing_extensions 4.16.0
⚙ TaskCreate Create D:\claude_code\relational_sparsity with a synthetic Sort-of-CLEVR-style dataset generator (numpy/PIL), including relational + non-relational questions and a held-out shape-color combination split. Produce visual sanity-check images David can eyeball. 
{
  "subject": "Scaffold relational_sparsity project + Sort-of-CLEVR-style data generator",
  "activeForm": "Building data generator"
}
Result
Task #1 created successfully: Scaffold relational_sparsity project + Sort-of-CLEVR-style data generator
⚙ TaskCreate Train the two reference models on the synthetic dataset on CPU. Reproduce the qualitative Santoro-2017 result: baseline fails relational questions, RN succeeds. This validates the data and training harness before the novel experiments. 
{
  "subject": "Validate harness: train CNN+MLP baseline and full Relation Network",
  "activeForm": "Training baseline and full RN"
}
Result
Task #2 created successfully: Validate harness: train CNN+MLP baseline and full Relation Network
⚙ TaskCreate Add learned top-k pair selection to the RN plus a random-k control. Sweep k, measuring relational vs non-relational accuracy and generalization to held-out shape-color combos. Multiple seeds per condition. 
{
  "subject": "Implement sparse RN and run pair-sparsity sweep",
  "activeForm": "Running sparsity sweep"
}
Result
Task #3 created successfully: Implement sparse RN and run pair-sparsity sweep
⚙ TaskCreate Port the Ritter et al. 2017 shape-bias probe to text-based novel-word learning for Claude models via API. Design stimuli, controls (order, attribute counterbalancing), trial count, and models to probe. Present design + estimated API cost to David before running. Requires: pip install anthropic into ml_venv (David to approve), API key availability. 
{
  "subject": "Design shape-bias LLM probe (Idea C) + cost estimate",
  "activeForm": "Designing LLM shape-bias probe"
}
Result
Task #4 created successfully: Design shape-bias LLM probe (Idea C) + cost estimate
⚙ TaskCreate Execute the approved probe design across 2-3 Claude models, collect and store raw responses, analyze bias rates with uncertainty estimates. 
{
  "subject": "Run LLM shape-bias experiments",
  "activeForm": "Running LLM probe experiments"
}
Result
Task #5 created successfully: Run LLM shape-bias experiments
⚙ TaskCreate Short paper-style writeups (abstract, method, results with plots, limitations) for A and C. Honest reporting including negative results. 
{
  "subject": "Write up results for both experiments",
  "activeForm": "Writing up results"
}
Result
Task #6 created successfully: Write up results for both experiments
⚙ TaskCreate Spawn a review subagent to check both projects for bugs that could invalidate claims, overclaiming, and unsupported statements. Address findings before declaring done. 
{
  "subject": "Skeptical subagent review of code + writeups",
  "activeForm": "Running skeptical review"
}
Result
Task #7 created successfully: Skeptical subagent review of code + writeups
⚙ mcp__ccd_session__mark_chapter 
{
  "title": "Experiment A: data generator",
  "summary": "Scaffolding the relational sparsity project and building the Sort-of-CLEVR-style synthetic dataset"
}
Result
Chapter marked: "Experiment A: data generator". Continue your current work.
⚙ TaskUpdate 
{
  "taskId": "1",
  "status": "in_progress"
}
Result
Updated task #1 status
📖 Read ml-environment.md
C:\Users\dprei\.claude\projects\D--claude-code\memory\ml-environment.md
Result
[auto-memory content redacted for sharing]
⚙ PowerShell Create project directories 
{
  "command": "New-Item -ItemType Directory -Force D:\\claude_code\\relational_sparsity\\data, D:\\claude_code\\relational_sparsity\\runs, D:\\claude_code\\relational_sparsity\\figures | Select-Object FullName"
}
Result
FullName                                  

--------                                  

D:\claude_code\relational_sparsity\data   

D:\claude_code\relational_sparsity\runs   

D:\claude_code\relational_sparsity\figures
📝 Write data_gen.py
D:\claude_code\relational_sparsity\data_gen.py
"""Sort-of-CLEVR-style synthetic dataset generator.

Scenes: 6 objects, one per color (red, green, blue, orange, yellow, gray),
each a square or a circle, at random non-overlapping positions in [0,1]^2.
Rendered to 64x64 RGB. Ground-truth object states are stored alongside.

Questions (per scene, all 6 colors x 6 subtypes = 36):
  Non-relational (about the object of color X):
    NR_SHAPE : what shape is X?                      -> square/circle
    NR_HORIZ : is X on the left or right half?       -> left/right
    NR_VERT  : is X on the top or bottom half?       -> top/bottom
  Relational:
    R_CLOSEST : shape of the object closest to X?    -> square/circle
    R_FARTHEST: shape of the object farthest from X? -> square/circle
    R_COUNT   : how many objects (incl. X) share X's shape? -> 1..6

Coordinate convention: x = column (right = larger), y = row (down = larger),
so "top" means y < 0.5.

Compositional split: HELD_OUT (color, shape) combos never appear in
train/val/test_iid scenes (those colors always take the other shape there).
test_ho scenes are sampled with unconstrained shapes, rejection-sampled to
contain at least one held-out combo.
"""

import argparse
import json
import numpy as np
from pathlib import Path

COLORS = ["red", "green", "blue", "orange", "yellow", "gray"]
COLOR_RGB = {
    "red": (200, 40, 40),
    "green": (40, 160, 60),
    "blue": (50, 80, 200),
    "orange": (230, 140, 30),
    "yellow": (220, 210, 40),
    "gray": (128, 128, 128),
}
SHAPES = ["square", "circle"]
# (color_idx, shape_idx) pairs excluded from the training distribution:
# red-square, green-circle, blue-square
HELD_OUT = [(0, 0), (1, 1), (2, 0)]

SUBTYPES = ["NR_SHAPE", "NR_HORIZ", "NR_VERT", "R_CLOSEST", "R_FARTHEST", "R_COUNT"]
ANSWERS = ["square", "circle", "left", "right", "top", "bottom",
           "1", "2", "3", "4", "5", "6"]

N_OBJ = 6
IMG = 64
MARGIN = 0.10        # keep object centers away from image edges
MIN_DIST = 0.18      # min distance between object centers
OBJ_HALF = 5         # half-size of objects in pixels (~10px objects)


def sample_positions(rng):
    """Rejection-sample 6 non-overlapping positions in [MARGIN, 1-MARGIN]^2."""
    while True:
        pos = rng.uniform(MARGIN, 1 - MARGIN, size=(N_OBJ, 2))
        d = np.linalg.norm(pos[:, None] - pos[None, :], axis=-1)
        d[np.diag_indices(N_OBJ)] = np.inf
        if d.min() > MIN_DIST:
            return pos


def sample_shapes(rng, respect_holdout):
    while True:
        shapes = rng.integers(0, 2, size=N_OBJ)
        combos = {(c, int(shapes[c])) for c in range(N_OBJ)}
        held = combos & set(map(tuple, HELD_OUT))
        if respect_holdout and held:
            continue                      # train dist: no held-out combos
        if not respect_holdout and not held:
            continue                      # test_ho: need >=1 held-out combo
        return shapes


def gen_scene(rng, respect_holdout=True):
    return sample_positions(rng), sample_shapes(rng, respect_holdout)


def answer_index(pos, shapes, color, subtype):
    x, y = pos[color]
    if subtype == 0:    # NR_SHAPE
        return int(shapes[color])                       # square=0 -> ANSWERS[0]
    if subtype == 1:    # NR_HORIZ
        return 2 if x < 0.5 else 3                      # left/right
    if subtype == 2:    # NR_VERT
        return 4 if y < 0.5 else 5                      # top/bottom
    d = np.linalg.norm(pos - pos[color], axis=-1)
    d[color] = np.inf
    if subtype == 3:    # R_CLOSEST
        return int(shapes[np.argmin(d)])
    if subtype == 4:    # R_FARTHEST
        d[color] = -np.inf
        return int(shapes[np.argmax(d)])
    if subtype == 5:    # R_COUNT (includes the queried object itself)
        return 6 + int((shapes == shapes[color]).sum() - 1)   # "1".."6"
    raise ValueError(subtype)


def render(pos, shapes):
    """Render scene to uint8 (IMG, IMG, 3). Light-gray background."""
    from PIL import Image, ImageDraw
    img = Image.new("RGB", (IMG, IMG), (215, 215, 215))
    draw = ImageDraw.Draw(img)
    for i in range(N_OBJ):
        cx, cy = pos[i, 0] * IMG, pos[i, 1] * IMG
        box = [cx - OBJ_HALF, cy - OBJ_HALF, cx + OBJ_HALF, cy + OBJ_HALF]
        if shapes[i] == 0:
            draw.rectangle(box, fill=COLOR_RGB[COLORS[i]])
        else:
            draw.ellipse(box, fill=COLOR_RGB[COLORS[i]])
    return np.asarray(img, dtype=np.uint8)


def build_split(rng, n_scenes, respect_holdout):
    positions = np.zeros((n_scenes, N_OBJ, 2), dtype=np.float32)
    shapes = np.zeros((n_scenes, N_OBJ), dtype=np.int8)
    images = np.zeros((n_scenes, IMG, IMG, 3), dtype=np.uint8)
    q_scene, q_color, q_subtype, q_answer = [], [], [], []
    for s in range(n_scenes):
        pos, shp = gen_scene(rng, respect_holdout)
        positions[s], shapes[s] = pos, shp
        images[s] = render(pos, shp)
        for c in range(N_OBJ):
            for t in range(len(SUBTYPES)):
                q_scene.append(s)
                q_color.append(c)
                q_subtype.append(t)
                q_answer.append(answer_index(pos, shp, c, t))
    return dict(
        positions=positions, shapes=shapes, images=images,
        q_scene=np.array(q_scene, dtype=np.int32),
        q_color=np.array(q_color, dtype=np.int8),
        q_subtype=np.array(q_subtype, dtype=np.int8),
        q_answer=np.array(q_answer, dtype=np.int8),
    )


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--out", default="data")
    ap.add_argument("--seed", type=int, default=0)
    ap.add_argument("--n_train", type=int, default=8000)
    ap.add_argument("--n_val", type=int, default=1000)
    ap.add_argument("--n_test", type=int, default=1000)
    args = ap.parse_args()

    out = Path(args.out)
    out.mkdir(exist_ok=True)
    rng = np.random.default_rng(args.seed)
    splits = {
        "train": (args.n_train, True),
        "val": (args.n_val, True),
        "test_iid": (args.n_test, True),
        "test_ho": (args.n_test, False),
    }
    meta = dict(colors=COLORS, shapes=SHAPES, subtypes=SUBTYPES,
                answers=ANSWERS, held_out=HELD_OUT, img=IMG, seed=args.seed)
    for name, (n, respect) in splits.items():
        print(f"generating {name}: {n} scenes ...", flush=True)
        data = build_split(rng, n, respect)
        np.savez_compressed(out / f"{name}.npz", **data)
    (out / "meta.json").write_text(json.dumps(meta, indent=2))
    print("done.")


if __name__ == "__main__":
    main()
Result
File created successfully at: D:\claude_code\relational_sparsity\data_gen.py (file state is current in your context — no need to Read it back)
📝 Write sanity_check.py
D:\claude_code\relational_sparsity\sanity_check.py
"""Visual + statistical sanity checks for the generated dataset.

Produces figures/sanity_scenes.png (12 scenes, with a few Q/A pairs printed
under each) and prints invariant checks + answer distributions per split.
"""

import json
import numpy as np
import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt
from pathlib import Path

from data_gen import COLORS, SHAPES, SUBTYPES, ANSWERS, HELD_OUT, N_OBJ

DATA = Path("data")
FIGS = Path("figures")


def qa_text(color, subtype, answer):
    templates = {
        "NR_SHAPE": "shape of {c}?",
        "NR_HORIZ": "{c} left or right?",
        "NR_VERT": "{c} top or bottom?",
        "R_CLOSEST": "shape closest to {c}?",
        "R_FARTHEST": "shape farthest from {c}?",
        "R_COUNT": "# same shape as {c}?",
    }
    q = templates[SUBTYPES[subtype]].format(c=COLORS[color])
    return f"{q} -> {ANSWERS[answer]}"


def main():
    FIGS.mkdir(exist_ok=True)
    rng = np.random.default_rng(1)

    # ---- visual check on val split ----
    d = np.load(DATA / "val.npz")
    fig, axes = plt.subplots(3, 4, figsize=(16, 13))
    for ax, s in zip(axes.flat, range(12)):
        ax.imshow(d["images"][s])
        ax.set_xticks([]); ax.set_yticks([])
        mask = d["q_scene"] == s
        idx = np.flatnonzero(mask)
        picks = rng.choice(idx, size=3, replace=False)
        lines = [qa_text(d["q_color"][i], d["q_subtype"][i], d["q_answer"][i])
                 for i in picks]
        ax.set_title("\n".join(lines), fontsize=8)
    fig.suptitle("Sanity check: 12 val scenes with sampled Q/A", fontsize=13)
    fig.tight_layout()
    fig.savefig(FIGS / "sanity_scenes.png", dpi=110)
    print(f"wrote {FIGS / 'sanity_scenes.png'}")

    # ---- invariant checks ----
    held = set(map(tuple, HELD_OUT))
    for split in ["train", "val", "test_iid", "test_ho"]:
        d = np.load(DATA / split)  # type: ignore[arg-type]
        d = np.load(DATA / f"{split}.npz")
        shapes = d["shapes"]
        n = len(shapes)
        combo_count = sum(
            1 for s in range(n) for c in range(N_OBJ)
            if (c, int(shapes[s, c])) in held
        )
        scenes_with_held = sum(
            1 for s in range(n)
            if any((c, int(shapes[s, c])) in held for c in range(N_OBJ))
        )
        # NR_SHAPE answers must equal ground-truth shape
        m = d["q_subtype"] == 0
        ok = np.all(
            d["q_answer"][m] == shapes[d["q_scene"][m], d["q_color"][m]]
        )
        print(f"\n{split}: {n} scenes, {len(d['q_answer'])} questions")
        print(f"  held-out combos present: {combo_count} "
              f"(scenes containing any: {scenes_with_held}/{n})")
        print(f"  NR_SHAPE answers match ground truth: {ok}")
        # answer distribution per subtype
        for t, st in enumerate(SUBTYPES):
            m = d["q_subtype"] == t
            vals, counts = np.unique(d["q_answer"][m], return_counts=True)
            dist = ", ".join(
                f"{ANSWERS[v]}:{c / m.sum():.2f}" for v, c in zip(vals, counts)
            )
            print(f"  {st:11s} {dist}")


if __name__ == "__main__":
    main()
Result
File created successfully at: D:\claude_code\relational_sparsity\sanity_check.py (file state is current in your context — no need to Read it back)
✏️ Edit sanity_check.py
D:\claude_code\relational_sparsity\sanity_check.py
−
        d = np.load(DATA / split)  # type: ignore[arg-type]
        d = np.load(DATA / f"{split}.npz")
+
        d = np.load(DATA / f"{split}.npz")
Result
The file D:\claude_code\relational_sparsity\sanity_check.py has been updated successfully. (file state is current in your context — no need to Read it back)
⚙ PowerShell Generate the synthetic dataset (11k scenes) 
{
  "command": "Set-Location D:\\claude_code\\relational_sparsity; & D:\\claude_code\\ml_venv\\Scripts\\python.exe data_gen.py --n_train 8000 --n_val 1000 --n_test 1000",
  "timeout": 300000
}
Result
generating train: 8000 scenes ...

generating val: 1000 scenes ...

generating test_iid: 1000 scenes ...

generating test_ho: 1000 scenes ...

done.
⚙ PowerShell Run dataset sanity checks and render sample scenes 
{
  "command": "Set-Location D:\\claude_code\\relational_sparsity; & D:\\claude_code\\ml_venv\\Scripts\\python.exe sanity_check.py",
  "timeout": 180000
}
Result
wrote figures\sanity_scenes.png



train: 8000 scenes, 288000 questions

  held-out combos present: 0 (scenes containing any: 0/8000)

  NR_SHAPE answers match ground truth: True

  NR_SHAPE    square:0.42, circle:0.58

  NR_HORIZ    left:0.50, right:0.50

  NR_VERT     top:0.50, bottom:0.50

  R_CLOSEST   square:0.42, circle:0.58

  R_FARTHEST  square:0.41, circle:0.59

  R_COUNT     1:0.02, 2:0.17, 3:0.37, 4:0.34, 5:0.11



val: 1000 scenes, 36000 questions

  held-out combos present: 0 (scenes containing any: 0/1000)

  NR_SHAPE answers match ground truth: True

  NR_SHAPE    square:0.41, circle:0.59

  NR_HORIZ    left:0.49, right:0.51

  NR_VERT     top:0.50, bottom:0.50

  R_CLOSEST   square:0.41, circle:0.59

  R_FARTHEST  square:0.41, circle:0.59

  R_COUNT     1:0.02, 2:0.16, 3:0.39, 4:0.32, 5:0.11



test_iid: 1000 scenes, 36000 questions

  held-out combos present: 0 (scenes containing any: 0/1000)

  NR_SHAPE answers match ground truth: True

  NR_SHAPE    square:0.41, circle:0.59

  NR_HORIZ    left:0.49, right:0.51

  NR_VERT     top:0.50, bottom:0.50

  R_CLOSEST   square:0.41, circle:0.59

  R_FARTHEST  square:0.42, circle:0.58

  R_COUNT     1:0.02, 2:0.16, 3:0.37, 4:0.32, 5:0.12



test_ho: 1000 scenes, 36000 questions

  held-out combos present: 1765 (scenes containing any: 1000/1000)

  NR_SHAPE answers match ground truth: True

  NR_SHAPE    square:0.51, circle:0.49

  NR_HORIZ    left:0.50, right:0.50

  NR_VERT     top:0.51, bottom:0.49

  R_CLOSEST   square:0.51, circle:0.49

  R_FARTHEST  square:0.51, circle:0.49

  R_COUNT     1:0.03, 2:0.15, 3:0.33, 4:0.30, 5:0.14, 6:0.04
📖 Read sanity_scenes.png
D:\claude_code\relational_sparsity\figures\sanity_scenes.png
Result
📝 Write models.py
D:\claude_code\relational_sparsity\models.py
"""Models: MLP baseline, Relation Network, and sparse-pair RN variants.

Objects arrive as (B, n, d) tensors; questions as (B, q).

State tier: n=6 ground-truth objects, d=10 (x, y in [-1,1], color one-hot 6,
shape one-hot 2), canonical color order (object i = color i).
Pixel tier: n=16 CNN feature-map cells (+2 coord dims appended).

RN pair selection modes:
  full    : classic RN — sum g over all n^2 ordered pairs (incl. self-pairs).
  learned : a scorer MLP ranks pairs given the question; top-k pairs are
            summed. Training uses a straight-through estimator (hard top-k
            forward, gradients via k * softmax(logits / tau)).
  random  : k pairs sampled uniformly per example per forward pass (control:
            "is it selection that matters, or just having fewer pairs?").
  oracle  : the n pairs (i, X) whose second element is the queried object X
            (state tier only, where object identity = color). Hand-coded
            upper bound for what a perfect selector could pick.
"""

import torch
import torch.nn as nn


def mlp(dims, out_dim):
    layers = []
    for a, b in zip(dims[:-1], dims[1:]):
        layers += [nn.Linear(a, b), nn.ReLU()]
    layers.append(nn.Linear(dims[-1], out_dim))
    return nn.Sequential(*layers)


class BaselineMLP(nn.Module):
    """Flattened objects + question -> MLP. No relational structure."""

    def __init__(self, n_obj, obj_dim, q_dim, n_answers, hidden=256):
        super().__init__()
        self.net = mlp([n_obj * obj_dim + q_dim, hidden, hidden, hidden],
                       n_answers)

    def forward(self, objs, q):
        return self.net(torch.cat([objs.flatten(1), q], dim=1)), None


class CNNEncoder(nn.Module):
    """64x64x3 -> 16 'objects' (4x4 feature map cells + coords)."""

    def __init__(self, ch=32):
        super().__init__()
        c = ch
        self.conv = nn.Sequential(
            nn.Conv2d(3, c, 3, stride=2, padding=1), nn.ReLU(),    # 32
            nn.Conv2d(c, c, 3, stride=2, padding=1), nn.ReLU(),    # 16
            nn.Conv2d(c, c, 3, stride=2, padding=1), nn.ReLU(),    # 8
            nn.Conv2d(c, c, 3, stride=2, padding=1), nn.ReLU(),    # 4
        )
        ys, xs = torch.meshgrid(
            torch.linspace(-1, 1, 4), torch.linspace(-1, 1, 4), indexing="ij")
        self.register_buffer("coords", torch.stack([xs, ys], -1).view(16, 2))
        self.out_dim = ch + 2

    def forward(self, img):                      # (B, 3, 64, 64)
        f = self.conv(img)                       # (B, c, 4, 4)
        f = f.flatten(2).transpose(1, 2)         # (B, 16, c)
        coords = self.coords.expand(f.shape[0], -1, -1)
        return torch.cat([f, coords], dim=-1)    # (B, 16, c+2)


class RelationNet(nn.Module):
    def __init__(self, n_obj, obj_dim, q_dim, n_answers,
                 select="full", k=None, g_hidden=128, f_hidden=128,
                 tau=0.5, encoder=None):
        super().__init__()
        assert select in ("full", "learned", "random", "oracle")
        if select != "full":
            assert k is not None or select == "oracle"
        self.n, self.select, self.k, self.tau = n_obj, select, k, tau
        self.encoder = encoder  # optional CNN for pixel tier
        pair_dim = 2 * obj_dim + q_dim
        self.g = mlp([pair_dim, g_hidden, g_hidden, g_hidden], g_hidden)
        self.f = mlp([g_hidden, f_hidden], n_answers)
        if select == "learned":
            self.scorer = mlp([pair_dim, 64], 1)
        idx = torch.arange(n_obj)
        self.register_buffer("pi", idx.repeat_interleave(n_obj))  # first of pair
        self.register_buffer("pj", idx.repeat(n_obj))             # second of pair

    def pair_weights(self, pairs, q_color=None):
        """Return (B, n^2) weights for summing g outputs, plus logits."""
        B, P, _ = pairs.shape
        dev = pairs.device
        if self.select == "full":
            return torch.ones(B, P, device=dev), None
        if self.select == "random":
            r = torch.rand(B, P, device=dev)
            thresh = r.topk(self.k, dim=1).values[:, -1:]
            return (r >= thresh).float(), None
        if self.select == "oracle":
            # pairs (i, X): second element is the queried object
            w = (self.pj[None, :].to(dev) == q_color[:, None]).float()
            return w, None
        # learned: straight-through hard top-k
        logits = self.scorer(pairs).squeeze(-1)             # (B, P)
        soft = self.k * torch.softmax(logits / self.tau, dim=1)
        thresh = logits.topk(self.k, dim=1).values[:, -1:]
        hard = (logits >= thresh).float()
        if self.training:
            w = hard + soft - soft.detach()
        else:
            w = hard
        return w, logits

    def forward(self, objs, q, q_color=None):
        if self.encoder is not None:
            objs = self.encoder(objs)
        oi, oj = objs[:, self.pi], objs[:, self.pj]          # (B, P, d)
        qe = q[:, None, :].expand(-1, oi.shape[1], -1)
        pairs = torch.cat([oi, oj, qe], dim=-1)
        w, logits = self.pair_weights(pairs, q_color)
        gout = self.g(pairs)                                 # (B, P, H)
        pooled = (gout * w[..., None]).sum(1)
        return self.f(pooled), logits
Result
File created successfully at: D:\claude_code\relational_sparsity\models.py (file state is current in your context — no need to Read it back)
📝 Write train.py
D:\claude_code\relational_sparsity\train.py
"""Training harness (state and pixel tiers).

Example:
  python train.py --name rn_full_s0 --model rn --select full --seed 0
  python train.py --name rn_k5_s0 --model rn --select learned --k 5 --seed 0

Checkpoints every epoch to runs/<name>/ckpt.pt and resumes automatically if
one exists. Final metrics -> runs/<name>/result.json, per-epoch -> log.csv.
"""

import argparse
import json
import time
from pathlib import Path

import numpy as np
import torch
import torch.nn.functional as F

from data_gen import SUBTYPES, ANSWERS, HELD_OUT, N_OBJ
from models import BaselineMLP, RelationNet, CNNEncoder

REL_SUBTYPES = [3, 4, 5]          # R_CLOSEST, R_FARTHEST, R_COUNT
ANS_SIX = ANSWERS.index("6")


def load_split(data_dir, name, pixels):
    d = np.load(Path(data_dir) / f"{name}.npz")
    pos, shp = d["positions"], d["shapes"]
    n = len(pos)
    if pixels:
        objs = torch.from_numpy(d["images"]).permute(0, 3, 1, 2).contiguous()
    else:
        feats = np.zeros((n, N_OBJ, 10), dtype=np.float32)
        feats[:, :, 0:2] = 2 * pos - 1
        feats[np.arange(n)[:, None], np.arange(N_OBJ)[None, :],
              2 + np.arange(N_OBJ)[None, :]] = 1.0          # color one-hot
        feats[np.arange(n)[:, None], np.arange(N_OBJ)[None, :],
              8 + shp.astype(int)] = 1.0                    # shape one-hot
        objs = torch.from_numpy(feats)
    q_color = torch.from_numpy(d["q_color"].astype(np.int64))
    q_subtype = torch.from_numpy(d["q_subtype"].astype(np.int64))
    qvec = torch.cat([F.one_hot(q_color, N_OBJ),
                      F.one_hot(q_subtype, len(SUBTYPES))], dim=1).float()
    # is the queried object a held-out (color, shape) combo?
    combo_held = np.zeros(len(q_color), dtype=bool)
    qs = d["q_scene"]
    for c, s in HELD_OUT:
        combo_held |= (d["q_color"] == c) & (shp[qs, c] == s)
    return dict(
        objs=objs, scene=torch.from_numpy(qs.astype(np.int64)),
        qvec=qvec, q_color=q_color, q_subtype=q_subtype,
        ans=torch.from_numpy(d["q_answer"].astype(np.int64)),
        combo_held=torch.from_numpy(combo_held),
    )


def get_batch(split, idx, pixels):
    objs = split["objs"][split["scene"][idx]]
    if pixels:
        objs = objs.float() / 255.0 - 0.5
    return objs, split["qvec"][idx], split["q_color"][idx], split["ans"][idx]


@torch.no_grad()
def evaluate(model, split, pixels, batch=2048):
    model.eval()
    n = len(split["ans"])
    correct = torch.zeros(n, dtype=torch.bool)
    sel_frac = []
    for lo in range(0, n, batch):
        idx = torch.arange(lo, min(lo + batch, n))
        objs, qv, qc, ans = get_batch(split, idx, pixels)
        logits, sel_logits = model(objs, qv, q_color=qc)
        correct[idx] = logits.argmax(1) == ans
        if sel_logits is not None and not pixels:
            # fraction of selected pairs that involve the queried object
            k = model.k
            top = sel_logits.topk(k, dim=1).indices
            pi, pj = model.pi[top], model.pj[top]
            involves = (pi == qc[:, None]) | (pj == qc[:, None])
            sel_frac.append(involves.float().mean().item())
    st = split["q_subtype"]
    res = {"acc": correct.float().mean().item()}
    for t, name in enumerate(SUBTYPES):
        res[f"acc_{name}"] = correct[st == t].float().mean().item()
    rel = sum(st == t for t in REL_SUBTYPES).bool()
    res["acc_rel"] = correct[rel].float().mean().item()
    res["acc_nonrel"] = correct[~rel].float().mean().item()
    held = split["combo_held"]
    if held.any():
        res["acc_heldout_combo_q"] = correct[held].float().mean().item()
        # R_COUNT with answer '6' is untrainable (never occurs in train dist)
        ok = ~((st == 5) & (split["ans"] == ANS_SIX))
        res["acc_excl_count6"] = correct[ok].float().mean().item()
    if sel_frac:
        res["sel_frac_involves_query"] = float(np.mean(sel_frac))
    return res


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--name", required=True)
    ap.add_argument("--data", default="data")
    ap.add_argument("--input", choices=["state", "pixel"], default="state")
    ap.add_argument("--model", choices=["baseline", "rn"], default="rn")
    ap.add_argument("--select", default="full",
                    choices=["full", "learned", "random", "oracle"])
    ap.add_argument("--k", type=int, default=None)
    ap.add_argument("--tau", type=float, default=0.5)
    ap.add_argument("--seed", type=int, default=0)
    ap.add_argument("--epochs", type=int, default=20)
    ap.add_argument("--batch", type=int, default=256)
    ap.add_argument("--lr", type=float, default=1e-3)
    ap.add_argument("--threads", type=int, default=4)
    ap.add_argument("--limit_train", type=int, default=None,
                    help="cap train questions (smoke tests)")
    args = ap.parse_args()

    torch.set_num_threads(args.threads)
    torch.manual_seed(args.seed)
    pixels = args.input == "pixel"
    out = Path("runs") / args.name
    out.mkdir(parents=True, exist_ok=True)

    tr = load_split(args.data, "train", pixels)
    va = load_split(args.data, "val", pixels)
    n_train = len(tr["ans"]) if args.limit_train is None else args.limit_train

    q_dim = N_OBJ + len(SUBTYPES)
    if args.model == "baseline":
        if pixels:
            raise SystemExit("pixel baseline: use models via rn path later")
        model = BaselineMLP(N_OBJ, 10, q_dim, len(ANSWERS))
    else:
        enc = CNNEncoder() if pixels else None
        n_obj = 16 if pixels else N_OBJ
        obj_dim = enc.out_dim if pixels else 10
        model = RelationNet(n_obj, obj_dim, q_dim, len(ANSWERS),
                            select=args.select, k=args.k, tau=args.tau,
                            encoder=enc)
    if args.select == "oracle" and pixels:
        raise SystemExit("oracle selection requires state input")
    n_params = sum(p.numel() for p in model.parameters())
    opt = torch.optim.Adam(model.parameters(), lr=args.lr)

    ckpt_path = out / "ckpt.pt"
    start_epoch = 0
    if ckpt_path.exists():
        ck = torch.load(ckpt_path, weights_only=False)
        model.load_state_dict(ck["model"])
        opt.load_state_dict(ck["opt"])
        start_epoch = ck["epoch"] + 1
        torch.set_rng_state(ck["rng"])
        print(f"resumed from epoch {start_epoch}", flush=True)

    log_path = out / "log.csv"
    if not log_path.exists():
        log_path.write_text(
            "epoch,train_loss,val_acc,val_acc_rel,val_acc_nonrel,"
            "sel_frac,secs\n")

    print(f"{args.name}: {n_params} params, {n_train} train questions",
          flush=True)
    for epoch in range(start_epoch, args.epochs):
        model.train()
        t0 = time.time()
        perm = torch.randperm(len(tr["ans"]))[:n_train]
        losses = []
        for lo in range(0, n_train, args.batch):
            idx = perm[lo:lo + args.batch]
            objs, qv, qc, ans = get_batch(tr, idx, pixels)
            logits, _ = model(objs, qv, q_color=qc)
            loss = F.cross_entropy(logits, ans)
            opt.zero_grad()
            loss.backward()
            opt.step()
            losses.append(loss.item())
        ev = evaluate(model, va, pixels)
        secs = time.time() - t0
        line = (f"{epoch},{np.mean(losses):.4f},{ev['acc']:.4f},"
                f"{ev['acc_rel']:.4f},{ev['acc_nonrel']:.4f},"
                f"{ev.get('sel_frac_involves_query', float('nan')):.4f},"
                f"{secs:.1f}")
        print(line, flush=True)
        with log_path.open("a") as fh:
            fh.write(line + "\n")
        torch.save(dict(model=model.state_dict(), opt=opt.state_dict(),
                        epoch=epoch, rng=torch.get_rng_state()), ckpt_path)

    # final evaluation
    result = dict(config=vars(args), n_params=n_params)
    for name in ["val", "test_iid", "test_ho"]:
        split = va if name == "val" else load_split(args.data, name, pixels)
        result[name] = evaluate(model, split, pixels)
    (out / "result.json").write_text(json.dumps(result, indent=2))
    print("final:", json.dumps({k: v for k, v in result.items()
                                if k in ("test_iid", "test_ho")}, indent=2),
          flush=True)


if __name__ == "__main__":
    main()
Result
File created successfully at: D:\claude_code\relational_sparsity\train.py (file state is current in your context — no need to Read it back)

Smoke test time — one fast epoch per variant to catch bugs and measure speed.

⚙ PowerShell Smoke-test baseline MLP and full RN (1 epoch, 20k questions) 
{
  "command": "Set-Location D:\\claude_code\\relational_sparsity; & D:\\claude_code\\ml_venv\\Scripts\\python.exe train.py --name smoke_baseline --model baseline --epochs 1 --limit_train 20000; & D:\\claude_code\\ml_venv\\Scripts\\python.exe train.py --name smoke_rn_full --model rn --select full --epochs 1 --limit_train 20000",
  "timeout": 600000
}
Result
smoke_baseline: 153356 params, 20000 train questions

Traceback (most recent call last):

  File "D:\claude_code\relational_sparsity\train.py", line 203, in <module>

    main()

    ~~~~^^

  File "D:\claude_code\relational_sparsity\train.py", line 173, in main

    logits, _ = model(objs, qv, q_color=qc)

                ~~~~~^^^^^^^^^^^^^^^^^^^^^^

  File "D:\claude_code\ml_venv\Lib\site-packages\torch\nn\modules\module.py", line 1778, in _wrapped_call_impl

    return self._call_impl(*args, **kwargs)

           ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^

  File "D:\claude_code\ml_venv\Lib\site-packages\torch\nn\modules\module.py", line 1789, in _call_impl

    return forward_call(*args, **kwargs)

TypeError: BaselineMLP.forward() got an unexpected keyword argument 'q_color'

smoke_rn_full: 71820 params, 20000 train questions

0,0.9718,0.5957,0.5747,0.6168,nan,2.4

final: {

  "test_iid": {

    "acc": 0.5990555286407471,

    "acc_NR_SHAPE": 0.7940000295639038,

    "acc_NR_HORIZ": 0.49133333563804626,

    "acc_NR_VERT": 0.5503333210945129,

    "acc_R_CLOSEST": 0.515999972820282,

    "acc_R_FARTHEST": 0.5619999766349792,

    "acc_R_COUNT": 0.6806666851043701,

    "acc_rel": 0.586222231388092,

    "acc_nonrel": 0.6118888854980469

  },

  "test_ho": {

    "acc": 0.542555570602417,

    "acc_NR_SHAPE": 0.5681666731834412,

    "acc_NR_HORIZ": 0.5034999847412109,

    "acc_NR_VERT": 0.5563333630561829,

    "acc_R_CLOSEST": 0.5814999938011169,

    "acc_R_FARTHEST": 0.5976666808128357,

    "acc_R_COUNT": 0.4481666684150696,

    "acc_rel": 0.5424444675445557,

    "acc_nonrel": 0.5426666736602783,

    "acc_heldout_combo_q": 0.47629839181900024,

    "acc_excl_count6": 0.5465636849403381

  }

}

The RN path works and it's fast (2.4 s for 20k questions → full training ≈ 12 min/run). The baseline just needs to accept the q_color kwarg it ignores.

✏️ Edit models.py
D:\claude_code\relational_sparsity\models.py
−
    def forward(self, objs, q):
        return self.net(torch.cat([objs.flatten(1), q], dim=1)), None
+
    def forward(self, objs, q, q_color=None):
        return self.net(torch.cat([objs.flatten(1), q], dim=1)), None
Result
The file D:\claude_code\relational_sparsity\models.py has been updated successfully. (file state is current in your context — no need to Read it back)
⚙ PowerShell Smoke-test baseline, learned-k, random-k, oracle variants 
{
  "command": "Set-Location D:\\claude_code\\relational_sparsity; Remove-Item -Recurse -Force runs\\smoke_baseline; & D:\\claude_code\\ml_venv\\Scripts\\python.exe train.py --name smoke_baseline --model baseline --epochs 1 --limit_train 20000; & D:\\claude_code\\ml_venv\\Scripts\\python.exe train.py --name smoke_learned --model rn --select learned --k 5 --epochs 1 --limit_train 20000; & D:\\claude_code\\ml_venv\\Scripts\\python.exe train.py --name smoke_random --model rn --select random --k 5 --epochs 1 --limit_train 20000; & D:\\claude_code\\ml_venv\\Scripts\\python.exe train.py --name smoke_oracle --model rn --select oracle --epochs 1 --limit_train 20000",
  "timeout": 600000
}
Result
smoke_baseline: 153356 params, 20000 train questions

0,1.4386,0.5898,0.6079,0.5717,nan,0.2

final: {

  "test_iid": {

    "acc": 0.5872222185134888,

    "acc_NR_SHAPE": 0.6990000009536743,

    "acc_NR_HORIZ": 0.5095000267028809,

    "acc_NR_VERT": 0.5106666684150696,

    "acc_R_CLOSEST": 0.606333315372467,

    "acc_R_FARTHEST": 0.596833348274231,

    "acc_R_COUNT": 0.6010000109672546,

    "acc_rel": 0.6013888716697693,

    "acc_nonrel": 0.5730555653572083

  },

  "test_ho": {

    "acc": 0.48222222924232483,

    "acc_NR_SHAPE": 0.5416666865348816,

    "acc_NR_HORIZ": 0.5005000233650208,

    "acc_NR_VERT": 0.5128333568572998,

    "acc_R_CLOSEST": 0.5263333320617676,

    "acc_R_FARTHEST": 0.5286666750907898,

    "acc_R_COUNT": 0.28333333134651184,

    "acc_rel": 0.44611111283302307,

    "acc_nonrel": 0.5183333158493042,

    "acc_heldout_combo_q": 0.43437203764915466,

    "acc_excl_count6": 0.485784649848938

  }

}

smoke_learned: 73997 params, 20000 train questions

0,1.2088,0.5537,0.5167,0.5907,0.3112,2.7

final: {

  "test_iid": {

    "acc": 0.5547500252723694,

    "acc_NR_SHAPE": 0.7425000071525574,

    "acc_NR_HORIZ": 0.49050000309944153,

    "acc_NR_VERT": 0.5364999771118164,

    "acc_R_CLOSEST": 0.5929999947547913,

    "acc_R_FARTHEST": 0.597000002861023,

    "acc_R_COUNT": 0.36899998784065247,

    "acc_rel": 0.5196666717529297,

    "acc_nonrel": 0.5898333191871643,

    "sel_frac_involves_query": 0.3119213928778966

  },

  "test_ho": {

    "acc": 0.5200833082199097,

    "acc_NR_SHAPE": 0.5820000171661377,

    "acc_NR_HORIZ": 0.49950000643730164,

    "acc_NR_VERT": 0.5333333611488342,

    "acc_R_CLOSEST": 0.5851666927337646,

    "acc_R_FARTHEST": 0.5924999713897705,

    "acc_R_COUNT": 0.328000009059906,

    "acc_rel": 0.5018888711929321,

    "acc_nonrel": 0.538277804851532,

    "acc_heldout_combo_q": 0.46496695280075073,

    "acc_excl_count6": 0.5239254236221313,

    "sel_frac_involves_query": 0.3082927183972465

  }

}

smoke_random: 71820 params, 20000 train questions

0,1.2271,0.4823,0.4574,0.5072,nan,2.4

final: {

  "test_iid": {

    "acc": 0.48133334517478943,

    "acc_NR_SHAPE": 0.5256666541099548,

    "acc_NR_HORIZ": 0.49050000309944153,

    "acc_NR_VERT": 0.5,

    "acc_R_CLOSEST": 0.45366665720939636,

    "acc_R_FARTHEST": 0.4801666736602783,

    "acc_R_COUNT": 0.43799999356269836,

    "acc_rel": 0.457277774810791,

    "acc_nonrel": 0.5053889155387878

  },

  "test_ho": {

    "acc": 0.4977777898311615,

    "acc_NR_SHAPE": 0.5383333563804626,

    "acc_NR_HORIZ": 0.49950000643730164,

    "acc_NR_VERT": 0.4925000071525574,

    "acc_R_CLOSEST": 0.5569999814033508,

    "acc_R_FARTHEST": 0.5641666650772095,

    "acc_R_COUNT": 0.33516666293144226,

    "acc_rel": 0.48544445633888245,

    "acc_nonrel": 0.5101110935211182,

    "acc_heldout_combo_q": 0.48385268449783325,

    "acc_excl_count6": 0.5014551281929016

  }

}

smoke_oracle: 71820 params, 20000 train questions

0,1.0932,0.7712,0.5828,0.9596,nan,2.4

final: {

  "test_iid": {

    "acc": 0.7693889141082764,

    "acc_NR_SHAPE": 1.0,

    "acc_NR_HORIZ": 0.9315000176429749,

    "acc_NR_VERT": 0.9478333592414856,

    "acc_R_CLOSEST": 0.6183333396911621,

    "acc_R_FARTHEST": 0.6178333163261414,

    "acc_R_COUNT": 0.5008333325386047,

    "acc_rel": 0.5789999961853027,

    "acc_nonrel": 0.9597777724266052

  },

  "test_ho": {

    "acc": 0.7379721999168396,

    "acc_NR_SHAPE": 0.987500011920929,

    "acc_NR_HORIZ": 0.918666660785675,

    "acc_NR_VERT": 0.934166669845581,

    "acc_R_CLOSEST": 0.5964999794960022,

    "acc_R_FARTHEST": 0.6234999895095825,

    "acc_R_COUNT": 0.3675000071525574,

    "acc_rel": 0.5291666388511658,

    "acc_nonrel": 0.9467777609825134,

    "acc_heldout_combo_q": 0.7151085734367371,

    "acc_excl_count6": 0.7434239983558655

  }

}
📝 Write run_sweep.py
D:\claude_code\relational_sparsity\run_sweep.py
"""Run queues of training runs with limited parallelism.

  python run_sweep.py validate   # baseline + full RN + oracle, 3 seeds
  python run_sweep.py sweep      # learned-k / random-k grids, 3 seeds

Idempotent: runs whose runs/<name>/result.json exists are skipped, and
train.py itself resumes from checkpoints, so this can be re-launched freely.
"""

import subprocess
import sys
import time
from pathlib import Path

PY = r"D:\claude_code\ml_venv\Scripts\python.exe"
MAX_WORKERS = 3
THREADS = 4
EPOCHS = 20
SEEDS = [0, 1, 2]
KS = [1, 3, 6, 12, 24]


def runs_for(stage):
    runs = []
    if stage == "validate":
        for s in SEEDS:
            runs.append((f"baseline_s{s}", ["--model", "baseline"], s))
            runs.append((f"rn_full_s{s}", ["--select", "full"], s))
            runs.append((f"rn_oracle_s{s}", ["--select", "oracle"], s))
    elif stage == "sweep":
        for s in SEEDS:
            for k in KS:
                runs.append((f"rn_learned_k{k}_s{s}",
                             ["--select", "learned", "--k", str(k)], s))
                runs.append((f"rn_random_k{k}_s{s}",
                             ["--select", "random", "--k", str(k)], s))
    else:
        raise SystemExit(f"unknown stage {stage}")
    return runs


def main():
    stage = sys.argv[1]
    queue = [
        (name, extra, seed) for name, extra, seed in runs_for(stage)
        if not (Path("runs") / name / "result.json").exists()
    ]
    print(f"{len(queue)} runs to do", flush=True)
    active = []
    while queue or active:
        while queue and len(active) < MAX_WORKERS:
            name, extra, seed = queue.pop(0)
            cmd = [PY, "-u", "train.py", "--name", name, "--seed", str(seed),
                   "--epochs", str(EPOCHS), "--threads", str(THREADS)] + extra
            log = open(Path("runs") / f"{name}.log", "w")
            print(f"start {name}", flush=True)
            active.append((name, subprocess.Popen(
                cmd, stdout=log, stderr=subprocess.STDOUT), log))
        time.sleep(5)
        still = []
        for name, proc, log in active:
            if proc.poll() is None:
                still.append((name, proc, log))
            else:
                log.close()
                print(f"done {name} (rc={proc.returncode})", flush=True)
        active = still
    print("all done", flush=True)


if __name__ == "__main__":
    main()
Result
File created successfully at: D:\claude_code\relational_sparsity\run_sweep.py (file state is current in your context — no need to Read it back)
⚙ PowerShell Clean smoke runs, launch validation stage detached, verify processes alive 
{
  "command": "Set-Location D:\\claude_code\\relational_sparsity; Remove-Item -Recurse -Force runs\\smoke_*; Start-Process -FilePath D:\\claude_code\\ml_venv\\Scripts\\python.exe -ArgumentList \"-u\",\"run_sweep.py\",\"validate\" -WorkingDirectory D:\\claude_code\\relational_sparsity -RedirectStandardOutput runs\\validate_stage.log -WindowStyle Hidden; Start-Sleep -Seconds 10; Get-Content runs\\validate_stage.log; Get-Process python* | Select-Object Id, ProcessName, StartTime"
}
Result
9 runs to do

start baseline_s0

start rn_full_s0

start rn_oracle_s0



   Id ProcessName StartTime          

   -- ----------- ---------          

 6020 python      09/07/2026 19:12:08

 7792 python      09/07/2026 19:12:08

13124 python      09/07/2026 19:12:08

19292 python      09/07/2026 19:12:08

21632 python      09/07/2026 19:12:08

23016 python      09/07/2026 19:12:08

24160 python      09/07/2026 19:12:08

27528 python      09/07/2026 19:12:08
⚙ TaskUpdate 
{
  "taskId": "1",
  "status": "completed"
}
Result
Updated task #1 status
⚙ TaskUpdate 
{
  "taskId": "2",
  "status": "in_progress"
}
Result
Updated task #2 status
📖 Read zork-paper-reproduction.md
C:\Users\dprei\.claude\projects\D--claude-code\memory\zork-paper-reproduction.md
Result
[auto-memory content redacted for sharing]
📖 Read riddle-riddle-reproduction.md
C:\Users\dprei\.claude\projects\D--claude-code\memory\riddle-riddle-reproduction.md
Result
[auto-memory content redacted for sharing]
⚙ PowerShell Verify riddle venv has anthropic SDK + key file; check training progress 
{
  "command": "& D:\\claude_code\\riddle_experiment\\.venv\\Scripts\\python.exe -c \"import anthropic, pandas, matplotlib; print('anthropic', anthropic.__version__)\"; Test-Path D:\\claude_code\\riddle_experiment\\.anthropic_key; Get-Content D:\\claude_code\\relational_sparsity\\runs\\validate_stage.log"
}
Result
anthropic 0.112.0

True

9 runs to do

start baseline_s0

start rn_full_s0

start rn_oracle_s0
⚙ PowerShell Check training progress of full RN and oracle runs 
{
  "command": "Get-Content D:\\claude_code\\relational_sparsity\\runs\\rn_full_s0.log -Tail 5; Get-Content D:\\claude_code\\relational_sparsity\\runs\\rn_oracle_s0.log -Tail 3"
}
Result
rn_full_s0: 71820 params, 288000 train questions

0,0.4198,0.8766,0.7681,0.9852,nan,30.8

1,0.2232,0.8860,0.7775,0.9946,nan,31.4

rn_oracle_s0: 71820 params, 288000 train questions

0,0.3139,0.8820,0.7754,0.9886,nan,30.7

1,0.2083,0.9156,0.8387,0.9926,nan,31.3
⚙ Skill claude-api 
{
  "skill": "claude-api",
  "args": "pricing and model ids for Haiku 4.5, Sonnet 5, Opus 4.8; basic messages API usage with temperature 0"
}
Result
Launching skill: claude-api
Injected context
Skill instructions: claude-api

Base directory for this skill: C:\Users\dprei\AppData\Local\Temp\claude\bundled-skills\2.1.202\ae6d73f94000a3521c3ee081d1c55e15\claude-api

Building LLM-Powered Applications with Claude

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

Before You Start

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

Output Requirement

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

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

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

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

If WebFetch or repository access fails (network restricted, timeouts, clone blocked): do not keep retrying — write code from the patterns and namespace/package tables in the {lang}/ file, run the compiler or interpreter on it, and iterate on the error output. For statically-typed SDKs (C#, Java, Go) a compile-fix loop against local errors reaches working code faster than blocked network research.

Defaults

Unless the user requests otherwise:

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

⚠️ API Drift — Your Training Prior May Be Stale

Several common Claude API shapes changed in 2025–2026. If you recall a pattern from training, verify it against the {lang}/ files in this skill before writing — the rows below are the most frequent drift points:

Area Stale prior Current API
Extended thinking thinking: {type: "enabled", budget_tokens: N} On Claude 4.6+ models: thinking: {type: "adaptive"}. budget_tokens is deprecated on Opus 4.6 / Sonnet 4.6 and rejected with a 400 on Fable 5 / Sonnet 5 / Opus 4.8 / 4.7. Pre-4.6 models still use budget_tokens.
Web search / web fetch tool type web_search_20250305, web_fetch_20250910 web_search_20260209, web_fetch_20260209 (dynamic filtering) on Opus 4.8/4.7/4.6, Sonnet 5, and Sonnet 4.6. Older models keep the basic variants; on Vertex AI only basic web_search_20250305 is available (web fetch is not on Vertex) — see the Server Tools QR below.
PHP parameter names snake_case wire names as named args (max_tokens) Top-level named args are camelCase (maxTokens). Nested array keys vary by feature (e.g. 'taskBudget', 'skillID', 'mcp_server_name') — copy the exact key from the documented example; do not bulk-convert.

The {lang}/ files in this skill are authoritative over recalled patterns.

Subcommands

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

Subcommand Action
migrate Migrate existing Claude API code to a newer model. Read shared/model-migration.md immediately and follow it in order: Step 0 (confirm scope — ask which files/directories before any edit), Step 1 (classify each file), then the per-target breaking-changes section. Do not summarize the guide — execute it. If the user did not name a target model, ask which model to migrate to in the same turn as the scope question.

Language Detection

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

  1. Look at project files to infer the language:

  2. *.py, requirements.txt, pyproject.toml, setup.py, Pipfile → Python — read from python/

  3. *.ts, *.tsx, package.json, tsconfig.json → TypeScript — read from typescript/
  4. *.js, *.jsx (no .ts files present) → TypeScript — JS uses the same SDK, read from typescript/
  5. *.java, pom.xml, build.gradle → Java — read from java/
  6. *.kt, *.kts, build.gradle.kts → Java — Kotlin uses the Java SDK, read from java/
  7. *.scala, build.sbt → Java — Scala uses the Java SDK, read from java/
  8. *.go, go.mod → Go — read from go/
  9. *.rb, Gemfile → Ruby — read from ruby/
  10. *.cs, *.csproj → C# — read from csharp/

  11. *.php, composer.json → PHP — read from php/

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

  13. Check which language the user's current file or question relates to

  14. If still ambiguous, ask: "I detected both Python and TypeScript files. Which language are you using for the Claude API integration?"

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

  16. Use AskUserQuestion with options: Python, TypeScript, Java, Go, Ruby, cURL/raw HTTP, C#, PHP

  17. If AskUserQuestion is unavailable, default to Python examples and note: "Showing Python examples. Let me know if you need a different language."

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

  19. Suggest cURL/raw HTTP examples from curl/ and note that community SDKs may exist

  20. Offer to show Python or TypeScript examples as reference implementations

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

Language-Specific Feature Support

Language Tool Runner Managed Agents Notes
Python Yes (beta) Yes (beta) Full support — @beta_tool decorator
TypeScript Yes (beta) Yes (beta) Full support — betaZodTool + Zod
Java Yes (beta) Yes (beta) Beta tool use with annotated classes
Go Yes (beta) Yes (beta) BetaToolRunner in toolrunner pkg
Ruby Yes (beta) Yes (beta) BaseTool + tool_runner in beta
C# Yes (beta) Yes (beta) BetaToolRunner + raw JSON schema
PHP Yes (beta) Yes (beta) BetaRunnableTool + toolRunner()
cURL N/A Yes (beta) Raw HTTP, no SDK features

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

Which Surface Should I Use?

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

Use Case Tier Recommended Surface Why
Classification, summarization, extraction, Q&A Single LLM call Claude API One request, one response
Batch processing or embeddings Single LLM call Claude API Specialized endpoints
Multi-step pipelines with code-controlled logic Workflow Claude API + tool use You orchestrate the loop
Custom agent with your own tools Agent Claude API + tool use Maximum flexibility
Server-managed stateful agent with workspace Agent Managed Agents Anthropic runs the loop and hosts the tool-execution sandbox
Persisted, versioned agent configs Agent Managed Agents Agents are stored objects; sessions pin to a version
Long-running multi-turn agent with file mounts Agent Managed Agents Per-session containers, SSE event stream, Skills + MCP

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

Cloud-provider access. Claude Platform on AWS is Anthropic-operated with same-day API parity — see shared/claude-platform-on-aws.md for client setup. For per-feature availability on Claude Platform on AWS, Amazon Bedrock, Google Vertex AI, and Microsoft Foundry, see shared/platform-availability.md — that table is the single source of truth in this skill; do not infer availability from anywhere else.

Decision Tree

What does your application need?

0. Which provider?
   ├── First-party API or Claude Platform on AWS → continue (full surface available; per-feature exceptions in shared/platform-availability.md).
   └── Amazon Bedrock, Google Vertex AI, or Microsoft Foundry → Claude API (+ tool use for agents); see shared/platform-availability.md for per-feature support.

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

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

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

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

Should I Build an Agent?

Before choosing the agent tier, check all four criteria:

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

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

Architecture

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

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

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

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

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

Current Models (cached: 2026-06-24)

Model Model ID Context Input $/1M Output $/1M
Claude Fable 5 claude-fable-5 1M $10.00 $50.00
Claude Mythos 5 (Project Glasswing only) claude-mythos-5 1M $10.00 $50.00
Claude Opus 4.8 claude-opus-4-8 1M $5.00 $25.00
Claude Opus 4.7 claude-opus-4-7 1M $5.00 $25.00
Claude Opus 4.6 claude-opus-4-6 1M $5.00 $25.00
Claude Sonnet 5 claude-sonnet-5 1M $3.00 ($2.00 intro through 2026-08-31) $15.00 ($10.00 intro)
Claude Sonnet 4.6 claude-sonnet-4-6 1M $3.00 $15.00
Claude Haiku 4.5 claude-haiku-4-5 200K $1.00 $5.00

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

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

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

  • Thinking is always on — omit the thinking parameter entirely (or send {type: "adaptive"}). Any other explicit configuration is rejected: {type: "disabled"} and {type: "enabled", budget_tokens: N} both return a 400. Control depth with output_config.effort (supports low through xhigh and max).
  • The raw chain of thought is never returned — responses carry regular thinking blocks (not redacted_thinking): display: "summarized" returns a readable summary, "omitted" (the default) leaves the thinking field as an empty string. Replay rules: pass thinking blocks back exactly as received on the same model (including empty-text blocks — the API rejects modified blocks, not read ones); a different model drops them from the prompt (typically silently — not an error; the drop happens before pricing, so dropped blocks aren't billed and there's nothing to strip). Regular thinking blocks from other models replay across models freely.
  • Tokenizer — same tokenizer as Opus 4.8 (introduced with Opus 4.7). Token counts are roughly unchanged when migrating from Opus 4.7/4.8; per-token pricing differs. Coming from Opus 4.6, Sonnet, Haiku, or older, re-baseline with count_tokens.
  • refusal stop reason — handle it, and opt into fallbacks by default — safety classifiers may decline a request (HTTP 200, stop_reason: "refusal", with a stop_details category). A pre-output refusal has an empty content array and is not billed at all; a mid-stream refusal bills the already-streamed output — discard the partial output. Always check stop_reason before reading content. Recovery is opt-in on the API: most Claude consumer surfaces ship with built-in Claude Opus 4.8 fallbacks, but an API request that doesn't opt in simply stops on a refusal — and false positives on benign adjacent work (security tooling, life-sciences tasks) do happen. When you write claude-fable-5 code, include the server-side fallbacks parameter by default (betas: ["server-side-fallback-2026-06-01"] + fallbacks: [{"model": "claude-opus-4-8"}]; Claude API and Claude Platform on AWS): a declined request is transparently re-served by the fallback model inside the same call, with credit-style repricing applied automatically (a decline before any output isn't billed; the rescue bills at the fallback model's own rates). Tell the user you've enabled it; drop it only if they decline. The GA SDKs' client-side BetaRefusalFallbackMiddleware + BetaFallbackState handle retry everywhere server-side fallbacks aren't supported (incl. Amazon Bedrock, Vertex AI, Microsoft Foundry); fallback credit refunds the cache-switch cost of client-side retries. Code examples: the Refusal Fallbacks section of your language's claude-api doc; full semantics in the migration guide's refusal section.
  • No assistant prefill — same as the rest of the 4.6+ family.
  • 30-day data retention required — Claude Fable 5 is not available under zero data retention; requests from an org whose retention configuration doesn't meet the requirement return 400 invalid_request_error.
  • Longer turns, different prompting — single requests on hard tasks can run many minutes (plan timeouts/streaming/progress UX); effort sweeps should include low/medium for routine work; prompts written for prior models are often too prescriptive and reduce output quality. See shared/model-migration.md → Migrating to Claude Fable 5 → Behavioral shifts (prompt-tunable) for the recommended prompt snippets (anti-overplanning, no-tidying, grounded progress claims, boundaries, async sub-agents, memory, send_to_user).

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

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

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

Authentication (Quick Reference)

An unset ANTHROPIC_API_KEY does NOT mean there are no credentials. The SDKs and the ant CLI resolve credentials in this order (first match wins): ANTHROPIC_API_KEY → ANTHROPIC_AUTH_TOKEN → the ANTHROPIC_PROFILE-selected or active OAuth profile from ant auth login → Workload Identity Federation env vars → the default profile on disk. A bare Anthropic() / new Anthropic() / anthropic.NewClient() works after ant auth login with no env var set.

When you need to call the API and ANTHROPIC_API_KEY is unset, don't ask the user for a key. First run ant auth status — it shows which credential source and profile is active. If it reports an active profile:

  • SDK code or ant CLI: just run it. The zero-arg client constructor and every ant … subcommand pick up the profile automatically — no env var needed.
  • Raw curl / HTTP: get a short-lived token with ant auth print-credentials --access-token and send it as Authorization: Bearer <token> plus the header anthropic-beta: oauth-2025-04-20 (OAuth tokens go on Authorization: Bearer, not x-api-key: — converting a curl from an API key is a header change, not a key swap). Always pass --access-token; the no-flag form prints JSON, not a bare token.

Only ask the user for a key if ant auth status reports no active credential source (or ant itself isn't installed). Suggest ant auth login as the first option — it stores a profile under ~/.config/anthropic/ that the SDKs read automatically — and an exported ANTHROPIC_API_KEY as the alternative.

Full auth details (named profiles, scopes, the API-key-shadows-profile trap, refresh-token expiry): shared/anthropic-cli.md.

Thinking & Effort (Quick Reference)

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

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

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

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

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

Compaction (Quick Reference)

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

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

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

Prompt Caching (Quick Reference)

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

Mid-conversation operator instructions (Claude Opus 4.8 only; no beta header): append {"role": "system", ...} to messages[] instead of editing top-level system. Preserves the cached history prefix and is the prompt-injection-safe operator channel. See shared/prompt-caching.md § Mid-conversation system messages.

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

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

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

Fast Mode (Quick Reference)

Research preview, Opus 4.8 / 4.7 only. Opus 4.7 fast mode is deprecated — after removal, speed: "fast" on 4.7 returns an error. Opus 4.8 is the durable fast-capable tier. Fast mode runs the same model at up to 2.5x higher output tokens per second, at premium pricing. Three things are required on every request: use the beta messages endpoint (client.beta.messages.…), pass the beta flag fast-mode-2026-02-01, and set speed: "fast" as a top-level request parameter (not a header, not in extra_body).

client.beta.messages.create(
    model="claude-opus-4-8", max_tokens=4096,
    speed="fast", betas=["fast-mode-2026-02-01"],
    messages=[...],
)
Language Beta flag Speed parameter
Python betas=["fast-mode-2026-02-01"] speed="fast"
TypeScript / Ruby betas: ["fast-mode-2026-02-01"] speed: "fast"
Go []anthropic.AnthropicBeta{anthropic.AnthropicBetaFastMode2026_02_01} Speed: anthropic.BetaMessageNewParamsSpeedFast
Java .addBeta(AnthropicBeta.FAST_MODE_2026_02_01) .speed(MessageCreateParams.Speed.FAST)
C# Betas = ["fast-mode-2026-02-01"] Speed = Speed.Fast (Anthropic.Models.Beta.Messages)
PHP betas: ['fast-mode-2026-02-01'] speed: 'fast'
cURL anthropic-beta: fast-mode-2026-02-01 header "speed": "fast" in body

response.usage.speed reports which speed was used. Fast mode has its own rate limit separate from standard Opus; on 429, either retry after the retry-after delay or drop speed and fall back to standard (note: switching speed invalidates prompt cache). Not available with Batch API, Priority Tier, Claude Platform on AWS, or third-party platforms.

Task Budgets (Quick Reference)

Beta, Fable 5 / Sonnet 5 / Opus 4.8 / 4.7. A task budget gives Claude a token ceiling for an agentic loop so it paces itself and finishes gracefully instead of being cut off. Set task_budget inside output_config on client.beta.messages.stream(...) with beta flag task-budgets-2026-03-13 — use streaming so the large max_tokens doesn't hit HTTP timeouts:

with client.beta.messages.stream(
    model="claude-opus-4-8", max_tokens=128000,
    output_config={"effort": "high", "task_budget": {"type": "tokens", "total": 64000}},
    betas=["task-budgets-2026-03-13"],
    messages=[...], tools=[...],
) as stream:
    response = stream.get_final_message()

task_budget fields: type (always "tokens"), total, and optional remaining (defaults to total). The server injects a countdown marker Claude sees during generation; the budget counts what Claude generates and the tool results it reads this turn — not the full history you resend each request.

Observing spend: accumulate response.usage.output_tokens (plus the token count of the tool-result blocks you append) across loop iterations if you want to display progress. Leave remaining unset in the normal loop — the server tracks the countdown itself, and passing a client-computed remaining while also resending full history under-reports the budget. Only pass remaining when you compact or rewrite history between requests and the server can no longer derive prior spend.

Provider Clients (Quick Reference)

When targeting Claude on a third-party platform, use that platform's dedicated client class — not the first-party Anthropic() client with a base_url override. After construction the client exposes the same messages.create / .stream surface as the first-party SDK.

Amazon Bedrock

Use the Mantle client (Messages-API Bedrock endpoint). Bedrock model IDs take an anthropic. prefix (e.g. "anthropic.claude-opus-4-8"). Region is required.

Language Client
Python from anthropic import AnthropicBedrockMantle → AnthropicBedrockMantle(aws_region="…")
TypeScript import { AnthropicBedrockMantle } from "@anthropic-ai/bedrock-sdk" → new AnthropicBedrockMantle({ awsRegion: "…" })
Go bedrock.NewMantleClient(ctx, bedrock.MantleClientConfig{ AWSRegion: "…" })
Java AnthropicOkHttpClient.builder().backend(BedrockMantleBackend.fromEnv()).build() (from com.anthropic.bedrock.backends)
C# new AnthropicBedrockMantleClient(new() { AwsRegion = "…" }) (package Anthropic.Bedrock)
PHP use Anthropic\Bedrock\MantleClient; → new MantleClient(awsRegion: '…')
Ruby Anthropic::BedrockMantleClient.new(aws_region: "…")

AnthropicBedrock / BedrockClient / BedrockBackend (without Mantle) are the legacy bedrock-runtime InvokeModel path — prefer the Mantle client for new code.

Microsoft Foundry

Language Client
Python from anthropic import AnthropicFoundry → AnthropicFoundry(api_key=…, resource="…")
TypeScript import AnthropicFoundry from "@anthropic-ai/foundry-sdk" → new AnthropicFoundry({ … })
Java AnthropicOkHttpClient.builder().backend(FoundryBackend.fromEnv()).build() (from com.anthropic.foundry.backends)
C# new AnthropicFoundryClient(new AnthropicFoundryApiKeyCredentials(…)) (package Anthropic.Foundry)
PHP Foundry\Client::withCredentials(…)

The Go and Ruby SDKs do not currently support Foundry. For Ruby, use the standard Anthropic::Client.new(base_url: "<foundry endpoint>") as a fallback (Entra ID auth is not built in). For Claude Platform on AWS, see shared/claude-platform-on-aws.md.

Google Cloud Vertex AI

Two required constructor args: GCP project_id and region. Vertex model IDs take no prefix — current-generation models (Opus 4.8/4.7/4.6, Sonnet 5, Sonnet 4.6) use the bare first-party ID (e.g. "claude-opus-4-8"); dated-snapshot models use an @ version separator (e.g. claude-opus-4-5@20251101, not claude-opus-4-5-20251101). Auth is GCP ADC (gcloud auth application-default login); no Anthropic API key. region can be "global" (recommended), a multi-region ("us"/"eu"), or a specific region. After construction, use the same messages.create / .stream surface.

Language Client
Python from anthropic import AnthropicVertex → AnthropicVertex(project_id="…", region="…") (install "anthropic[vertex]")
TypeScript import { AnthropicVertex } from "@anthropic-ai/vertex-sdk" → new AnthropicVertex({ projectId, region })
Go import "github.com/anthropics/anthropic-sdk-go/vertex" → anthropic.NewClient(vertex.WithGoogleAuth(ctx, region, projectID))
Java AnthropicOkHttpClient.builder().backend(VertexBackend.builder().region("…").project("…").build()).build() (from com.anthropic.vertex.backends)
C# new AnthropicClient { Backend = new VertexBackend(projectId, region) } (package Anthropic.Vertex)
PHP use Anthropic\Vertex; → Vertex\Client::fromEnvironment(location: '…', projectId: '…') — note location, not region
Ruby Anthropic::VertexClient.new(region: "…", project_id: "…")

Context Editing (Quick Reference)

Beta. Context editing clears old tool results or thinking blocks from the conversation before the model sees it; it is not compaction (which summarizes). On client.beta.messages.* with beta context-management-2025-06-27, pass context_management.edits with a strategy type:

client.beta.messages.create(
    model="claude-opus-4-8", max_tokens=4096,
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
    tools=[...], messages=[...],
)

Strategy types: clear_tool_uses_20250919 (clears old tool results; optional clear_tool_inputs: true also clears the tool_use params) and clear_thinking_20251015 (clears thinking blocks). Do not use compact_20260112 or beta compact-2026-01-12 — those are the separate compaction feature.

Mid-Conversation System Messages (Quick Reference)

Claude Opus 4.8 only; no beta header. Append {"role": "system", "content": "…"} to the messages array (not the top-level system field) to add an operator instruction mid-conversation without invalidating the cached prefix. Use the regular client.messages.create — there is no beta. A mid-conversation system message must follow a user message (or an assistant message ending in server-tool use), and must be either the last entry in messages or be followed by an assistant turn — it cannot be messages[0]. Availability: shared/platform-availability.md. See shared/prompt-caching.md § Mid-conversation system messages.

Managed Agents (Beta)

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

Availability: shared/platform-availability.md. For agents on Bedrock / Vertex / Foundry (where Managed Agents is unsupported), use Claude API + tool use.

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

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

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

Subcommand Action
managed-agents-onboard Walk the user through setting up a Managed Agent from scratch. Read shared/managed-agents-onboarding.md immediately and follow its interview script: describe → configure the agent (propose, don't interrogate) → environment → session (same arc as the Console quickstart, auth deferred to the session step) — defaults and inline suggestions do the work, with a silent viability gate (job vs tools/credentials/data) before any code is emitted. Do not summarize — run the interview.

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

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

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

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

Server Tools (Quick Reference)

Server-side tools run on Anthropic's infrastructure — no client-side execution loop. Declare in tools; results arrive as content blocks in the same response. No beta header unless noted. Prefer the latest type variant your model supports. The _20260209 web search / web fetch variants below (dynamic filtering) require Opus 4.8/4.7/4.6, Sonnet 5, or Sonnet 4.6; the basic variants for older models are listed after the table.

Tool type name Key optional params Result block type
Web search web_search_20260209 web_search max_uses, allowed_domains/blocked_domains, user_location web_search_tool_result → .content is a list of web_search_result
Web fetch web_fetch_20260209 web_fetch max_uses, allowed_domains/blocked_domains, citations, max_content_tokens web_fetch_tool_result → .content is a web_fetch_result with a document block
Code execution code_execution_20260521 code_execution none bash_code_execution_tool_result → .content.stdout / .stderr / .return_code
Tool search (regex) tool_search_tool_regex_20251119 tool_search_tool_regex mark other tools defer_loading: true tool_search_tool_result
Tool search (BM25) tool_search_tool_bm25_20251119 tool_search_tool_bm25 mark other tools defer_loading: true tool_search_tool_result

web_search_20260209 / web_fetch_20260209 have built-in dynamic filtering — code execution runs under the hood, so do not separately declare code_execution in tools (a second execution environment confuses the model). For models older than Opus 4.6 / Sonnet 4.6, use the basic variants web_search_20250305 / web_fetch_20250910 instead; on Vertex AI only basic web_search_20250305 is available. code_execution_20260120 (REPL persistence + programmatic tool calling) runs on Opus 4.5+ / Sonnet 4.5+. Go SDK only: code_execution_20260521 lives under client.Beta.Messages.New with Betas: []anthropic.AnthropicBeta{"code-execution-2025-08-25"} (other languages use plain client.messages.create); code_execution_20260120 uses the non-beta client.Messages.New in Go like everywhere else. Web fetch only fetches URLs already present in the conversation. Provider availability varies by tool — see shared/platform-availability.md. See shared/tool-use-concepts.md for pause_turn handling.

Document & File Input (Quick Reference)

PDF (base64, no beta): {"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": <b64 string>}} in user content, placed before the text block. Base64 string must have no newlines. Limits: 32 MB request, 600 pages (100 for 200k-context models). Java: ContentBlockParam.ofDocument(DocumentBlockParam... Base64PdfSource.builder().data(...)).

Files API (beta files-api-2025-04-14): upload via client.beta.files.upload(...) → response id is the file_id. Reference it as {"type": "document", "source": {"type": "file", "file_id": "..."}} for PDF/text, or {"type": "image", ...} for images — the content-block type must match the file's MIME type. The beta header is required on both the upload and the messages.create that references the file. Availability: shared/platform-availability.md.

Citations (no beta): set citations: {enabled: true} on each document content block (all or none). Response splits into multiple text blocks; cited blocks carry a citations array. Each citation has cited_text, document_index, document_title, and a location by type: char_location (start_char_index/end_char_index) for plain text, page_location (start_page_number/end_page_number, 1-indexed) for PDF, content_block_location for custom content. Incompatible with output_config.format.

Tool Use Patterns (Quick Reference)

Strict tool use (no beta): set strict: true as a top-level field on the tool definition (alongside name/description/input_schema), not on tool_choice. Schema must have additionalProperties: false + required. Guarantees tool_use.input validates exactly. Go: Strict: anthropic.Bool(true) + additionalProperties via InputSchema.ExtraFields; Java: .strict(true) + .putAdditionalProperty("additionalProperties", JsonValue.from(false)).

Parallel tool use (default on): one assistant message may contain multiple tool_use blocks. Execute them concurrently, then return all tool_result blocks in a single user message (don't split across multiple messages). For a failed tool, return tool_result with is_error: true — don't drop it.

Tool Runner (SDK beta helper): drives the tool-call loop for you via client.beta.messages.*. Python: @beta_tool decorator + client.beta.messages.tool_runner(...) → runner.until_done(). TypeScript: betaZodTool({...}) from @anthropic-ai/sdk/helpers/beta/zod + client.beta.messages.toolRunner(...) → await runner. Go: toolrunner.NewBetaToolFromJSONSchema(...) + client.Beta.Messages.NewToolRunner(...) → .RunToCompletion(ctx). Java requires .addBeta("structured-outputs-2025-11-13"). Ruby: Anthropic::BaseTool subclass + client.beta.messages.tool_runner(...). PHP: BetaRunnableTool + ->toolRunner(...). C#: raw JSON-schema tools + BetaToolRunner via client.Beta.Messages.ToolRunner(...).

Programmatic tool calling (no beta header): Claude calls your custom tool from inside code execution. Add {"type": "code_execution_20260120", "name": "code_execution"} and set "allowed_callers": ["code_execution_20260120"] on your custom tool. Opus 4.5+ / Sonnet 4.5+ (availability: shared/platform-availability.md). When responding to a pending programmatic call, the user message must contain only tool_result blocks (no text). Not compatible with strict: true, disable_parallel_tool_use, forced tool_choice, or MCP tools.

Other API Surfaces (Quick Reference)

Message Batches (no beta; availability: shared/platform-availability.md): client.messages.batches.create(requests=[{custom_id, params}, ...]) → poll client.messages.batches.retrieve(id).processing_status until "ended" → stream client.messages.batches.results(id). Each result has .custom_id + .result.type (succeeded/errored/canceled/expired); on success read .result.message.content. Python wraps requests as Request(custom_id=..., params=MessageCreateParamsNonStreaming(...)). Results arrive in any order — key by custom_id, never by position.

Models API (no beta; availability: shared/platform-availability.md): client.models.list() (auto-paginates) and client.models.retrieve("claude-opus-4-8"). Each model object has id, display_name, created_at, and — since Mar 2026 — max_input_tokens (the context window), max_tokens (the output cap), and capabilities. There is no context_window field.

Stop details (GA, Opus 4.7+): response.stop_details is populated only when stop_reason == "refusal" (fields: type: "refusal", category: "cyber"|"bio"|null, explanation). It is null for every other stop_reason (end_turn, max_tokens, tool_use, pause_turn, …) — always guard before reading.

Client config (no beta): timeout default 10 min; units differ by SDK — Python/Ruby: seconds; TypeScript: milliseconds; Go option.WithRequestTimeout(time.Duration); Java Duration; C# TimeSpan. TS scales the default up to 60 min for large max_tokens on non-streaming requests; Java does so for streaming requests (Java non-streaming scales 30s–10 min). max_retries/maxRetries default 2 (retries 408/409/429/5xx + connection errors). base_url (or ANTHROPIC_BASE_URL env). Per-request override: Python client.with_options(timeout=5.0).messages.create(...); TS client.messages.create({...}, {timeout: 5_000}); Ruby request_options: {timeout: 5}. Timeouts are retried — wall-clock can reach timeout × (max_retries+1).

Workload Identity Federation (Quick Reference)

GA, no beta header. Construct the normal zero-arg client (Anthropic() / new Anthropic() / anthropic.NewClient() / AnthropicOkHttpClient.fromEnv()); the SDK auto-detects WIF when all of ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID, and ANTHROPIC_IDENTITY_TOKEN_FILE (or ANTHROPIC_IDENTITY_TOKEN) are set, exchanges the JWT at /v1/oauth/token, and auto-refreshes. ANTHROPIC_WORKSPACE_ID does not gate activation — required only when the federation rule spans multiple workspaces (else 400 workspace_id_required), optional for single-workspace rules. ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN (even empty) outrank WIF, and a set ANTHROPIC_PROFILE also wins over the federation env vars (a missing named profile is an error, not a fall-through) — unset all three.

Reference Documentation

The relevant documentation for your detected language is included below in <doc> tags. Each tag has a path attribute showing its original file path. Use this to find the right section:

Quick Task Reference

All SDK languages use the same per-language claude-api/ directory layout (cURL: curl/examples.md). Not every language has every file — if a file is absent, that feature's example is not yet documented for that language; fall back to the cURL shape or WebFetch the SDK repo.

Single text classification/summarization/extraction/Q&A: → Refer to python/claude-api/README.md

Chat UI or real-time response display: → Refer to python/claude-api/README.md + python/claude-api/streaming.md

Long-running conversations (may exceed context window): → Refer to python/claude-api/README.md — see Compaction section

Migrating to a newer model or replacing a retired model: → Refer to shared/model-migration.md

Prompt caching / optimize caching / "why is my cache hit rate low": → Refer to shared/prompt-caching.md + python/claude-api/README.md (Prompt Caching section)

Count tokens in a file / prompt / diff ("how many tokens is X"): → Refer to shared/token-counting.md — use messages.count_tokens, never tiktoken

Function calling / tool use / agents: → Refer to python/claude-api/README.md + shared/tool-use-concepts.md + python/claude-api/tool-use.md

Batch processing (non-latency-sensitive): → Refer to python/claude-api/README.md + python/claude-api/batches.md

File uploads across multiple requests: → Refer to python/claude-api/README.md + python/claude-api/files-api.md

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

Anthropic CLI (ant) — terminal access, version-controlled agent/environment YAML, scripting: → Refer to shared/anthropic-cli.md

Managed Agents (server-managed stateful agents): → Refer to shared/managed-agents-overview.md and the rest of the shared/managed-agents-*.md files. For Python, TypeScript, Go, Ruby, PHP, and Java, read the managed-agents/README.md in the language folder for code examples. For cURL, read curl/managed-agents.md. C# has beta Managed Agents support — use curl/managed-agents.md as the wire-level reference (the C# SDK mirrors it via client.Beta.Agents; see csharp/claude-api/README.md).

Error handling: → Refer to shared/error-codes.md

Latest docs via WebFetch: → Refer to shared/live-sources.md for URLs

Included Documentation

Claude API — Python

Installation

pip install anthropic

Client Initialization

import anthropic

# Default — resolves credentials from the environment:
# ANTHROPIC_API_KEY, or ANTHROPIC_AUTH_TOKEN, or an `ant auth login` profile.
# Prefer this for local dev; don't hardcode a key.
client = anthropic.Anthropic()

# Explicit API key (only when you must inject a specific key)
client = anthropic.Anthropic(api_key="your-api-key")

# Async client
async_client = anthropic.AsyncAnthropic()

Client Configuration

Per-request overrides

Use with_options() to override client settings for a single call without mutating the client:

client.with_options(timeout=5.0, max_retries=5).messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)

Timeouts

Default request timeout is 10 minutes. Pass a float (seconds) or an httpx.Timeout for granular control. On timeout the SDK raises anthropic.APITimeoutError (and retries per max_retries).

import httpx

client = anthropic.Anthropic(timeout=20.0)
client = anthropic.Anthropic(
    timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0),
)

Retries

The SDK auto-retries connection errors, 408, 409, 429, and ≥500 with exponential backoff (default 2 retries). Set max_retries on the client or via with_options(); max_retries=0 disables.

Async performance (aiohttp backend)

For high-concurrency async workloads, install anthropic[aiohttp] and pass DefaultAioHttpClient instead of the default httpx backend:

from anthropic import AsyncAnthropic, DefaultAioHttpClient

async with AsyncAnthropic(http_client=DefaultAioHttpClient()) as client:
    ...

Custom HTTP client (proxy, base URL)

Use DefaultHttpxClient / DefaultAsyncHttpxClient — not raw httpx.Client — so the SDK's default timeouts and connection limits are preserved:

from anthropic import Anthropic, DefaultHttpxClient

client = Anthropic(
    base_url="http://my.test.server.example.com:8083",  # or ANTHROPIC_BASE_URL env var
    http_client=DefaultHttpxClient(proxy="http://my.test.proxy.example.com"),
)

Logging

Set ANTHROPIC_LOG=debug (or info) to enable SDK logging via the standard logging module.

Basic Message Request

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[
        {"role": "user", "content": "What is the capital of France?"}
    ]
)
# response.content is a list of content block objects (TextBlock, ThinkingBlock,
# ToolUseBlock, ...). Check .type before accessing .text.
for block in response.content:
    if block.type == "text":
        print(block.text)

System Prompts

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    system="You are a helpful coding assistant. Always provide examples in Python.",
    messages=[{"role": "user", "content": "How do I read a JSON file?"}]
)

Mid-conversation system messages (model-gated)

For operator instructions that arrive mid-conversation (mode switches, injected state), append {"role": "system", ...} to messages instead of editing top-level system — this preserves the cached prefix and carries operator authority. Must follow a user message (or an assistant message ending in server-tool use), and must be either the last entry in messages or be followed by an assistant turn; cannot be messages[0]. Unsupported models return a 400 (role 'system' is not supported on this model). See shared/prompt-caching.md for when to use this vs. top-level system.

response = client.messages.create(
    model=MODEL_ID,  # must support mid-conversation system messages
    max_tokens=16000,
    system=[{"type": "text", "text": STABLE_SYSTEM, "cache_control": {"type": "ephemeral"}}],
    messages=history + [
        {"role": "user", "content": user_message},
        {"role": "system", "content": "Terse mode enabled — keep responses under 40 words."},
    ],
)  # No beta header needed — use regular client.messages.create

Vision (Images)

Base64

import base64

with open("image.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "image",
                "source": {
                    "type": "base64",
                    "media_type": "image/png",
                    "data": image_data
                }
            },
            {"type": "text", "text": "What's in this image?"}
        ]
    }]
)

URL

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "image",
                "source": {
                    "type": "url",
                    "url": "https://example.com/image.png"
                }
            },
            {"type": "text", "text": "Describe this image"}
        ]
    }]
)

Prompt Caching

Cache large context to reduce costs (up to 90% savings). Caching is a prefix match — any byte change anywhere in the prefix invalidates everything after it. For placement patterns, architectural guidance (frozen system prompt, deterministic tool order, where to put volatile content), and the silent-invalidator audit checklist, read shared/prompt-caching.md.

Automatic Caching (Recommended)

Use top-level cache_control to automatically cache the last cacheable block in the request — no need to annotate individual content blocks:

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    cache_control={"type": "ephemeral"},  # auto-caches the last cacheable block
    system="You are an expert on this large document...",
    messages=[{"role": "user", "content": "Summarize the key points"}]
)

Manual Cache Control

For fine-grained control, add cache_control to specific content blocks:

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    system=[{
        "type": "text",
        "text": "You are an expert on this large document...",
        "cache_control": {"type": "ephemeral"}  # default TTL is 5 minutes
    }],
    messages=[{"role": "user", "content": "Summarize the key points"}]
)

# With explicit TTL (time-to-live)
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    system=[{
        "type": "text",
        "text": "You are an expert on this large document...",
        "cache_control": {"type": "ephemeral", "ttl": "1h"}  # 1 hour TTL
    }],
    messages=[{"role": "user", "content": "Summarize the key points"}]
)

Verifying Cache Hits

print(response.usage.cache_creation_input_tokens)  # tokens written to cache (~1.25x cost)
print(response.usage.cache_read_input_tokens)      # tokens served from cache (~0.1x cost)
print(response.usage.input_tokens)                 # uncached tokens (full cost)

If cache_read_input_tokens is zero across repeated identical-prefix requests, a silent invalidator is at work — datetime.now() or a UUID in the system prompt, unsorted json.dumps(), or a varying tool set. See shared/prompt-caching.md for the full audit table.

Extended Thinking

Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6: Use adaptive thinking. budget_tokens is removed on Fable 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6. Older models: Use thinking: {type: "enabled", budget_tokens: N} (must be < max_tokens, min 1024).

# Fable 5 / Opus 4.8 / 4.7 / 4.6: adaptive thinking (recommended)
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},  # display opt-in: default is omitted (empty thinking text) on Fable 5 / Mythos 5 / Opus 4.8 / 4.7
    output_config={"effort": "high"},  # low | medium | high | max
    messages=[{"role": "user", "content": "Solve this step by step..."}]
)

# Access thinking and response
for block in response.content:
    if block.type == "thinking":
        print(f"Thinking: {block.thinking}")
    elif block.type == "text":
        print(f"Response: {block.text}")

Error Handling

import anthropic

try:
    response = client.messages.create(...)
except anthropic.BadRequestError as e:
    print(f"Bad request: {e.message}")
except anthropic.AuthenticationError:
    print("Invalid API key")
except anthropic.PermissionDeniedError:
    print("API key lacks required permissions")
except anthropic.NotFoundError:
    print("Invalid model or endpoint")
except anthropic.RateLimitError as e:
    retry_after = int(e.response.headers.get("retry-after", "60"))
    print(f"Rate limited. Retry after {retry_after}s.")
except anthropic.APIStatusError as e:
    if e.status_code >= 500:
        print(f"Server error ({e.status_code}). Retry later.")
    else:
        print(f"API error: {e.message}")
except anthropic.APIConnectionError:
    print("Network error. Check internet connection.")

Response Helpers

Every response object exposes _request_id (populated from the request-id header) — log it when reporting failures to Anthropic. Despite the underscore prefix, this property is public.

message = client.messages.create(...)
print(message._request_id)       # req_018EeWyXxfu5pfWkrYcMdjWG
print(message.to_json())          # serialize the Pydantic model
print(message.to_dict())          # plain dict

To access raw headers or other response metadata, use .with_raw_response:

raw = client.messages.with_raw_response.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
print(raw.headers.get("request-id"))
message = raw.parse()  # the Message object messages.create() would have returned

Multi-Turn Conversations

The API is stateless — send the full conversation history each time.

class ConversationManager:
    """Manage multi-turn conversations with the Claude API."""

    def __init__(self, client: anthropic.Anthropic, model: str, system: str = None):
        self.client = client
        self.model = model
        self.system = system
        self.messages = []

    def send(self, user_message: str, **kwargs) -> str:
        """Send a message and get a response."""
        self.messages.append({"role": "user", "content": user_message})

        response = self.client.messages.create(
            model=self.model,
            max_tokens=kwargs.get("max_tokens", 16000),
            system=self.system,
            messages=self.messages,
            **kwargs
        )

        assistant_message = next(
            (b.text for b in response.content if b.type == "text"), ""
        )
        self.messages.append({"role": "assistant", "content": assistant_message})

        return assistant_message

# Usage
conversation = ConversationManager(
    client=anthropic.Anthropic(),
    model="claude-opus-4-8",
    system="You are a helpful assistant."
)

response1 = conversation.send("My name is Alice.")
response2 = conversation.send("What's my name?")  # Claude remembers "Alice"

Rules:

  • Consecutive same-role messages are allowed — the API combines them into a single turn
  • First message must be user
  • role: "system" messages are allowed mid-conversation on supporting models (no beta header needed) — see § Mid-conversation system messages above

Compaction (long conversations)

Beta, Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6. When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a compaction block; you must pass it back on subsequent requests — append response.content, not just the text.

import anthropic

client = anthropic.Anthropic()
messages = []

def chat(user_message: str) -> str:
    messages.append({"role": "user", "content": user_message})

    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-4-8",
        max_tokens=16000,
        messages=messages,
        context_management={
            "edits": [{"type": "compact_20260112"}]
        }
    )

    # Append full content — compaction blocks must be preserved
    messages.append({"role": "assistant", "content": response.content})

    return next(block.text for block in response.content if block.type == "text")

# Compaction triggers automatically when context grows large
print(chat("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now add rate limiting and error handling"))

Stop Reasons

The stop_reason field in the response indicates why the model stopped generating:

Value Meaning
end_turn Claude finished its response naturally
max_tokens Hit the max_tokens limit — increase it or use streaming
stop_sequence Hit a custom stop sequence
tool_use Claude wants to call a tool — execute it and continue
pause_turn Model paused and can be resumed (agentic flows)
refusal Claude refused for safety reasons — check stop_details

Structured Stop Details

When stop_reason is "refusal", the response includes a stop_details object with structured information about the refusal:

if response.stop_reason == "refusal" and response.stop_details:
    print(f"Category: {response.stop_details.category}")   # e.g. "cyber", "bio", "reasoning_extraction", "frontier_llm", or None — see docs for the full set
    print(f"Explanation: {response.stop_details.explanation}")

Refusal Fallbacks (Claude Fable 5) — opt in by default

Fallbacks are opt-in: without them a refused request simply stops. Include the server-side fallbacks parameter in claude-fable-5 code by default — on a policy decline the API re-runs the same request on the fallback model inside the same call. A decline before any output isn't billed (a mid-stream decline bills the streamed partial); the rescue bills at the fallback model's own rates, with cache repricing applied automatically.

response = client.beta.messages.create(
    model="claude-fable-5",
    max_tokens=16000,
    betas=["server-side-fallback-2026-06-01"],
    fallbacks=[{"model": "claude-opus-4-8"}],
    messages=[{"role": "user", "content": "..."}],
)

# Switch points: one fallback block per model that ran and declined this turn
for block in response.content:
    if block.type == "fallback":
        print(f"{block.from_.model} declined; {block.to.model} continued")

# Served-by signal — covers sticky turns, which carry no fallback block.
# Pair with stop_reason: the fallback model can itself refuse.
fallback_ran = any(
    entry.type == "fallback_message" for entry in response.usage.iterations or []
)
if fallback_ran and response.stop_reason != "refusal":
    print(f"Served by {response.model}")

A stop_reason: "refusal" on the final response means the whole chain refused. The header must be exactly server-side-fallback-2026-06-01; the parameter is rejected on the Batches API and unavailable on Amazon Bedrock, Vertex AI, and Microsoft Foundry — register the client-side BetaRefusalFallbackMiddleware on the client there instead. Full semantics (sticky routing, billing, streaming, echoing fallback turns back): shared/model-migration.md → Migrating to Claude Fable 5 → refusal stop reason.

Cost Optimization Strategies

1. Use Prompt Caching for Repeated Context

# Automatic caching (simplest — caches the last cacheable block)
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    cache_control={"type": "ephemeral"},
    system=large_document_text,  # e.g., 50KB of context
    messages=[{"role": "user", "content": "Summarize the key points"}]
)

# First request: full cost
# Subsequent requests: ~90% cheaper for cached portion

2. Choose the Right Model

# Default to Opus for most tasks
response = client.messages.create(
    model="claude-opus-4-8",  # $5.00/$25.00 per 1M tokens
    max_tokens=16000,
    messages=[{"role": "user", "content": "Explain quantum computing"}]
)

# Use Sonnet for high-volume production workloads
standard_response = client.messages.create(
    model="claude-sonnet-5",  # $3.00/$15.00 per 1M tokens
    max_tokens=16000,
    messages=[{"role": "user", "content": "Summarize this document"}]
)

# Use Haiku only for simple, speed-critical tasks
simple_response = client.messages.create(
    model="claude-haiku-4-5",  # $1.00/$5.00 per 1M tokens
    max_tokens=256,
    messages=[{"role": "user", "content": "Classify this as positive or negative"}]
)

3. Use Token Counting Before Requests

count_response = client.messages.count_tokens(
    model="claude-opus-4-8",
    messages=messages,
    system=system
)

estimated_input_cost = count_response.input_tokens * 0.000005  # $5/1M tokens
print(f"Estimated input cost: ${estimated_input_cost:.4f}")

Retry with Exponential Backoff

Note: The Anthropic SDK automatically retries rate limit (429) and server errors (5xx) with exponential backoff. You can configure this with max_retries (default: 2). Only implement custom retry logic if you need behavior beyond what the SDK provides.

import time
import random
import anthropic

def call_with_retry(
    client: anthropic.Anthropic,
    max_retries: int = 5,
    base_delay: float = 1.0,
    max_delay: float = 60.0,
    **kwargs
):
    """Call the API with exponential backoff retry."""
    last_exception = None

    for attempt in range(max_retries):
        try:
            return client.messages.create(**kwargs)
        except anthropic.RateLimitError as e:
            last_exception = e
        except anthropic.APIStatusError as e:
            if e.status_code >= 500:
                last_exception = e
            else:
                raise  # Client errors (4xx except 429) should not be retried

        delay = min(base_delay * (2 ** attempt) + random.uniform(0, 1), max_delay)
        print(f"Retry {attempt + 1}/{max_retries} after {delay:.1f}s")
        time.sleep(delay)

    raise last_exception

Message Batches API — Python

The Batches API (POST /v1/messages/batches) processes Messages API requests asynchronously at 50% of standard prices.

Key Facts

  • Up to 100,000 requests or 256 MB per batch
  • Most batches complete within 1 hour; maximum 24 hours
  • Results available for 29 days after creation
  • 50% cost reduction on all token usage
  • All Messages API features supported (vision, tools, caching, etc.)

Create a Batch

import anthropic
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()

message_batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id="request-1",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-8",
                max_tokens=16000,
                messages=[{"role": "user", "content": "Summarize climate change impacts"}]
            )
        ),
        Request(
            custom_id="request-2",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-8",
                max_tokens=16000,
                messages=[{"role": "user", "content": "Explain quantum computing basics"}]
            )
        ),
    ]
)

print(f"Batch ID: {message_batch.id}")
print(f"Status: {message_batch.processing_status}")

Poll for Completion

import time

while True:
    batch = client.messages.batches.retrieve(message_batch.id)
    if batch.processing_status == "ended":
        break
    print(f"Status: {batch.processing_status}, processing: {batch.request_counts.processing}")
    time.sleep(60)

print("Batch complete!")
print(f"Succeeded: {batch.request_counts.succeeded}")
print(f"Errored: {batch.request_counts.errored}")

Retrieve Results

Note: Examples below use match/case syntax, requiring Python 3.10+. For earlier versions, use if/elif chains instead.

for result in client.messages.batches.results(message_batch.id):
    match result.result.type:
        case "succeeded":
            msg = result.result.message
            text = next((b.text for b in msg.content if b.type == "text"), "")
            print(f"[{result.custom_id}] {text[:100]}")
        case "errored":
            if result.result.error.type == "invalid_request":
                print(f"[{result.custom_id}] Validation error - fix request and retry")
            else:
                print(f"[{result.custom_id}] Server error - safe to retry")
        case "canceled":
            print(f"[{result.custom_id}] Canceled")
        case "expired":
            print(f"[{result.custom_id}] Expired - resubmit")

Cancel a Batch

cancelled = client.messages.batches.cancel(message_batch.id)
print(f"Status: {cancelled.processing_status}")  # "canceling"

List Batches (auto-pagination)

Iterating the return value of any list() call auto-paginates across all pages — do not index into .data if you want the full set:

for batch in client.messages.batches.list(limit=20):
    print(batch.id, batch.processing_status)

For manual control, use first_page.has_next_page() / first_page.get_next_page() / first_page.next_page_info(); first_page.data holds the current page's items and first_page.last_id is the cursor.

Batch with Prompt Caching

shared_system = [
    {"type": "text", "text": "You are a literary analyst."},
    {
        "type": "text",
        "text": large_document_text,  # Shared across all requests
        "cache_control": {"type": "ephemeral"}
    }
]

message_batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id=f"analysis-{i}",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-8",
                max_tokens=16000,
                system=shared_system,
                messages=[{"role": "user", "content": question}]
            )
        )
        for i, question in enumerate(questions)
    ]
)

Full End-to-End Example

import anthropic
import time
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()

# 1. Prepare requests
items_to_classify = [
    "The product quality is excellent!",
    "Terrible customer service, never again.",
    "It's okay, nothing special.",
]

requests = [
    Request(
        custom_id=f"classify-{i}",
        params=MessageCreateParamsNonStreaming(
            model="claude-haiku-4-5",
            max_tokens=50,
            messages=[{
                "role": "user",
                "content": f"Classify as positive/negative/neutral (one word): {text}"
            }]
        )
    )
    for i, text in enumerate(items_to_classify)
]

# 2. Create batch
batch = client.messages.batches.create(requests=requests)
print(f"Created batch: {batch.id}")

# 3. Wait for completion
while True:
    batch = client.messages.batches.retrieve(batch.id)
    if batch.processing_status == "ended":
        break
    time.sleep(10)

# 4. Collect results
results = {}
for result in client.messages.batches.results(batch.id):
    if result.result.type == "succeeded":
        msg = result.result.message
        results[result.custom_id] = next((b.text for b in msg.content if b.type == "text"), "")

for custom_id, classification in sorted(results.items()):
    print(f"{custom_id}: {classification}")

Files API — Python

The Files API uploads files for use in Messages API requests. Reference files via file_id in content blocks, avoiding re-uploads across multiple API calls.

Beta: Pass betas=["files-api-2025-04-14"] in your API calls (the SDK sets the required header automatically).

Key Facts

  • Maximum file size: 500 MB
  • Total storage: 100 GB per organization
  • Files persist until deleted
  • File operations (upload, list, delete) are free; content used in messages is billed as input tokens
  • Not available on Amazon Bedrock or Google Vertex AI

Upload a File

The file argument accepts a (filename, content, content_type) tuple, a pathlib.Path (or any PathLike — read for you, async-safe with AsyncAnthropic), or an open binary file object.

import anthropic
from pathlib import Path

client = anthropic.Anthropic()

uploaded = client.beta.files.upload(
    file=("report.pdf", open("report.pdf", "rb"), "application/pdf"),
)
# or: client.beta.files.upload(file=Path("report.pdf"))
print(f"File ID: {uploaded.id}")
print(f"Size: {uploaded.size_bytes} bytes")

Use a File in Messages

PDF / Text Document

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Summarize the key findings in this report."},
            {
                "type": "document",
                "source": {"type": "file", "file_id": uploaded.id},
                "title": "Q4 Report",           # optional
                "citations": {"enabled": True}   # optional, enables citations
            }
        ]
    }],
    betas=["files-api-2025-04-14"],
)
for block in response.content:
    if block.type == "text":
        print(block.text)

Image

image_file = client.beta.files.upload(
    file=("photo.png", open("photo.png", "rb"), "image/png"),
)

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {
                "type": "image",
                "source": {"type": "file", "file_id": image_file.id}
            }
        ]
    }],
    betas=["files-api-2025-04-14"],
)

Manage Files

List Files

Iterate the list result directly — the SDK auto-paginates across all pages. Only use .data if you want the first page only.

for f in client.beta.files.list():
    print(f"{f.id}: {f.filename} ({f.size_bytes} bytes)")

Get File Metadata

file_info = client.beta.files.retrieve_metadata("file_011CNha8iCJcU1wXNR6q4V8w")
print(f"Filename: {file_info.filename}")
print(f"MIME type: {file_info.mime_type}")

Delete a File

client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w")

Download a File

Only files created by the code execution tool or skills can be downloaded (not user-uploaded files).

file_content = client.beta.files.download("file_011CNha8iCJcU1wXNR6q4V8w")
file_content.write_to_file("output.txt")

Full End-to-End Example

Upload a document once, ask multiple questions about it:

import anthropic

client = anthropic.Anthropic()

# 1. Upload once
uploaded = client.beta.files.upload(
    file=("contract.pdf", open("contract.pdf", "rb"), "application/pdf"),
)
print(f"Uploaded: {uploaded.id}")

# 2. Ask multiple questions using the same file_id
questions = [
    "What are the key terms and conditions?",
    "What is the termination clause?",
    "Summarize the payment schedule.",
]

for question in questions:
    response = client.beta.messages.create(
        model="claude-opus-4-8",
        max_tokens=16000,
        messages=[{
            "role": "user",
            "content": [
                {"type": "text", "text": question},
                {
                    "type": "document",
                    "source": {"type": "file", "file_id": uploaded.id}
                }
            ]
        }],
        betas=["files-api-2025-04-14"],
    )
    print(f"\nQ: {question}")
    text = next((b.text for b in response.content if b.type == "text"), "")
    print(f"A: {text[:200]}")

# 3. Clean up when done
client.beta.files.delete(uploaded.id)

Streaming — Python

Quick Start

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=64000,
    messages=[{"role": "user", "content": "Write a story"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Async

async with async_client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=64000,
    messages=[{"role": "user", "content": "Write a story"}]
) as stream:
    async for text in stream.text_stream:
        print(text, end="", flush=True)

Low-level: stream=True

messages.stream() (above) is the recommended helper — it accumulates state and exposes text_stream / get_final_message(). If you only need the raw event iterator and want lower memory use, pass stream=True to messages.create() instead:

for event in client.messages.create(
    model="claude-opus-4-8",
    max_tokens=64000,
    messages=[{"role": "user", "content": "Write a story"}],
    stream=True,
):
    print(event.type)

No final-message accumulation is done for you in this form.

Handling Different Content Types

Claude may return text, thinking blocks, or tool use. Handle each appropriately:

Fable 5 / Opus 4.8 / Opus 4.7 / Opus 4.6: Use thinking: {type: "adaptive"}. On older models, use thinking: {type: "enabled", budget_tokens: N} instead.

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=64000,
    thinking={"type": "adaptive", "display": "summarized"},  # display opt-in: default is omitted (empty thinking text) on Fable 5 / Mythos 5 / Opus 4.8 / 4.7
    messages=[{"role": "user", "content": "Analyze this problem"}]
) as stream:
    for event in stream:
        if event.type == "content_block_start":
            if event.content_block.type == "thinking":
                print("\n[Thinking...]")
            elif event.content_block.type == "text":
                print("\n[Response:]")

        elif event.type == "content_block_delta":
            if event.delta.type == "thinking_delta":
                print(event.delta.thinking, end="", flush=True)
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)

Streaming with Tool Use

The Python tool runner currently returns complete messages. Use streaming for individual API calls within a manual loop if you need per-token streaming with tools:

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=64000,
    tools=tools,
    messages=messages
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

    response = stream.get_final_message()
    # Continue with tool execution if response.stop_reason == "tool_use"

Getting the Final Message

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=64000,
    messages=[{"role": "user", "content": "Hello"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

    # Get full message after streaming
    final_message = stream.get_final_message()
    print(f"\n\nTokens used: {final_message.usage.output_tokens}")

Streaming with Progress Updates

def stream_with_progress(client, **kwargs):
    """Stream a response with progress updates."""
    total_tokens = 0
    content_parts = []

    with client.messages.stream(**kwargs) as stream:
        for event in stream:
            if event.type == "content_block_delta":
                if event.delta.type == "text_delta":
                    text = event.delta.text
                    content_parts.append(text)
                    print(text, end="", flush=True)

            elif event.type == "message_delta":
                if event.usage and event.usage.output_tokens is not None:
                    total_tokens = event.usage.output_tokens

        final_message = stream.get_final_message()

    print(f"\n\n[Tokens used: {total_tokens}]")
    return "".join(content_parts)

Error Handling in Streams

try:
    with client.messages.stream(
        model="claude-opus-4-8",
        max_tokens=64000,
        messages=[{"role": "user", "content": "Write a story"}]
    ) as stream:
        for text in stream.text_stream:
            print(text, end="", flush=True)
except anthropic.APIConnectionError:
    print("\nConnection lost. Please retry.")
except anthropic.RateLimitError:
    print("\nRate limited. Please wait and retry.")
except anthropic.APIStatusError as e:
    print(f"\nAPI error: {e.status_code}")

Stream Event Types

Event Type Description When it fires
message_start Contains message metadata Once at the beginning
content_block_start New content block beginning When a text/tool_use block starts
content_block_delta Incremental content update For each token/chunk
content_block_stop Content block complete When a block finishes
message_delta Message-level updates Contains stop_reason, usage
message_stop Message complete Once at the end

Best Practices

  1. Always flush output — Use flush=True to show tokens immediately
  2. Handle partial responses — If the stream is interrupted, you may have incomplete content
  3. Track token usage — The message_delta event contains usage information
  4. Use timeouts — Set appropriate timeouts for your application
  5. Default to streaming — Use .get_final_message() to get the complete response even when streaming, giving you timeout protection without needing to handle individual events
  6. Large max_tokens without streaming raises ValueError — The SDK refuses non-streaming requests it estimates will exceed ~10 minutes (idle connections drop). Pass stream=True / use messages.stream(), or explicitly override timeout, to suppress the guard.

Tool Use — Python

For conceptual overview (tool definitions, tool choice, tips), see shared/tool-use-concepts.md.

Tool Runner (Recommended)

Beta: The tool runner is in beta in the Python SDK.

Use the @beta_tool decorator to define tools as typed functions, then pass them to client.beta.messages.tool_runner():

import anthropic
from anthropic import beta_tool

client = anthropic.Anthropic()

@beta_tool
def get_weather(location: str, unit: str = "celsius") -> str:
    """Get current weather for a location.

    Args:
        location: City and state, e.g., San Francisco, CA.
        unit: Temperature unit, either "celsius" or "fahrenheit".
    """
    # Your implementation here
    return f"72°F and sunny in {location}"

# The tool runner handles the agentic loop automatically
runner = client.beta.messages.tool_runner(
    model="claude-opus-4-8",
    max_tokens=16000,
    tools=[get_weather],
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)

# Each iteration yields a BetaMessage; iteration stops when Claude is done
for message in runner:
    print(message)

For async usage, use @beta_async_tool with async def functions.

Key benefits of the tool runner:

  • No manual loop — the SDK handles calling tools and feeding results back
  • Type-safe tool inputs via decorators
  • Tool schemas are generated automatically from function signatures
  • Iteration stops automatically when Claude has no more tool calls

MCP Tool Conversion Helpers

Beta. Convert MCP (Model Context Protocol) tools, prompts, and resources to Anthropic API types for use with the tool runner. Requires pip install anthropic[mcp] (Python 3.10+).

Note: The Claude API also supports an mcp_servers parameter that lets Claude connect directly to remote MCP servers. Use these helpers instead when you need local MCP servers, prompts, resources, or more control over the MCP connection.

MCP Tools with Tool Runner

from anthropic import AsyncAnthropic
from anthropic.lib.tools.mcp import async_mcp_tool
from mcp import ClientSession
from mcp.client.stdio import stdio_client, StdioServerParameters

client = AsyncAnthropic()

async with stdio_client(StdioServerParameters(command="mcp-server")) as (read, write):
    async with ClientSession(read, write) as mcp_client:
        await mcp_client.initialize()

        tools_result = await mcp_client.list_tools()
        # tool_runner is sync — returns the runner, not a coroutine
        runner = client.beta.messages.tool_runner(
            model="claude-opus-4-8",
            max_tokens=16000,
            messages=[{"role": "user", "content": "Use the available tools"}],
            tools=[async_mcp_tool(t, mcp_client) for t in tools_result.tools],
        )
        async for message in runner:
            print(message)

For sync usage, use mcp_tool instead of async_mcp_tool.

MCP Prompts

from anthropic.lib.tools.mcp import mcp_message

prompt = await mcp_client.get_prompt(name="my-prompt")
response = await client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[mcp_message(m) for m in prompt.messages],
)

MCP Resources as Content

from anthropic.lib.tools.mcp import mcp_resource_to_content

resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt")
response = await client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{
        "role": "user",
        "content": [
            mcp_resource_to_content(resource),
            {"type": "text", "text": "Summarize this document"},
        ],
    }],
)

Upload MCP Resources as Files

from anthropic.lib.tools.mcp import mcp_resource_to_file

resource = await mcp_client.read_resource(uri="file:///path/to/data.json")
uploaded = await client.beta.files.upload(file=mcp_resource_to_file(resource))

Conversion functions raise UnsupportedMCPValueError if an MCP value cannot be converted (e.g., unsupported content types like audio, unsupported MIME types).

Manual Agentic Loop

Use this when you need fine-grained control over the loop (e.g., custom logging, conditional tool execution, human-in-the-loop approval):

import anthropic

client = anthropic.Anthropic()
tools = [...]  # Your tool definitions
messages = [{"role": "user", "content": user_input}]

# Agentic loop: keep going until Claude stops calling tools
while True:
    response = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=16000,
        tools=tools,
        messages=messages
    )

    # If Claude is done (no more tool calls), break
    if response.stop_reason == "end_turn":
        break

    # Server-side tool hit iteration limit; re-send to continue
    if response.stop_reason == "pause_turn":
        messages = [
            {"role": "user", "content": user_input},
            {"role": "assistant", "content": response.content},
        ]
        continue

    # Extract tool use blocks from the response
    tool_use_blocks = [b for b in response.content if b.type == "tool_use"]

    # Append assistant's response (including tool_use blocks)
    messages.append({"role": "assistant", "content": response.content})

    # Execute each tool and collect results
    tool_results = []
    for tool in tool_use_blocks:
        result = execute_tool(tool.name, tool.input)  # Your implementation
        tool_results.append({
            "type": "tool_result",
            "tool_use_id": tool.id,  # Must match the tool_use block's id
            "content": result
        })

    # Append tool results as a user message
    messages.append({"role": "user", "content": tool_results})

# Final response text
final_text = next(b.text for b in response.content if b.type == "text")

Handling Tool Results

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    tools=tools,
    messages=[{"role": "user", "content": "What's the weather in Paris?"}]
)

for block in response.content:
    if block.type == "tool_use":
        tool_name = block.name
        tool_input = block.input
        tool_use_id = block.id

        result = execute_tool(tool_name, tool_input)

        followup = client.messages.create(
            model="claude-opus-4-8",
            max_tokens=16000,
            tools=tools,
            messages=[
                {"role": "user", "content": "What's the weather in Paris?"},
                {"role": "assistant", "content": response.content},
                {
                    "role": "user",
                    "content": [{
                        "type": "tool_result",
                        "tool_use_id": tool_use_id,
                        "content": result
                    }]
                }
            ]
        )

Multiple Tool Calls

tool_results = []

for block in response.content:
    if block.type == "tool_use":
        result = execute_tool(block.name, block.input)
        tool_results.append({
            "type": "tool_result",
            "tool_use_id": block.id,
            "content": result
        })

# Send all results back at once
if tool_results:
    followup = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=16000,
        tools=tools,
        messages=[
            *previous_messages,
            {"role": "assistant", "content": response.content},
            {"role": "user", "content": tool_results}
        ]
    )

Error Handling in Tool Results

tool_result = {
    "type": "tool_result",
    "tool_use_id": tool_use_id,
    "content": "Error: Location 'xyz' not found. Please provide a valid city name.",
    "is_error": True
}

Tool Choice

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},  # Force specific tool
    messages=[{"role": "user", "content": "What's the weather in Paris?"}]
)

Code Execution

Basic Usage

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{
        "role": "user",
        "content": "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]"
    }],
    tools=[{
        "type": "code_execution_20260120",
        "name": "code_execution"
    }]
)

for block in response.content:
    if block.type == "text":
        print(block.text)
    elif block.type == "bash_code_execution_tool_result":
        print(f"stdout: {block.content.stdout}")

Upload Files for Analysis

# 1. Upload a file
uploaded = client.beta.files.upload(file=open("sales_data.csv", "rb"))

# 2. Pass to code execution via container_upload block
# Code execution is GA; Files API is still beta (pass via extra_headers)
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    extra_headers={"anthropic-beta": "files-api-2025-04-14"},
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Analyze this sales data. Show trends and create a visualization."},
            {"type": "container_upload", "file_id": uploaded.id}
        ]
    }],
    tools=[{"type": "code_execution_20260120", "name": "code_execution"}]
)

Retrieve Generated Files

import os

OUTPUT_DIR = "./claude_outputs"
os.makedirs(OUTPUT_DIR, exist_ok=True)

for block in response.content:
    if block.type == "bash_code_execution_tool_result":
        result = block.content
        if result.type == "bash_code_execution_result" and result.content:
            for file_ref in result.content:
                if file_ref.type == "bash_code_execution_output":
                    metadata = client.beta.files.retrieve_metadata(file_ref.file_id)
                    file_content = client.beta.files.download(file_ref.file_id)
                    # Use basename to prevent path traversal; validate result
                    safe_name = os.path.basename(metadata.filename)
                    if not safe_name or safe_name in (".", ".."):
                        print(f"Skipping invalid filename: {metadata.filename}")
                        continue
                    output_path = os.path.join(OUTPUT_DIR, safe_name)
                    file_content.write_to_file(output_path)
                    print(f"Saved: {output_path}")

Container Reuse

# First request: set up environment
response1 = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Install tabulate and create data.json with sample data"}],
    tools=[{"type": "code_execution_20260120", "name": "code_execution"}]
)

# Get container ID from response
container_id = response1.container.id

# Second request: reuse the same container
response2 = client.messages.create(
    container=container_id,
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Read data.json and display as a formatted table"}],
    tools=[{"type": "code_execution_20260120", "name": "code_execution"}]
)

Response Structure

for block in response.content:
    if block.type == "text":
        print(block.text)  # Claude's explanation
    elif block.type == "server_tool_use":
        print(f"Running: {block.name} - {block.input}")  # What Claude is doing
    elif block.type == "bash_code_execution_tool_result":
        result = block.content
        if result.type == "bash_code_execution_result":
            if result.return_code == 0:
                print(f"Output: {result.stdout}")
            else:
                print(f"Error: {result.stderr}")
        else:
            print(f"Tool error: {result.error_code}")
    elif block.type == "text_editor_code_execution_tool_result":
        print(f"File operation: {block.content}")

Memory Tool

Basic Usage

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Remember that my preferred language is Python."}],
    tools=[{"type": "memory_20250818", "name": "memory"}],
)

SDK Memory Helper

Subclass BetaAbstractMemoryTool:

from anthropic.lib.tools import BetaAbstractMemoryTool

class MyMemoryTool(BetaAbstractMemoryTool):
    def view(self, command): ...
    def create(self, command): ...
    def str_replace(self, command): ...
    def insert(self, command): ...
    def delete(self, command): ...
    def rename(self, command): ...

memory = MyMemoryTool()

# Use with tool runner
runner = client.beta.messages.tool_runner(
    model="claude-opus-4-8",
    max_tokens=16000,
    tools=[memory],
    messages=[{"role": "user", "content": "Remember my preferences"}],
)

for message in runner:
    print(message)

For full implementation examples, use WebFetch:

  • https://github.com/anthropics/anthropic-sdk-python/blob/main/examples/memory/basic.py

Structured Outputs

JSON Outputs (Pydantic — Recommended)

from pydantic import BaseModel
from typing import List
import anthropic

class ContactInfo(BaseModel):
    name: str
    email: str
    plan: str
    interests: List[str]
    demo_requested: bool

client = anthropic.Anthropic()

response = client.messages.parse(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{
        "role": "user",
        "content": "Extract: Jane Doe (jane@co.com) wants Enterprise, interested in API and SDKs, wants a demo."
    }],
    output_format=ContactInfo,
)

# response.parsed_output is a validated ContactInfo instance
contact = response.parsed_output
print(contact.name)           # "Jane Doe"
print(contact.interests)      # ["API", "SDKs"]

Raw Schema

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{
        "role": "user",
        "content": "Extract info: John Smith (john@example.com) wants the Enterprise plan."
    }],
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "email": {"type": "string"},
                    "plan": {"type": "string"},
                    "demo_requested": {"type": "boolean"}
                },
                "required": ["name", "email", "plan", "demo_requested"],
                "additionalProperties": False
            }
        }
    }
)

import json
# output_config.format guarantees the first block is text with valid JSON
text = next(b.text for b in response.content if b.type == "text")
data = json.loads(text)

Strict Tool Use

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Book a flight to Tokyo for 2 passengers on March 15"}],
    tools=[{
        "name": "book_flight",
        "description": "Book a flight to a destination",
        "strict": True,
        "input_schema": {
            "type": "object",
            "properties": {
                "destination": {"type": "string"},
                "date": {"type": "string", "format": "date"},
                "passengers": {"type": "integer", "enum": [1, 2, 3, 4, 5, 6, 7, 8]}
            },
            "required": ["destination", "date", "passengers"],
            "additionalProperties": False
        }
    }]
)

Using Both Together

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Plan a trip to Paris next month"}],
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "summary": {"type": "string"},
                    "next_steps": {"type": "array", "items": {"type": "string"}}
                },
                "required": ["summary", "next_steps"],
                "additionalProperties": False
            }
        }
    },
    tools=[{
        "name": "search_flights",
        "description": "Search for available flights",
        "strict": True,
        "input_schema": {
            "type": "object",
            "properties": {
                "destination": {"type": "string"},
                "date": {"type": "string", "format": "date"}
            },
            "required": ["destination", "date"],
            "additionalProperties": False
        }
    }]
)

Managed Agents — Python

Bindings not shown here: This README covers the most common managed-agents flows for Python. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the Python SDK repo or the relevant docs page from shared/live-sources.md rather than guess. Do not extrapolate from cURL shapes or another language's SDK.

Agents are persistent — create once, reference by ID. Store the agent ID returned by agents.create and pass it to every subsequent sessions.create; do not call agents.create in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in shared/live-sources.md. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path.

Installation

pip install anthropic

Client Initialization

import anthropic

# Default — resolves credentials from the environment:
# ANTHROPIC_API_KEY, or ANTHROPIC_AUTH_TOKEN, or an `ant auth login` profile.
# Prefer this for local dev; don't hardcode a key.
client = anthropic.Anthropic()

# Explicit API key (only when you must inject a specific key)
client = anthropic.Anthropic(api_key="your-api-key")

Create an Environment

environment = client.beta.environments.create(
    name="my-dev-env",
    config={
        "type": "cloud",
        "networking": {"type": "unrestricted"},
    },
)
print(environment.id)  # env_...

Create an Agent (required first step)

⚠️ There is no inline agent config. model/system/tools live on the agent object, not the session. Always start with agents.create() — the session only takes agent={"type": "agent", "id": agent.id}.

Minimal

# 1. Create the agent (reusable, versioned)
agent = client.beta.agents.create(
    name="Coding Assistant",
    model="claude-opus-4-8",
    tools=[{"type": "agent_toolset_20260401", "default_config": {"enabled": True}}],
)

# 2. Start a session
session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": agent.version},
    environment_id=environment.id,
)
print(session.id, session.status)
print(f"Trace: https://platform.claude.com/workspaces/default/sessions/{session.id}")

With system prompt and custom tools

import os

agent = client.beta.agents.create(
    name="Code Reviewer",
    model="claude-opus-4-8",
    system="You are a senior code reviewer.",
    tools=[
        {"type": "agent_toolset_20260401"},
        {
            "type": "custom",
            "name": "run_tests",
            "description": "Run the test suite",
            "input_schema": {
                "type": "object",
                "properties": {
                    "test_path": {"type": "string", "description": "Path to test file"}
                },
                "required": ["test_path"],
            },
        },
    ],
)

session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": agent.version},
    environment_id=environment.id,
    title="Code review session",
    resources=[
        {
            "type": "github_repository",
            "url": "https://github.com/owner/repo",
            "mount_path": "/workspace/repo",
            "authorization_token": os.environ["GITHUB_TOKEN"],
            "branch": "main",
        }
    ],
)

Send a User Message

client.beta.sessions.events.send(
    session_id=session.id,
    events=[
        {
            "type": "user.message",
            "content": [{"type": "text", "text": "Review the auth module"}],
        }
    ],
)

💡 Stream-first: Open the stream before (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See Steering Patterns.

Stream Events (SSE)

import json

# Stream-first: open stream, then send while stream is live
with client.beta.sessions.events.stream(
    session_id=session.id,
) as stream:
    client.beta.sessions.events.send(
        session_id=session.id,
        events=[{"type": "user.message", "content": [{"type": "text", "text": "..."}]}],
    )
    for event in stream:
        ...  # process events

# Standalone stream iteration:
with client.beta.sessions.events.stream(
    session_id=session.id,
) as stream:
    for event in stream:
        if event.type == "agent.message":
            for block in event.content:
                if block.type == "text":
                    print(block.text, end="", flush=True)
        elif event.type == "agent.custom_tool_use":
            # Custom tool invocation — session is now idle
            print(f"\nCustom tool call: {event.name}")
            print(f"Input: {json.dumps(event.input)}")
            # Send result back (see below)
        elif event.type == "session.status_idle":
            print("\n--- Agent idle ---")
        elif event.type == "session.status_terminated":
            print("\n--- Session terminated ---")
            break

Provide Custom Tool Result

client.beta.sessions.events.send(
    session_id=session.id,
    events=[
        {
            "type": "user.custom_tool_result",
            "custom_tool_use_id": "sevt_abc123",
            "content": [{"type": "text", "text": "All 42 tests passed."}],
        }
    ],
)

Poll Events

events = client.beta.sessions.events.list(
    session_id=session.id,
)
for event in events.data:
    print(f"{event.type}: {event.id}")

⚠️ Prefer the SDK over raw requests/httpx. If you hand-roll a poll loop, don't assume timeout=(5, 60) or httpx.Timeout(120) caps total call duration — both are per-chunk read timeouts (reset on every byte), so a trickling response can block forever. For a hard wall-clock deadline, track time.monotonic() at the loop level and bail explicitly, or wrap with asyncio.wait_for(). See Receiving Events.

Full Streaming Loop with Custom Tools

import json


def run_custom_tool(tool_name: str, tool_input: dict) -> str:
    """Execute a custom tool and return the result."""
    if tool_name == "run_tests":
        # Your tool implementation here
        return "All tests passed."
    return f"Unknown tool: {tool_name}"


def run_session(client, session_id: str):
    """Stream events and handle custom tool calls."""
    while True:
        with client.beta.sessions.events.stream(
            session_id=session_id,
        ) as stream:
            tool_calls = []
            for event in stream:
                if event.type == "agent.message":
                    for block in event.content:
                        if block.type == "text":
                            print(block.text, end="", flush=True)
                elif event.type == "agent.custom_tool_use":
                    tool_calls.append(event)
                elif event.type == "session.status_idle":
                    break
                elif event.type == "session.status_terminated":
                    return

        if not tool_calls:
            break

        # Process custom tool calls
        results = []
        for call in tool_calls:
            result = run_custom_tool(call.name, call.input)
            results.append({
                "type": "user.custom_tool_result",
                "custom_tool_use_id": call.id,
                "content": [{"type": "text", "text": result}],
            })

        client.beta.sessions.events.send(
            session_id=session_id,
            events=results,
        )

Upload a File

with open("data.csv", "rb") as f:
    file = client.beta.files.upload(
        file=f,
    )

# Use in a session
session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": agent.version},
    environment_id=environment.id,
    resources=[{"type": "file", "file_id": file.id, "mount_path": "/workspace/data.csv"}],
)

List and Download Session Files

List files the agent wrote to /mnt/session/outputs/ during a session, then download them.

# List files associated with a session
files = client.beta.files.list(
    scope_id=session.id,
    betas=["managed-agents-2026-04-01"],
)
for f in files.data:
    print(f.filename, f.size_bytes)
    # Download each file and save to disk
    file_content = client.beta.files.download(f.id)
    file_content.write_to_file(f.filename)

💡 There's a brief indexing lag (~1–3s) between session.status_idle and output files appearing in files.list. Retry once or twice if the list is empty.

Session Management

# Get session details
session = client.beta.sessions.retrieve(session_id="sesn_011CZxAbc123Def456")
print(session.status, session.usage)

# List sessions
sessions = client.beta.sessions.list()

# Delete a session
client.beta.sessions.delete(session_id="sesn_011CZxAbc123Def456")

# Archive a session
client.beta.sessions.archive(session_id="sesn_011CZxAbc123Def456")

MCP Server Integration

# Agent declares MCP server (no auth here — auth goes in a vault)
agent = client.beta.agents.create(
    name="MCP Agent",
    model="claude-opus-4-8",
    mcp_servers=[
        {"type": "url", "name": "my-tools", "url": "https://my-mcp-server.example.com/sse"},
    ],
    tools=[
        {"type": "agent_toolset_20260401", "default_config": {"enabled": True}},
        {"type": "mcp_toolset", "mcp_server_name": "my-tools"},
    ],
)

# Session attaches vault(s) containing credentials for those MCP server URLs
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)

See shared/managed-agents-tools.md §Vaults for creating vaults and adding credentials.

Agent Design Patterns

This file covers decision heuristics for building agents on the Claude API: which primitives to reach for, how to design your tool surface, and how to manage context and cost over long runs. For per-tool mechanics and code examples, see tool-use-concepts.md and the language-specific folders.

Model Parameters

Parameter When to use it What to expect
Adaptive thinking (thinking: {type: "adaptive"}) When you want Claude to control when and how much to think. Claude determines thinking depth per request and automatically interleaves thinking between tool calls. No token budget to tune.
Effort (output_config: {effort: ...}) When adjusting the tradeoff between thoroughness and token efficiency. Lower effort → fewer and more-consolidated tool calls, less preamble, terser confirmations. medium is often a favorable balance. Use max when correctness matters more than cost.

See SKILL.md §Thinking & Effort for model support and parameter details.

Designing Your Tool Surface

Bash vs. dedicated tools

Claude doesn't know your application's security boundary, approval policy, or UX surface. Claude emits tool calls; your harness handles them. The shape of those tool calls determines what the harness can do.

A bash tool gives Claude broad programmatic leverage — it can perform almost any action. But it gives the harness only an opaque command string, the same shape for every action. Promoting an action to a dedicated tool gives the harness an action-specific hook with typed arguments it can intercept, gate, render, or audit.

When to promote an action to a dedicated tool:

  • Security boundary. Actions that require gating are natural candidates. Reversibility is a useful criterion: hard-to-reverse actions (external API calls, sending messages, deleting data) can be gated behind user confirmation. A send_email tool is easy to gate; bash -c "curl -X POST ..." is not.
  • Staleness checks. A dedicated edit tool can reject writes if the file changed since Claude last read it. Bash can't enforce that invariant.
  • Rendering. Some actions benefit from custom UI. Claude Code promotes question-asking to a tool so it can render as a modal, present options, and block the agent loop until answered.
  • Scheduling. Read-only tools like glob and grep can be marked parallel-safe. When the same actions run through bash, the harness can't tell a parallel-safe grep from a parallel-unsafe git push, so it must serialize.

Rule of thumb: Start with bash for breadth. Promote to dedicated tools when you need to gate, render, audit, or parallelize the action.

Anthropic-Provided Tools

Tool Side When to use it What to expect
Bash Client Claude needs to execute shell commands. Claude emits commands; your harness executes them. Reference implementation provided.
Text editor Client Claude needs to read or edit files. Claude views, creates, and edits files via your implementation. Reference implementation provided.
Computer use Client or Server Claude needs to interact with GUIs, web apps, or visual interfaces. Claude takes screenshots and issues mouse/keyboard commands. Can be self-hosted (you run the environment) or Anthropic-hosted.
Code execution Server Claude needs to run code in a sandbox you don't want to manage. Anthropic-hosted container with built-in file and bash sub-tools. No client-side execution.
Web search / fetch Server Claude needs information past its training cutoff (news, current events, recent docs) or the content of a specific URL. Claude issues a query or URL; Anthropic executes it and returns results with citations.
Memory Client Claude needs to save context across sessions. Claude reads/writes a /memories directory. You implement the storage backend.

Client-side tools are defined by Anthropic (name, schema, Claude's usage pattern) but executed by your harness. Anthropic provides reference implementations. Server-side tools run entirely on Anthropic infrastructure — declare them in tools and Claude handles the rest.

Composing Tool Calls: Programmatic Tool Calling

With standard tool use, each tool call is a round trip: Claude calls the tool, the result lands in Claude's context, Claude reasons about it, then calls the next tool. Three sequential actions (read profile → look up orders → check inventory) means three round trips. Each adds latency and tokens, and most of the intermediate data is never needed again.

Programmatic tool calling (PTC) lets Claude compose those calls into a script instead. The script runs in the code execution container. When the script calls a tool, the container pauses, the call is executed (client-side or server-side), and the result returns to the running code — not to Claude's context. The script processes it with normal control flow (loops, filters, branches). Only the script's final output returns to Claude.

When to use it What to expect
Many sequential tool calls, or large intermediate results you want filtered before they hit the context window. Claude writes code that invokes tools as functions. Runs in the code execution container. Token cost scales with final output, not intermediate results.

Scaling the Tool and Instruction Set

Feature When to use it What to expect
Tool search Many tools available, but only a few relevant per request. Don't want all schemas in context upfront. Claude searches the tool set and loads only relevant schemas. Tool definitions are appended, not swapped — preserves cache (see Caching below).
Skills Task-specific instructions Claude should load only when relevant. Each skill is a folder with a SKILL.md. The skill's description sits in context by default; Claude reads the full file when the task calls for it.

Both patterns keep the fixed context small and load detail on demand.

Long-Running Agents: Managing Context

Pattern When to use it What to expect
Context editing Context grows stale over many turns (old tool results, completed thinking). Tool results and thinking blocks are cleared based on configurable thresholds. Keeps the transcript lean without summarizing.
Compaction Conversation likely to reach or exceed the context window limit. Earlier context is summarized into a compaction block server-side. See SKILL.md §Compaction for the critical response.content handling.
Memory State must persist across sessions (not just within one conversation). Claude reads/writes files in a memory directory. Survives process restarts.

Choosing between them: Context editing and compaction operate within a session — editing prunes stale turns, compaction summarizes when you're near the limit. Memory is for cross-session persistence. Many long-running agents use all three.

Caching for Agents

Read prompt-caching.md first. It covers the prefix-match invariant, breakpoint placement, the silent-invalidator audit, and why changing tools or models mid-session breaks the cache. This section covers only the agent-specific workarounds for those constraints.

Constraint (from prompt-caching.md) Agent-specific workaround
Editing the system prompt mid-session invalidates the cache. Append a {"role": "system", ...} message to messages[] instead (no beta header; on supporting models — see prompt-caching.md § Mid-conversation system messages). The cached prefix stays intact, and the model treats it as an operator-authority instruction rather than user text. On models that don't support it, fall back to a <system-reminder> text block in the user turn.
Switching models mid-session invalidates the cache. Spawn a subagent with the cheaper model for the sub-task; keep the main loop on one model.
Adding/removing tools mid-session invalidates the cache. Use tool search for dynamic discovery — it appends tool schemas rather than swapping them, so the existing prefix is preserved.

For multi-turn breakpoint placement, use top-level auto-caching — see prompt-caching.md §Placement patterns.

For live documentation on any of these features, see live-sources.md.

Anthropic CLI (ant)

The ant CLI exposes every Claude API resource as a shell subcommand. Compared to curl: request bodies are built from typed flags or piped YAML instead of hand-written JSON, @path inlines file contents into any string field, --transform extracts fields with a GJSON path (no jq), list endpoints auto-paginate (cap total results with --max-items N; --limit only sets the server page size), and the beta: prefix auto-sets the right anthropic-beta header.

When to use the CLI vs the SDK

CLI for the control plane, SDK for the data plane. Agents and environments are relatively static resources you define, configure, and debug with ant — check the YAML into your repo, apply from CI, inspect from a terminal. Sessions are dynamic and driven by your application through the SDK — create per task, stream events, react to tool calls, integrate into your product. Both hit the same API; the split is about where the call lives, not what's possible.

Control plane → ant Data plane → SDK
Resources agents, environments, skills, vaults, files sessions, events
Cadence Once per deploy / ad-hoc Every task / every turn
Lives in *.yaml in your repo + CI + terminal Application code
Typical calls create < agent.yaml, update --version N, list, retrieve, archive, --debug sessions.create(), events.stream(), events.send()

Install and auth

# macOS
brew install anthropics/tap/ant
xattr -d com.apple.quarantine "$(brew --prefix)/bin/ant"

# Linux / WSL — pick the release from github.com/anthropics/anthropic-cli/releases
curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${VERSION}/ant_${VERSION}_$(uname -s | tr A-Z a-z)_$(uname -m | sed -e s/x86_64/amd64/ -e s/aarch64/arm64/).tar.gz" \
  | sudo tar -xz -C /usr/local/bin ant

# Or from source (Go 1.22+)
go install github.com/anthropics/anthropic-cli/cmd/ant@latest

Auth — the CLI resolves credentials the same way the SDKs do (first match wins): explicit flags, then ANTHROPIC_API_KEY, then ANTHROPIC_AUTH_TOKEN, then the ANTHROPIC_PROFILE-selected or active profile, then Workload Identity Federation env vars, then the default profile on disk. Override the host with ANTHROPIC_BASE_URL or --base-url.

  • API key: set ANTHROPIC_API_KEY in the environment.
  • OAuth profile (no static key to manage): ant auth login opens a browser, exchanges for a short-lived token, and stores a profile under $ANTHROPIC_CONFIG_DIR (default ~/.config/anthropic/ on Linux/macOS, %APPDATA%\Anthropic on Windows — configs/<profile>.json for settings, credentials/<profile>.json for tokens). Subsequent ant (and SDK) calls pick it up automatically — a bare Anthropic() client works after login, but scripts that read ANTHROPIC_API_KEY directly do not. Claude Code and the Claude Agent SDK honor the same profile resolution. ant auth status shows which credential source and profile won (it reports status only — don't script against its exit code as a health check); ant auth logout clears the active profile (--all for every profile). On a remote host without a browser, ant auth login --no-browser prints the authorize URL and accepts the code back in the terminal.
  • Non-interactive workloads (CI, servers, containers): interactive login is for development on your own machine — use Workload Identity Federation instead (see the authentication docs via shared/live-sources.md).

The #1 auth trap: profiles are only consulted when no API key is set. A stale exported ANTHROPIC_API_KEY silently overrides every profile — requests hit whatever org/workspace that key is scoped to. ant auth status shows which source won; unset the key (or per-command: env -u ANTHROPIC_API_KEY ant …) before relying on a profile. Truly unset it — an empty ANTHROPIC_API_KEY="" still wins its precedence slot and authenticates with an empty key. The same shadowing applies in reverse to Claude Code: after ant auth login, Claude Code may warn about an auth conflict between the profile and its own /login credential — keep one (use the profile and /logout in Claude Code, or ant auth logout to keep Claude Code's own login).

Named profiles — an interactive-login token is bound to a single org+workspace, and the API only shows resources belonging to that workspace. If an agent, session, or file you created "disappears", the usual cause is a token scoped to a different workspace than the one that created it (ant auth status shows the active workspace). Multi-workspace work means one profile per workspace:

ant auth login --profile <name>                  # creates the profile if it doesn't exist; org/workspace picker in browser
ant auth login --profile <name> --workspace-id wrkspc_01...   # bind directly, skip the picker
ant profile activate <name>                      # switch the default profile
ant --profile <name> models list                 # one-off; equivalent: ANTHROPIC_PROFILE=<name> ant models list
ant profile list                                 # inspect
ant profile set workspace_id wrkspc_01... --profile <name>    # edit config keys (workspace_id, base_url, organization_id, …)

ant profile set edits an existing profile's config — it never creates one, and it does not rebind already-issued credentials; run ant auth login again under that profile to mint a token for the new target. Pointing ANTHROPIC_PROFILE at a profile that doesn't exist is an error, not a fall-through. Refresh tokens eventually hard-expire (they don't slide with use) — when a previously working profile starts failing auth, re-run ant auth login before debugging anything else.

Scopes — a profile's OAuth scope set is requested at login (--scope) and persists on the profile (scope is also a profile set config key; like other config edits, changing it requires a fresh ant auth login to take effect). Privileged scopes — e.g. org:admin for organization-administration endpoints — are not in the default scope set: pass the full set you want explicitly (ant auth login --profile admin --scope "... org:admin"), and the server grants a privileged scope only if your role actually has it. Because the scope set rides on every token the profile mints, keep privileged work on a dedicated profile (admin vs default) and do day-to-day inference on the unprivileged one, switching with --profile/ANTHROPIC_PROFILE. Check ant auth login --help for the current scope list, and ant auth status to see what the active token carries.

To hand the active credential to a subprocess or raw-HTTP script:

# Bare access token — for curl's Authorization header
curl https://api.anthropic.com/v1/messages \
  -H "Authorization: Bearer $(ant auth print-credentials --access-token)" \
  -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"}]}'

# .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:
set -a; eval "$(ant auth print-credentials --env)"; set +a
python my_script.py   # SDK picks up ANTHROPIC_AUTH_TOKEN

OAuth tokens go on Authorization: Bearer (not x-api-key:) plus the anthropic-beta: oauth-2025-04-20 header — converting a raw curl/httpx script from an API key is a header change, not a key swap. The beta header requirement is endpoint-dependent (some endpoints happen to work without it; /v1/messages does not) — always send it so requests don't break when you switch endpoints. The token is short-lived and not auto-refreshed when passed via env var, so re-run print-credentials before it expires for long-running scripts (print-credentials itself refreshes the token if needed). If both ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN are set, the SDKs send both and the API rejects the request — unset ANTHROPIC_API_KEY before evaling the --env output.

Foot-gun: ant auth print-credentials with no flags prints the entire credentials JSON, not the bare token — putting that in an Authorization header yields an empty response or HTTP/2 protocol error. Always use --access-token for headers (it always reads the named/active profile; a set ANTHROPIC_API_KEY doesn't override credential printing).

Command structure

ant <resource>[:<subresource>] <action> [flags]

Beta resources (agents, sessions, environments, deployments, skills, vaults, memory stores) live under beta: — the CLI auto-sends the right anthropic-beta header, so don't pass it yourself unless overriding with --beta <header>. For self-hosted environments, ant beta:worker poll/run and ant beta:environments:work stats/stop drive and monitor the work queue — see shared/managed-agents-self-hosted-sandboxes.md.

ant models list
ant messages create --model claude-opus-4-8 --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...

ant --help lists resources; append --help to any subcommand for its flags.

Global flags

Flag Purpose
--format auto (default: pretty if TTY, compact if piped), json, jsonl, yaml, pretty, raw, explore (interactive TUI)
--transform GJSON path applied to the response (per-item on list endpoints). Not applied when --format raw.
-r, --raw-output If the transformed result is a string, print it without quotes (jq semantics). Pair with --transform for scalar capture.
--max-items Cap total results returned from auto-paginating list endpoints (distinct from --limit, which is the server page size).
--format-error / --transform-error Same as --format/--transform, applied to error responses. -r does not apply to the error path — use --format-error yaml for unquoted error scalars.
--base-url Override API host
--debug Print full HTTP request + response to stderr (API key redacted)

Output — --transform + --format

--transform takes a GJSON path. On list endpoints it runs per item, not on the envelope.

ant beta:agents list --transform '{id,name,model}' --format jsonl

Extract a scalar for shell use: pair --transform with -r (--raw-output — prints strings unquoted, jq-style):

AGENT_ID=$(ant beta:agents create --name "My Agent" --model '{id: claude-sonnet-5}' \
  --transform id -r)

Input — flags, stdin, @file

Flags — scalar fields map directly. Structured fields accept relaxed-YAML syntax (unquoted keys) or strict JSON. Repeatable flags build arrays (each --tool, --event, --message appends one element):

ant beta:agents create \
  --name "Research Agent" \
  --model '{id: claude-opus-4-8}' \
  --tool '{type: agent_toolset_20260401}' \
  --tool '{type: custom, name: search_docs, input_schema: {type: object, properties: {query: {type: string}}}}'

Stdin — pipe a full JSON or YAML body. Merged with flags; flags win on conflict (for array fields, any flag replaces the stdin array entirely — it does not append). Quote the heredoc delimiter (<<'YAML') to disable shell expansion inside the body:

ant beta:agents create <<'YAML'
name: Research Agent
model: claude-opus-4-8
system: |
  You are a research assistant. Cite sources for every claim.
tools:
  - type: agent_toolset_20260401
YAML

@file references — inline a file's contents into any string-valued field. Inside structured flag values, quote the path. Binary files are auto-base64'd; force with @file:// (text) or @data:// (base64). Escape a literal leading @ as \@.

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 \
  --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."}
  ]}' \
  --transform 'content.0.text' -r

Flags that natively take a file path (e.g. --file on beta:files upload) accept a bare path without @.

Version-controlled Managed Agents resources

This is the recommended flow for defining agents and environments — check the YAML into your repo and sync via create (first time) / update (thereafter). See shared/managed-agents-core.md for the field reference.

# summarizer.agent.yaml
name: Summarizer
model: claude-sonnet-5
system: |
  You are a helpful assistant that writes concise summaries.
tools:
  - type: agent_toolset_20260401

# Create (once) — capture the ID
AGENT_ID=$(ant beta:agents create < summarizer.agent.yaml --transform id -r)

# Update (CI) — needs ID + current version (optimistic lock)
ant beta:agents update --agent-id "$AGENT_ID" --version 1 < summarizer.agent.yaml

Same pattern for environments (ant beta:environments create|update < env.yaml), then start a session with both IDs:

ant beta:sessions create --agent "$AGENT_ID" --environment-id "$ENV_ID" --title "Task"
ant beta:sessions:events send --session-id "$SID" \
  --event '{type: user.message, content: [{type: text, text: "Summarize X"}]}'
ant beta:sessions:events list --session-id "$SID" --transform 'content.0.text' -r
ant beta:sessions:events stream --session-id "$SID"   # live event stream

Interactive session loop (stream-before-send)

ant beta:sessions:events stream only delivers events emitted after the stream opens — so open it before sending the kickoff to avoid missing early events. Use process substitution to hold the stream on a file descriptor, send, then read:

exec {stream}< <(ant beta:sessions:events stream --session-id "$SID" \
  --transform '{type,text:content.#(type=="text").text,err:error.message}' --format yaml)

ant beta:sessions:events send --session-id "$SID" > /dev/null <<'YAML'
events:
  - type: user.message
    content:
      - type: text
        text: Summarize the repo README
YAML

type=
while IFS= read -r -u "$stream" line; do
  case "$line" in
    type:\ session.status_idle) break ;;
    type:\ session.error)
      IFS= read -r -u "$stream" next || next=
      case "$next" in err:\ *) msg=${next#err: } ;; *) msg=unknown ;; esac
      printf '\n[Error: %s]\n' "$msg"; break ;;
    type:\ *) type=${line#type: } ;;
    text:*)
      [[ $type == agent.message ]] || continue
      val=${line#text: }
      case "$val" in '|-'|'|') ;; *) printf '%s' "$val" ;; esac ;;
    \ \ *)
      if [[ $type == agent.message ]]; then printf '%s\n' "${line#  }"; fi ;;
  esac
done
exec {stream}<&-

This works for interactive exploration and demos. For application code that needs to react to agent.tool_use / agent.custom_tool_use events, reconnect after drops, or dedup against events.list, use the SDK — see shared/managed-agents-client-patterns.md.

Scripting patterns

--transform id -r on a list endpoint emits one bare ID per line — compose with xargs, or use --max-items N to bound the result set without piping through head:

FIRST=$(ant beta:agents list --transform id -r --max-items 1)
ant beta:agents:versions list --agent-id "$FIRST" --transform '{version,created_at}' --format jsonl

Error shaping mirrors the success path (note: -r does not apply to error output — use --format-error yaml for an unquoted scalar here):

ant beta:agents retrieve --agent-id bogus --transform-error error.message --format-error yaml 2>&1

Shell completion: ant @completion {zsh|bash|fish|powershell}.

For the full, always-current reference (including per-endpoint flags), WebFetch the Anthropic CLI URL in shared/live-sources.md.

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.

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.

Client & install

Language Install Client
Python pip install -U "anthropic[aws]" from anthropic import AnthropicAWS → AnthropicAWS()
TypeScript npm install @anthropic-ai/aws-sdk import AnthropicAws from "@anthropic-ai/aws-sdk" → new AnthropicAws()
Go go get github.com/anthropics/anthropic-sdk-go import anthropicaws "github.com/anthropics/anthropic-sdk-go/aws" → anthropicaws.NewClient(ctx, anthropicaws.ClientConfig{})
C# dotnet add package Anthropic.Aws new AnthropicAwsClient()
Java See SDK repo in shared/live-sources.md See SDK repo in shared/live-sources.md
Ruby gem install anthropic aws-sdk-core See SDK repo in shared/live-sources.md
PHP composer require anthropic-ai/sdk aws/aws-sdk-php See SDK repo in shared/live-sources.md

After construction, use the client exactly as you would Anthropic() — client.messages.create(...), client.beta.sessions.*, etc., with bare model IDs.

from anthropic import AnthropicAWS

client = AnthropicAWS()  # region + workspace_id from env; see below
client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)

Required configuration

Two values must be available (constructor args or environment) — there is no default fallback for either:

Value Env var Notes
AWS region AWS_REGION Required. Unlike AnthropicBedrock, there is no us-east-1 fallback.
Workspace ID ANTHROPIC_AWS_WORKSPACE_ID Required. Routes requests to your Claude workspace.

Endpoint pattern: https://aws-external-anthropic.{region}.api.aws/v1/.... Requests are SigV4-signed with service name aws-external-anthropic.

Authentication

The client resolves AWS credentials via the standard precedence chain: explicit constructor args → environment (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_SESSION_TOKEN) → shared profile → assumed role / instance metadata.

Short-term API keys are also supported for cases where SigV4 isn't practical (e.g., browser, simple scripts). Mint one with the per-language token-generator package; pass it as api_key on the client. Lifetime is the lesser of the requested duration, the underlying credential's expiry, and 12 hours. For package names and IAM details, WebFetch the Claude Platform on AWS page in shared/live-sources.md.

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.
  • 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.

HTTP Error Codes Reference

This file documents HTTP error codes returned by the Claude API, their common causes, and how to handle them. For language-specific error handling examples, see the python/ or typescript/ folders.

Error Code Summary

Code Error Type Retryable Common Cause
400 invalid_request_error No Invalid request format or parameters
401 authentication_error No Invalid or missing API key
403 permission_error No API key lacks permission
404 not_found_error No Invalid endpoint or model ID
413 request_too_large No Request exceeds size limits
429 rate_limit_error Yes Too many requests
500 api_error Yes Anthropic service issue
529 overloaded_error Yes API is temporarily overloaded

Detailed Error Information

400 Bad Request

Causes:

  • Malformed JSON in request body
  • Missing required parameters (model, max_tokens, messages)
  • Invalid parameter types (e.g., string where integer expected)
  • Empty messages array
  • Messages not alternating user/assistant

Example error:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "messages: roles must alternate between \"user\" and \"assistant\""
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

Fix: Validate request structure before sending. Check that:

  • model is a valid model ID
  • max_tokens is a positive integer
  • messages array is non-empty and alternates correctly

401 Unauthorized

Causes:

  • Missing x-api-key header or Authorization header
  • Invalid API key format
  • Revoked or deleted API key
  • OAuth bearer token sent via x-api-key instead of Authorization: Bearer
  • Both ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN set — the SDK sends both headers and the API rejects the request

Fix: Set ANTHROPIC_API_KEY, or run ant auth login and leave the client constructor empty. For raw HTTP with an OAuth token, use Authorization: Bearer <token> (not x-api-key:).

403 Forbidden

Causes:

  • API key doesn't have access to the requested model
  • Organization-level restrictions
  • Attempting to access beta features without beta access

Fix: Check your API key permissions in the Console. You may need a different API key or to request access to specific features.

404 Not Found

Causes:

  • Typo in model ID (e.g., claude-sonnet-4.6 instead of claude-sonnet-4-6)
  • 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).

413 Request Too Large

Causes:

  • Request body exceeds maximum size
  • Too many tokens in input
  • Image data too large

Fix: Reduce input size — truncate conversation history, compress/resize images, or split large documents into chunks.

400 Validation Errors

Some 400 errors are specifically related to parameter validation:

  • max_tokens exceeds model's limit
  • Invalid temperature value (must be 0.0-1.0)
  • budget_tokens >= max_tokens in extended thinking
  • Invalid tool definition schema

Model-specific 400s on 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.
  • 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):

# Wrong: budget_tokens must be < max_tokens
thinking: budget_tokens=10000, max_tokens=1000  → Error!

# Correct
thinking: budget_tokens=10000, max_tokens=16000

429 Rate Limited

Causes:

  • Exceeded requests per minute (RPM)
  • Exceeded tokens per minute (TPM)
  • Exceeded tokens per day (TPD)

Headers to check:

  • retry-after: Seconds to wait before retrying
  • x-ratelimit-limit-*: Your limits
  • x-ratelimit-remaining-*: Remaining quota

Fix: The Anthropic SDKs automatically retry 429 and 5xx errors with exponential backoff (default: max_retries=2). For custom retry behavior, see the language-specific error handling examples.

500 Internal Server Error

Causes:

  • Temporary Anthropic service issue
  • Bug in API processing

Fix: Retry with exponential backoff. If persistent, check status.anthropic.com.

529 Overloaded

Causes:

  • High API demand
  • Service capacity reached

Fix: Retry with exponential backoff. Consider using a different model (Haiku is often less loaded), spreading requests over time, or implementing request queuing.

Common Mistakes and Fixes

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"}
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
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
Custom retry needs 429/5xx SDK retries automatically; customize with max_retries

Typed Exceptions in SDKs

Always use the SDK's typed exception classes instead of checking error messages with string matching. Each HTTP status code maps to a specific exception class per SDK.

Exception class names by language

HTTP Python (anthropic.*) / TypeScript (Anthropic.*) Ruby (Anthropic::Errors::*) Java (com.anthropic.errors.*) C# PHP (Anthropic\Core\Exceptions\*)
400 BadRequestError BadRequestError BadRequestException AnthropicBadRequestException BadRequestException
401 AuthenticationError AuthenticationError UnauthorizedException AnthropicUnauthorizedException AuthenticationException
403 PermissionDeniedError PermissionDeniedError PermissionDeniedException AnthropicForbiddenException PermissionDeniedException
404 NotFoundError NotFoundError NotFoundException AnthropicNotFoundException NotFoundException
422 UnprocessableEntityError UnprocessableEntityError UnprocessableEntityException AnthropicUnprocessableEntityException UnprocessableEntityException
429 RateLimitError RateLimitError RateLimitException AnthropicRateLimitException RateLimitException
≥500 InternalServerError InternalServerError InternalServerException Anthropic5xxException InternalServerException
net APIConnectionError APIConnectionError AnthropicIoException AnthropicIOException APIConnectionException
base APIError (both); APIStatusError (Python only) APIStatusError / APIError AnthropicServiceException AnthropicApiException APIStatusException / APIException

The Ruby and PHP classes live in a dedicated errors namespace — write Anthropic::Errors::RateLimitError and Anthropic\Core\Exceptions\RateLimitException (not bare Anthropic::RateLimitError). All 4xx C# exceptions also inherit from Anthropic4xxException.

Catch most-specific first, in a chain

Order catch/except/rescue clauses from the most specific subclass to the base class, with a separate clause for each category you handle differently — retryable (429, ≥500, network) vs. non-retryable (4xx). The SDK defines a distinct class per status for exactly this reason; a single broad catch-all discards that information.

try:
    msg = client.messages.create(...)
except anthropic.NotFoundError as e:          # 404 — e.g. bad model ID
    ...
except anthropic.RateLimitError as e:         # 429 — back off and retry
    ...
except anthropic.APIStatusError as e:         # any other non-2xx HTTP response
    print(e.status_code, e.message)
except anthropic.APIConnectionError as e:     # network failure before a response
    ...

The same chain shape applies in every SDK: TypeScript instanceof Anthropic.NotFoundError → RateLimitError → APIConnectionError → APIError (check APIConnectionError before APIError — in the TypeScript SDK it's a subclass of APIError, unlike Python where it's a sibling); Ruby rescue Anthropic::Errors::NotFoundError → …::RateLimitError → …::APIStatusError; Java catch (NotFoundException) … catch (RateLimitException) … catch (AnthropicServiceException); C# catch (AnthropicNotFoundException) … catch (AnthropicRateLimitException) … catch (AnthropicApiException); PHP catch (NotFoundException) … catch (RateLimitException) … catch (APIStatusException).

Go — errors.As then branch on status

The Go SDK returns a single *anthropic.Error for all non-2xx responses. Unwrap it with errors.As, then branch on StatusCode:

_, err := client.Messages.New(ctx, params)
if err != nil {
    var apierr *anthropic.Error
    if errors.As(err, &apierr) {
        switch apierr.StatusCode {
        case 404:
            // bad model ID / resource
        case 429:
            // back off and retry
        default:
            // other API error — apierr.StatusCode, apierr.RequestID
        }
    } else {
        // transport-level error (*url.Error wrapping *net.OpError, etc.)
    }
}

Error .type Field

All APIStatusError subclasses now expose a .type property (Python: .type, TypeScript: .type, Java: .errorType(), Go: .Type(), Ruby: .type, PHP: .type) that returns the API error type string (e.g., "invalid_request_error", "authentication_error", "rate_limit_error", "overloaded_error"). Use this for programmatic error classification when you need finer granularity than the HTTP status code — for example, distinguishing "billing_error" from "permission_error" (both map to 403).

except anthropic.APIStatusError as e:
    if e.type == "rate_limit_error":
        # handle rate limiting
    elif e.type == "overloaded_error":
        # handle overload

Live Documentation Sources

This file contains WebFetch URLs for fetching current information from platform.claude.com and Agent SDK repositories. Use these when users need the latest data that may have changed since the cached content was last updated.

When to Use WebFetch

  • User explicitly asks for "latest" or "current" information
  • Cached data seems incorrect
  • User asks about features not covered in cached content
  • User needs specific API details or examples

Claude API Documentation URLs

Models & Pricing

Topic URL Extraction Prompt
Models Overview https://platform.claude.com/docs/en/about-claude/models/overview.md "Extract current model IDs, context windows, and pricing for all Claude models"
Migration Guide https://platform.claude.com/docs/en/about-claude/models/migration-guide.md "Extract breaking changes, deprecated parameters, and per-model migration steps when moving to a newer Claude model"
Introducing Claude Fable 5 https://platform.claude.com/docs/en/about-claude/models/introducing-claude-fable-5.md "Extract capabilities, API changes, and availability stages for Claude Fable 5 and Claude Mythos 5"
Pricing https://platform.claude.com/docs/en/pricing.md "Extract current pricing per million tokens for input and output"

Core Features

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"
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"
Prompt Caching https://platform.claude.com/docs/en/build-with-claude/prompt-caching.md "Extract cache_control usage, pricing benefits, and implementation examples"

Media & Files

Topic URL Extraction Prompt
Vision https://platform.claude.com/docs/en/build-with-claude/vision.md "Extract supported image formats, size limits, and code examples"
PDF Support https://platform.claude.com/docs/en/build-with-claude/pdf-support.md "Extract PDF handling capabilities, limits, and examples"

API Operations

Topic URL Extraction Prompt
Batch Processing https://platform.claude.com/docs/en/build-with-claude/batch-processing.md "Extract batch API endpoints, request format, and polling for results"
Files API https://platform.claude.com/docs/en/build-with-claude/files.md "Extract file upload, download, and referencing in messages, including supported types and beta header"
Token Counting https://platform.claude.com/docs/en/build-with-claude/token-counting.md "Extract token counting API usage and examples"
Rate Limits https://platform.claude.com/docs/en/api/rate-limits.md "Extract current rate limits by tier and model"
Errors https://platform.claude.com/docs/en/api/errors.md "Extract HTTP error codes, meanings, and retry guidance"
Amazon Bedrock https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock.md "Extract the AnthropicBedrockMantle client per language, anthropic.-prefixed model IDs, auth paths, feature availability, and regions"
Claude Platform on AWS https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws.md "Extract the AnthropicAWS client per language, SigV4 auth, credential precedence, short-term API keys, workspace_id, and region requirements"
Claude Platform on AWS — IAM actions https://platform.claude.com/docs/en/api/claude-platform-on-aws-iam-actions.md "Extract the IAM action names, resource ARNs, and policy examples required for each API capability"

Tools

Topic URL Extraction Prompt
Code Execution https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool.md "Extract code execution tool setup, file upload, container reuse, and response handling"
Computer Use https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use.md "Extract computer use tool setup, capabilities, and implementation examples"
Bash Tool https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool.md "Extract bash tool schema, reference implementation, and security considerations"
Text Editor https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool.md "Extract text editor tool commands, schema, and reference implementation"
Memory Tool https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool.md "Extract memory tool commands, directory structure, and implementation patterns"
Tool Search https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool.md "Extract tool search setup, when to use, and cache interaction"
Programmatic Tool Calling https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling.md "Extract PTC setup, script execution model, and tool invocation from code"
Skills https://platform.claude.com/docs/en/agents-and-tools/skills.md "Extract skill folder structure, SKILL.md format, and loading behavior"

Advanced Features

Topic URL Extraction Prompt
Structured Outputs https://platform.claude.com/docs/en/build-with-claude/structured-outputs.md "Extract output_config.format usage and schema enforcement"
Compaction https://platform.claude.com/docs/en/build-with-claude/compaction.md "Extract compaction setup, trigger config, and streaming with compaction"
Context Editing https://platform.claude.com/docs/en/build-with-claude/context-editing.md "Extract context editing thresholds, what gets cleared, and configuration"
Citations https://platform.claude.com/docs/en/build-with-claude/citations.md "Extract citation format and implementation"
Context Windows https://platform.claude.com/docs/en/build-with-claude/context-windows.md "Extract context window sizes and token management"

Managed Agents

Use these when a managed-agents binding, behavior, or wire-level detail isn't covered in the cached shared/managed-agents-*.md concept files or in {lang}/managed-agents/README.md.

Topic URL Extraction Prompt
Overview https://platform.claude.com/docs/en/managed-agents/overview.md "Extract the high-level architecture and how agents/sessions/environments/vaults fit together"
Quickstart https://platform.claude.com/docs/en/managed-agents/quickstart.md "Extract the minimal end-to-end agent → environment → session → stream code path"
Agent Setup https://platform.claude.com/docs/en/managed-agents/agent-setup.md "Extract agent create/update/list-versions/archive lifecycle and parameters"
Define Outcomes https://platform.claude.com/docs/en/managed-agents/define-outcomes.md "Extract outcome definitions, evaluation hooks, and success criteria configuration"
Sessions https://platform.claude.com/docs/en/managed-agents/sessions.md "Extract session lifecycle, status transitions, idle/terminated semantics, and resume rules"
Environments https://platform.claude.com/docs/en/managed-agents/environments.md "Extract environment config (cloud/networking), management endpoints, and reuse model"
Self-Hosted Sandboxes https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes.md "Extract config:{type:self_hosted}, ANTHROPIC_ENVIRONMENT_KEY, EnvironmentWorker.run/run_one, beta_agent_toolset, ant beta:worker poll/run, webhook-driven wake"
Self-Hosted Sandboxes — Security https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-security.md "Extract what the customer owns (hardening, egress, key custody, trust boundaries) vs what Anthropic cannot do"
Events and Streaming https://platform.claude.com/docs/en/managed-agents/events-and-streaming.md "Extract event stream types, stream-first ordering, reconnect/dedupe, and steering patterns"
Tools https://platform.claude.com/docs/en/managed-agents/tools.md "Extract built-in toolset, custom tool definitions, and tool result wire format"
Files https://platform.claude.com/docs/en/managed-agents/files.md "Extract file upload, mount paths, session resources, and listing/downloading session outputs"
Permission Policies https://platform.claude.com/docs/en/managed-agents/permission-policies.md "Extract permission policy types (allow/deny/confirm) and per-tool config"
Multi-Agent https://platform.claude.com/docs/en/managed-agents/multi-agent.md "Extract multi-agent composition patterns, sub-agent invocation, and result handoff"
Observability https://platform.claude.com/docs/en/managed-agents/observability.md "Extract logging, tracing, and usage telemetry exposed by managed agents"
Webhooks https://platform.claude.com/docs/en/managed-agents/webhooks.md "Extract webhook endpoint registration, HMAC signature verification, supported event types, and delivery semantics"
GitHub https://platform.claude.com/docs/en/managed-agents/github.md "Extract github_repository resource shape, multi-repo mounting, and token rotation"
MCP Connector https://platform.claude.com/docs/en/managed-agents/mcp-connector.md "Extract MCP server declaration on agents and vault-based credential injection at session"
Vaults https://platform.claude.com/docs/en/managed-agents/vaults.md "Extract vault create, credential add/rotate, OAuth refresh shape, and archive"
Skills https://platform.claude.com/docs/en/managed-agents/skills.md "Extract skill packaging and loading model for managed agents"
Memory https://platform.claude.com/docs/en/managed-agents/memory.md "Extract memory resource shape, scoping, and lifecycle"
Onboarding https://platform.claude.com/docs/en/managed-agents/onboarding.md "Extract first-run setup, prerequisites, and account/region requirements"
Cloud Containers https://platform.claude.com/docs/en/managed-agents/cloud-containers.md "Extract cloud container runtime, image config, and network/storage knobs"
Migration https://platform.claude.com/docs/en/managed-agents/migration.md "Extract migration paths from earlier APIs/preview shapes to GA managed agents"

Anthropic CLI

The ant CLI provides terminal access to the Claude API. Every API resource is exposed as a subcommand. It is one convenient way to create agents, environments, sessions, and other resources from version-controlled YAML, and to inspect responses interactively.

Topic URL Extraction Prompt
Anthropic CLI https://platform.claude.com/docs/en/api/sdks/cli.md "Extract CLI install, authentication, command structure, and the beta:agents/environments/sessions commands"
Authentication overview https://platform.claude.com/docs/en/manage-claude/authentication.md "Extract the credential options (API keys, interactive OAuth login, Workload Identity Federation) and when to use each"
WIF reference https://platform.claude.com/docs/en/manage-claude/wif-reference.md "Extract credential precedence order, the profile configuration file schema, and the configuration directory layout"

Claude API SDK Repositories

WebFetch these when a binding (class, method, namespace, field) isn't covered in the cached {lang}/ skill files or in the managed-agents docs above. The SDKs include beta managed-agents support for /v1/agents, /v1/sessions, /v1/environments, and related resources — search the repo for BetaManagedAgents, beta.agents, beta.sessions, or the equivalent namespace for that language.

SDK URL Extraction Prompt
Python https://github.com/anthropics/anthropic-sdk-python "Extract beta managed-agents namespaces, classes, and method signatures (client.beta.agents, client.beta.sessions)"
TypeScript https://github.com/anthropics/anthropic-sdk-typescript "Extract beta managed-agents namespaces, classes, and method signatures (client.beta.agents, client.beta.sessions)"
Java https://github.com/anthropics/anthropic-sdk-java "Extract beta managed-agents classes, builders, and method signatures (client.beta().agents(), BetaManagedAgents*)"
Go https://github.com/anthropics/anthropic-sdk-go "Extract beta managed-agents types and method signatures (client.Beta.Agents, BetaManagedAgents* event types)"
Ruby https://github.com/anthropics/anthropic-sdk-ruby "Extract beta managed-agents methods and parameter shapes (client.beta.agents, client.beta.sessions)"
C# https://github.com/anthropics/anthropic-sdk-csharp "Extract beta managed-agents classes and method signatures (NuGet package, BetaManagedAgents* types)"
PHP https://github.com/anthropics/anthropic-sdk-php "Extract beta managed-agents classes and method signatures ($client->beta->agents, BetaManagedAgents* params)"

Each SDK repo also ships runnable programs under examples/ — including the refusal-fallback / fallbacks examples (client-side middleware registration, fallback state, server-side fallbacks param). Fetch those for exact per-language syntax instead of translating another language's example.

Fallback Strategy

If WebFetch fails (network issues, URL changed):

  1. Use cached content from the language-specific files (note the cache date)
  2. Inform user the data may be outdated
  3. Suggest they check platform.claude.com or the GitHub repos directly

Managed Agents — Endpoint Reference

All endpoints require x-api-key and anthropic-version: 2023-06-01 headers. Managed Agents endpoints additionally require the anthropic-beta header.

Beta Headers

anthropic-beta: managed-agents-2026-04-01

The SDK adds this header automatically for all client.beta.{agents,environments,sessions,vaults,memory_stores,deployments,deployment_runs}.* calls. Skills endpoints use skills-2025-10-02; Files endpoints use files-api-2025-04-14.

SDK Method Reference

All resources are under the beta namespace. Python and TypeScript share identical method names.

Resource Python / TypeScript (client.beta.*) Go (client.Beta.*)
Agents agents.create / retrieve / update / list / archive Agents.New / Get / Update / List / Archive
Agent Versions agents.versions.list Agents.Versions.List
Environments environments.create / retrieve / update / list / delete / archive Environments.New / Get / Update / List / Delete / Archive
Environment Work (self-hosted) environments.work.poller / stats / stop See shared/managed-agents-self-hosted-sandboxes.md
Sessions sessions.create / retrieve / update / list / delete / archive Sessions.New / Get / Update / List / Delete / Archive
Session Events sessions.events.list / send / stream Sessions.Events.List / Send / StreamEvents
Session Threads sessions.threads.list / retrieve / archive; sessions.threads.events.list / stream Sessions.Threads.List / Get / Archive; Sessions.Threads.Events.List / StreamEvents
Session Resources sessions.resources.add / retrieve / update / list / delete Sessions.Resources.Add / Get / Update / List / Delete
Deployments deployments.create / pause / unpause / archive / run Not yet documented — WebFetch the SDK repo (shared/live-sources.md)
Deployment Runs deployment_runs.list / retrieve (TS: deploymentRuns.*) Not yet documented — WebFetch the SDK repo (shared/live-sources.md)
Vaults vaults.create / retrieve / update / list / delete / archive Vaults.New / Get / Update / List / Delete / Archive
Credentials vaults.credentials.create / retrieve / update / list / delete / archive / mcp_oauth_validate Vaults.Credentials.New / Get / Update / List / Delete / Archive / McpOauthValidate
Memory Stores memory_stores.create / retrieve / update / list / delete / archive MemoryStores.New / Get / Update / List / Delete / Archive
Memories memory_stores.memories.create / retrieve / update / list / delete MemoryStores.Memories.New / Get / Update / List / Delete
Memory Versions memory_stores.memory_versions.list / retrieve / redact MemoryStores.MemoryVersions.List / Get / Redact

Naming quirks to watch for: - Agents and Session Threads have no delete — only archive. Archive is permanent: the agent becomes read-only, new sessions cannot reference it, and there is no unarchive. Confirm with the user before archiving a production agent. Environments, Sessions, Vaults, Credentials, and Memory Stores have both delete and archive; Session Resources, Files, Skills, and Memories are delete-only; Memory Versions have neither — only redact. - Session resources use add (not create). - Go's event stream is StreamEvents (not Stream). - The self-hosted worker is not under client.beta.* — it's EnvironmentWorker from anthropic.lib.environments / @anthropic-ai/sdk/helpers/beta/environments; only environments.work.poller/stats/stop are client methods.

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 ({id: "claude-opus-4-8", speed: "fast"}). 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.

Agents

Step one of every flow. Sessions require a pre-created agent — there is no inline agent config under managed-agents-2026-04-01.

Method Path Operation Description
GET /v1/agents ListAgents List agents
POST /v1/agents CreateAgent Create a saved agent configuration
GET /v1/agents/{agent_id} GetAgent Get agent details
POST /v1/agents/{agent_id} UpdateAgent Update agent configuration
POST /v1/agents/{agent_id}/archive ArchiveAgent Archive an agent. Makes it read-only; existing sessions continue, new sessions cannot reference it. No unarchive — this is the terminal state.
GET /v1/agents/{agent_id}/versions ListAgentVersions List agent versions

Sessions

Method Path Operation Description
GET /v1/sessions ListSessions List sessions (paginated)
POST /v1/sessions CreateSession Create a new session
GET /v1/sessions/{session_id} GetSession Get session details
POST /v1/sessions/{session_id} UpdateSession Update session metadata/title, or agent.tools/agent.mcp_servers/vault_ids (session-local override; session must be idle). See shared/managed-agents-core.md → Updating the agent configuration mid-session.
DELETE /v1/sessions/{session_id} DeleteSession Delete a session
POST /v1/sessions/{session_id}/archive ArchiveSession Archive a session

Events

Method Path Operation Description
GET /v1/sessions/{session_id}/events ListEvents List events (polling, paginated)
POST /v1/sessions/{session_id}/events SendEvents Send events (user message, tool result)
GET /v1/sessions/{session_id}/events/stream StreamEvents Stream events via SSE. Optional event_deltas[]=agent.message / agent.thinking opts in to live-preview event_start/event_delta events — see shared/managed-agents-events.md § Live previews.

Session Threads

Per-subagent event streams in multiagent sessions. See shared/managed-agents-multiagent.md.

Method Path Operation Description
GET /v1/sessions/{session_id}/threads ListThreads List threads (paginated)
GET /v1/sessions/{session_id}/threads/{thread_id} GetThread Retrieve one thread (carries agent snapshot, status, parent_thread_id, stats, usage)
POST /v1/sessions/{session_id}/threads/{thread_id}/archive ArchiveThread Archive a thread
GET /v1/sessions/{session_id}/threads/{thread_id}/events ListThreadEvents List past events for one thread (paginated)
GET /v1/sessions/{session_id}/threads/{thread_id}/stream StreamThreadEvents Stream one thread via SSE (SDK: threads.events.stream)

Session Resources

Method Path Operation Description
GET /v1/sessions/{session_id}/resources ListResources List resources attached to session
POST /v1/sessions/{session_id}/resources AddResource Attach file or github_repository resource (SDK method: add, not create). memory_store resources attach at session-create time only.
GET /v1/sessions/{session_id}/resources/{resource_id} GetResource Get a single resource
POST /v1/sessions/{session_id}/resources/{resource_id} UpdateResource Update resource
DELETE /v1/sessions/{session_id}/resources/{resource_id} DeleteResource Remove resource from session

Environments

Method Path Operation Description
POST /v1/environments CreateEnvironment Create environment
GET /v1/environments ListEnvironments List environments
GET /v1/environments/{environment_id} GetEnvironment Get environment details
POST /v1/environments/{environment_id} UpdateEnvironment Update environment
DELETE /v1/environments/{environment_id} DeleteEnvironment Delete environment. Returns 204.
POST /v1/environments/{environment_id}/archive ArchiveEnvironment Archive environment. Makes it read-only; existing sessions continue, new sessions cannot reference it. No unarchive — this is the terminal state.
GET /v1/environments/{environment_id}/work/stats WorkQueueStats Self-hosted work-queue depth/pending/workers. x-api-key auth. See shared/managed-agents-self-hosted-sandboxes.md.
POST /v1/environments/{environment_id}/work/{work_id}/stop StopWork Self-hosted: stop a claimed work item. x-api-key auth.

For type: "self_hosted", config is the bare {"type": "self_hosted"} — networking and packages do not apply.

Deployments

Scheduled deployments (depl_ IDs) run an agent on a recurring cron schedule — each firing creates a session. See shared/managed-agents-scheduled-deployments.md for the conceptual guide (cron/DST semantics, failure behavior, lifecycle).

Method Path Operation Description
POST /v1/deployments CreateDeployment Create a scheduled deployment
POST /v1/deployments/{deployment_id}/pause PauseDeployment Suppress scheduled triggers (reversible; manual runs still allowed)
POST /v1/deployments/{deployment_id}/unpause UnpauseDeployment Resume from the next occurrence (no backfill)
POST /v1/deployments/{deployment_id}/archive ArchiveDeployment Terminal — schedule stops, deployment becomes immutable
POST /v1/deployments/{deployment_id}/run RunDeployment Trigger a manual run immediately (trigger_context.type: "manual"); works while paused

Deployment Runs

Each trigger attempt (scheduled or manual) writes a deployment_run record (drun_ IDs) carrying either the created session_id or an error.type (environment_archived, agent_archived, vault_not_found, session_rate_limited, service_unavailable).

Method Path Operation Description
GET /v1/deployment_runs?deployment_id=... ListDeploymentRuns List runs for a deployment (paginated; filter failures with has_error=true)
GET /v1/deployment_runs/{deployment_run_id} GetDeploymentRun Retrieve a single run by ID (a deployment_run.* webhook event carries this as data.id)

Vaults

Vaults store credentials that Anthropic manages on your behalf — MCP credentials (OAuth with auto-refresh, or static bearer tokens) and environment_variable credentials substituted into outbound requests at egress. Attach to sessions via vault_ids. See managed-agents-tools.md §Vaults for the conceptual guide and credential shapes.

Method Path Operation Description
POST /v1/vaults CreateVault Create a vault
GET /v1/vaults ListVaults List vaults
GET /v1/vaults/{vault_id} GetVault Get vault details
POST /v1/vaults/{vault_id} UpdateVault Update vault
DELETE /v1/vaults/{vault_id} DeleteVault Delete vault
POST /v1/vaults/{vault_id}/archive ArchiveVault Archive vault

Credentials

Credentials are individual secrets stored inside a vault.

Method Path Operation Description
POST /v1/vaults/{vault_id}/credentials CreateCredential Create a credential
GET /v1/vaults/{vault_id}/credentials ListCredentials List credentials in vault
GET /v1/vaults/{vault_id}/credentials/{credential_id} GetCredential Get credential metadata
POST /v1/vaults/{vault_id}/credentials/{credential_id} UpdateCredential Update credential
DELETE /v1/vaults/{vault_id}/credentials/{credential_id} DeleteCredential Delete credential
POST /v1/vaults/{vault_id}/credentials/{credential_id}/archive ArchiveCredential Archive credential
POST /v1/vaults/{vault_id}/credentials/{credential_id}/mcp_oauth_validate McpOauthValidate Validate an MCP OAuth credential

Memory Stores

Workspace-scoped persistent memory that survives across sessions. Attach to a session via a {"type": "memory_store", "memory_store_id": ...} entry in resources[] (session-create time only). See shared/managed-agents-memory.md for the conceptual guide, the FUSE-mount agent interface, preconditions, and versioning.

Method Path Operation Description
POST /v1/memory_stores CreateMemoryStore Create a store (name, description, metadata)
GET /v1/memory_stores ListMemoryStores List stores (include_archived, created_at_{gte,lte})
GET /v1/memory_stores/{memory_store_id} GetMemoryStore Get store details
POST /v1/memory_stores/{memory_store_id} UpdateMemoryStore Update store
DELETE /v1/memory_stores/{memory_store_id} DeleteMemoryStore Delete store
POST /v1/memory_stores/{memory_store_id}/archive ArchiveMemoryStore Archive store. Makes it read-only; existing sessions continue, new sessions cannot reference it. No unarchive.

Memories

Individual text documents inside a store (≤ 100KB each). create creates at a path and returns 409 (memory_path_conflict_error, with conflicting_memory_id) if the path is occupied; update mutates by mem_... ID (rename and/or content). Only update accepts a precondition ({"type": "content_sha256", "content_sha256": ...}) — on mismatch returns 409 (memory_precondition_failed_error). List endpoints accept view: "basic"|"full" (controls whether content is populated; retrieve defaults to full).

Method Path Operation Description
GET /v1/memory_stores/{memory_store_id}/memories ListMemories Returns Memory \| MemoryPrefix; filter by path_prefix, depth, order_by/order
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
DELETE /v1/memory_stores/{memory_store_id}/memories/{memory_id} DeleteMemory Delete (optional expected_content_sha256)

Memory Versions

Immutable per-mutation snapshots (memver_...) — the audit and rollback surface. operation ∈ created / modified / deleted.

Method Path Operation Description
GET /v1/memory_stores/{memory_store_id}/memory_versions ListMemoryVersions Newest-first; filter by memory_id, operation, session_id, api_key_id, created_at_{gte,lte}
GET /v1/memory_stores/{memory_store_id}/memory_versions/{version_id} GetMemoryVersion List fields + full content
POST /v1/memory_stores/{memory_store_id}/memory_versions/{version_id}/redact RedactMemoryVersion Clear content/content_sha256/content_size_bytes/path; preserve actor + timestamps

Files

Method Path Operation Description
POST /v1/files UploadFile Upload a file
GET /v1/files ListFiles List files
GET /v1/files/{file_id} GetFile Get file metadata (SDK method: retrieve_metadata)
GET /v1/files/{file_id}/content DownloadFile Download file content
DELETE /v1/files/{file_id} DeleteFile Delete a file

Skills

Method Path Operation Description
POST /v1/skills CreateSkill Create a skill
GET /v1/skills ListSkills List skills
GET /v1/skills/{skill_id} GetSkill Get skill details
DELETE /v1/skills/{skill_id} DeleteSkill Delete a skill
POST /v1/skills/{skill_id}/versions CreateVersion Create skill version
GET /v1/skills/{skill_id}/versions ListVersions List skill versions
GET /v1/skills/{skill_id}/versions/{version} GetVersion Get skill version
DELETE /v1/skills/{skill_id}/versions/{version} DeleteVersion Delete skill version

Request/Response Schema Quick Reference

CreateAgent Request Body

Always start here. model, system, tools, mcp_servers, skills are top-level fields on this object — they do NOT go on the session.

{
  "name": "string (required, 1-256 chars)",
  "model": "claude-opus-4-8 (required — bare string, or {id, speed} object)",
  "description": "string (optional, up to 2048 chars)",
  "system": "string (optional, up to 100,000 chars)",
  "tools": [
    { "type": "agent_toolset_20260401" }
  ],
  "skills": [
    { "type": "anthropic", "skill_id": "xlsx" },
    { "type": "custom", "skill_id": "skill_abc123", "version": "1" }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "name": "github",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  ],
  "multiagent": {
    "type": "coordinator",
    "agents": [
      "agent_abc123",
      { "type": "agent", "id": "agent_def456", "version": 4 },
      { "type": "self" }
    ]
  },
  "metadata": {
    "key": "value (max 16 pairs, keys ≤64 chars, values ≤512 chars)"
  }
}

Limits: tools max 128, skills max 20, mcp_servers max 20 (unique names). multiagent.agents 1–20 entries (string ID | {type:"agent",id,version?} | {type:"self"}) — see shared/managed-agents-multiagent.md.

CreateSession Request Body

{
  "agent": "agent_abc123 (required — string shorthand for latest version, or {type: \"agent\", id, version} object)",
  "environment_id": "env_abc123 (required)",
  "title": "string (optional)",
  "resources": [
    {
      "type": "github_repository",
      "url": "https://github.com/owner/repo (required)",
      "authorization_token": "ghp_... (required)",
      "mount_path": "/workspace/repo (optional — defaults to /workspace/<repo-name>)",
      "checkout": { "type": "branch", "name": "main" }
    }
  ],
  "vault_ids": ["vlt_abc123 (optional — vault credentials: MCP auth + environment variables)"],
  "metadata": {
    "key": "value"
  }
}

The agent field accepts a string ID, {type: "agent", id, version}, or {type: "agent_with_overrides", id, version?, ...} for session-local overrides of model/system/tools/mcp_servers/skills. Outside the overrides form, those fields live on the agent, not here.

checkout accepts {type: "branch", name: "..."} or {type: "commit", sha: "..."}. Omit for the repo's default branch.

CreateEnvironment Request Body

{
  "name": "string (required)",
  "description": "string (optional)",
  "config": {
    "type": "cloud | self_hosted",
    "networking": {
      "type": "unrestricted | limited (union — see SDK types)"
    },
    "packages": { }
  },
  "metadata": { "key": "value" }
}

CreateDeployment Request Body

{
  "name": "Weekly compliance scan",
  "agent": "agent_abc123 (required — same shapes as CreateSession)",
  "environment_id": "env_abc123 (required)",
  "initial_events": [
    { "type": "user.message", "content": [{ "type": "text", "text": "Run the weekly compliance scan." }] }
  ],
  "schedule": {
    "type": "cron",
    "expression": "0 20 * * 5",
    "timezone": "America/New_York"
  }
}

Optional session config (resources, vault_ids, etc.) is supported the same way as on CreateSession. Response includes status, paused_reason, and schedule.upcoming_runs_at (next fire times). See shared/managed-agents-scheduled-deployments.md.

SendEvents Request Body

{
  "events": [
    {
      "type": "user.message",
      "content": [
        {
          "type": "text",
          "text": "Hello"
        }
      ]
    }
  ]
}

system.message events (update the system prompt between turns) use the same envelope with type: "system.message" — Claude Opus 4.8 only; see shared/managed-agents-events.md § Updating the system prompt mid-session.

Define Outcome Event

{
  "type": "user.define_outcome",
  "description": "Build a DCF model for Costco in .xlsx",
  "rubric": { "type": "file", "file_id": "file_01..." },
  "max_iterations": 5
}

rubric is required: {type: "text", content} or {type: "file", file_id}. max_iterations default 3, max 20. Echoed back with outcome_id + processed_at. See shared/managed-agents-outcomes.md.

Tool Result Event

{
  "type": "user.custom_tool_result",
  "custom_tool_use_id": "sevt_abc123",
  "content": [{ "type": "text", "text": "Result data" }],
  "is_error": false
}

Error Handling

Managed Agents endpoints use the standard Anthropic API error format. Errors are returned with an HTTP status code and a JSON body containing type, error, and request_id:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Description of what went wrong"
  },
  "request_id": "req_011CRv1W3XQ8XpFikNYG7RnE"
}

Include the request_id when reporting issues to Anthropic — it lets us trace the request end-to-end. The inner error.type is one of the following:

Status Error type Description
400 invalid_request_error The request was malformed or missing required parameters
401 authentication_error Invalid or missing API key
403 permission_error The API key doesn't have permission for this operation
404 not_found_error The requested resource doesn't exist
409 invalid_request_error The request conflicts with the resource's current state (e.g., sending to an archived session)
413 request_too_large The request body exceeds the maximum allowed size
429 rate_limit_error Too many requests — check rate limit headers for retry timing
500 api_error An internal server error occurred
529 overloaded_error The service is temporarily overloaded — retry with backoff

Note that 409 Conflict carries error.type: "invalid_request_error" (there is no separate conflict_error type); inspect both the HTTP status and the message to distinguish conflicts from other invalid requests.

Pagination

Most Managed Agents list endpoints use the page / next_page cursor scheme:

Field Where Notes
limit query Max items per page
page query Opaque cursor from a previous response — pass a next_page or prev_page value here
order query asc / desc on endpoints that support sorting. A cursor encodes the order of the request that produced it — reusing it with a different order returns 400. Other params (filters, limit) can change between paginated requests.
next_page response Cursor for the next page; null when there are no more results
prev_page response Cursor for the previous page on endpoints that support backward pagination — currently only GET /v1/sessions. null on the first page. On endpoints that don't support it, the field is absent (not null).

Every SDK exposes an auto-paginating iterator that follows next_page. In Python and TypeScript, iterate the list result directly; the other SDKs expose the iterator via a separate method (iterating the plain list result returns one page). SDK auto-pagination is forward-only — to go back a page, read prev_page from the response and pass it back as the page parameter yourself.

⚠️ Some endpoints use a different cursor scheme: Message Batches, Files, Models, and several Admin API endpoints take after_id/before_id and return has_more/first_id/last_id instead of page/next_page. Some page-scheme endpoints (e.g. GET /v1/skills) also return a has_more boolean alongside next_page. Check the endpoint's reference page for its exact pagination fields.

Rate Limits

Managed Agents endpoints have per-organization request-per-minute (RPM) limits, separate from your Messages API token limits. Model inference inside a session still draws from your organization's standard ITPM/OTPM limits.

Endpoint group Scope RPM Max concurrent
Create operations (Agents, Sessions, Vaults) organization 300 —
All other operations (Agents, Sessions, Vaults) organization 600 —
All operations (Environments) organization 60 5

Files and Skills endpoints use the standard tier-based rate limits.

When a limit is exceeded the API returns 429 with a rate_limit_error (see Error Handling for the response envelope) and a retry-after header indicating how many seconds to wait before retrying. The Anthropic SDK reads this header and retries automatically.

Managed Agents — Common Client Patterns

Patterns you'll write on the client side when driving a Managed Agent session, grounded in working SDK examples.

Code samples are TypeScript — other languages follow the same shape; see {lang}/managed-agents/README.md (cURL and C#: curl/managed-agents.md) for equivalents.

1. Lossless stream reconnect

Problem: SSE has no replay. If the connection drops mid-session, a naive reconnect re-opens the stream from "now" and you silently miss every event emitted in between.

Solution: on reconnect, fetch the full event history via events.list() before consuming the live stream, and dedupe on event ID as the live stream catches up.

const seenEventIds = new Set<string>()
const stream = await client.beta.sessions.events.stream(session.id)

// Stream is now open and buffering server-side. Read history first.
for await (const event of client.beta.sessions.events.list(session.id)) {
  seenEventIds.add(event.id)
  handle(event)
}

// Tail the live stream. Dedupe only gates handle() — terminal checks must run
// even for already-seen events, or a terminal event that was in the history
// response gets skipped by `continue` and the loop never exits.
for await (const event of stream) {
  if (!seenEventIds.has(event.id)) {
    seenEventIds.add(event.id)
    handle(event)
  }
  if (event.type === 'session.status_terminated') break
  if (event.type === 'session.status_idle' && event.stop_reason.type !== 'requires_action') break
}

2. processed_at — queued vs processed

Every event on the stream carries processed_at (ISO 8601). For client-sent events (user.message, user.interrupt, user.tool_confirmation, user.custom_tool_result) it's null when the event has been queued but not yet picked up by the agent, and populated once the agent processes it. The same event appears on the stream twice — once with processed_at: null, once with a timestamp.

for await (const event of stream) {
  if (event.type === 'user.message') {
    if (event.processed_at == null) onQueued(event.id)
    else onProcessed(event.id, event.processed_at)
  }
}

Use this to drive pending → acknowledged UI state for anything you send. How you map a locally-rendered optimistic message to the server-assigned event.id is application-specific (typically via the return value of events.send() or FIFO ordering).

3. Interrupt a running session

Send user.interrupt as a normal event. The session keeps running until it reaches a safe boundary, then goes idle.

await client.beta.sessions.events.send(session.id, {
  events: [{ type: 'user.interrupt' }],
})

// Drain until the session is truly done — see Pattern 5 for the full gate.
for await (const event of stream) {
  if (event.type === 'session.status_terminated') break
  if (
    event.type === 'session.status_idle' &&
    event.stop_reason.type !== 'requires_action'
  ) break
}

Reference: interrupt.ts — sends the interrupt the moment it sees span.model_request_start, drains to idle, then verifies via sessions.retrieve().

4. tool_confirmation round-trip

When the agent has permission_policy: { type: 'always_ask' }, any call to that tool fires an agent.tool_use event with evaluated_permission === 'ask' and the session goes idle waiting for a decision. Respond with user.tool_confirmation.

for await (const event of stream) {
  if (event.type === 'agent.tool_use' && event.evaluated_permission === 'ask') {
    await client.beta.sessions.events.send(session.id, {
      events: [{
        type: 'user.tool_confirmation',
        tool_use_id: event.id,         // not a toolu_ id — use event.id
        result: 'allow',               // or 'deny'
        // deny_message: '...',        // optional, only with result: 'deny'
      }],
    })
  }
}

Key points: - tool_use_id is event.id (typically sevt_...), not a toolu_... ID. - result is 'allow' | 'deny'. Use deny_message to tell the model why you denied — it gets surfaced back to the agent. - Multiple pending tools: respond once per agent.tool_use event with evaluated_permission === 'ask'.

Reference: tool-permissions.ts.

5. Correct idle-break gate

Do not break on session.status_idle alone. The session goes idle transiently — e.g. between parallel tool executions, while waiting for a user.tool_confirmation, or while awaiting a user.custom_tool_result. Break when idle with a terminal stop_reason, or on session.status_terminated.

for await (const event of stream) {
  handle(event)
  if (event.type === 'session.status_terminated') break
  if (event.type === 'session.status_idle') {
    if (event.stop_reason.type === 'requires_action') continue // waiting on you — handle it
    break // end_turn or retries_exhausted — both terminal
  }
}

stop_reason.type values on session.status_idle: - requires_action — agent is waiting on a client-side event (tool confirmation, custom tool result). Handle it, don't break. - retries_exhausted — terminal failure. Break, then check sessions.retrieve() for the error state. - end_turn — normal completion.

6. Post-idle status-write race

The SSE stream emits session.status_idle slightly before the session's queryable status reflects it. Clients that break on idle and immediately call sessions.delete() or sessions.archive() will intermittently 400 with "cannot delete/archive while running."

Poll before cleanup:

let s
for (let i = 0; i < 10; i++) {
  s = await client.beta.sessions.retrieve(session.id)
  if (s.status !== 'running') break
  await new Promise(r => setTimeout(r, 200))
}
if (s?.status !== 'running') {
  await client.beta.sessions.archive(session.id)
} // else: still running after 2s — don't archive, let it settle or escalate

7. Stream-first, then send

Always open the stream before sending the kickoff event. Otherwise the agent may process the event and emit the first events before your consumer is attached, and you'll miss them.

const stream = await client.beta.sessions.events.stream(session.id)
await client.beta.sessions.events.send(session.id, {
  events: [{ type: 'user.message', content: [{ type: 'text', text: 'Hello' }] }],
})
for await (const event of stream) { /* ... */ }

The Promise.all([stream, send]) shape works too, but stream-first is simpler and has the same effect — the stream starts buffering the moment it's opened.

8. File-mount gotchas

The mounted resource has a different file_id than the file you uploaded. Session creation makes a session-scoped copy.

const uploaded = await client.beta.files.upload({ file, purpose: 'agent_resource' })
// uploaded.id         → the original file
const session = await client.beta.sessions.create({
  /* ... */
  resources: [{ type: 'file', file_id: uploaded.id, mount_path: '/workspace/data.csv' }],
})
// session.resources[0].file_id !== uploaded.id  ← different IDs

Delete the original via files.delete(uploaded.id); the session-scoped copy is garbage-collected with the session. mount_path must be absolute — see shared/managed-agents-environments.md.

9. Secrets for non-MCP APIs and CLIs — keep them host-side via custom tools

Problem: you want the agent to call a third-party API or run a CLI that needs a secret (API key, token, service-account credential), but you can't or don't want to hand the secret to a vault.

First check: for cloud environments, the first-class answer is now a vault environment_variable credential — the agent's shell sees an opaque placeholder and the real secret is substituted at egress. See shared/managed-agents-tools.md → Vaults. Use this pattern instead when that doesn't fit: self-hosted sandboxes (env-var credentials not yet supported there), clients that reject the placeholder via local format validation, secrets that must never leave your infrastructure, or calls that need host-side binaries.

Solution: move the authenticated call to your side. Declare a custom tool on the agent; when the agent emits agent.custom_tool_use, your orchestrator (the process reading the SSE stream) executes the call with its own credentials and responds with user.custom_tool_result. The container never sees the key.

// Agent template: declare the tool, no credentials
tools: [{ type: 'custom', name: 'linear_graphql', input_schema: { /* query, vars */ } }]

// Orchestrator: handle the call with host-side creds
for await (const event of stream) {
  if (event.type === 'agent.custom_tool_use' && event.name === 'linear_graphql') {
    const result = await linear.request(event.input.query, event.input.vars) // host's key
    await client.beta.sessions.events.send(session.id, {
      events: [{ type: 'user.custom_tool_result', tool_use_id: event.id, result }],
    })
  }
}

Same shape works for gh CLI, local eval scripts, or anything else that needs host-side auth or binaries.

Security note: this does not expose a public endpoint. agent.custom_tool_use arrives on the SSE stream your orchestrator already holds open with your Anthropic API key, and user.custom_tool_result goes back via events.send() under the same key. Your orchestrator is a client, not a server — nothing unauthenticated is listening.

Do not embed API keys in the system prompt or user messages as a workaround. Prompts and messages are stored in the session's event history, returned by events.list(), and included in compaction summaries — a secret placed there is durably persisted and readable via the API for the life of the session.

Managed Agents — Core Concepts

Architecture

Managed Agents is built around four core concepts:

Concept Endpoint What it is
Agent /v1/agents A persisted, versioned object defining the agent's capabilities and persona: model, system prompt, tools, MCP servers, skills. Must be created before starting a session. See the Agents section below.
Session /v1/sessions A stateful interaction with an agent. References a pre-created agent by ID + an environment + initial instructions. Produces an event stream.
Environment /v1/environments A template defining the configuration for container provisioning.
Container N/A An isolated compute instance where the agent's tools execute (bash, file ops, code). The agent loop does not run here — it runs on Anthropic's orchestration layer and acts on the container via tool calls. 
                       ┌─────────────────────────────────────┐
                       │  Anthropic orchestration layer      │
Agent (config) ───────▶│  (agent loop: Claude + tool calls)  │
                       └──────────────┬──────────────────────┘
                                      │ tool calls
                                      ▼
Environment (template) ──▶ Container (tool execution workspace)
                                 │
                         Session ─┤
                                 ├── Resources (files, repos, memory stores — attached at startup)
                                 ├── Vault IDs (MCP credential references)
                                 └── Conversation (event stream in/out)

Agent creation is a prerequisite. Sessions reference a pre-created agent by ID — model/system/tools live on the agent object, never on the session. Every flow starts with POST /v1/agents.

Session Lifecycle

rescheduling → running ↔ idle → terminated
Status Description
idle Agent has finished the current task, and is awaiting input. It's either waiting for input to continue working via a user.message or blocked awaiting a user.custom_tool_result or user.tool_confirmation. The stop_reason attached contains more information about why the Agent has stopped working.
running Session has starting running, and the Agent is actively doing work.
rescheduling Session is (re)scheduling after a retryable error has occurred, ready to be picked up by the orchestration system.
terminated Session has terminated, entering an irreversible and unusable state.
  • Events can be sent when the session is running or idle. Messages are queued and processed in order.
  • The agent transitions idle → running when it receives a new event, then back to idle when done.
  • Errors surface as session.error events in the stream, not as a status value.

Every session has a live trace view in the Anthropic Console at https://platform.claude.com/workspaces/default/sessions/{session_id}. Print this URL immediately after creating a session so the user can watch tool calls and messages stream in real time. The default workspace segment auto-resolves to the session's actual workspace on load, so you don't need the workspace id.

Built-in session features

  • Context compaction — if you approach max context, the API automatically condenses session history to keep the interaction going
  • Prompt caching — historical repeated tokens are cached, reducing processing time and cost
  • Extended thinking — on by default, returned as agent.thinking events

Session operations

Operation Notes
List / fetch Paginated list or single resource by ID
Update Only title is updatable
Archive Session becomes read-only. Not reversible.
Delete Permanently deletes session, event history, container, and checkpoints.

These are ops/inspection calls — typically made from a terminal, not application code. From the shell (see shared/anthropic-cli.md):

ant beta:sessions list --transform '{id,title,status,created_at}' --format jsonl
ant beta:sessions retrieve --session-id "$SID"
ant beta:sessions:events stream --session-id "$SID"   # watch events live
ant beta:sessions archive  --session-id "$SID"
ant beta:sessions delete   --session-id "$SID"

Sessions

A session is a running agent instance inside an environment.

Session Object

Key fields returned by the API:

Field Type Description
type string Always "session"
id string Unique session ID
title string Human-readable title
status string idle, running, rescheduling, terminated
created_at string ISO 8601 timestamp
updated_at string ISO 8601 timestamp
archived_at string ISO 8601 timestamp (nullable)
environment_id string Environment ID
agent object Agent configuration
resources array Attached files, repos, and memory stores
metadata object User-provided key-value pairs (max 8 keys)
usage object Token usage statistics

Creating a session

A session is meaningless without an agent. Sessions reference a pre-created agent by ID. Create the agent first via agents.create(), then reference it:

// 1. Create the agent (reusable, versioned)
const agent = await client.beta.agents.create(
  {
    name: "Coding Assistant",
    model: "claude-opus-4-8",
    system: "You are a helpful coding agent.",
    tools: [{ type: "agent_toolset_20260401"}],
  },
);

// 2. Start a session that references it
const session = await client.beta.sessions.create(
  {
    agent: agent.id,  // string shorthand → latest version. Or: { type: "agent", id: agent.id, version: agent.version }
    environment_id: environmentId,
    title: "Hello World Session",
  },
);

💡 Watch it live in Console. While developing, print a link so you can click through to the session UI instead of parsing the event stream: https://platform.claude.com/workspaces/default/sessions/{session.id}. The default workspace segment auto-resolves to the session's actual workspace on load, so you don't need to know the workspace id. Include this print/console.log in code you generate for users who are iterating locally.

Session creation parameters:

Field Type Required Description
agent string or object Yes Three forms: string shorthand "agent_abc123" (latest version); pinned {type: "agent", id, version}; or {type: "agent_with_overrides", id, version?, ...} to override model/system/tools/mcp_servers/skills for this session only — see § Override agent configuration for a session
environment_id string Yes Environment ID
title string No Human-readable name (appears in logs/dashboards)
resources array No Files, GitHub repos, or memory stores, attached to the container at startup. Memory stores are session-create-only (not addable via resources.add()).
vault_ids array No Vault IDs (vlt_*) — MCP credentials with auto-refresh + environment_variable secrets substituted at egress. See shared/managed-agents-tools.md → Vaults.
metadata object No User-provided key-value pairs

Agent configuration fields (passed to agents.create(), not sessions.create()):

Field Type Required Description
name string Yes Human-readable name (1-256 chars)
model string or object Yes Claude model ID (bare string, or {id, speed} object). All Claude 4.5+ models supported.
system string No System prompt — defines the agent's behavior (up to 100K chars)
tools array No Encompasses three kinds: (1) pre-built Claude Agent tools (agent_toolset_20260401), (2) MCP tools (mcp_toolset), and (3) custom client-side tools. Max 128.
mcp_servers array No MCP server connections — standardized third-party capabilities (e.g. GitHub, Asana). Max 20, unique names. See shared/managed-agents-tools.md → MCP Servers.
skills array No Customized "best-practices" context with progressive disclosure. Max 20. See shared/managed-agents-tools.md → Skills.
description string No Description of the agent (up to 2048 chars)
multiagent object No {type: "coordinator", agents: [...]} — roster this agent may delegate to. See shared/managed-agents-multiagent.md.
metadata object No Arbitrary key-value pairs (max 16, keys ≤64 chars, values ≤512 chars)

Agents

This is where every Managed Agents flow begins. The agent object is a persisted, versioned configuration — you create it once, then reference it by ID every time you start a session. No agent → no session.

Agent Object

The API is flat — model, system, tools etc. are top-level fields, not wrapped in an agent:{} sub-object.

Field Type Required Description
name string Yes Human-readable name
model string Yes Claude model ID
system string No System prompt
tools array No Agent toolset / MCP toolset / custom tools
mcp_servers array No MCP server connections
skills array No Skill references (max 20)
description string No Description of the agent
multiagent object No Coordinator roster — see shared/managed-agents-multiagent.md
metadata object No Arbitrary key-value pairs

Lifecycle: create once, run many, update in place

The agent is a persistent resource, not a per-run parameter. The intended pattern:

┌─ setup (once) ─────────┐     ┌─ runtime (every invocation) ─┐
│ agents.create()        │     │ sessions.create(             │
│   → store agent_id     │ ──→ │   agent={type:..., id: ID}   │
│     in config/env/db   │     │ )                            │
└────────────────────────┘     └──────────────────────────────┘

Anti-pattern: calling agents.create() at the top of every script run. This accumulates orphaned agent objects, pays create latency on every invocation, and defeats the versioning model. If you see agents.create() in a function that's called per-request or per-cron-tick, that's wrong — hoist it to one-time setup and persist the ID.

Recommended — define agents and environments as YAML + apply via the ant CLI. The split is CLI for the control plane, SDK for the data plane: agents and environments are relatively static resources you manage with ant (version-controlled YAML, applied from CI); sessions are dynamic and driven by your application through the SDK. See shared/anthropic-cli.md → Version-controlled Managed Agents resources for the ant beta:agents create < agent.yaml / update --version N flow. The SDK agents.create() call shown elsewhere in this doc is the in-code equivalent — use it when you need to provision programmatically, but prefer the YAML flow for anything a human maintains.

Versioning

Each POST /v1/agents/{id} (update) creates a new immutable version (numeric timestamp, e.g. 1772585501101368014). The agent's history is append-only — you can't edit a past version.

Why version: - Reproducibility — pin a session to a known-good config: {type: "agent", id, version: 3} - Safe iteration — update the agent without breaking sessions already running on the old version - Rollback — if a new system prompt regresses, pin new sessions back to the prior version while you debug

version is optional. Omit it (or use the string shorthand agent="agent_abc123") to get the latest version at session-creation time. Pass it explicitly ({type: "agent", id, version: N}) to pin for reproducibility.

Getting the version to pin: agents.create() and agents.update() both return version in the response. Store it alongside agent_id. To fetch the current latest for an existing agent: GET /v1/agents/{id} → .version.

When to update vs create new: Update (POST /v1/agents/{id}) when it's conceptually the same agent with tweaked behavior (better prompt, extra tool). Create a new agent when it's a different persona/purpose. Rule of thumb: if you'd give it the same name, update.

Agent Endpoints

Operation Method Path
Create POST /v1/agents
List GET /v1/agents
Get GET /v1/agents/{id}
Update POST /v1/agents/{id}
Archive POST /v1/agents/{id}/archive

⚠️ Archive is permanent. Archiving makes the agent read-only: existing sessions continue to run, but new sessions cannot reference it, and there is no unarchive. Since agents have no delete, this is the terminal lifecycle state. Never archive a production agent as routine cleanup — confirm with the user first.

Using an Agent in a Session

Reference the agent by string ID (latest version) or by object with an explicit version:

# String shorthand — uses the agent's latest version
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment_id,
)

# Or pin to a specific version (int)
session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": agent.version},
    environment_id=environment_id,
)

Override agent configuration for a session

The third agent form, agent_with_overrides, replaces parts of the agent's configuration for a single session — try a different model or grant an extra tool without versioning the agent. Pass id (and optionally version; omitted = latest, same default as the other two forms) plus any of model, system, tools, mcp_servers, skills:

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
        "system": None,           # clear the system prompt for this session
    },
    environment_id=environment_id,
)

Each overridable field follows tri-state rules: - Omit → the session inherits the value from the referenced agent version. - null (or [] for list fields) → the session runs with that field cleared. Applies in full to system, mcp_servers, skills. Two exceptions: model is never clearable (model: null → 400 agent_model_required); clearing tools returns 400 when the session's effective skills is non-empty (skills require the read tool), otherwise tools: null / tools: [] clears. - A value → replaces the agent's value in full. Overrides never merge — a tools override must list every tool the session should have.

Overrides are session-local: they do not modify the agent resource or create a new agent version. The response's agent object reflects the post-override configuration, while its id and version still identify the base agent — so you can trace a session back to its base. In multiagent sessions, overrides apply to the coordinator and its {type: "self"} copies; roster agents referenced by ID always use their own as-created configuration (see shared/managed-agents-multiagent.md).

Updating the agent configuration mid-session

sessions.update() can change agent.tools, agent.mcp_servers (including permission policies), and vault_ids on an existing session. This is a session-local override — it does not create a new agent version and does not propagate back to the agent object. The provided arrays are full replacements; to append one tool, GET the session, modify, and POST back. The session must be idle — interrupt first if running.

Only tools and mcp_servers can change after a session is created — to run with a model, system, or skills other than the agent's values, use agent_with_overrides at create time (above). The agent's configured system field is fixed for the session's lifetime; you can still replace the effective system prompt between turns by sending a system.message event (see shared/managed-agents-events.md § Updating the system prompt mid-session).

client.beta.sessions.update(
    session.id,
    agent={
        "tools": [
            {"type": "agent_toolset_20260401"},
            {"type": "mcp_toolset", "mcp_server_name": "linear"},
        ],
        "mcp_servers": [{"type": "url", "name": "linear", "url": "https://mcp.linear.app/sse"}],
    },
    vault_ids=["vlt_..."],
)

Managed Agents — Environments & Resources

Environments

Creating a session requires an environment_id. Environments are reusable configuration templates for spinning up containers in Anthropic's infrastructure — you might create different environments for different use cases (e.g. data visualization vs web development, with different package sets). Anthropic handles scaling, container lifecycle, and work orchestration.

Environment names must be unique. Creating an environment with an existing name returns 409.

Networking

Network Policy Description
unrestricted Full egress (except legal blocklist)
limited Deny-by-default; opt in via allowed_hosts / allow_package_managers / allow_mcp_servers 
{
  "networking": {
    "type": "limited",
    "allow_package_managers": true,
    "allow_mcp_servers": true,
    "allowed_hosts": ["api.example.com"]
  }
}

All three limited fields are optional. allow_package_managers (default false) permits PyPI/npm/etc.; allow_mcp_servers (default false) permits the agent's configured MCP server endpoints without listing them in allowed_hosts.

MCP caveat: Under limited networking, either set allow_mcp_servers: true or add each MCP server domain to allowed_hosts. Otherwise the container can't reach them and tools silently fail.

Creating an environment

The SDK adds managed-agents-2026-04-01 automatically. TypeScript:

const env = await client.beta.environments.create({
  name: "my_env",
  config: {
    type: "cloud",
    networking: { type: "unrestricted" },
  },
});

Self-hosted sandboxes

To run tool execution in your own infrastructure instead of Anthropic's, set config: {type: "self_hosted"} — the agent loop stays on Anthropic's side, but bash / file ops / code execute in a container you control via an outbound-polling worker. The networking block does not apply (you control egress). Resource mounting (file, github_repository) and memory stores behave differently — see shared/managed-agents-self-hosted-sandboxes.md for the worker, credentials, and cloud-vs-self-hosted comparison.

Environment CRUD

Operation Method Path Notes
Create POST /v1/environments
List GET /v1/environments Paginated (limit, after_id, before_id)
Get GET /v1/environments/{id}
Update POST /v1/environments/{id} Changes apply only to new containers; existing sessions keep their original config
Delete DELETE /v1/environments/{id} Returns 204.
Archive POST /v1/environments/{id}/archive Makes it read-only; existing sessions continue, new sessions cannot reference it. No unarchive — terminal state.

Resources

Attach files, GitHub repositories, and memory stores to a session. Session creation blocks until all resources are mounted — the container won't go running until every file and repo is in place. Max 999 file resources per session. Multiple GitHub repositories per session are supported. For type: "memory_store" resources (persistent cross-session memory — max 8 per session), see shared/managed-agents-memory.md.

File Uploads (input — host → agent)

Upload a file first via the Files API, then reference by file_id + mount_path:

// 1. Upload
const file = await client.beta.files.upload({
  file: fs.createReadStream("data.csv"),
  purpose: "agent",
});

// 2. Attach as a session resource
const session = await client.beta.sessions.create({
  agent: agent.id,
  environment_id: envId,
  resources: [
    { type: "file", file_id: file.id, mount_path: "/workspace/data.csv" }
  ],
});

mount_path is required and must be absolute. Parent directories are created automatically. Agent working directory defaults to /workspace. Files are mounted read-only — the agent writes modified versions to new paths.

Session outputs (output — agent → host)

The agent can write files to /mnt/session/outputs/ during a session. These are automatically captured by the Files API and can be listed and downloaded afterwards:

// After the turn completes, list output files scoped to this session:
for await (const f of client.beta.files.list({
  scope_id: session.id,
  betas: ["managed-agents-2026-04-01"],
})) {
  console.log(f.filename, f.size_bytes);
  const resp = await client.beta.files.download(f.id);
  const text = await resp.text();
}

Requirements: - The write tool (or bash) must be enabled for the agent to create output files. - Session-scoped files.list / files.download captures outputs written to /mnt/session/outputs/. - The filter parameter is scope_id (REST query param ?scope_id=<session_id>). The SDK's files resource auto-adds only the files-api-2025-04-14 header, so pass betas: ["managed-agents-2026-04-01"] explicitly (or both headers on raw HTTP) — without it the API may reject scope_id as an unknown field. Requires @anthropic-ai/sdk ≥ 0.88.0 / anthropic (Python) ≥ 0.92.0 — older versions don't type scope_id. The ant CLI does not expose this flag yet; use the SDK or curl. - Pass the session ID returned by sessions.create() verbatim (e.g. sesn_011CZx...) — the API validates the prefix. - There's a brief indexing lag (~1–3s) between session.status_idle and output files appearing in files.list. Retry once or twice if empty.

Fallback when scope_id filtering is unavailable (older SDK, or endpoint returns an error): send a follow-up user.message asking the agent to read each file under /mnt/session/outputs/ and return the contents. The agent streams the file bodies back as agent.message text. This works for text files only and costs output tokens — use it to unblock, not as the primary path.

This gives you a bidirectional file bridge: upload reference data in, download agent artifacts out.

GitHub Repositories

Clones a GitHub repository into the session container during initialization, before the agent begins execution. The agent can read, edit, commit, and push via bash (git). Multiple repositories per session are supported — add one resources entry per repo. Repositories are cached, so future sessions that use the same repository start faster.

Repositories are attached for the lifetime of the session — to change which repositories are mounted, create a new session. You can rotate a repository's authorization_token on a running session via client.beta.sessions.resources.update(resource_id, {session_id, authorization_token}); the resource id is returned at session creation and by resources.list().

Fields:

Field Required Notes
type ✅ "github_repository"
url ✅ The GitHub repository URL
authorization_token ✅ GitHub Personal Access Token with repository access. Never echoed in API responses.
mount_path ❌ Path where the repository will be cloned. Defaults to /workspace/<repo-name>.
checkout ❌ {type: "branch", name: "..."} or {type: "commit", sha: "..."}. Defaults to the repo's default branch.

Token permission levels (fine-grained PATs): - Contents: Read — clone only - Contents: Read and write — push changes and create pull requests

How auth works: authorization_token is never placed inside the container. git pull / git push and GitHub REST calls against the attached repository are routed through an Anthropic-side git proxy that injects the token after the request leaves the sandbox. Code running in the container — including anything the agent writes — cannot read or exfiltrate it.

‼️ To generate pull requests you also need GitHub MCP server access — the github_repository resource gives filesystem + git access only. See shared/managed-agents-tools.md → MCP Servers. The PR workflow is: edit files in the mounted repo → push branch via bash (authenticated via the git proxy using authorization_token) → create PR via the MCP create_pull_request tool (authenticated via the vault).

TypeScript:

// 1. Create the agent — declare GitHub MCP (no auth here)
const agent = await client.beta.agents.create(
  {
    name: 'GitHub Agent',
    model: 'claude-opus-4-8',
    mcp_servers: [
      { type: 'url', name: 'github', url: 'https://api.githubcopilot.com/mcp/' },
    ],
    tools: [
      { type: 'agent_toolset_20260401', default_config: { enabled: true } },
      { type: 'mcp_toolset', mcp_server_name: 'github' },
    ],
  },
);

// 2. Start a session — attach vault for MCP auth + mount the repo
const session = await client.beta.sessions.create({
  agent: agent.id,
  environment_id: envId,
  vault_ids: [vaultId],  // vault contains the GitHub MCP OAuth credential
  resources: [
    {
      type: 'github_repository',
      url: 'https://github.com/owner/repo',
      authorization_token: process.env.GITHUB_TOKEN,  // repo clone token (≠ MCP auth)
      checkout: { type: 'branch', name: 'main' },
    },
  ],
});

Python:

import os

agent = client.beta.agents.create(
    name="GitHub Agent",
    model="claude-opus-4-8",
    mcp_servers=[{
        "type": "url",
        "name": "github",
        "url": "https://api.githubcopilot.com/mcp/",
    }],
    tools=[
        {"type": "agent_toolset_20260401", "default_config": {"enabled": True}},
        {"type": "mcp_toolset", "mcp_server_name": "github"},
    ],
)

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=env_id,
    vault_ids=[vault_id],  # vault contains the GitHub MCP OAuth credential
    resources=[{
        "type": "github_repository",
        "url": "https://github.com/owner/repo",
        "authorization_token": os.environ["GITHUB_TOKEN"],  # repo clone token (≠ MCP auth)
        "checkout": {"type": "branch", "name": "main"},
    }],
)

Files API

Upload and manage files for use as session resources, and download files the agent wrote to /mnt/session/outputs/.

Operation Method Path SDK
Upload POST /v1/files client.beta.files.upload({ file })
List GET /v1/files?scope_id=... client.beta.files.list({ scope_id, betas: ["managed-agents-2026-04-01"] })
Get Metadata GET /v1/files/{id} client.beta.files.retrieveMetadata(id)
Download GET /v1/files/{id}/content client.beta.files.download(id) → Response
Delete DELETE /v1/files/{id} client.beta.files.delete(id)

The scope_id filter on List scopes the results to files written to /mnt/session/outputs/ by that session. Without the filter, you get all files uploaded to your account.

Managed Agents — Events & Steering

Events

Sending Events

Send events to a session via POST /v1/sessions/{id}/events.

Event Type When to Send
user.message Send a user message
user.interrupt Interrupt the agent while it's running
user.tool_confirmation Approve/deny a tool call (when always_ask policy)
user.custom_tool_result Provide result for a custom tool call
user.define_outcome Start a rubric-graded iterate loop — see shared/managed-agents-outcomes.md
system.message Update the agent's system prompt between turns — Claude Opus 4.8 only; see § Updating the system prompt mid-session

Updating the system prompt mid-session (system.message)

Unlike the system field on the agent definition (fixed at session creation), a system.message event changes the system prompt as the session progresses — a different persona, revised constraints, or runtime-fetched context that should shape behavior going forward:

client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "system.message",
            "content": [
                {"type": "text", "text": "The user's current timezone is America/New_York."},
            ],
        },
    ],
)

Constraints:

  • Claude Opus 4.8 only. If any model configured on the agent does not support mid-conversation system injection, the event is rejected with a model_does_not_support_mid_conversation_system validation error.
  • Cannot be sent while the session is idle with stop_reason: requires_action (blocked on user.custom_tool_result / user.tool_confirmation).
  • content accepts 1–1000 text items.

Receiving Events

Three methods:

  1. Streaming (SSE): GET /v1/sessions/{id}/events/stream — real-time Server-Sent Events. Long-lived — the server sends periodic heartbeats to keep the connection alive.
  2. Polling: GET /v1/sessions/{id}/events — paginated event list (query params: limit default 1000, page). Returns immediately — this is a plain paginated GET, not a long-poll.
  3. Webhooks: Anthropic POSTs session state transitions to your HTTPS endpoint — thin payloads (IDs only), HMAC-signed, Console-registered. See shared/managed-agents-webhooks.md.

All persisted events carry id, type, and processed_at (ISO 8601; null if not yet processed by the agent). The stream-only event_start / event_delta preview events (see § Live previews) carry only the id of the event they preview.

⚠️ 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.

Event Types (Received)

Event types use dot notation, grouped by namespace:

Event Type Description
agent.message Agent text output
agent.thinking Extended thinking blocks
agent.tool_use Agent used a built-in tool (agent_toolset_20260401)
agent.tool_result Result from a built-in tool
agent.mcp_tool_use Agent used an MCP tool
agent.mcp_tool_result Result from an MCP tool
agent.custom_tool_use Agent invoked a custom tool — session goes idle, you respond with user.custom_tool_result
agent.thread_context_compacted Conversation context was compacted
session.status_idle Agent has finished the current task, and is awaiting input. It's either waiting for input to continue working via a user.message or blocked awaiting a user.custom_tool_result or user.tool_confirmation. The stop_reason attached contains more information about why the Agent has stopped working.
session.status_running Session has starting running, and the Agent is actively doing work.
session.status_rescheduled Session is (re)scheduling after a retryable error has occurred, ready to be picked up by the orchestration system.
session.status_terminated Session has terminated, entering an irreversible and unusable state.
session.error Error occurred during processing
span.model_request_start Model inference started
span.model_request_end Model inference completed
span.outcome_evaluation_start / _ongoing / _end Grader progress for outcome-oriented sessions — see shared/managed-agents-outcomes.md
session.thread_created Subagent thread spawned (multiagent) — see shared/managed-agents-multiagent.md
session.thread_status_running / _idle / _rescheduled / _terminated Subagent thread status transitions (multiagent). _idle carries stop_reason.
agent.thread_message_sent / _received Cross-thread message, carries to_session_thread_id / from_session_thread_id (multiagent)

The stream also echoes back user-sent events (user.message, user.interrupt, user.tool_confirmation, user.custom_tool_result, user.define_outcome).

Stream-only delta preview events (event_start, event_delta) are the one exception to the {domain}.{action} naming convention — see § Live previews below; they never appear in GET /v1/sessions/{id}/events.

Live previews

By default, assistant text reaches the stream as buffered agent.message events — emitted only after the model request that produced them finishes. Live previews let you render that text incrementally while the model is still generating. The buffered agent.message is always the authoritative record; a client that ignores previews still receives a complete, correct stream. The wire format is not Messages-API streaming: the delta type is content_delta, not content_block_delta, so Messages-API accumulator code does not carry over unchanged.

Opt in per stream connection by adding the event_deltas[] query parameter to GET /v1/sessions/{id}/events/stream, repeated once per event type to preview. Accepted values: agent.message, agent.thinking (any other value → 400). Only the session-level stream supports it — per-thread streams (/threads/{tid}/stream) reject the parameter.

stream = client.beta.sessions.events.stream(
    session_id=session.id,
    event_deltas=["agent.message"],
)

When a previewed event begins, the stream emits an event_start carrying the upcoming event's type and id; for agent.message it's followed by event_delta events carrying incremental text:

{"type": "event_start", "event": {"type": "agent.message", "id": "sevt_01abc..."}}
{"type": "event_delta", "event_id": "sevt_01abc...", "delta": {"type": "content_delta", "index": 0, "content": {"type": "text", "text": "Here is the summary"}}}

event_start and event_delta have no id or processed_at of their own — the only identifier they carry is the id of the event they preview. For agent.thinking, only the event_start is emitted (a "thinking has started" signal) — no deltas follow; read content from the buffered agent.thinking event.

Accumulate-and-reconcile pattern. Treat the preview as a scratch buffer keyed by (event_id, index). On event_start, create an empty entry for the announced id. On each event_delta, append delta.content.text to (event_id, delta.index) and render the running text. When the buffered agent.message arrives, match it by id, discard the accumulated preview, and render the message's content instead. The identifiers always line up: event_start.event.id, every event_delta.event_id, and the buffered event's id are the same value. On a normal turn the order is fixed: session.status_running → span.model_request_start → event_start → event_delta* → buffered agent.message → span.model_request_end. If the turn errors or is interrupted the buffered event may never arrive, but span.model_request_end still does — close any unreconciled preview when you see it. Python/TypeScript/Go SDKs ship an accumulator helper that implements this; in other SDKs apply the manual pattern to the generated event types.

Limitations: - Best effort — under load the server may shed deltas for an event; you receive a contiguous prefix and then no further deltas for that event. The buffered agent.message still arrives complete. Never treat an accumulated preview as final. - No replay on reconnect — deltas are delivered only to the connection that opted in, while it's open. After a drop, follow the consolidation pattern in § Reconnecting after a dropped stream — the history fetch returns any buffered events emitted during the gap; missed deltas cannot be re-requested. - Primary thread, text only — tool use, tool results, MCP results, and subagent-thread activity are never previewed. - Never persisted — event_start / event_delta exist only on the live SSE stream, never in GET /v1/sessions/{id}/events.

Steering Patterns

Practical patterns for driving a session via the events surface.

Stream-first ordering

Open the stream before sending events. The stream only delivers events that occur after it's opened — it does not replay current state or historical events. If you send a message first and open the stream second, early events (including fast status transitions) arrive buffered in a single batch and you lose the ability to react to them in real time.

// ✅ Correct — stream and send concurrently
const [response] = await Promise.all([
  streamEvents(sessionId),   // opens SSE connection
  sendMessage(sessionId, text),
]);

// ❌ Wrong — events before stream opens arrive as a single buffered batch
await sendMessage(sessionId, text);
const response = await streamEvents(sessionId);

For full history, use GET /v1/sessions/{id}/events (paginated list) — the stream only gives you live events from connection onward.

Reconnecting after a dropped stream

The SSE stream has no replay. If your connection drops (httpx read timeout, network blip) and you reconnect, you only get events emitted after reconnection. Any events emitted during the gap are lost from the stream.

The consolidation pattern: on every (re)connect, overlap the stream with a history fetch and dedupe by event ID:

def connect_with_consolidation(client, session_id):
    # 1. Open the SSE stream first
    stream = client.beta.sessions.events.stream(session_id=session_id)

    # 2. Fetch history to cover any gap
    history = client.beta.sessions.events.list(
        session_id=session_id,
    )

    # 3. Yield history first, then stream — dedupe by event.id
    seen = set()
    for ev in history.data:
        seen.add(ev.id)
        yield ev
    for ev in stream:
        if ev.id not in seen:
            seen.add(ev.id)
            yield ev

Message queuing

You don't have to wait for a response before sending the next message. User events are queued server-side and processed in order. This is useful for chat bridges where the user sends rapid follow-ups:

// All three go into one session; agent processes them in order
await sendMessage(sessionId, "Summarize the README");
await sendMessage(sessionId, "Actually also check the CONTRIBUTING guide");
await sendMessage(sessionId, "And compare the two");
// Stream once — agent responds to all three as a coherent turn

Events can be sent up to the Session at any time. There is no need to wait on a specific session status to enqueue new events via client.beta.sessions.events.send()

Interrupt

An interrupt event jumps the queue (ahead of any pending user messages) and forces the session into idle. Use this for "stop" / "nevermind" / "cancel" commands:

await client.beta.sessions.events.send(sessionId, {
  events: [{ type: 'interrupt' }],
});

The agent stops mid-task. It does not see the interrupt as a message — it just halts. Send a follow-up user event to explain what to do instead. If an outcome is active, the interrupt also marks span.outcome_evaluation_end.result: "interrupted" (see shared/managed-agents-outcomes.md).

Note: Interrupt events may have empty IDs in the current implementation. When troubleshooting, use the processed_at timestamp along with surrounding event IDs.

Event payloads

some events carry useful metadata beyond the status change itself:

session.status_idle — includes a stop_reason field which elaborates on why the session stopped and what type of further action is required by the user.

{
  "id": "sevt_456",
  "processed_at": "2026-04-07T04:27:43.197Z",
  "stop_reason": {
    "event_ids": [
      "sevt_123"
    ],
    "type": "requires_action"
  },
  "type": "status_idle"
}

span.model_request_end contains a model_usage field for cost tracking and efficiency analysis:

{
  "type": "span.model_request_end",
  "id": "sevt_456",
  "is_error": false,
  "model_request_start_id": "sevt_123",
  "model_usage": {
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 6656,
    "input_tokens": 3571,
    "output_tokens": 727
  },
  "processed_at": "2026-04-07T04:11:32.189Z"
}

agent.thread_context_compacted — emitted when the conversation history was summarized to fit context. Includes pre_compaction_tokens so you know how much was squeezed:

{
  "id": "sevt_abc123",
  "processed_at": "2026-03-24T14:05:15.787Z",
  "type": "agent.thread_context_compacted"
}

Archive

When done with a session, archive it to free resources:

await client.beta.sessions.archive(sessionId);

Archiving a session is routine cleanup — sessions are per-run and disposable. Do not generalize this to agents or environments: those are persistent, reusable resources, and archiving them is permanent (no unarchive; new sessions cannot reference them). See shared/managed-agents-overview.md → Common Pitfalls.

Managed Agents — Memory Stores

Public beta. Memory stores ship under the managed-agents-2026-04-01 beta header; the SDK sets it automatically on all client.beta.memory_stores.* calls. If client.beta.memory_stores is missing, upgrade to the latest SDK release.

Sessions are ephemeral by default — when one ends, anything the agent learned is gone. A memory store is a workspace-scoped collection of small text documents that persists across sessions. When a store is attached to a session (via resources[]), it is mounted into the container as a filesystem directory; the agent reads and writes it with the ordinary file tools, and a system-prompt note tells it the mount is there.

Every mutation to a memory produces an immutable memory version (memver_...), giving you an audit trail and point-in-time rollback/redact.

Object model

Object ID prefix Scope Notes
Memory store memstore_... Workspace Attach to sessions via resources[]
Memory mem_... Store One text file, addressed by path (≤ 100KB each — prefer many small files)
Memory version memver_... Memory Immutable snapshot per mutation; operation ∈ created / modified / deleted

Create a store

description is passed to the agent so it knows what the store contains — write it for the model, not for humans.

store = client.beta.memory_stores.create(
    name="User Preferences",
    description="Per-user preferences and project context.",
)
print(store.id)  # memstore_01Hx...

Other SDKs: TypeScript client.beta.memoryStores.create({...}); Go client.Beta.MemoryStores.New(ctx, ...). See shared/managed-agents-api-reference.md → SDK Method Reference for the full per-language table.

Stores support retrieve / update / list (with include_archived, created_at_{gte,lte} filters) / delete / archive. Archive makes the store read-only — existing session attachments continue, new sessions cannot reference it; no unarchive.

Seed with content (optional)

Pre-load reference material before any session runs. memories.create creates a memory at the given path; if a memory already exists there the call returns 409 (memory_path_conflict_error, with the conflicting_memory_id). The store ID is the first positional argument.

client.beta.memory_stores.memories.create(
    store.id,
    path="/formatting_standards.md",
    content="All reports use GAAP formatting. Dates are ISO-8601...",
)

Attach to a session

Memory stores go in the session's resources[] array alongside file and github_repository resources (see shared/managed-agents-environments.md → Resources). Memory stores attach at session create time only — sessions.resources.add() does not accept memory_store.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "memory_store",
            "memory_store_id": store.id,
            "access": "read_write",  # or "read_only"; default is "read_write"
            "instructions": "User preferences and project context. Check before starting any task.",
        }
    ],
)
Field Required Notes
type ✅ "memory_store"
memory_store_id ✅ memstore_...
access — "read_write" (default) or "read_only" — enforced at the filesystem level on the mount
instructions — Session-specific guidance for this store, in addition to the store's name/description. ≤ 4,096 chars.

Max 8 memory stores per session. Attach multiple when different slices of memory have different owners or lifecycles — e.g. one read-only shared-reference store plus one read-write per-user store, or one store per end-user/team/project sharing a single agent config.

How the agent sees it (FUSE mount)

Each attached store is mounted in the session container at /mnt/memory/<store-name>/. The agent interacts with it using the standard file tools (bash, read, write, edit, glob, grep) — there are no dedicated memory tools. access: "read_only" makes the mount read-only at the filesystem level; "read_write" allows the agent to create, edit, and delete files under it. A short description of each mount (name, path, instructions, access) is automatically injected into the system prompt so the agent knows the store exists without you having to mention it.

Writes the agent makes under the mount are persisted back to the store and produce memory versions just like host-side memories.update calls.

Manage memories directly (host-side)

Use these for review workflows, correcting bad memories, or seeding stores out-of-band.

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.

for m in client.beta.memory_stores.memories.list(store.id, path_prefix="/"):
    if m.type == "memory":
        print(f"{m.path}  ({m.content_size_bytes} bytes, sha={m.content_sha256[:8]})")
    else:  # "memory_prefix"
        print(f"{m.path}/")

Read

mem = client.beta.memory_stores.memories.retrieve(memory_id, memory_store_id=store.id)
print(mem.content)

retrieve defaults to view="full" (content included); view matters mainly on list endpoints.

Create vs. update

Operation Addressed by Semantics
memories.create(store_id, path=..., content=...) Path Create at path. 409 (memory_path_conflict_error, includes conflicting_memory_id) if the path is already occupied.
memories.update(mem_id, memory_store_id=..., path=..., content=...) mem_... ID Mutate existing memory. Change content, path (rename), or both. Renaming onto an occupied path returns the same 409 memory_path_conflict_error. 
mem = client.beta.memory_stores.memories.create(
    store.id,
    path="/preferences/formatting.md",
    content="Always use tabs, not spaces.",
)

client.beta.memory_stores.memories.update(
    mem.id,
    memory_store_id=store.id,
    path="/archive/2026_q1_formatting.md",  # rename
)

Optimistic concurrency (precondition on update)

memories.update accepts a precondition so you can read → modify → write back without clobbering a concurrent writer. The only supported type is content_sha256. On mismatch the API returns 409 (memory_precondition_failed_error) — re-read and retry against fresh state.

client.beta.memory_stores.memories.update(
    mem.id,
    memory_store_id=store.id,
    content="CORRECTED: Always use 2-space indentation.",
    precondition={"type": "content_sha256", "content_sha256": mem.content_sha256},
)

Delete

client.beta.memory_stores.memories.delete(mem.id, memory_store_id=store.id)

Pass expected_content_sha256 for a conditional delete.

Audit and rollback — memory versions

Every mutation creates an immutable memver_... snapshot. Versions accumulate for the lifetime of the parent memory; memories.retrieve always returns the current head, the version endpoints give you history.

Operation that triggers it operation field on the version
memories.create at a new path "created"
memories.update changing content, path, or both (or an agent-side write to the mount) "modified"
memories.delete "deleted"

Each version also records created_by — an actor object with type ∈ session_actor / api_actor / user_actor — and, after redaction, redacted_at + redacted_by.

List versions

Newest-first, paginated. Filter by memory_id, operation, session_id, api_key_id, or created_at_gte / created_at_lte. Pass view="full" to include content; default is metadata-only.

for v in client.beta.memory_stores.memory_versions.list(store.id, memory_id=mem.id):
    print(f"{v.id}: {v.operation}")

Retrieve a version

version = client.beta.memory_stores.memory_versions.retrieve(
    version_id, memory_store_id=store.id
)
print(version.content)

Redact a version

Scrubs content from a historical version while preserving the audit trail (actor + timestamps). Clears content, content_sha256, content_size_bytes, and path; everything else stays. Use for leaked secrets, PII, or user-deletion requests.

client.beta.memory_stores.memory_versions.redact(version_id, memory_store_id=store.id)

Endpoint reference

See shared/managed-agents-api-reference.md → Memory Stores / Memories / Memory Versions for the full HTTP method/path tables. Raw HTTP base path:

POST   /v1/memory_stores
POST   /v1/memory_stores/{memory_store_id}/archive
GET    /v1/memory_stores/{memory_store_id}/memories
PATCH  /v1/memory_stores/{memory_store_id}/memories/{memory_id}
GET    /v1/memory_stores/{memory_store_id}/memory_versions
POST   /v1/memory_stores/{memory_store_id}/memory_versions/{version_id}/redact

For cURL examples and the CLI (ant beta:memory-stores ...), WebFetch the Memory URL in shared/live-sources.md → Managed Agents.

Managed Agents — Multiagent Sessions

A coordinator agent can delegate to other agents within one session. All agents share the container and filesystem; each runs in its own thread — a context-isolated event stream with its own conversation history, model, system prompt, tools, MCP servers, and skills (from that agent's own config). Threads are persistent: the coordinator can send a follow-up to a subagent it called earlier and that subagent retains its prior turns.

The SDK sets the managed-agents-2026-04-01 beta header automatically on all client.beta.{agents,sessions}.* calls; no additional header is required for multiagent.

Declare the roster on the coordinator

multiagent is a top-level field on agents.create() / agents.update() — not a tools[] entry. agents lists 1–20 roster entries. Nothing changes on sessions.create() — the roster is resolved from the coordinator's config.

orchestrator = client.beta.agents.create(
    name="Engineering Lead",
    model="claude-opus-4-8",
    system="You coordinate engineering work. Delegate code review to the reviewer and test writing to the test agent.",
    tools=[{"type": "agent_toolset_20260401"}],
    multiagent={
        "type": "coordinator",
        "agents": [
            reviewer.id,                                            # bare string — latest version
            {"type": "agent", "id": test_writer.id, "version": 4},  # pinned version
            {"type": "self"},                                       # the coordinator itself
        ],
    },
)

session = client.beta.sessions.create(agent=orchestrator.id, environment_id=env.id)
Roster entry Shape Notes
String shorthand "agent_abc123" References the latest version of a stored agent.
Agent reference {type: "agent", id, version?} Omit version to pin the latest at coordinator save time.
Self {type: "self"} The coordinator can spawn copies of itself.

If the session was created with agent_with_overrides (see shared/managed-agents-core.md → Override agent configuration for a session), those overrides apply to the coordinator and its self copies. Roster agents referenced by ID always use their own as-created configuration — overrides do not propagate to them.

Up to 20 unique agents in the roster; the coordinator may spawn multiple copies of each. One level of delegation only — depth > 1 is ignored.

Threads

The session-level event stream is the primary thread — it shows the coordinator's trace plus a condensed view of subagent activity (thread status transitions and cross-thread messages, not every subagent tool call). Drill into a specific subagent via the per-thread endpoints:

Operation HTTP SDK (client.beta.sessions.threads.*)
List threads GET /v1/sessions/{sid}/threads .list(session_id)
Retrieve one GET /v1/sessions/{sid}/threads/{tid} .retrieve(thread_id, session_id=...)
Archive POST /v1/sessions/{sid}/threads/{tid}/archive .archive(thread_id, session_id=...)
List thread events GET /v1/sessions/{sid}/threads/{tid}/events .events.list(thread_id, session_id=...)
Stream thread events GET /v1/sessions/{sid}/threads/{tid}/stream .events.stream(thread_id, session_id=...)

Each SessionThread carries id, status (running | idle | rescheduling | terminated), agent (a resolved snapshot of the agent config — id, name, model, system, tools, skills, mcp_servers, version), parent_thread_id (null for the primary thread, which is included in the list), archived_at, and optional stats/usage. Session status aggregates thread statuses — if any thread is running, session.status is running. Max 25 concurrent threads. When draining a per-thread stream, break on session.thread_status_idle (and check its stop_reason as you would for the session-level idle).

Multiagent events (on the session stream)

Event Payload highlights Meaning
session.thread_created session_thread_id, agent_name A new thread was created.
session.thread_status_running session_thread_id, agent_name Thread started activity.
session.thread_status_idle session_thread_id, agent_name, stop_reason Thread is awaiting input. Inspect stop_reason (same shape as session.status_idle.stop_reason).
session.thread_status_rescheduled session_thread_id, agent_name Thread is rescheduling after a retryable error.
session.thread_status_terminated session_thread_id, agent_name Thread was archived or hit a terminal error.
agent.thread_message_sent to_session_thread_id, to_agent_name, content Coordinator sent a follow-up to another thread.
agent.thread_message_received from_session_thread_id, from_agent_name, content An agent delivered its result to the coordinator.

Tool permissions and custom tools from subagent threads

When a subagent needs your client (an always_ask confirmation, or a custom tool result), the request is cross-posted to the primary thread with session_thread_id identifying the originating thread — so you only need to watch the session stream. Reply with user.tool_confirmation (carrying tool_use_id) or user.custom_tool_result (carrying custom_tool_use_id), and echo the session_thread_id from the originating event (the SDK param type and docstring expect it). The server also routes by the tool-use ID, so the echo is belt-and-suspenders rather than load-bearing — but include it.

for event_id in stop.event_ids:
    pending = events_by_id[event_id]
    confirmation = {
        "type": "user.tool_confirmation",
        "tool_use_id": event_id,
        "result": "allow",
    }
    if pending.session_thread_id is not None:
        confirmation["session_thread_id"] = pending.session_thread_id
    client.beta.sessions.events.send(session.id, events=[confirmation])

The same pattern applies to user.custom_tool_result.

Pitfalls

  • Don't put the roster on sessions.create() or in tools[]. multiagent is a top-level agent field; update the coordinator, then start a session that references it.
  • Don't assume shared context. Threads share the filesystem but not conversation history or tools. If the coordinator needs a subagent to act on something, it must say so in the delegated message (or write it to disk).
  • Depth > 1 is ignored. A subagent's own multiagent roster (if any) doesn't cascade — only the session's coordinator delegates.

For per-language bindings beyond Python, WebFetch https://platform.claude.com/docs/en/managed-agents/multi-agent.md (see shared/live-sources.md).

Managed Agents — Onboarding Flow

Invoked via /claude-api managed-agents-onboard? You're in the right place. Run the interview below — don't summarize it back to the user, ask the questions.

Claude Managed Agents is a hosted agent: Anthropic runs the agent loop and provisions a sandboxed container per session where the agent's tools execute (or your own worker, with a self_hosted environment — see shared/managed-agents-self-hosted-sandboxes.md). You supply an agent config (tools, skills, model, system prompt — reusable, versioned) and an environment config (the sandbox — reusable across agents). Each run is a session.

The flow is four beats — describe → agent → environment → session — the same arc as the Console quickstart, and the same philosophy: value before credentials. The user goes from idea to a runnable session before any auth ask; each credential is flagged at the moment the design makes it relevant (§2) and collected once, at session setup (§4), where it binds (sessions.create()) and gets exercised (smoke-test). Read shared/managed-agents-core.md alongside this — it has full detail for each knob; this doc is the interview script.

1. Describe the task

Open with a one-breath signpost and a single open prompt — don't guess, don't questionnaire. In your own words:

Managed Agents is hosted — Anthropic runs the agent loop, the sandbox, and the infrastructure; you just define the agent. We'll do this in three moves: the agent, the environment it runs in, then a live test session. So: describe the agent you want — what should it do, and what kicks it off (a person, an event, a schedule)?

Let them answer in full before configuring anything.

2. Configure the agent — propose, don't interrogate

Their description does the interview's work. Draft the agent config from it and present it as a proposal with your suggestions inline — the user reacts to a concrete config instead of answering a question list. At most one batched follow-up for true gaps. Suggest where the description gives you an opening:

  • Tools — enable the full prebuilt toolset by default (agent_toolset_20260401: bash, read, write, edit, glob, grep, web_fetch, web_search). Suggest MCP servers for any third-party service the job names (GitHub, Linear, Slack, …) — and flag the credential each one implies as you suggest it ("Linear MCP → you'll need a Linear API token at kickoff"), so §4's auth step is a formality, not a surprise. Collection itself waits for §4. Custom tools only if the user's own app must answer calls (name, description, input schema — their handler code is theirs; don't generate it).
  • 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).

‼️ 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.

Full detail per knob: shared/managed-agents-tools.md (toolset, MCP, custom tools, skills), shared/managed-agents-environments.md (repos, files).

3. Environment

Usually zero or one question:

  • Reuse or create? Environments are shared across agents — check for an existing one first.
  • Networking — default unrestricted egress. Switch to limited only if the user wants egress control — then set allow_mcp_servers: true or list every MCP server domain in allowed_hosts, or those tools fail silently.
  • Suggest self_hosted when the signals are there: tools must run on their own infra, secrets can't leave it, or they need binaries/data the cloud container won't have (shared/managed-agents-self-hosted-sandboxes.md; not available on Claude Platform on AWS). Otherwise cloud — don't raise it unprompted for simple jobs.

4. Session — auth, then test run

Auth happens here — collect the credentials flagged in §2, now that the config is settled: a vault (existing or vaults.create()) + vaults.credentials.create() for each MCP server declared in §2, environment_variable credentials for API keys the job uses (substituted at egress; the sandbox sees a placeholder), and the authorization_token for each repo mount. Credentials are write-only; MCP credentials match servers by URL and auto-refresh. See shared/managed-agents-tools.md → Vaults.

Silent viability gate — run this yourself before emitting anything; surface only the gaps. Walk the job clause by clause: every verb maps to an enabled tool or MCP server ("open a PR" → GitHub MCP, not just the mount); every MCP server and repo mount has its credential from the auth step; every external host is reachable under the networking choice; every file/repo/dataset the job references is mounted; "done" is checkable. If something's missing, say so and resolve it — don't emit a config you already know is under-resourced.

Kickoff — pick one, never both: - user.message — conversational. - user.define_outcome + rubric — when §2 settled on an Outcome; the harness iterates and grades until the rubric passes. - Scheduled shape? Skip per-session kickoff entirely — create a deployment (deployments.create() with schedule + initial_events); each firing creates the session autonomously. See shared/managed-agents-scheduled-deployments.md.

Mechanics to bake into the runtime code: session creation blocks until resources mount (bad mounts surface there, before tokens); open the event stream before sending the kickoff; break on session.status_terminated, or session.status_idle with a terminal stop_reason — anything except requires_action (shared/managed-agents-client-patterns.md Pattern 5); usage lands on span.model_request_end; artifacts land in /mnt/session/outputs/ (files.list({scope_id: session.id, ...})).

5. Integrate — emit the code

Go straight from the last answer to the code — no preamble, no lecture about setup-vs-runtime; the two-block structure shows it. Generate two clearly-separated blocks:

Block 1 — Setup (run once, store the IDs). Prefer YAML files + ant CLI — agents and environments are version-controlled definitions users should check in and apply from CI:

  1. <name>.agent.yaml (flat: name, model, system, tools, mcp_servers, skills) and <name>.environment.yaml
  2. sh AGENT_ID=$(ant beta:agents create < <name>.agent.yaml --transform id -r) ENV_ID=$(ant beta:environments create < <name>.environment.yaml --transform id -r) # CI sync: ant beta:agents update --agent-id "$AGENT_ID" --version N < <name>.agent.yaml

SDK fallback if the user asks — and required on Claude Platform on AWS, where auth is SigV4 and the ant CLI has no SigV4 mode (use the platform client from shared/claude-platform-on-aws.md): label it # ONE-TIME SETUP — run once, save the IDs and call environments.create() → agents.create().

⚠️ Deployments are newer than the rest of the MA surface. Before emitting ant beta:deployments … or client.beta.deployments / client.beta.deployment_runs calls, verify the user's installed CLI/SDK exposes them (ant beta:deployments --help; hasattr(client.beta, "deployments")). If not, emit raw HTTP against POST /v1/deployments with the managed-agents-2026-04-01 beta header (plus oauth-2025-04-20 when authenticating with a Bearer token from ant auth print-credentials), and leave an upgrade note marking what simplifies to SDK calls.

Scheduled shape? The deployment is setup, not runtime. Create it in Block 1, after the agent/environment IDs exist (deployments.create() with schedule + initial_events). Block 2 is then not a session loop — there is no per-run kickoff to send. Emit instead: a manual-run trigger (POST /v1/deployments/{id}/run) so the user can test now rather than wait for the first firing — the manual run doubles as the smoke test — plus a fetch helper (latest deployment_runs entry → session_id → Console URL + files.list(scope_id=session_id) for the artifacts).

Block 2 — Runtime (every invocation; conversational and Outcome shapes). SDK code in the detected language (Python/TS/cURL — SKILL.md → Language Detection); don't emit shell loops here:

  1. Load agent_id + env_id from config/env
  2. sessions.create(agent=AGENT_ID, environment_id=ENV_ID, resources=[...], vault_ids=[...]), then print the Console URL so the user can watch live: https://platform.claude.com/workspaces/default/sessions/{session.id} (swap default for their workspace slug)
  3. Smoke-test when the job depends on MCP servers, credentials, or locked-down hosts — those failures don't surface at sessions.create(), only on first use. One cheap probe turn ("Confirm you can reach and list 1–2 items; don't start the task"), verify, then send the real kickoff. Skip when there are no external dependencies.
  4. Open stream → send the §4 kickoff → loop with the terminal gate from §4.

⚠️ Never emit agents.create() and sessions.create() in the same unguarded block — that teaches creating a new agent per run, the #1 anti-pattern. Single-script requests: wrap creation in if not os.getenv("AGENT_ID"):.

Pull exact syntax from {lang}/managed-agents/README.md for your detected language (cURL and C#: use curl/managed-agents.md as the wire-level reference). Don't invent field names.

Managed Agents — Outcomes

An outcome elevates a session from conversation to work: you state what "done" looks like, and the harness runs an iterate → grade → revise loop until the artifact meets the rubric, hits max_iterations, or is interrupted. A separate grader (independent context window) scores each iteration against your rubric and feeds per-criterion gaps back to the agent.

The SDK sets the managed-agents-2026-04-01 beta header automatically on all client.beta.sessions.* calls; no additional header is required for outcomes.

The user.define_outcome event

Outcomes are not a field on sessions.create(). You create a normal session, then send a user.define_outcome event. The agent starts working on receipt — do not also send a user.message to kick it off.

session = client.beta.sessions.create(
    agent=AGENT_ID,
    environment_id=ENVIRONMENT_ID,
    title="Financial analysis on Costco",
)

client.beta.sessions.events.send(
    session_id=session.id,
    events=[
        {
            "type": "user.define_outcome",
            "description": "Build a DCF model for Costco in .xlsx",
            "rubric": {"type": "text", "content": RUBRIC_MD},
            # or: "rubric": {"type": "file", "file_id": rubric.id}
            "max_iterations": 5,  # optional; default 3, max 20
        }
    ],
)
Field Type Notes
type "user.define_outcome"
description string The task. This is what the agent works toward — no separate user.message needed.
rubric {type: "text", content} | {type: "file", file_id} Required. Markdown with explicit, independently gradeable criteria. Upload once via client.beta.files.upload(...) (beta files-api-2025-04-14) to reuse across sessions.
max_iterations int Optional. Default 3, max 20.

The event is echoed back on the stream with a server-assigned outcome_id and processed_at.

Writing rubrics. Use explicit, gradeable criteria ("CSV has a numeric price column"), not vibes ("data looks good") — the grader scores each criterion independently, so vague criteria produce noisy loops. If you don't have a rubric, have Claude analyze a known-good artifact and turn that analysis into one.

Outcome-specific events

These appear on the standard event stream (sessions.events.stream / .list) alongside the usual agent.* / session.* events.

Event Payload highlights Meaning
span.outcome_evaluation_start outcome_id, iteration (0-indexed) Grader began scoring iteration N.
span.outcome_evaluation_ongoing outcome_id Heartbeat while the grader runs. Grader reasoning is opaque — you see that it's working, not what it's thinking.
span.outcome_evaluation_end outcome_evaluation_start_id, outcome_id, iteration, result, explanation, usage Grader finished one iteration. result drives what happens next (table below).

span.outcome_evaluation_end.result

result Next
satisfied Session → idle. Terminal for this outcome.
needs_revision Agent starts another iteration.
max_iterations_reached No further grader cycles. Agent may run one final revision, then session → idle.
failed Session → idle. Rubric fundamentally doesn't match the task (e.g. description and rubric contradict).
interrupted Only emitted if _start had already fired before a user.interrupt arrived. 
{
  "type": "span.outcome_evaluation_end",
  "id": "sevt_01jkl...",
  "outcome_evaluation_start_id": "sevt_01def...",
  "outcome_id": "outc_01a...",
  "result": "satisfied",
  "explanation": "All 12 criteria met: revenue projections use 5 years of historical data, ...",
  "iteration": 0,
  "usage": { "input_tokens": 2400, "output_tokens": 350, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 1800 },
  "processed_at": "2026-03-25T14:03:00Z"
}

Checking status & retrieving deliverables

Status — either watch the stream for span.outcome_evaluation_end, or poll the session and read outcome_evaluations:

session = client.beta.sessions.retrieve(session.id)
for ev in session.outcome_evaluations:
    print(f"{ev.outcome_id}: {ev.result}")  # outc_01a...: satisfied

Deliverables — the agent writes to /mnt/session/outputs/. Once idle, fetch via the Files API with scope_id=session.id. This is the same session-outputs mechanism documented in shared/managed-agents-environments.md → Session outputs (including the dual-beta-header requirement on files.list).

Interaction rules & pitfalls

  • One outcome at a time. Chain by sending the next user.define_outcome only after the previous one's terminal span.outcome_evaluation_end (satisfied / max_iterations_reached / failed / interrupted). The session retains history across chained outcomes.
  • Steering is allowed but optional. You may send user.message events mid-outcome to nudge direction, but the agent already knows to keep working until terminal — don't send "keep going" prompts.
  • user.interrupt pauses the current outcome — it marks result: "interrupted" and leaves the session idle, ready for a new outcome or conversational turn.
  • After terminal, the session is reusable — continue conversationally or define a new outcome.
  • Outcome ≠ session-create field. Don't put outcome, rubric, or description on sessions.create() — outcomes are always sent as a user.define_outcome event.
  • Idle-break gate is unchanged. In your drain loop, keep using event.type === 'session.status_idle' && event.stop_reason?.type !== 'requires_action' — do not gate on span.outcome_evaluation_end alone (on needs_revision the session keeps running). See shared/managed-agents-client-patterns.md Pattern 5.

For the raw HTTP shapes and per-language SDK bindings beyond Python, WebFetch https://platform.claude.com/docs/en/managed-agents/define-outcomes.md (see shared/live-sources.md).

Managed Agents — Overview

Managed Agents provisions a container per session as the agent's workspace. The agent loop runs on Anthropic's orchestration layer; the container is where the agent's tools execute — bash commands, file operations, code. You create a persisted Agent config (model, system prompt, tools, MCP servers, skills), then start Sessions that reference it. The session streams events back to you; you send user messages and tool results in.

⚠️ THE MANDATORY FLOW: Agent (once) → Session (every run)

Why agents are separate objects: versioning. An agent is a persisted, versioned config — every update creates a new immutable version, and sessions pin to a version at creation time. This lets you iterate on the agent (tweak the prompt, add a tool) without breaking sessions already running, roll back if a change regresses, and A/B test versions side-by-side. None of that works if you agents.create() fresh on every run.

Every session references a pre-created /v1/agents object. Create the agent once, store the ID, and reuse it across runs.

Step Call Frequency
1 POST /v1/agents — model, system, tools, mcp_servers, skills live here ONCE. Store agent.id and agent.version.
2 POST /v1/sessions — agent: "agent_abc123" or {type: "agent", id, version} Every run. String shorthand uses latest version.

If you're about to write sessions.create() with model, system, or tools on the session body — stop. Those fields live on agents.create(). The session takes a pointer only.

When generating code, separate setup from runtime. agents.create() belongs in a setup script (or a guarded if agent_id is None: block), not at the top of the hot path. If the user's code calls agents.create() on every invocation, they're accumulating orphaned agents and paying the create latency for nothing. The correct shape is: create once → persist the ID (config file, env var, secrets manager) → every run loads the ID and calls sessions.create().

To change the agent's behavior, use POST /v1/agents/{id} — don't create a new one. Each update bumps the version; running sessions keep their pinned version, new sessions get the latest (or pin explicitly via {type: "agent", id, version}). See shared/managed-agents-core.md → Agents → Versioning. To change tools/mcp_servers/vault_ids on one running session without touching the agent object, use sessions.update() — see shared/managed-agents-core.md → Updating the agent configuration mid-session.

Beta Headers

Managed Agents is in beta. The SDK sets required beta headers automatically:

Beta Header What it enables
managed-agents-2026-04-01 Agents, Environments, Sessions, Events, Session Resources, Session Threads, Outcomes, Multiagent, Vaults, Credentials, Memory Stores, Deployments
skills-2025-10-02 Skills API (for managing custom skill definitions)
files-api-2025-04-14 Files API for file uploads

Which beta header goes where: The SDK sets managed-agents-2026-04-01 automatically on client.beta.{agents,environments,sessions,vaults,memory_stores,deployments,deployment_runs}.* calls, and files-api-2025-04-14 / skills-2025-10-02 automatically on client.beta.files.* / client.beta.skills.* calls. You do NOT need to add the Skills or Files beta header when calling Managed Agents endpoints. Exception — session-scoped file listing: client.beta.files.list({scope_id: session.id}) is a Files endpoint that takes a Managed Agents parameter, so it needs both headers. Pass betas: ["managed-agents-2026-04-01"] explicitly on that call (the SDK adds the Files header; you add the Managed Agents one). See shared/managed-agents-environments.md → Session outputs.

Reading Guide

User wants to... Read these files
Get started from scratch / "help me set up an agent" shared/managed-agents-onboarding.md — guided interview (WHERE→WHO→WHAT→WATCH), then emit code
Understand how the API works shared/managed-agents-core.md
See the full endpoint reference shared/managed-agents-api-reference.md
Create an agent (required first step) shared/managed-agents-core.md (Agents section) + language file
Update/version an agent shared/managed-agents-core.md (Agents → Versioning) — update, don't re-create
Create a session shared/managed-agents-core.md + {lang}/managed-agents/README.md (cURL/C#: curl/managed-agents.md)
Configure tools and permissions shared/managed-agents-tools.md
Set up MCP servers shared/managed-agents-tools.md (MCP Servers section)
Stream events / handle tool_use shared/managed-agents-events.md + language file
Get notified of session state changes via webhook (no polling) shared/managed-agents-webhooks.md — Console-registered endpoint, HMAC verify, thin payload + fetch
Define an outcome / rubric-graded iterate loop shared/managed-agents-outcomes.md — user.define_outcome event, grader, span.outcome_evaluation_* events
Coordinate multiple agents / subagents / threads shared/managed-agents-multiagent.md — multiagent: {type: "coordinator", agents: [...]} on the agent, session threads, cross-posted tool confirmations
Set up environments shared/managed-agents-environments.md + language file
Run tool execution in your own infra / VPC (self-hosted sandbox) shared/managed-agents-self-hosted-sandboxes.md — config:{type:"self_hosted"}, ANTHROPIC_ENVIRONMENT_KEY, EnvironmentWorker.run() / ant beta:worker poll
Upload files / attach repos shared/managed-agents-environments.md (Resources)
Give agents persistent memory across sessions shared/managed-agents-memory.md — memory stores, memory_store session resource, preconditions, versions/redact
Define agents/environments as version-controlled YAML; drive the API from the shell shared/anthropic-cli.md — ant beta:agents create < agent.yaml, --transform, @file inlining
Store credentials (MCP auth, API keys for CLIs/SDKs) shared/managed-agents-tools.md (Vaults section) — mcp_oauth / static_bearer / environment_variable
Call a non-MCP API / CLI that needs a secret shared/managed-agents-tools.md (Vaults section) — environment_variable credential, substituted at egress. If that doesn't fit (e.g. self-hosted sandboxes), shared/managed-agents-client-patterns.md Pattern 9 keeps the secret host-side via a custom tool
Run an agent on a recurring cron schedule shared/managed-agents-scheduled-deployments.md — deployments, deployment runs, pause/auto-pause

Common Pitfalls

  • Agent FIRST, then session — NO EXCEPTIONS — the session's agent field accepts only a string ID or {type: "agent", id, version}. model, system, tools, mcp_servers, skills are top-level fields on POST /v1/agents, never on sessions.create(). If the user hasn't created an agent, that is step zero of every example.
  • Agent ONCE, not every run — agents.create() is a setup step. Store the returned agent_id and reuse it; don't call agents.create() at the top of your hot path. If the agent's config needs to change, POST /v1/agents/{id} — each update creates a new version, and sessions can pin to a specific version for reproducibility.
  • MCP auth goes through vaults — the agent's mcp_servers array declares {type, name, url} only (no auth). Credentials live in vaults (client.beta.vaults.credentials.create) and attach to sessions via vault_ids. Anthropic auto-refreshes OAuth tokens using the stored refresh token. Vaults also hold environment_variable credentials for non-MCP services (CLIs, SDKs, direct API calls) — substituted at egress, never visible in the sandbox.
  • 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.
  • 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.

Managed Agents — Scheduled Deployments

A scheduled deployment runs an agent on a recurring cron schedule — each firing creates a session autonomously. Use it for predictable-cadence work: nightly triage, weekly compliance scans, hourly monitors.

Requires the managed-agents-2026-04-01 beta header (the SDK sets it automatically for client.beta.deployments.* / client.beta.deployment_runs.* calls).

Create a deployment

A deployment bundles everything a session needs (agent, environment, optional files / GitHub / memory stores / vaults) plus a schedule and the initial_events that kick off each run:

  • agent and environment_id are required — same shapes as sessions.create (see shared/managed-agents-core.md).
  • initial_events must contain the starting user.message.
  • schedule takes a cron expression and an IANA timezone. Minute-level granularity is the maximum.
curl -fsSL https://api.anthropic.com/v1/deployments \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "name": "Weekly compliance scan",
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "initial_events": [
    {"type": "user.message", "content": [{"type": "text", "text": "Run the weekly compliance scan."}]}
  ],
  "schedule": {
    "type": "cron",
    "expression": "0 20 * * 5",
    "timezone": "America/New_York"
  }
}
EOF

deployment = client.beta.deployments.create(
    name="Weekly compliance scan",
    agent=agent.id,
    environment_id=environment.id,
    initial_events=[
        {
            "type": "user.message",
            "content": [{"type": "text", "text": "Run the weekly compliance scan."}],
        },
    ],
    schedule={
        "type": "cron",
        "expression": "0 20 * * 5",
        "timezone": "America/New_York",
    },
)

The response is a deployment object (depl_ ID prefix). Check schedule.upcoming_runs_at — the next fire times — to confirm the schedule parses the way you intended:

{
  "id": "depl_01xyz",
  "status": "active",
  "paused_reason": null,
  "schedule": {
    "type": "cron",
    "expression": "0 20 * * 5",
    "timezone": "America/New_York",
    "last_run_at": null,
    "upcoming_runs_at": ["2026-05-09T00:00:00Z", "2026-05-16T00:00:00Z", "2026-05-23T00:00:00Z"]
  }
}

Deployments may apply up to 10 seconds of jitter to distribute load. Maximum 1000 scheduled deployments per organization (contact Anthropic support for more).

Cron and timezone semantics

  • Expression: standard POSIX cron (minute hour day-of-month month day-of-week).
  • Timezone: IANA identifier (e.g. "America/Los_Angeles").
  • DST: literal wall-clock matching — "0 20 * * *" in America/New_York fires at 8:00 PM local regardless of EST/EDT.

⚠️ DST edge: wall-clock times that don't exist on a spring-forward day (e.g. 2AM) are skipped; times that occur twice on a fall-back day fire twice. Schedule outside the 1–3AM local window, or use UTC, when missed or duplicate executions are unacceptable.

Deployment runs

Every trigger attempt — successful or not — writes a deployment run record (drun_ prefix), so you can audit failures independent of the session lifecycle. A successful run carries the created session_id; follow that session via the event stream (shared/managed-agents-events.md) or webhooks (shared/managed-agents-webhooks.md) as usual. A failed run carries an error whose type explains why session creation was rejected.

# All runs for a deployment
for run in client.beta.deployment_runs.list(deployment_id=deployment.id):
    print(run.created_at, run.session_id or run.error.type)

# Failures only
for run in client.beta.deployment_runs.list(deployment_id=deployment.id, has_error=True):
    print(run.created_at, run.error.type, run.error.message)

for await (const run of client.beta.deploymentRuns.list({
  deployment_id: deployment.id,
  has_error: true,
})) {
  console.log(run.created_at, run.error?.type, run.error?.message);
}

Raw HTTP: GET /v1/deployment_runs?deployment_id=...&has_error=true. To retrieve a single run by ID, GET /v1/deployment_runs/{deployment_run_id} (SDK: client.beta.deployment_runs.retrieve(run_id)) — a deployment_run.* webhook event carries the run ID as its data.id.

A failed run looks like:

{
  "type": "deployment_run",
  "id": "drun_01abc124",
  "deployment_id": "depl_01xyz",
  "trigger_context": { "type": "schedule", "scheduled_at": "2026-05-09T00:00:00Z" },
  "session_id": null,
  "error": { "type": "environment_archived", "message": "environment `env_01abc` is archived" },
  "agent": { "type": "agent", "id": "agent_01ghi789", "version": 3 },
  "created_at": "2026-05-09T00:00:01Z"
}

Error types include environment_archived, agent_archived, vault_not_found, session_rate_limited, and service_unavailable.

The outcome of each scheduled run (started/succeeded/failed) and each deployment lifecycle change (created/updated/paused/unpaused/archived/deleted) is also delivered as a webhook event — see shared/managed-agents-webhooks.md for the deployment.* and deployment_run.* event types — so you can react without polling. Manual runs do not emit deployment_run.* webhook events.

Lifecycle: pause / unpause / archive

Operation SDK Effect
Pause client.beta.deployments.pause(id) Suppresses scheduled triggers go-forward. Sessions already running continue. Manual runs are still permitted while paused. Sets paused_reason: {"type": "manual"}.
Unpause client.beta.deployments.unpause(id) Resumes from the next scheduled occurrence. Missed triggers are not backfilled. Clears paused_reason.
Archive client.beta.deployments.archive(id) Terminal — the schedule stops and the deployment can no longer be modified. Use pause for anything reversible.

Raw HTTP: POST /v1/deployments/{deployment_id}/pause (likewise /unpause, /archive).

Failure behavior

  • Rate-limited: recorded immediately as a session_rate_limited run, no retry — the schedule simply tries again at the next occurrence. (Rate limits on API calls inside a session are handled by the session itself.)
  • Other failed runs (e.g. environment_archived, vault_not_found, service_unavailable): the run records the error.type — monitor runs and fix the referenced resource, or pause the deployment.
  • Agent archived or deleted: the deployment is automatically archived (terminal) and no further sessions are created.

Manual runs

POST /v1/deployments/{deployment_id}/run (SDK: client.beta.deployments.run(id)) creates a session immediately and writes a run with trigger_context.type: "manual". Use it to test a deployment before committing to the schedule — and remember it works even while the deployment is paused.

Managed Agents — Self-Hosted Sandboxes

With config.type: "self_hosted", the agent loop stays on Anthropic's orchestration layer but tool execution moves to infrastructure you control — bash, file ops, and code run inside your container, so filesystem contents and network egress never leave your environment. Contrast with config.type: "cloud", where Anthropic runs the container. Connectivity is outbound-only: your worker long-polls Anthropic's work queue; Anthropic never dials into your network.

Flow

1. Create environment:      config: {type: "self_hosted"}        → env_...
2. Generate environment key (Console, on the environment page)   → sk-ant-oat01-...  as ANTHROPIC_ENVIRONMENT_KEY
3. Run a worker:            EnvironmentWorker.run()  or  ant beta:worker poll
4. Sessions reference       environment_id=env_... exactly as for cloud

Create the environment

client = anthropic.Anthropic()

environment = client.beta.environments.create(
    name="self-hosted", config={"type": "self_hosted"}
)

{"type": "self_hosted"} is the entire config — there are no pool, capacity, or networking sub-fields; you control those on your side.

Run a worker — SDK (primary path)

EnvironmentWorker wraps the poll → dispatch → tool-execute loop. .run() is the always-on loop; .run_one() / .runOne() handles one work item (for webhook-driven wake).

Python — always-on:

import asyncio
import os
from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker


async def main() -> None:
    environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
    environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
    async with AsyncAnthropic(auth_token=environment_key) as client:
        await EnvironmentWorker(
            client,
            environment_id=environment_id,
            environment_key=environment_key,
            workdir="/workspace",
        ).run()


asyncio.run(main())

TypeScript — always-on:

import Anthropic from "@anthropic-ai/sdk";
import { EnvironmentWorker } from "@anthropic-ai/sdk/helpers/beta/environments";

const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;
const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
const client = new Anthropic({ authToken: environmentKey });
const ctrl = new AbortController();
process.once("SIGTERM", () => ctrl.abort());

await new EnvironmentWorker({
  client,
  environmentId,
  environmentKey,
  workdir: "/workspace",
  signal: ctrl.signal
}).run();

Customizing tools. EnvironmentWorker runs the built-in toolset by default. To add or replace tools, use AgentToolContext(workdir=, client=, session_id=) with beta_agent_toolset(env) / betaAgentToolset(env) and pass the resulting tools to the lower-level tool_runner(). Skills attached to the agent are downloaded into {workdir}/skills/<name>/ before tool calls begin (AgentToolContext handles this when given client and session_id). Downloaded skill files are marked executable automatically by the CLI and SDK; if you implement skills download yourself, you set permissions.

Runtime deps: the SDK helpers require /bin/bash at that exact path. The TypeScript SDK additionally requires unzip, tar, and Node.js 22+. These are resolved at fixed paths and do not respect PATH overrides.

Run a worker — ant CLI (fixed tools)

The ant CLI ships a worker with the fixed built-in toolset (bash, read, write, edit, glob, grep). Install per shared/anthropic-cli.md, then:

export ANTHROPIC_ENVIRONMENT_KEY=sk-ant-oat01-...
ant beta:worker poll --environment-id env_... --workdir /workspace
  • --workdir is the directory tools operate in (default .); tool calls are sandboxed to it.
  • --environment-key overrides the env var.
  • --on-work <script> runs your script per work item (e.g. to spin a fresh container per session — see Container orchestration below).
  • --unrestricted-paths, --max-idle (default 60s), --log-format — see ant beta:worker poll --help.
  • Flags fall back to env vars (ANTHROPIC_ENVIRONMENT_ID, ANTHROPIC_ENVIRONMENT_KEY).
  • Exits cleanly on SIGTERM/SIGINT after draining in-flight work.
  • Fixed toolset — for custom tools, use the SDK worker above.

Inside an --on-work container, run ant beta:worker run --workdir <dir> as the entrypoint.

Webhook-driven wake (instead of always-on)

Register a webhook for session.status_run_started (see shared/managed-agents-webhooks.md), verify the delivery, then drain one work item with .run_one():

import os
import anthropic
from anthropic.lib.environments import EnvironmentWorker

environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
client = anthropic.AsyncAnthropic(
    auth_token=environment_key,
)  # reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env for webhooks.unwrap()


async def handle(raw: bytes, headers: dict[str, str]) -> dict:
    event = client.beta.webhooks.unwrap(raw.decode(), headers=headers)
    if event.data.type != "session.status_run_started":
        return {"status": "ignored"}
    await EnvironmentWorker(
        client,
        environment_id=environment_id,
        environment_key=environment_key,
        workdir="/workspace",
    ).run_one()
    return {"status": "ok"}

TypeScript: same shape with client.beta.webhooks.unwrap(body, {headers}) and new EnvironmentWorker({...}).runOne().

Container orchestration (mid-level)

EnvironmentWorker.run() polls and executes tools in the same process. To run each session in its own container, use the mid-level poller in a thin orchestrator — Python client.beta.environments.work.poller(environment_id=, environment_key=, drain=, block_ms=, reclaim_older_than_ms=, auto_stop=); TypeScript new WorkPoller({client, environmentId, environmentKey, autoStop}) from @anthropic-ai/sdk/helpers/beta/environments — and, for each yielded work item, start a fresh container with these env vars injected, whose entrypoint runs ant beta:worker run or an EnvironmentWorker(...).run_one(). block_ms is 1–999 (or None for non-blocking); reclaim_older_than_ms re-claims items leased to a dead worker; drain stops once the queue is empty; auto_stop posts a stop signal after the iterator exits (set False when the launched container owns the stop call). Go's poller has no auto_stop opt-out — it calls work.Stop when the handler returns, so block in the handler until the session completes rather than detaching.

Env var Value
ANTHROPIC_SESSION_ID work.data.id
ANTHROPIC_WORK_ID work.id
ANTHROPIC_ENVIRONMENT_ID work.environment_id
ANTHROPIC_ENVIRONMENT_KEY pass through
ANTHROPIC_BASE_URL pass through

Skip items where work.data.type != "session".

Monitoring & control

These are control-plane calls — authenticate with x-api-key (not the environment key); managed-agents-2026-04-01 beta header. Call them from outside the worker host — setting ANTHROPIC_API_KEY on the worker host exposes an organization-scoped credential to agent tool calls.

SDK (client.beta.environments.work.*) REST CLI Returns
stats(environment_id) GET /v1/environments/{id}/work/stats ant beta:environments:work stats {type:"work_queue_stats", depth, pending, oldest_queued_at, workers_polling}
stop(work_id, environment_id=) POST /v1/environments/{id}/work/{work_id}/stop ant beta:environments:work stop work.state

What changes vs cloud

Concern cloud self_hosted
Container lifecycle, hardening, networking Anthropic You — run non-root, read-only rootfs, drop caps; egress is whatever your VPC/firewall allows
file / github_repository resource mounting Anthropic mounts into the container You — pass pointers via sessions.create(metadata={...}) and have your orchestrator fetch/clone before dispatch
memory_store resources Supported Not yet supported
Vault environment_variable credentials Supported (substituted at Anthropic-managed egress) Not yet supported — egress is yours, so there's nowhere to substitute the secret. Use MCP credentials or a host-side custom tool (shared/managed-agents-client-patterns.md Pattern 9)
Built-in tools Via agent_toolset_20260401 Supplied by your worker (EnvironmentWorker default / beta_agent_toolset(env) / ant CLI fixed set)
Skills download Automatic EnvironmentWorker / AgentToolContext fetch into {workdir}/skills/ (needs client + session_id)
Claude Platform on AWS Supported Not available
SDK worker helpers All SDKs Python, TypeScript, Go only (EnvironmentWorker / poller not in Java, Ruby, PHP, or C#) — use one of those three or the ant CLI

Credentials

Credential Format Scope
ANTHROPIC_ENVIRONMENT_KEY sk-ant-oat01-... One environment's work queue. Generate in Console ("Generate environment key"). Pass as auth_token= / authToken on the client and as environment_key= / environmentKey on EnvironmentWorker. Store in a secrets manager; rotate on exposure.
ANTHROPIC_WEBHOOK_SIGNING_KEY whsec_... Webhook signature verification (if using webhook-driven wake). The SDK reads this env var automatically for client.beta.webhooks.unwrap().

Security — what you own

Container hardening; egress restriction (there is no default); ANTHROPIC_ENVIRONMENT_KEY custody and rotation; one workspace + environment per trust boundary when running untrusted code; least-privilege for the tool process; log retention and redaction. Anthropic cannot: fast-revoke a leaked environment key, verify your image or supply chain, sandbox tool execution inside your container, or enforce retention after tool output reaches your infrastructure. See the Self-Hosted Sandboxes Security page in shared/live-sources.md for the full checklist.

Managed Agents — Tools & Skills

Tools

Server tools vs client tools

Type Who runs it How it works
Prebuilt Claude Agent tools (agent_toolset_20260401) Anthropic, on the session's container (for cloud envs; for self_hosted, your worker supplies and runs them — see shared/managed-agents-self-hosted-sandboxes.md) File ops, bash, web search, etc. Enable all at once or configure individually with enabled: true/false.
MCP tools (mcp_toolset) Anthropic's orchestration layer Capabilities exposed by connected MCP servers. Grant access per-server via the toolset.
Custom tools You — your application handles the call and returns results Agent emits a agent.custom_tool_use event, session goes idle, you send back a user.custom_tool_result event.

Recommendation: Enable all prebuilt tools via agent_toolset_20260401, then disable individually as needed.

Versioning: The toolset is a versioned, static resource. When underlying tools change, a new toolset version is created (hence _20260401) so you always know exactly what you're getting.

Agent Toolset

The agent_toolset_20260401 provides these built-in tools:

Tool Description
bash Execute bash commands in a shell session
read Read a file from the local filesystem, including text, images, PDFs, and Jupyter notebooks
write Write a file to the local filesystem
edit Perform string replacement in a file
glob Fast file pattern matching using glob patterns
grep Text search using regex patterns
web_fetch Fetch content from a URL
web_search Search the web for information

Enable the full toolset:

{
  "tools": [
    { "type": "agent_toolset_20260401" }
  ]
}

Per-Tool Configuration

Override defaults for individual tools. This example enables everything except bash:

{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "default_config": { "enabled": true },
      "configs": [
        { "name": "bash", "enabled": false }
      ]
    }
  ]
}
Field Required Description
type ✅ "agent_toolset_20260401"
default_config ❌ Applied to all tools. { "enabled": bool, "permission_policy": {...} }
configs ❌ Per-tool overrides: [{ "name": "...", "enabled": bool, "permission_policy": {...} }]

Permission Policies

Control when server-executed tools (agent toolset + MCP) run automatically vs wait for approval. Does not apply to custom tools.

Policy Behavior
always_allow Tool executes automatically (default)
always_ask Session emits session.status_idle and pauses until you send a tool_confirmation event 
{
  "type": "agent_toolset_20260401",
  "default_config": {
    "enabled": true,
    "permission_policy": { "type": "always_allow" }
  },
  "configs": [
    { "name": "bash", "permission_policy": { "type": "always_ask" } }
  ]
}

Responding to always_ask: Send a user.tool_confirmation event with tool_use_id from the triggering agent_tool_use/mcp_tool_use event:

{ "type": "tool_confirmation", "tool_use_id": "sevt_abc123", "result": "allow" }
{ "type": "tool_confirmation", "tool_use_id": "sevt_def456", "result": "deny", "message": "Read .env.example instead" }

The optional message on a deny is delivered to the agent so it can adjust its approach.

To enable only specific tools, flip the default off and opt-in per tool:

{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "default_config": { "enabled": false },
      "configs": [
        { "name": "bash", "enabled": true },
        { "name": "read", "enabled": true }
      ]
    }
  ]
}

Custom Tools (Client-Side)

Custom tools are executed by your application, not Anthropic. The flow:

  1. Agent decides to use the tool → session emits a agent.custom_tool_use event with inputs
  2. Session goes idle waiting for you
  3. Your application executes the tool
  4. You send back a user.custom_tool_result event with the output
  5. Session resumes running

No permission policy needed — you're the one executing.

{
  "tools": [
    {
      "type": "custom",
      "name": "get_weather",
      "description": "Fetch current weather for a city.",
      "input_schema": {
        "type": "object",
        "properties": {
          "city": { "type": "string", "description": "City name" }
        },
        "required": ["city"]
      }
    }
  ]
}

MCP Servers

MCP (Model Context Protocol) servers expose standardized third-party capabilities (e.g. Asana, GitHub, Linear). Configuration is split across agent and vault:

  1. Agent creation declares which servers to connect to (type, name, url — no auth). The agent's mcp_servers array has no auth field.
  2. Vault stores the OAuth credentials. Attach via vault_ids on session create.

This keeps secrets out of reusable agent definitions. Each vault credential is tied to one MCP server URL; Anthropic matches credentials to servers by URL.

Agent side — declare servers (no auth):

Field Required Description
type ✅ "url"
name ✅ Unique name — referenced by mcp_toolset.mcp_server_name
url ✅ The MCP server's endpoint URL (Streamable HTTP transport) 
{
  "mcp_servers": [
    { "type": "url", "name": "linear", "url": "https://mcp.linear.app/mcp" }
  ],
  "tools": [
    { "type": "mcp_toolset", "mcp_server_name": "linear" }
  ]
}

Session side — attach vault:

{
  "agent": "agent_abc123",
  "environment_id": "env_abc123",
  "vault_ids": ["vlt_abc123"]
}

💡 Per-tool enablement (empirical): mcp_toolset has been observed accepting default_config: {enabled: false} + configs: [{name, enabled: true}] for an allowlist pattern. The API ref shows only the minimal {type, mcp_server_name} form.

💡 Changing tools/MCP servers on a running session: sessions.update() can replace agent.tools, agent.mcp_servers, and vault_ids while the session is idle — a session-local override that doesn't touch the agent object. See shared/managed-agents-core.md → Updating the agent configuration mid-session.

Large MCP tool outputs. If an MCP tool returns more than 100K tokens, the output is automatically offloaded to a file in the sandbox — the agent receives a truncated preview plus the file path and can read the full content. No configuration required.

Invalid vault credentials don't block session creation. If a vault credential is invalid for a declared MCP server, the session still creates successfully; a session.error event describes the MCP auth failure, and auth retries on the next session.status_idle → session.status_running transition.

⚠️ MCP auth tokens ≠ REST API tokens. Hosted MCP servers (mcp.notion.com, mcp.linear.app, etc.) typically require OAuth bearer tokens, not the service's native API keys. A Notion ntn_ integration token authenticates against Notion's REST API but will not work as a vault credential for the Notion MCP server. These are different auth systems.

Vaults — the credential store

Vaults store credentials that Anthropic manages on your behalf. Two credential categories:

  • MCP credentials (mcp_oauth, static_bearer) — keyed by mcp_server_url. When the agent connects to a server at that URL, the token is injected automatically. mcp_oauth tokens are auto-refreshed via the standard OAuth 2.0 refresh_token grant. This is the only way to authenticate MCP servers.
  • Environment variables (environment_variable) — keyed by secret_name (the env var name). The sandbox sees only an opaque placeholder; the real secret is substituted into the outbound request at egress. Use this for any service that authenticates through an environment variable: CLIs (aws, gcloud, stripe), SDKs, or direct curl calls from the bash tool.

Secret fields you supply (token, access_token, refresh_token, client_secret, secret_value) are write-only — never returned in API responses.

Credentials and the sandbox

Vaults store credentials; those credentials never enter the sandbox. This is a deliberate security boundary — code running in the sandbox (including anything the agent writes) cannot read or exfiltrate a vaulted credential, even under prompt injection. Instead, credentials are injected by Anthropic-side proxies after a request leaves the sandbox:

  • MCP tool calls are routed through an Anthropic-side proxy that fetches the credential from the vault and adds it to the outbound request.
  • Git operations on attached GitHub repositories (git pull, git push, GitHub REST calls) are routed through a git proxy that injects the github_repository resource's authorization_token the same way.
  • Environment-variable credentials appear in the sandbox as an opaque placeholder; the real value replaces the placeholder at egress, on requests to the credential's allowed hosts only.

When vault credentials don't fit (e.g. self-hosted sandboxes — environment_variable is not yet supported there), register a custom tool: the agent emits agent.custom_tool_use, your orchestrator (which already holds the credential) executes the call and returns user.custom_tool_result over the same authenticated event stream. No public endpoint is exposed; the sandbox never sees the secret. See shared/managed-agents-client-patterns.md → Pattern 9.

Do not put API keys in the system prompt or user messages as a workaround — they persist in the session's event history.

Formerly known internally as TATs (Tool/Tenant Access Tokens).

Flow:

  1. Create a vault (client.beta.vaults.create(...)) — one per tenant/user, or one shared, depending on your model
  2. Add credentials to it (client.beta.vaults.credentials.create(...)) — MCP credentials are keyed by MCP server URL; environment-variable credentials by secret_name
  3. Reference the vault on session create via vault_ids: ["vlt_..."]
  4. Anthropic auto-refreshes OAuth tokens before they expire and substitutes secrets at runtime

MCP OAuth credential shape:

{
  "display_name": "Notion (workspace-foo)",
  "auth": {
    "type": "mcp_oauth",
    "mcp_server_url": "https://mcp.notion.com/mcp",
    "access_token": "<current access token>",
    "expires_at": "2026-04-02T14:00:00Z",
    "refresh": {
      "refresh_token": "<refresh token>",
      "client_id": "<your OAuth client_id>",
      "token_endpoint": "https://api.notion.com/v1/oauth/token",
      "token_endpoint_auth": { "type": "none" }
    }
  }
}

The refresh block is what enables auto-refresh — token_endpoint is where Anthropic posts the refresh_token grant. token_endpoint_auth is a discriminated union:

type Shape Use when
"none" {type: "none"} Public OAuth client (no secret)
"client_secret_basic" {type: "client_secret_basic", client_secret: "..."} Confidential client, secret via HTTP Basic auth
"client_secret_post" {type: "client_secret_post", client_secret: "..."} Confidential client, secret in request body

Omit refresh entirely if you only have an access token with no refresh capability — it'll work until it expires, then the agent loses access.

💡 Getting an OAuth token. How you obtain the initial access and refresh tokens depends on the MCP server — consult its documentation. Once you have them, store them in a vault credential using the shape above; Anthropic auto-refreshes via the refresh.token_endpoint from there.

Environment-variable credential shape:

{
  "display_name": "Twilio API key for sandbox",
  "auth": {
    "type": "environment_variable",
    "secret_name": "TWILIO_API_KEY",
    "secret_value": "sk-your-secret-here",
    "networking": {
      "type": "limited",
      "allowed_hosts": ["api.twilio.com", "*.twilio.com"]
    }
  }
}

networking.allowed_hosts controls which outbound hosts the secret can be substituted for — {"type": "limited", "allowed_hosts": [...]} or {"type": "unrestricted"} if you can't enumerate the domains in advance. Limiting is strongly recommended: it prevents the key from ever being sent to unauthorized hosts.

injection_location (optional, sibling of networking) controls where in the outbound request the secret is substituted — {header: bool, body: bool}. The two are independent: allowed_hosts scopes which hosts a substituted request can target; injection_location scopes which parts of the request the secret is substituted into across all of those hosts. Most services read an API key from a request header, so {"header": true} is the narrower configuration — request bodies are often assembled from content the agent is working with, making the body the broader exposure surface. A placeholder in a disabled location is neither substituted nor stripped — the literal opaque placeholder string is sent to the third party in that location.

Operation injection_location semantics
Create credential Omit the field entirely → both locations enabled. Provide the object → any field you omit defaults to false ({"header": true} creates a header-only credential).
Update credential Fields merge individually — {"body": false} disables body substitution and leaves header unchanged. For a running session, the update takes effect on the session's next operation.

A credential must have at least one location enabled; a create or update that would disable both returns 400, as does explicit null for the object or either field (omit instead). The response always returns both fields with their resolved values.

⚠️ Two networking layers, both required. networking.allowed_hosts on the credential controls which requests use the secret, not which requests are allowed. The agent must also be able to reach the domain at the environment level (unrestricted, or the host listed in the environment's allowed_hosts — see shared/managed-agents-environments.md). A domain missing from either layer means the secret-substituted request fails.

⚠️ Client-side validation caveat. Substitution happens at egress, not inside the sandbox — clients that validate the credential format locally before making a network request (e.g. a CLI that checks the key starts with sk-) will see the opaque placeholder and may fail at startup. If a client rejects the credential before any network call, that's why.

💡 Scope the key minimally. The agent can do anything the key allows; a key with broader permissions than the task needs increases the blast radius if the agent behaves unexpectedly.

Not supported with self-hosted sandboxes — environment_variable credentials require Anthropic-managed egress. See shared/managed-agents-self-hosted-sandboxes.md.

Constraints (all credential types):

  • Unique key per vault. mcp_server_url (MCP credentials) and secret_name (environment-variable credentials) must be unique among active credentials in a vault; duplicates return a 409.
  • Keys are immutable. Secret values, display_name, and (on environment-variable credentials) injection_location can be updated; to change mcp_server_url, secret_name, token_endpoint, or client_id, archive the credential and create a new one. Archiving purges the secret and frees the key for a replacement.
  • Maximum 20 credentials per vault.
  • Credentials are stored as provided and not validated until session runtime — an invalid credential surfaces as an authentication or downstream error during the session, which is emitted but does not block the session from continuing.

Scoping: Vaults are workspace-scoped. Anyone with developer+ role in the API workspace can create, read (metadata only — secrets are write-only), and attach vaults. vault_ids can be set at session create time but not via session update (the SDK docstring says "Not yet supported; requests setting this field are rejected").

Skills

Skills are reusable, filesystem-based resources that provide your agent with domain-specific expertise: workflows, context, and best practices that transform general-purpose agents into specialists. Unlike prompts (conversation-level instructions for one-off tasks), skills load on-demand and eliminate the need to repeatedly provide the same guidance across multiple conversations.

Two types — both work the same way; the agent automatically uses them when relevant to the task at hand:

Type What it is
Pre-built Anthropic skills Common document tasks (PowerPoint, Excel, Word, PDF). Reference by name (e.g. xlsx).
Custom skills Skills you've created in your organization via the Skills API. Reference by skill_id + optional version.

Max 20 skills per agent. Agent creation uses managed-agents-2026-04-01; the separate Skills API (for managing custom skill definitions) uses skills-2025-10-02.

Enabling skills on a session

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",
    system: "You are a financial analysis agent.",
    skills: [
      { type: "anthropic", skill_id: "xlsx" },
      { type: "custom", skill_id: "skill_abc123", version: "latest" },
    ],
  }
);

Python:

agent = client.beta.agents.create(
    name="Financial Agent",
    model="claude-opus-4-8",
    system="You are a financial analysis agent.",
    skills=[
        {"type": "anthropic", "skill_id": "xlsx"},
        {"type": "custom", "skill_id": "skill_abc123", "version": "latest"},
    ]
)

Skill reference fields:

Field Anthropic skill Custom skill
type "anthropic" "custom"
skill_id Skill name (e.g. "xlsx", "docx", "pptx", "pdf") Skill ID from Skills API (e.g. "skill_abc123")
version — "latest" or a specific version number

Skills API

Operation Method Path
Create Skill POST /v1/skills
List Skills GET /v1/skills
Get Skill GET /v1/skills/{id}
Delete Skill DELETE /v1/skills/{id}
Create Version POST /v1/skills/{id}/versions
List Versions GET /v1/skills/{id}/versions
Get Version GET /v1/skills/{id}/versions/{version}
Delete Version DELETE /v1/skills/{id}/versions/{version}

Managed Agents — Webhooks

Anthropic can POST to your HTTPS endpoint when a Managed Agents resource changes state — an alternative to holding an SSE stream or polling. Payloads are thin (event type + resource IDs only); on receipt, fetch the resource for current state. Every delivery is HMAC-signed.

Direction matters. This page covers Anthropic → you notifications about session/vault state. It does not cover third-party → you webhooks that trigger a session (e.g. a GitHub push handler that calls sessions.create()) — that's ordinary application code on your side with no Anthropic-specific wire format.

Register an endpoint (Console only)

Console → Manage → Webhooks. There is no programmatic endpoint-management API yet. Secret rotation is supported from the same page.

Field Constraint
URL HTTPS on port 443, publicly resolvable hostname
Event types Subscribe per data.type — you only receive subscribed types (plus test events)
Signing secret whsec_-prefixed, 32 bytes, shown once at creation — store it

Verify the signature

Every delivery is HMAC-signed. Use the SDK's client.beta.webhooks.unwrap() — it verifies the signature, rejects payloads more than ~5 minutes old, and returns the parsed event. It reads the whsec_ secret from ANTHROPIC_WEBHOOK_SIGNING_KEY.

import anthropic
from flask import Flask, request

client = anthropic.Anthropic()  # reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env
app = Flask(__name__)


@app.route("/webhook", methods=["POST"])
def webhook():
    try:
        event = client.beta.webhooks.unwrap(
            request.get_data(as_text=True),
            headers=dict(request.headers),
        )
    except Exception:
        return "invalid signature", 400

    if event.id in seen_event_ids:  # dedupe retries — id is per-event, not per-delivery
        return "", 204
    seen_event_ids.add(event.id)

    match event.data.type:
        case "session.status_idled":
            session = client.beta.sessions.retrieve(event.data.id)
            notify_user(session)
        case "vault_credential.refresh_failed":
            alert_oncall(event.data.id)

    return "", 204

Pass the raw request body to unwrap() — frameworks that re-serialize JSON (Express .json(), Flask .get_json()) change the bytes and break the MAC. For other languages, look up the beta.webhooks.unwrap binding in the SDK repo (shared/live-sources.md); don't hand-roll verification.

Payload envelope

{
  "type": "event",
  "id": "event_01ABC...",
  "created_at": "2026-03-18T14:05:22Z",
  "data": {
    "type": "session.status_idled",
    "id": "session_01XYZ...",
    "organization_id": "8a3d2f1e-...",
    "workspace_id": "c7b0e4d9-..."
  }
}

Switch on data.type, fetch the resource by data.id, return any 2xx to acknowledge. created_at is when the state transition happened, not when the webhook fired.

Supported data.type values

data.type Fires when
session.status_scheduled Session created and ready to accept events
session.status_run_started Agent execution kicked off (every transition to running)
session.status_idled Agent awaiting input (tool approval, custom tool result, or next message)
session.status_terminated Session hit a terminal error
session.thread_created Multiagent: coordinator opened a new subagent thread
session.thread_idled Multiagent: a subagent thread is waiting for input
session.outcome_evaluation_ended Outcome grader finished one iteration
vault.archived Vault was archived
vault.created Vault was created
vault.deleted Vault was deleted
vault_credential.archived Vault credential was archived
vault_credential.created Vault credential was created
vault_credential.deleted Vault credential was deleted
vault_credential.refresh_failed MCP OAuth vault credential failed to refresh
agent.created Agent created
agent.updated A new agent version was published. Updates that do not create a new version do not fire this.
agent.archived Agent archived
agent.deleted Agent permanently deleted — no object left to fetch; treat the event itself as final
deployment.created Scheduled deployment created
deployment.updated Deployment properties changed (e.g. schedule edited)
deployment.paused Deployment paused — by request, or automatically when a scheduled run fails with a non-recoverable error (archived agent, missing environment). Recoverable failures, including rate limits, do not auto-pause.
deployment.unpaused Deployment unpaused; schedule resumes
deployment.archived Deployment archived — directly, or as a result of agent archival/deletion
deployment.deleted Deployment permanently deleted — no object left to fetch; treat the event itself as final
deployment_run.started A scheduled run started. Manual runs do not emit deployment_run.* events.
deployment_run.succeeded Scheduled run created its session. Same data.id (the run ID) as the run's .started event — fetch the deployment run for its session_id, then subscribe to the session events to follow the work.
deployment_run.failed Scheduled run did not create a session. Same data.id as the run's .started event — fetch the deployment run for error.type / error.message.

These are webhook data.type values — a separate namespace from SSE event types (session.status_idle, span.outcome_evaluation_end, etc. in shared/managed-agents-events.md). Don't reuse SSE constants in webhook handlers.

Delivery behavior & pitfalls

  • No ordering guarantee. session.status_idled may arrive before session.outcome_evaluation_ended even if the evaluation finished first. Sort by envelope created_at if order matters.
  • Retries carry the same event.id. At least one retry on non-2xx. Dedupe on event.id.
  • 3xx is failure. Redirects are not followed — update the URL in Console if your endpoint moves.
  • Auto-disable after ~20 consecutive failed deliveries, or immediately if the hostname resolves to a private IP or returns a redirect. Re-enable manually in Console.
  • Thin payload is intentional. Don't expect stop_reason, outcome_evaluations, credential secrets, etc. on the webhook body — fetch the resource.

Model Migration Guide

If you arrived via /claude-api migrate: this is the right file. Execute the steps below in order — do not summarize them back to the user. Start with Step 0 (confirm scope) before touching any file.

How to move existing code to newer Claude models. Covers breaking changes, deprecated parameters, and drop-in replacements for retired models.

For the latest, authoritative version (with code samples in every supported language), WebFetch the Migration Guide URL from shared/live-sources.md. Use this file for the consolidated, skill-resident reference; fall back to the live docs whenever a model launch or breaking change may have shifted the picture.

This file is large. Use the section names below to jump (or Grep this file for the heading text). Read Step 0 and Step 1 first — they apply to every migration. Then read only the per-target section for the model you are migrating to.

Section When you need it
Step 0: Confirm the migration scope Always — before any edits
Step 1: Classify each file Always — decides whether to swap, add-alongside, or skip
Per-SDK Syntax Reference Translate the Python examples in this guide to TypeScript / Go / Ruby / Java / C# / PHP
Destination Models / Retired Model Replacements Picking a target model
Breaking Changes by Source Model Migrating to Opus 4.6 / Sonnet 4.6
Migrating to Opus 4.7 Migrating to Opus 4.7 (breaking changes, silent defaults, behavioral shifts)
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 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)
Claude Fable 5 Migration Checklist The required vs optional items for Claude Fable 5, tagged [BLOCKS] / [TUNE]
Verify the Migration After edits — runtime spot-check

TL;DR: Change the model ID string. If you were using budget_tokens, switch to thinking: {type: "adaptive"}. If you were using assistant prefills, they 400 on both Opus 4.6 and Sonnet 4.6 — switch to one of the prefill replacements (most often output_config.format; see the table in Breaking Changes by Source Model). If you're moving from Sonnet 4.5 to Sonnet 4.6, set effort explicitly — 4.6 defaults to high. Remove the effort-2025-11-24 and fine-grained-tool-streaming-2025-05-14 beta headers (GA on 4.6); remove interleaved-thinking-2025-05-14 once you're on adaptive thinking (keep it only while using the transitional budget_tokens escape hatch). Then drop back from client.beta.messages.create to client.messages.create. Dial back any aggressive "CRITICAL: YOU MUST" tool instructions; 4.6 follows the system prompt much more closely.

Step 0: Confirm the migration scope

Before any Write, Edit, or MultiEdit call, confirm the scope. If the user's request does not explicitly name a single file, a specific directory, or an explicit file list, ask first — do not start editing. This is non-negotiable: even imperative-sounding requests like "migrate my codebase", "move my project to X", "upgrade to Sonnet 4.6", or bare "migrate to Opus 4.7" leave the scope ambiguous and require a clarifying question. Phrases like "my project", "my code", "my codebase", "the whole thing", "everywhere", or "across the repo" are ambiguous, not directive — they tell you what to do but not where. Ask before doing.

Offer the common scopes explicitly and wait for the answer before touching any file:

  1. The entire working directory
  2. A specific subdirectory (e.g. src/, app/, services/billing/)
  3. A specific file or a list of files

Surface this as a single clarifying question so the user can answer in one turn. Proceed without asking only when the scope is already unambiguous — the user named an exact file ("migrate extract.py to Sonnet 4.6"), pointed at a specific directory ("migrate everything under services/billing/ to Opus 4.6"), listed specific files ("update a.py and b.py"), or already answered the scope question in an earlier turn. If you can answer the question "which files is this change going to touch?" with a precise list from the prompt alone, proceed. If not, ask.

Worked example. If the user says "Move my project to Opus 4.6. I want adaptive thinking everywhere it makes sense." you do not know whether "my project" means the whole working directory, just src/, just the production code, or something else — the everywhere makes the intent clear (update every call site within scope) but the scope itself is still not defined. Do not start editing. Respond with:

Before I start editing, can you confirm the scope? I can migrate: 1. Every .py file in the working directory 2. Just the files under src/ (production code) 3. A specific subdirectory or list of files you name

Which one?

Then wait for the answer. The same applies to "Migrate to Opus 4.7" and bare "Help me upgrade to Sonnet 4.6" — ask before editing.

Sizing the scope question (large repos). Before asking, get a per-directory count so the user can pick concretely:

rg -l "<old-model-id>" --type-not md | cut -d/ -f1 | sort | uniq -c | sort -rn

Present the breakdown in your scope question (e.g. "Found 217 references across 3 directories: api/ (130), api-go/ (62), routing/ (25). Which to migrate?"). Also confirm git status is clean before surveying — unexpected modifications mean a concurrent process; stop and investigate before proceeding.

Step 1: Classify each file

Not every file that contains the old model ID is a caller of the API. Before editing, classify each file into one of these buckets — the right action differs:

# Bucket What it looks like Action
1 Calls the API/SDK client.messages.create(model=…), anthropic.Anthropic(), request payloads Swap the model ID and apply the breaking-change checklist for the target version (below).
2 Defines or serves the model Model registries, OpenAPI specs, routing/queue configs, model-policy enums, generated catalogs The old entry stays (the model is still served). Ask whether to (a) add the new model alongside, (b) leave alone, or (c) retire the old model — never blind-replace. If you can't ask, default to (a): add the new model alongside and flag it — replacing would de-register a model that's still in production.
3 References the ID as an opaque string UI fallback constants, capability-gate substring checks, generic test fixtures, label parsers, env defaults Usually swap the string and verify any parser/regex/substring match handles the new ID — but check the sub-cases below first.
4 Suffixed variant ID claude-<model>-<suffix> like -fast, -1024k, -200k, [1m], dated snapshots These are deployment/routing identifiers, not the public model ID. Do not assume a new-model equivalent exists. Verify in the registry first; if absent, leave the string alone and flag it. Exception: -fast strings (e.g. claude-opus-4-6-fast) are handled by the Fast Mode section below, which rewrites them to Opus 4.8 plus speed="fast" and the fast-mode-2026-02-01 beta rather than leaving them in place.

Bucket 3 sub-cases — before swapping a string reference, check:

  • Capability gate (e.g. if 'opus-4-6' in model_id: enables a feature) → add the new ID alongside, don't replace. The old model is still served and still has the capability, so replacing would silently disable the feature for any old-model traffic that still flows through. If you know no old-model traffic will hit this gate (single-caller codebase fully migrating), replacing is fine; if unsure, add alongside.
  • Registry-assert test (e.g. assert "claude-X" in supported_models, test_X_has_N_clusters) → add an assertion for the new model alongside; keep the old one. The old model is still served, so its assertion stays valid — but the registry should also include the new model, so assert that too. Heuristic: if the test references multiple model versions in a list, it's a registry test; if one model in a struct compared only to itself, it's a generic fixture.
  • Frozen / generated snapshot → regenerate, don't hand-edit.
  • Coupled to a definer (e.g. an integration test that passes model authorization via a shared conftest seed list, or asserts on a billing-tier / rate-limit-group enum or a generated SKU/pricing catalog) → verify the definer has a new-model entry first. If not, add a seed entry (reusing the nearest existing tier as a placeholder); if you can't confidently do that, ask the user how to populate the definer. Do not skip the test. Swapping without populating the definer will make the test fail at runtime.

When migrating tests specifically: breaking parameters (temperature, top_p, budget_tokens) are usually absent — test fixtures rarely set sampling params on placeholder models. The breaking-change scan is still required, but expect mostly clean results.

Find intentionally-flagged sync points first. Many codebases tag spots that must change at every model launch with comment markers like MODEL LAUNCH, KEEP IN SYNC, @model-update, or similar. Grep for whatever convention the repo uses before the broad model-ID grep — those markers point at the load-bearing changes.

Per-SDK Syntax Reference

Code examples in this guide are Python. The same fields exist in every official Anthropic SDK — Stainless generates all 7 from the same OpenAPI spec, so JSON field names map 1:1 with only case-convention differences. Use the rows below to translate the Python examples to the SDK you are migrating.

Verify type and method names against the SDK source before writing them into customer code. WebFetch the relevant repository from the SDK source-code table in shared/live-sources.md (one row per SDK) and confirm the exact symbol — particularly for typed SDKs (Go, Java, C#) where union/builder names can differ from the JSON shape. Do not guess type names that aren't in the table below or in <lang>/claude-api/README.md.

thinking — budget_tokens → adaptive

SDK Before After
Python thinking={"type": "enabled", "budget_tokens": N} thinking={"type": "adaptive"}
TypeScript thinking: { type: 'enabled', budget_tokens: N } thinking: { type: 'adaptive' }
Go Thinking: anthropic.ThinkingConfigParamOfEnabled(N) Thinking: anthropic.ThinkingConfigParamUnion{OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{}}
Ruby thinking: { type: "enabled", budget_tokens: N } thinking: { type: "adaptive" }
Java .thinking(ThinkingConfigEnabled.builder().budgetTokens(N).build()) .thinking(ThinkingConfigAdaptive.builder().build())
C# Thinking = new ThinkingConfigEnabled { BudgetTokens = N } Thinking = new ThinkingConfigAdaptive()
PHP thinking: ['type' => 'enabled', 'budget_tokens' => N] thinking: ['type' => 'adaptive']

Sampling parameters — temperature / top_p / top_k

(Remove the field entirely on Opus 4.7; on Claude 4.x keep at most one of temperature or top_p.)

SDK Field(s) to remove
Python temperature=…, top_p=…, top_k=…
TypeScript temperature: …, top_p: …, top_k: …
Go Temperature: anthropic.Float(…), TopP: anthropic.Float(…), TopK: anthropic.Int(…)
Ruby temperature: …, top_p: …, top_k: …
Java .temperature(…), .topP(…), .topK(…)
C# Temperature = …, TopP = …, TopK = …
PHP temperature: …, topP: …, topK: …

Prefill replacement — structured outputs via output_config.format

SDK Remove (last assistant turn) Add
Python {"role": "assistant", "content": "…"} output_config={"format": {"type": "json_schema", "schema": SCHEMA}}
TypeScript { role: 'assistant', content: '…' } output_config: { format: { type: 'json_schema', schema: SCHEMA } }
Go trailing anthropic.MessageParam{Role: "assistant", …} OutputConfig: anthropic.OutputConfigParam{Format: anthropic.JSONOutputFormatParam{…}}
Ruby { role: "assistant", content: "…" } output_config: { format: { type: "json_schema", schema: SCHEMA } }
Java trailing Message.builder().role(ASSISTANT)… .outputConfig(OutputConfig.builder().format(JsonOutputFormat.builder()…build()).build())
C# trailing new Message { Role = "assistant", … } OutputConfig = new OutputConfig { Format = new JsonOutputFormat { … } }
PHP trailing ['role' => 'assistant', 'content' => '…'] outputConfig: ['format' => ['type' => 'json_schema', 'schema' => $SCHEMA]]

thinking.display — opt back into summarized reasoning (Opus 4.7)

SDK Add
Python thinking={"type": "adaptive", "display": "summarized"}
TypeScript thinking: { type: 'adaptive', display: 'summarized' }
Go Thinking: anthropic.ThinkingConfigParamUnion{OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{Display: anthropic.ThinkingConfigAdaptiveDisplaySummarized}}
Ruby thinking: { type: "adaptive", display: "summarized" } (or display_: when constructing the model class directly)
Java .thinking(ThinkingConfigAdaptive.builder().display(ThinkingConfigAdaptive.Display.SUMMARIZED).build())
C# Thinking = new ThinkingConfigAdaptive { Display = Display.Summarized }
PHP thinking: ['type' => 'adaptive', 'display' => 'summarized']

For any field not in these tables, the JSON key in the Python example translates directly: snake_case for Python/TypeScript/Ruby, camelCase named args for PHP, PascalCase struct fields for Go/C#, camelCase builder methods for Java.

Explain every change you make

Migration edits often look arbitrary to a user who hasn't read the release notes — a removed temperature, a deleted prefill, a rewritten system-prompt sentence. For each edit, tell the user what you changed and why, tied to the specific API or behavioral change that motivates it. Do this in your summary as you work, not just at the end.

Be especially explicit about system-prompt edits. Users are rightly protective of their prompts, and prompt-tuning changes are judgment calls (not hard API requirements). For any prompt edit:

  • Quote the before and after text.
  • State the behavioral shift that motivates it (e.g. "Opus 4.7 calibrates response length to task complexity, so I added an explicit length instruction", or "4.6 follows instructions more literally, so 'CRITICAL: YOU MUST use the search tool' will now overtrigger — softened to 'Use the search tool when…'").
  • Make clear which prompt edits are optional tuning (tone, length, subagent guidance) versus which code edits are required to avoid a 400 (sampling params, budget_tokens, prefills). Never present an optional prompt change as mandatory.

If you're applying several prompt-tuning edits at once, offer them as a short list the user can accept or decline item-by-item rather than silently rewriting their system prompt.

Before You Migrate

  1. Confirm the target model ID. Use only the exact strings from shared/models.md — do not append date suffixes to aliases (claude-opus-4-6, not claude-opus-4-6-20251101). Guessing an ID will 404.
  2. Check which features your code uses with this checklist:
  3. thinking: {type: "enabled", budget_tokens: N} → migrate to adaptive thinking on Opus 4.6 / Sonnet 4.6 (still functional but deprecated)
  4. Assistant-turn prefills (messages ending with role: "assistant") → must change on Opus 4.6 / Sonnet 4.6 (returns 400)
  5. output_format parameter on messages.create() → must change on all models (deprecated API-wide)
  6. max_tokens > ~16000 → must stream on any model (above ~16K risks SDK HTTP timeouts). When streaming, every current model reaches 128K except Haiku 4.5, which caps at 64K
  7. Beta headers effort-2025-11-24, fine-grained-tool-streaming-2025-05-14, interleaved-thinking-2025-05-14 → GA on 4.6, remove them and switch from client.beta.messages.create to client.messages.create
  8. Moving Sonnet 4.5 → Sonnet 4.6 with no effort set → 4.6 defaults to high, which may change your latency/cost profile
  9. System prompts with CRITICAL, MUST, If in doubt, use X language → likely to overtrigger on 4.6 (see Prompt-Behavior Changes)
  10. Coming from 3.x / 4.0 / 4.1: also check sampling params (temperature + top_p), tool versions (text_editor_20250728), refusal + model_context_window_exceeded stop reasons, trailing-newline tool-param handling
  11. Test on a single request first. Run one call against the new model, inspect the response, then roll out.

Destination Models (recommended targets)

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)
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

Default to the latest Opus for the caller's tier unless they explicitly chose otherwise. The Opus migrations layer: if you're on Opus 4.6 or older, apply each version's section in order up to your target (e.g. 4.5 → 4.8 means the 4.6, 4.7, and 4.8 sections in sequence). A 4.7 → 4.8 move has no new breaking changes — see Migrating to Opus 4.8 below.

Retired Model Replacements

These models return 404 — update immediately:

Retired model Retired Drop-in replacement
claude-3-7-sonnet-20250219 Feb 19, 2026 claude-sonnet-5
claude-3-5-haiku-20241022 Feb 19, 2026 claude-haiku-4-5
claude-3-opus-20240229 Jan 5, 2026 claude-opus-4-8
claude-3-5-sonnet-20241022 Oct 28, 2025 claude-sonnet-5
claude-3-5-sonnet-20240620 Oct 28, 2025 claude-sonnet-5
claude-3-sonnet-20240229 Jul 21, 2025 claude-sonnet-5
claude-2.1, claude-2.0 Jul 21, 2025 claude-sonnet-5

Deprecated Models (retiring soon)

Model Retires Replacement
claude-3-haiku-20240307 Apr 19, 2026 claude-haiku-4-5
claude-opus-4-20250514 June 15, 2026 claude-opus-4-8
claude-sonnet-4-20250514 June 15, 2026 claude-sonnet-5

Breaking Changes by Source Model

Migrating from Sonnet 4.5 to Sonnet 4.6 (effort default change)

Sonnet 4.5 had no effort parameter; Sonnet 4.6 defaults to high. If you just switch the model string and do nothing else, you may see noticeably higher latency and token usage. Set effort explicitly.

Recommended starting points:

Workload Start at Notes
Chat, classification, content generation low With thinking: {"type": "disabled"} you'll see similar or better performance vs. Sonnet 4.5 no-thinking
Most applications (balanced) medium The default sweet spot for quality vs. cost
Agentic coding, tool-heavy workflows medium Pair with adaptive thinking and a generous max_tokens (up to 128K with streaming — Sonnet 4.6's ceiling)
Autonomous multi-step agents, long-horizon loops high Scale down to medium if latency/tokens become a concern
Computer-use agents high + adaptive Sonnet 4.6's best computer-use accuracy is on adaptive + high

For non-thinking chat workloads specifically:

client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=8192,
    thinking={"type": "disabled"},
    output_config={"effort": "low"},
    messages=[{"role": "user", "content": "..."}],
)

When to use Opus 4.6 instead: hardest and longest-horizon problems — large code migrations, deep research, extended autonomous work. Sonnet 4.6 wins on fast turnaround and cost efficiency.

Migrating to Opus 4.6 / Sonnet 4.6 (from any older model)

1. Manual extended thinking is deprecated — use adaptive thinking.

thinking: {type: "enabled", budget_tokens: N} (manual extended thinking with a fixed token budget) is deprecated on Opus 4.6 and Sonnet 4.6. Replace it with thinking: {type: "adaptive"}, which lets Claude decide when and how much to think. Adaptive thinking also enables interleaved thinking automatically (no beta header needed).

# Old (still works on older models, deprecated on 4.6)
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 8000},
    messages=[...]
)

# New (Opus 4.6 / Sonnet 4.6)
response = client.messages.create(
    model="claude-opus-4-6",  # or "claude-sonnet-4-6"
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # optional: low | medium | high | max
    messages=[...]
)

Adaptive thinking is the long-term target, and on internal evaluations it outperforms manual extended thinking. Move when you can.

Transitional escape hatch: manual extended thinking is still functional on Opus 4.6 and Sonnet 4.6 (deprecated, will be removed in a future release). If you need a hard ceiling while migrating — for example, to bound token spend on a runaway workload before you've tuned effort — you can keep budget_tokens around alongside an explicit effort value, then remove it in a follow-up. budget_tokens must be strictly less than max_tokens:

# Transitional only — deprecated, plan to remove
client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16384,
    thinking={"type": "enabled", "budget_tokens": 8192},  # must be < max_tokens
    output_config={"effort": "medium"},
    messages=[...],
)

If the user asks for a "thinking budget" on 4.6, the preferred answer is effort — use low, medium, high, or max rather than a token count.

2. Effort parameter (Opus 4.5, Opus 4.6, Sonnet 4.6 only).

Controls thinking depth and overall token spend. Goes inside output_config, not top-level. Default is high. max is supported on Fable 5, Opus 4.6 and later, Sonnet 5, and Sonnet 4.6 — it errors on Sonnet 4.5 and Haiku 4.5.

output_config={"effort": "medium"}  # often the best cost / quality balance

Migrating to the 4.6 family (Opus 4.6 and Sonnet 4.6)

3. Assistant-turn prefills return 400 (Opus 4.6 and Sonnet 4.6).

Prefilled responses on the final assistant turn are no longer supported on either Opus 4.6 or Sonnet 4.6 — both return a 400. Adding assistant messages elsewhere in the conversation (e.g., for few-shot examples) still works. Pick the replacement that matches what the prefill was doing:

Prefill was used for Replacement
Forcing JSON / YAML / schema output output_config.format with a json_schema — see example below
Forcing a classification label Tool with an enum field containing valid labels, or structured outputs
Skipping preambles (Here is the summary:\n) System prompt instruction: "Respond directly without preamble. Do not start with phrases like 'Here is...' or 'Based on...'."
Steering around bad refusals Usually no longer needed — 4.6 refuses far more appropriately. Plain user-turn prompting is sufficient.
Continuing an interrupted response Move continuation into the user turn: "Your previous response was interrupted and ended with [last text]. Continue from there."
Injecting reminders / context hydration Inject into the user turn instead. For complex agent harnesses, expose context via a tool call or during compaction. 
# Old (fails on Opus 4.6 / Sonnet 4.6) — prefill forcing JSON shape
messages=[
    {"role": "user", "content": "Extract the name."},
    {"role": "assistant", "content": "{\"name\": \""},
]

# New — structured outputs replace the prefill
response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    output_config={"format": {"type": "json_schema", "schema": {...}}},
    messages=[{"role": "user", "content": "Extract the name."}],
)

4. Stream for max_tokens > ~16K (all models); only Haiku 4.5 caps lower, at 64K.

Non-streaming requests hit SDK HTTP timeouts at high max_tokens, regardless of model — stream for anything above ~16K output. The streamable ceiling is 128K for every current model except Haiku 4.5, which caps at 64K.

with client.messages.stream(model="claude-opus-4-6", max_tokens=64000, ...) as stream:
    message = stream.get_final_message()

5. Tool-call JSON escaping may differ (Opus 4.6 and Sonnet 4.6).

Both 4.6 models can produce tool call input fields with Unicode or forward-slash escaping. Always parse with json.loads() / JSON.parse() — never raw-string-match the serialized input.

All models

6. output_format → output_config.format (API-wide).

The old top-level output_format parameter on messages.create() is deprecated. Use output_config.format instead. This is not 4.6-specific — applies to every model.

Beta Headers to Remove on 4.6

Several beta headers that were required on 4.5 are now GA on 4.6 and should be removed. Leaving them in is harmless but misleading; removing them also lets you move from client.beta.messages.create(...) back to client.messages.create(...).

Header Status on 4.6 Action
effort-2025-11-24 Effort parameter is GA Remove
fine-grained-tool-streaming-2025-05-14 GA Remove
interleaved-thinking-2025-05-14 Adaptive thinking enables interleaved thinking automatically Remove when using adaptive thinking; still functional on Sonnet 4.6 with manual extended thinking, but that path is deprecated
token-efficient-tools-2025-02-19 Built in to all Claude 4+ models Remove (no effect)
output-128k-2025-02-19 Built in to Claude 4+ models Remove (no effect)

Once you remove all of these and finish moving to adaptive thinking, you can switch the SDK call site from the beta namespace back to the regular one:

# Before
response = client.beta.messages.create(
    model="claude-opus-4-5",
    betas=["interleaved-thinking-2025-05-14", "effort-2025-11-24"],
    ...
)

# After
response = client.messages.create(
    model="claude-opus-4-6",
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},
    ...
)

Additional Changes When Coming from 3.x / 4.0 / 4.1 → 4.6

If you're jumping from Opus 4.1, Sonnet 4, Sonnet 3.7, or an older Claude 3.x model directly to 4.6, apply everything above plus the items in this section. Users already on Opus 4.5 / Sonnet 4.5 can skip this.

1. Sampling parameters: temperature OR top_p, not both.

Passing both will error on every Claude 4+ model:

# Old (3.x only — errors on 4+)
client.messages.create(temperature=0.7, top_p=0.9, ...)

# New
client.messages.create(temperature=0.7, ...)  # or top_p, not both

2. Update tool versions.

Legacy tool versions are not supported on 4+. Both the type and the name field change — text_editor_20250728 and str_replace_based_edit_tool are a pair; updating one without the other 400s. Also remove the undo_edit command from your text-editor integration:

Old New
text_editor_20250124 + str_replace_editor text_editor_20250728 + str_replace_based_edit_tool
code_execution_* (earlier versions) code_execution_20260521
undo_edit command (no longer supported — delete call sites) 
# Before
tools = [{"type": "text_editor_20250124", "name": "str_replace_editor"}]

# After — BOTH fields change
tools = [{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]

3. Handle the refusal stop reason.

Claude 4+ can return stop_reason: "refusal" on the response. If your code only handles end_turn / tool_use / max_tokens, add a branch:

if response.stop_reason == "refusal":
    # Surface the refusal to the user; do not retry with the same prompt
    ...

4. Handle the model_context_window_exceeded stop reason (4.5+).

Distinct from max_tokens: it means the model hit the context window limit, not the requested output cap. Handle both:

if response.stop_reason == "model_context_window_exceeded":
    # Context window exhausted — compact or split the conversation
    ...
elif response.stop_reason == "max_tokens":
    # Requested output cap hit — retry with higher max_tokens or stream
    ...

5. Trailing newlines preserved in tool call string parameters (4.5+).

4.5 and 4.6 preserve trailing newlines that older models stripped. If your tool implementations do exact string matching against tool-call input values (e.g., if name == "foo"), verify they still match when the model sends "foo\n". Normalizing with .rstrip() on the receiving side is usually the simplest fix.

6. Haiku: rate limits reset between generations.

Haiku 4.5 has its own rate-limit pool separate from Haiku 3 / 3.5. If you're ramping traffic as you migrate, check your tier's Haiku 4.5 limits at API rate limits — a quota that comfortably served Haiku 3.5 traffic may need a tier bump for the same volume on 4.5.

Prompt-Behavior Changes (Opus 4.5 / 4.6, Sonnet 4.6)

These don't break your code, but prompts that worked on 4.5-and-earlier may over- or under-trigger on 4.6. Tune as needed.

1. Aggressive instructions cause overtriggering. Opus 4.5 and 4.6 follow the system prompt much more closely than earlier models. Prompts written to overcome the old reluctance are now too aggressive:

Before (worked on 4.0 / 4.5) After (use on 4.6)
CRITICAL: You MUST use this tool when... Use this tool when...
Default to using [tool] Use [tool] when it would improve X
If in doubt, use [tool] (delete — no longer needed)

If the model is now overtriggering a tool or skill, the fix is almost always to dial back the language, not to add more guardrails.

2. Overthinking and excessive exploration (Opus 4.6). At higher effort settings, Opus 4.6 explores more before answering. If that burns too many thinking tokens, lower effort first (medium is often the sweet spot) before adding prose instructions to constrain reasoning.

3. Overeager subagent spawning (Opus 4.6). Opus 4.6 has a strong preference for delegating to subagents. If you see it spawning a subagent for something a direct grep or read would solve, add guidance: "Use subagents only for parallel or independent workstreams. For single-file reads or sequential operations, work directly."

4. Overengineering (Opus 4.5 / 4.6). Both models may add extra files, abstractions, or defensive error handling beyond what was asked. If you want minimal changes, prompt for it explicitly: "Only make changes directly requested. Don't add helpers, abstractions, or error handling for scenarios that can't happen."

5. LaTeX math output (Opus 4.6). Opus 4.6 defaults to LaTeX (\frac{}{}, $...$) for math and technical content. If you need plain text, instruct it explicitly: "Format all math as plain text — no LaTeX, no $, no \frac{}{}. Use / for division and ^ for exponents."

6. Skipped verbal summaries (4.6 family). The 4.6 models are more concise and may skip the summary paragraph after a tool call, jumping straight to the next action. If you rely on those summaries for visibility, add: "After completing a task that involves tool use, provide a brief summary of what you did."

7. "Think" as a trigger word (Opus 4.5 with thinking disabled). When thinking is off, Opus 4.5 is particularly sensitive to the word think and may reason more than you want. Use consider, evaluate, or reason through instead.

Model-ID Rename Quick Reference

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-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
claude-sonnet-4-0 claude-sonnet-5

Older aliases (claude-opus-4-7, claude-opus-4-6, claude-opus-4-5, claude-sonnet-4-6, claude-sonnet-4-5, etc.) are still active and can be pinned if you need time before upgrading — see shared/models.md for the full legacy list.

Amazon Bedrock model IDs

If the code uses the AnthropicBedrockMantle client (Python anthropic[bedrock], TypeScript @anthropic-ai/bedrock-sdk, Java BedrockMantleBackend, Go bedrock.NewMantleClient, etc.) or targets https://bedrock-mantle.{region}.api.aws/anthropic, it is running on Claude in Amazon Bedrock. All breaking changes in this guide apply unchanged there — it serves the same Messages API shape — but model IDs carry an anthropic. provider prefix:

First-party ID Bedrock ID
claude-opus-4-8 anthropic.claude-opus-4-8
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

When migrating a Bedrock file, apply the same rename-table row as first-party, then keep/add the anthropic. prefix. Do not generate a first-party claude-* ID for a Bedrock client — it will 400.

Skip for Bedrock: the code_execution_* tool-version checklist item and the Task Budgets section — neither is available on Bedrock (see shared/platform-availability.md for the per-feature table). Everything else in this guide — effort, adaptive/extended thinking, output_config.format, thinking.display, fine-grained tool streaming, token counting — is available on Bedrock.

Out of scope: the legacy Amazon Bedrock integration (InvokeModel / Converse APIs with ARN-versioned IDs like anthropic.claude-3-5-sonnet-20241022-v2:0) uses a different request shape and model-ID format. This guide does not cover it; WebFetch the Bedrock page in shared/live-sources.md if the user is migrating between the two Bedrock integrations.

Claude Platform on AWS

If the code uses AnthropicAWS / AnthropicAws / anthropicaws.NewClient / AnthropicAwsClient (or targets https://aws-external-anthropic.{region}.api.aws), it is running on Claude Platform on AWS — Anthropic-operated, same-day API parity. Model IDs are bare first-party strings; apply the rename table above verbatim and every breaking-change section in this guide unchanged. There is nothing to skip. Do not add an anthropic. prefix (that's Amazon Bedrock, a separate offering). See shared/claude-platform-on-aws.md for client/auth details.

Migration Checklist

Every item is tagged: [BLOCKS] items cause a 400 error, infinite loop, silent timeout, or wrong tool selection if missed — apply these as code edits, not as suggestions. [TUNE] items are quality/cost adjustments.

For each file that calls messages.create() / equivalent SDK method:

  • [ ] [BLOCKS] Update the model= string to the new alias
  • [ ] [BLOCKS] Replace budget_tokens with thinking={"type": "adaptive"} (deprecated on Opus 4.6 / Sonnet 4.6)
  • [ ] [BLOCKS] Move format from top-level output_format into output_config.format
  • [ ] [BLOCKS] Remove any assistant-turn prefills if targeting Opus 4.6 or Sonnet 4.6 (see the prefill replacement table)
  • [ ] [BLOCKS] Switch to streaming if max_tokens > ~16000 (otherwise SDK HTTP timeout)
  • [ ] [TUNE] Verify tool-input handling parses JSON rather than raw-string-matching the serialized input (4.6 may escape Unicode / forward slashes differently; most SDKs already expose block.input as a parsed object)
  • [ ] [TUNE] Set output_config={"effort": "..."} explicitly — especially when moving Sonnet 4.5 → Sonnet 4.6 (4.6 defaults to high)
  • [ ] [TUNE] Remove GA beta headers: effort-2025-11-24, fine-grained-tool-streaming-2025-05-14, token-efficient-tools-2025-02-19, output-128k-2025-02-19; remove interleaved-thinking-2025-05-14 once on adaptive thinking
  • [ ] [TUNE] Switch client.beta.messages.create(...) → client.messages.create(...) once all betas are removed
  • [ ] [TUNE] Review system prompt for aggressive tool language (CRITICAL:, MUST, If in doubt) and dial it back

Extra items when coming from 3.x / 4.0 / 4.1: - [ ] [BLOCKS] Remove either temperature or top_p (passing both 400s on Claude 4+) - [ ] [BLOCKS] Update text-editor tool type to text_editor_20250728 - [ ] [BLOCKS] Update text-editor tool name to str_replace_based_edit_tool — changing only the type and keeping name: "str_replace_editor" returns a 400 - [ ] [BLOCKS] Update code-execution tool to code_execution_20260521 - [ ] [BLOCKS] Delete any undo_edit command call sites - [ ] [TUNE] Add handling for stop_reason == "refusal" - [ ] [TUNE] Add handling for stop_reason == "model_context_window_exceeded" (4.5+) - [ ] [TUNE] Verify tool-param string matching tolerates trailing newlines (preserved on 4.5+) - [ ] [TUNE] If moving to Haiku 4.5: review rate-limit tier (separate pool from Haiku 3.x)

Verification: - [ ] Run one test request and inspect response.stop_reason, response.usage, and whether tool-use / thinking behavior matches expectations

For cached prompts: the render order and hash inputs did not change, so existing cache_control breakpoints keep working. However, changing the model string invalidates the existing cache — the first request on the new model will write the cache fresh.

Migrating to Opus 4.7

Model ID claude-opus-4-7 is authoritative as written here. When the user asks to migrate to Opus 4.7, write model="claude-opus-4-7" 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 4.7 was Anthropic's most capable model at its launch and is now the previous-generation Opus (Opus 4.8 is current — see Migrating to Opus 4.8 below). It is highly autonomous and performs exceptionally well on long-horizon agentic work, knowledge work, vision tasks, and memory tasks. This section summarizes everything that was new at the 4.7 launch and remains the layered breaking-change path for callers coming from Opus 4.6 or older. It is layered on top of the 4.6 migration above — if the caller is jumping from Opus 4.5 or older, apply the 4.6 changes first, then this section, then the 4.8 section.

TL;DR for someone already on Opus 4.6: update the model ID to claude-opus-4-7, strip any remaining budget_tokens and sampling parameters (both 400 on Opus 4.7), give max_tokens extra headroom and re-baseline with count_tokens() against the new model, opt back into thinking.display: "summarized" if reasoning is surfaced to users, and re-tune effort — it matters more on 4.7 than on any prior Opus.

Breaking changes (will 400 on Opus 4.7)

Extended thinking removed.

thinking: {type: "enabled", budget_tokens: N} is no longer supported on Claude Opus 4.7 or later models and returns a 400 error. Switch to adaptive thinking (thinking: {type: "adaptive"}) and use the effort parameter to control thinking depth. Adaptive thinking is off by default on Claude Opus 4.7: requests with no thinking field run without thinking, matching Opus 4.6 behavior. Set thinking: {type: "adaptive"} explicitly to enable it.

# Before (Opus 4.6)
client.messages.create(
    model="claude-opus-4-6",
    max_tokens=64000,
    thinking={"type": "enabled", "budget_tokens": 32000},
    messages=[{"role": "user", "content": "..."}],
)

# After (Opus 4.7)
client.messages.create(
    model="claude-opus-4-7",
    max_tokens=64000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # or "max", "xhigh", "medium", "low"
    messages=[{"role": "user", "content": "..."}],
)

If the caller wasn't using extended thinking, no change is required — thinking is off by default, or can be set explicitly with thinking={"type": "disabled"}.

Delete budget_tokens plumbing entirely. For the replacement effort value, see Choosing an effort level on Opus 4.7 below — there is no exact 1:1 mapping from budget_tokens.

Sampling parameters removed.

The temperature, top_p, and top_k parameters are no longer accepted on Claude Opus 4.7. Requests that include them return a 400 error. Remove these fields from your request payloads. Prompting is the recommended way to guide model behavior on Claude Opus 4.7. If you were using temperature = 0 for determinism, note that it never guaranteed identical outputs on prior models.

# Before — errors on Opus 4.7
client.messages.create(temperature=0.7, top_p=0.9, ...)

# After
client.messages.create(...)  # no sampling params
  • If the intent was determinism — use effort: "low" with a tighter prompt.
  • If the intent was creative variance — the prompt replacement depends on the use case; ask the user how they want variance elicited. If you can't ask, add a use-case-appropriate instruction along the lines of "choose something off-distribution and interesting" — e.g. for text generation, "Vary your phrasing and structure across responses"; for frontend/design, use the propose-4-directions approach under Design and frontend coding below.

Choosing an effort level on Opus 4.7

budget_tokens controlled how much to think; effort controls how much to think and act, so there is no exact 1:1 mapping. Use xhigh for best results in coding and agentic use cases, and a minimum of high for most intelligence-sensitive use cases. Experiment with other levels to further tune token usage and intelligence:

Level Use when Notes
max Intelligence-demanding tasks worth testing at the ceiling Can deliver gains in some use cases but may show diminishing returns from increased token usage; can be prone to overthinking
xhigh Most coding and agentic use cases The best setting for these; used as the default in Claude Code
high Intelligence-sensitive use cases generally Balances token usage and intelligence; recommended minimum for most intelligence-sensitive work
medium Cost-sensitive use cases that need to reduce token usage while trading off intelligence
low Short, scoped tasks and latency-sensitive workloads that are not intelligence-sensitive

Silent default changes (no error, but behavior differs)

Thinking content omitted by default.

Thinking blocks still appear in the response stream on Claude Opus 4.7, but their thinking field is empty unless you explicitly opt in. This is a silent change from Claude Opus 4.6, where the default was to return summarized thinking text. To restore summarized thinking content on Claude Opus 4.7, set thinking.display to "summarized". The block-field name is unchanged — it is still block.thinking on a thinking-type block; do not rename it.

Detect this: any code that reads block.thinking (or equivalent) from a thinking-type block and renders it in a UI, log, or trace. The fix is the request parameter, not the response handling — add display: "summarized" to the thinking parameter:

thinking={"type": "adaptive", "display": "summarized"}  # "display" is new on Opus 4.7; values: "omitted" (default) | "summarized"

The default is "omitted" on Claude Opus 4.7. If thinking content was never surfaced anywhere, no change needed. If your product streams reasoning to users, the new default appears as a long pause before output begins; set display: "summarized" to restore visible progress during thinking.

Updated token counting.

Claude Opus 4.7 and Claude Opus 4.6 count tokens differently. The same input text produces a higher token count on Claude Opus 4.7 than on Claude Opus 4.6, and /v1/messages/count_tokens will return a different number of tokens for Claude Opus 4.7 than it did for Claude Opus 4.6. The token efficiency of Claude Opus 4.7 can vary by workload shape. Prompting interventions, task_budget, and effort can help control costs and ensure appropriate token usage. Keep in mind that these controls may trade off model intelligence. Update your max_tokens parameters to give additional headroom, including compaction triggers. Claude Opus 4.7 provides a 1M context window at standard API pricing with no long-context premium.

What else to check:

  • Client-side token estimators (tiktoken-style approximations) calibrated against 4.6
  • Cost calculators that multiply tokens by a fixed per-token rate
  • Rate-limit retry thresholds keyed to measured token counts

Re-baseline by re-running client.messages.count_tokens() against claude-opus-4-7 on a representative sample of the caller's prompts. Do not apply a blanket multiplier. For cost-sensitive workloads, consider reducing effort by one level (e.g. high → medium). For agentic loops, consider adopting Task Budgets (below).

New feature: Task Budgets (beta)

Opus 4.7 introduces task budgets — tell Claude how many tokens it has for a full agentic loop (thinking + tool calls + final output). The model sees a running countdown and uses it to prioritize work and wrap up gracefully as the budget is consumed.

This is a suggestion the model is aware of, not a hard cap. It is distinct from max_tokens, which remains the enforced per-response limit and is not surfaced to the model. Use task_budget when you want the model to self-moderate; use max_tokens as a hard ceiling to cap usage.

Requires beta header task-budgets-2026-03-13:

client.beta.messages.create(
    betas=["task-budgets-2026-03-13"],
    model="claude-opus-4-7",
    max_tokens=64000,
    thinking={"type": "adaptive"},
    output_config={
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 128000},
    },
    messages=[...],
)

Set a generous budget for open-ended agentic tasks and tighten it for latency-sensitive ones. Minimum task_budget.total is 20,000 tokens. If the budget is too restrictive for the task, the model may complete it less thoroughly, referencing its budget as the constraint. Do not add task_budget during a migration unless you are sure the budget value is right — if you can run the workload and measure, do so; otherwise ask the user for the value rather than guessing. This is the primary lever for offsetting the token-counting shift on agentic workloads.

Capability improvements

High-resolution vision. Opus 4.7 is the first Claude model with high-resolution image support. Maximum image resolution is 2576 pixels on the long edge (up from 1568px on Opus 4.6 and prior). This unlocks gains on vision-heavy workloads, especially computer use and screenshot/artifact/document understanding. Coordinates returned by the model now map 1:1 to actual image pixels, so no scale-factor math is needed.

High-res support is automatic on Opus 4.7 — no beta header, no client-side opt-in required. The model accepts larger inputs and returns pixel-accurate coordinates out of the box.

Token cost. Full-resolution images on Opus 4.7 can use up to ~3× more image tokens than on prior models (up to ~4784 tokens per image, vs. the previous ~1,600-token cap). If the extra fidelity isn't needed, downsample client-side before sending to control cost — but do not add downsampling by default during a migration. If you're not sure whether the pipeline needs the fidelity, ask the user rather than guessing. Use count_tokens() on representative images on Opus 4.7 to re-baseline before reacting to any measured cost shift.

Beyond resolution, Opus 4.7 also improves on low-level perception (pointing, measuring, counting) and natural-image bounding-box localization and detection.

Knowledge work. Meaningful gains on tasks where the model visually verifies its own output — .docx redlining, .pptx editing, and programmatic chart/figure analysis (e.g. pixel-level data transcription via image-processing libraries). If prompts have scaffolding like "double-check the slide layout before returning", try removing it and re-baselining.

Memory. Opus 4.7 is better at writing and using file-system-based memory. If an agent maintains a scratchpad, notes file, or structured memory store across turns, that agent should improve at jotting down notes to itself and leveraging its notes in future tasks.

User-facing progress updates. Opus 4.7 provides more regular, higher-quality interim updates during long agentic traces. If the system prompt has scaffolding like "After every 3 tool calls, summarize progress", try removing it to avoid excessive user-facing text. If the length or contents of Opus 4.7's updates are not well-calibrated to your use case, explicitly describe what these updates should look like in the prompt and provide examples.

Real-time cybersecurity safeguards

Requests that involve prohibited or high-risk topics may lead to refusals.

Fast Mode: Opus 4.8 / 4.7 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.

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:

# Request fast mode on Opus 4.8.
client.beta.messages.create(
    model="claude-opus-4-8", 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.

Behavioral shifts (prompt-tunable)

These don't break anything, but prompts tuned for Opus 4.6 may land differently. Opus 4.7 is more steerable than 4.6, so small prompt nudges usually close the gap.

More literal instruction following. Claude Opus 4.7 interprets prompts more literally and explicitly than Claude Opus 4.6, particularly at lower effort levels. It will not silently generalize an instruction from one item to another, and it will not infer requests you didn't make. The upside of this literalism is precision and less thrash. It generally performs better for API use cases with carefully tuned prompts, structured extraction, and pipelines where you want predictable behavior. A prompt and harness review may be especially helpful for migration to Claude Opus 4.7.

Verbosity calibrates to task complexity. Opus 4.7 scales response length to how complex it judges the task to be, rather than defaulting to a fixed verbosity — shorter answers on simple lookups, much longer on open-ended analysis. If the product depends on a particular length or style, tune the prompt explicitly. To reduce verbosity:

"Provide concise, focused responses. Skip non-essential context, and keep examples minimal."

If you see specific kinds of over-verbosity (e.g. over-explaining), add instructions targeting those. Positive examples showing the desired level of concision tend to be more effective than negative examples or instructions telling the model what not to do. Do not assume existing "be concise" instructions should be removed — test first.

Tone and writing style. Opus 4.7 is more direct and opinionated, with less validation-forward phrasing and fewer emoji than Opus 4.6's warmer style. As with any new model, prose style on long-form writing may shift. If the product relies on a specific voice, re-evaluate style prompts against the new baseline. If a warmer or more conversational voice is wanted, specify it:

"Use a warm, collaborative tone. Acknowledge the user's framing before answering."

effort matters more than on any prior Opus. Opus 4.7 respects effort levels more strictly, especially at the low end. At low and medium it scopes work to what was asked rather than going above and beyond — good for latency and cost, but on moderate tasks at low there is some risk of under-thinking.

  • If shallow reasoning shows up on complex problems, raise effort to high or xhigh rather than prompting around it.
  • If effort must stay low for latency, add targeted guidance: "This task involves multi-step reasoning. Think carefully through the problem before responding."
  • 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 from there. (xhigh is a new effort level on Opus 4.7, between high and max.)

Adaptive-thinking triggering is also steerable. If the model thinks more often than wanted — which can happen with large or complex system prompts — add: "Thinking adds latency and should only be used when it will meaningfully improve answer quality — typically for problems that require multi-step reasoning. When in doubt, respond directly."

Uses tools less often by default. Opus 4.7 tends to use tools less often than 4.6 and to use reasoning more. This produces better results in most cases, but for products that rely on tools (search/retrieval, function-calling, computer-use steps), it can drop tool-use rate. Two levers:

  • Raise effort — high or xhigh show substantially more tool usage in agentic search and coding, and are especially useful for knowledge work.
  • Prompt for it — be explicit in tool descriptions or the system prompt about when and how to use the tool, and encourage the model to err on the side of using it more often:

"When the answer depends on information not present in the conversation, you MUST call the search tool before answering — do not answer from prior knowledge."

Fewer subagents by default. Opus 4.7 tends to spawn fewer subagents than 4.6. This is steerable — give explicit guidance on when delegation is desirable. For a coding agent, for example:

"Do NOT spawn a subagent for work you can complete directly in a single response (e.g. refactoring a function you can already see). Spawn multiple subagents in the same turn when fanning out across items or reading multiple files."

Design and frontend coding. Opus 4.7 has stronger design instincts than 4.6, with a consistent default house style: warm cream/off-white backgrounds (around #F4F1EA), serif display type (Georgia, Fraunces, Playfair), italic word-accents, and a terracotta/amber accent. This reads well for editorial, hospitality, and portfolio briefs, but will feel off for dashboards, dev tools, fintech, healthcare, or enterprise apps — and it appears in slide decks as well as web UIs.

The default is persistent. Generic instructions ("don't use cream," "make it clean and minimal") tend to shift the model to a different fixed palette rather than producing variety. Two approaches work reliably:

  1. Specify a concrete alternative. The model follows explicit specs precisely — give exact hex values, typefaces, and layout constraints.
  2. Have the model propose options before building. This breaks the default and gives the user control:

"Before building, propose 4 distinct visual directions tailored to this brief (each as: bg hex / accent hex / typeface — one-line rationale). Ask the user to pick one, then implement only that direction."

If the caller previously relied on temperature for design variety, use approach (2) — it produces meaningfully different directions across runs.

Opus 4.7 also requires less frontend-design prompting than previous models to avoid generic "AI slop" aesthetics. Where earlier models needed a lengthy anti-slop snippet, Opus 4.7 generates distinctive, creative frontends with a much shorter nudge. This snippet works well alongside the variety approaches above:

"NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white or dark backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character. Use unique fonts, cohesive colors and themes, and animations for effects and micro-interactions."

Interactive coding products. Opus 4.7's token usage and behavior can differ between autonomous, asynchronous coding agents with a single user turn and interactive, synchronous coding agents with multiple user turns. Specifically, it tends to use more tokens in interactive settings, primarily because it reasons more after user turns. This can improve long-horizon coherence, instruction following, and coding capabilities in long interactive coding sessions, but also comes with more token usage. To maximize both performance and token efficiency in coding products, use effort: "xhigh" or "high", add autonomous features (like an auto mode), and reduce the number of human interactions required from users.

When limiting required user interactions, specify the task, intent, and relevant constraints upfront in the first human turn. Well-specified, clear, and accurate task descriptions upfront help maximize autonomy and intelligence while minimizing extra token usage after user turns — because Opus 4.7 is more autonomous than prior models, this usage pattern helps to maximize performance. In contrast, ambiguous or underspecified prompts conveyed progressively over multiple user turns tend to reduce token efficiency and sometimes performance.

Code review. Opus 4.7 is meaningfully better at finding bugs than prior models, with both higher recall and precision. However, if a code-review harness was tuned for an earlier model, it may initially show lower recall — this is likely a harness effect, not a capability regression. When a review prompt says "only report high-severity issues," "be conservative," or "don't nitpick," Opus 4.7 follows that instruction more faithfully than earlier models did: it investigates just as thoroughly, identifies the bugs, and then declines to report findings it judges to be below the stated bar. Precision rises, but measured recall can fall even though underlying bug-finding has improved.

Recommended prompt language:

"Report every issue you find, including ones you are uncertain about or consider low-severity. Do not filter for importance or confidence at this stage — a separate verification step will do that. Your goal here is coverage: it is better to surface a finding that later gets filtered out than to silently drop a bug. For each finding, include your confidence level and an estimated severity so a downstream filter can rank them."

This can be used without an actual second step, but moving confidence filtering out of the finding step often helps. If the harness has a separate verification/dedup/ranking stage, tell the model explicitly that its job at the finding stage is coverage, not filtering. If single-pass self-filtering is wanted, be concrete about the bar rather than using qualitative terms like "important" — e.g. "report any bugs that could cause incorrect behavior, a test failure, or a misleading result; only omit nits like pure style or naming preferences." Iterate on prompts against a subset of evals to validate recall or F1 gains.

Computer use. Computer use works across resolutions up to the new 2576px / 3.75MP maximum. Sending images at 1080p provides a good balance of performance and cost. For particularly cost-sensitive workloads, 720p or 1366×768 are lower-cost options with strong performance. Test to find the ideal settings for the use case; experimenting with effort can also help tune behavior.

Opus 4.7 Migration Checklist

Every item is tagged: [BLOCKS] items cause a 400 error, infinite loop, silent truncation, or empty output if missed — apply these as code edits, not as suggestions. [TUNE] items are quality/cost adjustments — surface them to the user as recommendations.

[BLOCKS] items prefixed with "If…" or "At…" are conditional. Before working through the list, scan the file for the conditions: does it surface thinking text to a UI/log? Does it set output_config.effort to "x-high" or "max"? Is it a security workload? Is it a multi-turn agentic loop? Apply only the items whose condition matches.

  • [ ] [BLOCKS] Replace thinking: {type: "enabled", budget_tokens: N} with thinking: {type: "adaptive"} + output_config.effort; delete budget_tokens plumbing entirely
  • [ ] [BLOCKS] Strip temperature, top_p, top_k from request construction
  • [ ] [BLOCKS] If thinking content is surfaced to users or stored in logs: add thinking.display: "summarized" (otherwise the rendered text is empty)
  • [ ] [BLOCKS] At output_config.effort of xhigh or max: set max_tokens ≥ 64000 (otherwise output truncates mid-thought)
  • [ ] [TUNE] Give max_tokens and compaction triggers extra headroom; re-run count_tokens() against claude-opus-4-7 on representative prompts to re-baseline (no blanket multiplier)
  • [ ] [TUNE] Re-baseline cost and rate-limit dashboards before reacting to measured shifts
  • [ ] [TUNE] Re-evaluate effort per route — use xhigh for coding/agentic and a minimum of high for most intelligence-sensitive work; it matters more on 4.7 than any prior Opus
  • [ ] [TUNE] Multi-turn agentic loops: adopt the API-native Task Budgets (output_config.task_budget, beta task-budgets-2026-03-13, minimum 20k tokens) — this is for capping cumulative spend across a loop; per-turn depth is effort
  • [ ] [TUNE] Check for ambiguous or underspecified instructions that relied on 4.6 generalizing intent, and update them to be clearer or more precise — 4.7 follows them literally
  • [ ] [TUNE] Tool-use workloads: add explicit when/how-to-use guidance to tool descriptions (4.7 reaches for tools less often)
  • [ ] [TUNE] Verbosity: test existing length instructions before changing them — 4.7 calibrates length to task complexity, so tune for the desired output rather than assuming a direction
  • [ ] [TUNE] Remove forced-progress-update scaffolding ("after every N tool calls…")
  • [ ] [TUNE] Remove knowledge-work verification scaffolding ("double-check the slide layout…") and re-baseline
  • [ ] [TUNE] Add tone instruction if a warmer / more conversational voice is needed; re-evaluate style prompts on writing-heavy routes
  • [ ] [TUNE] Subagent tool present: add explicit spawn / don't-spawn guidance
  • [ ] [TUNE] Frontend/design output: specify a concrete palette/typeface, or have the model propose 4 visual directions before building (the default cream/serif house style is persistent)
  • [ ] [TUNE] Interactive coding products: use effort: "xhigh" or "high", add autonomous features (e.g. an auto mode) to reduce human interactions, and specify task/intent/constraints upfront in the first turn
  • [ ] [TUNE] Code-review harnesses: remove or loosen "only report high-severity" / "be conservative" filters and have the model report every finding with confidence + severity; move filtering to a downstream step (4.7 follows severity filters more literally, which can depress measured recall)
  • [ ] [TUNE] Vision-heavy pipelines (screenshots, charts, document understanding): leave images at native resolution up to 2576px long edge for the accuracy gain; remove any scale-factor math from coordinate handling (coords are now 1:1 with pixels). No beta header / opt-in needed — high-res is automatic on Opus 4.7.
  • [ ] [TUNE] Computer-use pipelines: send screenshots at 1080p for a good performance/cost balance (720p or 1366×768 for cost-sensitive workloads); experiment with effort to tune behavior
  • [ ] [TUNE] Cost-sensitive image pipelines: full-res images on 4.7 use up to ~4784 tokens vs ~1,600 on prior models (~3×). Downsampling client-side before upload avoids the increase, but do not downsample by default — if you're unsure whether fidelity is needed, ask the user. Re-baseline with count_tokens() on representative images before reacting to cost shifts.

Migrating to Opus 4.8

Model ID claude-opus-4-8 is authoritative as written here. When the user asks to migrate to Opus 4.8, write model="claude-opus-4-8" 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 4.8 is our most capable Opus-tier model — highly autonomous, with state-of-the-art long-horizon agentic execution, knowledge work, and memory. It is layered on top of the Opus 4.7 migration above. If the caller is jumping from Opus 4.6 or older, apply the 4.6 and 4.7 sections first, then this one.

No new breaking changes. Opus 4.8 keeps the same request surface as Opus 4.7. The same calls that already work on 4.7 work unchanged on 4.8 — adaptive thinking only (thinking: {type: "enabled", budget_tokens: N} still 400s; use {type: "adaptive"}), sampling parameters (temperature, top_p, top_k) still rejected, last-assistant-turn prefills still 400, thinking.display still defaults to "omitted", and the low/medium/high/xhigh/max effort levels, Task Budgets (beta), and high-resolution vision all behave as on 4.7. A 4.7 → 4.8 migration is therefore the model-ID swap plus prompt re-tuning — there is no required code edit beyond the model string.

TL;DR for someone already on Opus 4.7: swap the model ID to claude-opus-4-8. Nothing else is required to avoid an error. Then re-tune prompts for the behavioral shifts: 4.8 narrates more than 4.7 (add a silence-default if you want 4.7-like terseness), writes in a warmer, less hedged voice, is more deliberate and asks more often (add autonomy guidance to claw back ask-rate), and is more conservative about reaching for search, subagents, file-based memory, and custom tools (add explicit "when to use this" triggering). For long-horizon agentic work, give the full task specification up front in one well-specified turn and run at high effort.

No new API breaking changes (inherited from 4.7)

These all carry over from Opus 4.7 unchanged — apply them only if the caller is coming from Opus 4.6 or earlier (see the Migrating to Opus 4.7 section above for the before/after and the SDK-specific syntax):

  • thinking: {type: "enabled", budget_tokens: N} → 400. Use thinking: {type: "adaptive"} + output_config.effort.
  • temperature, top_p, top_k → 400. Remove them; steer with prompting.
  • Last-assistant-turn prefills → 400. Use output_config.format (structured outputs) or a system-prompt instruction.
  • thinking.display defaults to "omitted"; set "summarized" if you surface reasoning to users.

If the caller is already on Opus 4.7 and these are clean, there is nothing to change here.

New API feature: mid-session system prompts

You can deliver trusted instructions partway through a session by placing {"role": "system", ...} entries directly in the messages array — without editing the top-level system prompt and invalidating your prompt cache. Use it for things the application learns mid-session: the user delivered async context, a mode toggled (auto-approve enabled), files changed on disk, the remaining token budget dropped.

messages=[
    {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "...", "content": "..."}]},
    {"role": "system", "content": "This project's codebase is Go. Write code in Go."},
]

Phrase these as context, not commands. State the fact and let Claude act on it; avoid override-style language ("ignore what the user said", "regardless of the user's request", "disregard the previous instruction"). Claude is trained to protect users from instructions that appear to work against them, and that protection applies to the system role too. No beta header is required; available on Claude Opus 4.8. For cache-placement details and the older-model <system-reminder> fallback, see shared/prompt-caching.md and shared/agent-design.md.

Capability improvements

Long-horizon agentic execution. Opus 4.8 is state-of-the-art at long, autonomous agentic work — complex refactors and overnight coding runs that complete without human correction. To get the most out of it, give the full task specification up front in a single well-specified initial turn and run at high effort (effort: "high" or "xhigh"). Its long-horizon coherence comes partly from reasoning more at each step; combined with a clear up-front goal, that more-intelligent planning often produces more efficient and more accurate output than prior frontier models. The "clear goal up front" principle maps to two product surfaces: in Claude Code, /goal sets direction for the run; with Managed Agents (CMA), state what "done" looks like via an Outcome (user.define_outcome with a gradeable rubric — the harness runs an iterate → grade → revise loop), see shared/managed-agents-outcomes.md.

Effort is a dimension to test, not a fixed setting. On prior models many reached for xhigh reflexively to maximize intelligence. Opus 4.8 has a higher intelligence ceiling, so start at high as the default and iterate rather than defaulting to xhigh. Sweep medium, high, and xhigh on your own eval set and weigh the intelligence ↔ latency ↔ cost tradeoff per route — the relationship isn't monotonic: higher effort up front often reduces turn count and total cost on agentic work, while for some tasks medium delivers equally good results in less time. Reserve max for extremely hard, latency-insensitive cases. The per-level effort table in the Migrating to Opus 4.7 section above applies unchanged on 4.8.

Writing voice and clarity. Testers consistently describe 4.8's prose as clearer, warmer, and less hedged than prior models, with fewer measurable AI vocal tics — especially at higher effort, where it approaches expert-level prose and structure. This is roughly the opposite direction from the 4.7 shift (4.7 was more clipped, direct, and less validation-forward). If you added style prompts to counter 4.7's terseness or to inject warmth, re-evaluate them against the new baseline before keeping them — they may now overcorrect. 4.8 is also a stronger thought partner: more thoughtful, more willing to push back, and more likely to infer the right answer from context.

Code review and debugging. Stronger real-bug finding and clearer explanations than 4.7 — one-shot fixes where 4.7 needed more, and correctly identifying intermittent flakes rather than declaring "fixed" after one clean run. The 4.7 caveat still applies: if a review harness says "only report high-severity issues" or "be conservative", 4.8 follows it literally and measured recall can drop even though underlying bug-finding improved. Tell the model to report everything and filter downstream (or review a second time) — see the Code review guidance in the 4.7 section for the recommended prompt.

Behavioral shifts (prompt-tunable)

None of these break code, but prompts tuned for Opus 4.7 may land differently. 4.8 follows instructions well, so small, explicit nudges close the gap.

Tool triggering is surface-dependent (search & knowledge). 4.8's tool-triggering is more surface-dependent than in prior models: with a system prompt present it is high-precision / low-recall — web search triggers slightly more often but runs fewer rounds per trigger, while knowledge-retrieval tools (Drive, project knowledge, connected files) trigger less often. It searches when it's confident search is needed and otherwise answers from context, which can lower research depth on tasks that need it. Recover should-search rate with an explicit search-first instruction:

<search_first> For questions where current information would change the answer (recent events, current roles or prices, version-specific behavior, or anything the user flags as time-sensitive) search before answering rather than answering from memory. For open-ended research requests, begin searching immediately; do not ask a scoping question first unless the request is genuinely ambiguous about what to research. </search_first>

Under-utilization of subagents, memory, and custom tools. Separately from search, 4.8 is conservative about reaching for capabilities that need an explicit "decide to use this" step — file-based memory, subagent delegation, custom tools. It won't reach for complex or expensive capabilities unless reasonably sure they're needed. This is steerable since 4.8 follows instructions well — say when each capability applies, not just that it exists:

"Before any task longer than a few turns, check your memory file for relevant prior context and write new findings to it as you go. When a task fans out across independent items (many files to read, many tests to run, many candidates to check), delegate to subagents rather than iterating serially."

The same lever works at the tool-description level, not just the system prompt: prescriptive descriptions that state when to call a tool (e.g. "Call this when the user asks about current prices or recent events") give meaningful lift on 4.8 over descriptions that only state what the tool does. Make the trigger condition part of each capability's own description.

More user-facing narration. 4.8 narrates more than 4.7 — more text between tool calls in long tool-calling sessions, and longer, more detailed end-of-task wrap-ups by default. If you previously added scaffolding to force interim status ("after every 3 tool calls, summarize progress"), remove it — 4.8 does this on its own. If the narration is too verbose for a coding agent, an explicit silence-default makes it behave like 4.7 with no loss of quality:

"Default to silence between tool calls. Only write text when you find something, change direction, or hit a blocker — one sentence each. Do not narrate routine actions ('Now I'll...', 'Let me check...', 'Looking at...'). When done: one or two sentences on the outcome. Do not recap every file or test — the user has been following along."

For knowledge-work deliverables (reports, analysis readouts), verbosity responds very well to instructions in user preferences or the user turn — expose a verbosity preference rather than hard-coding a length.

More deliberate — asks more often. 4.8 is more deliberate than prior Opus models. On minor decisions it would previously just make (a variable name, a default value, which of two equivalent approaches), it tends to pause and ask, and it often closes a completed task with "Want me to also…?" rather than doing the obvious next step or stopping cleanly. This is preferred for high-stakes or unfamiliar codebases, but bugs users when uncalibrated. Grant autonomy on the small stuff while keeping caution where it matters (in Claude Code testing this cut ask-rate by ~12 percentage points with no increase in over-reach):

"For minor choices (naming, formatting, default values, which approach among equivalents), pick a reasonable option and note it rather than asking. For scope changes or destructive actions, still ask first."

Verbose reasoning when thinking is disabled. With thinking: {type: "disabled"}, 4.8 occasionally writes longer explanations of its reasoning into the visible response, which reads as verbose when the user wants a fast, quick answer. The simplest fix is to leave adaptive thinking on — set thinking: {type: "adaptive"} (the recommended setting; it adjusts how much to think per task). Note adaptive is not on when the field is omitted — like Opus 4.7, a request with no thinking field runs without thinking, so set it explicitly. If you need thinking off for latency or cost, scope it in the system prompt:

"Respond only with your final answer. Do not include exploratory reasoning, intermediate drafts, diffs you considered but rejected, or meta-commentary about your process."

Opus 4.8 Migration Checklist

Every item is tagged: [BLOCKS] items cause a 400 error if missed; [TUNE] items are quality/cost adjustments — surface them to the user as recommendations.

For a caller already on Opus 4.7, only the first item is required; everything else is [TUNE]. The conditional [BLOCKS] item applies only when coming from Opus 4.6 or earlier.

  • [ ] [BLOCKS] Update the model= string to claude-opus-4-8
  • [ ] [BLOCKS] (only if coming from Opus 4.6 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. These already 400 on 4.7 and continue to 400 on 4.8.
  • [ ] [TUNE] Long-horizon / agentic work: put the full task spec in one well-specified first turn and run at high or xhigh effort (Claude Code: /goal; Managed Agents: an Outcome with a gradeable rubric)
  • [ ] [TUNE] Effort: sweep medium / high / xhigh on your eval set and pick per route by the intelligence ↔ latency ↔ cost tradeoff (default high, xhigh for coding/agentic)
  • [ ] [TUNE] Research depth & tool use: add a search-first instruction; add explicit triggering guidance for subagents, file-based memory, and custom tools (4.8 under-reaches for these by default) — in the system prompt and in each tool's own description (prescriptive "call this when…" descriptions give measurable lift)
  • [ ] [TUNE] Narration: remove forced-progress scaffolding ("after every N tool calls…"); add a silence-default if a coding agent is too chatty
  • [ ] [TUNE] Autonomy: add small-decisions-don't-ask guidance to cut ask-rate, while keeping caution on scope changes / destructive actions
  • [ ] [TUNE] Writing voice: re-evaluate style prompts added to counter 4.7's directness — 4.8 is warmer and less hedged by default; re-baseline before keeping them
  • [ ] [TUNE] Code-review harnesses: keep the report-everything-filter-downstream pattern (4.8 follows "only high-severity" / "be conservative" filters literally, which can depress measured recall)
  • [ ] [TUNE] Thinking-disabled paths: add a final-answer-only instruction if reasoning leaks into the visible response
  • [ ] [TUNE] Consider mid-session system messages (role:"system" in messages; no beta header) for context the app learns mid-session, instead of rebuilding the top-level system prompt and invalidating the cache

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.

Claude Sonnet 5 substantially improves on Sonnet 4.6 for coding and agentic work, reaching what was previously Opus-tier quality on many tasks. Its API surface aligns with Opus 4.7/4.8: manual extended thinking is removed (adaptive or disabled only, adaptive is the default), and non-default sampling parameters are rejected. This section is layered on top of the Sonnet 4.6 migration above — if the caller is jumping from Sonnet 4.5 or older, apply the 4.6 changes first, then this one.

TL;DR for someone already on Sonnet 4.6: swap the model ID to claude-sonnet-5. Replace any remaining thinking: {type: "enabled", budget_tokens: N} with thinking: {type: "adaptive"} (the transitional escape hatch is gone — it now 400s), and note that omitting thinking now runs adaptive (4.6 ran thinking-off). Strip non-default temperature/top_p/top_k. Re-run count_tokens() against claude-sonnet-5 — the new tokenizer produces ~30% more tokens for the same text, so token-budgeted limits and cost baselines shift even though per-token pricing is unchanged. effort defaults to high, the same as Sonnet 4.6 — raise to xhigh for the hardest coding and agentic tasks (Claude Sonnet 5 supports the full low/medium/high/xhigh/max range), and give max_tokens headroom at xhigh/max (the new tokenizer means a Sonnet-4.6-tuned max_tokens may truncate equivalent output). Then re-tune prompts: Claude Sonnet 5 interprets instructions more literally than 4.6 — holdover style/tone directives now apply at face value; it is more agentic by default and reaches for tools and self-verification loops more readily (with thinking disabled it is less tool-eager — add an explicit nudge); it gives better in-progress updates by default (drop forced "summarize every N tool calls" scaffolding); and code-review harnesses with conservative-reporting instructions may see lower recall (tell it to report everything and filter downstream).

Breaking changes (will 400 on Claude Sonnet 5)

These bring the Sonnet line onto the same request surface as Opus 4.7/4.8. See the Per-SDK Syntax Reference above for the language-specific spelling of each.

1. Extended thinking removed — adaptive only. thinking: {type: "enabled", budget_tokens: N} returns a 400. The transitional escape hatch that still worked on Sonnet 4.6 is gone. Use adaptive thinking with an effort hint:

# Before — deprecated on Sonnet 4.6, now errors on Claude Sonnet 5
thinking={"type": "enabled", "budget_tokens": 10000}

# After
thinking={"type": "adaptive"},
output_config={"effort": "high"},  # or "xhigh" for the hardest coding/agentic tasks

To turn thinking off entirely, set thinking: {type: "disabled"} — but see Adaptive vs. disabled below before doing so.

2. Sampling parameters rejected. Setting temperature, top_p, or top_k to a non-default value returns a 400; omitting the parameter, or passing its default, is still accepted. The safest migration is to omit them entirely and steer with prompting. If the caller was relying on temperature=0 for determinism, note in the migration comment that it never guaranteed identical outputs.

# Before
client.messages.create(model="claude-sonnet-4-6", temperature=0.2, ...)

# After — omit entirely
client.messages.create(model="claude-sonnet-5", ...)

3. Bedrock only: forced tool_choice requires thinking: {type: "disabled"}. On Amazon Bedrock, pass thinking: {type: "disabled"} alongside tool_choice: {type: "tool", name: ...} or tool_choice: {type: "any"}. The Claude API and Vertex AI do not require this.

Not a request-shape error, but handle it: cybersecurity safeguards. Claude Sonnet 5 is substantially more cyber-capable than Sonnet 4.6, so — like Opus 4.7/4.8 — requests touching prohibited or high-risk topics may be refused. Handle it as a content outcome (see the refusal stop-reason guidance in the Claude Fable 5 section if the caller needs a fallback path).

Unchanged from Sonnet 4.6: assistant-turn prefills still return a 400 (use output_config.format or a system-prompt instruction); the 1M-token context window, the 128k max-output ceiling, prompt caching, batch processing, the Files API, PDF support, vision, and the full server- and client-side tool set all carry over.

Silent default change: adaptive thinking on when thinking is omitted

On Sonnet 4.6, a request with no thinking field runs without thinking. On Claude Sonnet 5, the same request runs with adaptive thinking. This is not an error — but callers who never set thinking will now see thinking output (and spend thinking tokens) where they didn't before. max_tokens is a hard limit on total output (thinking + response text), so a workload that ran thinking-off on Sonnet 4.6 by omission may now truncate. Either set thinking: {type: "disabled"} explicitly to keep the old behavior, or revisit max_tokens to leave room for thinking.

Silent default change: thinking.display defaults to "omitted"

thinking.display defaults to "omitted" on Claude Sonnet 5 (matching Opus 4.7/4.8 and Claude Fable 5); on Sonnet 4.6 it defaulted to "summarized". With the default, thinking blocks stream with empty text — to a streaming UI this looks like a long pause before output. Combined with the adaptive-on-by-default change above, a Sonnet 4.6 caller who omits thinking entirely now gets adaptive thinking and empty-text thinking blocks. If you stream reasoning to users, set thinking: {type: "adaptive", display: "summarized"} explicitly. display controls visibility only — thinking happens and is billed the same under every setting.

New tokenizer (~30% more tokens)

Claude Sonnet 5 uses the same new tokenizer as Opus 4.7/4.8. The same input text produces approximately 30% more tokens than on Sonnet 4.6. No request/response shape changes and no code edits are required, but everything measured or budgeted in tokens shifts: usage fields and count_tokens() results for the same text are higher, the 1M context window holds less text, and a max_tokens limit tuned for Sonnet 4.6 may truncate equivalent output. Per-token pricing is unchanged at the $3/$15 sticker (introductory $2/$10 per MTok applies through 2026-08-31), so the cost of an equivalent request can differ. Re-run count_tokens() against claude-sonnet-5 rather than reusing counts measured against earlier models, and re-baseline cost dashboards before reacting to measured shifts.

Choosing an effort level on Claude Sonnet 5

effort defaults to high when not set (same as Sonnet 4.6 and Opus 4.8). Claude Sonnet 5 supports the full low/medium/high/xhigh/max range — the first Sonnet-tier model with xhigh. Keep the high default for most work and raise to xhigh for the hardest coding and agentic tasks:

Level When to use on Claude Sonnet 5
max Tasks needing the absolute highest capability with no token constraint. Can deliver gains in some use cases but may show diminishing returns and is sometimes prone to overthinking — test before committing
xhigh The hardest coding and agentic use cases — the recommended setting for those
high The default; balances token usage and intelligence for most use cases
medium Cost-saving step-down from the default — comparable to Sonnet 4.6 at high
low Short, scoped tasks and latency-sensitive workloads that aren't intelligence-sensitive (chat, simple lookups)

As a rough cross-model mapping when migrating: Claude Sonnet 5 at medium is comparable in intelligence to Sonnet 4.6 at high, and Claude Sonnet 5 at high is comparable to Sonnet 4.6 at max. When benchmarking, match by observed thinking length rather than effort name.

Claude Sonnet 5 respects effort levels strictly, especially at the low end. At low and medium it scopes its work to what was asked rather than going above and beyond — good for latency and cost, but on moderately complex tasks at low there is some risk of under-thinking. If you observe shallow reasoning on complex problems, raise effort to high or xhigh rather than prompting around it. If you must keep effort at low for latency, add targeted guidance:

"This task involves multi-step reasoning. Think carefully through the problem before responding."

Leave max_tokens headroom at xhigh/max. Set a large output token budget (up to the 128k cap, unchanged from Sonnet 4.6) so the model has room for thinking and tool calls. On long tasks, adaptive thinking can use a large share of the budget; if the budget is tight you may see a response that is almost entirely thinking followed by a truncated answer and stop_reason: "max_tokens" — raise max_tokens or drop to medium. Because Claude Sonnet 5 uses the new tokenizer (~30% more tokens for the same text), max_tokens limits tuned for Sonnet 4.6 may truncate equivalent output.

Adaptive vs. disabled thinking

Leave adaptive thinking on. Claude Sonnet 5 calibrates thinking spend to task complexity; the small added latency is usually worth the quality gain. If the caller was running Sonnet 4.6 with thinking off, try adaptive + effort: "low" first rather than thinking: {type: "disabled"}.

The triggering behavior for adaptive thinking is steerable. If the model emits thinking blocks more often than wanted (which can happen with large or complex system prompts), prompt it directly — and measure the effect on quality:

"Thinking adds latency and should only be used when it will meaningfully improve answer quality, typically for problems that require multi-step reasoning. When in doubt, respond directly."

Conversely, if you're running hard workloads at medium and seeing under-thinking, the first lever is to raise effort; if you need finer control, prompt for it directly.

Capability improvements

Coding and agentic tasks. The largest gains over Sonnet 4.6 are in coding and agentic tasks. Claude Sonnet 5 performs well out of the box on existing Sonnet 4.6 prompts.

High-resolution vision. Claude Sonnet 5 is the first Sonnet-tier model with high-resolution image support: maximum 2576 pixels on the long edge (up from 1568px on Sonnet 4.6). High-res images can use up to ~3× more image tokens than on Sonnet 4.6 (4784 vs 1568 tokens per image at the limit) — if the added fidelity isn't needed, downsample before sending to control token costs. No beta header or opt-in required.

Computer use. Supports the computer_20251124 tool version (beta header computer-use-2025-11-24). Capability works across resolutions up to the 2576px / 3.75MP maximum; sending screenshots at 1080p provides a good balance of performance and cost. For particularly cost-sensitive workloads, 720p or 1366×768 are lower-cost options with strong performance. Test to find the ideal settings for the use case; experimenting with effort can also help tune behavior.

Behavioral shifts (prompt-tunable)

None of these break code, but prompts tuned for Sonnet 4.6 may land differently. Claude Sonnet 5 follows instructions closely, so small explicit directives close the gap.

Response length and verbosity. Claude Sonnet 5 calibrates response length to task complexity rather than defaulting to a fixed verbosity — usually shorter on simple lookups, longer on open-ended analysis. If a product depends on a particular verbosity, tune the prompt. To decrease verbosity:

"Provide concise, focused responses. Skip non-essential context, and keep examples minimal."

If you see specific kinds of verbosity (e.g. over-explaining), add targeted instructions to prevent them. Positive examples showing the desired concision tend to be more effective than telling the model what not to do.

Tool use triggering. Claude Sonnet 5 is more agentic than Sonnet 4.6 by default and will reach for tools and run self-verification loops more readily. With thinking disabled, the model is less likely to reach for tools or consider searching — if the harness relies on tool calls with thinking off, add an explicit nudge in the system prompt. effort is also a lever: high and xhigh show substantially more tool usage in agentic search and coding. For scenarios where you want more tool use, also explicitly instruct when and how to use the tools (e.g. if web-search is under-used, describe in the prompt why and how it should be called).

User-facing progress updates. Claude Sonnet 5 provides regular, higher-quality updates to the user throughout long agentic traces by default. If the harness has scaffolding to force interim status messages ("After every 3 tool calls, summarize progress"), try removing it. If the length or content of the updates isn't well-calibrated to the use case, describe what they should look like in the prompt and provide an example.

More literal instruction following. Claude Sonnet 5 interprets prompts literally and explicitly, particularly at lower effort levels. It does not silently generalize an instruction from one item to another, and it does not infer requests that weren't made. The upside is precision — better for carefully tuned prompts, structured extraction, and pipelines that need predictable behavior. If an instruction should apply broadly, state the scope explicitly ("Apply this formatting to every section, not just the first one"). The same literalism means style/tone directives carried over from Sonnet 4.6 may now over-apply — re-baseline holdover lines like "be concise" before keeping them.

Tone and writing style. Prose style on long-form writing may shift. If a product relies on a specific voice, re-evaluate style prompts against the new baseline. For a warmer or more conversational voice:

"Use a warm, collaborative tone. Acknowledge the user's framing before answering."

Because temperature/top_p/top_k are not accepted on Claude Sonnet 5, callers who previously relied on temperature for stylistic variety must use system-prompt instructions instead.

Code review harnesses. A review harness tuned for an earlier model may initially see lower recall on Claude Sonnet 5. This is likely a harness effect, not a capability regression: when a review prompt says "only report high-severity issues" / "be conservative" / "don't nitpick," Claude Sonnet 5 follows that instruction more faithfully than earlier models did — it investigates just as thoroughly, identifies the bugs, and then doesn't report findings it judges below the stated bar. Precision typically rises, but measured recall can fall even though underlying bug-finding ability has improved. Recommended prompt language:

"Report every issue you find, including ones you are uncertain about or consider low-severity. Do not filter for importance or confidence at this stage — a separate verification step will do that. Your goal here is coverage: it is better to surface a finding that later gets filtered out than to silently drop a real bug. For each finding, include your confidence level and an estimated severity so a downstream filter can rank them."

This works even without an actual second step, but moving confidence filtering out of the finding stage often helps. If you do want single-pass self-filtering, be concrete about where the bar is rather than using qualitative terms like "important" — e.g. "report any bugs that could cause incorrect behavior, a test failure, or a misleading result; only omit nits like pure style or naming preferences." Iterate against a subset of evals to validate recall/F1 gains.

Design and frontend defaults. Claude Sonnet 5 may settle into a consistent default visual style on open-ended frontend and design briefs. Generic instructions ("don't use that color," "make it clean and minimal") tend to shift it to a different fixed palette rather than producing variety. Two approaches work reliably: specify a concrete alternative (the model follows explicit specs precisely — give the palette, typography, layout, and spacing), or have the model propose options before building (e.g. "Before building, propose 4 distinct visual directions tailored to this brief — bg hex / accent hex / typeface plus a one-line rationale — ask the user to pick one, then implement only that direction"). Because temperature isn't accepted on Claude Sonnet 5, the propose-then-pick approach is the recommended way to get meaningfully different design directions across runs. To steer away from generic AI-aesthetic patterns, a short directive in the system prompt also helps:

"NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white or dark backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character. Use unique fonts, cohesive colors and themes, and animations for effects and micro-interactions."

Interactive coding products. Token usage and behavior can differ between autonomous, asynchronous coding agents (single user turn) and interactive, synchronous coding agents (multiple user turns). To maximize both performance and token efficiency, use effort: "xhigh" or "high", add autonomous features like an auto mode, and reduce the number of human interactions required. Specify task, intent, and constraints upfront in the first turn — well-specified initial prompts maximize autonomy and intelligence while minimizing extra token usage after user turns; ambiguous or progressively-revealed prompts tend to reduce token efficiency and sometimes performance.

Claude Sonnet 5 Migration Checklist

Every item is tagged: [BLOCKS] items cause a 400 error or truncated output if missed; [TUNE] items are quality/cost adjustments — surface them to the user as recommendations.

  • [ ] [BLOCKS] Update the model= string to claude-sonnet-5
  • [ ] [BLOCKS] Replace thinking: {type: "enabled", budget_tokens: N} with thinking: {type: "adaptive"} + output_config.effort — the Sonnet 4.6 transitional escape hatch is gone
  • [ ] [BLOCKS] Strip temperature, top_p, top_k from request construction (use system-prompt instructions for tone/variety instead)
  • [ ] [BLOCKS] Bedrock only: pass thinking: {type: "disabled"} alongside forced tool_choice ({type: "tool"} / {type: "any"}) — not required on the Claude API or Vertex AI
  • [ ] [BLOCKS] At effort: "xhigh" or "max": set a large max_tokens (up to 128k, unchanged from Sonnet 4.6) so the model has room for thinking and tool calls — Sonnet-4.6-tuned limits may truncate equivalent output under the new tokenizer (symptom: stop_reason: "max_tokens")
  • [ ] [TUNE] Thinking-field omitted: adaptive is now the default (4.6 ran thinking-off) — either set thinking: {type: "disabled"} to preserve the old behavior, or revisit max_tokens for the added thinking spend
  • [ ] [TUNE] thinking.display defaults to "omitted" (4.6 defaulted to "summarized"): if you stream reasoning to users, set thinking: {type: "adaptive", display: "summarized"} explicitly — the default streams empty-text thinking blocks (long pause before output)
  • [ ] [TUNE] New tokenizer: re-run count_tokens() against claude-sonnet-5 (~30% more tokens for the same text); revisit max_tokens and compaction triggers sized close to expected output length; re-baseline cost dashboards before reacting (per-token pricing unchanged)
  • [ ] [TUNE] Effort: keep the high default; raise to xhigh for the hardest coding/agentic tasks; medium is a cost-saving step-down (≈ Sonnet 4.6 at high); reserve low for short, latency-sensitive, non-intelligence-sensitive tasks. If shallow reasoning shows up at low/medium, raise effort rather than prompting around it
  • [ ] [TUNE] Thinking-off callers: try thinking: {type: "adaptive"} + effort: "low" instead of disabled; if disabled must stay, add an explicit tool-triggering nudge (the model is less tool-eager with thinking off)
  • [ ] [TUNE] Tool usage: more agentic than 4.6 by default (reaches for tools and self-verification more readily) — effort is a lever (high/xhigh for more tool use); add explicit when/how triggering instructions for under-used tools
  • [ ] [TUNE] Drop forced progress-update scaffolding ("after every N tool calls, summarize") — the default updates are higher quality; describe the desired update shape if it still needs tuning
  • [ ] [TUNE] Re-baseline holdover style/tone/scope directives — instructions are followed literally; state the scope explicitly when one should apply broadly
  • [ ] [TUNE] Verbosity-sensitive routes: tune response length via prompt (positive examples > "don't" instructions)
  • [ ] [TUNE] Code-review harnesses with conservative-reporting instructions ("only high-severity", "don't nitpick"): switch to a coverage-first prompt (report everything with confidence + severity) and filter downstream — measured recall can otherwise fall even though bug-finding improved
  • [ ] [TUNE] Open-ended frontend/design briefs: specify a concrete spec, or have the model propose 3–4 visual directions and pick one (the recommended substitute for temperature-driven variety)
  • [ ] [TUNE] Interactive coding products: use effort: "xhigh"/"high", add autonomous features (e.g. auto mode), and put task/intent/constraints in the first turn
  • [ ] [TUNE] Vision-heavy / computer-use pipelines: leave images at native resolution up to 2576px long edge for the accuracy gain (downsample to control image-token cost if fidelity isn't needed); for computer use, 1080p screenshots are a good performance/cost balance with computer_20251124
  • [ ] [TUNE] Security workloads: add handling for safeguard refusals (cyber-capable topics may now be declined where Sonnet 4.6 answered)

Migrating to Claude Fable 5

Model IDs claude-fable-5 and claude-mythos-5 are authoritative as written here. When the user asks to migrate to Claude Fable 5, write model="claude-fable-5" exactly; a Mythos Preview migrator in Project Glasswing writes model="claude-mythos-5" (everyone else: claude-fable-5). Do not WebFetch to verify — this guide is the source of truth for migration target IDs. The corresponding entries exist in shared/models.md.

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.

Breaking changes (vs Opus-tier and Mythos Preview)

  1. Thinking is always on — remove all thinking configuration. Adaptive thinking applies automatically whenever the thinking parameter is unset (an explicit {type: "adaptive"} is also accepted). Any other configuration is rejected: thinking: {type: "disabled"} and {type: "enabled", budget_tokens: N} both return a 400. budget_tokens has no replacement — the output_config.effort parameter is a separate output-level control, not a thinking budget.

```python # Before (Mythos Preview / older models) client.messages.create( model="claude-mythos-preview", max_tokens=16000, thinking={"type": "enabled", "budget_tokens": 10000}, messages=[...], )

# After (Claude Fable 5) — no thinking field at all client.messages.create( model="claude-fable-5", max_tokens=16000, output_config={"effort": "high"}, messages=[...], ) ```

  1. Assistant prefill is not supported. Replace last-assistant-turn prefills with structured outputs (output_config.format) or system prompt instructions — same replacement patterns as the 4.6-family prefill removal above. (One exception: the fallback-credit prefill claim — the server accepts the echoed assistant message when redeeming a credit; see the refusal section below.)

  2. Interleaved scratchpad is not supported (Mythos Preview migrators only). Inter-tool reasoning is returned in thinking blocks instead, which adaptive thinking produces automatically between tool calls.

Thinking output on Claude Fable 5 and Claude Mythos 5

On Claude Fable 5 and Claude Mythos 5, the raw chain of thought is never returned. What you receive are regular thinking blocks, not encrypted blobs or redacted_thinking: display: "summarized" returns a readable summary of the reasoning, and with "omitted" — the default, same as Opus 4.8/4.7 — responses still include thinking blocks but the thinking field is an empty string. display controls visibility only; thinking happens and is billed the same under every setting. When continuing a conversation on the same model, pass thinking blocks back to the API unchanged (the standard multi-turn pattern; dropping or editing them breaks the turn).

When continuing on the same model, pass each thinking block back exactly as received — including blocks whose thinking text is empty. The API rejects blocks whose content has been modified, not blocks you have read; displaying the summary is fine, editing or reconstructing blocks is not.

Regular thinking blocks aren't origin-locked — they replay across models fine (the server renders them into the target model's prompt). Claude Fable 5/Claude Mythos 5 thinking is the exception: a thinking block from these models replayed to a different model is dropped from the prompt rather than rendered — typically silently (early-access builds hard-rejected with invalid_request_error; that broke workflows and was reverted before launch, but the new behavior is still rolling out, so don't build logic that depends on either outcome). The drop happens before the prompt is priced, so a dropped block lowers usage.input_tokens — you aren't billed for it, and there's nothing to strip for cost. Don't strip regular thinking blocks either: removing them can trigger ordering/signature 400s. Two rules for replay bodies stand regardless: fallback-credit retries must echo the refused body unchanged, and fallback blocks from a mid-output fallback stay where they appeared.

Related: a request that tries to elicit the model's internal reasoning in the response text can be refused with stop_details.category: "reasoning_extraction" — applications needing reasoning visibility should read the summarized thinking blocks instead of prompting for reasoning.

Tokenizer — unchanged from Opus 4.8

Claude Fable 5 uses the same tokenizer as Claude Opus 4.8 (the tokenizer introduced with Opus 4.7). Token counts are roughly unchanged when migrating from Opus 4.7/4.8 or from claude-mythos-preview; per-token pricing differs.

  • Coming from Opus 4.7/4.8 or claude-mythos-preview: token counts are roughly unchanged. Re-baseline cost and latency on your own workloads for the per-token price difference.
  • Coming from Opus 4.6, Sonnet, Haiku, or older: the Opus 4.7 tokenizer tokenizes the same content to roughly 1×–1.35× as many tokens (varies by content and workload shape). Do not reuse token counts, context-window budgets, or max_tokens settings measured on the old model; re-baseline with count_tokens.

To measure the difference on your own prompts, call count_tokens once with your current model and once with model: "claude-fable-5", and compare the two input_tokens values.

refusal stop reason — handle before reading content

Claude Fable 5 runs safety classifiers on incoming requests, targeting research biology and most cybersecurity content (Claude Fable 5 is not intended for those domains); benign adjacent work — security tooling, life-sciences tasks — can occasionally trigger false positives, which is why the fallback patterns below matter even for legitimate workloads. (Most Claude consumer surfaces ship with built-in Opus 4.8 fallbacks; API callers configure their own.) A declined request returns a successful HTTP 200 with stop_reason: "refusal", plus a stop_details object with the policy category (values such as "cyber", "bio", "reasoning_extraction", "frontier_llm", or null — treat null as a permanent valid state; see the refusal category table in the public docs for the full set). Branch on stop_reason, never on stop_details — stop_details is informational and can be null even on a refusal, and explanation is not guaranteed present. Note that classifier blocks and ordinary model refusals (the model itself declining) both surface as stop_reason: "refusal"; stop_details.category tells you which class you're handling, and therefore whether retrying on a fallback model is the right response. The classifier can fire before any output (empty content array; not billed at all — no input or output tokens, no rate-limit consumption) or mid-stream after partial output (already-streamed output is billed at normal rates — discard the partial output rather than treating it as complete). Code that reads response.content[0] unconditionally will break — check stop_reason first:

response = client.messages.create(model="claude-fable-5", max_tokens=1024, messages=[...])
if response.stop_reason == "refusal":
    # classifiers declined; content is empty (pre-output) or partial (mid-stream)
    handle_refusal()
else:
    print(response.content[0].text)

Default to opting in. Fallbacks are not automatic on the API — a request without them simply stops on a refusal. Migrated and new Claude Fable 5 code should ship with pattern 1 below (pattern 2 on providers without server-side support) from day one, not as a later hardening step: emit the opt-in in the code, tell the user it's there, and remove it only if they decline.

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.

response = client.beta.messages.create(
    model="claude-fable-5",
    max_tokens=1024,
    betas=["server-side-fallback-2026-06-01"],
    fallbacks=[{"model": "claude-opus-4-8"}],
    messages=[{"role": "user", "content": "Hello, Claude"}],
)

# Switch points: one fallback block per model that ran and declined this turn
for block in response.content:
    if block.type == "fallback":
        print(f"{block.from_.model} declined; {block.to.model} continued")

# Served-by signal: a fallback_message in usage.iterations means a fallback model
# ran; pair it with stop_reason to confirm the fallback served the response
# (a fallback model can also refuse). Covers sticky turns too.
fallback_ran = any(
    entry.type == "fallback_message" for entry in response.usage.iterations or []
)
if fallback_ran and response.stop_reason != "refusal":
    print(f"Served by {response.model}")

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.
  • 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.
  • Sticky routing: once a conversation falls back, later non-streaming requests with fallbacks are served directly by the fallback model for ~1 hour (best-effort; org-scoped content-hash record, not message content; not recorded for ZDR orgs). Handle the requested model being tried again at any time.
  • Echoing fallback turns back: after a mid-output fallback, omit thinking, redacted_thinking, and tool_use blocks — plus any server_tool_use block without its matching server_tool_result, and any other unrecognized model-internal block type — that appear before the final fallback block; text blocks, paired server-tool blocks, and everything after the boundary echo normally. The fallback block itself is an ignored audit marker (keep or drop). Streaming: the retry happens on the same stream and already-received content is never invalidated — a pre-output block is seamless (message_start names the fallback model; the fallback block arrives as an ordinary content_block_start, first in content — there is no special SSE event type; note message_start arrives only after the declined attempt, so time-to-first-byte includes it), and a mid-stream block keeps the partial, marks the boundary with the block, and continues — only the partial's text blocks are passed to the fallback model as continuation context (other block types stay in content but aren't part of it). Sticky routing is not consulted on streaming requests in the initial release, so on streams the fallback block check is the complete signal; non-streaming mid-output declines omit the declined partial entirely.

2. SDK client-side middleware — for providers without server-side fallbacks (Amazon Bedrock, Vertex AI, Microsoft Foundry). Register it on the client and every client.beta.messages request (streaming included) retries refusals automatically, splicing the fallback model's events onto the open stream in the same wire shape as pattern 1 (a fallback content block at each boundary, per-hop usage.iterations). It is also a beta surface: the middleware sends the fallback-credit-2026-06-01 header by default so retries are repriced via credit tokens (override with its betas option). BetaFallbackState pins follow-up turns to the model that accepted (the client-side analog of sticky routing) — reuse one state object per conversation:

from anthropic import Anthropic, BetaFallbackState, BetaRefusalFallbackMiddleware

client = Anthropic(middleware=[BetaRefusalFallbackMiddleware([{"model": "claude-opus-4-8"}])])
state = BetaFallbackState()  # pins follow-ups to the model that accepted
with state:
    response = client.beta.messages.create(model="claude-fable-5", max_tokens=1024, messages=messages)

Create one state per conversation — it is the pinning scope; sharing one across conversations pins unrelated threads together, and a conversation without a state is never pinned. Per-language naming (from the GA SDK examples — don't improvise):

  • TypeScript: betaRefusalFallbackMiddleware([...]) in the client's middleware array; pass { fallbackState: state } (a BetaFallbackState) as a request option.
  • Go: option.WithMiddleware(betafallback.BetaRefusalFallbackMiddleware([]anthropic.BetaFallbackParam{{Model: ...}})) (package lib/betafallback); state via betafallback.WithBetaFallbackState(&betafallback.BetaFallbackState{}) passed as a request option. Server-side equivalents: Fallbacks: []anthropic.BetaFallbackParam{...} + anthropic.AnthropicBetaServerSideFallback2026_06_01.
  • C#: it's a handler — new AnthropicClient { Handlers = [new BetaRefusalFallbackHandler { Fallbacks = [new(Model.ClaudeOpus4_8)] }] } (namespace Anthropic.Helpers); state via BetaFallbackState.Create() scoped per call with using (fallbackState.Use()) { ... }. Server-side equivalents: Fallbacks = [new(Model.ClaudeOpus4_8)] + AnthropicBeta.ServerSideFallback2026_06_01.

For languages not listed (Java, Ruby, PHP) — or for a full runnable program in any language — each public SDK repo ships a fallbacks example under examples/ (e.g. examples/fallbacks.py, examples/refusal-fallback/): WebFetch the repo from shared/live-sources.md § SDK Repositories rather than improvising the binding.

3. Hand-rolled retry + fallback credit (raw HTTP, or SDKs without the middleware). Detect the refusal via stop_reason and re-send the conversation as-is on a model with broader availability such as claude-opus-4-8 (Claude Fable 5's thinking blocks are silently ignored by other models — no stripping required); keep using the fallback model for subsequent turns. Fallback credit (beta: Claude API, Claude Platform on AWS, Amazon Bedrock, Vertex AI, and Microsoft Foundry) makes those retries cheaper. Prompt caches are per-model, so a plain retry pays cold cache-writes on the new model. With the fallback-credit-2026-06-01 beta header (send it on both the original request and the retry), a refusal's stop_details carries fallback_credit_token (opaque; null when unavailable) and fallback_has_prefill_claim. Echo the token as the top-level fallback_credit_token request parameter on the retry (typed in the GA SDKs; on a pre-GA SDK pass it via extra_body) and the previously-cached span bills at cache-read rates — the retry costs what it would have if the conversation had been on that model all along. Rules: the retry body must match the refused request exactly in every prompt-shaping field (system, messages, tools, tool_choice, thinking — do not strip thinking blocks when redeeming a credit — the server handles them); the retry model must be in the refused model's allowed_fallback_models; the token expires in 5 minutes; Batches results carry no tokens. If fallback_has_prefill_claim is true, append one assistant message echoing the refused response's content — the retry model continues from where the refused model stopped (and completed server-tool work isn't re-run). When echoing, strip trailing whitespace from a final text block (the prefill validator rejects it; the credit match tolerates that edit), after omitting any unpaired tool_use blocks. On a 400, fall back to the unchanged body with the token; on a 400 naming fallback_credit_token, retry without it (credit forfeited).

Migrating code built on the v1 preview. If the code you're editing carries any of these markers, it targets the discontinued early-access surface — migrate it to the v2 shapes above, and ship the header and parameter changes together (the v1 parameter shape under the v2 header is a 400):

v1 marker (replace) v2
server-side-fallback-2026-06-09 / -2026-06-02 header server-side-fallback-2026-06-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
fallback_primary / fallback_retry iteration types Blocked attempts are plain message entries; the serving attempt is fallback_message
reason: "sticky" No reason field — sticky turns carry no block; detect via fallback_message in usage.iterations + response.model
recommended_model meaning "primary served the refusal" Now populated only when the fallback attempt couldn't run (rate-limited/overloaded) — its presence means a direct retry on that model may succeed, not that it refused too

Data retention requirement

Claude Fable 5 requires 30-day data retention and is not available under zero data retention. Requests from an organization whose data-retention configuration doesn't meet the requirement return 400 invalid_request_error — if a migration suddenly 400s with no obvious request problem, check the org's retention configuration before debugging the payload. On Amazon Bedrock, Google Vertex AI, and Microsoft Foundry, data-retention requirements are set by each platform.

What carries over unchanged

Same Messages API and tool-use patterns as Opus-tier and Mythos Preview. Supported at launch: output_config.effort (low/medium/high/xhigh/max), Task Budgets (beta, task-budgets-2026-03-13 header), compaction (beta, compact-2026-01-12 header), the memory tool, tool-call clearing via context editing, and high-resolution vision (no downscaling cap, as on Opus 4.7+).

Behavioral shifts (prompt-tunable)

None of these are API-breaking, but they're where migrated workloads feel different. Claude Fable 5's biggest gains are on work above what prior models could do (long-horizon autonomous runs, first-shot implementations of well-specified systems, end-to-end enterprise deliverables — financial analysis, spreadsheets, slides, docs — code review/debugging and repository-history search, vision on dense or degraded images — it's explicitly trained to use bash and crop tools on flipped/blurry/noisy inputs — navigating ambiguity, parallel sub-agent delegation and collaboration — it reliably sustains ongoing communications with long-running sub-agents and peer agents; note bug-finding gains exclude security-focused analysis, where the cyber classifiers apply) — don't evaluate it only on workloads older models already handled.

Longer turns by default — the biggest structural shift. Individual requests on hard tasks can run many minutes at higher effort (a 15-minute single request is normal when the task involves gathering context, building, and self-verifying). Before migrating, plan timeouts, streaming, and user-facing progress indicators; structure work so callers check in on runs asynchronously rather than blocking inside one request. On ambiguous tasks Claude Fable 5 may need a small nudge to avoid overplanning:

When you have enough information to act, act. Do not re-derive facts already established in the conversation, re-litigate a decision the user has already made, or narrate options you will not pursue in user-facing messages. If you are weighing a choice, give a recommendation, not an exhaustive survey. This does not apply to thinking blocks.

Consider all effort levels. output_config.effort is the primary intelligence/latency/cost control. Recommended defaults: high for most tasks, xhigh for the most capability-sensitive workloads, medium/low for routine work. Lower effort settings — including low — still perform very well on Claude Fable 5, often exceeding the xhigh or even max performance of previous models. Reduce effort if a task completes correctly but takes longer than necessary, or for a quicker interactive working style. At higher effort on routine work, Claude Fable 5 can gather context and deliberate beyond what the task needs (the flip side: higher effort buys excellent verification behavior and the most rigorous outputs). To prevent unrequested tidying or refactoring at higher effort:

Don't add features, refactor, or introduce abstractions beyond what the task requires. A bug fix doesn't need surrounding cleanup and a one-shot operation usually doesn't need a helper. Don't design for hypothetical future requirements - do the simplest thing that works well. Avoid premature abstraction. Avoid half-finished implementations either. Don't add error handling, fallbacks, or validation for scenarios that cannot happen. Trust internal code and framework guarantees. Only validate at system boundaries (user input, external APIs). Don't use feature flags or backwards-compatibility shims when you can just change the code.

Instruction following is strong — use it. Claude Fable 5 is very responsive to explicit communication-style sections in system prompts; invest in them rather than fighting output style downstream. Un-steered — especially at higher effort — it can elaborate beyond what the task needs: heavily-structured PR descriptions, sections on alternatives that weren't chosen, comments narrating what the next line does. You don't need to enumerate these behaviors by name; a brief instruction is just as effective:

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 come after. Being readable and being concise are different things, and readability matters more. 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.

Ground progress claims on long runs. Require progress claims to be audited against tool results — in testing this nearly eliminated fabricated status reports on tasks designed to elicit them:

Before reporting progress, audit each claim against a tool result from this session. Only report work you can point to evidence for; if something is not yet verified, say so explicitly. Report outcomes faithfully: if tests fail, say so with the output; if a step was skipped, say that; when something is done and verified, state it plainly without hedging.

State boundaries explicitly. Claude Fable 5 sometimes takes unrequested-but-adjacent actions (e.g. composing an email straight to drafts, creating backup git branches). Define what it should not do:

When the user is describing a problem, asking a question, or thinking out loud rather than requesting a change, the deliverable is your assessment. Report your findings and stop. Don't apply a fix until they ask for one. Before running a command that changes system state — restarts, deletes, config edits — check that the evidence actually supports that specific action. A signal that pattern-matches to a known failure may have a different cause.

Let it delegate — asynchronously. Parallel sub-agents are dependable on Claude Fable 5 — instead of suppressing delegation (a common prior-model guardrail), use sub-agents frequently and give explicit guidance on when delegation is desirable. Sub-agents that communicate asynchronously with the orchestrator outperform spawn-and-block: long-lived agents keep their context instead of re-establishing it per subtask (cache-read savings), the orchestrator isn't bottlenecked on the slowest sub-agent, and context persists across subtasks.

Delegate independent subtasks to sub-agents and keep working while they run. Intervene if a sub-agent goes off track or is missing relevant context.

Give it a memory surface. Claude Fable 5 performs notably better when it can write learnings somewhere for future reference — even a plain .md file. Tell it where, tell it to consult that file in future sessions, and give it a format:

Store one lesson per file with a one-line summary at the top. Record corrections and confirmed approaches alike, including why they mattered. Don't save what the repo or chat history already records; update an existing note rather than creating a duplicate; delete notes that turn out to be wrong.

Rare: early stopping. Deep into long sessions it can occasionally end a turn with a text-only statement of intent ("I'll now run X") without the tool call, or ask permission it doesn't need. A "continue" recovers it interactively; for autonomous pipelines add a system reminder:

You are operating autonomously. The user is not watching in real time and cannot answer questions mid-task, so asking 'Want me to…?' or 'Shall I…?' will block the work. For reversible actions that follow from the original request, proceed without asking. Offering follow-ups after the task is done is fine; asking permission after already discussing with the user before doing the work is not. Before ending your turn, check your last paragraph. If it is a plan, an analysis, a question, a list of next steps, or a promise about work you have not done ('I'll…', 'let me know when…'), do that work now with tool calls. End your turn only when the task is complete or you are blocked on input only the user can provide.

Rare: context anxiety. In very long sessions it can worry about running out of context — suggesting a new session or trimming its own work — most often when the harness surfaces a remaining-token countdown. Avoid showing explicit context-budget counts; if you must:

You have ample context remaining. Do not stop, summarize, or suggest a new session on account of context limits – continue the work.

Give the reason, not just the request. Claude Fable 5 performs better when it understands the intent behind a request — it connects the task to relevant information rather than inferring intent on its own. This matters most for long-running agents juggling context from disparate workstreams:

I'm working on [the larger task] for [who it's for]. They need [what the output enables]. With that in mind: [request].

Readability in long agentic sessions. Deep into extended conversations (many tool calls, large working context) Claude Fable 5 can produce text users find hard to follow — dense arrow-chain shorthand, implementation-level detail, references to thinking the user never saw. A communication-style addendum strongly mitigates this; adapt:

Terse shorthand is fine between tool calls (that's you thinking out loud, and brevity there is good). Your final summary is different: it's for a reader who didn't see any of that. If you've been working for a while without the user watching - overnight, across many tool calls, since they last spoke - your final message is their first look at any of it. Write it as a re-grounding, not a continuation of your working thread: the outcome first, then the one or two things you need from them, each explained as if new. The vocabulary you built up while working is yours, not theirs; leave it behind unless you re-introduce it. When you write the summary at the end, drop the working shorthand. Write complete sentences. Spell out terms instead of abbreviating them. Don't use arrow chains, hyphen-stacked compounds, or labels you made up earlier — the reader doesn't have the context to decode them. When you mention files, commits, flags, or other identifiers, give each one its own plain-language clause saying what it is or what changed — never pack several into one parenthesized run or slash-separated list. Open with the outcome: one sentence on what happened or what you found. Then the supporting detail. If you have to choose between short and clear, choose clear.

Long-running agent recommendations

  • Make self-verification explicit. For long-running builds, instruct it to establish and run its own checking harness on a cadence ("Establish a method for checking your own work as you build; run it every [interval], verifying against the specification with sub-agents"). Separate fresh-context verifier sub-agents tend to outperform self-critique.
  • De-prescribe migrated prompts and skills. Prompts and skills written for prior models are often too prescriptive for Claude Fable 5 and reduce output quality. After migrating, A/B the workload with older step-by-step scaffolding removed — prefer stating the goal and constraints over enumerating the steps. Claude Fable 5 is also good at updating skills on the fly from what it learns mid-task — let it.
  • Start at the top of your difficulty range. The teams with the best early-access outcomes gave it their hardest unsolved problems first — have it scope the problem, ask questions, then execute.
  • Add a send_to_user tool for verbatim mid-task delivery. When an asynchronous agent must deliver something the user sees exactly as written mid-run (a deliverable, a progress update with specific numbers, a direct answer), give it a client-side tool whose input you render directly in the UI — tool inputs are never summarized, so content arrives intact. Return a simple acknowledgement as the tool result:
{
  "name": "send_to_user",
  "description": "Display a message directly to the user. Use this for progress updates, partial results, or content the user must see exactly as written before the task finishes.",
  "input_schema": {
    "type": "object",
    "properties": {
      "message": { "type": "string", "description": "The content to display to the user." }
    },
    "required": ["message"]
  }
}

For agents that only narrate routine progress, the model's default progress narration is typically adequate without this tool.

Claude Fable 5 Migration Checklist

  • [ ] [BLOCKS] Update the model= string to claude-fable-5 (claude-mythos-5 for Mythos Preview migrators in Project Glasswing)
  • [ ] [BLOCKS] Remove thinking: {type: "disabled"} (errors on Claude Fable 5)
  • [ ] [BLOCKS] Replace assistant prefill with structured outputs or system prompt instructions
  • [ ] [BLOCKS] Confirm the org meets the 30-day data-retention requirement (ZDR orgs get 400 invalid_request_error on every request)
  • [ ] [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] 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
  • [ ] [TUNE] A/B with prior-model scaffolding removed — over-prescriptive prompts/skills reduce Claude Fable 5 output quality

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:

YOUR_TARGET_MODEL = "claude-opus-4-8"  # 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

For rate-limit headroom changes, pricing, or capability deltas (vision, structured outputs, effort support), query the Models API:

m = client.models.retrieve(YOUR_TARGET_MODEL)
m.max_input_tokens, m.max_tokens
m.capabilities["effort"]["max"]["supported"]

See shared/models.md for the full capability lookup pattern.

Claude Model Catalog

Only use exact model IDs listed in this file. Never guess or construct model IDs — incorrect IDs will cause API errors. Use aliases wherever available. For the latest information, WebFetch the Models Overview URL in shared/live-sources.md, or query the Models API directly (see Programmatic Model Discovery below).

Programmatic Model Discovery

For live capability data — context window, max output tokens, feature support (thinking, vision, effort, structured outputs, etc.) — query the Models API instead of relying on the cached tables below. Use this when the user asks "what's the context window for X", "does model X support vision/thinking/effort", "which models support feature Y", or wants to select a model by capability at runtime.

m = client.models.retrieve("claude-opus-4-8")
m.id                 # "claude-opus-4-8"
m.display_name       # "Claude Opus 4.8"
m.max_input_tokens   # context window (int)
m.max_tokens         # max output tokens (int)

# capabilities is an untyped nested dict — bracket access, check ["supported"] at the leaf
caps = m.capabilities
caps["image_input"]["supported"]                       # vision
caps["thinking"]["types"]["adaptive"]["supported"]     # adaptive thinking
caps["effort"]["max"]["supported"]                     # effort: max (also low/medium/high)
caps["structured_outputs"]["supported"]
caps["context_management"]["compact_20260112"]["supported"]

# filter across all models — iterate the page object directly (auto-paginates); do NOT use .data
[m for m in client.models.list()
 if m.capabilities["thinking"]["types"]["adaptive"]["supported"]
 and m.max_input_tokens >= 200_000]

Top-level fields (id, display_name, max_input_tokens, max_tokens) are typed attributes. capabilities is a dict — use bracket access, not attribute access. The API returns the full capability tree for every model with supported: true/false at each leaf, so bracket chains are safe without .get() guards. TypeScript SDK: same method names, also auto-paginates on iteration.

Raw HTTP

curl https://api.anthropic.com/v1/models/claude-opus-4-8 \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01"

{
  "id": "claude-opus-4-8",
  "display_name": "Claude Opus 4.8",
  "max_input_tokens": 1000000,
  "max_tokens": 128000,
  "capabilities": {
    "image_input": {"supported": true},
    "structured_outputs": {"supported": true},
    "thinking": {"supported": true, "types": {"enabled": {"supported": false}, "adaptive": {"supported": true}}},
    "effort": {"supported": true, "low": {"supported": true}, …, "max": {"supported": true}},
    …
  }
}

Current Models (recommended)

Friendly Name Alias (use this) Full ID Context Max Output Status
Claude Fable 5 claude-fable-5 — 1M 128K Active
Claude Mythos 5 claude-mythos-5 — 1M 128K Active (Project Glasswing only)
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
Claude Sonnet 5 claude-sonnet-5 — 1M 128K Active
Claude Sonnet 4.6 claude-sonnet-4-6 - 1M 128K Active
Claude Haiku 4.5 claude-haiku-4-5 claude-haiku-4-5-20251001 200K 64K Active

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 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.
  • Claude Sonnet 4.6 — Previous-generation Sonnet. Supports adaptive thinking (recommended). 1M context window. 128K max output tokens.
  • Claude Haiku 4.5 — Fastest and most cost-effective model for simple tasks.

Legacy Models (still active)

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 Sonnet 4.5 claude-sonnet-4-5 claude-sonnet-4-5-20250929 Active

Deprecated Models (retiring soon)

Friendly Name Alias (use this) Full ID Status Retires
Claude Sonnet 4 claude-sonnet-4-0 claude-sonnet-4-20250514 Deprecated TBD
Claude Opus 4 claude-opus-4-0 claude-opus-4-20250514 Deprecated TBD
Claude Haiku 3 — claude-3-haiku-20240307 Deprecated Apr 19, 2026

Retired Models (no longer available)

Friendly Name Full ID Retired
Claude Sonnet 3.7 claude-3-7-sonnet-20250219 Feb 19, 2026
Claude Haiku 3.5 claude-3-5-haiku-20241022 Feb 19, 2026
Claude Opus 3 claude-3-opus-20240229 Jan 5, 2026
Claude Sonnet 3.5 claude-3-5-sonnet-20241022 Oct 28, 2025
Claude Sonnet 3.5 claude-3-5-sonnet-20240620 Oct 28, 2025
Claude Sonnet 3 claude-3-sonnet-20240229 Jul 21, 2025
Claude 2.1 claude-2.1 Jul 21, 2025
Claude 2.0 claude-2.0 Jul 21, 2025

Resolving User Requests

When a user asks for a model by name, use this table to find the correct model ID:

User says... Use this model ID
"fable", "most capable model" claude-fable-5
"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 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)
"sonnet", "balanced" claude-sonnet-5
"sonnet 5" claude-sonnet-5
"sonnet 4.6" claude-sonnet-4-6
"sonnet 4.5" claude-sonnet-4-5
"sonnet 4", "sonnet 4.0" claude-sonnet-4-0 (deprecated — suggest claude-sonnet-5)
"sonnet 3.7" Retired — suggest claude-sonnet-5
"sonnet 3.5" Retired — suggest claude-sonnet-5
"haiku", "fast", "cheap" claude-haiku-4-5
"haiku 4.5" claude-haiku-4-5
"haiku 3.5" Retired — suggest claude-haiku-4-5
"haiku 3" Deprecated — suggest claude-haiku-4-5

Platform Availability

Which features work on which provider platform. This table is the single source of truth in this skill — per-feature sections elsewhere point here instead of restating availability. When writing code for a third-party platform (Bedrock, Vertex, Foundry) or Claude Platform on AWS, check this table first; a feature not supported there means use the first-party Claude API surface or a different approach.

Columns: 1P = first-party Claude API, P-AWS = Claude Platform on AWS (Anthropic-operated, same-day parity), Bedrock = Amazon Bedrock, Vertex = Google Cloud Vertex AI, Foundry = Microsoft Foundry. ✅ = GA, β = beta, ❌ = not supported.

Feature 1P P-AWS Bedrock Vertex Foundry Notes
Messages, streaming, tool use ✅ ✅ ✅ ✅ ✅ Core API
PDF input ✅ ✅ ✅ ✅ β
Structured outputs / strict tool use ✅ ✅ ✅ ✅ β
Adaptive thinking / effort ✅ ✅ ✅ ✅ β
Extended thinking ✅ ✅ ✅ ✅ β
Prompt caching (5m, 1h) ✅ ✅ ✅ ✅ β
Automatic prompt caching ✅ ✅ ❌ ❌ β
Token counting ✅ ✅ ✅ ✅ β
Citations ✅ ✅ ✅ ✅ β
Search results content blocks ✅ ✅ ✅ ✅ β
Fine-grained tool streaming ✅ ✅ ✅ ✅ ✅
Compaction β β β β β
Context editing β β β β β
Context windows (1M) ✅ ✅ ✅ ✅ β
inference_geo (data residency) ✅ ✅ ❌ ❌ ❌
Server-side tools
  Web search ✅ ✅ ❌ ✅ β Vertex: basic web_search_20250305 only (no _20260209 dynamic filtering)
  Web fetch ✅ ✅ ❌ ❌ β
  Code execution ✅ ✅ ❌ ❌ β
  Tool search ✅ ✅ ✅ ✅ β Bedrock: InvokeModel API only, not Converse
  Advisor tool β β ❌ ❌ ❌
Client-implemented tools
  Bash, text editor, memory ✅ ✅ ✅ ✅ β
  Computer use β β β β β
Agentic / orchestration
  Agent Skills (Messages API) β β ❌ ❌ β
  Programmatic tool calling ✅ ✅ ❌ ❌ β
  MCP connector β β ❌ ❌ β
  Managed Agents β β ❌ ❌ ❌ Foundry ❌ inferred (not in Foundry docs either way)
  Self-hosted sandboxes β β ❌ ❌ ❌ P-AWS: GET /v1/environments/{id}/work list endpoint not supported; other work endpoints OK
API endpoints
  Message Batches ✅ ✅ ❌ ❌ ❌
  Files API β β ❌ ❌ β
  Models API ✅ ✅ ❌ ❌ ❌
Other
  Mid-conversation system messages ✅ ✅ ❌ ❌ ❌ Claude Opus 4.8 only
  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

Prompt Caching — Design & Optimization

This file covers how to design prompt-building code for effective caching. For language-specific syntax, see the ## Prompt Caching section in each language's README or single-file doc.

The one invariant everything follows from

Prompt caching is a prefix match. Any change anywhere in the prefix invalidates everything after it.

The cache key is derived from the exact bytes of the rendered prompt up to each cache_control breakpoint. A single byte difference at position N — a timestamp, a reordered JSON key, a different tool in the list — invalidates the cache for all breakpoints at positions ≥ N.

Render order is: tools → system → messages. A breakpoint on the last system block caches both tools and system together.

Design the prompt-building path around this constraint. Get the ordering right and most caching works for free. Get it wrong and no amount of cache_control markers will help.

Workflow for optimizing existing code

When asked to add or optimize caching:

  1. Trace the prompt assembly path. Find where system, tools, and messages are constructed. Identify every input that flows into them.
  2. Classify each input by stability:
  3. Never changes → belongs early in the prompt, before any breakpoint
  4. Changes per-session → belongs after the global prefix, cache per-session
  5. Changes per-turn → belongs at the end, after the last breakpoint
  6. Changes per-request (timestamps, UUIDs, random IDs) → eliminate or move to the very end
  7. Check rendered order matches stability order. Stable content must physically precede volatile content. If a timestamp is interpolated into the system prompt header, everything after it is uncacheable regardless of markers.
  8. Place breakpoints at stability boundaries. See placement patterns below.
  9. Audit for silent invalidators. See anti-patterns table.

Placement patterns

Large system prompt shared across many requests

Put a breakpoint on the last system text block. If there are tools, they render before system — the marker on the last system block caches tools + system together.

"system": [
  {"type": "text", "text": "<large shared prompt>", "cache_control": {"type": "ephemeral"}}
]

Multi-turn conversations

Put a breakpoint on the last content block of the most-recently-appended turn. Each subsequent request reuses the entire prior conversation prefix. Earlier breakpoints remain valid read points, so hits accrue incrementally as the conversation grows.

// Last content block of the last user turn
messages[-1].content[-1].cache_control = {"type": "ephemeral"}

Shared prefix, varying suffix

Many requests share a large fixed preamble (few-shot examples, retrieved docs, instructions) but differ in the final question. Put the breakpoint at the end of the shared portion, not at the end of the whole prompt — otherwise every request writes a distinct cache entry and nothing is ever read.

"messages": [{"role": "user", "content": [
  {"type": "text", "text": "<shared context>", "cache_control": {"type": "ephemeral"}},
  {"type": "text", "text": "<varying question>"}  // no marker — differs every time
]}]

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.

// Top-level system stays byte-identical; new instruction goes after the cached history
"system": [{"type": "text", "text": "<stable core>", "cache_control": {"type": "ephemeral"}}],
"messages": [
  ...history,
  {"role": "user", "content": "..."},
  {"role": "system", "content": "Terse mode enabled — keep responses under 40 words."}
]

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.

Prompts that change from the beginning every time

Don't cache. If the first 1K tokens differ per request, there is no reusable prefix. Adding cache_control only pays the cache-write premium with zero reads. Leave it off.

Architectural guidance

These are the decisions that matter more than marker placement. Fix these first.

Keep the system prompt frozen. Don't interpolate "current date: X", "mode: Y", "user name: Z" into the system prompt — those sit at the front of the prefix and invalidate everything downstream. Inject dynamic context later in messages instead — as a {"role": "system", ...} message where supported (see § Mid-conversation system messages above), or as text in a user message otherwise. A message at turn 5 invalidates nothing before turn 5.

Don't change tools or model mid-conversation. Tools render at position 0; adding, removing, or reordering a tool invalidates the entire cache. Same for switching models (caches are model-scoped). If you need "modes", don't swap the tool set — give Claude a tool that records the mode transition, or pass the mode as message content. Serialize tools deterministically (sort by name).

Fork operations must reuse the parent's exact prefix. Side computations (summarization, compaction, sub-agents) often spin up a separate API call. If the fork rebuilds system / tools / model with any difference, it misses the parent's cache entirely. Copy the parent's system, tools, and model verbatim, then append fork-specific content at the end.

Silent invalidators

When reviewing code, grep for these inside anything that feeds the prompt prefix:

Pattern Why it breaks caching
datetime.now() / Date.now() / time.time() in system prompt Prefix changes every request
uuid4() / crypto.randomUUID() / request IDs early in content Same — every request is unique
json.dumps(d) without sort_keys=True / iterating a set Non-deterministic serialization → prefix bytes differ
f-string interpolating session/user ID into system prompt Per-user prefix; no cross-user sharing
Conditional system sections (if flag: system += ...) Every flag combination is a distinct prefix
tools=build_tools(user) where set varies per user Tools render at position 0; nothing caches across users

Fix by moving the dynamic piece after the last breakpoint, making it deterministic, or deleting it if it's not load-bearing.

API reference

"cache_control": {"type": "ephemeral"}              // 5-minute TTL (default)
"cache_control": {"type": "ephemeral", "ttl": "1h"} // 1-hour TTL
  • Max 4 cache_control breakpoints per request.
  • Goes on any content block: system text blocks, tool definitions, message content blocks (text, image, tool_use, tool_result, document).
  • Top-level cache_control on messages.create() auto-places on the last cacheable block — simplest option when you don't need fine-grained placement.
  • Minimum cacheable prefix is model-dependent. Shorter prefixes silently won't cache even with a marker — no error, just cache_creation_input_tokens: 0:
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

A 3K-token prompt caches on Sonnet 4.5 and Fable 5 but silently won't on Opus 4.8.

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.

Verifying cache hits

The response usage object reports cache activity:

Field Meaning
cache_creation_input_tokens Tokens written to cache this request (you paid the ~1.25× write premium)
cache_read_input_tokens Tokens served from cache this request (you paid ~0.1×)
input_tokens Tokens processed at full price (not cached)

If cache_read_input_tokens is zero across repeated requests with identical prefixes, a silent invalidator is at work — diff the rendered prompt bytes between two requests to find it.

input_tokens is the uncached remainder only. Total prompt size = input_tokens + cache_creation_input_tokens + cache_read_input_tokens. If your agent ran for hours but input_tokens shows 4K, the rest was served from cache — check the sum, not the single field.

Language-specific access: response.usage.cache_read_input_tokens (Python/TS/Ruby), $message->usage->cacheReadInputTokens (PHP), resp.Usage.CacheReadInputTokens (Go/C#), .usage().cacheReadInputTokens() (Java).

Invalidation hierarchy

Not every parameter change invalidates everything. The API has three cache tiers, and changes only invalidate their own tier and below:

Change Tools cache System cache Messages cache
Tool definitions (add/remove/reorder) ❌ ❌ ❌
Model switch ❌ ❌ ❌
speed, web-search, citations toggle ✅ ❌ ❌
System prompt content ✅ ❌ ❌
tool_choice, images, thinking enable/disable ✅ ✅ ❌
Message content ✅ ✅ ❌

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.

20-block lookback window

Each breakpoint walks backward at most 20 content blocks to find a prior cache entry. If a single turn adds more than 20 blocks (common in agentic loops with many tool_use/tool_result pairs), the next request's breakpoint won't find the previous cache and silently misses.

Fix: place an intermediate breakpoint every ~15 blocks in long turns, or put the marker on a block that's within 20 of the previous turn's last cached block.

Concurrent-request timing

A cache entry becomes readable only after the first response begins streaming. N parallel requests with identical prefixes all pay full price — none can read what the others are still writing.

For fan-out patterns: send 1 request, await the first streamed token (not the full response), then fire the remaining N−1. They'll read the cache the first one just wrote.

Pre-warming the cache

To eliminate the cache-miss latency on the first real request, send a max_tokens: 0 request at startup (or on an interval). The API runs prefill — writing the cache at your cache_control breakpoint — and returns immediately with content: [], stop_reason: "max_tokens", and a populated usage block (zero output tokens billed; normal cache-write charge on cache_creation_input_tokens).

When to pre-warm — pre-warming trades a cache-write charge now for lower TTFT on the next real request. It's worth it when all three hold: (a) first-request latency is user-visible (chat/voice/interactive — not background jobs), (b) the shared prefix is large enough that a cold write is noticeably slow, and (c) there's a moment before traffic to fire it — app startup, worker boot, post-deploy, start of a scheduled window.

Skip pre-warming when… Because
Traffic is continuous (requests ≤ TTL apart) The first real request warms the cache and every subsequent one hits it; a separate warm call is a pure extra write
The prefix is small or below the cacheable minimum The cold-write penalty is negligible
The prefix varies per request/user Nothing shared to pre-warm
You'd pre-warm many distinct prefixes speculatively Each is a ~1.25× write; cost can exceed the latency you save

Scheduled re-warms: only needed when traffic has gaps longer than the TTL. If real requests arrive more often than every 5 minutes, they keep the cache warm on their own — don't add an interval re-warm. For bursty traffic with long idle gaps, either re-warm just under the TTL or switch to ttl: "1h" and re-warm less often.

client.messages.create(
    model="claude-opus-4-8",
    max_tokens=0,
    system=[{
        "type": "text",
        "text": SYSTEM_PROMPT,
        "cache_control": {"type": "ephemeral"},
    }],
    messages=[{"role": "user", "content": "warmup"}],
)

Breakpoint placement: put cache_control on the last block shared with the real request (the system prompt or tool definitions) — not on the placeholder user message, and not via top-level automatic caching (which would key the cache to the placeholder). The placeholder can be any non-whitespace string; it's read during prefill but never answered.

Rejected combinations: max_tokens: 0 is an invalid_request_error with stream: true, thinking.type: "enabled", output_config.format, tool_choice of {"type":"tool"} or {"type":"any"}, or inside a Message Batches request.

TTL still applies — re-warm at least every 5 minutes for the default cache, or use the 1-hour TTL. This replaces the older max_tokens: 1 workaround (no single-token reply to discard, no output tokens billed, intent is unambiguous).

Token Counting

Use the count_tokens endpoint (POST /v1/messages/count_tokens) for accurate token counts against Claude models. Token counts are model-specific — pass the same model ID you'll use for inference.

Do not use tiktoken. It's OpenAI's tokenizer. It undercounts Claude tokens by ~15–20% on typical text, and by much more on code or non-English input. Any estimate from tiktoken, gpt-tokenizer, or similar is wrong for Claude.

Count a file or string

from anthropic import Anthropic

client = Anthropic()
resp = client.messages.count_tokens(
    model="claude-opus-4-8",
    messages=[{"role": "user", "content": open("CLAUDE.md").read()}],
)
print(resp.input_tokens)

TypeScript: await client.messages.countTokens({model, messages}) → .input_tokens. See {lang}/claude-api/README.md for other SDKs.

CLI

ant messages count-tokens --model claude-opus-4-8 \
  --message '{role: user, content: "@./CLAUDE.md"}' \
  --transform input_tokens -r

Diffing a file across two versions

The endpoint is stateless — count each version separately and subtract:

from anthropic import Anthropic
import subprocess

client = Anthropic()
def count(text: str) -> int:
    return client.messages.count_tokens(
        model="claude-opus-4-8",
        messages=[{"role": "user", "content": text}],
    ).input_tokens

before = subprocess.check_output(["git", "show", "HEAD:CLAUDE.md"], text=True)
after = open("CLAUDE.md").read()
print(count(after) - count(before))

Full docs: see the Token Counting entry in shared/live-sources.md.

Tool Use Concepts

This file covers the conceptual foundations of tool use with the Claude API. For language-specific code examples, see the python/, typescript/, or other language folders. For decision heuristics on which tools to expose, how to manage context in long-running agents, and caching strategy, see agent-design.md.

User-Defined Tools

Tool Definition Structure

Note: When using the Tool Runner (beta), tool schemas are generated automatically from your function signatures (Python), Zod schemas (TypeScript), annotated classes (Java), jsonschema struct tags (Go), or BaseTool subclasses (Ruby). The raw JSON schema format below is for the manual approach — including PHP's BetaRunnableTool, which wraps a run closure around a hand-written schema — or SDKs without tool runner support.

Each tool requires a name, description, and JSON Schema for its inputs:

{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City and state, e.g., San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "Temperature unit"
      }
    },
    "required": ["location"]
  }
}

Best practices for tool definitions:

  • Use clear, descriptive names (e.g., get_weather, search_database, send_email)
  • Write detailed descriptions — Claude uses these to decide when to use the tool. Be prescriptive about when to call it, not just what it does (e.g. "Call this when the user asks about current prices or recent events"). On recent Opus models, which reach for tools more conservatively, trigger conditions in the description give measurable lift in should-call rate.
  • Include descriptions for each property
  • Use enum for parameters with a fixed set of values
  • Mark truly required parameters in required; make others optional with defaults

Tool Choice Options

Control when Claude uses tools:

Value Behavior
{"type": "auto"} Claude decides whether to use tools (default)
{"type": "any"} Claude must use at least one tool
{"type": "tool", "name": "..."} Claude must use the specified tool
{"type": "none"} Claude cannot use tools

Any tool_choice value can also include "disable_parallel_tool_use": true to force Claude to use at most one tool per response. By default, Claude may request multiple tool calls in a single response.

Tool Runner vs Manual Loop

Tool Runner (Recommended): The SDK's tool runner handles the agentic loop automatically — it calls the API, detects tool use requests, executes your tool functions, feeds results back to Claude, and repeats until Claude stops calling tools. Available in Python, TypeScript, Java, Go, Ruby, and PHP SDKs (beta). The Python SDK also provides MCP conversion helpers (anthropic.lib.tools.mcp) to convert MCP tools, prompts, and resources for use with the tool runner — see python/claude-api/tool-use.md for details.

Manual Agentic Loop: Use when you need fine-grained control over the loop (e.g., custom logging, conditional tool execution, human-in-the-loop approval). Loop until stop_reason == "end_turn", always append the full response.content to preserve tool_use blocks, and ensure each tool_result includes the matching tool_use_id.

Stop reasons for server-side tools: When using server-side tools (code execution, web search, etc.), the API runs a server-side sampling loop. If this loop reaches its default limit of 10 iterations, the response will have stop_reason: "pause_turn". To continue, re-send the user message and assistant response and make another API request — the server will resume where it left off. Do NOT add an extra user message like "Continue." — the API detects the trailing server_tool_use block and knows to resume automatically.

# Handle pause_turn in your agentic loop
if response.stop_reason == "pause_turn":
    messages = [
        {"role": "user", "content": user_query},
        {"role": "assistant", "content": response.content},
    ]
    # Make another API request — server resumes automatically
    response = client.messages.create(
        model="claude-opus-4-8", messages=messages, tools=tools
    )

Set a max_continuations limit (e.g., 5) to prevent infinite loops. For the full guide, see: https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons

Security: The tool runner executes your tool functions automatically whenever Claude requests them. For tools with side effects (sending emails, modifying databases, financial transactions), validate inputs within your tool functions and consider requiring confirmation for destructive operations. Use the manual agentic loop if you need human-in-the-loop approval before each tool execution.

Handling Tool Results

When Claude uses a tool, the response contains a tool_use block. You must:

  1. Execute the tool with the provided input
  2. Send the result back in a tool_result message
  3. Continue the conversation

Error handling in tool results: When a tool execution fails, set "is_error": true and provide an informative error message. Claude will typically acknowledge the error and either try a different approach or ask for clarification.

Multiple tool calls: Claude can request multiple tools in a single response. Handle them all before continuing — send all results back in a single user message.

Server-Side Tools: Code Execution

The code execution tool lets Claude run code in a secure, sandboxed container. Unlike user-defined tools, server-side tools run on Anthropic's infrastructure — you don't execute anything client-side. Just include the tool definition and Claude handles the rest.

Key Facts

  • Runs in an isolated container (1 CPU, 5 GiB RAM, 5 GiB disk)
  • No internet access (fully sandboxed)
  • Python 3.11 with data science libraries pre-installed
  • Containers persist for 30 days and can be reused across requests
  • Free when used with web search/web fetch tools; otherwise $0.05/hour after 1,550 free hours/month per organization

Tool Definition

The tool requires no schema — just declare it in the tools array:

{
  "type": "code_execution_20260120",
  "name": "code_execution"
}

Claude automatically gains access to bash_code_execution (run shell commands) and text_editor_code_execution (create/view/edit files).

Pre-installed Python Libraries

  • Data science: pandas, numpy, scipy, scikit-learn, statsmodels
  • Visualization: matplotlib, seaborn
  • File processing: openpyxl, xlsxwriter, pillow, pypdf, pdfplumber, python-docx, python-pptx
  • Math: sympy, mpmath
  • Utilities: tqdm, python-dateutil, pytz, sqlite3

Additional packages can be installed at runtime via pip install.

Supported File Types for Upload

Type Extensions
Data CSV, Excel (.xlsx/.xls), JSON, XML
Images JPEG, PNG, GIF, WebP
Text .txt, .md, .py, .js, etc.

Container Reuse

Reuse containers across requests to maintain state (files, installed packages, variables). Extract the container_id from the first response and pass it to subsequent requests.

Response Structure

The response contains interleaved text and tool result blocks:

  • text — Claude's explanation
  • server_tool_use — What Claude is doing
  • bash_code_execution_tool_result — Code execution output (check return_code for success/failure)
  • text_editor_code_execution_tool_result — File operation results

Security: Always sanitize filenames with os.path.basename() / path.basename() before writing downloaded files to disk to prevent path traversal attacks. Write files to a dedicated output directory.

Server-Side Tools: Web Search and Web Fetch

Web search and web fetch let Claude search the web and retrieve page content. They run server-side — just include the tool definitions and Claude handles queries, fetching, and result processing automatically.

Tool Definitions

[
  { "type": "web_search_20260209", "name": "web_search" },
  { "type": "web_fetch_20260209", "name": "web_fetch" }
]

Dynamic Filtering (Fable 5 / Opus 4.8 / Opus 4.7 / Opus 4.6 / 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.

{
  "tools": [
    { "type": "web_search_20260209", "name": "web_search" },
    { "type": "web_fetch_20260209", "name": "web_fetch" }
  ]
}

Without dynamic filtering, the previous web_search_20250305 version is also available.

Note: Only include the standalone code_execution tool when your application needs code execution for its own purposes (data analysis, file processing, visualization) independent of web search. Including it alongside _20260209 web tools creates a second execution environment that can confuse the model.

Server-Side Tools: Programmatic Tool Calling

With standard tool use, each tool call is a round trip: Claude calls, the result enters Claude's context, Claude reasons, then calls the next tool. Chained calls accumulate latency and tokens — most of that intermediate data is never needed again.

Programmatic tool calling lets Claude compose those calls into a script. The script runs in the code execution container; when it invokes a tool, the container pauses, the call executes, and the result returns to the running code (not to Claude's context). The script processes it with normal control flow. Only the final output returns to Claude. Use it when chaining many tool calls or when intermediate results are large and should be filtered before reaching the context window.

For full documentation, use WebFetch:

  • URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling

Server-Side Tools: Tool Search

The tool search tool lets Claude dynamically discover tools from large libraries without loading all definitions into the context window. Use it when you have many tools but only a few are relevant to any given request. Discovered tool schemas are appended to the request, not swapped in — this preserves the prompt cache (see agent-design.md §Caching for Agents).

For full documentation, use WebFetch:

  • URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool

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.

Required on each request:

  1. client.beta.messages.create(...) with both beta flags: code-execution-2025-08-25 and skills-2025-10-02.
  2. container={"skills": [{"type": "anthropic", "skill_id": "<id>", "version": "latest"}]} — the skills list selects which skills are available inside the execution container.
  3. tools=[{"type": "code_execution_20260521", "name": "code_execution"}] — skills execute via code execution in the container.
response = client.beta.messages.create(
    model="claude-opus-4-8", 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"}],
    messages=[{"role": "user", "content": "Create a 3-slide presentation on X"}],
)

Generated files (.pptx, .xlsx, …) are written inside the container; the response carries a file ID for each. Download by passing that ID to the Files API (client.beta.files.download(file_id) / GET /v1/files/{id}/content with anthropic-beta: files-api-2025-04-14).

List available skills via GET /v1/skills (requires anthropic-beta: skills-2025-10-02).

MCP Connector (Beta)

The MCP connector lets Claude call tools hosted on a remote MCP server directly from the Messages API — Anthropic makes the MCP connection server-side. Requires beta flag mcp-client-2025-11-20 on client.beta.messages.create(...). Availability: see shared/platform-availability.md.

Two parameters are required together:

  • mcp_servers — array of server connection definitions: [{"type": "url", "url": "<server URL>", "name": "<server-name>", "authorization_token": "<optional>"}]
  • tools — must include an mcp_toolset entry that references the server by name: [{"type": "mcp_toolset", "mcp_server_name": "<server-name>"}]

The mcp_server_name in the toolset must match a name in mcp_servers. Omitting the mcp_toolset entry is rejected as a validation error — every server in mcp_servers must be referenced by exactly one toolset.

client.beta.messages.create(
    model="claude-opus-4-8", 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"}],
    messages=[...],
)

Go uses the typed constant anthropic.AnthropicBetaMCPClient2025_11_20; the older …2025_04_04 constant is deprecated.

Optional toolset fields: default_config (defaults for all tools, e.g. {"enabled": false} for allowlist mode) and configs (per-tool overrides keyed by tool name).

Tool Use Examples

You can provide sample tool calls directly in your tool definitions to demonstrate usage patterns and reduce parameter errors. This helps Claude understand how to correctly format tool inputs, especially for tools with complex schemas.

For full documentation, use WebFetch:

  • URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use

Client-Side Tools: Computer Use

Computer use lets Claude interact with a desktop environment (screenshots, mouse, keyboard). It is a client-side tool — your application provides the environment and executes the actions Claude requests; Anthropic processes the screenshots and action requests in real time but does not host the environment or retain the data.

For full documentation, use WebFetch:

  • URL: https://platform.claude.com/docs/en/agents-and-tools/computer-use/overview

Context Editing

Context editing clears stale tool results and thinking blocks from the transcript as a long-running agent accumulates turns. Unlike compaction (which summarizes), context editing prunes — the cleared content is removed, not replaced. Use it when old tool outputs are no longer relevant and you want to keep the transcript lean without losing the conversation structure.

Beta. Use client.beta.messages.* with beta context-management-2025-06-27. Configure via context_management.edits with a strategy type of clear_tool_uses_20250919 (clear old tool results; optional clear_tool_inputs: true also clears the tool_use params) or clear_thinking_20251015 (clear thinking blocks). These are not the compaction types — compact_20260112 with beta compact-2026-01-12 is the separate compaction feature.

For full documentation, use WebFetch:

  • URL: https://platform.claude.com/docs/en/build-with-claude/context-editing

Server-Side Tools: Advisor (Beta)

The advisor tool pairs a faster, lower-cost executor model (the top-level model on the request) with a higher-intelligence advisor model (the model field inside the tool definition) that provides strategic guidance mid-generation. The executor does most of the token generation; the advisor is consulted for planning. Availability: see shared/platform-availability.md.

Tool Definition

{
  "type": "advisor_20260301",
  "name": "advisor",
  "model": "claude-opus-4-8"
}

The advisor model must be at least as capable as the executor. An invalid pairing returns 400 invalid_request_error. Valid pairs:

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

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.

Client-Side Tools: Memory

The memory tool enables Claude to store and retrieve information across conversations through a memory file directory. Claude can create, read, update, and delete files that persist between sessions.

Key Facts

  • Client-side tool — you control storage via your implementation
  • Supports commands: view, create, str_replace, insert, delete, rename
  • Operates on files in a /memories directory
  • The Python, TypeScript, and Java SDKs provide helper classes/functions for implementing the memory backend

Security: Never store API keys, passwords, tokens, or other secrets in memory files. Be cautious with personally identifiable information (PII) — check data privacy regulations (GDPR, CCPA) before persisting user data. The reference implementations have no built-in access control; in multi-user systems, implement per-user memory directories and authentication in your tool handlers.

For full implementation examples, use WebFetch:

  • Docs: https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool.md

Client-Side Tools: Bash and Text Editor

The bash and text editor tools are Anthropic-defined, schema-less tools. Declare them by type and name only — the input schema is built into the model and cannot be modified. Do not pass an input_schema, and do not define a custom tool that happens to be named "bash" — that creates a user-defined tool without the built-in behavior.

Both are client-executed: Claude returns a tool_use block, your code performs the action locally, and you send back a tool_result. The API is stateless; your application maintains the shell session or filesystem between turns.

Bash tool declaration

{"type": "bash_20250124", "name": "bash"}
Language Declaration
Python / TypeScript / Ruby / cURL plain object {"type": "bash_20250124", "name": "bash"}
Go anthropic.ToolUnionParam{OfBashTool20250124: &anthropic.ToolBash20250124Param{}}
Java .addTool(ToolBash20250124.builder().build()) from com.anthropic.models.messages
C# Tools = [new ToolBash20250124()] from Anthropic.Models.Messages
PHP tools: [new \Anthropic\Messages\ToolBash20250124()]

Claude's tool_use.input contains either {"command": "<string>"} or {"restart": true}. Check for restart first (reset the session, return a confirmation string); otherwise run command and return combined stdout + stderr.

Security — commands are untrusted model output. Run in an isolated environment (container, VM, or restricted user); apply an allowlist of permitted executables and reject shell operators (&&, |, ;, `, $()); set timeouts and resource limits; log every command. A blocklist is not sufficient.

Text editor tool declaration

{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}

Optional field: max_characters to cap view output. Java exposes a typed ToolTextEditor20250728 builder (com.anthropic.models.messages); other statically-typed SDKs follow the same naming pattern — see the Anthropic-Defined Tools section in {lang}/claude-api/tool-use.md for the exact class.

Security — path is untrusted model output. Confine every file operation to a fixed project root. Before executing any command, resolve the model-supplied path to its canonical form and verify it remains within your project root; reject the request if it escapes (.., symlinks, absolute paths outside the root, URL-encoded traversal like %2e%2e%2f). Use your language's built-in path utilities (e.g., Python pathlib.Path.resolve() then check .is_relative_to(root)). Never call open() / writeFile / unlink directly on the raw path value.

tool_use.input.command is one of:

command Other inputs Action
view path, optional view_range Return file contents or directory listing
create path, file_text Create/overwrite file with file_text. Create a backup if the file already exists.
str_replace path, old_str, new_str Replace exactly one occurrence; error if 0 or >1 matches
insert path, insert_line, insert_text Insert insert_text after line insert_line (0 = beginning of file)

For both tools, on error return {"type": "tool_result", "tool_use_id": "…", "content": "<error text>", "is_error": true} so Claude can recover.

Structured Outputs

Structured outputs constrain Claude's responses to follow a specific JSON schema, guaranteeing valid, parseable output. This is not a separate tool — it enhances the Messages API response format and/or tool parameter validation.

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.

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.

JSON Schema Limitations

Supported:

  • Basic types: object, array, string, integer, number, boolean, null
  • enum, const, anyOf, allOf, $ref/$def
  • String formats: date-time, time, date, duration, email, hostname, uri, ipv4, ipv6, uuid
  • additionalProperties: false (required for all objects)

Not supported:

  • Recursive schemas
  • Numerical constraints (minimum, maximum, multipleOf)
  • String constraints (minLength, maxLength)
  • Complex array constraints
  • additionalProperties set to anything other than false

The Python and TypeScript SDKs automatically handle unsupported constraints by removing them from the schema sent to the API and validating them client-side.

Important Notes

  • First request latency: New schemas incur a one-time compilation cost. Subsequent requests with the same schema use a 24-hour cache.
  • Refusals: If Claude refuses for safety reasons (stop_reason: "refusal"), the output may not match your schema.
  • Token limits: If stop_reason: "max_tokens", output may be incomplete. Increase max_tokens.
  • Incompatible with: Citations (returns 400 error), message prefilling.
  • Works with: Batches API, streaming, token counting, extended thinking.

Tips for Effective Tool Use

  1. Provide detailed descriptions: Claude relies heavily on descriptions to understand when and how to use tools
  2. Use specific tool names: get_current_weather is better than weather
  3. Validate inputs: Always validate tool inputs before execution
  4. Handle errors gracefully: Return informative error messages so Claude can adapt
  5. Limit tool count: Too many tools can confuse the model — keep the set focused
  6. Test tool interactions: Verify Claude uses tools correctly in various scenarios

For detailed tool use documentation, use WebFetch:

  • URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview

When to Use WebFetch

Use WebFetch to get the latest documentation when:

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

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

Common Pitfalls

  • No ANTHROPIC_API_KEY ≠ no credentials. Don't bail or ask the user for a key just because the env var is unset — run ant auth status first. After ant auth login, a bare Anthropic() client and ant … work with no env var; for raw curl, use Authorization: Bearer $(ant auth print-credentials --access-token) plus header anthropic-beta: oauth-2025-04-20. See the Authentication quick reference above and shared/anthropic-cli.md.
  • Don't truncate inputs when passing files or content to the API. If the content is too long to fit in the context window, notify the user and discuss options (chunking, summarization, etc.) rather than silently truncating.
  • Fable 5 / Sonnet 5 / Opus 4.8 / 4.7 thinking: Adaptive only. thinking: {type: "enabled", budget_tokens: N} returns 400 — budget_tokens is fully removed (along with temperature, top_p, top_k). Use thinking: {type: "adaptive"}. Opus 4.8 inherits this surface from 4.7 with no new breaking changes; Fable 5 adds one — an explicit thinking: {type: "disabled"} returns a 400 (accepted on Sonnet 5 / 4.7 / 4.8); omit the param instead.
  • Opus 4.6 / Sonnet 4.6 thinking: Use thinking: {type: "adaptive"} — do NOT use budget_tokens for new 4.6 code (deprecated on both Opus 4.6 and Sonnet 4.6; for gradual migration of existing code, see the transitional escape hatch in shared/model-migration.md — note this carve-out does not apply to Fable 5, Opus 4.7 or 4.8). For older models, budget_tokens must be less than max_tokens (minimum 1024). This will throw an error if you get it wrong.
  • Prefill removed (Fable 5 and the 4.6/4.7/4.8 family): Assistant message prefills (last-assistant-turn prefills) return a 400 error on Fable 5, Opus 4.6, Opus 4.7, Opus 4.8, and Sonnet 4.6. Use structured outputs (output_config.format) or system prompt instructions to control response format instead. (One exception: the fallback-credit prefill claim — when redeeming a credit with fallback_has_prefill_claim: true, the server accepts the echoed assistant message; see the migration guide's refusal section.)
  • Fable 5 refusal stop reason: Safety classifiers may decline a request — a successful HTTP 200 with stop_reason: "refusal" (pre-output: empty content, nothing billed; mid-stream: partial output billed — discard it). Check stop_reason before reading response.content[0], or you'll hit index errors on refused requests. To retry on another model, replay the history as-is — other models drop the refused model's thinking blocks from the prompt, unbilled; no stripping needed (and a fallback-credit redemption must echo the refused body exactly anyway, thinking blocks included). Fallbacks are opt-in — new claude-fable-5 code should include the server-side fallbacks parameter by default so a refusal doesn't fail the request outright; see the Claude Fable 5 section above.
  • Fable 5 tokenizer: Same tokenizer as Opus 4.8 — token counts are roughly unchanged when migrating from Opus 4.7/4.8. Coming from Opus 4.6, Sonnet, Haiku, or older, token counts differ (the Opus 4.7 tokenizer uses ~1×–1.35× as many tokens) — re-measure by calling count_tokens once with each model and comparing input_tokens.
  • Confirm migration scope before editing: When a user asks to migrate code to a newer Claude model without naming a specific file, directory, or file list, ask which scope to apply first — the entire working directory, a specific subdirectory, or a specific set of files. Do not start editing until the user confirms. Imperative phrasings like "migrate my codebase", "move my project to X", "upgrade to Sonnet 4.6", or bare "migrate to Opus 4.8" are still ambiguous — they tell you what to do but not where, so ask. Proceed without asking only when the prompt names an exact file, a specific directory, or an explicit file list ("migrate app.py", "migrate everything under services/", "update a.py and b.py"). See shared/model-migration.md Step 0.
  • max_tokens defaults: Don't lowball max_tokens — hitting the cap truncates output mid-thought and requires a retry. For non-streaming requests, default to ~16000 (keeps responses under SDK HTTP timeouts). For streaming requests, default to ~64000 (timeouts aren't a concern, so give the model room). Only go lower when you have a hard reason: classification (~256), cost caps, deliberately short outputs, or max_tokens: 0 for cache pre-warming (see shared/prompt-caching.md → Pre-warming).
  • 128K output tokens: Fable 5, Opus 4.6, Opus 4.7, Opus 4.8, Sonnet 5, and Sonnet 4.6 support up to 128K max_tokens, but the SDKs require streaming for values that large to avoid HTTP timeouts. Use .stream() with .get_final_message() / .finalMessage().
  • Tool call JSON parsing (Fable 5 and the 4.6/4.7/4.8 family): Fable 5, Opus 4.6, Opus 4.7, Opus 4.8, and Sonnet 4.6 may produce different JSON string escaping in tool call input fields (e.g., Unicode or forward-slash escaping). Always parse tool inputs with json.loads() / JSON.parse() — never do raw string matching on the serialized input.
  • Structured outputs (all models): Use output_config: {format: {...}} instead of the deprecated output_format parameter on messages.create(). This is a general API change, not 4.6-specific.
  • Don't reimplement SDK functionality: The SDK provides high-level helpers — use them instead of building from scratch. Specifically: use stream.finalMessage() instead of wrapping .on() events in new Promise(); use typed exception classes (Anthropic.RateLimitError, etc.) instead of string-matching error messages; use SDK types (Anthropic.MessageParam, Anthropic.Tool, Anthropic.Message, etc.) instead of redefining equivalent interfaces.
  • Error handling — catch a chain, not one broad class. A single except APIStatusError / catch (AnthropicServiceException) / rescue APIError loses the distinction between retryable (429, ≥500, network) and non-retryable (400/404) failures. Write a most-specific-first chain — e.g. NotFoundError → RateLimitError → APIStatusError → APIConnectionError (or the Go equivalent: errors.As into *anthropic.Error then switch apierr.StatusCode { case 404: …; case 429: …; default: … }). Per-language class names and namespaces are in shared/error-codes.md.
  • Don't research SDK types — write first. If a type name isn't shown in the documentation included in this skill, write the code file from the namespace/package tables in the language-specific doc and let the compiler's error point you to the right name. Do not spend turns on WebFetch, SDK-repo clones, or compiling-and-running a separate reflection program to discover type names before writing — produce the source file first, then fix what the compiler reports. A quick strings / jar tf / javap against the installed SDK is acceptable for locating names (it returns in seconds), but don't escalate beyond that. A file with a wrong type name is recoverable; a session spent on discovery with no file written is not.
  • Bash and text editor tools are Anthropic-defined, schema-less. Declare {"type": "bash_20250124", "name": "bash"} / {"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"} — no input_schema. A custom tool with your own schema named "bash" is a different tool. Handler paths and security checks are in shared/tool-use-concepts.md § Client-Side Tools.
  • Advisor tool model pairing. The advisor tool's model must be at least as capable as the request's top-level model — e.g. executor claude-sonnet-5 → advisor claude-opus-4-8 or claude-opus-4-7. An invalid pair returns 400. Pairing table in shared/tool-use-concepts.md § Advisor. Availability: shared/platform-availability.md.
  • Agent Skills ≠ Managed Agents. To have Claude generate a .pptx/.xlsx/etc. via Agent Skills, call client.beta.messages.create with container={"skills": [...]}, the code_execution_20260521 tool, and both code-execution-2025-08-25 + skills-2025-10-02 betas. Do not use client.beta.agents / sessions / environments here — those are the Managed Agents surface, not Agent Skills.
  • MCP connector needs both halves. mcp_servers=[{type:"url", url, name}] alone is rejected as a validation error — also add tools=[{type:"mcp_toolset", mcp_server_name:<same name>}] with beta mcp-client-2025-11-20. Availability: shared/platform-availability.md.
  • Context editing ≠ compaction. Context editing clears tool results and thinking blocks; compaction summarizes history. For context editing, use context_management.edits with type clear_tool_uses_20250919 (or clear_thinking_20251015) on client.beta.messages.* with beta context-management-2025-06-27 — not the compact_20260112 type or compact-2026-01-12 beta, which are compaction.
  • inference_geo is a direct top-level request parameter — client.messages.create(..., inference_geo="us") / .inferenceGeo("us"). Do not put it in extra_body / putAdditionalBodyProperty. Supported on Opus 4.6 / Sonnet 4.6 and later; availability: shared/platform-availability.md. response.usage.inference_geo reports where inference ran.
  • Fine-grained tool streaming is not a beta feature. Set eager_input_streaming: true on the tool definition and call the regular client.messages.stream(...). There is no beta header and no client.beta.* path.
  • Cache diagnostics is beta. Use client.beta.messages.* with beta cache-diagnosis-2026-04-07. Pass diagnostics: {previous_message_id: null} on the first turn and diagnostics: {previous_message_id: <previous response id>} on subsequent turns; the result is on response.diagnostics. Availability: shared/platform-availability.md.
  • Memory tool type is memory_20250818. Declare {"type": "memory_20250818", "name": "memory"}. Go uses the beta-namespace type {OfMemoryTool20250818: &anthropic.BetaMemoryTool20250818Param{}} on client.Beta.Messages.New; Python/TypeScript/Ruby/PHP/C# use the non-beta client.messages.create; Java has both a non-beta MemoryTool20250818 and a beta tool-runner path. Python/TypeScript provide BetaAbstractMemoryTool / betaMemoryTool helpers for implementing the backend.
  • Use a model the feature actually supports. Some features are restricted to specific model tiers — fast mode is Opus 4.8 / 4.7 only, task budgets are Fable 5 / Sonnet 5 / Opus 4.8 / 4.7 only, and the advisor tool requires a valid executor↔advisor pair. If the user's prompt names a model that the feature doesn't support, use a supported model instead and note the substitution in the output.
  • Bedrock / Foundry: use the platform client class. For Bedrock use the …BedrockMantle… client (e.g. Python AnthropicBedrockMantle, Java BedrockMantleBackend) with anthropic.-prefixed model IDs; AnthropicBedrock/BedrockBackend without Mantle is the legacy path. For Foundry use AnthropicFoundry / FoundryBackend / AnthropicFoundryClient where the SDK supports it (C#, Java, PHP, Python, TypeScript); Go and Ruby have no Foundry client — Ruby's documented fallback is the first-party client with a custom base_url. Per-language table above.
  • Don't define custom types for SDK data structures: The SDK exports types for all API objects. Use Anthropic.MessageParam for messages, Anthropic.Tool for tool definitions, Anthropic.ToolUseBlock / Anthropic.ToolResultBlockParam for tool results, Anthropic.Message for responses. Defining your own interface ChatMessage { role: string; content: unknown } duplicates what the SDK already provides and loses type safety.
  • Report and document output: For tasks that produce reports, documents, or visualizations, the code execution sandbox has python-docx, python-pptx, matplotlib, pillow, and pypdf pre-installed. Claude can generate formatted files (DOCX, PDF, charts) and return them via the Files API — consider this for "report" or "document" type requests instead of plain stdout text.
  • Server-tool errors don't raise. Web search and web fetch errors return HTTP 200 with a web_search_tool_result / web_fetch_tool_result block whose content is a single error object (e.g. {error_code: "max_uses_exceeded"}) — not a raised exception. For web search, a success content is a list; an error content is an object — branch on that before indexing.
  • Code execution output block type: code_execution_20260521 returns bash_code_execution_tool_result (with .content.stdout), not the legacy bare code_execution_tool_result. Iterate response.content and match on the correct type.
  • Tool search: never defer everything. The search tool itself must not have defer_loading: true, and at least one tool in tools must be non-deferred, or the API returns 400 All tools have defer_loading set.
  • strict: true goes on the tool, not tool_choice. Putting strict on tool_choice does nothing; it's a sibling of name/description/input_schema on the tool definition itself.
  • Parallel tool results go in ONE user message. Splitting tool_result blocks across multiple user messages silently trains Claude to stop making parallel calls. One assistant message of tool_use blocks → one user message of tool_result blocks.
  • Citations + structured outputs are incompatible. Enabling citations: {enabled: true} on a document while also setting output_config.format returns a 400.
  • Batch results are unordered. Match by custom_id, never by position in the results stream.
  • Vertex model IDs have no prefix. Unlike Bedrock's anthropic.-prefixed IDs, Vertex takes the bare first-party ID for current-generation models (e.g. "claude-opus-4-8"); dated-snapshot models use an @ separator (e.g. claude-haiku-4-5@20251001).
  • stop_details is null unless stop_reason == "refusal". For max_tokens, end_turn, etc., stop_details is null — guard before reading .category.
  • WIF auth: unset ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, and ANTHROPIC_PROFILE. ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN (even set to "") outrank Workload Identity Federation in the SDK's precedence chain and silently win; a set ANTHROPIC_PROFILE also wins (a missing named profile is an error, not a fall-through). unset them, don't blank them.

User Request

pricing and model ids for Haiku 4.5, Sonnet 5, Opus 4.8; basic messages API usage with temperature 0

Assistant
⚙ TaskUpdate 
{
  "taskId": "4",
  "status": "in_progress"
}
Result
Updated task #4 status
⚙ PowerShell Check training run progress 
{
  "command": "Get-Content D:\\claude_code\\relational_sparsity\\runs\\validate_stage.log; Get-ChildItem D:\\claude_code\\relational_sparsity\\runs -Filter *.log | ForEach-Object { $last = Get-Content $_.FullName -Tail 1; \"$($_.Name): $last\" }"
}
Result
9 runs to do

start baseline_s0

start rn_full_s0

start rn_oracle_s0

done baseline_s0 (rc=0)

start baseline_s1

done baseline_s1 (rc=0)

start rn_full_s1

baseline_s0.log: }

baseline_s1.log: }

rn_full_s0.log: 5,0.0890,0.9721,0.9487,0.9954,nan,29.6

rn_full_s1.log: rn_full_s1: 71820 params, 288000 train questions

rn_oracle_s0.log: 5,0.0513,0.9808,0.9670,0.9947,nan,29.4

validate_stage.log: start rn_full_s1
⚙ mcp__ccd_session__mark_chapter 
{
  "title": "Experiment C: LLM shape-bias probe",
  "summary": "Designing and building the text-based word-learning bias probe for Claude models"
}
Result
Chapter marked: "Experiment C: LLM shape-bias probe". Continue your current work.
📝 Write DESIGN.md
D:\claude_code\shape_bias\DESIGN.md
# Word-learning biases in LLMs: a text-based shape-bias probe

Riff on: Ritter, Barrett, Santoro & Botvinick (ICML 2017), "Cognitive Psychology
for Deep Neural Networks: A Shape Bias Case Study", which ported the
developmental-psychology shape-bias probe (Landau, Smith & Jones 1988) to
one-shot image classifiers. We port it to text-based novel-word learning in
LLMs (Claude models via API).

## Research questions

1. **RQ1 (default bias):** When an LLM learns a novel word ("this is a dax")
   from a single described exemplar with shape, color, and texture attributes,
   does it extend the word by shape (like children and like Ritter et al.'s
   image models), or by color/texture?
2. **RQ2 (bias variation):** Does the bias differ across models of the same
   family (the analogue of Ritter et al.'s finding that identically-trained
   models with different seeds had very different bias strengths), and how
   consistent is a single model under repeated sampling?
3. **RQ3 (in-context malleability):** In children, the shape bias is *learned*
   (it strengthens with vocabulary development; Smith et al. 2002). Can a few
   in-context demonstrations of *color-based* or *texture-based* word
   extension override the default bias, and how does the override scale with
   the number of demonstrations k? This connects to Santoro's co-authored
   2022 line on data distributional properties driving in-context learning.

## Trial structure (Landau-Smith-Jones forced choice)

Exemplar: an object described by three attributes (shape, color, texture)
plus a novel name, e.g.

> "It is shaped like an arch, crimson in color, and has a waxy texture.
>  We call it 'a dax'."

Three test objects, each sharing EXACTLY ONE attribute with the exemplar:

- shape match   (same shape, new color, new texture)
- color match   (new shape, same color, new texture)
- texture match (new shape, new color, same texture)

No attribute is shared between the three options (6 distractor values per
trial are all distinct). "Which is also a dax?" — forced choice A/B/C,
option order randomized and recorded. Answer must be a single letter.

## Conditions

- **C1 (default bias, RQ1+RQ2):** 60 unique trials per model + 20 fixed
  trials x 3 repeated samples (consistency). No demonstrations.
- **C3 (malleability, RQ3):** k in-context demonstration Q/A pairs
  (independent trials with the answer given), all consistently resolved
  toward one dimension d in {shape, color, texture};
  k in {1, 2, 4, 8}; 30 test trials per (d, k) cell.
  The shape-demonstration condition is the control (demonstrating the
  presumed default should do little); color/texture conditions measure
  override. Answer positions in demos are balanced across A/B/C.

## Models & API settings

- claude-haiku-4-5, claude-sonnet-5, claude-opus-4-8.
- Thinking explicitly disabled (Sonnet 5 defaults to adaptive thinking ON,
  so it must be disabled explicitly; measuring the fast/default association
  is the design intent — thinking-on is a possible follow-up).
- No temperature parameter (not accepted on Sonnet 5 / Opus 4.8); default
  sampling, repeated samples give within-model consistency.
- max_tokens=8 ("Answer with only the letter").

## Counterbalancing & controls

- Attribute values sampled without replacement per trial from pools of 12
  shapes, 12 colors, 12 textures; fresh novel word per trial (24 nonwords).
- Option order (which dimension appears as A/B/C) randomized per trial and
  stored; position bias checked in analysis.
- All stimuli generated with a fixed RNG seed; stored as JSONL before any
  API call, so every model sees identical trials.

## Analysis

- C1: per-model choice shares by dimension with 95% binomial CIs; position-
  bias check; consistency = per-item modal-choice agreement across reps.
- C3: P(choose demonstrated dimension) vs k per model, per dimension, with
  CIs; compare k=0 baseline from C1.
- All raw responses stored; unparsable responses retried once, then counted
  as 'other' (reported).

## Cost estimate (before running; per zork-project principle #4)

~480 calls/model x 3 models = 1440 calls, avg ~450 tokens in / ~10 out:
Haiku ~$0.7, Sonnet 5 ~$1.5 (intro pricing), Opus 4.8 ~$3.6. Total ~$6,
call it <$10 with retries/reruns. Smoke test (~6 Haiku calls) ~$0.01.
Result
File created successfully at: D:\claude_code\shape_bias\DESIGN.md (file state is current in your context — no need to Read it back)
📝 Write stimuli.py
D:\claude_code\shape_bias\stimuli.py
"""Generate forced-choice word-learning trials (see DESIGN.md).

Writes trials.jsonl: one record per API call to make, covering
  C1: 60 unique trials (rep 0) + 20 trials x 3 reps (consistency subset)
  C3: demos toward d in {shape,color,texture} x k in {1,2,4,8} x 30 trials
All models see identical trials.
"""

import json
import random
from pathlib import Path

SHAPES = ["arch", "star", "ring", "cross", "spiral", "wedge", "cube",
          "cylinder", "crescent", "cone", "horseshoe", "pyramid"]
COLORS = ["crimson", "turquoise", "mustard", "lavender", "olive", "teal",
          "magenta", "beige", "maroon", "coral", "indigo", "charcoal"]
TEXTURES = ["waxy", "furry", "metallic", "rubbery", "velvety", "glossy",
            "spongy", "leathery", "gritty", "silky", "bumpy", "prickly"]
NONWORDS = ["dax", "wug", "blicket", "toma", "zav", "fep", "lorp", "mib",
            "pilk", "snod", "tupa", "gorp", "vimble", "kern", "jop", "risp",
            "moke", "fendle", "quib", "surp", "nell", "darg", "plif", "womp"]
DIMS = ["shape", "color", "texture"]


def describe(shape, color, texture):
    return f"shaped like a {shape}, {color} in color, with a {texture} texture"


def make_item(rng):
    """One forced-choice item: exemplar + 3 options, each matching exactly
    one exemplar attribute; all 6 distractor values distinct."""
    s = rng.sample(SHAPES, 3)       # s[0]=exemplar, s[1],s[2] distractors
    c = rng.sample(COLORS, 3)
    t = rng.sample(TEXTURES, 3)
    word = rng.choice(NONWORDS)
    options = {                      # each shares exactly one attr w/ exemplar
        "shape": (s[0], c[1], t[1]),
        "color": (s[1], c[0], t[2]),
        "texture": (s[2], c[2], t[0]),
    }
    order = DIMS[:]
    rng.shuffle(order)               # which dimension is A / B / C
    return dict(
        word=word,
        exemplar=(s[0], c[0], t[0]),
        options={d: options[d] for d in order},   # insertion order = A,B,C
        order=order,
    )


def item_text(item, with_answer=None):
    """Render an item as prompt text. with_answer: dimension whose option
    letter is appended as the given answer (for demonstrations)."""
    ex = describe(*item["exemplar"])
    lines = [f"Here is an object: it is {ex}. We call it \"a {item['word']}\".",
             f"Now consider three more objects:"]
    letters = "ABC"
    for letter, d in zip(letters, item["order"]):
        lines.append(f"{letter}: {describe(*item['options'][d])}")
    lines.append(f"Question: Which of A, B, or C is also a {item['word']}?")
    if with_answer is not None:
        ans = letters[item["order"].index(with_answer)]
        lines.append(f"Answer: {ans}")
    return "\n".join(lines)


def build_prompt(test_item, demos=(), demo_dim=None):
    parts = ["I am going to show you some objects and teach you words for "
             "them. Then you will answer a question."]
    for d_item in demos:
        parts.append(item_text(d_item, with_answer=demo_dim))
    parts.append(item_text(test_item))
    parts.append("Answer with only the letter A, B, or C.")
    return "\n\n".join(parts)


def main():
    rng = random.Random(42)
    trials = []

    # C1: 60 unique + 20x3 consistency reps
    c1_items = [make_item(rng) for _ in range(60)]
    for i, item in enumerate(c1_items):
        trials.append(dict(trial_id=f"c1_{i:03d}_r0", phase="c1", item=item,
                           demo_dim=None, k=0, rep=0,
                           prompt=build_prompt(item)))
    for i in range(20):              # first 20 items, 2 extra reps each
        for rep in (1, 2):
            trials.append(dict(trial_id=f"c1_{i:03d}_r{rep}", phase="c1",
                               item=c1_items[i], demo_dim=None, k=0, rep=rep,
                               prompt=build_prompt(c1_items[i])))

    # C3: demos toward each dimension x k x 30 test items
    for demo_dim in DIMS:
        for k in (1, 2, 4, 8):
            for i in range(30):
                demos = [make_item(rng) for _ in range(k)]
                test = make_item(rng)
                trials.append(dict(
                    trial_id=f"c3_{demo_dim}_k{k}_{i:03d}", phase="c3",
                    item=test, demo_dim=demo_dim, k=k, rep=0,
                    prompt=build_prompt(test, demos, demo_dim)))

    out = Path("trials.jsonl")
    with out.open("w") as fh:
        for t in trials:
            fh.write(json.dumps(t) + "\n")
    print(f"{len(trials)} trials -> {out}")
    # sanity: demo answer positions balanced?
    from collections import Counter
    pos = Counter()
    for t in trials:
        if t["phase"] == "c3":
            pos[t["item"]["order"].index(t["demo_dim"]) if t["demo_dim"] in
                t["item"]["order"] else -1] += 0  # (test item, not demo)
    print("example prompt:\n" + "-" * 40)
    print(trials[0]["prompt"])
    print("-" * 40)
    print("example c3 k=2 prompt:\n" + "-" * 40)
    print(next(t for t in trials if t["phase"] == "c3" and t["k"] == 2)["prompt"])


if __name__ == "__main__":
    main()
Result
File created successfully at: D:\claude_code\shape_bias\stimuli.py (file state is current in your context — no need to Read it back)
✏️ Edit stimuli.py
D:\claude_code\shape_bias\stimuli.py
−
    print(f"{len(trials)} trials -> {out}")
    # sanity: demo answer positions balanced?
    from collections import Counter
    pos = Counter()
    for t in trials:
        if t["phase"] == "c3":
            pos[t["item"]["order"].index(t["demo_dim"]) if t["demo_dim"] in
                t["item"]["order"] else -1] += 0  # (test item, not demo)
    print("example prompt:\n" + "-" * 40)
+
    print(f"{len(trials)} trials -> {out}")
    print("example prompt:\n" + "-" * 40)
Result
The file D:\claude_code\shape_bias\stimuli.py has been updated successfully. (file state is current in your context — no need to Read it back)
📝 Write run_probe.py
D:\claude_code\shape_bias\run_probe.py
"""Run word-learning probe trials against Claude models.

  python run_probe.py --model claude-haiku-4-5 [--limit N] [--phase c1|c3]

Resumable: appends to results.csv, skips (model, trial_id) pairs already
present. Raw response text is stored. Unparsable answers get one retry with
a clarifying suffix; still-unparsable -> choice 'other'.

API key: reads ../riddle_experiment/.anthropic_key (same account as the
riddle/zork projects).
"""

import argparse
import csv
import json
import time
from pathlib import Path

import anthropic

KEY_PATH = Path(__file__).parent.parent / "riddle_experiment" / ".anthropic_key"
RESULTS = Path(__file__).parent / "results.csv"
FIELDS = ["model", "trial_id", "phase", "demo_dim", "k", "rep",
          "order", "raw", "letter", "choice_dim",
          "input_tokens", "output_tokens"]

# Sonnet 5 runs adaptive thinking when `thinking` is omitted -> disable
# explicitly. Haiku 4.5 predates the adaptive API; omit the param (off).
THINKING = {
    "claude-haiku-4-5": None,
    "claude-sonnet-5": {"type": "disabled"},
    "claude-opus-4-8": {"type": "disabled"},
}


def parse_letter(text):
    stripped = text.strip().upper()
    for ch in stripped[:8]:            # tolerate 'A.', '**B**', 'Answer: C'
        if ch in "ABC":
            return ch
    return None


def call(client, model, prompt):
    kwargs = dict(model=model, max_tokens=8,
                  messages=[{"role": "user", "content": prompt}])
    if THINKING[model] is not None:
        kwargs["thinking"] = THINKING[model]
    for attempt in range(4):
        try:
            return client.messages.create(**kwargs)
        except (anthropic.RateLimitError, anthropic.InternalServerError,
                anthropic.APIConnectionError) as e:
            wait = 5 * (2 ** attempt)
            print(f"  {type(e).__name__}, retrying in {wait}s", flush=True)
            time.sleep(wait)
    raise RuntimeError("API retries exhausted")


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--model", required=True, choices=list(THINKING))
    ap.add_argument("--limit", type=int, default=None)
    ap.add_argument("--phase", default=None, choices=["c1", "c3"])
    args = ap.parse_args()

    client = anthropic.Anthropic(api_key=KEY_PATH.read_text().strip())
    trials = [json.loads(l) for l in
              (Path(__file__).parent / "trials.jsonl").open()]
    if args.phase:
        trials = [t for t in trials if t["phase"] == args.phase]

    done = set()
    if RESULTS.exists():
        with RESULTS.open() as fh:
            done = {(r["model"], r["trial_id"]) for r in csv.DictReader(fh)}
    todo = [t for t in trials if (args.model, t["trial_id"]) not in done]
    if args.limit:
        todo = todo[:args.limit]
    print(f"{args.model}: {len(todo)} trials to run "
          f"({len(trials) - len(todo)} already done)", flush=True)

    new_file = not RESULTS.exists()
    with RESULTS.open("a", newline="") as fh:
        writer = csv.DictWriter(fh, fieldnames=FIELDS)
        if new_file:
            writer.writeheader()
        for n, t in enumerate(todo):
            resp = call(client, args.model, t["prompt"])
            raw = "".join(b.text for b in resp.content if b.type == "text")
            in_tok = resp.usage.input_tokens
            out_tok = resp.usage.output_tokens
            letter = parse_letter(raw)
            if letter is None:       # one clarifying retry
                resp2 = call(client, args.model,
                             t["prompt"] + "\nRespond with exactly one "
                             "character: A, B, or C.")
                raw2 = "".join(b.text for b in resp2.content
                               if b.type == "text")
                in_tok += resp2.usage.input_tokens
                out_tok += resp2.usage.output_tokens
                letter = parse_letter(raw2)
                raw = raw + " || RETRY: " + raw2
            order = t["item"]["order"]
            choice = order["ABC".index(letter)] if letter else "other"
            writer.writerow(dict(
                model=args.model, trial_id=t["trial_id"], phase=t["phase"],
                demo_dim=t["demo_dim"], k=t["k"], rep=t["rep"],
                order="|".join(order), raw=raw.replace("\n", " ")[:200],
                letter=letter or "", choice_dim=choice,
                input_tokens=in_tok, output_tokens=out_tok))
            fh.flush()
            if (n + 1) % 25 == 0:
                print(f"  {n + 1}/{len(todo)}", flush=True)
    print("done", flush=True)


if __name__ == "__main__":
    main()
Result
File created successfully at: D:\claude_code\shape_bias\run_probe.py (file state is current in your context — no need to Read it back)
⚙ PowerShell Generate probe trials and show example prompts 
{
  "command": "Set-Location D:\\claude_code\\shape_bias; & D:\\claude_code\\riddle_experiment\\.venv\\Scripts\\python.exe stimuli.py"
}
Result
460 trials -> trials.jsonl

example prompt:

----------------------------------------

I am going to show you some objects and teach you words for them. Then you will answer a question.



Here is an object: it is shaped like a horseshoe, charcoal in color, with a rubbery texture. We call it "a darg".

Now consider three more objects:

A: shaped like a star, charcoal in color, with a furry texture

B: shaped like a horseshoe, olive in color, with a metallic texture

C: shaped like a arch, lavender in color, with a rubbery texture

Question: Which of A, B, or C is also a darg?



Answer with only the letter A, B, or C.

----------------------------------------

example c3 k=2 prompt:

----------------------------------------

I am going to show you some objects and teach you words for them. Then you will answer a question.



Here is an object: it is shaped like a cube, magenta in color, with a spongy texture. We call it "a tupa".

Now consider three more objects:

A: shaped like a cube, teal in color, with a prickly texture

B: shaped like a cross, beige in color, with a spongy texture

C: shaped like a cylinder, magenta in color, with a furry texture

Question: Which of A, B, or C is also a tupa?

Answer: A



Here is an object: it is shaped like a horseshoe, mustard in color, with a furry texture. We call it "a blicket".

Now consider three more objects:

A: shaped like a wedge, beige in color, with a furry texture

B: shaped like a horseshoe, indigo in color, with a prickly texture

C: shaped like a spiral, mustard in color, with a bumpy texture

Question: Which of A, B, or C is also a blicket?

Answer: B



Here is an object: it is shaped like a pyramid, maroon in color, with a gritty texture. We call it "a darg".

Now consider three more objects:

A: shaped like a ring, coral in color, with a gritty texture

B: shaped like a wedge, maroon in color, with a glossy texture

C: shaped like a pyramid, crimson in color, with a prickly texture

Question: Which of A, B, or C is also a darg?



Answer with only the letter A, B, or C.
✏️ Edit stimuli.py
D:\claude_code\shape_bias\stimuli.py
−
def describe(shape, color, texture):
    return f"shaped like a {shape}, {color} in color, with a {texture} texture"
+
def describe(shape, color, texture):
    art = "an" if shape[0] in "aeiou" else "a"
    return f"shaped like {art} {shape}, {color} in color, with a {texture} texture"
Result
The file D:\claude_code\shape_bias\stimuli.py has been updated successfully. (file state is current in your context — no need to Read it back)
⚙ PowerShell Regenerate trials and smoke-test 6 Haiku API calls 
{
  "command": "Set-Location D:\\claude_code\\shape_bias; & D:\\claude_code\\riddle_experiment\\.venv\\Scripts\\python.exe stimuli.py | Select-Object -First 1; & D:\\claude_code\\riddle_experiment\\.venv\\Scripts\\python.exe run_probe.py --model claude-haiku-4-5 --limit 6",
  "timeout": 300000
}
Result
460 trials -> trials.jsonl

claude-haiku-4-5: 6 trials to run (454 already done)

done
⚙ PowerShell Inspect smoke test results 
{
  "command": "Get-Content D:\\claude_code\\shape_bias\\results.csv"
}
Result
model,trial_id,phase,demo_dim,k,rep,order,raw,letter,choice_dim,input_tokens,output_tokens

claude-haiku-4-5,c1_000_r0,c1,,0,0,color|shape|texture,B,B,shape,159,4

claude-haiku-4-5,c1_001_r0,c1,,0,0,color|shape|texture,B,B,shape,156,4

claude-haiku-4-5,c1_002_r0,c1,,0,0,shape|color|texture,A,A,shape,156,4

claude-haiku-4-5,c1_003_r0,c1,,0,0,shape|texture|color,A,A,shape,157,4

claude-haiku-4-5,c1_004_r0,c1,,0,0,color|shape|texture,B,B,shape,159,4

claude-haiku-4-5,c1_005_r0,c1,,0,0,shape|texture|color,A,A,shape,155,4
✏️ Edit run_probe.py
D:\claude_code\shape_bias\run_probe.py
−
    todo = [t for t in trials if (args.model, t["trial_id"]) not in done]
    if args.limit:
        todo = todo[:args.limit]
    print(f"{args.model}: {len(todo)} trials to run "
          f"({len(trials) - len(todo)} already done)", flush=True)
+
    todo = [t for t in trials if (args.model, t["trial_id"]) not in done]
    n_done = len(trials) - len(todo)
    if args.limit:
        todo = todo[:args.limit]
    print(f"{args.model}: {len(todo)} trials to run "
          f"({n_done} already done)", flush=True)
Result
The file D:\claude_code\shape_bias\run_probe.py has been updated successfully. (file state is current in your context — no need to Read it back)
⚙ PowerShell Run full shape-bias probe on all three models (~1440 API calls) 
{
  "command": "Set-Location D:\\claude_code\\shape_bias; $py = \"D:\\claude_code\\riddle_experiment\\.venv\\Scripts\\python.exe\"; & $py -u run_probe.py --model claude-haiku-4-5; & $py -u run_probe.py --model claude-sonnet-5; & $py -u run_probe.py --model claude-opus-4-8",
  "run_in_background": true
}
Result
Command running in background with ID: b6a35xzbo. Output is being written to: C:\Users\dprei\AppData\Local\Temp\claude\D--claude-code\47229213-8ef7-49af-a346-62ea167b235b\tasks\b6a35xzbo.output. You will be notified when it completes. To check interim output, use Read on that file path.
⚙ PowerShell Check validation stage status 
{
  "command": "Get-Content D:\\claude_code\\relational_sparsity\\runs\\validate_stage.log"
}
Result
9 runs to do

start baseline_s0

start rn_full_s0

start rn_oracle_s0

done baseline_s0 (rc=0)

start baseline_s1

done baseline_s1 (rc=0)

start rn_full_s1
📝 Write analyze.py
D:\claude_code\relational_sparsity\analyze.py
"""Aggregate runs/*/result.json into a summary table + figures."""

import json
from collections import defaultdict
from pathlib import Path

import numpy as np
import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt

RUNS = Path("runs")
FIGS = Path("figures")


def load():
    rows = []
    for rj in sorted(RUNS.glob("*/result.json")):
        r = json.loads(rj.read_text())
        cfg = r["config"]
        name = cfg["name"]
        base = name.rsplit("_s", 1)[0]           # strip seed suffix
        rows.append(dict(
            name=name, base=base, model=cfg["model"], select=cfg["select"],
            k=cfg["k"], seed=cfg["seed"], r=r))
    return rows


def agg(rows, split, metric):
    """mean and (min,max) across seeds per base config -> {base: (m, lo, hi)}"""
    by = defaultdict(list)
    for row in rows:
        v = row["r"][split].get(metric)
        if v is not None:
            by[row["base"]].append(v)
    return {b: (float(np.mean(v)), min(v), max(v)) for b, v in by.items()}


def line(ax, rows, select, split, metric, label, color):
    ks = sorted({r["k"] for r in rows if r["select"] == select and r["k"]})
    m = agg([r for r in rows if r["select"] == select], split, metric)
    ys, los, his = [], [], []
    for k in ks:
        mm, lo, hi = m[f"rn_{select}_k{k}"]
        ys.append(mm); los.append(lo); his.append(hi)
    ax.plot(ks, ys, "-o", label=label, color=color)
    ax.fill_between(ks, los, his, alpha=0.15, color=color)
    return ks


def main():
    FIGS.mkdir(exist_ok=True)
    rows = load()

    # ---- text summary ----
    print(f"{'config':24s} {'n':>2s} {'iid rel':>8s} {'iid nonrel':>10s} "
          f"{'ho rel':>8s} {'ho combo-q':>10s} {'sel-q':>6s}")
    bases = sorted({r["base"] for r in rows})
    for b in bases:
        sub = [r for r in rows if r["base"] == b]
        def m(split, met):
            vals = [r["r"][split].get(met) for r in sub
                    if r["r"][split].get(met) is not None]
            return f"{np.mean(vals):.3f}" if vals else "  -  "
        print(f"{b:24s} {len(sub):2d} {m('test_iid','acc_rel'):>8s} "
              f"{m('test_iid','acc_nonrel'):>10s} {m('test_ho','acc_rel'):>8s} "
              f"{m('test_ho','acc_heldout_combo_q'):>10s} "
              f"{m('test_iid','sel_frac_involves_query'):>6s}")

    sweep = [r for r in rows if r["select"] in ("learned", "random")]
    if not sweep:
        print("\n(no sweep runs yet - summary only)")
        return

    # ---- figure: accuracy vs k ----
    full = agg([r for r in rows if r["base"] == "rn_full"], "test_iid", "acc_rel")
    fullho = agg([r for r in rows if r["base"] == "rn_full"], "test_ho",
                 "acc_heldout_combo_q")
    oracle = agg([r for r in rows if r["base"] == "rn_oracle"], "test_iid",
                 "acc_rel")
    basel = agg([r for r in rows if r["base"] == "baseline"], "test_iid",
                "acc_rel")

    fig, axes = plt.subplots(1, 3, figsize=(15, 4.5))
    panels = [
        ("test_iid", "acc_rel", "Relational acc (IID test)"),
        ("test_iid", "acc_nonrel", "Non-relational acc (IID test)"),
        ("test_ho", "acc_heldout_combo_q",
         "Held-out combo questions (compositional test)"),
    ]
    for ax, (split, metric, title) in zip(axes, panels):
        ks = line(ax, sweep, "learned", split, metric, "learned top-k", "C0")
        line(ax, sweep, "random", split, metric, "random k", "C1")
        for name, d, color in [("full RN (36 pairs)",
                                agg([r for r in rows if r["base"] == "rn_full"],
                                    split, metric), "C2"),
                               ("oracle (6 pairs)",
                                agg([r for r in rows if r["base"] == "rn_oracle"],
                                    split, metric), "C3"),
                               ("MLP baseline",
                                agg([r for r in rows if r["base"] == "baseline"],
                                    split, metric), "C4")]:
            key = list(d)[0] if d else None
            if key:
                m, lo, hi = d[key]
                ax.axhline(m, color=color, ls="--", lw=1.2, label=name)
        ax.set_xscale("log")
        ax.set_xticks(ks); ax.set_xticklabels(ks)
        ax.set_xlabel("k (pairs kept)"); ax.set_ylabel("accuracy")
        ax.set_title(title, fontsize=10)
        ax.grid(alpha=0.3)
    axes[0].legend(fontsize=8, loc="lower right")
    fig.suptitle("Sparse Relation Networks: accuracy vs number of pairs kept "
                 "(shading = min/max over 3 seeds)")
    fig.tight_layout()
    fig.savefig(FIGS / "sweep_accuracy.png", dpi=130)
    print(f"\nwrote {FIGS / 'sweep_accuracy.png'}")

    # ---- figure: selection quality ----
    fig, ax = plt.subplots(figsize=(5.5, 4))
    ks = line(ax, sweep, "learned", "test_iid", "sel_frac_involves_query",
              "learned top-k", "C0")
    # chance rate: fraction of all 36 ordered pairs involving the queried
    # object = 11/36
    ax.axhline(11 / 36, color="gray", ls=":", label="chance (11/36)")
    ax.set_xscale("log"); ax.set_xticks(ks); ax.set_xticklabels(ks)
    ax.set_xlabel("k (pairs kept)")
    ax.set_ylabel("frac. selected pairs involving queried object")
    ax.set_title("Does the learned selector find the relevant pairs?",
                 fontsize=10)
    ax.legend(fontsize=8); ax.grid(alpha=0.3)
    fig.tight_layout()
    fig.savefig(FIGS / "selection_quality.png", dpi=130)
    print(f"wrote {FIGS / 'selection_quality.png'}")


if __name__ == "__main__":
    main()
Result
File created successfully at: D:\claude_code\relational_sparsity\analyze.py (file state is current in your context — no need to Read it back)
📝 Write analyze.py
D:\claude_code\shape_bias\analyze.py
"""Analyze shape-bias probe results -> tables + figures + cost report."""

from pathlib import Path

import numpy as np
import pandas as pd
import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt

HERE = Path(__file__).parent
DIMS = ["shape", "color", "texture"]
MODELS = ["claude-haiku-4-5", "claude-sonnet-5", "claude-opus-4-8"]
PRICE = {  # $ per Mtok (in, out); Sonnet intro pricing as of 2026-07
    "claude-haiku-4-5": (1, 5),
    "claude-sonnet-5": (2, 10),
    "claude-opus-4-8": (5, 25),
}


def wilson(p, n, z=1.96):
    if n == 0:
        return (0, 0)
    d = 1 + z**2 / n
    c = (p + z**2 / (2 * n)) / d
    h = z * np.sqrt(p * (1 - p) / n + z**2 / (4 * n**2)) / d
    return c - h, c + h


def main():
    df = pd.read_csv(HERE / "results.csv")
    df = df[df.model.isin(MODELS)]

    # ---- cost ----
    cost = 0.0
    for m, g in df.groupby("model"):
        ci, co = PRICE[m]
        c = (g.input_tokens.sum() * ci + g.output_tokens.sum() * co) / 1e6
        cost += c
        print(f"{m}: {len(g)} trials, ${c:.2f}")
    print(f"TOTAL COST: ${cost:.2f}\n")

    # ---- C1: default bias ----
    c1 = df[df.phase == "c1"]
    print("C1 default bias (choice share, unique trials rep0):")
    fig, axes = plt.subplots(1, 2, figsize=(11, 4.2))
    width = 0.25
    for i, m in enumerate(MODELS):
        g = c1[(c1.model == m) & (c1.rep == 0)]
        n = len(g)
        shares, errs = [], []
        for j, d in enumerate(DIMS):
            p = (g.choice_dim == d).mean()
            lo, hi = wilson(p, n)
            shares.append(p); errs.append((p - lo, hi - p))
            print(f"  {m:22s} {d:8s} {p:.2f}  [{lo:.2f},{hi:.2f}] (n={n})")
        other = (~g.choice_dim.isin(DIMS)).mean()
        if other:
            print(f"  {m:22s} other    {other:.2f}")
        axes[0].bar(np.arange(3) + (i - 1) * width, shares, width,
                    yerr=np.array(errs).T, capsize=3, label=m.replace("claude-", ""))
        # position bias check
        pos = g.letter.value_counts(normalize=True).reindex(list("ABC")).fillna(0)
        print(f"  {m:22s} letters  A:{pos['A']:.2f} B:{pos['B']:.2f} C:{pos['C']:.2f}")
    axes[0].set_xticks(range(3)); axes[0].set_xticklabels(DIMS)
    axes[0].set_ylabel("choice share"); axes[0].axhline(1/3, color="gray", ls=":")
    axes[0].set_title("C1: which match is 'also a dax'? (95% Wilson CIs)",
                      fontsize=10)
    axes[0].legend(fontsize=8)

    # consistency subset
    print("\nC1 consistency (20 items x 3 reps): frac items unanimous")
    for m in MODELS:
        g = c1[(c1.model == m) & (c1.trial_id.str.match(r"c1_0(0\d|1\d)_"))]
        unam = g.groupby(g.trial_id.str[:6]).choice_dim.nunique().eq(1).mean()
        print(f"  {m:22s} {unam:.2f}")

    # ---- C3: in-context malleability ----
    c3 = df[df.phase == "c3"]
    ax = axes[1]
    styles = {"shape": "-", "color": "--", "texture": ":"}
    colors = {m: f"C{i}" for i, m in enumerate(MODELS)}
    print("\nC3: P(choose demonstrated dimension) by k:")
    for m in MODELS:
        # k=0 baseline = share of that dim in C1
        g0 = c1[(c1.model == m) & (c1.rep == 0)]
        for d in DIMS:
            ks, ps = [0], [(g0.choice_dim == d).mean()]
            for k in (1, 2, 4, 8):
                g = c3[(c3.model == m) & (c3.demo_dim == d) & (c3.k == k)]
                if len(g):
                    ks.append(k); ps.append((g.choice_dim == d).mean())
            ax.plot(ks, ps, styles[d], marker="o", ms=3.5, color=colors[m],
                    alpha=0.85,
                    label=f"{m.replace('claude-','')} / {d}" )
            print(f"  {m:22s} {d:8s} " +
                  " ".join(f"k{k}:{p:.2f}" for k, p in zip(ks, ps)))
    ax.set_xlabel("k demonstrations"); ax.set_ylabel("P(choose demoed dim)")
    ax.axhline(1/3, color="gray", ls=":")
    ax.set_title("C3: overriding the default bias in context", fontsize=10)
    ax.legend(fontsize=6, ncol=1, loc="center right")
    fig.tight_layout()
    fig.savefig(HERE / "figures_bias.png", dpi=130)
    print(f"\nwrote {HERE / 'figures_bias.png'}")


if __name__ == "__main__":
    main()
Result
File created successfully at: D:\claude_code\shape_bias\analyze.py (file state is current in your context — no need to Read it back)
📖 Read b6a35xzbo.output
C:\Users\dprei\AppData\Local\Temp\claude\D--claude-code\47229213-8ef7-49af-a346-62ea167b235b\tasks\b6a35xzbo.output
Result
1	claude-haiku-4-5: 454 trials to run (6 already done)
2	  25/454
3	  50/454
4	  75/454
5

While those run, a quick README for the relational sparsity project so the repo is self-documenting for the review pass later.

📝 Write README.md
D:\claude_code\relational_sparsity\README.md
# Do Relation Networks need all pairs? Sparse relational bottlenecks

Riff on Santoro et al. (NeurIPS 2017), "A simple neural network module for
relational reasoning", connected to the adaptive-compute question of
Raposo/Santoro et al. 2024 (Mixture-of-Depths): the RN sums a relation MLP g
over ALL n^2 ordered object pairs. How much of that is necessary? Can the
network learn WHICH pairs matter, and does forced pair-sparsity help or hurt
systematic generalization?

## Setup

- **Data:** Sort-of-CLEVR-style scenes generated in-house (`data_gen.py`):
  6 objects (one per color), square/circle, 64x64 images + ground-truth
  states. 36 questions/scene (6 colors x 6 subtypes; 3 non-relational,
  3 relational). Compositional split: red-square, green-circle, blue-square
  never occur in train/val/test_iid; every test_ho scene contains >=1.
  Known artifact: R_COUNT answer "6" is impossible in the train distribution
  (held-out constraint forces mixed shapes) -> report test_ho also excluding
  those questions (`acc_excl_count6`).
- **Tier 1 (state input, all main results):** objects = ground-truth
  (x, y, color one-hot, shape one-hot) vectors; canonical color order
  (helps the MLP baseline, irrelevant to the permutation-invariant RN).
- **Models** (`models.py`): MLP baseline; RN (sum g over all 36 ordered
  pairs incl. self-pairs); sparse RN with learned top-k pair selection
  (straight-through: hard top-k forward, gradient via k*softmax(logits/tau));
  random-k control (fresh uniform k pairs per forward pass); oracle
  selection (the 6 pairs (i, X) whose 2nd element is the queried color) —
  the hand-coded ceiling for what a perfect selector could pick.
- **Hypothesis:** all 6 questions are answerable from pairs involving the
  queried object X, so a learned selector that discovers "pick pairs
  involving X" should match the full RN with k~6; k below ~5 should
  selectively destroy relational accuracy while non-relational survives
  (k=1 suffices via the self-pair (X,X)). Selection quality is measured as
  the fraction of selected pairs involving X (chance 11/36).

## Reproduce

```
python data_gen.py                      # ~2 min
python sanity_check.py                  # figures/sanity_scenes.png + checks
python run_sweep.py validate            # baseline/full/oracle x 3 seeds
python run_sweep.py sweep               # learned/random x k in {1,3,6,12,24} x 3 seeds
python analyze.py                       # summary table + figures
```

Runs checkpoint per epoch and resume; `run_sweep.py` skips finished runs.
Venv: `D:\claude_code\ml_venv` (torch CPU). 20 epochs, batch 256, Adam 1e-3,
~10 min/run at 4 threads, 3 concurrent.
Result
File created successfully at: D:\claude_code\relational_sparsity\README.md (file state is current in your context — no need to Read it back)
⚙ PowerShell Check validation run progress 
{
  "command": "Get-Content D:\\claude_code\\relational_sparsity\\runs\\validate_stage.log; Get-ChildItem D:\\claude_code\\relational_sparsity\\runs -Directory | ForEach-Object { $rj = Join-Path $_.FullName \"result.json\"; if (Test-Path $rj) { \"$($_.Name): done\" } else { $log = Get-Content (Join-Path $_.FullName \"log.csv\") -Tail 1; \"$($_.Name): $log\" } }"
}
Result
9 runs to do

start baseline_s0

start rn_full_s0

start rn_oracle_s0

done baseline_s0 (rc=0)

start baseline_s1

done baseline_s1 (rc=0)

start rn_full_s1

baseline_s0: done

baseline_s1: done

rn_full_s0: 15,0.0268,0.9883,0.9799,0.9967,nan,34.6

rn_full_s1: 9,0.0509,0.9787,0.9612,0.9962,nan,34.6

rn_oracle_s0: 15,0.0272,0.9865,0.9767,0.9963,nan,35.6
⚙ PowerShell Wait for validation stage, then run the full k-sweep (30 runs) 
{
  "command": "Set-Location D:\\claude_code\\relational_sparsity; while (-not (Select-String -Path runs\\validate_stage.log -Pattern \"all done\" -Quiet)) { Start-Sleep -Seconds 60 }; & D:\\claude_code\\ml_venv\\Scripts\\python.exe -u run_sweep.py sweep",
  "run_in_background": true,
  "timeout": 600000
}
Result
Command running in background with ID: bhvh71x75. Output is being written to: C:\Users\dprei\AppData\Local\Temp\claude\D--claude-code\47229213-8ef7-49af-a346-62ea167b235b\tasks\bhvh71x75.output. You will be notified when it completes. To check interim output, use Read on that file path.
⚙ TaskUpdate 
{
  "taskId": "4",
  "status": "completed"
}
Result
Updated task #4 status
⚙ TaskUpdate 
{
  "taskId": "5",
  "status": "in_progress"
}
Result
Updated task #5 status
⚙ TaskUpdate 
{
  "taskId": "3",
  "status": "in_progress"
}
Result
Updated task #3 status

Status update while the machines work — here's where both experiments stand:

Experiment A (sparse Relation Networks) — Data generator built and sanity-checked (I verified rendered scenes against their question/answer pairs by eye, and the held-out shape-color constraint holds). The harness validation is reproducing the Santoro 2017 result nicely: the full RN reaches ~98% on relational questions where early baseline numbers are far lower. The main event — the k-sweep with learned vs. random pair selection (30 runs, 3 seeds each) — is queued to start automatically the moment validation finishes, roughly two hours of CPU time total.

Experiment C (LLM shape bias) — Designed, documented in DESIGN.md, smoke-tested, and now running the full 1,440-call probe across Haiku 4.5, Sonnet 5, and Opus 4.8. No installs were needed (reusing the riddle project's venv and API key). Estimated cost ~$6; I'm recording actual token usage per call and will report the real number. First interesting signal: in the smoke test Haiku chose the shape match 6 out of 6 times across randomized option positions — consistent with a strong human-like shape bias.

Analysis scripts for both are written and waiting for data. I'll pick things up when the background jobs report in.

User

Can I check, why were you looking at the zork and riddle riddle memories? Less cross contamination here is better

Assistant

Fair question — the honest answer is I read them purely for operational reasons, at the moment I needed to make API calls work:

  1. API key mechanics — my memory index said those two projects had solved "how does Claude call the Anthropic API from this sandboxed machine" (answer: key in a gitignored .anthropic_key file, and the riddle venv already has the anthropic SDK installed on D:). That saved you a package-install review and me a broken first attempt.
  2. Spending norms — the zork memory records the rule you set there: estimate costs before spending, report actuals. I wanted to apply the same rule here.

What I didn't take from them: any experimental design, stimuli, hypotheses, or analysis choices. The shape-bias design comes from the Ritter et al. 2017 paper and the classic Landau/Smith/Jones child paradigm it's based on, and Experiment A comes straight from the Santoro papers.

But your point stands, and there is a real contamination risk I should name: the riddle memory contains methodology-adjacent things (judge design, resumable-harness patterns, your design principles) that could subtly shape how I build LLM experiments — and if the point of this exercise is "how well does a fresh AI run do ML research," leaning on accumulated craft-knowledge from past projects muddies the measurement. I'll treat project memories as off-limits for the rest of this run except for pure infrastructure facts (paths, keys, hardware), and I'll note in the final writeup the two places they influenced anything (API access route, cost-reporting habit) so the provenance is transparent.

Let me record that as standing guidance so future sessions respect it too.

📝 Write feedback-limit-cross-project-memory-use.md
C:\Users\dprei\.claude\projects\D--claude-code\memory\feedback-limit-cross-project-memory-use.md
[auto-memory content redacted for sharing]
Result
[auto-memory content redacted for sharing]
✏️ Edit MEMORY.mderror
C:\Users\dprei\.claude\projects\D--claude-code\memory\MEMORY.md
−
[auto-memory content redacted for sharing]
+
[auto-memory content redacted for sharing]
Error
[auto-memory content redacted for sharing]
📖 Read MEMORY.md
C:\Users\dprei\.claude\projects\D--claude-code\memory\MEMORY.md
Result
[auto-memory content redacted for sharing]
✏️ Edit MEMORY.md
C:\Users\dprei\.claude\projects\D--claude-code\memory\MEMORY.md
−
[auto-memory content redacted for sharing]
+
[auto-memory content redacted for sharing]
Result
[auto-memory content redacted for sharing]

Saved. Going forward in this session I'll touch memories only for infrastructure facts (the venv paths and API key location are already in use; nothing else). Both experiments are still running in the background — I'll report when they land, including the two disclosure notes in the final writeup.