该模式不是 API 参数。它完全由文档中已有的组件构成：

1. 一个 effort 级别： 请求以文档中的 Effort 值运行，例如 xhigh。该页面所列级别之上没有隐藏级别。本示例在每个请求的顶层设置 effort，无需 beta header。
2. 一条模式提醒： 一条 会话中途的 system message 告知模型该模式处于活动状态，每隔若干轮附带一行刷新提醒，并在关闭模式时发送退出通知。顶层 system 字段始终不变，因此缓存前缀保持完整。
3. 工具描述中的持续性授权： 编排工具的描述写明：模式开启时，模型应为每一个实质性任务编写并运行 workflow，无需事先询问。

设置循环

该示例是单个文件。常量控制 effort 级别、fan-out 形态，以及模式刷新提醒的重发频率。MAX_CONCURRENT 限制同时运行的子代理数量（PHP 移植版是顺序执行并忽略该值）；MAX_TOTAL_SUBTASKS 限制模型在单次 Workflow 调用中可以排队的数量。把两者分开，让模型可以规划大量积压任务，而不必一次全部启动。当设置了环境变量 DOC_TEST_MODE 时，该检查会把循环限制为单轮，以便自动化文档 harness 验证文件能够编译并迅速结束，而无需跑完整编排；你自己运行示例时请保持其未设置。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

</CodeGroup>

## 定义模式提醒

提醒刻意写得很短。它们切换模式，并指向工具描述——重量级指令就放在那里。全文只在模式开启时发送一次，刷新提醒只在若干用户轮次之后才重发，退出通知在模式关闭时发送一次。

<CodeGroup>
```python Python
MODE_ENTER = (
    "Orchestration mode is on: optimize for the most exhaustive, correct answer rather than "
    "the fastest one. Use the Workflow tool on every substantive task, sized to the problem's "
    "natural decomposition rather than the maximum the tool allows. See the Workflow tool's "
    "description for standing consent, granularity guidance, and quality patterns. Work solo "
    "only on conversational or trivial turns."
)
MODE_REFRESH = (
    "Orchestration mode is still on. Use the Workflow tool; see its standing consent section."
)
MODE_EXIT = (
    "Orchestration mode is off. The Workflow tool's standard opt-in rule applies again."
)

在工具描述中授予持续性授权

Workflow 工具承载真正的行为契约：opt-in 规则、模式开启期间适用的持续性授权、用于确定 fan-out 规模的粒度指引，以及模型可以取用的质量模式（验证波、完备性批评者、多阶段分步）。子代理还会得到一个 report_findings 工具，使其结果以结构化 JSON 而非散文返回；bash 工具则是 Anthropic 定义的 bash_20250124 工具，在本地运行。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

</CodeGroup>

## 在本地运行 bash 工具

bash 处理器以超时运行所请求的命令，捕获合并后的 stdout 和 stderr，并截断结果，以免失控命令淹没上下文窗口。命令在你启动示例时所在的目录中运行，因此要指向某个项目，就从那里启动；当设置了 `DOC_TEST_MODE` 时，harness 会改为给 bash 一个退出时删除的小型一次性夹具目录。这里没有沙箱：命令以启动该示例的进程的权限运行。为清晰起见，本示例在全新的 subshell 中运行每一次调用，而不是维护 `bash_20250124` 契约所描述的持久会话；生产级代理应用长生命周期 shell 支撑该工具，使工作目录、环境以及 `restart` 动作按文档行为。

<CodeGroup>
```python Python
# Run bash where the example was launched. In DOC_TEST_MODE the docs harness
# points it at a throwaway fixture directory instead, removed on exit.
if DOC_TEST_MODE:
    WORK_DIR = tempfile.mkdtemp(prefix="orchestration-")
    atexit.register(shutil.rmtree, WORK_DIR, ignore_errors=True)
    with open(os.path.join(WORK_DIR, "sample.py"), "w") as fixture:
        fixture.write(
            "def fib(n):\n"
            "    return n if n < 2 else fib(n - 1) + fib(n - 2)\n\n"
            "print(fib(10))\n"
        )
else:
    WORK_DIR = os.getcwd()


def run_bash(command: str) -> tuple[str, bool]:
    """Run a shell command and return (output, is_error). No sandbox: example code only."""
    print(f"[bash] {command}", file=sys.stderr)
    try:
        proc = subprocess.run(
            ["bash", "-c", command],
            cwd=WORK_DIR,
            capture_output=True,
            text=True,
            errors="replace",
            timeout=BASH_TIMEOUT_SECONDS,
        )
    except subprocess.TimeoutExpired:
        return f"command timed out after {BASH_TIMEOUT_SECONDS}s", True
    output = (proc.stdout + proc.stderr).strip() or "(no output)"
    if len(output) > TOOL_RESULT_MAX_CHARS:
        output = output[:TOOL_RESULT_MAX_CHARS] + f"\n(truncated at {TOOL_RESULT_MAX_CHARS} chars)"
    if proc.returncode != 0:
        output = f"(exit code {proc.returncode})\n{output}"
    return output, proc.returncode != 0


def handle_bash_block(block) -> tuple[str, bool]:
    if block.input.get("restart") is True:
        return "Shell restarted.", False
    command = block.input.get("command")
    if not isinstance(command, str) or not command:
        return "bash error: no command was provided.", True
    return run_bash(command)

运行一个子代理

每一个 workflow 子任务都会变成带 bash 工具的小型代理循环，并以与主循环相同的 effort 运行。每次 API 调用都有按请求的超时上限，因此连接中断只会让一个子代理降级，而不会卡住整次运行。

将结果写入 journal，以便重跑时续跑

催生数十个子代理的 fan-out，从头重启代价很高。一个小型内容寻址 journal 使其幂等：在派发子代理之前，在本地 JSON 文件中查找其 prompt 的 SHA-256，若已有记录则返回该结果。中断运行后再重跑，只有从未完成的子任务才会被重新计算。journal 在多次运行之间去重，而不是在单次 fan-out 波次之内；删除 journal 文件即可重新开始。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

</CodeGroup>

## 先 fan-out，再验证

fan-out 最多接受 `MAX_TOTAL_SUBTASKS` 条 prompt，经 journal 运行，同时进行中的不超过 `MAX_CONCURRENT` 个（PHP 移植版为顺序执行），并隔离失败，使一个损坏的子代理降级为错误字符串，而不是结束整次运行。第一波完成后，第二波复用同一条子代理路径，试图反驳每一条结果：每个验证者从源头重新推导这些论断，不确定时默认判定为已反驳。原始结果及其裁决都会返回给编排器，以便一并权衡。

<CodeGroup>
```python Python
def normalize_subtasks(raw) -> list[str]:
    """Accept the subtasks input in whatever shape the model emits: an array, the array
    JSON-encoded as a single string, or a newline-separated list."""
    if isinstance(raw, str):
        try:
            raw = json.loads(raw)
        except json.JSONDecodeError:
            raw = raw.splitlines() if "\n" in raw else [raw]
    if not isinstance(raw, list):
        return []
    return [task.strip() for task in raw if isinstance(task, str) and task.strip()]


def verify_prompt_for(subtask: str, result: str) -> str:
    return (
        "Adversarially verify the subagent result below: try to REFUTE it. Re-derive the "
        "claims yourself with bash rather than trusting the result, and look for evidence "
        "that contradicts them. Default to refuted if uncertain. Call report_findings with "
        "summary 'refuted: <why>' or 'confirmed: <why>', citing the file:line or command "
        "output that decided it.\n\n"
        f"Subtask: {subtask}\n\nResult to verify:\n{result}"
    )


def run_workflow(model: str, raw_subtasks) -> tuple[str, bool]:
    """Run subtasks as parallel subagents, then run a second verification wave over
    the results, and return both. MAX_TOTAL_SUBTASKS bounds how many the model can
    queue; MAX_CONCURRENT bounds how many run at once."""
    all_subtasks = normalize_subtasks(raw_subtasks)
    subtasks = all_subtasks[:MAX_TOTAL_SUBTASKS]
    dropped = len(all_subtasks) - len(subtasks)
    if not subtasks:
        return "Workflow error: no usable subtasks were provided.", True
    print(f"[workflow] fanning out {len(subtasks)} agents", file=sys.stderr)

    def run_one(prompt: str) -> str:
        try:
            return journaled(prompt, lambda: run_subagent(model, prompt))
        except Exception as error:  # isolation boundary: one bad subagent should not end the run
            return f"(subagent failed: {type(error).__name__}: {error})"

    with concurrent.futures.ThreadPoolExecutor(max_workers=MAX_CONCURRENT) as pool:
        results = list(pool.map(run_one, subtasks))
        print(f"[workflow] verifying {len(results)} results", file=sys.stderr)
        verify_prompts = [verify_prompt_for(task, result) for task, result in zip(subtasks, results)]
        verdicts = list(pool.map(run_one, verify_prompts))

    joined = "\n\n".join(
        f"[agent {index + 1}: {task}]\n{result}\n\n[verify {index + 1}]\n{verdict}"
        for index, (task, result, verdict) in enumerate(zip(subtasks, results, verdicts))
    )
    if dropped > 0:
        joined = (
            f"(note: {dropped} subtasks beyond MAX_TOTAL_SUBTASKS={MAX_TOTAL_SUBTASKS} were not "
            "run; rerun them in a follow-up Workflow call)\n\n" + joined
        )
    return joined, False

用会话中途的 system messages 切换模式

代理先追加用户消息，再追加本轮应付的任何 system messages：退出通知、进入时的完整模式文本，或周期性刷新提醒。把 system message 放在用户轮次之后，可使它前面的每一个缓存字节保持未动，并满足 system message 跟在用户轮次之后的放置规则。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

class ModeAgent:
    """An agent loop whose orchestration mode is toggled with mid-conversation system messages."""

    def __init__(self, model: str, mode_on: bool = True):
        self.model = model
        self.mode_on = mode_on
        self.messages: list[dict] = []
        self._mode_announced = False
        self._exit_pending = False
        self._turns_since_reminder = 0

    def set_mode(self, mode_on: bool) -> None:
        """Turn the mode on or off. The notice is delivered with the next user turn."""
        if mode_on == self.mode_on:
            return
        if not mode_on:
            if self._mode_announced:
                self._exit_pending = True
        else:
            self._exit_pending = False
        self.mode_on = mode_on

    def _due_system_messages(self) -> list[dict]:
        """System messages owed on this turn: an exit notice, the full mode text on entry,
        or a one-line refresher every TURNS_BETWEEN_REFRESHERS user turns."""
        due = []
        if self._exit_pending:
            self._exit_pending = False
            self._mode_announced = False
            due.append({"role": "system", "content": MODE_EXIT})
        if self.mode_on:
            if not self._mode_announced:
                self._mode_announced = True
                self._turns_since_reminder = 0
                due.append({"role": "system", "content": MODE_ENTER})
            elif self._turns_since_reminder >= TURNS_BETWEEN_REFRESHERS:
                self._turns_since_reminder = 0
                due.append({"role": "system", "content": MODE_REFRESH})
        return due

    def turn(self, user_input: str) -> str:
        # Mid-conversation system messages follow the user turn they apply to, which keeps
        # the cached prefix ahead of them untouched.
        self.messages.append({"role": "user", "content": user_input})
        self.messages.extend(self._due_system_messages())
        self._turns_since_reminder += 1

        for _ in range(MAX_MAIN_TURNS):
            with client.messages.stream(
                model=self.model,
                max_tokens=64000,
                system=SYSTEM_PROMPT,  # static for the whole session
                output_config={"effort": EFFORT},
                tools=[WORKFLOW_TOOL, BASH_TOOL],
                messages=self.messages,
                timeout=REQUEST_TIMEOUT_SECONDS,
            ) as stream:
                response = stream.get_final_message()
            self.messages.append({"role": "assistant", "content": response.content})

            if response.stop_reason == "pause_turn":
                continue
            if response.stop_reason != "tool_use":
                text = "".join(block.text for block in response.content if block.type == "text")
                if response.stop_reason == "max_tokens":
                    # Drop the truncated assistant message so later turns don't build on it.
                    self.messages.pop()
                    text += "\n\n(warning: response was truncated at max_tokens)"
                return text

            tool_results = []
            for block in response.content:
                if block.type != "tool_use":
                    continue
                if block.name == "Workflow":
                    output, is_error = run_workflow(self.model, block.input.get("subtasks", []))
                elif block.name == "bash":
                    output, is_error = handle_bash_block(block)
                else:
                    output, is_error = f"unknown tool: {block.name}", True
                tool_results.append(
                    {
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": output,
                        "is_error": is_error,
                    }
                )
            self.messages.append({"role": "user", "content": tool_results})
        return "(hit the main loop turn limit before finishing)"

运行它

从你希望代理工作的目录启动该示例，例如要审查的仓库根目录：

模式开启时，预期模型会用几条 bash 命令侦察，主动派发 Workflow 工具，并把子代理报告综合成最终答案。琐碎或对话性请求会保持单独处理，正如提醒所指示的。

迈向生产级 harness

本示例刻意保持精简。面向真实工作负载的 harness 通常还会加上：

• 带沙箱的编排脚本： 让模型发出一段简短的编排程序（分支、循环和 reduce 步骤），并在隔离的解释器中运行，而不是只接受扁平的子任务字符串列表。
• 持久 journaling： 用能在进程重启后存活、且在跨机器并发写入下安全的存储，替换本地 JSON 文件。
• 预算强制： 跟踪整个会话中启动的子代理总数，而不只是每次 Workflow 调用，并拒绝超过硬上限，以免失控计划耗尽你的配额。

本示例中的模式（模式提醒、工具描述中的持续性授权、journaling，以及验证波）原样沿用；只是它们周围的执行基底会更稳健。

相关内容

• 状态：Beta
• Beta header: cache-diagnosis-2026-04-07
• ZDR（零数据保留）: 符合资格（不包括 Covered Models）
• 平台：Claude API (beta)；在 Claude Platform on AWS、Amazon Bedrock、Google Cloud、Microsoft Foundry 上不可用

Prompt Caching 能显著降低延迟和成本，但前提是 prompt 的开头必须与近期某次请求逐字节相同。被重排的 tool、插入到 system prompt 中的时间戳，或对更早消息的编辑，都可能悄无声息地使缓存失效。没有 cache diagnostics 时，唯一信号是 usage.cache_read_input_tokens 降为零，却无法得知什么发生了变化。

Cache diagnostics 填补了这一缺口。传入上一次响应的 id，API 会对比两次请求，并告诉你它们在何处分叉（model、system prompt、tools 或消息历史），从而让你修复根因，而不是猜测。

Cache diagnostics 如何工作

当 beta header 存在时，API 会为每个请求存储一份轻量 fingerprint，并以响应 id 作为键。在下一次请求中，将该 id 作为 diagnostics.previous_message_id 传入。API 会为新请求重建 fingerprint，与已存储的那份对比，并在响应上附加一个 diagnostics 对象，描述第一个分歧点。

对比针对的是请求结构，与缓存是否实际命中无关。关于如何将 diagnostics 结果与 usage.cache_read_input_tokens 结合使用，见 结合 usage 解读 diagnostics。

Fingerprint 仅包含哈希和 token 数量估计（绝不包含原始 prompt 内容），保留时间有限，作用域限定在你的 organization 和 workspace，且不会用于任何其他目的。

基本用法

每一 turn 都发送 beta header。第一 turn 传入 "previous_message_id": null 以选择加入，此时没有可供对比的先前消息。后续 turn 传入上一次响应中的 id。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

client = anthropic.Anthropic()

SYSTEM = "You are an AI assistant analyzing a large document. <document>...</document>"

# Turn 1: opt in with previous_message_id=None
r1 = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system=SYSTEM,
    messages=[{"role": "user", "content": "Summarize section 1."}],
    diagnostics={"previous_message_id": None},
    betas=["cache-diagnosis-2026-04-07"],
)

# Turn 2: reference the previous response id
r2 = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system=SYSTEM,
    messages=[
        {"role": "user", "content": "Summarize section 1."},
        {"role": "assistant", "content": r1.content},
        {"role": "user", "content": "Now summarize section 2."},
    ],
    diagnostics={"previous_message_id": r1.id},
    betas=["cache-diagnosis-2026-04-07"],
)

diagnostics = r2.diagnostics
if diagnostics is None:
    print("No divergence detected.")
elif diagnostics.cache_miss_reason is None:
    print("Comparison still pending.")
else:
    print(f"cache_miss_reason: {diagnostics.cache_miss_reason.type}")

流式

在流式响应中，diagnostics 出现在 message_start 事件上。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# Turn 2: stream, referencing the previous response id
with client.beta.messages.stream(
    model="claude-opus-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system=SYSTEM,
    messages=[
        {"role": "user", "content": "Summarize section 1."},
        {"role": "assistant", "content": r1.content},
        {"role": "user", "content": "Now summarize section 2."},
    ],
    diagnostics={"previous_message_id": r1.id},
    betas=["cache-diagnosis-2026-04-07"],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    print()
    r2 = stream.get_final_message()

diagnostics = r2.diagnostics
if diagnostics is None:
    print("No divergence detected.")
elif diagnostics.cache_miss_reason is None:
    print("Comparison still pending.")
else:
    print(f"cache_miss_reason: {diagnostics.cache_miss_reason.type}")

message_start 事件携带完整的 diagnostics 字段；可能的取值见 响应格式。

在对话循环中贯穿 diagnostics

在多 turn 对话中，每一 turn 都将最新响应的 id 作为 previous_message_id 向前传递。第一次迭代传入 null 以选择加入；之后每次迭代传入上一次响应中的 id。

SYSTEM = "You are an AI assistant analyzing a large document. <document>...</document>"

messages = []
prev_id = None

for i, user_message in enumerate(
    ["Summarize section 1.", "Now section 2.", "Now section 3."]
):
    messages.append({"role": "user", "content": user_message})

    r = client.beta.messages.create(
        model="claude-opus-5",
        max_tokens=1024,
        cache_control={"type": "ephemeral"},
        system=SYSTEM,
        messages=messages,
        diagnostics={"previous_message_id": prev_id},
        betas=["cache-diagnosis-2026-04-07"],
    )

    if r.diagnostics is not None and r.diagnostics.cache_miss_reason is not None:
        print(f"Turn {i + 1} cache_miss_reason: {r.diagnostics.cache_miss_reason.type}")

    messages.append({"role": "assistant", "content": r.content})
    prev_id = r.id
```

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

{
  "id": "msg_01Xyz...",
  "type": "message",
  "role": "assistant",
  "content": [{ "type": "text", "text": "..." }],
  "usage": {
    "input_tokens": 42,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 41850,
    "output_tokens": 210
  },
  "diagnostics": {
    "cache_miss_reason": {
      "type": "system_changed",
      "cache_missed_input_tokens": 41850
    }
  }
}

context rot:随着上下文token数地增长,准确性和召回率会下降的现象

对于一个request包含的内容:

1. tools:能够给模型提供tools,包含其名称,描述,参数
2. System prompt:系统提示词
3. 一些harness设置的信息,比如ClaudeCode的CLAUDE.md或者codex的AGENTS.md等等
4. user message: prompt,tool calling,thinking block,tool result等等

区分三个概念:

input_tokens;cache_read_input_tokens;cache_creation_input_token

这和prompt caching还有price有关

带thinking的上下文窗口

thinking tokens是max_tokens的子集

关于assistant turn中的think blocks是否保留在上下文由模型决定 不过现在大部分的模型都是全量保留 不过在context_editing中你可以在通过设置来清楚think blocks腾出更多的上下文空间

对于启用了剥离thinking blocks的模型:

• thinking blocks会作为上一轮assistant turn的output,但是不会作为下一轮的user turn的input
• 计费:think blocks作为输出计费,如果被保留,在下一轮对话中也会作为上下文输出,按输入再次计费

上下文的感知(context awareness):

工作原理:

之前:每个request的system prompt中会包含总的上下文窗口 每次工具调用之后,API会向Claude提供剩余用量的更新 之后: 不会收到这些注入的标签了 通过task_budgets给模型一个显示预算

用压缩管理上下文:

server-side compaction时最常见的管理上下文的方式 对于更为专业的需求,在context-editing中提供了额外的策略:

• tool result clearing: 清楚工具调用的结果,可通过设置也清楚工具调用的请求信息
• thinking blocks clearing:在extending thinking时清楚thinking blocks

Compaction

server-side Compaction是管理上下文的最常见的方式,他会自动处理上下文管理

when:

压缩会在上下文窗口的大小接近上限时自动摘要较久的上下文

适用于:

• 基于聊天的多轮对话
• 需要大量后续工作,且可能超出上下文窗口的面向任务的prompt

压缩如何工作的

当快要到达对话设定的阈值的时候,会自动触发上下文压缩:

1. 检测输出的token是否达到你设定的阈值
2. 生成当前对话的摘要
3. 创建包含该摘要的compaction block
4. 使用压缩后的上下文进行回复

基本用法:

在message API请求的context_management.edits中添加compact_20260112的策略来启用缓存

参数

触发配置:

使用trigger参数配置何时触发压缩

自定义摘要指令:

默认的prompt因模型而异,但是可以通过instruction参数提供自定义的指令 而且它不会补充默认的指令,而是完全代替它

压缩后暂停:

使用pause_after_compaction参数设置,这可以使得在继续生成回复之前添加额外的content block(例如保留最近的消息或者特定的指令导向消息)

启用后,API在生成compaction block后会返回带有compaction stop reason的消息

处理compaction block:

触发压缩后,会在压缩完成后assistant回复的开头返回一个compaction block 长时间运行的对话可能会存在多次compaction,最后一个compaction block反应了prompt的最终状态

回传compaction block:

你必须在后续的request中回传compaction block,才能以缩短后的prompt继续对话 最简单的做法是:把整个响应content追加到你的message中

当API收到compaction block时,之前的所有的content block都会被忽略,你可以:

• 在列表中保留原始message,让API处理移除已经压缩的内容
• 手动丢弃已经压缩的内容我

如果你编写自己的 instructions，需告知模型摘要必须保留什么；见 Tell the model what to preserve in compaction summaries。

流式输出:

compaction的流式传输方式与text block不同:

1. 你会先收到一个content_block_start事件
2. 收到一条包含完整摘要内容的content_block_delta(无中间流式片段)
3. 然后时cintent_block_stop事件

Prompt caching:

你可以在compaction block上添加cache control的breakdown来缓存摘要后的内容

通过System prompt最大化缓存命中:

发生压缩时,摘要会称为需要写入缓存的新内容,如果没有额外的缓存断点,会使已经缓存的system prompt失效

为了最大化缓存命中率,会在system prompt的末尾添加一个cache_control的断点,使得system_prompt和对话分开缓存,因此在发生压缩时:

• system prompt缓存依旧有效,从缓存读取
• 将摘要作为新的缓存条目读入

了解用量:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

{
  "usage": {
    "input_tokens": 23000,
    "output_tokens": 1000,
    "iterations": [
      {
        "type": "compaction",
        "input_tokens": 180000,
        "output_tokens": 3500
      },
      {
        "type": "message",
        "input_tokens": 23000,
        "output_tokens": 1000
      }
    ]
  }
}

iteration数组显示每次采样的迭代用量 发生压缩时,你会看到一次compaction迭代,随后是主要的message迭代 最顶层的input_tokens和output_tokens不包含压缩迭代的用量,因此在计算总的用量时,请对usage.iteration的每一个迭代进行求和(包括compaction迭代)

与其他功能结合:

服务端工具:

使用服务端工具（例如 web search）时，会在每次采样迭代开始时检查压缩触发条件。根据触发阈值和生成的输出量，单次请求内可能发生多次压缩。

Token计数

token 计数端点（/v1/messages/count_tokens）会应用 prompt 中已有的 compaction block，但不会触发新的压缩。用它来检查先前压缩后的有效 token 数：

当前限制:

• 摘要使用同一模型:
• 定义了tools时压缩可能失败:当请求包含tools时,模型偶尔会在内部摘要步骤中调用工具,而不是撰写摘要,发生这种情况时,会响应中会返回一个content: null的compaction block 为了防止这种情况,会在instruction中明确告知模型不要调用工具

Context editing:

概述:server-side compaction是最常见的上下文管理措施 而本章中的策略适用于需要更加精细控制需要clear哪些内容的特定场景 允许你有选择性地清楚特定地内容,不仅仅是为了优化成本,也是为了主动筛选模型所见地内容 主要由下面三种策略:

1. tool result clear:
2. think block clear:用于开启了extended thinking时管理think block
3. 客户端SDK压缩(不打算看)

服务端策略:

主要分为两种:tool_result clear和thinking block clear

Tool result clear:

用于清理工具调用地结果(和工具调用:需要配置开启) 激活后,API会清理最旧的工具结果,将其替换为占位文本,表示已经被移除 也可以将clear_tool_inputs设置为true,同时清理tool result和tool call

Thinking block clear:

对于开启extended thing时启用 现在的大部分模型都默认保留think block,并且作为后续的input

context editing和Prompt Caching:

• tool result clear:会使已经缓存的prompt失效,所以应该清理足够多的token使得物有所值,可以使用clear_at_least规定清理token的最少数量
• think block clear:同样的,缓存会在清理发生处失效,常见是将thinking block keep

tool result clear usage:

最常见:使用仅指定策略(即不清除tool call),其他使用默认值

高级配置:其他参数定义清楚行为

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Create a simple command line calculator app using Python",
        }
    ],
    tools=[
        {
            "type": "text_editor_20250728",
            "name": "str_replace_based_edit_tool",
            "max_characters": 10000,
        },
        {"type": "web_search_20250305", "name": "web_search", "max_uses": 3},
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                # Trigger clearing when threshold is exceeded
                "trigger": {"type": "input_tokens", "value": 30000},
                # Number of tool uses to keep after clearing
                "keep": {"type": "tool_uses", "value": 3},
                # Optional: Clear at least this many tokens
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                # Exclude these tools from being cleared
                "exclude_tools": ["web_search"],
            }
        ]
    },
)

可以配置的选项有:

think block clear:

可配置的选项:

keep: 定义要保留的多少个含think block的assistant turn使用{type: “thinking_turns”, value: N}.(管理上下文) 或者直接使用keep: all来保留所有的think blocks(最大化缓存命中)

组合策略:

限制:当使用组合策略时,clear_thinking_20251015比放在edits数组的第一位

上下文编辑响应

你可以使用context_management的响应字段来查看哪些上下文编辑已经应用于你的request,已经有关已清楚内容和输入token的有用统计信息 例如:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    // ...
  ],
  "usage": {
    // ...
  },
  "context_management": {
    "applied_edits": [
      // When using `clear_thinking_20251015`
      {
        "type": "clear_thinking_20251015",
        "cleared_thinking_turns": 3,
        "cleared_input_tokens": 15000
      },
      // When using `clear_tool_uses_20250919`
      {
        "type": "clear_tool_uses_20250919",
        "cleared_tool_uses": 8,
        "cleared_input_tokens": 50000
      }
    ]
  }
}

对于stream响应,相关的信息在最终的message_delta

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "type": "message_delta",
  "delta": {
    "stop_reason": "end_turn",
    "stop_sequence": null
  },
  "usage": {
    "output_tokens": 1024
  },
  "context_management": {
    "applied_edits": [
      // ...
    ]
  }
}

Token count:

用于支持上下文管理,让你预览在context edit后prompt使用多少token

1
2
3
4
5
6

  print(f"Original tokens: {response.context_management.original_input_tokens}")
  print(f"After clearing: {response.input_tokens}")
  print(
      f"Savings: {response.context_management.original_input_tokens - response.input_tokens} tokens"
  )

响应显示context editing之后的token和清楚发生之前的original_input_tokens

与memory tool一起使用

当context到达被清除的阈值时,在被清理之前,收到自动警告以保存重要信息,将对话历史和其他信息保存到memory中

• 保留重要上下文
• 维持长时间的工作流
• 按需访问信息

Prompt Caching

允许你使用prompt prefix匹配来优化API的token用量

对于重复性任务和包含一致元素的prompt会显著降低处理时间和成本

有两种方法来启用Prompt Caching

• automatic cache:在请求的顶层添加单个cache_control字段,系统会自动将缓存的断点应用到最后一个可缓存的block
• 显式缓存断点:将cache_control放在content block上

最简单的方式是使用自动缓存: 使用自动缓存时，系统会缓存直到并包括最后一个可缓存块的全部内容

Prompt Caching怎么工作:

1. 系统检查prompt prefix,查看是否能够查询到
2. 如果能够找到,就直接复用
3. 否则处理完整的prompt

一般来说,缓存的TTL为5min(由模型决定)或1h(需要设置开启,且price更贵)

TTL(生命周期):从写入或者读取该条缓存条目开始而非响应结束的时刻 Prompt Caching缓存完整的前缀: 引用整个prompt—tools,system和messages,知道并包括使用cache_control的block

Automatic Caching:

usage:在单个请求体顶层添加 cache_control字段 将缓存断点应用到最后一个可缓存的block

自动缓存在多轮对话中怎么工作?

随着对话的进行,断点会自动向前移动,到新的请求的最后一个可缓存的block的 而先前的内容通过缓存读取 所以不需要跟随对话去更新cache_control标记

TTL支持:

默认5min,可开启1h,价格不同

与显式缓存结合:

两者是可以兼容的,这个时候,自动缓存断点会占用四个可用断点槽位中的一个 常见用法: 用显式缓存断点缓存system prompt;用自动缓存断点处理对话 将stable prompt和variable prompt分开进行缓存

边界情况

• 如果最后一个块已经带有相同 TTL 的显式 cache_control，自动缓存为 no-op。
• 如果最后一个块带有不同 TTL 的显式 cache_control，API 返回 400 error。
• 如果已经存在 4 个显式块级断点，API 返回 400 error（没有剩余槽位给自动缓存）。
• 如果最后一个块不适合作为自动缓存断点目标，系统会静默向后查找最近的合格块。如果找不到，则跳过缓存。

显式缓存断点

更加精细地控制缓存 usage:将cache_control放在具体的block上

组织你的prompt:

将stable prompt放在prompt开头,是cache_control参数标记在可复用内容的结尾便于缓存 prompt prefix的顺序: tools,system,messages

自动前缀检查如何工作:

三条核心原则:(这个只针对采取这种算法的模型成立)

1. 缓存写入只发生在你的断点处
2. 缓存读取会向后查找先前请求写入的条目
3. 回看窗口为20块 注意此处为block而非记录哦,但是不是在20块结束就停止,也是会继续向前读条目

缓存策略和注意事项

缓存限制:

可缓存Prompt的最短长度,小于这个长度,即使有cache_control也不会缓存

哪些内容可以缓存:

• 工具：tools 数组中的工具定义
• 系统消息：system 数组中的内容块
• 文本消息：messages.content 数组中的内容块，适用于 user 和 assistant 两轮
• 图像和文档：messages.content 数组中的内容块，位于 user 轮
• 工具使用和工具结果：messages.content 数组中的内容块，适用于 user 和 assistant 两轮

哪些内容不能缓存:

• Thinking 块不能用 cache_control 直接缓存。但是，当 thinking 块出现在先前的 assistant 轮中时，它们可以与其他内容一起被缓存。以这种方式缓存时，从缓存读取时它们会计入输入 token。

• 子内容块（例如 citations）本身不能直接缓存。应改为缓存顶层块。

  对于 citations，作为 citations 源材料的顶层文档内容块可以缓存。这样你可以通过缓存 citations 将引用的文档，有效地将 Prompt Caching 与 citations 一起使用。

• 空文本块不能缓存。

哪些会使缓存失效:

理解token分解

input_tokens 字段只表示请求中最后一个缓存断点之后的 token——并非你发送的全部输入 token。

缓存存储和共享

Prompt Caching使用workspace级别隔离

预热缓存

在用户的真实请求之前,把system prompt或者tools等加载进prompt cache中 降低TTFT

工作原理:

在请求中设置 max_tokens: 0。API 将你的 prompt 读入模型，并在任何 cache_control 断点处写入缓存，然后立即返回而不生成任何输出。响应包含空的 content 数组、stop_reason: "max_tokens"，以及完整填充的 usage 块。 将 cache_control 断点放在与后续请求共享的最后一个块上 这意味着应使用显式缓存断点而不是自动缓存，因为自动缓存会把断点放在最后一个块上，而这里最后一个块就是占位符。占位用户消息可以是任何含非空白内容的字符串（此处示例使用 "warmup"）

Mid-conversation system messages and tool changes

基础内容

System指令通常放在顶层的System字段当中,非常适合Prompt Caching Mid-conversation system message可以在不改变顶层System字段的情况下,追加{role: system}指令,且不会将其视为text文本而是视为system指令

Mid-conversation tool change

tool数组在prefix中的位置比顶层的system字段还要靠前,编辑它会使缓存失效 Mid-conversation tool change机制允许你不需要把工具列表固定为整段对话生命周期内不变,而是可以在turn之间更改向模型提供哪些工具: 预先在tools中声明完整的工具集,然后使用tool_addition和tool_removal块,在对话中提供工具或者撤回工具,而tools数组本身不改变 tool_addition和tool_removal是role: system消息的content block 每个块的tool字段引用一项工具而不是定义工具:{“type”: “tool_reference”, “name”: “…”} tools中生命的某项工具从对话开始就会提供给模型,除非声明时哎呦defer_loading: true,就会被保留直到tool_addition将其呈现出来 此外tool_addition也可以重新提供之前被tool_removal的工具

何时使用mid-conversation system message:

会话中的mid-conversation把指令加在消息历史的末尾

工作原理

指令冲突时,较后的system message优先于较前的,相应的,mid-conversation system message优先级高于顶层system字段 role: "system" 消息还可以携带 output_config.effort，从下一个 user turn 起更改 effort 级别(此处的effort为占位符,具体为论文low,high等等)

system message的位置:

在user turn(或者是server tool result结尾的assistant)之后,并且必须是messages中的最后一项或者紧接着的一个assistant turn. 放在交付tool result的user之后,下一个turn之前

放在tool result之后

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

[
  { "role": "user", "content": "Run the test suite and fix any failures." },
  {
    "role": "assistant",
    "content": [{ "type": "tool_use", "id": "toolu_01", "name": "run_tests", "input": {} }]
  },
  {
    "role": "user",
    "content": [
      { "type": "tool_result", "tool_use_id": "toolu_01", "content": "12 passed, 0 failed" }
    ]
  },
  {
    "role": "system",
    "content": "The user sent the following message while you were working: also update the changelog before you finish."
  }
]

此模式用于转达来自该对话最终用户本人的输入。不要用它传递工具输出、检索到的文档或其他第三方内容；将这些内容放在 tool_result 块中（参见 限制）。

限定当前turn的system message:

使用clear_at字段,它有两个取值:

• “never”:该消息在包含它的每次请求中都会在其位置渲染
• “next_user_message”:限定当前turn的,其文本仅在message中其后灭有role: user消息时渲染 此外,仅携带tool_result的user消息也算用户消息

一旦存在更后恶的user_message,该消息就会被清除,仍留在数组中但是不渲染也不占输入

限定当前turn的消息的规则:

• 应该逐字重发已经清除的消息而不是更改clear_at值
• type仅限于文本
• 其block上不能有cache_control
• 位置规则依然生效,无论是否被清除
• assistant turn不会清除它,只有user message会清除它
• token count更碎渲染内容,被清除的消息不会增加user.input_token,也不会增加token计数
• 导出,在被清除之后就不被渲染

限制

• 不能作为第一条消息,毕竟你为什么不放在顶层的system字段中呢?
• 放置的位置收到约束
• 限制在当前turn的system的type仅限为文本
• 不要放置在不受信任的地方

Build an orchestration mode

编排模式是一个会话级别的开关:当开启时,对于每一个任务都是最大级别的effort(agent的思考程度),并将工作默认fan-out给并行的子代理

该模式不是API参数,是由文档中的已有的组件构成的:

1. 1.effort级别:最大的effort的取值
2. a refresher:一条mid-conversation system message告知模式的开启,并且每隔几个对话带一行刷新提醒,并在关闭模式的时候发出通知
3. 工具描述中的持续性授权

note:fan-out会成本的增加成本 实际上使用subagent就是很烧钱

设置循环

三个参数: MAX_CONCURRENT 限制同时运行的子代理数量; MAX_TOTAL_SUBTASKS 限制模型在单次 Workflow 调用中可以排队的数量; 当设置了环境变量 DOC_TEST_MODE = TRUE 时，该检查会把循环限制为单轮，以便自动化文档 harness 验证文件能够编译并迅速结束，而无需跑完整编排 通过常量来控制effort的等级(实际上就是最高的effort),fan-out的形态和refresher的频率

定义模式refresher和notice(包括ENTER和EXIT)

这些message都刻意地写的很短,他们切换模式并且指向工具描述(workflow工具)–重量级的指令就在那 ENTER只在开启模式时发送一次,refresh则每隔几个turns发送一次,exit_notice则只在模式关闭的时候发送一次

在工具描述中授予持续性权限

Workflow工具承载真正的行为契约: opt-in规则(指的是进入编排模式的规则是需要用户主动同意的),模式开启期间适用的持续性授权,用于确定fan-out规模的粒度指引,还有模式可以采取的质量检测模式如:验证波、完备性批评者、多阶段分步

而子代理则会得到一个report_finging工具,使其结果JSON结构化 bash工具则是Anthropic定义的bash_20250124,在本地运行

Workflow_tool定义非常的长,有兴趣自己去看一看

在本地运行bash工具

为什么会强调是本地运行呢? 强调你harness的运行环境,比如Windows,Linux,云服务器等等

Bash处理器运行带有timeout的命令,并且捕获合并后的stdout和stderr并截断结果,防止失控命令淹没上下文 命令的运行环境就是你启动模式对应的文件目录 而当你设置了DOC_TEST_MODE= TRUE时,harness会改为给bash一个小型的一次性目录,在退出时直接删除

运行一个子代理Subagent

每一个workflow的子任务都会变成带bash工具的小型代理循环,并且effort等级于主agent相等 每次API调用都有按请求的超时上限,所以连接中断只会让一个子代理降级,而不会卡住整个运行

将结果写入jouornal,方便重跑时continue

启动子代理冲头开始的成本很高,一个小型的基于内容寻址的journal使其幂等: 在fan-out subagent之前,现在本地的JSON文件中寻找它的prompt的SHA-256,如果已经有记录了就返回该结果.中断运行后再跑,就只有没有完成的子任务会被重新计算 journal会在多次运行中去重,但是不会在单次fan-out内去重 如果你想从头再来,那你就删掉journal

先fan-out,再验证

fan-out 最多接受 MAX_TOTAL_SUBTASKS 条 prompt，经 journal 运行，同时进行中的不超过 MAX_CONCURRENT 个,并隔离失败,使得一个损坏的子代理降级为字符串,而不是使得整个运行失败 第一波fan-out完成之后,会复用同一条子代理路径,视图反驳每一条结果

用Mid-conversation的system message切换模式

代理先追加用户信息,再追加本轮的system message,这样更适合于prompt caching

迈向生产级Harness

• 带沙箱的编排脚本
• 持久journaling
• 预算强制

Cache diagnostics

在没有Cache diagnostic的情况下,缓存失效的唯一信号是usage.cache_read_input_tokens = 0 Cache diagnostic通过API对比两次请求,告诉你他们在哪处分叉(（model、system prompt、tools 或消息历史）),而你需要做的仅仅是传入上一次响应的ID 解析:通过分析请求的前缀结构,来查看前后两次请求的前缀最开始的不匹配处也就是分叉处

How to work

当beta header存在,API会给每个request存储一份fingerprint,且将其与id建立起key-value的关系,而在下一次的请求中,将该 id 作为diagnostics.previous_message_id 传入 然后API会给新的request创建一个新的fingerprint,通过id访问前一个请求的fingerprint和当前请求的fingerprint进行对比 对比针对的是请求的结构,与缓存实际命中无关,所以结合起来使用可以帮助你分析为什么缓存失效了 fingerprint的内容包括: 哈希和token数量估计(绝对不包含原始的prompt),保存时间有限且scope为你的workspace

基本用法:

每一次turn都发送beta header,第一次传入的id为null,后续每一次请求传入上一次响应中的id

Stream:

在stream中,diagnostic出现在message_start事件上 message_start事件携带完整的diagnostic字段

在对话循环中贯穿diagnostic

响应格式:

响应message上的diagnostic可能有以下四种状态

当cache miss!= null时,形态如下:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

{
  "id": "msg_01Xyz...",
  "type": "message",
  "role": "assistant",
  "content": [{ "type": "text", "text": "..." }],
  "usage": {
    "input_tokens": 42,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 41850,
    "output_tokens": 210
  },
  "diagnostics": {
    "cache_miss_reason": {
      "type": "system_changed",
      "cache_missed_input_tokens": 41850
    }
  }
}

缓存未命中原因类型

note:

四种 *_changed 类型还会附带一个 cache_missed_input_tokens 整数：估计有多少 input token 落在分歧点之后，让你对损失了多少可缓存前缀有个量级感。该值由 tokenization 之前的字节长度推导，因此应视为量级指标而非计费数字。它可能与 usage.input_tokens 不同（偶尔还会更大）。

结合usage解读diagnostic

diagnostics 回答「我的请求变了吗？ usage.cache_read_input_tokens 回答「缓存命中了吗？」 两者结合可惜分析缓存未命中的原因

Token counting

作用:在你把message发给Claude之前确定其中的token数量

如何统计 message tokens

token counting endpoint 接受与创建 message 相同的结构化输入列表，包括对 system prompt、tools、images 和 PDFs 的支持。响应中包含输入 tokens 的总数。

对于 Messages API 会接受、但本 endpoint 不接受的少数输入，该 endpoint 会返回 invalid_request_error：例如 web search、web fetch、code execution 和 tool search 等 server tools（advisor tool 除外的所有 server tool）、MCP connector，以及 source 为 url 或 file 的 image 或 document blocks。统计图片和 PDF 时请以 base64 发送。对于使用 server tools 或 MCP servers 的请求，Messages API 响应会在其 usage 对象中报告所用 tokens。

概述

上下文编辑（context editing）允许你在对话历史增长时有选择地清除特定内容。这不仅是为了优化成本并保持在限制之内，更是为了主动筛选 Claude 所见的内容：上下文是一种收益递减的有限资源，无关内容会降低模型的专注度。上下文编辑让你在运行时对这些筛选进行精细控制。有关上下文管理背后的更广泛原则，请参阅 有效的上下文工程。本页涵盖：

• 工具结果清除 - 最适合大量使用工具、旧工具结果不再需要的智能体工作流
• thinking block 清除 - 用于在使用 extended thinking 时管理 thinking block，可选择保留近期 thinking 以维持上下文连续性
• 客户端 SDK 压缩 - 一种基于 SDK 的摘要式上下文管理替代方案（通常更推荐服务端压缩）

服务端策略

1
2
3
4
5
6
7
8

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Search for recent developments in AI"}],
    tools=[{"type": "web_search_20250305", "name": "web_search"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Create a simple command line calculator app using Python",
        }
    ],
    tools=[
        {
            "type": "text_editor_20250728",
            "name": "str_replace_based_edit_tool",
            "max_characters": 10000,
        },
        {"type": "web_search_20250305", "name": "web_search", "max_uses": 3},
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                # Trigger clearing when threshold is exceeded
                "trigger": {"type": "input_tokens", "value": 30000},
                # Number of tool uses to keep after clearing
                "keep": {"type": "tool_uses", "value": 3},
                # Optional: Clear at least this many tokens
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                # Exclude these tools from being cleared
                "exclude_tools": ["web_search"],
            }
        ]
    },
)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            }
        ]
    },
)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 3},
            }
        ]
    },
)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": "all",
            }
        ]
    },
)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[
        {
            "role": "user",
            "content": "Search for the latest developments in quantum error correction and summarize the key breakthroughs.",
        }
    ],
    tools=[
        {
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5,
        }
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            },
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 50000},
                "keep": {"type": "tool_uses", "value": 5},
            },
        ]
    },
)

print(response)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    // ...
  ],
  "usage": {
    // ...
  },
  "context_management": {
    "applied_edits": [
      // When using `clear_thinking_20251015`
      {
        "type": "clear_thinking_20251015",
        "cleared_thinking_turns": 3,
        "cleared_input_tokens": 15000
      },
      // When using `clear_tool_uses_20250919`
      {
        "type": "clear_tool_uses_20250919",
        "cleared_tool_uses": 8,
        "cleared_input_tokens": 50000
      }
    ]
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "type": "message_delta",
  "delta": {
    "stop_reason": "end_turn",
    "stop_sequence": null
  },
  "usage": {
    "output_tokens": 1024
  },
  "context_management": {
    "applied_edits": [
      // ...
    ]
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

response = client.beta.messages.count_tokens(
    model="claude-opus-5",
    messages=[{"role": "user", "content": "Continue our conversation..."}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 30000},
                "keep": {"type": "tool_uses", "value": 5},
            }
        ]
    },
)

print(f"Original tokens: {response.context_management.original_input_tokens}")
print(f"After clearing: {response.input_tokens}")
print(
    f"Savings: {response.context_management.original_input_tokens - response.input_tokens} tokens"
)

1
2
3
4
5
6

{
  "input_tokens": 25000,
  "context_management": {
    "original_input_tokens": 70000
  }
}

1
2
3
4
5
6
7
8

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Hello"}],
    tools=[{"type": "memory_20250818", "name": "memory"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

[
  { "role": "user", "content": "Analyze all files and write a report..." },
  { "role": "assistant", "content": "I'll help. Let me start by reading..." },
  {
    "role": "user",
    "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }]
  },
  { "role": "assistant", "content": "Based on file1.txt, I see..." },
  {
    "role": "user",
    "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }]
  },
  { "role": "assistant", "content": "After analyzing file2.txt..." }
  // ... 50 more exchanges like this ...
]

1
2
3
4
5
6

[
  {
    "role": "assistant",
    "content": "# Task Overview\nThe user requested analysis of directory files to produce a summary report...\n\n# Current State\nAnalyzed 52 files across 3 subdirectories. Key findings documented in report.md...\n\n# Important Discoveries\n- Configuration files use YAML format\n- Found 3 deprecated dependencies\n- Test coverage at 67%\n\n# Next Steps\n1. Analyze remaining files in /src/legacy\n2. Complete final report sections...\n\n# Context to Preserve\nUser prefers markdown format with executive summary first..."
  }
]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

</Accordion>

### 限制

#### 服务端工具

<Warning>
在使用 [web search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool) 或 [web fetch](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool) 等服务端工具时，压缩需要特别考虑。
</Warning>

使用服务端工具时，SDK 可能错误计算 token 用量，导致压缩在错误的时间触发。

例如，在 web search 操作之后，API 响应可能显示：

```json Output
{
"usage": {
  "input_tokens": 63000,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 270000,
  "output_tokens": 1400
}
}

上下文窗口如何工作

“上下文窗口”（context window）指语言模型在生成回复时可参考的全部文本，包括回复本身。这不同于语言模型训练所用的大规模语料，而是模型的“工作记忆”。更大的上下文窗口让模型能够处理更复杂、更长的 prompt，但更多上下文并不自动意味着更好。随着 token 数量增长，准确性和召回会下降，这一现象称为 context rot。因此，策选上下文中有什么，与可用空间有多大同样重要。

下图说明了 API 请求的标准上下文窗口行为1：

1 诸如 claude.ai 之类的聊天界面也可以按滚动的“先进先出”方式管理上下文窗口。

• token 逐步累积： 随着对话按 turn 推进，每条 user message 和 assistant 回复都会在上下文窗口中累积，且先前的 turn 会被完整保留。

• 上下文窗口容量： 上下文窗口（最多 1M tokens，取决于模型）保存对话历史，加上 Claude 新生成的输出。

• 输入-输出流程： 每个 turn 包括：

  • 输入阶段： 包含全部先前对话历史加上当前 user message
  • 输出阶段： 生成一段文本回复，该回复会成为下一 turn 输入的一部分

请求中的所有内容都计入上下文窗口：system prompt、messages 中的每条消息（包括工具结果、图片和文档），以及你的工具定义。Claude 为本 turn 生成的输出（包括其 extended thinking）也计入。每次响应都会在 usage 字段中报告该请求消耗了什么。如果你使用 Prompt Caching，输入计数会拆分到 input_tokens、cache_read_input_tokens 和 cache_creation_input_tokens，这三项都计入窗口。要在发送前估算请求，使用 token counting API。

各模型的上下文窗口大小

Claude Fable 5.1、Claude Mythos 5.1、Claude Fable 5、Claude Mythos 5、Claude Opus 5、Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6、Claude Sonnet 5、Claude Sonnet 4.6 和 Claude Mythos Preview 具有 1M-token 上下文窗口。对其中任一模型的单次请求最多可生成 128k 输出 tokens（max_tokens）。其他 Claude 模型，包括 Claude Sonnet 4.5，具有 200k-token 上下文窗口。

对每个具有 1M-token 上下文窗口的模型，1M 是默认值：你不需要 beta header，长上下文请求按 标准定价 计费。

单次请求最多可包含 600 张图片或 PDF 页（对具有 200k-token 上下文窗口的模型为 100）。如果你发送大量图片或大型文档，可能会在达到 token 限制之前先达到 请求大小限制。

各模型上下文窗口大小列表见 模型对比 表。

带 thinking 的上下文窗口

使用 thinking 时，所有输入和输出 tokens（包括 thinking tokens）都计入上下文窗口限制，在多 turn 情况下有一些细微差别。

thinking tokens 是你的 max_tokens 参数的子集，按输出 tokens 计费，并计入速率限制。使用 adaptive thinking 时，Claude 会动态决定其 thinking 分配，因此 thinking token 用量会因请求而异。

先前 assistant turn 中的 thinking blocks 是否留在上下文窗口中取决于模型。在 Claude Opus 4.5 及之后的 Opus 模型、Claude Sonnet 4.6 及之后的 Sonnet 模型、Claude Fable 5.1、Claude Mythos 5.1、Claude Fable 5、Claude Mythos 5 和 Claude Mythos Preview 上，API 默认保留先前的 thinking blocks，它们像其他输入 tokens 一样计入上下文窗口。在更早的 Opus 和 Sonnet 模型以及所有 Haiku 模型上，当你把先前的 thinking blocks 传回时，API 会自动从对话历史中剥离它们，从而为对话内容保留 token 容量。各模型默认值见 thinking block 按模型的保留策略。要向任一方向覆盖默认值，使用 thinking block 清除。

下图展示了在会剥离先前 thinking blocks 的模型上启用 thinking 时如何管理 tokens：

• 剥离 thinking blocks： 在会剥离先前 thinking blocks 的模型上，thinking blocks（深灰色所示）在每个 turn 的输出阶段生成，但不会作为后续 turn 的输入 tokens 向前携带。你不需要自己剥离 thinking blocks：如果你把它们传回，Claude API 会自动剥离。
• 计费： thinking tokens 在生成时作为输出 tokens 计费一次。在会保留先前 thinking blocks 的模型上，被保留的 blocks 随后会成为后续请求输入的一部分，并像对话历史的其余部分一样作为输入 tokens 计费。

带 thinking 和工具调用的上下文窗口

下图说明了在会剥离先前 thinking blocks 的模型上，将 thinking 与工具调用结合时如何管理 tokens：

• 将 thinking 与工具调用一起使用时的注意事项：

  • 当你提交工具结果时，必须包含伴随该工具请求的整个未经修改的 thinking block，包括其 signature。
  • API 使用加密签名来验证 thinking block 的真实性。如果你修改了 thinking block，API 会返回错误。

1

<budget:token_budget>200000</budget:token_budget>

1

<system_warning>Token usage: 35000/200000; 165000 remaining</system_warning>

• 状态: Beta
• Beta header: compact-2026-01-12
• ZDR: 符合条件（不含 Covered Models）
• 支持的模型: claude-fable-5-1, claude-mythos-5-1, claude-fable-5, claude-mythos-5, claude-mythos-preview, claude-opus-5, claude-opus-4-8, claude-opus-4-7, claude-opus-4-6, claude-sonnet-5, claude-sonnet-4-6
• 平台: Claude API (beta), Claude Platform on AWS (beta), Amazon Bedrock (beta), Google Cloud (beta), Microsoft Foundry (beta)

压缩通过在接近上下文窗口上限时自动摘要较旧的上下文，来延长长时间运行对话和任务的有效上下文长度。它也会保持活动上下文较小：随着对话增长，回复质量会下降，因此压缩会用简洁摘要替换较旧内容。

适用于：

• 基于聊天的多轮对话，希望用户长时间使用同一会话
• 需要大量后续工作（通常是工具调用）且可能超出上下文窗口的面向任务的 prompt

压缩如何工作

启用压缩后，当对话达到所配置的 token 阈值时，Claude 会自动对对话进行摘要。API 会：

1. 检测输入 tokens 何时达到你指定的触发阈值。
2. 生成当前对话的摘要。
3. 创建包含该摘要的 compaction block。
4. 使用压缩后的上下文继续回复。

在后续请求中，将响应追加到你的 messages。API 会自动丢弃 compaction block 之前的所有 content block，并从摘要处继续对话。

基本用法

通过在 Messages API 请求的 context_management.edits 中添加 compact_20260112 策略来启用压缩。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Help me build a website"}]

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

# Append the response (including any compaction block) to continue the conversation
messages.append({"role": "assistant", "content": response.content})

参数

触发配置

使用 trigger 参数配置何时触发压缩：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": 150000},
            }
        ]
    },
)

自定义摘要指令

默认摘要 prompt 因模型而异。各默认 prompt 都指示 Claude 在 <summary></summary> 标签内撰写摘要，并包含在未来上下文窗口中继续任务所需的信息。例如，部分模型使用以下 prompt：

1

You have written a partial transcript for the initial task above. Please write a summary of the transcript. The purpose of this summary is to provide continuity so you can continue to make progress towards solving the task in a future context, where the raw history above may not be accessible and will be replaced with this summary. Write down anything that would be helpful, including the state, next steps, learnings etc. You must wrap your summary in a <summary></summary> block.

可通过 instructions 参数提供自定义指令。自定义指令不会补充默认 prompt，而是完全替换它：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "instructions": "Focus on preserving code snippets, variable names, and technical decisions.",
            }
        ]
    },
)

在 Claude Fable 5.1 和 Claude Mythos 5.1 上，带自定义 instructions 的请求仅从可见对话进行摘要：更早的 thinking block 不在摘要器的输入中。

压缩后暂停

使用 pause_after_compaction 在生成压缩摘要后暂停 API。这使你可以在 API 继续生成回复之前添加额外的 content block（例如保留最近的消息或特定的指令导向消息）。

启用后，API 在生成 compaction block 后会返回带 compaction stop reason 的消息：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [{"type": "compact_20260112", "pause_after_compaction": True}]
    },
)

# Check if compaction triggered a pause
if response.stop_reason == "compaction":
    # Response contains only the compaction block
    messages.append({"role": "assistant", "content": response.content})

    # Continue the request
    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-5",
        max_tokens=4096,
        messages=messages,
        context_management={"edits": [{"type": "compact_20260112"}]},
    )

强制执行总 token 预算

当模型处理带有多次工具调用迭代的长任务时，总 token 消耗可能显著增长。你可以将 pause_after_compaction 与压缩计数器结合，以估算累计用量，并在达到预算后优雅地收尾任务。

此示例仅出现在 SDK 语言中：其价值在于请求周围的预算跟踪逻辑。原始请求将 触发配置 中的 trigger 与 压缩后暂停 中的 pause_after_compaction 结合。

  # Estimate total tokens consumed; prompt wrap-up if over budget
  if n_compactions * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET:
      messages.append(
          {
              "role": "user",
              "content": "Please wrap up your current work and summarize the final state.",
          }
      )

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

</CodeGroup>

## 处理 `compaction` block

触发压缩时，API 会在 assistant 回复的开头返回一个 `compaction` block。

长时间运行的对话可能发生多次压缩。最后一个 `compaction` block 反映 prompt 的最终状态，用生成的摘要替换其之前的内容。

```json Output
{
"content": [
  {
    "type": "compaction",
    "content": "Summary of the conversation: The user requested help building a web scraper..."
  },
  {
    "type": "text",
    "text": "Based on our conversation so far..."
  }
]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)
# After receiving a response with a compaction block
messages.append({"role": "assistant", "content": response.content})

# Continue the conversation
messages.append({"role": "user", "content": "Now add error handling"})

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