---
title: 컨텍스트 편집
url: https://platform.claude.com/docs/ko/build-with-claude/context-editing
description: 컨텍스트 편집을 사용하여 대화 컨텍스트가 커짐에 따라 자동으로 관리합니다.
---

<Note>
  "zero data retention"(제로 데이터 보존), 즉 ZDR이 이 기능에 어떻게 적용되는지 알아보려면 [API 및 데이터 보존](https://platform.claude.com/docs/ko/manage-claude/api-and-data-retention)을 참조하세요.
</Note>

## 개요

<Note>
  대부분의 사용 사례에서 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction)은 장기 실행 대화에서 컨텍스트를 관리하기 위한 기본 전략입니다. 이 페이지의 전략은 어떤 콘텐츠를 지울지 더 세밀하게 제어해야 하는 특정 시나리오에 유용합니다.
</Note>

"Context editing"(컨텍스트 편집)을 사용하면 대화 기록이 커짐에 따라 특정 콘텐츠를 선택적으로 지울 수 있습니다. 비용을 최적화하고 한도 내에 머무르는 것을 넘어, 이는 Claude가 보는 내용을 적극적으로 선별하는 것입니다. 컨텍스트는 수익이 점차 감소하는 유한한 자원이며, 관련 없는 콘텐츠는 모델의 집중력을 저하시킵니다. 컨텍스트 편집은 이러한 선별에 대한 세밀한 런타임 제어를 제공합니다. 컨텍스트 관리의 더 넓은 원칙에 대해서는 [효과적인 컨텍스트 엔지니어링](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)을 참조하세요. 이 페이지에서 다루는 내용은 다음과 같습니다:

* **도구 결과 지우기** - 오래된 도구 결과가 더 이상 필요하지 않은, 도구 사용이 많은 에이전트 워크플로에 가장 적합합니다
* **사고 블록 지우기** - 이전 턴의 사고 블록을 관리하기 위한 것으로, 컨텍스트 연속성을 위해 최근 사고를 보존하는 옵션이 있습니다
* **클라이언트 측 SDK 압축** - 요약 기반 컨텍스트 관리를 위한 SDK 기반 대안입니다(일반적으로 서버 측 압축이 선호됩니다)

| 접근 방식       | 실행 위치 | 전략                                                                                | 작동 방식                                                                                                                                                                                                                                                                                                                                                     |
| ----------- | ----- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **서버 측**    | API   | 도구 결과 지우기 (`clear_tool_uses_20250919`)<br />사고 블록 지우기 (`clear_thinking_20251015`) | 프롬프트가 Claude에 도달하기 전에 적용됩니다. 대화 기록에서 특정 콘텐츠를 지웁니다. 각 전략은 독립적으로 구성할 수 있습니다.                                                                                                                                                                                                                                                                                |
| **클라이언트 측** | SDK   | 압축                                                                                | [`tool_runner`](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-runner)를 사용할 때 [TypeScript 및 Ruby SDK](https://platform.claude.com/docs/ko/cli-sdks-libraries/overview)에서 사용할 수 있습니다. 요약을 생성하고 전체 대화 기록을 대체합니다. [클라이언트 측 압축](https://platform.claude.com/docs/ko/build-with-claude/context-editing#client-side-compaction-sdk)을 참조하세요. |

## 서버 측 전략

<Note>
  컨텍스트 편집은 도구 결과 지우기 및 사고 블록 지우기를 지원하는 베타 상태입니다. 이를 활성화하려면 API 요청에서 베타 헤더 `context-management-2025-06-27`을 사용하세요.

  [피드백 양식](https://forms.gle/YXC2EKGMhjN1c4L88)을 통해 이 기능에 대한 피드백을 공유해 주세요.
</Note>

### 도구 결과 지우기

`clear_tool_uses_20250919` 전략은 대화 컨텍스트가 구성된 임계값을 초과하여 커질 때 도구 결과를 지웁니다. 이는 도구 사용이 많은 에이전트 워크플로에 특히 유용합니다. 오래된 도구 결과(파일 내용이나 검색 결과 등)는 Claude가 처리한 후에는 더 이상 필요하지 않습니다.

활성화되면 API는 가장 오래된 도구 결과를 시간순으로 자동으로 지웁니다. API는 지워진 각 결과를 Claude에게 해당 결과가 제거되었음을 알리는 플레이스홀더 텍스트로 대체합니다. 기본적으로 도구 결과만 지워집니다. `clear_tool_inputs`를 true로 설정하여 도구 결과와 도구 호출(도구 사용 매개변수)을 모두 지우도록 선택할 수 있습니다.

### 사고 블록 지우기

`clear_thinking_20251015` 전략은 이전 어시스턴트 턴의 `thinking` 블록을 관리합니다. 이 전략을 사용하면 사고 보존을 제어할 수 있습니다. 추론 연속성을 유지하기 위해 더 많은 사고 블록을 유지하거나, 컨텍스트 공간을 절약하기 위해 더 적극적으로 지울 수 있습니다.

<Tip>
  **기본 동작:** 기본값은 모델 클래스에 따라 다릅니다.

  | 모델 클래스         | 이전 사고 모두 유지          | 마지막 턴의 사고만 유지               |
  | -------------- | -------------------- | --------------------------- |
  | Opus           | Claude Opus 4.5 이상   | Claude Opus 4.1 이하          |
  | Sonnet         | Claude Sonnet 4.6 이상 | Claude Sonnet 4.5(지원 중단) 이하 |
  | Haiku          | Claude Haiku 5.5 이상  | Claude Haiku 4.5 이하         |
  | Fable 및 Mythos | 모든 모델                | (없음)                        |

  이 전략을 사용하여 기본값을 재정의하세요. 코드가 여러 모델 티어에서 실행되는 경우 모델별 기본값에 의존하지 말고 `keep`을 명시적으로 설정하세요.
</Tip>

어시스턴트 대화 턴에는 여러 콘텐츠 블록(예: 도구를 사용할 때)과 여러 사고 블록(예: [인터리브 사고](https://platform.claude.com/docs/ko/build-with-claude/thinking#interleaved-thinking) 사용 시)이 포함될 수 있습니다.

### 컨텍스트 편집은 서버 측에서 수행됩니다

컨텍스트 편집은 프롬프트가 Claude에 도달하기 전에 서버 측에서 적용됩니다. 클라이언트 애플리케이션은 수정되지 않은 전체 대화 기록을 유지합니다. 클라이언트 상태를 편집된 버전과 동기화할 필요가 없습니다. 평소처럼 전체 대화 기록을 로컬에서 계속 관리하세요.

Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5에서는 서버 측 컨텍스트 관리가 사고 블록을 무효화하지 않습니다. 이전 턴에 대한 클라이언트 측 편집은 이후의 모든 어시스턴트 턴에 있는 사고 블록을 무효화할 수 있습니다. 2026년 8월 31일 이후에 생성된 신규 계정의 경우, 무효화된 블록을 재전송하는 요청은 해당 블록을 삭제하도록 옵트인하지 않는 한 거부됩니다. [접두사를 변경하지 않고 유지하기](https://platform.claude.com/docs/ko/build-with-claude/preserved-thinking#prefix-check)를 참조하세요.

### 컨텍스트 편집과 프롬프트 캐싱

컨텍스트 편집과 [프롬프트 캐싱](https://platform.claude.com/docs/ko/build-with-claude/prompt-caching)의 상호작용은 전략에 따라 다릅니다:

* **도구 결과 지우기:** 콘텐츠가 지워질 때 캐시된 프롬프트 접두사를 무효화합니다. 이를 고려하여 캐시 무효화가 가치 있을 만큼 충분한 토큰을 지우세요. `clear_at_least` 매개변수를 사용하여 매번 최소한의 토큰 수가 지워지도록 하세요. 콘텐츠가 지워질 때마다 캐시 쓰기 비용이 발생하지만, 후속 요청은 새로 캐시된 접두사를 재사용할 수 있습니다.

* **사고 블록 지우기:** 사고 블록이 컨텍스트에 **유지**되면(지워지지 않으면) 프롬프트 캐시가 보존되어 캐시 히트가 가능하고 입력 토큰 비용이 줄어듭니다. 사고 블록이 **지워지면** 지우기가 발생한 지점에서 캐시가 무효화됩니다. 캐시 성능을 우선할지 컨텍스트 윈도우 가용성을 우선할지에 따라 `keep` 매개변수를 구성하세요.

## 지원 모델

컨텍스트 편집은 지원되는 모든 Claude 모델에서 사용할 수 있습니다.

## 도구 결과 지우기 사용법

도구 결과 지우기를 활성화하는 가장 간단한 방법은 전략 유형만 지정하는 것입니다. 다른 모든 [구성 옵션](https://platform.claude.com/docs/ko/build-with-claude/context-editing#configuration-options-for-tool-result-clearing)은 기본값을 사용합니다:

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
      --header "x-api-key: $ANTHROPIC_API_KEY" \
      --header "anthropic-version: 2023-06-01" \
      --header "content-type: application/json" \
      --header "anthropic-beta: context-management-2025-06-27" \
      --data '{
          "model": "claude-opus-5-5",
          "max_tokens": 4096,
          "messages": [
              {
                  "role": "user",
                  "content": "Search for recent developments in AI"
              }
          ],
          "tools": [
              {
                  "type": "web_search_20250305",
                  "name": "web_search"
              }
          ],
          "context_management": {
              "edits": [
                  {"type": "clear_tool_uses_20250919"}
              ]
          }
      }'
  ```

  ```bash CLI
  ant beta:messages create --beta context-management-2025-06-27 <<'YAML'
  model: claude-opus-5-5
  max_tokens: 4096
  messages:
    - role: user
      content: Search for recent developments in AI
  tools:
    - type: web_search_20250305
      name: web_search
  context_management:
    edits:
      - type: clear_tool_uses_20250919
  YAML
  ```

  ```python Python
  response = client.beta.messages.create(
      model="claude-opus-5-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"}]},
  )
  ```

  ```typescript TypeScript
  const anthropic = new Anthropic({
    apiKey: process.env.ANTHROPIC_API_KEY
  });

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

  ```csharp C#
  using Anthropic;
  using Anthropic.Models.Beta;
  using Anthropic.Models.Beta.Messages;
  using Messages = Anthropic.Models.Messages;

  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Messages::Model.ClaudeOpus5_5,
      MaxTokens = 4096,
      Messages = [
          new() { Role = Role.User, Content = "Search for recent developments in AI" }
      ],
      Tools = [
          new BetaWebSearchTool20250305()
      ],
      ContextManagement = new BetaContextManagementConfig
      {
          Edits = [new BetaClearToolUses20250919Edit()]
      },
      Betas = [AnthropicBeta.ContextManagement2025_06_27]
  };

  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,
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Search for recent developments in AI")),
  	},
  	Tools: []anthropic.BetaToolUnionParam{
  		{OfWebSearchTool20250305: &anthropic.BetaWebSearchTool20250305Param{}},
  	},
  	ContextManagement: anthropic.BetaContextManagementConfigParam{
  		Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
  			{OfClearToolUses20250919: &anthropic.BetaClearToolUses20250919EditParam{}},
  		},
  	},
  	Betas: []anthropic.AnthropicBeta{
  		anthropic.AnthropicBetaContextManagement2025_06_27,
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response)
  ```

  ```java Java
  import com.anthropic.models.beta.messages.BetaWebSearchTool20250305;
  import com.anthropic.models.beta.messages.BetaContextManagementConfig;
  import com.anthropic.models.beta.messages.BetaClearToolUses20250919Edit;
  import com.anthropic.models.beta.AnthropicBeta;
  // ...
  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      MessageCreateParams params = MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(4096L)
          .addUserMessage("Search for recent developments in AI")
          .addTool(BetaWebSearchTool20250305.builder().build())
          .contextManagement(BetaContextManagementConfig.builder()
              .addEdit(BetaClearToolUses20250919Edit.builder().build())
              .build())
          .addBeta(AnthropicBeta.CONTEXT_MANAGEMENT_2025_06_27)
          .build();

      BetaMessage response = client.beta().messages().create(params);
      IO.println(response);
  }
  ```

  ```php PHP
  $client = new Client();

  $response = $client->beta->messages->create(
      maxTokens: 4096,
      messages: [
          ['role' => 'user', 'content' => 'Search for recent developments in AI']
      ],
      model: 'claude-opus-5-5',
      betas: ['context-management-2025-06-27'],
      tools: [
          ['type' => 'web_search_20250305', 'name' => 'web_search']
      ],
      contextManagement: [
          'edits' => [
              ['type' => 'clear_tool_uses_20250919']
          ]
      ],
  );

  echo $response;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

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

### 고급 구성

추가 매개변수로 도구 결과 지우기 동작을 사용자 지정할 수 있습니다:

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
      --header "x-api-key: $ANTHROPIC_API_KEY" \
      --header "anthropic-version: 2023-06-01" \
      --header "content-type: application/json" \
      --header "anthropic-beta: context-management-2025-06-27" \
      --data '{
          "model": "claude-opus-5-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
              }
          ],
          "context_management": {
              "edits": [
                  {
                      "type": "clear_tool_uses_20250919",
                      "trigger": {
                          "type": "input_tokens",
                          "value": 30000
                      },
                      "keep": {
                          "type": "tool_uses",
                          "value": 3
                      },
                      "clear_at_least": {
                          "type": "input_tokens",
                          "value": 5000
                      },
                      "exclude_tools": ["web_search"]
                  }
              ]
          }
      }'
  ```

  ```bash CLI
  ant beta:messages create --beta context-management-2025-06-27 <<'YAML'
  model: claude-opus-5-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
  context_management:
    edits:
      - type: clear_tool_uses_20250919
        trigger:
          type: input_tokens
          value: 30000
        keep:
          type: tool_uses
          value: 3
        clear_at_least:
          type: input_tokens
          value: 5000
        exclude_tools:
          - web_search
  YAML
  ```

  ```python Python
  response = client.beta.messages.create(
      model="claude-opus-5-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": {"type": "input_tokens", "value": 30000},
                  # 지운 후 유지할 도구 사용 횟수
                  "keep": {"type": "tool_uses", "value": 3},
                  # 선택 사항: 최소 이 토큰 수만큼 지웁니다
                  "clear_at_least": {"type": "input_tokens", "value": 5000},
                  # 이 도구들은 지우기 대상에서 제외합니다
                  "exclude_tools": ["web_search"],
              }
          ]
      },
  )
  ```

  ```typescript TypeScript
  const anthropic = new Anthropic({
    apiKey: process.env.ANTHROPIC_API_KEY
  });

  const response = await anthropic.beta.messages.create({
    model: "claude-opus-5-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: {
            type: "input_tokens",
            value: 30000
          },
          // 지운 후 유지할 도구 사용 횟수입니다
          keep: {
            type: "tool_uses",
            value: 3
          },
          // 선택 사항: 최소한 이 토큰 수만큼 지웁니다
          clear_at_least: {
            type: "input_tokens",
            value: 5000
          },
          // 이 도구들은 지우기 대상에서 제외합니다
          exclude_tools: ["web_search"]
        }
      ]
    }
  });
  ```

  ```csharp C#
  using Anthropic;
  using Anthropic.Models.Beta;
  using Anthropic.Models.Beta.Messages;
  using Messages = Anthropic.Models.Messages;

  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Messages::Model.ClaudeOpus5_5,
      MaxTokens = 4096,
      Messages = [
          new() { Role = Role.User, Content = "Create a simple command line calculator app using Python" }
      ],
      Tools = [
          new BetaToolTextEditor20250728 { MaxCharacters = 10000 },
          new BetaWebSearchTool20250305 { MaxUses = 3 }
      ],
      Betas = [AnthropicBeta.ContextManagement2025_06_27],
      ContextManagement = new BetaContextManagementConfig
      {
          Edits = [
              new BetaClearToolUses20250919Edit
              {
                  Trigger = new BetaInputTokensTrigger(30000),
                  Keep = new BetaToolUsesKeep(3),
                  ClearAtLeast = new BetaInputTokensClearAtLeast(5000),
                  ExcludeTools = ["web_search"]
              }
          ]
      }
  };

  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,
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Create a simple command line calculator app using Python")),
  	},
  	Tools: []anthropic.BetaToolUnionParam{
  		{OfTextEditor20250728: &anthropic.BetaToolTextEditor20250728Param{
  			MaxCharacters: anthropic.Int(10000),
  		}},
  		{OfWebSearchTool20250305: &anthropic.BetaWebSearchTool20250305Param{
  			MaxUses: anthropic.Int(3),
  		}},
  	},
  	Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaContextManagement2025_06_27},
  	ContextManagement: anthropic.BetaContextManagementConfigParam{
  		Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
  			{OfClearToolUses20250919: &anthropic.BetaClearToolUses20250919EditParam{
  				Trigger: anthropic.BetaClearToolUses20250919EditTriggerUnionParam{
  					OfInputTokens: &anthropic.BetaInputTokensTriggerParam{
  						Value: 30000,
  					},
  				},
  				Keep: anthropic.BetaToolUsesKeepParam{
  					Value: 3,
  				},
  				ClearAtLeast: anthropic.BetaInputTokensClearAtLeastParam{
  					Value: 5000,
  				},
  				ExcludeTools: []string{"web_search"},
  			}},
  		},
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response)
  ```

  ```java Java
  import com.anthropic.models.beta.messages.BetaToolTextEditor20250728;
  import com.anthropic.models.beta.messages.BetaWebSearchTool20250305;
  import com.anthropic.models.beta.messages.BetaContextManagementConfig;
  import com.anthropic.models.beta.messages.BetaClearToolUses20250919Edit;
  import com.anthropic.models.beta.messages.BetaInputTokensTrigger;
  import com.anthropic.models.beta.messages.BetaInputTokensClearAtLeast;
  import com.anthropic.models.beta.messages.BetaToolUsesKeep;
  import com.anthropic.models.beta.AnthropicBeta;
  // ...
  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      MessageCreateParams params = MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(4096L)
          .addUserMessage("Create a simple command line calculator app using Python")
          .addTool(BetaToolTextEditor20250728.builder()
              .maxCharacters(10000L)
              .build())
          .addTool(BetaWebSearchTool20250305.builder()
              .maxUses(3L)
              .build())
          .addBeta(AnthropicBeta.CONTEXT_MANAGEMENT_2025_06_27)
          .contextManagement(BetaContextManagementConfig.builder()
              .addEdit(BetaClearToolUses20250919Edit.builder()
                  .trigger(BetaInputTokensTrigger.builder()
                      .value(30000L)
                      .build())
                  .keep(BetaToolUsesKeep.builder()
                      .value(3L)
                      .build())
                  .clearAtLeast(BetaInputTokensClearAtLeast.builder()
                      .value(5000L)
                      .build())
                  .addExcludeTool("web_search")
                  .build())
              .build())
          .build();

      BetaMessage response = client.beta().messages().create(params);
      IO.println(response);
  }
  ```

  ```php PHP
  $client = new Client();

  $response = $client->beta->messages->create(
      maxTokens: 4096,
      messages: [
          [
              'role' => 'user',
              'content' => 'Create a simple command line calculator app using Python'
          ]
      ],
      model: 'claude-opus-5-5',
      betas: ['context-management-2025-06-27'],
      tools: [
          [
              'type' => 'text_editor_20250728',
              'name' => 'str_replace_based_edit_tool',
              'max_characters' => 10000
          ],
          [
              'type' => 'web_search_20250305',
              'name' => 'web_search',
              'max_uses' => 3
          ]
      ],
      contextManagement: [
          'edits' => [
              [
                  'type' => 'clear_tool_uses_20250919',
                  'trigger' => [
                      'type' => 'input_tokens',
                      'value' => 30000
                  ],
                  'keep' => [
                      'type' => 'tool_uses',
                      'value' => 3
                  ],
                  'clear_at_least' => [
                      'type' => 'input_tokens',
                      'value' => 5000
                  ],
                  'exclude_tools' => ['web_search']
              ]
          ]
      ],
  );

  echo $response;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  response = client.beta.messages.create(
    model: "claude-opus-5-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: {
            type: "input_tokens",
            value: 30000
          },
          keep: {
            type: "tool_uses",
            value: 3
          },
          clear_at_least: {
            type: "input_tokens",
            value: 5000
          },
          exclude_tools: ["web_search"]
        }
      ]
    }
  )
  puts response
  ```
</CodeGroup>

## 사고 블록 지우기 사용법

이전 턴의 사고 블록을 포함하는 대화에서 컨텍스트와 프롬프트 캐싱을 관리하려면 사고 블록 지우기를 사용하세요:

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
      --header "x-api-key: $ANTHROPIC_API_KEY" \
      --header "anthropic-version: 2023-06-01" \
      --header "content-type: application/json" \
      --header "anthropic-beta: context-management-2025-06-27" \
      --data '{
          "model": "claude-opus-5-5",
          "max_tokens": 16000,
          "messages": [{"role": "user", "content": "Hello"}],
          "context_management": {
              "edits": [
                  {
                      "type": "clear_thinking_20251015",
                      "keep": {
                          "type": "thinking_turns",
                          "value": 2
                      }
                  }
              ]
          }
      }'
  ```

  ```bash CLI
  ant beta:messages create --beta context-management-2025-06-27 <<'YAML'
  model: claude-opus-5-5
  max_tokens: 16000
  messages:
    - role: user
      content: Hello
  context_management:
    edits:
      - type: clear_thinking_20251015
        keep:
          type: thinking_turns
          value: 2
  YAML
  ```

  ```python Python
  response = client.beta.messages.create(
      model="claude-opus-5-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},
              }
          ]
      },
  )
  ```

  ```typescript TypeScript
  const anthropic = new Anthropic({
    apiKey: process.env.ANTHROPIC_API_KEY
  });

  const response = await anthropic.beta.messages.create({
    model: "claude-opus-5-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
          }
        }
      ]
    }
  });
  ```

  ```csharp C#
  using Anthropic;
  using Anthropic.Models.Beta;
  using Anthropic.Models.Beta.Messages;
  using Messages = Anthropic.Models.Messages;

  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Messages::Model.ClaudeOpus5_5,
      MaxTokens = 16000,
      Messages = [
          new() { Role = Role.User, Content = "Hello" }
      ],
      Betas = [AnthropicBeta.ContextManagement2025_06_27],
      ContextManagement = new BetaContextManagementConfig
      {
          Edits = [
              new BetaClearThinking20251015Edit
              {
                  Keep = new BetaThinkingTurns(2)
              }
          ]
      }
  };

  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: 16000,
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello")),
  	},
  	Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaContextManagement2025_06_27},
  	ContextManagement: anthropic.BetaContextManagementConfigParam{
  		Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
  			{OfClearThinking20251015: &anthropic.BetaClearThinking20251015EditParam{
  				Keep: anthropic.BetaClearThinking20251015EditKeepUnionParam{
  					OfThinkingTurns: &anthropic.BetaThinkingTurnsParam{
  						Value: 2,
  					},
  				},
  			}},
  		},
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response)
  ```

  ```java Java
  import com.anthropic.models.beta.messages.BetaContextManagementConfig;
  import com.anthropic.models.beta.messages.BetaClearThinking20251015Edit;
  import com.anthropic.models.beta.messages.BetaThinkingTurns;
  import com.anthropic.models.beta.AnthropicBeta;
  // ...
  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      MessageCreateParams params = MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(16000L)
          .addUserMessage("Hello")
          .addBeta(AnthropicBeta.CONTEXT_MANAGEMENT_2025_06_27)
          .contextManagement(BetaContextManagementConfig.builder()
              .addEdit(BetaClearThinking20251015Edit.builder()
                  .keep(BetaThinkingTurns.builder()
                      .value(2L)
                      .build())
                  .build())
              .build())
          .build();

      BetaMessage response = client.beta().messages().create(params);
      IO.println(response);
  }
  ```

  ```php PHP
  $client = new Client();

  $response = $client->beta->messages->create(
      maxTokens: 16000,
      messages: [
          ['role' => 'user', 'content' => 'Hello']
      ],
      model: 'claude-opus-5-5',
      betas: ['context-management-2025-06-27'],
      contextManagement: [
          'edits' => [
              [
                  'type' => 'clear_thinking_20251015',
                  'keep' => [
                      'type' => 'thinking_turns',
                      'value' => 2
                  ]
              ]
          ]
      ],
  );

  echo $response;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  response = client.beta.messages.create(
    model: "claude-opus-5-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
          }
        }
      ]
    }
  )
  puts response
  ```
</CodeGroup>

### 사고 블록 지우기 구성 옵션

`clear_thinking_20251015` 전략은 다음 구성을 지원합니다:

| 구성 옵션  | 기본값 | 설명                                                                                                                                                                                                                                                                    |
| ------ | --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `keep` | 모델별 | 사고 블록이 있는 최근 어시스턴트 턴을 몇 개 보존할지 정의합니다. 마지막 N개 턴을 유지하려면 `{type: "thinking_turns", value: N}`(N은 0보다 커야 함)을 사용하고, 모든 사고 블록을 유지하려면 `"all"`을 사용하세요. Opus 4.5+, Sonnet 4.6+, Haiku 5.5+: 모든 턴. Fable 및 Mythos 모델: 모든 턴. 이전 Opus/Sonnet 및 Claude Haiku 4.5까지의 Haiku: 마지막 턴만. |

**구성 예시:**

마지막 3개 어시스턴트 턴의 사고 블록 유지:

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
      --header "x-api-key: $ANTHROPIC_API_KEY" \
      --header "anthropic-version: 2023-06-01" \
      --header "content-type: application/json" \
      --header "anthropic-beta: context-management-2025-06-27" \
      --data '{
          "model": "claude-opus-5-5",
          "max_tokens": 16000,
          "messages": [{"role": "user", "content": "Hello"}],
          "context_management": {
              "edits": [
                  {
                      "type": "clear_thinking_20251015",
                      "keep": {
                          "type": "thinking_turns",
                          "value": 3
                      }
                  }
              ]
          }
      }'
  ```

  ```bash CLI
  ant beta:messages create --beta context-management-2025-06-27 <<'YAML'
  model: claude-opus-5-5
  max_tokens: 16000
  messages:
    - role: user
      content: Hello
  context_management:
    edits:
      - type: clear_thinking_20251015
        keep:
          type: thinking_turns
          value: 3
  YAML
  ```

  ```python Python
  response = client.beta.messages.create(
      model="claude-opus-5-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},
              }
          ]
      },
  )
  ```

  ```typescript TypeScript
  const anthropic = new Anthropic({
    apiKey: process.env.ANTHROPIC_API_KEY
  });

  const response = await anthropic.beta.messages.create({
    model: "claude-opus-5-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
          }
        }
      ]
    }
  });
  ```

  ```csharp C#
  using Anthropic;
  using Anthropic.Models.Beta;
  using Anthropic.Models.Beta.Messages;
  using Messages = Anthropic.Models.Messages;

  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Messages::Model.ClaudeOpus5_5,
      MaxTokens = 16000,
      Messages = [
          new() { Role = Role.User, Content = "Hello" }
      ],
      Betas = [AnthropicBeta.ContextManagement2025_06_27],
      ContextManagement = new BetaContextManagementConfig
      {
          Edits = [
              new BetaClearThinking20251015Edit
              {
                  Keep = new BetaThinkingTurns(3)
              }
          ]
      }
  };

  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: 16000,
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello")),
  	},
  	Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaContextManagement2025_06_27},
  	ContextManagement: anthropic.BetaContextManagementConfigParam{
  		Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
  			{OfClearThinking20251015: &anthropic.BetaClearThinking20251015EditParam{
  				Keep: anthropic.BetaClearThinking20251015EditKeepUnionParam{
  					OfThinkingTurns: &anthropic.BetaThinkingTurnsParam{
  						Value: 3,
  					},
  				},
  			}},
  		},
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response)
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_OPUS_5_5)
      .maxTokens(16000L)
      .addUserMessage("Hello")
      .addBeta(AnthropicBeta.CONTEXT_MANAGEMENT_2025_06_27)
      .contextManagement(BetaContextManagementConfig.builder()
          .addEdit(BetaClearThinking20251015Edit.builder()
              .keep(BetaThinkingTurns.builder()
                  .value(3L)
                  .build())
              .build())
          .build())
      .build();

  BetaMessage response = client.beta().messages().create(params);
  IO.println(response);
  ```

  ```php PHP
  $client = new Client();

  $response = $client->beta->messages->create(
      maxTokens: 16000,
      messages: [
          ['role' => 'user', 'content' => 'Hello']
      ],
      model: 'claude-opus-5-5',
      betas: ['context-management-2025-06-27'],
      contextManagement: [
          'edits' => [
              [
                  'type' => 'clear_thinking_20251015',
                  'keep' => [
                      'type' => 'thinking_turns',
                      'value' => 3
                  ]
              ]
          ]
      ],
  );

  echo $response;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  response = client.beta.messages.create(
    model: "claude-opus-5-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
          }
        }
      ]
    }
  )
  puts response
  ```
</CodeGroup>

모든 사고 블록 유지(캐시 히트 최대화):

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
      --header "x-api-key: $ANTHROPIC_API_KEY" \
      --header "anthropic-version: 2023-06-01" \
      --header "content-type: application/json" \
      --header "anthropic-beta: context-management-2025-06-27" \
      --data '{
          "model": "claude-opus-5-5",
          "max_tokens": 16000,
          "messages": [{"role": "user", "content": "Hello"}],
          "context_management": {
              "edits": [
                  {
                      "type": "clear_thinking_20251015",
                      "keep": "all"
                  }
              ]
          }
      }'
  ```

  ```bash CLI
  ant beta:messages create --beta context-management-2025-06-27 <<'YAML'
  model: claude-opus-5-5
  max_tokens: 16000
  messages:
    - role: user
      content: Hello
  context_management:
    edits:
      - type: clear_thinking_20251015
        keep: all
  YAML
  ```

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

  ```typescript TypeScript
  const anthropic = new Anthropic({
    apiKey: process.env.ANTHROPIC_API_KEY
  });

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

  ```csharp C#
  using Anthropic;
  using Anthropic.Models.Beta;
  using Anthropic.Models.Beta.Messages;
  using Messages = Anthropic.Models.Messages;

  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Messages::Model.ClaudeOpus5_5,
      MaxTokens = 16000,
      Messages = [
          new() { Role = Role.User, Content = "Hello" }
      ],
      Betas = [AnthropicBeta.ContextManagement2025_06_27],
      ContextManagement = new BetaContextManagementConfig
      {
          Edits = [
              new BetaClearThinking20251015Edit
              {
                  Keep = new All()
              }
          ]
      }
  };

  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: 16000,
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello")),
  	},
  	Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaContextManagement2025_06_27},
  	ContextManagement: anthropic.BetaContextManagementConfigParam{
  		Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
  			{OfClearThinking20251015: &anthropic.BetaClearThinking20251015EditParam{
  				Keep: anthropic.BetaClearThinking20251015EditKeepUnionParam{
  					OfAll: constant.ValueOf[constant.All](),
  				},
  			}},
  		},
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response)
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_OPUS_5_5)
      .maxTokens(16000L)
      .addUserMessage("Hello")
      .addBeta(AnthropicBeta.CONTEXT_MANAGEMENT_2025_06_27)
      .contextManagement(BetaContextManagementConfig.builder()
          .addEdit(BetaClearThinking20251015Edit.builder()
              .keepAll()
              .build())
          .build())
      .build();

  BetaMessage response = client.beta().messages().create(params);
  IO.println(response);
  ```

  ```php PHP
  $client = new Client();

  $response = $client->beta->messages->create(
      maxTokens: 16000,
      messages: [
          ['role' => 'user', 'content' => 'Hello']
      ],
      model: 'claude-opus-5-5',
      betas: ['context-management-2025-06-27'],
      contextManagement: [
          'edits' => [
              [
                  'type' => 'clear_thinking_20251015',
                  'keep' => 'all'
              ]
          ]
      ],
  );

  echo $response;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

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

### 전략 결합

사고 블록 지우기와 도구 결과 지우기를 함께 사용할 수 있습니다:

<Note>
  여러 전략을 사용할 때 `clear_thinking_20251015` 전략이 `edits` 배열에서 첫 번째로 나열되어야 합니다.
</Note>

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
      --header "x-api-key: $ANTHROPIC_API_KEY" \
      --header "anthropic-version: 2023-06-01" \
      --header "content-type: application/json" \
      --header "anthropic-beta: context-management-2025-06-27" \
      --data '{
          "model": "claude-opus-5-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
              }
          ],
          "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
                      }
                  }
              ]
          }
      }'
  ```

  ```bash CLI
  ant beta:messages create --beta context-management-2025-06-27 <<'YAML'
  model: claude-opus-5-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
  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
  YAML
  ```

  ```python Python
  response = client.beta.messages.create(
      model="claude-opus-5-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)
  ```

  ```typescript TypeScript
  const anthropic = new Anthropic({
    apiKey: process.env.ANTHROPIC_API_KEY
  });

  const response = await anthropic.beta.messages.create({
    model: "claude-opus-5-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
          }
        }
      ]
    }
  });

  console.log(response);
  ```

  ```csharp C#
  using Anthropic;
  using Anthropic.Models.Beta;
  using Anthropic.Models.Beta.Messages;
  using Messages = Anthropic.Models.Messages;

  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Messages::Model.ClaudeOpus5_5,
      MaxTokens = 16000,
      Messages = [
          new() { Role = Role.User, Content = "Search for the latest developments in quantum error correction and summarize the key breakthroughs." }
      ],
      Tools = [
          new BetaWebSearchTool20250305 { MaxUses = 5 }
      ],
      Betas = [AnthropicBeta.ContextManagement2025_06_27],
      ContextManagement = new BetaContextManagementConfig
      {
          Edits = [
              new BetaClearThinking20251015Edit
              {
                  Keep = new BetaThinkingTurns(2)
              },
              new BetaClearToolUses20250919Edit
              {
                  Trigger = new BetaInputTokensTrigger(50000),
                  Keep = new BetaToolUsesKeep(5)
              }
          ]
      }
  };

  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: 16000,
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Search for the latest developments in quantum error correction and summarize the key breakthroughs.")),
  	},
  	Tools: []anthropic.BetaToolUnionParam{
  		{OfWebSearchTool20250305: &anthropic.BetaWebSearchTool20250305Param{
  			MaxUses: anthropic.Int(5),
  		}},
  	},
  	Betas: []anthropic.AnthropicBeta{
  		anthropic.AnthropicBetaContextManagement2025_06_27,
  	},
  	ContextManagement: anthropic.BetaContextManagementConfigParam{
  		Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
  			{OfClearThinking20251015: &anthropic.BetaClearThinking20251015EditParam{
  				Keep: anthropic.BetaClearThinking20251015EditKeepUnionParam{
  					OfThinkingTurns: &anthropic.BetaThinkingTurnsParam{
  						Value: 2,
  					},
  				},
  			}},
  			{OfClearToolUses20250919: &anthropic.BetaClearToolUses20250919EditParam{
  				Trigger: anthropic.BetaClearToolUses20250919EditTriggerUnionParam{
  					OfInputTokens: &anthropic.BetaInputTokensTriggerParam{
  						Value: 50000,
  					},
  				},
  				Keep: anthropic.BetaToolUsesKeepParam{
  					Value: 5,
  				},
  			}},
  		},
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response)
  ```

  ```java Java
  import com.anthropic.models.beta.messages.BetaWebSearchTool20250305;
  import com.anthropic.models.beta.messages.BetaContextManagementConfig;
  import com.anthropic.models.beta.messages.BetaClearThinking20251015Edit;
  import com.anthropic.models.beta.messages.BetaClearToolUses20250919Edit;
  import com.anthropic.models.beta.messages.BetaThinkingTurns;
  import com.anthropic.models.beta.messages.BetaInputTokensTrigger;
  import com.anthropic.models.beta.messages.BetaToolUsesKeep;
  import com.anthropic.models.beta.AnthropicBeta;
  // ...
  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      MessageCreateParams params = MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(16000L)
          .addUserMessage("Search for the latest developments in quantum error correction and summarize the key breakthroughs.")
          .addTool(BetaWebSearchTool20250305.builder()
              .maxUses(5L)
              .build())
          .addBeta(AnthropicBeta.CONTEXT_MANAGEMENT_2025_06_27)
          .contextManagement(BetaContextManagementConfig.builder()
              .addEdit(BetaClearThinking20251015Edit.builder()
                  .keep(BetaThinkingTurns.builder()
                      .value(2L)
                      .build())
                  .build())
              .addEdit(BetaClearToolUses20250919Edit.builder()
                  .trigger(BetaInputTokensTrigger.builder()
                      .value(50000L)
                      .build())
                  .keep(BetaToolUsesKeep.builder()
                      .value(5L)
                      .build())
                  .build())
              .build())
          .build();

      BetaMessage response = client.beta().messages().create(params);
      IO.println(response);
  }
  ```

  ```php PHP
  $client = new Client();

  $response = $client->beta->messages->create(
      maxTokens: 16000,
      messages: [
          [
              'role' => 'user',
              'content' => 'Search for the latest developments in quantum error correction and summarize the key breakthroughs.'
          ]
      ],
      model: 'claude-opus-5-5',
      betas: ['context-management-2025-06-27'],
      tools: [
          [
              'type' => 'web_search_20250305',
              'name' => 'web_search',
              'max_uses' => 5
          ]
      ],
      contextManagement: [
          '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
                  ]
              ]
          ]
      ],
  );

  echo $response;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  response = client.beta.messages.create(
    model: "claude-opus-5-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
          }
        }
      ]
    }
  )
  puts response
  ```
</CodeGroup>

## 도구 결과 지우기 구성 옵션

| 구성 옵션               | 기본값           | 설명                                                                                                                               |
| ------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `trigger`           | 100,000 입력 토큰 | 컨텍스트 편집 전략이 활성화되는 시점을 정의합니다. 프롬프트가 이 임계값을 초과하면 지우기가 시작됩니다. 이 값은 `input_tokens` 또는 `tool_uses`로 지정할 수 있습니다.                       |
| `keep`              | 3개 도구 사용      | 지우기가 발생한 후 유지할 최근 도구 사용/결과 쌍의 수를 정의합니다. API는 가장 오래된 도구 상호작용을 먼저 제거하고 가장 최근 것을 보존합니다.                                             |
| `clear_at_least`    | 없음            | 전략이 활성화될 때마다 최소한의 토큰 수가 지워지도록 보장합니다. API가 지정된 양 이상을 지울 수 없으면 전략이 적용되지 않습니다. 이는 컨텍스트 지우기가 프롬프트 캐시를 깨뜨릴 만한 가치가 있는지 판단하는 데 도움이 됩니다. |
| `exclude_tools`     | 없음            | 도구 사용 및 결과가 절대 지워지지 않아야 하는 도구 이름 목록입니다. 중요한 컨텍스트를 보존하는 데 유용합니다.                                                                  |
| `clear_tool_inputs` | `false`       | 도구 결과와 함께 도구 호출 매개변수도 지울지 여부를 제어합니다. 기본적으로 Claude의 원래 도구 호출은 보이도록 유지하면서 도구 결과만 지워집니다.                                            |

## 컨텍스트 편집 응답

`context_management` 응답 필드를 사용하여 요청에 어떤 컨텍스트 편집이 적용되었는지, 그리고 지워진 콘텐츠 및 입력 토큰에 대한 유용한 통계를 확인할 수 있습니다.

```json Output
{
  "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
      }
    ]
  }
}
```

스트리밍 응답의 경우 컨텍스트 편집은 최종 `message_delta` 이벤트에 포함됩니다:

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

## 토큰 카운팅

[토큰 카운팅](https://platform.claude.com/docs/ko/build-with-claude/token-counting) 엔드포인트는 컨텍스트 관리를 지원하므로, 컨텍스트 편집이 적용된 후 프롬프트가 사용할 토큰 수를 미리 확인할 수 있습니다.

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages/count_tokens \
      --header "x-api-key: $ANTHROPIC_API_KEY" \
      --header "anthropic-version: 2023-06-01" \
      --header "content-type: application/json" \
      --header "anthropic-beta: context-management-2025-06-27" \
      --data '{
          "model": "claude-opus-5-5",
          "messages": [
              {
                  "role": "user",
                  "content": "Continue our conversation..."
              }
          ],
          "context_management": {
              "edits": [
                  {
                      "type": "clear_tool_uses_20250919",
                      "trigger": {
                          "type": "input_tokens",
                          "value": 30000
                      },
                      "keep": {
                          "type": "tool_uses",
                          "value": 5
                      }
                  }
              ]
          }
      }'
  ```

  ```bash CLI
  ORIGINAL=$(ant beta:messages count-tokens \
    --beta context-management-2025-06-27 \
    --transform context_management.original_input_tokens \
    --raw-output <<'YAML'
  model: claude-opus-5-5
  messages:
    - role: user
      content: Continue our conversation...
  context_management:
    edits:
      - type: clear_tool_uses_20250919
        trigger:
          type: input_tokens
          value: 30000
        keep:
          type: tool_uses
          value: 5
  YAML
  )

  INPUT_TOKENS=$(ant beta:messages count-tokens \
    --beta context-management-2025-06-27 \
    --transform input_tokens --raw-output <<'YAML'
  model: claude-opus-5-5
  messages:
    - role: user
      content: Continue our conversation...
  context_management:
    edits:
      - type: clear_tool_uses_20250919
        trigger:
          type: input_tokens
          value: 30000
        keep:
          type: tool_uses
          value: 5
  YAML
  )

  printf 'Original tokens: %s\n' "$ORIGINAL"
  printf 'After clearing: %s\n' "$INPUT_TOKENS"
  printf 'Savings: %s tokens\n' "$((ORIGINAL - INPUT_TOKENS))"
  ```

  ```python Python
  response = client.beta.messages.count_tokens(
      model="claude-opus-5-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"
  )
  ```

  ```typescript TypeScript
  const anthropic = new Anthropic({
    apiKey: process.env.ANTHROPIC_API_KEY
  });

  const response = await anthropic.beta.messages.countTokens({
    model: "claude-opus-5-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
          }
        }
      ]
    }
  });

  console.log(`Original tokens: ${response.context_management?.original_input_tokens}`);
  console.log(`After clearing: ${response.input_tokens}`);
  console.log(
    `Savings: ${
      (response.context_management?.original_input_tokens || 0) - response.input_tokens
    } tokens`
  );
  ```

  ```csharp C#
  using Anthropic;
  using Anthropic.Models.Beta;
  using Anthropic.Models.Beta.Messages;
  using Messages = Anthropic.Models.Messages;

  AnthropicClient client = new();

  var parameters = new MessageCountTokensParams
  {
      Model = Messages::Model.ClaudeOpus5_5,
      Messages = [new() { Role = Role.User, Content = "Continue our conversation..." }],
      Betas = [AnthropicBeta.ContextManagement2025_06_27],
      ContextManagement = new BetaContextManagementConfig
      {
          Edits = [
              new BetaClearToolUses20250919Edit
              {
                  Trigger = new BetaInputTokensTrigger(30000),
                  Keep = new BetaToolUsesKeep(5)
              }
          ]
      }
  };

  var response = await client.Beta.Messages.CountTokens(parameters);

  Console.WriteLine($"Original tokens: {response.ContextManagement?.OriginalInputTokens}");
  Console.WriteLine($"After clearing: {response.InputTokens}");
  Console.WriteLine($"Savings: {(response.ContextManagement?.OriginalInputTokens ?? 0) - response.InputTokens} tokens");
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Beta.Messages.CountTokens(context.TODO(), anthropic.BetaMessageCountTokensParams{
  	Model: anthropic.ModelClaudeOpus5_5,
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Continue our conversation...")),
  	},
  	Betas: []anthropic.AnthropicBeta{
  		anthropic.AnthropicBetaContextManagement2025_06_27,
  	},
  	ContextManagement: anthropic.BetaContextManagementConfigParam{
  		Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
  			{OfClearToolUses20250919: &anthropic.BetaClearToolUses20250919EditParam{
  				Trigger: anthropic.BetaClearToolUses20250919EditTriggerUnionParam{
  					OfInputTokens: &anthropic.BetaInputTokensTriggerParam{
  						Value: 30000,
  					},
  				},
  				Keep: anthropic.BetaToolUsesKeepParam{
  					Value: 5,
  				},
  			}},
  		},
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Printf("Original tokens: %d\n", response.ContextManagement.OriginalInputTokens)
  fmt.Printf("After clearing: %d\n", response.InputTokens)
  fmt.Printf("Savings: %d tokens\n", response.ContextManagement.OriginalInputTokens-response.InputTokens)
  ```

  ```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.BetaClearToolUses20250919Edit;
  import com.anthropic.models.beta.messages.BetaInputTokensTrigger;
  import com.anthropic.models.beta.messages.BetaToolUsesKeep;
  import com.anthropic.models.beta.AnthropicBeta;
  // ...
  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      MessageCountTokensParams params = MessageCountTokensParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .addUserMessage("Continue our conversation...")
          .addBeta(AnthropicBeta.CONTEXT_MANAGEMENT_2025_06_27)
          .contextManagement(BetaContextManagementConfig.builder()
              .addEdit(BetaClearToolUses20250919Edit.builder()
                  .trigger(BetaInputTokensTrigger.builder()
                      .value(30000L)
                      .build())
                  .keep(BetaToolUsesKeep.builder()
                      .value(5L)
                      .build())
                  .build())
              .build())
          .build();

      BetaMessageTokensCount response = client.beta().messages().countTokens(params);

      IO.println("Original tokens: " + response.contextManagement().get().originalInputTokens());
      IO.println("After clearing: " + response.inputTokens());
      IO.println("Savings: " + (response.contextManagement().get().originalInputTokens() - response.inputTokens()) + " tokens");
  }
  ```

  ```php PHP
  $client = new Client();

  $response = $client->beta->messages->countTokens(
      messages: [
          ['role' => 'user', 'content' => 'Continue our conversation...']
      ],
      model: 'claude-opus-5-5',
      betas: ['context-management-2025-06-27'],
      contextManagement: [
          'edits' => [
              [
                  'type' => 'clear_tool_uses_20250919',
                  'trigger' => [
                      'type' => 'input_tokens',
                      'value' => 30000
                  ],
                  'keep' => [
                      'type' => 'tool_uses',
                      'value' => 5
                  ]
              ]
          ]
      ],
  );

  echo "Original tokens: " . $response->contextManagement->originalInputTokens . "\n";
  echo "After clearing: " . $response->inputTokens . "\n";
  echo "Savings: " . ($response->contextManagement->originalInputTokens - $response->inputTokens) . " tokens\n";
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  response = client.beta.messages.count_tokens(
    model: "claude-opus-5-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
          }
        }
      ]
    }
  )

  puts "Original tokens: #{response.context_management.original_input_tokens}"
  puts "After clearing: #{response.input_tokens}"
  puts "Savings: #{response.context_management.original_input_tokens - response.input_tokens} tokens"
  ```
</CodeGroup>

```json Output
{
  "input_tokens": 25000,
  "context_management": {
    "original_input_tokens": 70000
  }
}
```

응답에는 컨텍스트 관리가 적용된 후의 최종 토큰 수(`input_tokens`)와 지우기가 발생하기 전의 원래 토큰 수(`original_input_tokens`)가 모두 표시됩니다.

## 메모리 도구와 함께 사용

컨텍스트 편집은 [메모리 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/memory-tool)와 결합할 수 있습니다. 대화 컨텍스트가 구성된 지우기 임계값에 가까워지면 Claude는 중요한 정보를 보존하라는 자동 경고를 받습니다. 이를 통해 Claude는 도구 결과나 컨텍스트가 대화 기록에서 지워지기 전에 메모리 파일에 저장할 수 있습니다.

이 조합을 통해 다음을 수행할 수 있습니다:

* **중요한 컨텍스트 보존:** Claude는 도구 결과가 지워지기 전에 해당 결과의 필수 정보를 메모리 파일에 기록할 수 있습니다
* **장기 실행 워크플로 유지:** 정보를 영구 저장소로 오프로드하여 그렇지 않으면 컨텍스트 한도를 초과할 에이전트 워크플로를 가능하게 합니다
* **필요 시 정보 접근:** Claude는 모든 것을 활성 컨텍스트 윈도우에 유지하는 대신, 필요할 때 이전에 지워진 정보를 메모리 파일에서 조회할 수 있습니다

예를 들어, Claude가 많은 작업을 수행하는 파일 편집 워크플로에서 Claude는 컨텍스트가 커짐에 따라 완료된 변경 사항을 메모리 파일에 요약할 수 있습니다. 도구 결과가 지워져도 Claude는 메모리 시스템을 통해 해당 정보에 계속 접근할 수 있으며 효과적으로 작업을 계속할 수 있습니다.

두 기능을 함께 사용하려면 API 요청에서 둘 다 활성화하세요:

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
      --header "x-api-key: $ANTHROPIC_API_KEY" \
      --header "anthropic-version: 2023-06-01" \
      --header "content-type: application/json" \
      --header "anthropic-beta: context-management-2025-06-27" \
      --data '{
          "model": "claude-opus-5-5",
          "max_tokens": 4096,
          "messages": [
              {
                  "role": "user",
                  "content": "Hello"
              }
          ],
          "tools": [
              {
                  "type": "memory_20250818",
                  "name": "memory"
              }
          ],
          "context_management": {
              "edits": [
                  {"type": "clear_tool_uses_20250919"}
              ]
          }
      }'
  ```

  ```bash CLI
  ant beta:messages create --beta context-management-2025-06-27 <<'YAML'
  model: claude-opus-5-5
  max_tokens: 4096
  messages:
    - role: user
      content: Hello
  tools:
    - type: memory_20250818
      name: memory
  context_management:
    edits:
      - type: clear_tool_uses_20250919
  YAML
  ```

  ```python Python
  response = client.beta.messages.create(
      model="claude-opus-5-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"}]},
  )
  ```

  ```typescript TypeScript
  const anthropic = new Anthropic({
    apiKey: process.env.ANTHROPIC_API_KEY
  });

  const response = await anthropic.beta.messages.create({
    model: "claude-opus-5-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" }]
    }
  });
  ```

  ```csharp C#
  using Anthropic;
  using Anthropic.Models.Beta;
  using Anthropic.Models.Beta.Messages;
  using Messages = Anthropic.Models.Messages;

  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Messages::Model.ClaudeOpus5_5,
      MaxTokens = 4096,
      Messages = [
          new() { Role = Role.User, Content = "Hello" }
      ],
      Tools = [
          new BetaMemoryTool20250818()
      ],
      Betas = [AnthropicBeta.ContextManagement2025_06_27],
      ContextManagement = new BetaContextManagementConfig
      {
          Edits = [new BetaClearToolUses20250919Edit()]
      }
  };

  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,
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello")),
  	},
  	Tools: []anthropic.BetaToolUnionParam{
  		{OfMemoryTool20250818: &anthropic.BetaMemoryTool20250818Param{}},
  	},
  	Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaContextManagement2025_06_27},
  	ContextManagement: anthropic.BetaContextManagementConfigParam{
  		Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
  			{OfClearToolUses20250919: &anthropic.BetaClearToolUses20250919EditParam{}},
  		},
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response)
  ```

  ```java Java
  import com.anthropic.models.beta.messages.BetaMemoryTool20250818;
  import com.anthropic.models.beta.messages.BetaContextManagementConfig;
  import com.anthropic.models.beta.messages.BetaClearToolUses20250919Edit;
  import com.anthropic.models.beta.AnthropicBeta;
  // ...
  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      MessageCreateParams params = MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(4096L)
          .addUserMessage("Hello")
          .addTool(BetaMemoryTool20250818.builder().build())
          .addBeta(AnthropicBeta.CONTEXT_MANAGEMENT_2025_06_27)
          .contextManagement(BetaContextManagementConfig.builder()
              .addEdit(BetaClearToolUses20250919Edit.builder().build())
              .build())
          .build();

      BetaMessage response = client.beta().messages().create(params);
      IO.println(response);
  }
  ```

  ```php PHP
  $client = new Client();

  $response = $client->beta->messages->create(
      maxTokens: 4096,
      messages: [
          ['role' => 'user', 'content' => 'Hello']
      ],
      model: 'claude-opus-5-5',
      betas: ['context-management-2025-06-27'],
      tools: [
          [
              'type' => 'memory_20250818',
              'name' => 'memory'
          ]
      ],
      contextManagement: [
          'edits' => [
              ['type' => 'clear_tool_uses_20250919']
          ]
      ],
  );

  echo $response;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  response = client.beta.messages.create(
    model: "claude-opus-5-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" }
      ]
    }
  )
  puts response
  ```
</CodeGroup>

명령 및 예시를 포함한 전체 메모리 도구 참조는 [메모리 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/memory-tool)를 참조하세요.

## 클라이언트 측 압축 (SDK)

<Warning>
  **Anthropic은 SDK 압축보다 서버 측 압축을 권장합니다.** [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction)은 통합 복잡성이 적고, 토큰 사용량 계산이 더 정확하며, 클라이언트 측 제한 없이 컨텍스트 관리를 자동으로 처리합니다. 요약 프로세스에 대한 클라이언트 측 제어가 특별히 필요한 경우에만 SDK 압축을 사용하세요.

  `compaction_control` 매개변수는 TypeScript 및 Ruby SDK에서 지원 중단되었으며 향후 버전에서 제거될 예정입니다. SDK는 이 매개변수가 활성화되면 지원 중단 경고를 표시합니다. Python SDK는 v1.0에서 이를 제거했습니다. 도구 러너와 함께 서버 측 압축을 사용하려면 요청의 `context_management` 매개변수에 `compact_20260112` 편집을 전달하세요.
</Warning>

<Note>
  압축은 [`tool_runner` 메서드](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-runner)를 사용할 때 [TypeScript 및 Ruby SDK](https://platform.claude.com/docs/ko/cli-sdks-libraries/overview)에서 사용할 수 있습니다.
</Note>

"Compaction"(압축)은 토큰 사용량이 너무 커지면 요약을 생성하여 대화 컨텍스트를 자동으로 관리하는 SDK 기능입니다. 콘텐츠를 지우는 서버 측 컨텍스트 편집 전략과 달리, 압축은 Claude에게 대화 기록을 요약하도록 지시한 다음 전체 기록을 해당 요약으로 대체합니다. 이를 통해 Claude는 그렇지 않으면 [컨텍스트 윈도우](https://platform.claude.com/docs/ko/build-with-claude/context-windows)를 초과할 장기 실행 작업을 계속할 수 있습니다.

### 압축 작동 방식

압축이 활성화되면 SDK는 각 모델 응답 후 토큰 사용량을 모니터링합니다:

1. **임계값 확인:** SDK는 총 토큰을 `input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens`로 계산합니다(캐시 토큰 필드에 대해서는 [프롬프트 캐싱](https://platform.claude.com/docs/ko/build-with-claude/prompt-caching)을 참조하세요).
2. **요약 생성:** 임계값이 초과되면 요약 프롬프트가 사용자 턴으로 주입되고, Claude는 `<summary></summary>` 태그로 감싼 구조화된 요약을 생성합니다.
3. **컨텍스트 대체:** SDK는 요약을 추출하고 전체 메시지 기록을 해당 요약으로 대체합니다.
4. **계속:** 대화는 요약에서 재개되며, Claude는 중단한 지점부터 이어서 작업합니다.

### 압축 사용

토큰 사용량이 임계값을 초과할 때 자동 요약을 활성화하려면 `tool_runner` 호출에 `compaction_control`을 추가하세요.

<Tabs>
  <Tab title="cURL">
    <Note>
      압축은 SDK `tool_runner` 헬퍼에서 클라이언트 측으로 실행되므로 직접적인 HTTP 대응 항목이 없습니다. 대신 Anthropic 서버에서 압축을 처리하는 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction)을 사용하세요.
    </Note>
  </Tab>

  <Tab title="CLI">
    <Note>
      CLI에는 `tool_runner` 헬퍼가 포함되어 있지 않습니다. 대신 SDK 측 통합 없이 Anthropic 서버에서 압축을 처리하는 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction)을 사용하세요.
    </Note>
  </Tab>

  <Tab title="Python">
    <Note>
      v1.0 이상에서 Python SDK의 도구 러너는 클라이언트 측 `compaction_control`을 지원하지 않습니다. 대신 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction-threshold)을 사용하세요. 요청의 `context_management` 매개변수에 `compact_20260112` 편집을 전달하면 도구 러너와 함께 작동합니다.
    </Note>
  </Tab>

  <Tab title="TypeScript">
    ```typescript TypeScript
    const client = new Anthropic();

    const runner = client.beta.messages.toolRunner({
      model: "claude-opus-5-5",
      max_tokens: 1024,
      tools: [readFile],
      messages: [{ role: "user", content: "What's in config.json?" }],
      compactionControl: { enabled: true, contextTokenThreshold: 100000 }
    });

    for await (const message of runner) {
      console.log(`Tokens used: ${message.usage.input_tokens}`);
    }
    ```
  </Tab>

  <Tab title="C#">
    <Note>
      C# SDK에는 도구 러너가 포함되어 있지만 클라이언트 측 `compaction_control`은 지원하지 않습니다. 대신 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction-threshold)을 사용하세요. 요청의 `context_management` 매개변수에 `compact_20260112` 편집을 전달하면 도구 러너와 함께 작동합니다.
    </Note>
  </Tab>

  <Tab title="Go">
    <Note>
      Go SDK에는 도구 러너가 포함되어 있지만 클라이언트 측 `compaction_control`은 지원하지 않습니다. 대신 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction-threshold)을 사용하세요. 요청의 `context_management` 매개변수에 `compact_20260112` 편집을 전달하면 도구 러너와 함께 작동합니다.
    </Note>
  </Tab>

  <Tab title="Java">
    <Note>
      Java SDK에는 도구 러너가 포함되어 있지만 클라이언트 측 `compaction_control`은 지원하지 않습니다. 대신 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction-threshold)을 사용하세요. 요청의 `context_management` 매개변수에 `compact_20260112` 편집을 전달하면 도구 러너와 함께 작동합니다.
    </Note>
  </Tab>

  <Tab title="PHP">
    <Note>
      PHP SDK에는 도구 러너가 포함되어 있지만 클라이언트 측 `compaction_control`은 지원하지 않습니다. 대신 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction-threshold)을 사용하세요. 요청의 `context_management` 매개변수에 `compact_20260112` 편집을 전달하면 도구 러너와 함께 작동합니다.
    </Note>
  </Tab>

  <Tab title="Ruby">
    ```ruby Ruby
    client = Anthropic::Client.new

    runner = client.beta.messages.tool_runner(
      model: "claude-opus-5-5",
      max_tokens: 1024,
      tools: [ReadFile.new],
      messages: [{ role: "user", content: "What's in config.json?" }],
      compaction_control: { enabled: true, context_token_threshold: 100000 }
    )

    runner.each_message do |message|
      puts "Tokens used: #{message.usage.input_tokens}"
    end
    ```
  </Tab>
</Tabs>

#### 압축 중에 일어나는 일

대화가 커짐에 따라 메시지 기록이 누적됩니다:

**압축 전(100k 토큰에 근접):**

```json
[
  { "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 ...
]
```

토큰이 임계값을 초과하면 SDK는 요약 요청을 주입하고 Claude는 요약을 생성합니다. 그런 다음 전체 기록이 대체됩니다:

**압축 후(약 2–3k 토큰으로 복귀):**

```json
[
  {
    "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..."
  }
]
```

Claude는 이 요약이 원래 대화 기록인 것처럼 이 요약에서 작업을 계속합니다.

### 구성 옵션

| 매개변수                      | 타입      | 필수  | 기본값                                                                                                           | 설명                    |
| ------------------------- | ------- | --- | ------------------------------------------------------------------------------------------------------------- | --------------------- |
| `enabled`                 | boolean | 예   | -                                                                                                             | 자동 압축 활성화 여부          |
| `context_token_threshold` | number  | 아니요 | 100,000                                                                                                       | 압축이 트리거되는 토큰 수        |
| `model`                   | string  | 아니요 | 기본 모델과 동일                                                                                                     | 요약 생성에 사용할 모델         |
| `summary_prompt`          | string  | 아니요 | [기본 요약 프롬프트](https://platform.claude.com/docs/ko/build-with-claude/context-editing#default-summary-prompt) 참조 | 요약 생성을 위한 사용자 지정 프롬프트 |

#### 토큰 임계값 선택

임계값은 압축이 발생하는 시점을 결정합니다. 임계값이 낮으면 더 작은 컨텍스트 윈도우로 더 자주 압축이 발생합니다. 임계값이 높으면 더 많은 컨텍스트를 허용하지만 한도에 도달할 위험이 있습니다.

<Tabs>
  <Tab title="cURL">
    <Note>
      압축은 SDK `tool_runner` 헬퍼에서 클라이언트 측으로 실행되므로 직접적인 HTTP 대응 항목이 없습니다. 대신 Anthropic 서버에서 압축을 처리하는 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction)을 사용하세요.
    </Note>
  </Tab>

  <Tab title="CLI">
    <Note>
      CLI에는 `tool_runner` 헬퍼가 포함되어 있지 않습니다. 대신 SDK 측 통합 없이 Anthropic 서버에서 압축을 처리하는 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction)을 사용하세요.
    </Note>
  </Tab>

  <Tab title="Python">
    <Note>
      v1.0 이상에서 Python SDK의 도구 러너는 클라이언트 측 `compaction_control`을 지원하지 않습니다. 대신 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction-threshold)을 사용하세요. 요청의 `context_management` 매개변수에 `compact_20260112` 편집을 전달하면 도구 러너와 함께 작동합니다.
    </Note>
  </Tab>

  <Tab title="TypeScript">
    ```typescript TypeScript
    const client = new Anthropic();

    const runner = client.beta.messages.toolRunner({
      model: "claude-opus-5-5",
      max_tokens: 1024,
      tools: [readFile],
      messages: [{ role: "user", content: "What's in config.json?" }],
      // 값이 낮을수록 더 자주 압축합니다. 작업에 더 많은 컨텍스트가 필요하면 150000으로 높이세요
      compactionControl: { enabled: true, contextTokenThreshold: 50000 }
    });

    for await (const message of runner) {
      console.log(`Tokens used: ${message.usage.input_tokens}`);
    }
    ```
  </Tab>

  <Tab title="C#">
    <Note>
      C# SDK에는 tool runner가 포함되어 있지만 클라이언트 측 `compaction_control`은 지원하지 않습니다. 대신 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction-threshold)을 사용하세요. 요청의 `context_management` 매개변수에 `compact_20260112` 편집을 전달하면 tool runner와 함께 작동합니다.
    </Note>
  </Tab>

  <Tab title="Go">
    <Note>
      Go SDK에는 tool runner가 포함되어 있지만 클라이언트 측 `compaction_control`은 지원하지 않습니다. 대신 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction-threshold)을 사용하세요. 요청의 `context_management` 매개변수에 `compact_20260112` 편집을 전달하면 tool runner와 함께 작동합니다.
    </Note>
  </Tab>

  <Tab title="Java">
    <Note>
      Java SDK에는 tool runner가 포함되어 있지만 클라이언트 측 `compaction_control`은 지원하지 않습니다. 대신 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction-threshold)을 사용하세요. 요청의 `context_management` 매개변수에 `compact_20260112` 편집을 전달하면 tool runner와 함께 작동합니다.
    </Note>
  </Tab>

  <Tab title="PHP">
    <Note>
      PHP SDK에는 tool runner가 포함되어 있지만 클라이언트 측 `compaction_control`은 지원하지 않습니다. 대신 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction-threshold)을 사용하세요. 요청의 `context_management` 매개변수에 `compact_20260112` 편집을 전달하면 tool runner와 함께 작동합니다.
    </Note>
  </Tab>

  <Tab title="Ruby">
    ```ruby Ruby
    client = Anthropic::Client.new

    runner = client.beta.messages.tool_runner(
      model: "claude-opus-5-5",
      max_tokens: 1024,
      tools: [ReadFile.new],
      messages: [{ role: "user", content: "What's in config.json?" }],
      # 값이 낮을수록 더 자주 압축합니다. 작업에 더 많은 컨텍스트가 필요하면 150000으로 높이세요
      compaction_control: { enabled: true, context_token_threshold: 50000 }
    )

    runner.each_message do |message|
      puts "Tokens used: #{message.usage.input_tokens}"
    end
    ```
  </Tab>
</Tabs>

#### 요약에 다른 모델 사용

요약 생성에 더 빠르거나 저렴한 모델을 사용할 수 있습니다:

<Tabs>
  <Tab title="cURL">
    <Note>
      압축은 SDK `tool_runner` 헬퍼에서 클라이언트 측으로 실행되므로 직접적인 HTTP 대응 항목이 없습니다. 대신 Anthropic 서버에서 압축을 처리하는 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction)을 사용하세요.
    </Note>
  </Tab>

  <Tab title="CLI">
    <Note>
      CLI에는 `tool_runner` 헬퍼가 포함되어 있지 않습니다. 대신 SDK 측 통합 없이 Anthropic 서버에서 압축을 처리하는 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction)을 사용하세요.
    </Note>
  </Tab>

  <Tab title="Python">
    <Note>
      v1.0 이상에서 Python SDK의 도구 러너는 클라이언트 측 `compaction_control`을 지원하지 않습니다. 대신 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction-threshold)을 사용하세요. 요청의 `context_management` 매개변수에 `compact_20260112` 편집을 전달하면 도구 러너와 함께 작동합니다.
    </Note>
  </Tab>

  <Tab title="TypeScript">
    ```typescript TypeScript
    const client = new Anthropic();

    const runner = client.beta.messages.toolRunner({
      model: "claude-opus-5-5",
      max_tokens: 1024,
      tools: [readFile],
      messages: [{ role: "user", content: "What's in config.json?" }],
      compactionControl: {
        enabled: true,
        contextTokenThreshold: 100000,
        model: "claude-haiku-4-5"
      }
    });

    for await (const message of runner) {
      console.log(`Tokens used: ${message.usage.input_tokens}`);
    }
    ```
  </Tab>

  <Tab title="C#">
    <Note>
      C# SDK에는 tool runner가 포함되어 있지만 클라이언트 측 `compaction_control`은 지원하지 않습니다. 대신 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction-threshold)을 사용하세요. 요청의 `context_management` 매개변수에 `compact_20260112` 편집을 전달하면 tool runner와 함께 작동합니다.
    </Note>
  </Tab>

  <Tab title="Go">
    <Note>
      Go SDK에는 tool runner가 포함되어 있지만 클라이언트 측 `compaction_control`은 지원하지 않습니다. 대신 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction-threshold)을 사용하세요. 요청의 `context_management` 매개변수에 `compact_20260112` 편집을 전달하면 tool runner와 함께 작동합니다.
    </Note>
  </Tab>

  <Tab title="Java">
    <Note>
      Java SDK에는 tool runner가 포함되어 있지만 클라이언트 측 `compaction_control`은 지원하지 않습니다. 대신 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction-threshold)을 사용하세요. 요청의 `context_management` 매개변수에 `compact_20260112` 편집을 전달하면 tool runner와 함께 작동합니다.
    </Note>
  </Tab>

  <Tab title="PHP">
    <Note>
      PHP SDK에는 tool runner가 포함되어 있지만 클라이언트 측 `compaction_control`은 지원하지 않습니다. 대신 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction-threshold)을 사용하세요. 요청의 `context_management` 매개변수에 `compact_20260112` 편집을 전달하면 tool runner와 함께 작동합니다.
    </Note>
  </Tab>

  <Tab title="Ruby">
    ```ruby Ruby
    client = Anthropic::Client.new

    runner = client.beta.messages.tool_runner(
      model: "claude-opus-5-5",
      max_tokens: 1024,
      tools: [ReadFile.new],
      messages: [{ role: "user", content: "What's in config.json?" }],
      compaction_control: {
        enabled: true,
        context_token_threshold: 100000,
        model: "claude-haiku-4-5"
      }
    )

    runner.each_message do |message|
      puts "Tokens used: #{message.usage.input_tokens}"
    end
    ```
  </Tab>
</Tabs>

#### 사용자 지정 요약 프롬프트

도메인별 요구 사항에 맞는 사용자 지정 프롬프트를 제공할 수 있습니다. 프롬프트는 Claude에게 요약을 `<summary></summary>` 태그로 감싸도록 지시해야 합니다.

<Tabs>
  <Tab title="cURL">
    <Note>
      압축은 SDK `tool_runner` 헬퍼에서 클라이언트 측으로 실행되므로 직접적인 HTTP 대응 항목이 없습니다. 대신 Anthropic 서버에서 압축을 처리하는 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction)을 사용하세요.
    </Note>
  </Tab>

  <Tab title="CLI">
    <Note>
      CLI에는 `tool_runner` 헬퍼가 포함되어 있지 않습니다. 대신 SDK 측 통합 없이 Anthropic 서버에서 압축을 처리하는 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction)을 사용하세요.
    </Note>
  </Tab>

  <Tab title="Python">
    <Note>
      v1.0 이상에서 Python SDK의 도구 러너는 클라이언트 측 `compaction_control`을 지원하지 않습니다. 대신 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction-threshold)을 사용하세요. 요청의 `context_management` 매개변수에 `compact_20260112` 편집을 전달하면 도구 러너와 함께 작동합니다.
    </Note>
  </Tab>

  <Tab title="TypeScript">
    ```typescript TypeScript
    const client = new Anthropic();

    const runner = client.beta.messages.toolRunner({
      model: "claude-opus-5-5",
      max_tokens: 1024,
      tools: [readFile],
      messages: [{ role: "user", content: "What's in config.json?" }],
      compactionControl: {
        enabled: true,
        contextTokenThreshold: 100000,
        summaryPrompt: `Summarize the research conducted so far, including:
    - Sources consulted and key findings
    - Questions answered and remaining unknowns
    - Recommended next steps

    Wrap your summary in <summary></summary> tags.`
      }
    });

    for await (const message of runner) {
      console.log(`Tokens used: ${message.usage.input_tokens}`);
    }
    ```
  </Tab>

  <Tab title="C#">
    <Note>
      C# SDK에는 tool runner가 포함되어 있지만 클라이언트 측 `compaction_control`은 지원하지 않습니다. 대신 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction-threshold)을 사용하세요. 요청의 `context_management` 매개변수에 `compact_20260112` 편집을 전달하면 tool runner와 함께 작동합니다.
    </Note>
  </Tab>

  <Tab title="Go">
    <Note>
      Go SDK에는 tool runner가 포함되어 있지만 클라이언트 측 `compaction_control`은 지원하지 않습니다. 대신 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction-threshold)을 사용하세요. 요청의 `context_management` 매개변수에 `compact_20260112` 편집을 전달하면 tool runner와 함께 작동합니다.
    </Note>
  </Tab>

  <Tab title="Java">
    <Note>
      Java SDK에는 tool runner가 포함되어 있지만 클라이언트 측 `compaction_control`은 지원하지 않습니다. 대신 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction-threshold)을 사용하세요. 요청의 `context_management` 매개변수에 `compact_20260112` 편집을 전달하면 tool runner와 함께 작동합니다.
    </Note>
  </Tab>

  <Tab title="PHP">
    <Note>
      PHP SDK에는 tool runner가 포함되어 있지만 클라이언트 측 `compaction_control`은 지원하지 않습니다. 대신 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction-threshold)을 사용하세요. 요청의 `context_management` 매개변수에 `compact_20260112` 편집을 전달하면 tool runner와 함께 작동합니다.
    </Note>
  </Tab>

  <Tab title="Ruby">
    ```ruby Ruby
    client = Anthropic::Client.new

    runner = client.beta.messages.tool_runner(
      model: "claude-opus-5-5",
      max_tokens: 1024,
      tools: [ReadFile.new],
      messages: [{ role: "user", content: "What's in config.json?" }],
      compaction_control: {
        enabled: true,
        context_token_threshold: 100000,
        summary_prompt: <<~PROMPT
          Summarize the research conducted so far, including:
          - Sources consulted and key findings
          - Questions answered and remaining unknowns
          - Recommended next steps

          Wrap your summary in <summary></summary> tags.
        PROMPT
      }
    )

    runner.each_message do |message|
      puts "Tokens used: #{message.usage.input_tokens}"
    end
    ```
  </Tab>
</Tabs>

### 기본 요약 프롬프트

내장 요약 프롬프트는 Claude에게 다음을 포함하는 구조화된 연속 요약을 작성하도록 지시합니다:

1. **작업 개요:** 사용자의 핵심 요청, 성공 기준 및 제약 조건.
2. **현재 상태:** 완료된 작업, 수정된 파일 및 생성된 아티팩트.
3. **중요한 발견:** 기술적 제약, 내린 결정, 해결된 오류 및 실패한 접근 방식.
4. **다음 단계:** 필요한 구체적인 조치, 차단 요소 및 우선순위.
5. **보존할 컨텍스트:** 사용자 선호도, 도메인별 세부 사항 및 약속한 사항.

이 구조를 통해 Claude는 중요한 컨텍스트를 잃거나 실수를 반복하지 않고 효율적으로 작업을 재개할 수 있습니다.

<Accordion title="전체 기본 프롬프트 보기">
  ```text wrap
  You have been working on the task described above but have not yet completed it. Write a continuation summary that will allow you (or another instance of yourself) to resume work efficiently in a future context window where the conversation history will be replaced with this summary. Your summary should be structured, concise, and actionable. Include:

  1. Task Overview
  The user's core request and success criteria
  Any clarifications or constraints they specified

  2. Current State
  What has been completed so far
  Files created, modified, or analyzed (with paths if relevant)
  Key outputs or artifacts produced

  3. Important Discoveries
  Technical constraints or requirements uncovered
  Decisions made and their rationale
  Errors encountered and how they were resolved
  What approaches were tried that didn't work (and why)

  4. Next Steps
  Specific actions needed to complete the task
  Any blockers or open questions to resolve
  Priority order if multiple steps remain

  5. Context to Preserve
  User preferences or style requirements
  Domain-specific details that aren't obvious
  Any promises made to the user

  Be concise but complete—err on the side of including information that would prevent duplicate work or repeated mistakes. Write in a way that enables immediate resumption of the task.

  Wrap your summary in <summary></summary> tags.
  ```
</Accordion>

### 제한 사항

#### 서버 측 도구

<Warning>
  [웹 검색](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-search-tool) 또는 [웹 가져오기](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-fetch-tool)와 같은 서버 측 도구를 사용할 때는 압축에 특별한 고려가 필요합니다.
</Warning>

서버 측 도구를 사용할 때 SDK가 토큰 사용량을 잘못 계산하여 압축이 잘못된 시점에 트리거될 수 있습니다.

예를 들어, 웹 검색 작업 후 API 응답은 다음과 같이 표시될 수 있습니다:

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

SDK는 총 사용량을 63,000 + 0 + 270,000 + 1,400 = 334,400 토큰으로 계산합니다. 그러나 `cache_read_input_tokens` 값에는 실제 대화 컨텍스트가 아니라 서버 측 도구가 수행한 여러 내부 API 호출에서 누적된 읽기가 포함됩니다. 실제 컨텍스트 길이는 63,000 `input_tokens`에 불과할 수 있지만, SDK는 334k로 인식하여 압축을 조기에 트리거합니다.

**해결 방법:**

* [토큰 카운팅](https://platform.claude.com/docs/ko/build-with-claude/token-counting) 엔드포인트를 사용하여 정확한 컨텍스트 길이를 얻으세요
* 서버 측 도구를 광범위하게 사용할 때는 압축을 피하세요

#### 도구 사용 엣지 케이스

도구 사용 응답이 대기 중인 상태에서 SDK가 압축을 트리거하면, 요약을 생성하기 전에 메시지 기록에서 도구 사용 블록을 제거합니다. Claude는 요약에서 재개한 후 여전히 필요한 경우 도구 호출을 다시 발행합니다.

### 압축 모니터링

압축이 언제 트리거되는지 이해하면 임계값을 조정하고 예상 동작을 확인하는 데 도움이 됩니다.

<Tabs>
  <Tab title="cURL">
    <Note>
      압축은 SDK `tool_runner` 헬퍼에서 클라이언트 측으로 실행되므로 직접적인 HTTP 대응 항목이 없습니다. 대신 Anthropic 서버에서 압축을 처리하는 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction)을 사용하세요.
    </Note>
  </Tab>

  <Tab title="CLI">
    <Note>
      CLI에는 `tool_runner` 헬퍼가 포함되어 있지 않습니다. 대신 SDK 측 통합 없이 Anthropic 서버에서 압축을 처리하는 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction)을 사용하세요.
    </Note>
  </Tab>

  <Tab title="Python">
    <Note>
      v1.0 이상에서 Python SDK의 도구 러너는 `compaction_control`을 지원하지 않습니다. 대신 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction)을 사용하세요.
    </Note>
  </Tab>

  <Tab title="TypeScript">
    TypeScript SDK의 `toolRunner`는 압축을 지원하지만 이벤트를 로깅하지 않습니다. 턴 사이에 `runner.params.messages.length`가 줄어드는 것을 관찰하여 압축을 감지하세요:

    ```typescript TypeScript
    let prevMsgCount = 0;
    for await (const message of runner) {
      const currMsgCount = runner.params.messages.length;
      if (currMsgCount < prevMsgCount) {
        console.log(`Compaction occurred: ${prevMsgCount} -> ${currMsgCount} messages`);
        console.log(`Input tokens after compaction: ${message.usage.input_tokens}`);
      }
      prevMsgCount = currMsgCount;
    }
    ```
  </Tab>

  <Tab title="C#">
    <Note>
      C# SDK의 도구 러너는 `compaction_control`을 지원하지 않습니다. 대신 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction)을 사용하세요.
    </Note>
  </Tab>

  <Tab title="Go">
    <Note>
      Go SDK의 도구 러너는 `compaction_control`을 지원하지 않습니다. 대신 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction)을 사용하세요.
    </Note>
  </Tab>

  <Tab title="Java">
    <Note>
      Java SDK의 도구 러너는 `compaction_control`을 지원하지 않습니다. 대신 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction)을 사용하세요.
    </Note>
  </Tab>

  <Tab title="PHP">
    <Note>
      PHP SDK의 도구 러너는 `compaction_control`을 지원하지 않습니다. 대신 [서버 측 압축](https://platform.claude.com/docs/ko/build-with-claude/compaction)을 사용하세요.
    </Note>
  </Tab>

  <Tab title="Ruby">
    Ruby SDK는 압축이 발생할 때 실행되는 `on_compact:` 콜백을 지원합니다. `compaction_control` 구성에 추가하세요:

    ```ruby Ruby
    client = Anthropic::Client.new

    runner = client.beta.messages.tool_runner(
      model: "claude-opus-5-5",
      max_tokens: 1024,
      tools: [ReadFile.new],
      messages: [{ role: "user", content: "What's in config.json?" }],
      compaction_control: {
        enabled: true,
        context_token_threshold: 100000,
        on_compact: ->(tokens_before, tokens_after) do
          puts "Compaction occurred: #{tokens_before} -> #{tokens_after} tokens"
        end
      }
    )

    runner.each_message do |message|
      puts "Tokens: #{message.usage.input_tokens}"
    end
    ```
  </Tab>
</Tabs>

### 압축을 사용해야 하는 경우

**적합한 사용 사례:**

* 많은 파일이나 데이터 소스를 처리하는 장기 실행 에이전트 작업
* 대량의 정보를 축적하는 리서치 워크플로
* 명확하고 측정 가능한 진행 상황이 있는 다단계 작업
* 대화 외부에 지속되는 아티팩트(파일, 보고서)를 생성하는 작업

**덜 이상적인 사용 사례:**

* 초기 대화 세부 사항의 정확한 기억이 필요한 작업
* 서버 측 도구를 광범위하게 사용하는 워크플로
* 많은 변수에 걸쳐 정확한 상태를 유지해야 하는 작업

## 다음 단계

<CardGroup cols={2}>
  <Card title="압축" icon="arrows-clockwise" href="https://platform.claude.com/docs/ko/build-with-claude/compaction">
    대부분의 사용 사례에 권장되는 전략인 서버 측 압축으로 긴 대화를 관리하세요.
  </Card>

  <Card title="프롬프트 캐싱" icon="database" href="https://platform.claude.com/docs/ko/build-with-claude/prompt-caching">
    프롬프트 접두사를 캐싱하여 비용과 지연 시간을 줄이고, 컨텍스트 편집이 캐시와 어떻게 상호작용하는지 알아보세요.
  </Card>
</CardGroup>