--- title: 在 token 閾值時進行壓縮 url: https://platform.claude.com/docs/zh-TW/build-with-claude/compaction-threshold description: 當對話達到您設定的 token 閾值時，讓 API 在一般請求中自動摘要較早的上下文。 featureMetadata: status: beta betaHeader: compact-2026-01-12 zdr: eligibility: eligible note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements). supportedModels: - claude-fable-5-1 - claude-mythos-5-1 - claude-fable-5 - claude-mythos-5 - claude-mythos-preview - claude-opus-5-5 - claude-opus-5 - claude-opus-4-8 - claude-opus-4-7 - claude-opus-4-6 - claude-sonnet-5-5 - claude-sonnet-5 - claude-sonnet-4-6 - claude-haiku-5-5 supportedPlatforms: Claude API: beta Claude Platform on AWS: beta Amazon Bedrock: beta Google Cloud: beta Microsoft Foundry: beta --- 「Threshold compaction」（閾值壓縮）是自動形式的「compaction」（壓縮）：您在一般請求上設定 token 閾值，一旦達到該閾值，API 就會在請求進行途中摘要較舊的上下文。它與「on-demand compaction」（隨需壓縮）一同受到支援，在隨需壓縮中，由您決定何時撰寫摘要（請參閱[隨需壓縮](https://platform.claude.com/docs/zh-TW/build-with-claude/compaction-on-demand)）。若要在兩者之間做選擇，請參閱[選擇如何壓縮](https://platform.claude.com/docs/zh-TW/build-with-claude/compaction#choose-how-to-compact)。壓縮會在接近「context window」（上下文視窗）限制時自動摘要較舊的上下文，藉此延長長時間執行的對話與任務的有效上下文長度。它也能讓作用中的上下文保持精簡：隨著對話增長，回應品質會下降，因此壓縮會以簡潔的摘要取代較舊的內容。若要深入了解長上下文為何會導致品質下降，以及壓縮如何提供幫助，請參閱 [Effective context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)。這非常適合： * 以聊天為基礎的多輪對話，您希望使用者能長時間使用同一個聊天 * 需要大量後續工作（通常是「tool use」（工具使用））且可能超出上下文視窗的任務導向提示 ## 壓縮的運作方式啟用壓縮後，當對話達到所設定的 token 閾值時，Claude 會自動摘要您的對話。API 會： 1. 偵測輸入 token 何時達到您指定的觸發閾值。 2. 產生目前對話的摘要。 3. 建立包含該摘要的 `compaction` 區塊。 4. 以壓縮後的上下文繼續產生回應。在後續請求中，請將回應附加到您的訊息中。API 會自動捨棄 `compaction` 區塊之前的所有內容區塊，並從摘要繼續對話。 ![Compaction flow（壓縮流程）：當輸入 token 達到觸發條件時，Claude 會將摘要寫入 compaction 區塊並繼續](https://platform.claude.com/docs/zh-TW/images/compaction-flow.svg) ## 基本用法在您的 Messages API 請求中，將 `compact_20260112` 策略加入 `context_management.edits` 即可啟用壓縮。 ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: compact-2026-01-12" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 4096, "messages": [ { "role": "user", "content": "Help me build a website" } ], "context_management": { "edits": [ { "type": "compact_20260112" } ] } }' ``` ```bash CLI ant beta:messages create --beta compact-2026-01-12 <<'YAML' model: claude-opus-5-5 max_tokens: 4096 messages: - role: user content: Help me build a website context_management: edits: - type: compact_20260112 YAML ``` ```python Python 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-5", max_tokens=4096, messages=messages, context_management={"edits": [{"type": "compact_20260112"}]}, ) # 附加回應（包括任何 compaction 區塊）以繼續對話 messages.append({"role": "assistant", "content": response.content}) ``` ```typescript TypeScript const client = new Anthropic(); const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [ { role: "user", content: "Help me build a website" } ]; const response = await client.beta.messages.create({ betas: ["compact-2026-01-12"], model: "claude-opus-5-5", max_tokens: 4096, messages, context_management: { edits: [ { type: "compact_20260112" } ] } }); // 附加回應（包括任何 compaction 區塊）以繼續對話 messages.push({ role: "assistant", content: response.content }); ``` ```csharp C# AnthropicClient client = new(); var messages = new List { new() { Role = Role.User, Content = "Help me build a website" } }; var parameters = new MessageCreateParams { Betas = ["compact-2026-01-12"], Model = Model.ClaudeOpus5_5, MaxTokens = 4096, Messages = messages, ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit()] } }; var response = await client.Beta.Messages.Create(parameters); // 將回應（包括任何 compaction 區塊）附加至對話中，以繼續進行對話 messages.Add(new BetaMessageParam { Role = Role.Assistant, Content = response.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList() }); Console.WriteLine(response); ``` ```go Go client := anthropic.NewClient() messages := []anthropic.BetaMessageParam{ anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Help me build a website")), } response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 4096, Messages: messages, ContextManagement: anthropic.BetaContextManagementConfigParam{ Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}}, }, }, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) if err != nil { log.Fatal(err) } // 附加回應（包含任何 compaction 區塊）以繼續對話 messages = append(messages, response.ToParam()) fmt.Println(response) ``` ```java Java import com.anthropic.models.beta.messages.BetaContextManagementConfig; import com.anthropic.models.beta.messages.BetaCompact20260112Edit; // ... AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .addBeta("compact-2026-01-12") .model(Model.CLAUDE_OPUS_5_5) .maxTokens(4096L) .addUserMessage("Help me build a website") .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder().build()) .build()) .build(); BetaMessage response = client.beta().messages().create(params); // 附加回應（包含任何 compaction 區塊）以繼續對話 // 方法是將其納入下一個請求的 messages 中 System.out.println(response); ``` ```php PHP $client = new Client(); $messages = [ ['role' => 'user', 'content' => 'Help me build a website'] ]; $response = $client->beta->messages->create( maxTokens: 4096, messages: $messages, model: 'claude-opus-5-5', betas: ['compact-2026-01-12'], contextManagement: [ 'edits' => [ ['type' => 'compact_20260112'] ] ] ); // 附加回應以繼續對話，包含任何 compaction block（壓縮區塊） $messages[] = ['role' => 'assistant', 'content' => $response->content]; echo json_encode($response, JSON_PRETTY_PRINT), PHP_EOL; ``` ```ruby Ruby client = Anthropic::Client.new messages = [ { role: "user", content: "Help me build a website" } ] response = client.beta.messages.create( betas: ["compact-2026-01-12"], model: "claude-opus-5-5", max_tokens: 4096, messages: messages, context_management: { edits: [{ type: "compact_20260112" }] } ) # 附加回應（包含任何 compaction 區塊）以繼續對話 messages << { role: "assistant", content: response.content } puts response ``` ## 參數 | 參數 | 類型 | 預設值 | 說明 | | ------------------------ | ------- | ------------------------------------------- | -------------------------------------------------------------- | | `type` | string | 必填 | 必須為 `"compact_20260112"` | | `trigger` | object | `{"type": "input_tokens", "value": 150000}` | 何時觸發壓縮。`input_tokens` 是唯一支援的觸發類型。`value` 必須至少為 50,000 個 token。 | | `pause_after_compaction` | boolean | `false` | 產生壓縮摘要後是否暫停 | | `instructions` | string | `null` | 自訂摘要提示。提供時會完全取代預設提示。 | ### 觸發設定使用 `trigger` 參數設定壓縮的觸發時機： ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: compact-2026-01-12" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 4096, "messages": [ { "role": "user", "content": "Hello, Claude" } ], "context_management": { "edits": [ { "type": "compact_20260112", "trigger": { "type": "input_tokens", "value": 150000 } } ] } }' ``` ```bash CLI ant beta:messages create --beta compact-2026-01-12 <<'YAML' model: claude-opus-5-5 max_tokens: 4096 messages: - role: user content: Hello, Claude context_management: edits: - type: compact_20260112 trigger: type: input_tokens value: 150000 YAML ``` ```python Python client = anthropic.Anthropic() messages = [{"role": "user", "content": "Hello, Claude"}] response = client.beta.messages.create( betas=["compact-2026-01-12"], model="claude-opus-5-5", max_tokens=4096, messages=messages, context_management={ "edits": [ { "type": "compact_20260112", "trigger": {"type": "input_tokens", "value": 150000}, } ] }, ) ``` ```typescript TypeScript const client = new Anthropic(); const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [ { role: "user", content: "Hello, Claude" } ]; const response = await client.beta.messages.create({ betas: ["compact-2026-01-12"], model: "claude-opus-5-5", max_tokens: 4096, messages, context_management: { edits: [ { type: "compact_20260112", trigger: { type: "input_tokens", value: 150000 } } ] } }); ``` ```csharp C# AnthropicClient client = new(); List messages = [new() { Role = Role.User, Content = "Hello" }]; var parameters = new MessageCreateParams { Model = Model.ClaudeOpus5_5, MaxTokens = 4096, Betas = ["compact-2026-01-12"], Messages = messages, ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit { Trigger = new BetaInputTokensTrigger(150000) }] } }; var message = await client.Beta.Messages.Create(parameters); Console.WriteLine(message); ``` ```go Go client := anthropic.NewClient() messages := []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude"))} response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 4096, Messages: messages, ContextManagement: anthropic.BetaContextManagementConfigParam{ Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{ Trigger: anthropic.BetaInputTokensTriggerParam{Value: 150000}, }}, }, }, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) if err != nil { log.Fatal(err) } fmt.Println(response) ``` ```java Java import com.anthropic.models.beta.messages.BetaContextManagementConfig; import com.anthropic.models.beta.messages.BetaCompact20260112Edit; import com.anthropic.models.beta.messages.BetaInputTokensTrigger; // ... AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(4096L) .addBeta("compact-2026-01-12") .addUserMessage("Hello, Claude") .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder() .trigger(BetaInputTokensTrigger.builder() .value(150000L) .build()) .build()) .build()) .build(); BetaMessage response = client.beta().messages().create(params); System.out.println(response); ``` ```php PHP $client = new Client(); $messages = [['role' => 'user', 'content' => 'Hello, Claude']]; $message = $client->beta->messages->create( maxTokens: 4096, messages: $messages, model: 'claude-opus-5-5', betas: ['compact-2026-01-12'], contextManagement: [ 'edits' => [ [ 'type' => 'compact_20260112', 'trigger' => [ 'type' => 'input_tokens', 'value' => 150000 ] ] ] ] ); echo $message; ``` ```ruby Ruby client = Anthropic::Client.new messages = [{ role: "user", content: "Hello, Claude" }] response = client.beta.messages.create( betas: ["compact-2026-01-12"], model: "claude-opus-5-5", max_tokens: 4096, messages: messages, context_management: { edits: [ { type: "compact_20260112", trigger: { type: "input_tokens", value: 150000 } } ] } ) puts response ``` ### 自訂摘要指示預設的摘要提示因模型而異。每個預設提示都會指示 Claude 在 `

` 標籤內撰寫摘要，並包含在未來的上下文視窗中繼續任務所需的資訊。例如，部分模型使用以下提示： ```text wrap 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

block. ``` 您可以透過 `instructions` 參數提供自訂指示。自訂指示不會補充預設提示，而是會完全取代它： ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: compact-2026-01-12" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 4096, "messages": [ { "role": "user", "content": "Hello, Claude" } ], "context_management": { "edits": [ { "type": "compact_20260112", "instructions": "Focus on preserving code snippets, variable names, and technical decisions." } ] } }' ``` ```bash CLI ant beta:messages create --beta compact-2026-01-12 <<'YAML' model: claude-opus-5-5 max_tokens: 4096 messages: - role: user content: Hello, Claude context_management: edits: - type: compact_20260112 instructions: >- Focus on preserving code snippets, variable names, and technical decisions. YAML ``` ```python Python client = anthropic.Anthropic() messages = [{"role": "user", "content": "Hello, Claude"}] response = client.beta.messages.create( betas=["compact-2026-01-12"], model="claude-opus-5-5", max_tokens=4096, messages=messages, context_management={ "edits": [ { "type": "compact_20260112", "instructions": "Focus on preserving code snippets, variable names, and technical decisions.", } ] }, ) ``` ```typescript TypeScript const client = new Anthropic(); const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [ { role: "user", content: "Hello, Claude" } ]; const response = await client.beta.messages.create({ betas: ["compact-2026-01-12"], model: "claude-opus-5-5", max_tokens: 4096, messages, context_management: { edits: [ { type: "compact_20260112", instructions: "Focus on preserving code snippets, variable names, and technical decisions." } ] } }); ``` ```csharp C# AnthropicClient client = new(); var parameters = new MessageCreateParams { Betas = ["compact-2026-01-12"], Model = Model.ClaudeOpus5_5, MaxTokens = 4096, Messages = [ new BetaMessageParam { Role = Role.User, Content = "Help me build a Python web scraper" }, new BetaMessageParam { Role = Role.Assistant, Content = "I'll help you build a web scraper..." }, new BetaMessageParam { Role = Role.User, Content = "Add support for JavaScript-rendered pages" } ], ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit { Instructions = "Focus on preserving code snippets, variable names, and technical decisions." }] } }; var message = await client.Beta.Messages.Create(parameters); Console.WriteLine(message); ``` ```go Go client := anthropic.NewClient() response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 4096, Messages: []anthropic.BetaMessageParam{ anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Help me build a Python web scraper")), {Role: anthropic.BetaMessageParamRoleAssistant, Content: []anthropic.BetaContentBlockParamUnion{anthropic.NewBetaTextBlock("I'll help you build a web scraper...")}}, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Add support for JavaScript-rendered pages")), }, ContextManagement: anthropic.BetaContextManagementConfigParam{ Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{ Instructions: anthropic.String("Focus on preserving code snippets, variable names, and technical decisions."), }}, }, }, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) if err != nil { log.Fatal(err) } fmt.Println(response) ``` ```java Java import com.anthropic.models.beta.messages.BetaContextManagementConfig; import com.anthropic.models.beta.messages.BetaCompact20260112Edit; // ... AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .addBeta("compact-2026-01-12") .model(Model.CLAUDE_OPUS_5_5) .maxTokens(4096L) .addUserMessage("Help me build a Python web scraper") .addAssistantMessage("I'll help you build a web scraper...") .addUserMessage("Add support for JavaScript-rendered pages") .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder() .instructions("Focus on preserving code snippets, variable names, and technical decisions.") .build()) .build()) .build(); BetaMessage response = client.beta().messages().create(params); System.out.println(response); ``` ```php PHP $client = new Client(); $response = $client->beta->messages->create( maxTokens: 4096, messages: [ ['role' => 'user', 'content' => 'Help me build a Python web scraper'], ['role' => 'assistant', 'content' => "I'll help you build a web scraper..."], ['role' => 'user', 'content' => 'Add support for JavaScript-rendered pages'] ], model: 'claude-opus-5-5', betas: ['compact-2026-01-12'], contextManagement: [ 'edits' => [ [ 'type' => 'compact_20260112', 'instructions' => 'Focus on preserving code snippets, variable names, and technical decisions.' ] ] ] ); echo json_encode($response, JSON_PRETTY_PRINT), PHP_EOL; ``` ```ruby Ruby client = Anthropic::Client.new response = client.beta.messages.create( betas: ["compact-2026-01-12"], model: "claude-opus-5-5", max_tokens: 4096, messages: [ { role: "user", content: "Help me build a Python web scraper" }, { role: "assistant", content: "I'll help you build a web scraper..." }, { role: "user", content: "Add support for JavaScript-rendered pages" } ], context_management: { edits: [ { type: "compact_20260112", instructions: "Focus on preserving code snippets, variable names, and technical decisions." } ] } ) puts response ``` 在 Claude 5.1 及更新的模型上，帶有自訂 `instructions` 的請求只會根據可見的對話進行摘要：先前的思考區塊不會成為摘要器輸入的一部分。 ### 壓縮後暫停使用 `pause_after_compaction` 可讓 API 在產生壓縮摘要後暫停。這讓您可以在 API 繼續產生回應之前，加入額外的內容區塊（例如保留最近的訊息或特定的指示導向訊息）。啟用後，API 會在產生壓縮區塊後，回傳一則帶有 `compaction` 停止原因的訊息： ```bash cURL # pause_after_compaction 會在壓縮（compaction）完成後立即停止回應， # 並傳回摘要，讓您能在繼續之前調整訊息。繼續 # 步驟不易以單次 shell 指令呈現；請參閱 SDK 分頁 # 以了解完整的暫停與繼續流程。單一暫停請求： curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: compact-2026-01-12" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 4096, "messages": [ { "role": "user", "content": "Hello, Claude" } ], "context_management": { "edits": [ { "type": "compact_20260112", "pause_after_compaction": true } ] } }' ``` ```bash CLI # pause_after_compaction 會在產生 compaction（壓縮） # 摘要後立即停止回應，讓您在繼續之前調整訊息。繼續 # 這個步驟不易以單次 CLI 指令呈現；完整的暫停與繼續流程 # 請參閱 SDK 分頁。單一暫停請求： ant beta:messages create --beta compact-2026-01-12 --format jsonl <<'YAML' model: claude-opus-5-5 max_tokens: 4096 messages: - role: user content: Hello, Claude context_management: edits: - type: compact_20260112 pause_after_compaction: true YAML ``` ```python Python client = anthropic.Anthropic() messages = [{"role": "user", "content": "Hello, Claude"}] response = client.beta.messages.create( betas=["compact-2026-01-12"], model="claude-opus-5-5", max_tokens=4096, messages=messages, context_management={ "edits": [{"type": "compact_20260112", "pause_after_compaction": True}] }, ) # 檢查 compaction（壓縮）是否觸發了暫停 if response.stop_reason == "compaction": # 回應僅包含 compaction 區塊 messages.append({"role": "assistant", "content": response.content}) # 繼續該請求 response = client.beta.messages.create( betas=["compact-2026-01-12"], model="claude-opus-5-5", max_tokens=4096, messages=messages, context_management={"edits": [{"type": "compact_20260112"}]}, ) ``` ```typescript TypeScript const client = new Anthropic(); const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [ { role: "user", content: "Hello, Claude" } ]; let response = await client.beta.messages.create({ betas: ["compact-2026-01-12"], model: "claude-opus-5-5", max_tokens: 4096, messages, context_management: { edits: [ { type: "compact_20260112", pause_after_compaction: true } ] } }); // 檢查 compaction（壓縮）是否觸發了暫停 if (response.stop_reason === "compaction") { // 回應僅包含 compaction 區塊 messages.push({ role: "assistant", content: response.content }); // 繼續該請求 response = await client.beta.messages.create({ betas: ["compact-2026-01-12"], model: "claude-opus-5-5", max_tokens: 4096, messages, context_management: { edits: [{ type: "compact_20260112" }] } }); } ``` ```csharp C# var client = new AnthropicClient(); var messages = new List { new() { Role = Role.User, Content = "Hello, Claude" } }; var parameters = new MessageCreateParams { Model = Model.ClaudeOpus5_5, MaxTokens = 4096, Betas = ["compact-2026-01-12"], Messages = messages, ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit { PauseAfterCompaction = true }] } }; var response = await client.Beta.Messages.Create(parameters); if (response.StopReason == BetaStopReason.Compaction) { messages.Add(new BetaMessageParam { Role = Role.Assistant, Content = response.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList() }); parameters = new() { Model = Model.ClaudeOpus5_5, MaxTokens = 4096, Betas = ["compact-2026-01-12"], Messages = messages, ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit()] } }; response = await client.Beta.Messages.Create(parameters); } Console.WriteLine(response); ``` ```go Go client := anthropic.NewClient() messages := []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude"))} compactEdit := anthropic.BetaContextManagementConfigParam{ Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{ PauseAfterCompaction: anthropic.Bool(true), }}, }, } response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 4096, Messages: messages, ContextManagement: compactEdit, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) if err != nil { log.Fatal(err) } if response.StopReason == "compaction" { messages = append(messages, response.ToParam()) response, err = client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 4096, Messages: messages, ContextManagement: anthropic.BetaContextManagementConfigParam{ Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}}, }, }, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) if err != nil { log.Fatal(err) } } fmt.Println(response) ``` ```java Java import com.anthropic.models.beta.messages.BetaContextManagementConfig; import com.anthropic.models.beta.messages.BetaCompact20260112Edit; import com.anthropic.models.beta.messages.BetaStopReason; // ... AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(4096L) .addBeta("compact-2026-01-12") .addUserMessage("Help me build a website") .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder() .pauseAfterCompaction(true) .build()) .build()) .build(); BetaMessage response = client.beta().messages().create(params); // 檢查 compaction（壓縮）是否觸發了暫停 if (response.stopReason().isPresent() && response.stopReason().get().equals(BetaStopReason.COMPACTION)) { // 附加 compaction 區塊並繼續請求 // 方法是以壓縮後的上下文建立新的請求 MessageCreateParams continueParams = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(4096L) .addBeta("compact-2026-01-12") .addUserMessage("Help me build a website") .addMessage(response) .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder().build()) .build()) .build(); response = client.beta().messages().create(continueParams); } System.out.println(response); ``` ```php PHP $client = new Client(); $messages = [['role' => 'user', 'content' => 'Hello, Claude']]; $response = $client->beta->messages->create( maxTokens: 4096, messages: $messages, model: 'claude-opus-5-5', betas: ['compact-2026-01-12'], contextManagement: [ 'edits' => [ [ 'type' => 'compact_20260112', 'pause_after_compaction' => true ] ] ] ); if ($response->stopReason === 'compaction') { $messages[] = [ 'role' => 'assistant', 'content' => $response->content ]; $response = $client->beta->messages->create( maxTokens: 4096, messages: $messages, model: 'claude-opus-5-5', betas: ['compact-2026-01-12'], contextManagement: [ 'edits' => [ ['type' => 'compact_20260112'] ] ] ); } echo $response; ``` ```ruby Ruby client = Anthropic::Client.new messages = [{ role: "user", content: "Hello, Claude" }] response = client.beta.messages.create( betas: ["compact-2026-01-12"], model: "claude-opus-5-5", max_tokens: 4096, messages: messages, context_management: { edits: [ { type: "compact_20260112", pause_after_compaction: true } ] } ) if response.stop_reason == :compaction messages << { role: "assistant", content: response.content } response = client.beta.messages.create( betas: ["compact-2026-01-12"], model: "claude-opus-5-5", max_tokens: 4096, messages: messages, context_management: { edits: [{ type: "compact_20260112" }] } ) end puts response ``` #### 強制執行總 token 預算當模型處理包含多次工具使用迭代的長時間任務時，總 token 消耗量可能會大幅增加。您可以將 `pause_after_compaction` 與壓縮計數器結合，以估算累計用量，並在達到預算時妥善地收尾任務。此範例僅以 SDK 語言呈現：其價值在於請求周圍的預算追蹤邏輯。原始請求結合了[觸發設定](https://platform.claude.com/docs/zh-TW/build-with-claude/compaction-threshold#trigger-configuration)中的 `trigger` 與[壓縮後暫停](https://platform.claude.com/docs/zh-TW/build-with-claude/compaction-threshold#pausing-after-compaction)中的 `pause_after_compaction`。 ```python Python client = anthropic.Anthropic() messages = [{"role": "user", "content": "Hello, Claude"}] TRIGGER_THRESHOLD = 100_000 TOTAL_TOKEN_BUDGET = 3_000_000 n_compactions = 0 response = client.beta.messages.create( betas=["compact-2026-01-12"], model="claude-opus-5-5", max_tokens=4096, messages=messages, context_management={ "edits": [ { "type": "compact_20260112", "trigger": {"type": "input_tokens", "value": TRIGGER_THRESHOLD}, "pause_after_compaction": True, } ] }, ) if response.stop_reason == "compaction": n_compactions += 1 messages.append({"role": "assistant", "content": response.content}) # 估算已消耗的 token 總數；若超出預算則提示收尾 if n_compactions * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET: messages.append( { "role": "user", "content": "Please wrap up your current work and summarize the final state.", } ) ``` ```typescript TypeScript const client = new Anthropic(); const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [ { role: "user", content: "Hello, Claude" } ]; const TRIGGER_THRESHOLD = 100_000; const TOTAL_TOKEN_BUDGET = 3_000_000; let compactionCount = 0; const response = await client.beta.messages.create({ betas: ["compact-2026-01-12"], model: "claude-opus-5-5", max_tokens: 4096, messages, context_management: { edits: [ { type: "compact_20260112", trigger: { type: "input_tokens", value: TRIGGER_THRESHOLD }, pause_after_compaction: true } ] } }); if (response.stop_reason === "compaction") { compactionCount += 1; messages.push({ role: "assistant", content: response.content }); // 估算已消耗的 token 總數；若超出預算則提示收尾 if (compactionCount * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET) { messages.push({ role: "user", content: "Please wrap up your current work and summarize the final state." }); } } ``` ```csharp C# AnthropicClient client = new(); List messages = [new() { Role = Role.User, Content = "Hello, Claude" }]; const int TriggerThreshold = 100_000; const int TotalTokenBudget = 3_000_000; int compactionCount = 0; var response = await client.Beta.Messages.Create(new() { Betas = ["compact-2026-01-12"], Model = Model.ClaudeOpus5_5, MaxTokens = 4096, Messages = messages, ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit { Trigger = new BetaInputTokensTrigger(TriggerThreshold), PauseAfterCompaction = true }] } }); if (response.StopReason == BetaStopReason.Compaction) { compactionCount += 1; messages.Add(new() { Role = Role.Assistant, Content = response.Content.Select(b => new BetaContentBlockParam(b.Json)).ToList() }); // 估算已消耗的 token 總數；若超出預算則提示收尾 if (compactionCount * TriggerThreshold >= TotalTokenBudget) { messages.Add(new() { Role = Role.User, Content = "Please wrap up your current work and summarize the final state." }); } } Console.WriteLine(response); ``` ```go Go client := anthropic.NewClient() messages := []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude"))} const triggerThreshold = 100_000 const totalTokenBudget = 3_000_000 compactionCount := 0 response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 4096, Messages: messages, ContextManagement: anthropic.BetaContextManagementConfigParam{ Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{ Trigger: anthropic.BetaInputTokensTriggerParam{Value: triggerThreshold}, PauseAfterCompaction: anthropic.Bool(true), }}, }, }, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) if err != nil { log.Fatal(err) } if response.StopReason == "compaction" { compactionCount++ messages = append(messages, response.ToParam()) // 估算已消耗的 token 總數；若超出預算則提示收尾 if compactionCount*triggerThreshold >= totalTokenBudget { messages = append(messages, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Please wrap up your current work and summarize the final state."))) } } fmt.Println(response) ``` ```java Java import com.anthropic.models.beta.messages.BetaContextManagementConfig; import com.anthropic.models.beta.messages.BetaCompact20260112Edit; import com.anthropic.models.beta.messages.BetaInputTokensTrigger; import com.anthropic.models.beta.messages.BetaStopReason; // ... AnthropicClient client = AnthropicOkHttpClient.fromEnv(); long triggerThreshold = 100_000; long totalTokenBudget = 3_000_000; int compactionCount = 0; List messages = new ArrayList<>(); messages.add(BetaMessageParam.builder() .role(BetaMessageParam.Role.USER) .content("Hello, Claude") .build()); MessageCreateParams params = MessageCreateParams.builder() .addBeta("compact-2026-01-12") .model(Model.CLAUDE_OPUS_5_5) .maxTokens(4096L) .messages(messages) .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder() .trigger(BetaInputTokensTrigger.builder() .value(triggerThreshold) .build()) .pauseAfterCompaction(true) .build()) .build()) .build(); BetaMessage response = client.beta().messages().create(params); if (response.stopReason().isPresent() && response.stopReason().get().equals(BetaStopReason.COMPACTION)) { compactionCount += 1; messages.add(response.toParam()); // 估算已消耗的 token 總數；若超出預算則提示收尾 if (compactionCount * triggerThreshold >= totalTokenBudget) { messages.add(BetaMessageParam.builder() .role(BetaMessageParam.Role.USER) .content("Please wrap up your current work and summarize the final state.") .build()); } } System.out.println(response); ``` ```php PHP $client = new Client(); $triggerThreshold = 100_000; $totalTokenBudget = 3_000_000; $compactionCount = 0; $messages = [['role' => 'user', 'content' => 'Hello, Claude']]; $response = $client->beta->messages->create( maxTokens: 4096, messages: $messages, model: 'claude-opus-5-5', betas: ['compact-2026-01-12'], contextManagement: [ 'edits' => [ [ 'type' => 'compact_20260112', 'trigger' => ['type' => 'input_tokens', 'value' => $triggerThreshold], 'pause_after_compaction' => true ] ] ] ); if ($response->stopReason === 'compaction') { $compactionCount += 1; $messages[] = ['role' => 'assistant', 'content' => $response->content]; // 估算已消耗的 token 總數；若超出預算則提示收尾 if ($compactionCount * $triggerThreshold >= $totalTokenBudget) { $messages[] = [ 'role' => 'user', 'content' => 'Please wrap up your current work and summarize the final state.' ]; } } ``` ```ruby Ruby client = Anthropic::Client.new messages = [{ role: "user", content: "Hello, Claude" }] TRIGGER_THRESHOLD = 100_000 TOTAL_TOKEN_BUDGET = 3_000_000 compaction_count = 0 response = client.beta.messages.create( betas: ["compact-2026-01-12"], model: "claude-opus-5-5", max_tokens: 4096, messages: messages, context_management: { edits: [ { type: "compact_20260112", trigger: { type: "input_tokens", value: TRIGGER_THRESHOLD }, pause_after_compaction: true } ] } ) if response.stop_reason == :compaction compaction_count += 1 messages << { role: "assistant", content: response.content } # 估算已消耗的 token 總數；若超出預算則提示收尾 if compaction_count * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET messages << { role: "user", content: "Please wrap up your current work and summarize the final state." } end end ``` ## 使用壓縮區塊觸發壓縮時，API 會在助理回應的開頭回傳一個 `compaction` 區塊。長時間執行的對話可能會產生多次壓縮。最後一個壓縮區塊反映提示的最終狀態，並以產生的摘要取代其之前的內容。 ```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..." } ] } ``` ### 回傳壓縮區塊您必須在後續請求中將 `compaction` 區塊回傳給 API，才能以縮短後的提示繼續對話。最簡單的做法是將整個回應內容附加到您的訊息中： ```bash cURL # 回應內容（包括 compaction 區塊）必須送回 # API，作為下一個請求的 assistant 回合。管理該訊息清單 # 不適合用一次性的 shell 指令完成；請參閱 CLI 與 SDK # 分頁以了解完整流程。第一個請求： curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: compact-2026-01-12" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 4096, "messages": [ { "role": "user", "content": "Hello, Claude" } ], "context_management": { "edits": [ { "type": "compact_20260112" } ] } }' ``` ```bash CLI ant beta:messages create \ --beta compact-2026-01-12 \ --transform content \ --format jsonl <<'YAML' > content.json model: claude-opus-5-5 max_tokens: 4096 messages: - role: user content: Hello, Claude context_management: edits: - type: compact_20260112 YAML # 收到含有 compaction 區塊的回應後，將其附加為 # assistant 回合，並繼續對話 ant beta:messages create --beta compact-2026-01-12 < { new() { Role = Role.User, Content = "Help me build a web scraper" } }; var response = await client.Beta.Messages.Create(new() { Betas = ["compact-2026-01-12"], Model = Model.ClaudeOpus5_5, MaxTokens = 4096, Messages = messages, ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit()] } }); messages.Add(new BetaMessageParam { Role = Role.Assistant, Content = response.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList() }); messages.Add(new BetaMessageParam { Role = Role.User, Content = "Now add error handling" }); var nextResponse = await client.Beta.Messages.Create(new() { Betas = ["compact-2026-01-12"], Model = Model.ClaudeOpus5_5, MaxTokens = 4096, Messages = messages, ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit()] } }); Console.WriteLine(nextResponse); ``` ```go Go client := anthropic.NewClient() messages := []anthropic.BetaMessageParam{ anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Help me build a web scraper")), } compactEdit := anthropic.BetaContextManagementConfigParam{ Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}}, }, } response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 4096, Messages: messages, ContextManagement: compactEdit, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) if err != nil { log.Fatal(err) } messages = append(messages, response.ToParam()) messages = append(messages, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Now add error handling"))) nextResponse, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 4096, Messages: messages, ContextManagement: compactEdit, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) if err != nil { log.Fatal(err) } fmt.Println(nextResponse) ``` ```java Java import com.anthropic.models.beta.messages.BetaContextManagementConfig; import com.anthropic.models.beta.messages.BetaCompact20260112Edit; // ... AnthropicClient client = AnthropicOkHttpClient.fromEnv(); // 第一個請求 BetaMessage response = client.beta().messages().create( MessageCreateParams.builder() .addBeta("compact-2026-01-12") .model(Model.CLAUDE_OPUS_5_5) .maxTokens(4096L) .addUserMessage("Help me build a web scraper") .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder().build()) .build()) .build()); // 收到含有 compaction 區塊的回應後，請附加完整的 // 內容（包括 compaction 區塊）並繼續對話 BetaMessage nextResponse = client.beta().messages().create( MessageCreateParams.builder() .addBeta("compact-2026-01-12") .model(Model.CLAUDE_OPUS_5_5) .maxTokens(4096L) .addUserMessage("Help me build a web scraper") .addMessage(response) .addUserMessage("Now add error handling") .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder().build()) .build()) .build()); System.out.println(nextResponse); ``` ```php PHP $client = new Client(); $messages = [ ['role' => 'user', 'content' => 'Help me build a web scraper'] ]; $response = $client->beta->messages->create( maxTokens: 4096, messages: $messages, model: 'claude-opus-5-5', betas: ['compact-2026-01-12'], contextManagement: [ 'edits' => [['type' => 'compact_20260112']] ] ); $messages[] = ['role' => 'assistant', 'content' => $response->content]; $messages[] = ['role' => 'user', 'content' => 'Now add error handling']; $nextResponse = $client->beta->messages->create( maxTokens: 4096, messages: $messages, model: 'claude-opus-5-5', betas: ['compact-2026-01-12'], contextManagement: [ 'edits' => [['type' => 'compact_20260112']] ] ); echo json_encode($nextResponse, JSON_PRETTY_PRINT), PHP_EOL; ``` ```ruby Ruby client = Anthropic::Client.new messages = [ { role: "user", content: "Help me build a web scraper" } ] response = client.beta.messages.create( betas: ["compact-2026-01-12"], model: "claude-opus-5-5", max_tokens: 4096, messages: messages, context_management: { edits: [{ type: "compact_20260112" }] } ) messages << { role: "assistant", content: response.content } messages << { role: "user", content: "Now add error handling" } next_response = client.beta.messages.create( betas: ["compact-2026-01-12"], model: "claude-opus-5-5", max_tokens: 4096, messages: messages, context_management: { edits: [{ type: "compact_20260112" }] } ) puts next_response.content ``` 在 Python 中，請如本頁範例所示使用 `client.beta.messages`。如果您呼叫 `client.messages` 並自行序列化區塊，單純的 `model_dump()` 會在 `compaction` 區塊中加入 `text: null` 和 `citations: null`。API 接著會以 400 錯誤（`Extra inputs are not permitted`）拒絕該請求。請改用 `to_dict()` 或 `model_dump(exclude_none=True)`。[從摘要繼續](https://platform.claude.com/docs/zh-TW/build-with-claude/compaction-on-demand#continue-from-the-summary)針對隨需壓縮也提供了相同的建議。當 API 收到 `compaction` 區塊時，其之前的所有內容區塊都會被忽略。您可以選擇： * 將原始訊息保留在清單中，讓 API 處理移除已壓縮內容的工作 * 手動捨棄已壓縮的訊息，只包含從壓縮區塊開始的內容在 Claude Fable 5.1、Claude Mythos 5.1、Claude Opus 5.5、Claude Sonnet 5.5 和 Claude Haiku 5.5 上，`compaction` 區塊之前的思考區塊不會被延續，因此摘要就是模型對先前工作所擁有的全部資訊。如果您撰寫自己的 `instructions`，請告訴模型摘要必須保留哪些內容；請參閱[告訴模型在壓縮摘要中要保留什麼](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#tell-the-model-what-to-preserve-in-compaction-summaries)。 ### 串流壓縮區塊的「streaming」（串流）方式與文字區塊不同。您會收到一個 `content_block_start` 事件，接著是一個包含完整摘要內容的 `content_block_delta`（沒有中間的串流過程），然後是一個 `content_block_stop` 事件。 ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: compact-2026-01-12" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 4096, "stream": true, "messages": [ { "role": "user", "content": "Hello, Claude" } ], "context_management": { "edits": [ { "type": "compact_20260112" } ] } }' ``` ```bash CLI ant beta:messages create \ --stream \ --beta compact-2026-01-12 \ --format jsonl <<'YAML' model: claude-opus-5-5 max_tokens: 4096 messages: - role: user content: Hello, Claude context_management: edits: - type: compact_20260112 YAML ``` ```python Python client = anthropic.Anthropic() messages = [{"role": "user", "content": "Hello, Claude"}] with client.beta.messages.stream( betas=["compact-2026-01-12"], model="claude-opus-5-5", max_tokens=4096, messages=messages, context_management={"edits": [{"type": "compact_20260112"}]}, ) as stream: for event in stream: match event.type: case "content_block_start": block = event.content_block match block.type: case "compaction": print("Compaction started...") case "text": print("Text response started...") case "content_block_delta": delta = event.delta match delta.type: case "compaction_delta": print(f"Compaction complete: {len(delta.content or '')} chars") case "text_delta": print(delta.text, end="", flush=True) # 取得最終累積的訊息 message = stream.get_final_message() messages.append({"role": "assistant", "content": message.content}) ``` ```typescript TypeScript const client = new Anthropic(); const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [ { role: "user", content: "Hello, Claude" } ]; const stream = await client.beta.messages.stream({ betas: ["compact-2026-01-12"], model: "claude-opus-5-5", max_tokens: 4096, messages, context_management: { edits: [{ type: "compact_20260112" }] } }); for await (const event of stream) { switch (event.type) { case "content_block_start": switch (event.content_block.type) { case "compaction": console.log("Compaction started..."); break; case "text": console.log("Text response started..."); break; } break; case "content_block_delta": switch (event.delta.type) { case "compaction_delta": console.log(`Compaction complete: ${event.delta.content?.length ?? 0} chars`); break; case "text_delta": process.stdout.write(event.delta.text); break; } break; } } // 取得最終累積的訊息 const message = await stream.finalMessage(); messages.push({ role: "assistant", content: message.content }); ``` ```csharp C# var client = new AnthropicClient(); List messages = [new() { Role = Role.User, Content = "Hello" }]; var parameters = new MessageCreateParams { Betas = ["compact-2026-01-12"], Model = Model.ClaudeOpus5_5, MaxTokens = 4096, Messages = messages, ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit()] } }; await foreach (var streamEvent in client.Beta.Messages.CreateStreaming(parameters)) { if (streamEvent.TryPickContentBlockStart(out var startEvent)) { if (startEvent.ContentBlock.TryPickBetaCompaction(out _)) { Console.WriteLine("Compaction started..."); } else if (startEvent.ContentBlock.TryPickBetaText(out _)) { Console.WriteLine("Text response started..."); } } else if (streamEvent.TryPickContentBlockDelta(out var deltaEvent)) { if (deltaEvent.Delta.TryPickCompaction(out var compactionDelta)) { Console.WriteLine($"Compaction complete: {compactionDelta.Content?.Length ?? 0} chars"); } else if (deltaEvent.Delta.TryPickText(out var textDelta)) { Console.Write(textDelta.Text); } } } ``` ```go Go client := anthropic.NewClient() messages := []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude"))} stream := client.Beta.Messages.NewStreaming(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 4096, Messages: messages, ContextManagement: anthropic.BetaContextManagementConfigParam{ Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}}, }, }, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) for stream.Next() { event := stream.Current() switch eventVariant := event.AsAny().(type) { case anthropic.BetaRawContentBlockStartEvent: switch eventVariant.ContentBlock.AsAny().(type) { case anthropic.BetaCompactionBlock: fmt.Println("Compaction started...") case anthropic.BetaTextBlock: fmt.Println("Text response started...") } case anthropic.BetaRawContentBlockDeltaEvent: switch deltaVariant := eventVariant.Delta.AsAny().(type) { case anthropic.BetaCompactionContentBlockDelta: fmt.Printf("Compaction complete: %d chars\n", len(deltaVariant.Content)) case anthropic.BetaTextDelta: fmt.Print(deltaVariant.Text) } } } if err := stream.Err(); err != nil { log.Fatal(err) } ``` ```java Java import com.anthropic.models.beta.messages.BetaContextManagementConfig; import com.anthropic.models.beta.messages.BetaCompact20260112Edit; // ... AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(4096L) .addBeta("compact-2026-01-12") .addUserMessage("Hello, Claude") .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder().build()) .build()) .build(); try (var streamResponse = client.beta().messages().createStreaming(params)) { streamResponse.stream().forEach(event -> { event.contentBlockStart().ifPresent(startEvent -> { startEvent.contentBlock().compaction().ifPresent(c -> System.out.println("Compaction started...") ); startEvent.contentBlock().text().ifPresent(t -> System.out.println("Text response started...") ); }); event.contentBlockDelta().ifPresent(deltaEvent -> { deltaEvent.delta().compaction().ifPresent(cd -> System.out.println("Compaction complete: " + cd.content().map(String::length).orElse(0) + " chars") ); deltaEvent.delta().text().ifPresent(td -> System.out.print(td.text()) ); }); }); } ``` ```php PHP use Anthropic\Beta\Messages\BetaCompactionBlock; use Anthropic\Beta\Messages\BetaCompactionContentBlockDelta; use Anthropic\Beta\Messages\BetaRawContentBlockDeltaEvent; use Anthropic\Beta\Messages\BetaRawContentBlockStartEvent; use Anthropic\Beta\Messages\BetaTextBlock; use Anthropic\Beta\Messages\BetaTextDelta; $client = new Client(); $messages = [['role' => 'user', 'content' => 'Hello, Claude']]; $stream = $client->beta->messages->createStream( maxTokens: 4096, messages: $messages, model: 'claude-opus-5-5', betas: ['compact-2026-01-12'], contextManagement: [ 'edits' => [ ['type' => 'compact_20260112'] ] ] ); foreach ($stream as $event) { switch (true) { case $event instanceof BetaRawContentBlockStartEvent: switch (true) { case $event->contentBlock instanceof BetaCompactionBlock: echo "Compaction started...\n"; break; case $event->contentBlock instanceof BetaTextBlock: echo "Text response started...\n"; break; } break; case $event instanceof BetaRawContentBlockDeltaEvent: switch (true) { case $event->delta instanceof BetaCompactionContentBlockDelta: echo "Compaction complete: " . strlen($event->delta->content ?? '') . " chars\n"; break; case $event->delta instanceof BetaTextDelta: echo $event->delta->text; break; } break; } } ``` ```ruby Ruby client = Anthropic::Client.new messages = [{ role: "user", content: "Hello, Claude" }] stream = client.beta.messages.stream( betas: ["compact-2026-01-12"], model: "claude-opus-5-5", max_tokens: 4096, messages: messages, context_management: { edits: [{ type: "compact_20260112" }] } ) stream.each do |event| case event when Anthropic::Models::BetaRawContentBlockStartEvent case event.content_block when Anthropic::Models::BetaCompactionBlock puts "Compaction started..." when Anthropic::Models::BetaTextBlock puts "Text response started..." end when Anthropic::Models::BetaRawContentBlockDeltaEvent delta = event.delta case delta when Anthropic::Models::BetaCompactionContentBlockDelta puts "Compaction complete: #{(delta.content || "").length} chars" when Anthropic::Models::BetaTextDelta print delta.text end end end ``` ### 提示快取壓縮能與「[prompt caching](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching)」（提示快取）良好搭配。您可以在壓縮區塊上加入 `cache_control` 中斷點，以快取摘要後的內容。 ```json { "role": "assistant", "content": [ { "type": "compaction", "content": "[summary text]", "cache_control": { "type": "ephemeral" } }, { "type": "text", "text": "Based on our conversation..." } ] } ``` #### 透過系統提示最大化快取命中發生壓縮時，摘要會成為需要寫入快取的新內容。若沒有額外的快取中斷點，這也會使任何已快取的「system prompt」（系統提示）失效，導致系統提示需要與壓縮摘要一起重新快取。若要最大化快取命中率，請在系統提示的結尾加入 `cache_control` 中斷點。這會讓系統提示與對話分開快取，因此當發生壓縮時： * 系統提示的快取仍然有效，並會從快取中讀取 * 只有壓縮摘要需要寫入為新的快取項目 ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: compact-2026-01-12" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 4096, "system": [ { "type": "text", "text": "You are a helpful coding assistant...", "cache_control": { "type": "ephemeral" } } ], "messages": [ { "role": "user", "content": "Hello, Claude" } ], "context_management": { "edits": [ { "type": "compact_20260112" } ] } }' ``` ```bash CLI ant beta:messages create --beta compact-2026-01-12 <<'YAML' model: claude-opus-5-5 max_tokens: 4096 system: - type: text text: You are a helpful coding assistant... cache_control: type: ephemeral messages: - role: user content: Hello, Claude context_management: edits: - type: compact_20260112 YAML ``` ```python Python client = anthropic.Anthropic() messages = [{"role": "user", "content": "Hello, Claude"}] response = client.beta.messages.create( betas=["compact-2026-01-12"], model="claude-opus-5-5", max_tokens=4096, system=[ { "type": "text", "text": "You are a helpful coding assistant...", "cache_control": { "type": "ephemeral" }, # Cache the system prompt separately } ], messages=messages, context_management={"edits": [{"type": "compact_20260112"}]}, ) ``` ```typescript TypeScript const client = new Anthropic(); const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [ { role: "user", content: "Hello, Claude" } ]; const response = await client.beta.messages.create({ betas: ["compact-2026-01-12"], model: "claude-opus-5-5", max_tokens: 4096, system: [ { type: "text", text: "You are a helpful coding assistant...", cache_control: { type: "ephemeral" } // Cache the system prompt separately } ], messages, context_management: { edits: [{ type: "compact_20260112" }] } }); ``` ```csharp C# var client = new AnthropicClient(); var parameters = new MessageCreateParams { Betas = ["compact-2026-01-12"], Model = Model.ClaudeOpus5_5, MaxTokens = 4096, System = new List { new() { Text = "You are a helpful coding assistant...", CacheControl = new BetaCacheControlEphemeral() } }, Messages = [new() { Role = Role.User, Content = "Hello, Claude" }], ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit()] } }; var response = await client.Beta.Messages.Create(parameters); Console.WriteLine(response); ``` ```go Go client := anthropic.NewClient() response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 4096, System: []anthropic.BetaTextBlockParam{ { Text: "You are a helpful coding assistant...", CacheControl: anthropic.NewBetaCacheControlEphemeralParam(), }, }, Messages: []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude"))}, ContextManagement: anthropic.BetaContextManagementConfigParam{ Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}}, }, }, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) if err != nil { log.Fatal(err) } fmt.Println(response) ``` ```java Java import com.anthropic.models.beta.messages.BetaContextManagementConfig; import com.anthropic.models.beta.messages.BetaCompact20260112Edit; import com.anthropic.models.beta.messages.BetaCacheControlEphemeral; // ... AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(4096L) .addBeta("compact-2026-01-12") .systemOfBetaTextBlockParams(List.of( BetaTextBlockParam.builder() .text("You are a helpful coding assistant...") .cacheControl(BetaCacheControlEphemeral.builder().build()) .build() )) .addUserMessage("Hello, Claude") .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder().build()) .build()) .build(); BetaMessage response = client.beta().messages().create(params); System.out.println(response); ``` ```php PHP $client = new Client(); $response = $client->beta->messages->create( maxTokens: 4096, messages: [['role' => 'user', 'content' => 'Hello, Claude']], model: 'claude-opus-5-5', betas: ['compact-2026-01-12'], system: [ [ 'type' => 'text', 'text' => 'You are a helpful coding assistant...', 'cache_control' => [ 'type' => 'ephemeral' ] ] ], contextManagement: [ 'edits' => [ ['type' => 'compact_20260112'] ] ] ); echo json_encode($response, JSON_PRETTY_PRINT), PHP_EOL; ``` ```ruby Ruby client = Anthropic::Client.new response = client.beta.messages.create( betas: ["compact-2026-01-12"], model: "claude-opus-5-5", max_tokens: 4096, system: [ { type: "text", text: "You are a helpful coding assistant...", cache_control: { type: "ephemeral" } } ], messages: [{ role: "user", content: "Hello, Claude" }], context_management: { edits: [{ type: "compact_20260112" }] } ) puts response ``` 這能讓冗長的系統提示在整個對話的多次壓縮事件中持續保持快取狀態。 ## 了解用量壓縮需要額外的取樣步驟，這會計入「rate limit」（速率限制）與計費。API 會在回應中回傳詳細的用量資訊： ```json Output { "usage": { "input_tokens": 23000, "output_tokens": 1000, "iterations": [ { "type": "compaction", "input_tokens": 180000, "output_tokens": 3500 }, { "type": "message", "input_tokens": 23000, "output_tokens": 1000 } ] } } ``` `iterations` 陣列顯示每次取樣迭代的用量。發生壓縮時，您會看到一個 `compaction` 迭代，接著是主要的 `message` 迭代。在此範例中，頂層的 `input_tokens` 和 `output_tokens` 與 `message` 迭代完全相符，因為只有一個非壓縮迭代。最後一次迭代的 token 數量反映壓縮後的有效上下文大小。頂層的 `input_tokens` 和 `output_tokens` 不包含壓縮迭代的用量。它們反映的是所有非壓縮迭代的總和。若要計算一個請求所消耗及計費的總 token 數，請加總 `usage.iterations` 陣列中的所有項目。如果您先前依賴 `usage.input_tokens` 和 `usage.output_tokens` 進行成本追蹤或稽核，則在啟用壓縮時，您需要更新追蹤邏輯，改為彙總 `usage.iterations` 中的數值。啟用壓縮 beta 後，每個回應都會包含 `usage.iterations`，即使沒有發生壓縮也是如此。只有在請求期間觸發新的壓縮時，才會出現 `compaction` 項目。重新套用先前的 `compaction` 區塊不會產生額外的壓縮成本，在這種情況下，頂層的用量欄位仍然準確。 ## 與其他功能結合 ### 伺服器工具使用伺服器工具（例如網頁搜尋）時，會在每次取樣迭代開始時檢查壓縮觸發條件。視您的觸發閾值與產生的輸出量而定，單一請求中可能會發生多次壓縮。 ### Token 計數 Token 計數端點（`/v1/messages/count_tokens`）會套用提示中既有的 `compaction` 區塊，但不會觸發新的壓縮。您可以使用它來檢查先前壓縮後的有效 token 數量： ```bash cURL curl https://api.anthropic.com/v1/messages/count_tokens \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: compact-2026-01-12" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "messages": [ { "role": "user", "content": "Hello, Claude" } ], "context_management": { "edits": [ { "type": "compact_20260112" } ] } }' ``` ```bash CLI CURRENT=$(ant beta:messages count-tokens \ --beta compact-2026-01-12 \ --transform input_tokens \ --raw-output <<'YAML' model: claude-opus-5-5 messages: - role: user content: Hello, Claude context_management: edits: - type: compact_20260112 YAML ) ORIGINAL=$(ant beta:messages count-tokens \ --beta compact-2026-01-12 \ --transform context_management.original_input_tokens \ --raw-output <<'YAML' model: claude-opus-5-5 messages: - role: user content: Hello, Claude context_management: edits: - type: compact_20260112 YAML ) printf 'Current tokens: %s\n' "$CURRENT" printf 'Original tokens: %s\n' "$ORIGINAL" ``` ```python Python client = anthropic.Anthropic() messages = [{"role": "user", "content": "Hello, Claude"}] count_response = client.beta.messages.count_tokens( betas=["compact-2026-01-12"], model="claude-opus-5-5", messages=messages, context_management={"edits": [{"type": "compact_20260112"}]}, ) print(f"Current tokens: {count_response.input_tokens}") print(f"Original tokens: {count_response.context_management.original_input_tokens}") ``` ```typescript TypeScript const client = new Anthropic(); const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [ { role: "user", content: "Summarize the key points of our conversation so far." } ]; const countResponse = await client.beta.messages.countTokens({ betas: ["compact-2026-01-12"], model: "claude-opus-5-5", messages, context_management: { edits: [{ type: "compact_20260112" }] } }); console.log(`Current tokens: ${countResponse.input_tokens}`); console.log(`Original tokens: ${countResponse.context_management!.original_input_tokens}`); ``` ```csharp C# AnthropicClient client = new(); List messages = [new() { Role = Role.User, Content = "Hello" }]; var countParams = new MessageCountTokensParams { Model = Model.ClaudeOpus5_5, Messages = messages, ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit()] }, Betas = ["compact-2026-01-12"] }; var countResponse = await client.Beta.Messages.CountTokens(countParams); Console.WriteLine($"Current tokens: {countResponse.InputTokens}"); Console.WriteLine($"Original tokens: {countResponse.ContextManagement?.OriginalInputTokens}"); ``` ```go Go client := anthropic.NewClient() messages := []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude"))} countResponse, err := client.Beta.Messages.CountTokens(context.TODO(), anthropic.BetaMessageCountTokensParams{ Model: anthropic.ModelClaudeOpus5_5, Messages: messages, ContextManagement: anthropic.BetaContextManagementConfigParam{ Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}}, }, }, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) if err != nil { log.Fatal(err) } fmt.Printf("Current tokens: %d\n", countResponse.InputTokens) fmt.Printf("Original tokens: %d\n", countResponse.ContextManagement.OriginalInputTokens) ``` ```java Java import com.anthropic.models.beta.messages.BetaMessageTokensCount; import com.anthropic.models.beta.messages.MessageCountTokensParams; import com.anthropic.models.beta.messages.BetaContextManagementConfig; import com.anthropic.models.beta.messages.BetaCompact20260112Edit; // ... AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCountTokensParams params = MessageCountTokensParams.builder() .model(Model.CLAUDE_OPUS_5_5) .addUserMessage("Hello, Claude") .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder().build()) .build()) .addBeta("compact-2026-01-12") .build(); BetaMessageTokensCount countResponse = client.beta().messages().countTokens(params); System.out.println("Current tokens: " + countResponse.inputTokens()); System.out.println("Original tokens: " + countResponse.contextManagement().get().originalInputTokens()); ``` ```php PHP $client = new Client(); $messages = [['role' => 'user', 'content' => 'Hello, Claude']]; $countResponse = $client->beta->messages->countTokens( messages: $messages, model: 'claude-opus-5-5', betas: ['compact-2026-01-12'], contextManagement: [ 'edits' => [ ['type' => 'compact_20260112'] ] ] ); echo "Current tokens: " . $countResponse->inputTokens . "\n"; echo "Original tokens: " . $countResponse->contextManagement->originalInputTokens . "\n"; ``` ```ruby Ruby client = Anthropic::Client.new messages = [{ role: "user", content: "Hello, Claude" }] count_response = client.beta.messages.count_tokens( betas: ["compact-2026-01-12"], model: "claude-opus-5-5", messages: messages, context_management: { edits: [{ type: "compact_20260112" }] } ) puts "Current tokens: #{count_response.input_tokens}" puts "Original tokens: #{count_response.context_management.original_input_tokens}" ``` ## 範例以下是一個使用壓縮的長時間執行對話的完整範例： ```bash cURL # curl 只會傳送個別請求；請在呼叫端指令碼中維護 messages 陣列。 # 完整的 chat() 迴圈請參閱 SDK 分頁。單輪 # 請求格式： curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: compact-2026-01-12" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 4096, "messages": [ { "role": "user", "content": "Help me build a Python web scraper" } ], "context_management": { "edits": [ { "type": "compact_20260112", "trigger": { "type": "input_tokens", "value": 100000 } } ] } }' ``` ```bash CLI # CLI 負責處理個別回合；請在呼叫端指令碼中維護 messages 陣列。 # 完整的 chat() 迴圈請參閱 SDK 分頁。單一回合 # 請求格式： ant beta:messages create \ --beta compact-2026-01-12 \ --transform 'content.#(type=="text").text' \ --raw-output <<'YAML' model: claude-opus-5-5 max_tokens: 4096 messages: - role: user content: Help me build a Python web scraper context_management: edits: - type: compact_20260112 trigger: type: input_tokens value: 100000 YAML ``` ```python Python client = anthropic.Anthropic() messages: list[dict] = [] 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-5-5", max_tokens=4096, messages=messages, context_management={ "edits": [ { "type": "compact_20260112", "trigger": {"type": "input_tokens", "value": 100000}, } ] }, ) # 附加回應（compaction 區塊會自動包含在內） messages.append({"role": "assistant", "content": response.content}) # 傳回文字內容 return next(block.text for block in response.content if block.type == "text") # 執行長時間對話 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")) # 依對話需要持續呼叫 chat() ``` ```typescript TypeScript const client = new Anthropic(); const messages: Anthropic.Beta.Messages.BetaMessageParam[] = []; async function chat(userMessage: string): Promise { messages.push({ role: "user", content: userMessage }); const response = await client.beta.messages.create({ betas: ["compact-2026-01-12"], model: "claude-opus-5-5", max_tokens: 4096, messages, context_management: { edits: [ { type: "compact_20260112", trigger: { type: "input_tokens", value: 100000 } } ] } }); // 附加回應（compaction 區塊會自動包含在內） messages.push({ role: "assistant", content: response.content }); // 傳回文字內容 const textBlock = response.content.find((block) => block.type === "text"); return textBlock?.text ?? ""; } // 執行長時間的對話 console.log(await chat("Help me build a Python web scraper")); console.log(await chat("Add support for JavaScript-rendered pages")); console.log(await chat("Now add rate limiting and error handling")); // 依對話需要持續呼叫 chat() ``` ```csharp C# AnthropicClient client = new(); List messages = new(); Console.WriteLine(await Chat(client, messages, "Help me build a Python web scraper")); Console.WriteLine(await Chat(client, messages, "Add support for JavaScript-rendered pages")); Console.WriteLine(await Chat(client, messages, "Now add rate limiting and error handling")); static async Task Chat(AnthropicClient client, List messages, string userMessage) { messages.Add(new() { Role = Role.User, Content = userMessage }); var parameters = new MessageCreateParams { Betas = ["compact-2026-01-12"], Model = Model.ClaudeOpus5_5, MaxTokens = 4096, Messages = messages, ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit { Trigger = new BetaInputTokensTrigger(100000) }] } }; var response = await client.Beta.Messages.Create(parameters); messages.Add(new() { Role = Role.Assistant, Content = response.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList() }); return response.Content .Select(block => block.Value) .OfType() .Select(tb => tb.Text) .FirstOrDefault() ?? ""; } ``` ```go Go package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) var ( client = anthropic.NewClient() messages []anthropic.BetaMessageParam ) func chat(userMessage string) string { messages = append(messages, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(userMessage))) response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 4096, Messages: messages, ContextManagement: anthropic.BetaContextManagementConfigParam{ Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{ Trigger: anthropic.BetaInputTokensTriggerParam{Value: 100000}, }}, }, }, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) if err != nil { log.Fatal(err) } messages = append(messages, response.ToParam()) for _, block := range response.Content { if variant, ok := block.AsAny().(anthropic.BetaTextBlock); ok { return variant.Text } } return "" } func main() { fmt.Println(chat("Help me build a Python web scraper")) fmt.Println(chat("Add support for JavaScript-rendered pages")) fmt.Println(chat("Now add rate limiting and error handling")) } ``` ```java Java import com.anthropic.models.beta.messages.BetaContextManagementConfig; import com.anthropic.models.beta.messages.BetaCompact20260112Edit; import com.anthropic.models.beta.messages.BetaInputTokensTrigger; // ... private static final AnthropicClient client = AnthropicOkHttpClient.fromEnv(); private static final List messages = new ArrayList<>(); public static void main(String[] args) { System.out.println(chat("Help me build a Python web scraper")); System.out.println(chat("Add support for JavaScript-rendered pages")); System.out.println(chat("Now add rate limiting and error handling")); } private static String chat(String userMessage) { messages.add(BetaMessageParam.builder() .role(BetaMessageParam.Role.USER) .content(userMessage) .build()); MessageCreateParams params = MessageCreateParams.builder() .addBeta("compact-2026-01-12") .model(Model.CLAUDE_OPUS_5_5) .maxTokens(4096L) .messages(messages) .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder() .trigger(BetaInputTokensTrigger.builder() .value(100000L) .build()) .build()) .build()) .build(); BetaMessage response = client.beta().messages().create(params); // 附加回應（compaction 區塊會自動包含在內） messages.add(response.toParam()); return response.content().stream() .filter(block -> block.text().isPresent()) .map(block -> block.text().get().text()) .findFirst() .orElse(""); } ``` ```php PHP $client = new Client(); $messages = []; function chat($client, &$messages, $userMessage) { $messages[] = ['role' => 'user', 'content' => $userMessage]; $response = $client->beta->messages->create( maxTokens: 4096, messages: $messages, model: 'claude-opus-5-5', betas: ['compact-2026-01-12'], contextManagement: [ 'edits' => [ [ 'type' => 'compact_20260112', 'trigger' => ['type' => 'input_tokens', 'value' => 100000] ] ] ] ); $messages[] = ['role' => 'assistant', 'content' => $response->content]; foreach ($response->content as $block) { if ($block->type === 'text') { return $block->text; } } return ''; } echo chat($client, $messages, "Help me build a Python web scraper") . "\n"; echo chat($client, $messages, "Add support for JavaScript-rendered pages") . "\n"; echo chat($client, $messages, "Now add rate limiting and error handling") . "\n"; ``` ```ruby Ruby client = Anthropic::Client.new messages = [] def chat(client, messages, user_message) messages << { role: "user", content: user_message } response = client.beta.messages.create( betas: ["compact-2026-01-12"], model: "claude-opus-5-5", max_tokens: 4096, messages: messages, context_management: { edits: [ { type: "compact_20260112", trigger: { type: "input_tokens", value: 100000 } } ] } ) messages << { role: "assistant", content: response.content } response.content.find { |block| block.type == :text }&.text || "" end puts chat(client, messages, "Help me build a Python web scraper") puts chat(client, messages, "Add support for JavaScript-rendered pages") puts chat(client, messages, "Now add rate limiting and error handling") ``` 在 Claude Fable 5.1、Claude Opus 5.5、Claude Sonnet 5.5 和 Claude Haiku 5.5 上，請從您在壓縮區塊之後重新插入的任何助理回合中移除 `thinking` 和 `redacted_thinking` 區塊，或搭配 `thinking-binding-controls-2026-08-01` [beta 標頭](https://platform.claude.com/docs/zh-TW/api/beta-headers)傳送 `thinking.block_binding.prefix_mismatch_behavior: "drop_block"`。這些區塊是在完整歷史記錄存在時產生的，因此它們不再能通過[對話檢查](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking#preserved-in-conversation)。在強制執行該檢查的情況下，延續請求會以 400 錯誤被拒絕。保留的文字和工具區塊可以維持原樣。讓 API 摘要所有內容，而不重新插入較早的回合，即可避免此問題。在 Claude Sonnet 5.5 上，`block_binding` 僅適用於 `thinking: {"type": "adaptive"}`。使用 `between_tools` 時，請改為移除這些區塊。在 Claude Haiku 5.5 上，`block_binding` 僅適用於 `thinking: {"type": "adaptive"}`，因此使用 `thinking: {"type": "disabled"}` 時，請改為移除這些區塊。以下範例使用 `pause_after_compaction` 來保留先前的交流和目前的使用者訊息（共三則訊息），而不是將其摘要。它會保持其文字和工具區塊不變，從保留的助理回合中移除 `thinking` 和 `redacted_thinking` 區塊，並在該回合沒有剩餘內容時將其捨棄： ```bash cURL # curl 只會傳送個別請求；請在呼叫端指令碼中維護 messages 陣列。 # 完整的 chat() 迴圈（含暫停並保留的處理方式）請參閱 SDK 分頁。 # 單輪請求的格式如下： curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: compact-2026-01-12" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 4096, "messages": [ { "role": "user", "content": "Help me build a Python web scraper" } ], "context_management": { "edits": [ { "type": "compact_20260112", "trigger": { "type": "input_tokens", "value": 100000 }, "pause_after_compaction": true } ] } }' ``` ```bash CLI # CLI 負責處理單一回合；請在呼叫端指令碼中維護 messages 陣列。 # 完整的 chat() 迴圈（含暫停並保留的處理）請參閱 SDK 分頁。 # 單一回合請求的格式： ant beta:messages create \ --beta compact-2026-01-12 \ --transform 'content.#(type=="text").text' \ --raw-output <<'YAML' model: claude-opus-5-5 max_tokens: 4096 messages: - role: user content: Help me build a Python web scraper context_management: edits: - type: compact_20260112 trigger: type: input_tokens value: 100000 pause_after_compaction: true YAML ``` ```python Python from typing import Any client = anthropic.Anthropic() messages: list[dict[str, Any]] = [] 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-5-5", max_tokens=4096, messages=messages, context_management={ "edits": [ { "type": "compact_20260112", "trigger": {"type": "input_tokens", "value": 100000}, "pause_after_compaction": True, } ] }, ) # 檢查是否發生壓縮並已暫停 if response.stop_reason == "compaction": # 從回應中取得壓縮區塊 compaction_block = response.content[0] # 保留先前的對話交換與目前的使用者訊息（3 則訊息） # 方法是將它們放在壓縮區塊之後，且不含 thinking # 區塊；沒有任何內容的助理回合會被捨棄 preserved_messages = [ { **message, "content": [ block for block in message["content"] if block.type not in ("thinking", "redacted_thinking") ], } if message["role"] == "assistant" else message for message in messages[-3:] ] preserved_messages = [m for m in preserved_messages if m["content"]] # 建立新的訊息清單：壓縮內容 + 保留的訊息 new_assistant_content = [compaction_block] messages_after_compaction = [ {"role": "assistant", "content": new_assistant_content} ] + preserved_messages # 以壓縮後的上下文 + 保留的訊息繼續請求 response = client.beta.messages.create( betas=["compact-2026-01-12"], model="claude-opus-5-5", max_tokens=4096, messages=messages_after_compaction, context_management={"edits": [{"type": "compact_20260112"}]}, ) # 更新訊息清單以反映壓縮結果 messages.clear() messages.extend(messages_after_compaction) # 附加最終回應 messages.append({"role": "assistant", "content": response.content}) # 傳回文字內容 return next(block.text for block in response.content if block.type == "text") # 執行長時間對話 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")) # 依對話需要持續呼叫 chat() ``` ```typescript TypeScript const client = new Anthropic(); let messages: Anthropic.Beta.Messages.BetaMessageParam[] = []; async function chat(userMessage: string): Promise { messages.push({ role: "user", content: userMessage }); let response = await client.beta.messages.create({ betas: ["compact-2026-01-12"], model: "claude-opus-5-5", max_tokens: 4096, messages, context_management: { edits: [ { type: "compact_20260112", trigger: { type: "input_tokens", value: 100000 }, pause_after_compaction: true } ] } }); // 檢查是否發生壓縮並已暫停 if (response.stop_reason === "compaction") { // 從回應中取得壓縮區塊 const compactionBlock = response.content[0]; // 保留先前的對話往返與目前的使用者訊息（3 則訊息） // 方法是將它們放在壓縮區塊之後，並移除 thinking // 區塊；沒有任何內容的助理回合會被捨棄 const preservedMessages = messages .slice(-3) .map((message) => message.role === "assistant" && Array.isArray(message.content) ? { ...message, content: message.content.filter( (block) => block.type !== "thinking" && block.type !== "redacted_thinking" ) } : message ) .filter((message) => message.content.length > 0); // 建立新的訊息清單：壓縮區塊 + 保留的訊息 const messagesAfterCompaction: Anthropic.Beta.Messages.BetaMessageParam[] = [ { role: "assistant", content: [compactionBlock] }, ...preservedMessages ]; // 以壓縮後的上下文 + 保留的訊息繼續請求 response = await client.beta.messages.create({ betas: ["compact-2026-01-12"], model: "claude-opus-5-5", max_tokens: 4096, messages: messagesAfterCompaction, context_management: { edits: [{ type: "compact_20260112" }] } }); // 更新訊息清單以反映壓縮結果 messages = messagesAfterCompaction; } // 附加最終回應 messages.push({ role: "assistant", content: response.content }); // 傳回文字內容 const textBlock = response.content.find((block) => block.type === "text"); return textBlock?.text ?? ""; } // 執行長時間對話 console.log(await chat("Help me build a Python web scraper")); console.log(await chat("Add support for JavaScript-rendered pages")); console.log(await chat("Now add rate limiting and error handling")); // 視對話需要持續呼叫 chat() ``` ```csharp C# AnthropicClient client = new(); List messages = new(); Console.WriteLine(await Chat("Help me build a Python web scraper")); Console.WriteLine(await Chat("Add support for JavaScript-rendered pages")); Console.WriteLine(await Chat("Now add rate limiting and error handling")); async Task Chat(string userMessage) { messages.Add(new() { Role = Role.User, Content = userMessage }); var response = await client.Beta.Messages.Create(new() { Betas = ["compact-2026-01-12"], Model = Model.ClaudeOpus5_5, MaxTokens = 4096, Messages = messages, ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit { Trigger = new BetaInputTokensTrigger(100000), PauseAfterCompaction = true }] } }); if (response.StopReason == BetaStopReason.Compaction) { if (!response.Content[0].TryPickCompaction(out _)) throw new InvalidOperationException("Expected compaction block"); // 保留先前的對話往返與目前的使用者訊息（共 3 則訊息）， // 但不含 thinking 區塊；內容為空的 assistant 回合會被捨棄 var preserved = messages .Skip(Math.Max(0, messages.Count - 3)) .Select(message => message.Content.TryPickBetaContentBlockParams(out var blocks) ? new BetaMessageParam { Role = message.Role, Content = blocks .Where(block => block.Type.GetString() is not ("thinking" or "redacted_thinking")) .ToList() } : message) .Where(message => !message.Content.TryPickBetaContentBlockParams(out var blocks) || blocks.Count > 0) .ToList(); var messagesAfterCompaction = new List { new() { Role = Role.Assistant, Content = new List { new BetaContentBlockParam(response.Content[0].Json) } } }; messagesAfterCompaction.AddRange(preserved); response = await client.Beta.Messages.Create(new() { Betas = ["compact-2026-01-12"], Model = Model.ClaudeOpus5_5, MaxTokens = 4096, Messages = messagesAfterCompaction, ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit()] } }); messages = messagesAfterCompaction; } messages.Add(new() { Role = Role.Assistant, Content = response.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList() }); return response.Content .Select(block => block.Value) .OfType() .Select(tb => tb.Text) .FirstOrDefault() ?? ""; } ``` ```go Go package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) var ( client = anthropic.NewClient() messages []anthropic.BetaMessageParam ) func chat(userMessage string) string { messages = append(messages, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(userMessage))) compactEdit := anthropic.BetaContextManagementConfigParam{ Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{ Trigger: anthropic.BetaInputTokensTriggerParam{Value: 100000}, PauseAfterCompaction: anthropic.Bool(true), }}, }, } response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 4096, Messages: messages, ContextManagement: compactEdit, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) if err != nil { log.Fatal(err) } if response.StopReason == "compaction" { compactionParam := response.Content[0].ToParam() // 保留先前的對話往返與目前的使用者訊息（共 3 則訊息）， // 但不含 thinking 區塊；內容為空的 assistant 回合會被捨棄 var preserved []anthropic.BetaMessageParam for _, message := range messages[max(0, len(messages)-3):] { var content []anthropic.BetaContentBlockParamUnion for _, block := range message.Content { if block.OfThinking == nil && block.OfRedactedThinking == nil { content = append(content, block) } } if len(content) == 0 { continue } message.Content = content preserved = append(preserved, message) } messagesAfterCompaction := []anthropic.BetaMessageParam{ {Role: anthropic.BetaMessageParamRoleAssistant, Content: []anthropic.BetaContentBlockParamUnion{compactionParam}}, } messagesAfterCompaction = append(messagesAfterCompaction, preserved...) response, err = client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 4096, Messages: messagesAfterCompaction, ContextManagement: anthropic.BetaContextManagementConfigParam{ Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}}, }, }, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) if err != nil { log.Fatal(err) } messages = messagesAfterCompaction } messages = append(messages, response.ToParam()) for _, block := range response.Content { if textBlock, ok := block.AsAny().(anthropic.BetaTextBlock); ok { return textBlock.Text } } return "" } func main() { fmt.Println(chat("Help me build a Python web scraper")) fmt.Println(chat("Add support for JavaScript-rendered pages")) fmt.Println(chat("Now add rate limiting and error handling")) } ``` ```java Java import com.anthropic.models.beta.messages.BetaContextManagementConfig; import com.anthropic.models.beta.messages.BetaCompact20260112Edit; import com.anthropic.models.beta.messages.BetaInputTokensTrigger; import com.anthropic.models.beta.messages.BetaStopReason; // ... private static final AnthropicClient client = AnthropicOkHttpClient.fromEnv(); private static final List messages = new ArrayList<>(); public static String chat(String userMessage) { messages.add(BetaMessageParam.builder() .role(BetaMessageParam.Role.USER) .content(userMessage) .build()); MessageCreateParams params = MessageCreateParams.builder() .addBeta("compact-2026-01-12") .model(Model.CLAUDE_OPUS_5_5) .maxTokens(4096L) .messages(messages) .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder() .trigger(BetaInputTokensTrigger.builder() .value(100000L) .build()) .pauseAfterCompaction(true) .build()) .build()) .build(); BetaMessage response = client.beta().messages().create(params); // 檢查是否已發生壓縮並暫停 if (response.stopReason().isPresent() && response.stopReason().get().equals(BetaStopReason.COMPACTION)) { // 保留先前的對話往返與目前的使用者訊息（共 3 則訊息）， // 不含 thinking 區塊；若 assistant 回合因此為空則予以捨棄 List preservedMessages = new ArrayList<>(); for (BetaMessageParam message : messages.subList(Math.max(0, messages.size() - 3), messages.size())) { if (message.content().isBetaContentBlockParams()) { message = message.toBuilder() .contentOfBetaContentBlockParams(message.content().asBetaContentBlockParams().stream() .filter(block -> !block.isThinking() && !block.isRedactedThinking()) .toList()) .build(); if (message.content().asBetaContentBlockParams().isEmpty()) { continue; } } preservedMessages.add(message); } // 建立新的訊息清單：壓縮內容 + 保留的訊息 List messagesAfterCompaction = new ArrayList<>(); messagesAfterCompaction.add(response.toParam()); messagesAfterCompaction.addAll(preservedMessages); // 以壓縮後的上下文 + 保留的訊息繼續請求 MessageCreateParams continueParams = MessageCreateParams.builder() .addBeta("compact-2026-01-12") .model(Model.CLAUDE_OPUS_5_5) .maxTokens(4096L) .messages(messagesAfterCompaction) .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder().build()) .build()) .build(); response = client.beta().messages().create(continueParams); // 更新訊息清單以反映壓縮結果 messages.clear(); messages.addAll(messagesAfterCompaction); } // 附加最終回應 messages.add(response.toParam()); return response.content().stream() .filter(block -> block.text().isPresent()) .map(block -> block.text().get().text()) .findFirst() .orElse(""); } public static void main(String[] args) { System.out.println(chat("Help me build a Python web scraper")); System.out.println(chat("Add support for JavaScript-rendered pages")); System.out.println(chat("Now add rate limiting and error handling")); } ``` ```php PHP $client = new Client(); $messages = []; function chat($client, &$messages, $userMessage) { $messages[] = ['role' => 'user', 'content' => $userMessage]; $response = $client->beta->messages->create( maxTokens: 4096, messages: $messages, model: 'claude-opus-5-5', betas: ['compact-2026-01-12'], contextManagement: [ 'edits' => [ [ 'type' => 'compact_20260112', 'trigger' => ['type' => 'input_tokens', 'value' => 100000], 'pause_after_compaction' => true ] ] ] ); if ($response->stopReason === 'compaction') { $compactionBlock = $response->content[0]; // 保留先前的對話往返與目前的使用者訊息（共 3 則訊息）， // 不含 thinking 區塊；內容為空的 assistant 回合會被捨棄 $preserved = array_values(array_filter(array_map( fn($message) => $message['role'] === 'assistant' ? array_merge($message, ['content' => array_values(array_filter( $message['content'], fn($block) => !in_array($block->type, ['thinking', 'redacted_thinking'], true) ))]) : $message, array_slice($messages, -3) ), fn($message) => $message['content'] !== [])); $messagesAfterCompaction = array_merge( [['role' => 'assistant', 'content' => [$compactionBlock]]], $preserved ); $response = $client->beta->messages->create( maxTokens: 4096, messages: $messagesAfterCompaction, model: 'claude-opus-5-5', betas: ['compact-2026-01-12'], contextManagement: [ 'edits' => [['type' => 'compact_20260112']] ] ); $messages = $messagesAfterCompaction; } $messages[] = ['role' => 'assistant', 'content' => $response->content]; foreach ($response->content as $block) { if ($block->type === 'text') { return $block->text; } } return ''; } echo chat($client, $messages, "Help me build a Python web scraper") . "\n"; echo chat($client, $messages, "Add support for JavaScript-rendered pages") . "\n"; echo chat($client, $messages, "Now add rate limiting and error handling") . "\n"; ``` ```ruby Ruby client = Anthropic::Client.new messages = [] def chat(client, messages, user_message) messages << { role: "user", content: user_message } response = client.beta.messages.create( betas: ["compact-2026-01-12"], model: "claude-opus-5-5", max_tokens: 4096, messages: messages, context_management: { edits: [ { type: "compact_20260112", trigger: { type: "input_tokens", value: 100000 }, pause_after_compaction: true } ] } ) if response.stop_reason == :compaction compaction_block = response.content[0] # 保留先前的對話往返與目前的使用者訊息（共 3 則訊息）， # 但不含 thinking 區塊；內容為空的 assistant 回合會被捨棄 preserved = messages.last(3).map do |message| next message unless message[:role] == "assistant" message.merge(content: message[:content].reject { |block| %i[thinking redacted_thinking].include?(block.type) }) end.reject { |message| message[:content].empty? } messages_after_compaction = [ { role: "assistant", content: [compaction_block] } ] + preserved response = client.beta.messages.create( betas: ["compact-2026-01-12"], model: "claude-opus-5-5", max_tokens: 4096, messages: messages_after_compaction, context_management: { edits: [{ type: "compact_20260112" }] } ) messages.clear messages.concat(messages_after_compaction) end messages << { role: "assistant", content: response.content } response.content.find { |block| block.type == :text }&.text || "" end puts chat(client, messages, "Help me build a Python web scraper") puts chat(client, messages, "Add support for JavaScript-rendered pages") puts chat(client, messages, "Now add rate limiting and error handling") ``` ## 目前的限制 * **使用相同模型進行摘要：** 您在請求中指定的模型會用於摘要。目前沒有選項可以使用不同的（例如較便宜的）模型來產生摘要。 * **定義工具時壓縮可能會失敗：** 當您的請求包含 `tools` 時，模型偶爾會在內部摘要步驟中呼叫工具，而不是撰寫摘要。發生這種情況時，回應會包含一個 `content: null` 的 `compaction` 區塊。為避免此情況，請將 [`instructions`](https://platform.claude.com/docs/zh-TW/build-with-claude/compaction-threshold#custom-summarization-instructions) 設定為明確告訴模型不要呼叫工具的提示，例如： ```text wrap Summarize the transcript inside

tags. Include relevant information in the summary for continuing the task in the next context window. Do not call any tools while writing this summary; respond with text only. ``` ## 後續步驟透過上下文編輯，在對話上下文增長時自動加以管理。了解上下文視窗的大小與管理策略。探索一個實際的實作，它使用背景執行緒與提示快取，透過即時工作階段記憶壓縮來管理長時間執行的對話。