---
title: Claude Sonnet 5.5 마이그레이션 가이드
url: https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide
description: 이 마이그레이션 가이드를 통해 이전 Sonnet 모델 또는 Claude Haiku 4.5에서 Claude Sonnet 5.5로 전환하세요. Claude Sonnet 5.5를 활성화하기 위한 안내에는 오류를 반환하는 설정, 사고 관련 변경 사항, 시작 모델별 체크리스트가 포함되어 있습니다.
---

이 가이드는 Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Sonnet 4, Claude 3.7 Sonnet 또는 Claude Haiku 4.5에서 Claude Sonnet 5.5로 이전할 때 필요한 코드 변경 사항을 나열합니다. 처음 두 섹션을 읽은 다음, 현재 사용 중인 모델에 해당하는 섹션까지 읽어 내려가세요. [마이그레이션 체크리스트](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#migration-checklist)에는 시작 모델별로 모든 변경 사항이 나열되어 있습니다.

<Note>
  이 가이드는 [Messages API](https://platform.claude.com/docs/ko/build-with-claude/working-with-messages) 코드 마이그레이션을 다룹니다. [Claude Managed Agents](https://platform.claude.com/docs/ko/managed-agents/overview)를 사용하는 경우, 모델 이름을 업데이트하는 것 외에는 변경이 필요하지 않습니다.
</Note>

<Tip>
  **Claude API 스킬로 마이그레이션을 자동화하세요.** Claude Code에서 `/claude-api migrate`를 실행하여 번들로 제공되는 [Claude API 스킬](https://platform.claude.com/docs/ko/agents-and-tools/agent-skills/claude-api-skill#migrating-to-a-newer-claude-model)을 호출하세요. 현재 제공되는 모든 Claude 모델을 대상으로 사용할 수 있습니다:

  Claude Code가 코드를 대신 마이그레이션하도록 하세요

  ```text
  /claude-api migrate 이 프로젝트를 claude-sonnet-5-5 모델로 마이그레이션해 줘
  ```

  이 스킬은 코드베이스 전반에 걸쳐 모델 ID 교체를 적용하고, 필요에 따라 호환성이 깨지는 매개변수 변경, 프리필(prefill) 대체, 대상 모델에 맞춘 effort 보정을 수행한 다음, 수동으로 확인해야 할 항목의 체크리스트를 생성합니다. 파일을 편집하기 전에 마이그레이션 범위(전체 작업 디렉터리, 하위 디렉터리 또는 특정 파일 목록)를 확인하도록 요청합니다. 또한 이 스킬은 Amazon Bedrock 및 Claude Platform on AWS 클라이언트를 감지하여 해당 플랫폼에 맞게 모델 ID 형식과 기능 변경 사항을 조정합니다.
</Tip>

Claude Sonnet 5.5의 가격은 Claude Sonnet 5와 동일하지만, 프롬프트 캐시 읽기는 예외로 백만 토큰당 $0.10 USD이며 이는 Claude Sonnet 5 요금의 절반입니다. [Claude 가격](https://platform.claude.com/docs/ko/about-claude/pricing)을 참조하세요. "Context window"(컨텍스트 윈도우)와 출력 한도는 [Claude Sonnet 5.5 모델 페이지](https://platform.claude.com/docs/ko/models/sonnet-5-5/overview)를 참조하세요. 기능과 프롬프팅에 대해서는 [Claude Sonnet 5.5의 새로운 기능](https://platform.claude.com/docs/ko/models/sonnet-5-5/whats-new-sonnet-5-5#feature-support) 및 [Claude Sonnet 5.5 프롬프팅](https://platform.claude.com/docs/ko/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5)을 참조하세요.

## Claude Sonnet 5.5에 요청 보내기

이 요청은 작성된 그대로 Claude Sonnet 5.5에서 작동합니다. 이 요청은 effort 수준을 설정하며, SDK 탭은 블록 유형별로 응답을 읽습니다. 400 오류를 반환하는 다섯 가지 설정은 제외되어 있습니다: [사고 예산](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#sonnet-46-breaking-changes), [샘플링 매개변수](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#sonnet-46-breaking-changes), [어시스턴트 prefill](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#migrating-from-sonnet-45), [강제 도구 선택](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#forced-tool-use), 그리고 [`thinking: {"type": "disabled"}`](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#turn-off-up-front-thinking)입니다.

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-sonnet-5-5",
      "max_tokens": 4096,
      "messages": [{
        "role": "user",
        "content": "Analyze the trade-offs between microservices and monolithic architectures"
      }],
      "output_config": {
        "effort": "medium"
      }
    }'
  ```

  ```bash CLI
  ant messages create \
    --model claude-sonnet-5-5 \
    --max-tokens 4096 \
    --output-config '{effort: medium}' \
    --message '{role: user, content: "Analyze the trade-offs between microservices and monolithic architectures"}'
  ```

  ```python Python
  client = anthropic.Anthropic()

  response = client.messages.create(
      model="claude-sonnet-5-5",
      max_tokens=4096,
      messages=[
          {
              "role": "user",
              "content": "Analyze the trade-offs between microservices and monolithic architectures",
          }
      ],
      output_config={"effort": "medium"},
  )

  print(f"Stop reason: {response.stop_reason}")
  for block in response.content:
      if block.type == "text":
          print(block.text)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const response = await client.messages.create({
    model: "claude-sonnet-5-5",
    max_tokens: 4096,
    messages: [
      {
        role: "user",
        content: "Analyze the trade-offs between microservices and monolithic architectures"
      }
    ],
    output_config: {
      effort: "medium"
    }
  });

  console.log(`Stop reason: ${response.stop_reason}`);
  const textBlock = response.content.find(
    (block): block is Anthropic.TextBlock => block.type === "text"
  );
  console.log(textBlock?.text);
  ```

  ```csharp C#
  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeSonnet5_5,
      MaxTokens = 4096,
      Messages = [
          new() {
              Role = Role.User,
              Content = "Analyze the trade-offs between microservices and monolithic architectures"
          }
      ],
      OutputConfig = new OutputConfig
      {
          Effort = Effort.Medium
      }
  };

  var message = await client.Messages.Create(parameters);
  Console.WriteLine($"Stop reason: {message.StopReason?.Raw()}");
  foreach (var block in message.Content)
  {
      if (block.TryPickText(out var textBlock))
      {
          Console.WriteLine(textBlock.Text);
      }
  }
  ```

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

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeSonnet5_5,
  	MaxTokens: 4096,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the trade-offs between microservices and monolithic architectures")),
  	},
  	OutputConfig: anthropic.OutputConfigParam{
  		Effort: anthropic.OutputConfigEffortMedium,
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println("Stop reason:", response.StopReason)
  for _, block := range response.Content {
  	if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
  		fmt.Println(textBlock.Text)
  	}
  }
  ```

  ```java Java
  import com.anthropic.models.messages.OutputConfig;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      MessageCreateParams params = MessageCreateParams.builder()
          .model(Model.CLAUDE_SONNET_5_5)
          .maxTokens(4096L)
          .addUserMessage("Analyze the trade-offs between microservices and monolithic architectures")
          .outputConfig(OutputConfig.builder()
              .effort(OutputConfig.Effort.MEDIUM)
              .build())
          .build();

      Message response = client.messages().create(params);
      response.stopReason().ifPresent(reason -> IO.println("Stop reason: " + reason));
      response.content().stream()
          .flatMap(block -> block.text().stream())
          .forEach(textBlock -> IO.println(textBlock.text()));
  }
  ```

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

  $message = $client->messages->create(
      maxTokens: 4096,
      messages: [
          ['role' => 'user', 'content' => 'Analyze the trade-offs between microservices and monolithic architectures']
      ],
      model: 'claude-sonnet-5-5',
      outputConfig: ['effort' => 'medium'],
  );

  echo "Stop reason: {$message->stopReason}", PHP_EOL;
  foreach ($message->content as $block) {
      if ($block->type === 'text') {
          echo $block->text, PHP_EOL;
      }
  }
  ```

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

  message = client.messages.create(
    model: "claude-sonnet-5-5",
    max_tokens: 4096,
    messages: [
      { role: "user", content: "Analyze the trade-offs between microservices and monolithic architectures" }
    ],
    output_config: {
      effort: "medium"
    }
  )

  puts "Stop reason: #{message.stop_reason}"
  message.content.each do |block|
    puts block.text if block.type == :text
  end
  ```
</CodeGroup>

## 기본적으로 사고가 실행됩니다

Claude Sonnet 5.5에서는 `thinking` 필드가 없는 요청도 `thinking: {"type": "adaptive"}`를 보낸 요청과 마찬가지로 ["adaptive thinking"(적응형 사고)](https://platform.claude.com/docs/ko/build-with-claude/thinking)으로 실행됩니다. Claude Sonnet 4.6 및 이전 모델과 Claude Haiku 4.5에서는 같은 요청이 사고 없이 실행되었습니다. "up-front thinking"(사전 사고) 없이 계속 실행하려면 [사전 사고 끄기](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#turn-off-up-front-thinking)를 참조하세요.

| 모델                                   | `thinking` 필드가 없을 때의 사고 | 허용되는 `thinking.type` 값                          | 기본 `display`   |
| ------------------------------------ | ----------------------- | ----------------------------------------------- | -------------- |
| Claude Sonnet 5.5                    | 켜짐                      | `"adaptive"`, `"between_tools"`                 | `"omitted"`    |
| Claude Sonnet 5                      | 켜짐                      | `"adaptive"`, `"disabled"`                      | `"omitted"`    |
| Claude Sonnet 4.6                    | 꺼짐                      | `"adaptive"`, `"disabled"`, `"enabled"` (지원 중단) | `"summarized"` |
| Claude Sonnet 4.5 및 Claude Haiku 4.5 | 꺼짐                      | `"disabled"`, `"enabled"`                       | `"summarized"` |

### 응답에서 사고 처리하기

사고 없이 실행되던 코드는 아래 세 항목을 모두 적용해야 합니다. Claude Sonnet 5용 코드에는 처음 두 항목이 이미 반영되어 있을 가능성이 높습니다.

* **콘텐츠 블록을 `type`으로 구분해 읽으세요.** 응답이 `thinking` 블록으로 시작할 수 있으므로, `content[0].text`를 읽는 코드는 제대로 작동하지 않습니다.
* 도구 사용 루프에서는 빈 블록을 포함해 **`thinking` 블록을 변경하지 말고 그대로 다시 전달하세요**. [사고 블록 보존](https://platform.claude.com/docs/ko/build-with-claude/thinking#preserving-thinking-blocks)을 참조하세요.
* **`max_tokens`를 다시 검토하세요.** 이 값에는 사고와 텍스트가 모두 포함되며, 사고 토큰은 출력 토큰으로 청구됩니다. [비용 제어](https://platform.claude.com/docs/ko/build-with-claude/thinking-steering-and-cost#cost-control)를 참조하세요.

사고 텍스트는 기본적으로 생략됩니다. `thinking` 블록은 빈 `thinking` 필드와 `signature`만 담아 반환됩니다. 읽을 수 있는 요약을 받으려면 `display: "summarized"`를 설정하세요. 이 값은 Claude Sonnet 4.6 및 이전 모델과 Claude Haiku 4.5의 기본값입니다. [사고 표시 제어](https://platform.claude.com/docs/ko/build-with-claude/thinking#controlling-thinking-display)를 참조하세요.

### 사전 사고 끄기

Claude Sonnet 5.5에서 사전 사고를 끄려면 `thinking: {"type": "between_tools"}`를 보내세요. 이는 가장 낮은 사고 설정입니다. 도구 호출 사이의 진행 상황 업데이트는 여전히 요약 텍스트와 함께 `thinking` 블록으로 반환됩니다. 도구가 없으면 응답에는 텍스트만 포함됩니다. Claude Sonnet 5는 대신 `thinking: {"type": "disabled"}`로 사고를 끄며, 이전 모델은 기본적으로 사고 없이 실행됩니다. Claude Sonnet 5.5에서 `disabled`는 400 `invalid_request_error`를 반환합니다:

```text wrap
To turn thinking off on this model, send "thinking": {"type": "between_tools"} instead of {"type": "disabled"}. The model does not think before responding. The short updates it writes between tool calls come back as thinking blocks.
```

`between_tools`는 Claude Sonnet 5.5를 제공하는 모든 플랫폼에서 베타 헤더 없이 작동합니다. `low`, `medium`, `high` effort에서 허용됩니다. `xhigh` 또는 `max`에서는 400 오류를 반환합니다. 해당 수준에서 실행하려면 적응형 사고를 사용하세요: `thinking` 필드를 생략하거나 `thinking: {"type": "adaptive"}`를 보내면 됩니다. `between_tools`는 다른 필드를 받지 않습니다: 함께 보낸 `display`, `budget_tokens` 또는 `block_binding`은 400 오류를 반환합니다. [서버 측 폴백](https://platform.claude.com/docs/ko/build-with-claude/refusals-and-fallback#server-side-fallback)을 사용하면, Claude Sonnet 5로 폴백되는 `between_tools` 요청은 그곳에서 `thinking: {"type": "disabled"}`로 실행됩니다.

`between_tools`를 사용하면 대화 도중에 effort를 변경할 수 없습니다: 현재 적용 중인 수준과 다른 메시지별 `output_config.effort`는 400 오류를 반환합니다. 턴마다 effort를 다르게 하려면 적응형 사고를 사용하세요. 프롬프팅 안내는 [사전 사고 없이 실행하기](https://platform.claude.com/docs/ko/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#running-without-up-front-thinking)를 참조하세요.

이전 (Claude Sonnet 5):

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-sonnet-5",
      "max_tokens": 16000,
      "thinking": {"type": "disabled"},
      "output_config": {"effort": "xhigh"},
      "messages": [{"role": "user", "content": "..."}]
    }'
  ```

  ```bash CLI
  ant messages create \
    --model claude-sonnet-5 \
    --max-tokens 16000 \
    --thinking '{type: disabled}' \
    --output-config '{effort: xhigh}' \
    --message '{role: user, content: "..."}'
  ```

  ```python Python
  client.messages.create(
      model="claude-sonnet-5",
      max_tokens=16000,
      thinking={"type": "disabled"},
      output_config={"effort": "xhigh"},
      messages=[{"role": "user", "content": "..."}],
  )
  ```

  ```typescript TypeScript
  await client.messages.create({
    model: "claude-sonnet-5",
    max_tokens: 16000,
    thinking: { type: "disabled" },
    output_config: { effort: "xhigh" },
    messages: [{ role: "user", content: "..." }]
  });
  ```

  ```csharp C#
  await client.Messages.Create(new MessageCreateParams
  {
      Model = Model.ClaudeSonnet5,
      MaxTokens = 16000,
      Thinking = new ThinkingConfigDisabled(),
      OutputConfig = new() { Effort = Effort.Xhigh },
      Messages = [new() { Role = Role.User, Content = "..." }],
  });
  ```

  ```go Go
  client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeSonnet5,
  	MaxTokens: 16000,
  	Thinking: anthropic.ThinkingConfigParamUnion{
  		OfDisabled: &anthropic.ThinkingConfigDisabledParam{},
  	},
  	OutputConfig: anthropic.OutputConfigParam{
  		Effort: anthropic.OutputConfigEffortXhigh,
  	},
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
  	},
  })
  ```

  ```java Java
  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_SONNET_5)
      .maxTokens(16000L)
      .thinking(ThinkingConfigDisabled.builder().build())
      .outputConfig(OutputConfig.builder()
          .effort(OutputConfig.Effort.XHIGH)
          .build())
      .addUserMessage("...")
      .build();

  client.messages().create(params);
  ```

  ```php PHP
  $client->messages->create(
      model: Model::CLAUDE_SONNET_5,
      maxTokens: 16000,
      thinking: ThinkingConfigDisabled::with(),
      outputConfig: OutputConfig::with(effort: Effort::XHIGH),
      messages: [['role' => 'user', 'content' => '...']],
  );
  ```

  ```ruby Ruby
  client.messages.create(
    model: Anthropic::Model::CLAUDE_SONNET_5,
    max_tokens: 16000,
    thinking: Anthropic::ThinkingConfigDisabled.new,
    output_config: { effort: Anthropic::OutputConfig::Effort::XHIGH },
    messages: [{ role: "user", content: "..." }]
  )
  ```
</CodeGroup>

이후 (Claude Sonnet 5.5):

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-sonnet-5-5",
      "max_tokens": 16000,
      "thinking": {"type": "between_tools"},
      "output_config": {"effort": "high"},
      "messages": [{"role": "user", "content": "..."}]
    }'
  ```

  ```bash CLI
  ant messages create \
    --model claude-sonnet-5-5 \
    --max-tokens 16000 \
    --thinking '{type: between_tools}' \
    --output-config '{effort: high}' \
    --message '{role: user, content: "..."}'
  ```

  ```python Python
  client.messages.create(
      model="claude-sonnet-5-5",
      max_tokens=16000,
      thinking={"type": "between_tools"},
      output_config={"effort": "high"},
      messages=[{"role": "user", "content": "..."}],
  )
  ```

  ```typescript TypeScript
  await client.messages.create({
    model: "claude-sonnet-5-5",
    max_tokens: 16000,
    thinking: { type: "between_tools" },
    output_config: { effort: "high" },
    messages: [{ role: "user", content: "..." }]
  });
  ```

  ```csharp C#
  await client.Messages.Create(new MessageCreateParams
  {
      Model = Model.ClaudeSonnet5_5,
      MaxTokens = 16000,
      Thinking = new ThinkingConfigBetweenTools(),
      OutputConfig = new() { Effort = Effort.High },
      Messages = [new() { Role = Role.User, Content = "..." }],
  });
  ```

  ```go Go
  client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeSonnet5_5,
  	MaxTokens: 16000,
  	Thinking: anthropic.ThinkingConfigParamUnion{
  		OfBetweenTools: &anthropic.ThinkingConfigBetweenToolsParam{},
  	},
  	OutputConfig: anthropic.OutputConfigParam{
  		Effort: anthropic.OutputConfigEffortHigh,
  	},
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
  	},
  })
  ```

  ```java Java
  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_SONNET_5_5)
      .maxTokens(16000L)
      .thinking(ThinkingConfigBetweenTools.builder().build())
      .outputConfig(OutputConfig.builder()
          .effort(OutputConfig.Effort.HIGH)
          .build())
      .addUserMessage("...")
      .build();

  client.messages().create(params);
  ```

  ```php PHP
  $client->messages->create(
      model: Model::CLAUDE_SONNET_5_5,
      maxTokens: 16000,
      thinking: ThinkingConfigBetweenTools::with(),
      outputConfig: OutputConfig::with(effort: Effort::HIGH),
      messages: [['role' => 'user', 'content' => '...']],
  );
  ```

  ```ruby Ruby
  client.messages.create(
    model: Anthropic::Model::CLAUDE_SONNET_5_5,
    max_tokens: 16000,
    thinking: Anthropic::ThinkingConfigBetweenTools.new,
    output_config: { effort: Anthropic::OutputConfig::Effort::HIGH },
    messages: [{ role: "user", content: "..." }]
  )
  ```
</CodeGroup>

## 시작 모델별 마이그레이션 체크리스트

아래 그룹을 위에서부터 차례로 적용하고, 사용 중인 모델이 제목에 포함된 그룹까지 적용한 뒤 멈추세요. Claude Haiku 4.5에서 옮기는 경우에는 "Claude Sonnet 4 이하"를 제외한 모든 그룹을 적용하고, 마지막으로 "Claude Haiku 4.5 전용"을 적용하세요.

### 모든 시작 모델

* 모델 ID를 `claude-sonnet-5-5`로 변경하세요.
* [콘텐츠 블록을 `type`으로 읽고](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#thinking-in-responses), `thinking` 블록을 변경 없이 다시 전달하세요.
* 사전 사고 없이 계속 실행하려면 `high` effort 이하에서 [가장 낮은 사고 설정](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#turn-off-up-front-thinking)을 보내세요.
* [강제 도구 사용](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#forced-tool-use)을 `auto`와 strict 도구로(Amazon Bedrock에서는 `auto`만으로) 대체하세요.
* 대화를 [추가 전용(append-only)](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#thinking-blocks)으로 유지하세요.
* Claude API와 Google Cloud에서는 `fine-grained-tool-streaming-2025-05-14` 베타 헤더 없이 컴퓨터 사용을 [툴셋](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#computer-use-toolset)으로 옮기세요.
* [어드바이저 도구](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#advisor-tool)를 지원되는 어드바이저와 함께 사용하고, 암호화된 조언을 예상하세요.
* [도구 호출 사이의 텍스트](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#text-between-tool-calls)를 `thinking` 블록에서 읽으세요.
* [거부를 처리](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#safety-classifiers-and-fallback)하고 폴백을 구성하세요.
* [effort 스윕을 다시 실행](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#recommended-changes)하고 비용 기준선을 다시 설정하세요.

### Claude Sonnet 4.6 이하

* [`thinking` 필드가 없는 요청에서도 사고가 실행된다는 점](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#thinking-on-by-default)에 대비하고, `max_tokens`를 다시 검토하세요.
* [사고 예산](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#sonnet-46-breaking-changes)을 노력 수준으로 대체하세요.
* 기본값이 아닌 `temperature`, `top_p`, `top_k` 값을 제거하세요.
* [사고 텍스트를 표시하는](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#thinking-in-responses) 경우 `display: "summarized"`를 설정하세요.
* [토큰 수를 다시 계산하고](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#other-changes-from-claude-sonnet-4-6) 이미지 토큰 예산을 다시 책정하세요.

### Claude Sonnet 4.5 이하

* [어시스턴트 prefill](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#migrating-from-sonnet-45)을 다른 방식으로 대체하세요.
* 도구 호출 입력은 표준 JSON 파서로 파싱하세요.
* Amazon Bedrock에서는 컴퓨터 사용 도구를 `computer_20250124`에서 [`computer_20251124`](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#computer-use-toolset)로 옮기세요.
* `output_config.effort`를 명시적으로 설정하세요.
* 컨텍스트 윈도우 관련 베타 헤더를 모두 제거하세요.
* `interleaved-thinking-2025-05-14`를 제거하고, `fine-grained-tool-streaming-2025-05-14`를 `eager_input_streaming`으로 대체하세요.
* `output_format`을 `output_config.format`으로 옮기세요.

### Claude Sonnet 4 이하

* [도구 버전](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#migrating-from-claude-sonnet-4-or-earlier)을 `text_editor_20250728` 및 `code_execution_20260521`로 업데이트하세요.
* `refusal` 및 `model_context_window_exceeded` 중지 이유를 처리하세요.
* 도구의 문자열 매개변수에 후행 줄바꿈이 있는지 확인하세요.
* `token-efficient-tools-2025-02-19` 및 `output-128k-2025-02-19`를 제거하세요.
* 프롬프트를 검토하세요.

### Claude Haiku 4.5 전용

* [`claude-haiku-4-5-20251001`](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#migrating-from-claude-haiku-4-5) 또는 해당 별칭을 새 모델 ID로 바꾸세요.
* 더 높은 토큰당 가격을 기준으로 비용 기준선을 다시 설정하세요.
* Claude Haiku 4.5에서는 너무 짧아 캐시되지 않았던 프롬프트를 검토하세요.

## Claude Sonnet 5에서 Claude Sonnet 5.5로 마이그레이션하기

이 섹션의 변경 사항은 모든 시작 모델에 적용됩니다. 모델 ID를 날짜 접미사가 없는 `claude-sonnet-5-5`로 바꾸세요. 다른 플랫폼에서는 [가용성](https://platform.claude.com/docs/ko/models/sonnet-5-5/whats-new-sonnet-5-5#availability)에 나열된 ID를 사용하세요.

### 강제 도구 사용은 지원되지 않습니다

이 페이지의 모든 이전 모델은 `any` 또는 `tool` 유형의 `tool_choice`를 허용합니다. Claude Sonnet 5.5는 [토큰 카운팅](https://platform.claude.com/docs/ko/build-with-claude/token-counting) 엔드포인트를 포함하여 두 가지 모두를 400 오류로 거부합니다:

```text wrap
tool_choice: type "tool" and "any" are not supported for this model.
```

`tool_choice: {"type": "auto"}`를 보내고, 입력이 스키마와 일치하도록 도구를 `strict: true`로 표시하세요. 이 경우 모델이 도구를 호출하지 않고 답변할 수 있으므로, 언제 도구를 사용해야 하는지 프롬프트에 명시하세요. [Strict 도구 사용](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/strict-tool-use)은 JSON Schema의 일부만 지원하며, 모든 객체에 `additionalProperties: false`가 필요합니다. [JSON Schema 제한 사항](https://platform.claude.com/docs/ko/build-with-claude/structured-outputs#json-schema-limitations)을 참조하세요. Amazon Bedrock에서는 strict 도구 사용을 포함하는 [구조화된 출력](https://platform.claude.com/docs/ko/build-with-claude/structured-outputs)을 Claude Sonnet 5.5에서 사용할 수 없습니다. 그곳에서는 `strict` 없이 `auto`를 보내고, 언제 도구를 호출해야 하는지 프롬프트에 명시하며, 코드에서 도구 입력을 검증하세요.

이전 (Claude Sonnet 5):

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-sonnet-5",
      "max_tokens": 1024,
      "tools": [{
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            }
          },
          "required": ["location"],
          "additionalProperties": false
        }
      }],
      "tool_choice": {"type": "tool", "name": "get_weather"},
      "messages": [{"role": "user", "content": "What'\''s the weather in Paris?"}]
    }'
  ```

  ```bash CLI
  ant messages create <<'YAML'
  model: claude-sonnet-5
  max_tokens: 1024
  tools:
    - name: get_weather
      description: Get the current weather in a given location
      input_schema:
        type: object
        properties:
          location:
            type: string
            description: The city and state, e.g. San Francisco, CA
        required: [location]
        additionalProperties: false
  tool_choice:
    type: tool
    name: get_weather
  messages:
    - role: user
      content: What's the weather in Paris?
  YAML
  ```

  ```python Python
  client.messages.create(
      model="claude-sonnet-5",
      max_tokens=1024,
      tools=tools,
      tool_choice={"type": "tool", "name": "get_weather"},
      messages=[{"role": "user", "content": "What's the weather in Paris?"}],
  )
  ```

  ```typescript TypeScript
  await client.messages.create({
    model: "claude-sonnet-5",
    max_tokens: 1024,
    tools,
    tool_choice: { type: "tool", name: "get_weather" },
    messages: [{ role: "user", content: "What's the weather in Paris?" }]
  });
  ```

  ```csharp C#
  await client.Messages.Create(new MessageCreateParams
  {
      Model = Model.ClaudeSonnet5,
      MaxTokens = 1024,
      Tools = [.. tools],
      ToolChoice = new ToolChoiceTool { Name = "get_weather" },
      Messages = [new() { Role = Role.User, Content = "What's the weather in Paris?" }],
  });
  ```

  ```go Go
  client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:      anthropic.ModelClaudeSonnet5,
  	MaxTokens:  1024,
  	Tools:      tools,
  	ToolChoice: anthropic.ToolChoiceParamOfTool("get_weather"),
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather in Paris?")),
  	},
  })
  ```

  ```java Java
  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_SONNET_5)
      .maxTokens(1024L)
      .tools(tools)
      .toolChoice(ToolChoiceTool.of("get_weather"))
      .addUserMessage("What's the weather in Paris?")
      .build();

  client.messages().create(params);
  ```

  ```php PHP
  $client->messages->create(
      model: Model::CLAUDE_SONNET_5,
      maxTokens: 1024,
      tools: $tools,
      toolChoice: ToolChoiceTool::with(name: 'get_weather'),
      messages: [['role' => 'user', 'content' => "What's the weather in Paris?"]],
  );
  ```

  ```ruby Ruby
  client.messages.create(
    model: Anthropic::Model::CLAUDE_SONNET_5,
    max_tokens: 1024,
    tools: tools,
    tool_choice: Anthropic::ToolChoiceTool.new(name: "get_weather"),
    messages: [{ role: "user", content: "What's the weather in Paris?" }]
  )
  ```
</CodeGroup>

이후 (Claude Sonnet 5.5):

<CodeGroup>
  ```bash cURL
  # strict tool use(엄격한 도구 사용): 모든 호출이 도구의 input_schema와 일치합니다
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-sonnet-5-5",
      "max_tokens": 1024,
      "tools": [{
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            }
          },
          "required": ["location"],
          "additionalProperties": false
        },
        "strict": true
      }],
      "tool_choice": {"type": "auto"},
      "messages": [{
        "role": "user",
        "content": "What'\''s the weather in Paris? Use the get_weather tool."
      }]
    }'
  ```

  ```bash CLI
  ant messages create <<'YAML'
  model: claude-sonnet-5-5
  max_tokens: 1024
  tools:
    - name: get_weather
      description: Get the current weather in a given location
      input_schema:
        type: object
        properties:
          location:
            type: string
            description: The city and state, e.g. San Francisco, CA
        required: [location]
        additionalProperties: false
      # strict tool use(엄격한 도구 사용): 모든 호출이 도구의 input_schema와 일치합니다
      strict: true
  tool_choice:
    type: auto
  messages:
    - role: user
      content: What's the weather in Paris? Use the get_weather tool.
  YAML
  ```

  ```python Python
  client.messages.create(
      model="claude-sonnet-5-5",
      max_tokens=1024,
      # strict tool use(엄격한 도구 사용): 모든 호출이 도구의 input_schema와 일치합니다
      tools=[{**tool, "strict": True} for tool in tools],
      tool_choice={"type": "auto"},
      messages=[
          {
              "role": "user",
              "content": "What's the weather in Paris? Use the get_weather tool.",
          }
      ],
  )
  ```

  ```typescript TypeScript
  await client.messages.create({
    model: "claude-sonnet-5-5",
    max_tokens: 1024,
    // strict 도구 사용: 모든 호출이 도구의 input_schema와 일치합니다
    tools: tools.map((tool) => ({ ...tool, strict: true })),
    tool_choice: { type: "auto" },
    messages: [
      {
        role: "user",
        content: "What's the weather in Paris? Use the get_weather tool."
      }
    ]
  });
  ```

  ```csharp C#
  await client.Messages.Create(new MessageCreateParams
  {
      Model = Model.ClaudeSonnet5_5,
      MaxTokens = 1024,
      // strict tool use(엄격한 도구 사용): 모든 호출이 도구의 input_schema와 일치합니다
      Tools = [.. tools.Select(tool => tool with { Strict = true })],
      ToolChoice = new ToolChoiceAuto(),
      Messages =
      [
          new()
          {
              Role = Role.User,
              Content = "What's the weather in Paris? Use the get_weather tool.",
          },
      ],
  });
  ```

  ```go Go
  // strict 도구 사용: 모든 호출이 도구의 input_schema와 일치합니다
  var strictTools []anthropic.ToolUnionParam
  for _, tool := range tools {
  	strictTool := *tool.OfTool
  	strictTool.Strict = anthropic.Bool(true)
  	strictTools = append(strictTools, anthropic.ToolUnionParam{OfTool: &strictTool})
  }
  client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:      anthropic.ModelClaudeSonnet5_5,
  	MaxTokens:  1024,
  	Tools:      strictTools,
  	ToolChoice: anthropic.ToolChoiceUnionParam{OfAuto: &anthropic.ToolChoiceAutoParam{}},
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(
  			anthropic.NewTextBlock("What's the weather in Paris? Use the get_weather tool."),
  		),
  	},
  })
  ```

  ```java Java
  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_SONNET_5_5)
      .maxTokens(1024L)
      // strict 도구 사용: 모든 호출이 도구의 input_schema와 일치합니다
      .tools(tools.stream()
          .map(tool -> tool.tool()
              .map(customTool -> customTool.toBuilder().strict(true).build())
              .map(ToolUnion::ofTool)
              .orElse(tool))
          .toList())
      .toolChoice(ToolChoiceAuto.builder().build())
      .addUserMessage("What's the weather in Paris? Use the get_weather tool.")
      .build();

  client.messages().create(params);
  ```

  ```php PHP
  $client->messages->create(
      model: Model::CLAUDE_SONNET_5_5,
      maxTokens: 1024,
      // strict 도구 사용: 모든 호출이 도구의 input_schema와 일치합니다
      tools: array_map(fn (Tool $tool) => $tool->withStrict(true), $tools),
      toolChoice: ToolChoiceAuto::with(),
      messages: [
          [
              'role' => 'user',
              'content' => "What's the weather in Paris? Use the get_weather tool.",
          ],
      ],
  );
  ```

  ```ruby Ruby
  client.messages.create(
    model: Anthropic::Model::CLAUDE_SONNET_5_5,
    max_tokens: 1024,
    # strict tool use(엄격한 도구 사용): 모든 호출이 도구의 input_schema와 일치합니다
    tools: tools.map { |tool| tool.merge(strict: true) },
    tool_choice: Anthropic::ToolChoiceAuto.new,
    messages: [
      { role: "user", content: "What's the weather in Paris? Use the get_weather tool." }
    ]
  )
  ```
</CodeGroup>

이 예제는 목록의 모든 도구를 strict로 표시합니다. 하나의 요청에는 최대 20개의 strict 도구를 포함할 수 있으며, MCP, 컴퓨터 사용, 브라우저 사용 툴셋 항목은 `strict`를 허용하지 않습니다. 더 긴 도구 목록에서는 필요한 도구만 표시하세요.

### 사고 블록은 모델과 대화에 연결됩니다

Claude Sonnet 5.5는 Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5 및 이전 모델의 사고 블록을 읽으며, Claude API와 Google Cloud에서는 Claude Haiku 5.5의 사고 블록도 읽습니다. Claude Opus 5, Claude Opus 5.5 또는 Claude Fable이나 Claude Mythos 모델의 블록은 읽지 않습니다. API는 모델이 읽을 수 없는 블록을 삭제합니다. 요청은 여전히 200을 반환하며, 삭제된 블록은 청구되지 않습니다. [대화 중 모델 전환](https://platform.claude.com/docs/ko/build-with-claude/preserved-thinking#switching-models)을 참조하세요.

각 Claude Sonnet 5.5 사고 블록은 그 이전의 대화에 대해서도 서명됩니다. 2026년 8월 31일 00:00 UTC 이후에 생성된 계정의 경우, API는 Claude API, Amazon Bedrock, Google Cloud에서 기본적으로 이를 적용합니다. 해당 계정에서는 이전 기록을 편집한 후 블록을 재전송하는 요청이 400 오류를 반환합니다. 대화를 추가 전용으로 유지하고, [대화 중간 시스템 메시지](https://platform.claude.com/docs/ko/build-with-claude/mid-conversation-system-messages)로 지침이나 도구를 변경하세요. Claude Sonnet 5.5가 생성한 사고 블록은 해당 블록을 생성한 계정 또는 그 계정에 연결된 계정에서만 작동합니다. [보존된 사고](https://platform.claude.com/docs/ko/build-with-claude/preserved-thinking#account-bound-thinking)를 참조하세요.

### Claude API와 Google Cloud에서는 컴퓨터 사용에 툴셋이 필요합니다

Claude API와 Google Cloud에서 Claude Sonnet 5.5는 `computer_toolset_20260801` 툴셋을 통해서만 컴퓨터 사용을 지원하며, 이 플랫폼에서 `computer_20251124`를 보내면 400 오류가 반환됩니다. `computer_20250124`는 어떤 플랫폼에서도 Claude Sonnet 5.5에서 사용할 수 없습니다. 아래 표에서 현재 보내는 버전을 찾으세요.

| 현재 보내는 버전           | 이 버전을 보내는 시작 모델                                      | Claude API 및 Google Cloud에서 보낼 버전 | Amazon Bedrock에서 보낼 버전 |
| ------------------- | ---------------------------------------------------- | --------------------------------- | ---------------------- |
| `computer_20251124` | Claude Sonnet 5, Claude Sonnet 4.6                   | `computer_toolset_20260801`       | `computer_20251124`    |
| `computer_20250124` | Claude Sonnet 4.5, Claude Haiku 4.5, Claude Sonnet 4 | `computer_toolset_20260801`       | `computer_20251124`    |

`fine-grained-tool-streaming-2025-05-14` 베타 헤더를 보내고 있다면 툴셋으로 옮길 때 제거하세요. 이 헤더를 툴셋 항목과 함께 보내면 400 오류가 반환됩니다. 대신 필요한 각 도구에 `eager_input_streaming: true`를 설정하세요.

이미 툴셋을 보내는 코드는 변경할 필요가 없습니다. 요청과 에이전트 루프의 변경 사항은 [`computer_20251124`에서 마이그레이션하기](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124)를 참조하세요. 다른 플랫폼에 대해서는 [호환성](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#compatibility)을 참조하세요.

### 어드바이저 도구에서 사용할 수 있는 어드바이저가 줄었습니다

[어드바이저 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/advisor-tool)를 사용할 때 Claude Sonnet 5.5 실행자(executor)에는 Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5, Claude Fable 5.1, Claude Mythos 5, Claude Mythos 5.1 중 하나를 어드바이저로 지정해야 합니다. Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5, Claude Sonnet 4.6, Claude Haiku 5.5 어드바이저는 400 오류를 반환합니다. 조언은 `advisor_redacted_result` 블록으로 암호화되어 반환되므로 응답에서 그 텍스트를 읽을 수 없습니다. [모델 호환성](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/advisor-tool#model-compatibility)을 참조하세요.

### 도구 호출 사이의 텍스트는 사고 블록으로 반환됩니다

Claude Sonnet 5.5에서는 모델이 도구 호출 사이에 작성하는 메모 중 한두 문장보다 긴 것은 [진행 상황 업데이트 `thinking` 블록](https://platform.claude.com/docs/ko/build-with-claude/thinking#progress-updates)으로 반환되며, 기본 `display` 설정에서는 내용이 비어 있습니다. 이보다 짧은 메모는 계속 `text`로 반환됩니다. Claude Sonnet 5 및 이전 모델에서는 도구 호출 사이의 모든 텍스트가 `text` 블록으로 반환됩니다. 이 변경으로 요청이 실패하지는 않지만, 이러한 메모를 표시하던 인터페이스에는 더 이상 메모가 나타나지 않습니다.

적응형 사고를 사용할 때 업데이트만 받으려면 `display`를 `"updates"`(베타, `thinking-display-updates-2026-08-18` 헤더 필요)로 설정하고, 추론과 함께 받으려면 `"summarized"`로 설정하세요. 내용이 있는 각 `thinking` 블록은 바로 뒤에 오는 `tool_use` 블록보다 먼저 렌더링하세요. [`between_tools`](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#turn-off-up-front-thinking)를 사용하면 `display`를 설정하지 않아도 텍스트가 반환됩니다. [사용자 대상 진행 상황 업데이트](https://platform.claude.com/docs/ko/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#user-facing-progress-updates)를 참조하세요.

### 안전 분류기와 폴백

Claude Sonnet 5.5는 Claude Sonnet 5보다 더 많은 범주에서 요청을 거절합니다. 거절된 요청은 `stop_reason: "refusal"`을 반환하며, `stop_details`에 다음 [범주](https://platform.claude.com/docs/ko/build-with-claude/refusals-and-fallback#refusal-response) 중 하나가 표시될 수 있습니다.

* **`"cyber"`:** 멀웨어나 익스플로잇 개발처럼 사이버 피해로 이어질 수 있는 요청입니다.
* **`"bio"`:** 위험한 실험 방법처럼 생물학적 피해로 이어질 수 있는 요청입니다.
* **`"frontier_llm"`:** 경쟁 AI 모델 개발에 도움이 될 수 있는 요청입니다.
* **`"reasoning_extraction"`:** 모델의 내부 추론을 응답 텍스트에 그대로 재현하도록 요구하는 요청입니다.
* **`"general_harms"`:** 그 밖의 사용 정책 영역에 해당하는 요청입니다. 무해한 작업도 이 범주로 분류될 수 있습니다.

[서버 측 폴백](https://platform.claude.com/docs/ko/build-with-claude/refusals-and-fallback#server-side-fallback)(`fallbacks: "default"`, 베타, Claude API 전용)은 `"cyber"` 및 `"frontier_llm"` 범주로 거절된 요청을 Claude Sonnet 5에서 다시 시도합니다. `"bio"`, `"reasoning_extraction"`, `"general_harms"` 범주로 거절된 요청은 다시 시도하지 않습니다. [거부 및 폴백](https://platform.claude.com/docs/ko/build-with-claude/refusals-and-fallback)과 [거부에 대한 요금 청구 방식](https://platform.claude.com/docs/ko/build-with-claude/refusals-and-fallback#how-refusals-are-billed)을 참조하세요.

Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Haiku 4.5에서 옮기는 코드에는 실시간 사이버 보호 장치가 새로 적용됩니다. 정당한 보안 작업을 수행하는 경우 [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude-opus-and-sonnet)에 신청하세요.

### 기타 변경 사항

* **"Prompt caching"(프롬프트 캐싱):** 캐시할 수 있는 최소 프롬프트 길이가 Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5의 1,024 토큰에서 512 토큰으로 줄었습니다. [프롬프트 캐싱](https://platform.claude.com/docs/ko/build-with-claude/prompt-caching#cache-limitations)을 참조하세요.
* **새로운 기능:** 대화 중간 시스템 메시지, 대화 중간 도구 변경, 메시지별 노력 수준에 대해서는 [Claude Sonnet 5.5의 새로운 기능](https://platform.claude.com/docs/ko/models/sonnet-5-5/whats-new-sonnet-5-5#feature-support)을 참조하세요. 단, [`between_tools`](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#turn-off-up-front-thinking)를 사용하면 대화 도중에 노력 수준을 바꿀 수 없습니다.

### 권장 변경 사항

노력 수준 스윕을 다시 실행하세요. Claude Sonnet 5.5에는 `low`, `medium`, `high`, `xhigh`, `max`의 다섯 가지 노력 수준이 있으며, Claude API의 기본값은 `high`입니다. 각 수준이 재보정되었으므로, 같은 수준이라도 Claude Sonnet 5와 같은 양의 사고를 생성하지는 않습니다. 에이전트형 워크로드나 "latency"(지연 시간)에 민감한 워크로드가 아니라면 `high`에서 시작하세요. 에이전트형 코딩과 다단계 도구 사용에서는 요구 사항이 명확한 작업은 `medium`에서 시작하고, 더 어렵거나 긴 작업은 `high`로 올리세요. 채팅처럼 지연 시간에 민감한 작업은 `medium` 또는 `low`에서 시작하세요. 수준은 `output_config.effort`에서 설정합니다. [Claude Sonnet 5.5 권장 노력 수준](https://platform.claude.com/docs/ko/build-with-claude/effort#recommended-effort-levels-for-claude-sonnet-5-5)을 참조하세요. 그런 다음 [Claude Sonnet 5.5 프롬프팅](https://platform.claude.com/docs/ko/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5)을 기준으로 모델별 프롬프트 지침을 다시 평가하세요.

## Claude Sonnet 4.6 및 이전 Sonnet 모델에서 Claude Sonnet 5.5로 마이그레이션하기

먼저 앞의 모든 섹션을 적용하세요. 이때 모델 ID는 `claude-sonnet-4-6`을 바꾸면 됩니다. 그런 다음 아래 변경 사항을 적용하세요. Claude Sonnet 4.5 이하에서 옮기는 경우에는 이어지는 하위 섹션도 계속 적용하세요.

### 호환성을 깨는 변경 사항

**사고를 지정하지 않은 요청에서도 사고가 실행됩니다.** [기본적으로 사고가 실행됩니다](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#thinking-on-by-default)와 [사전 사고 끄기](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#turn-off-up-front-thinking)를 참조하세요.

**사고 예산을 지정하면 오류가 반환됩니다.** Claude Sonnet 4.6은 `thinking: {"type": "enabled", "budget_tokens": N}`을 지원 중단된 설정으로 허용하며, Claude Sonnet 4.5와 Claude Haiku 4.5는 모든 사고에 이 설정을 사용합니다. Claude Sonnet 5.5에서는 이 설정이 400 오류를 반환합니다.

```text wrap
"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.
```

예산을 제거하고 [노력](https://platform.claude.com/docs/ko/build-with-claude/effort) 수준을 설정하세요. 예산과 노력 수준 사이에는 정해진 대응 관계가 없으므로, 두세 가지 수준에서 평가를 실행해 보세요.

이전 (Claude Sonnet 4.6):

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-sonnet-4-6",
      "max_tokens": 16000,
      "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
      },
      "messages": [
        {
          "role": "user",
          "content": "..."
        }
      ]
    }'
  ```

  ```bash CLI
  ant messages create <<'YAML'
  model: claude-sonnet-4-6
  max_tokens: 16000
  thinking:
    type: enabled
    budget_tokens: 10000
  messages:
    - role: user
      content: "..."
  YAML
  ```

  ```python Python
  client.messages.create(
      model="claude-sonnet-4-6",
      max_tokens=16000,
      thinking={"type": "enabled", "budget_tokens": 10000},
      messages=[{"role": "user", "content": "..."}],
  )
  ```

  ```typescript TypeScript
  await client.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 16000,
    thinking: { type: "enabled", budget_tokens: 10000 },
    messages: [{ role: "user", content: "..." }]
  });
  ```

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

  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeSonnet4_6,
      MaxTokens = 16000,
      Thinking = new ThinkingConfigEnabled(budgetTokens: 10000),
      Messages = [new() { Role = Role.User, Content = "..." }]
  };

  var response = await client.Messages.Create(parameters);
  Console.WriteLine(response);
  ```

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

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeSonnet4_6,
  	MaxTokens: 16000,
  	Thinking:  anthropic.ThinkingConfigParamOfEnabled(10000),
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response)
  ```

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

  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_SONNET_4_6)
      .maxTokens(16000L)
      .enabledThinking(10000L)
      .addUserMessage("...")
      .build();

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

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

  $message = $client->messages->create(
      maxTokens: 16000,
      messages: [['role' => 'user', 'content' => '...']],
      model: 'claude-sonnet-4-6',
      thinking: ['type' => 'enabled', 'budget_tokens' => 10000],
  );
  ```

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

  message = client.messages.create(
    model: "claude-sonnet-4-6",
    max_tokens: 16000,
    thinking: {
      type: "enabled",
      budget_tokens: 10000
    },
    messages: [
      { role: "user", content: "..." }
    ]
  )
  ```
</CodeGroup>

이후 (Claude Sonnet 5.5):

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-sonnet-5-5",
      "max_tokens": 16000,
      "thinking": {
        "type": "adaptive"
      },
      "output_config": {
        "effort": "high"
      },
      "messages": [
        {
          "role": "user",
          "content": "..."
        }
      ]
    }'
  ```

  ```bash CLI
  ant messages create <<'YAML'
  model: claude-sonnet-5-5
  max_tokens: 16000
  thinking:
    type: adaptive
  output_config:
    effort: high
  messages:
    - role: user
      content: "..."
  YAML
  ```

  ```python Python
  client.messages.create(
      model="claude-sonnet-5-5",
      max_tokens=16000,
      thinking={"type": "adaptive"},
      output_config={"effort": "high"},  # or "max", "xhigh", "medium", "low"
      messages=[{"role": "user", "content": "..."}],
  )
  ```

  ```typescript TypeScript
  await client.messages.create({
    model: "claude-sonnet-5-5",
    max_tokens: 16000,
    thinking: { type: "adaptive" },
    output_config: { effort: "high" }, // or "max", "xhigh", "medium", "low"
    messages: [{ role: "user", content: "..." }]
  });
  ```

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

  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeSonnet5_5,
      MaxTokens = 16000,
      Thinking = new ThinkingConfigAdaptive(),
      OutputConfig = new OutputConfig { Effort = Effort.High }, // or Max, Xhigh, Medium, Low
      Messages = [new() { Role = Role.User, Content = "..." }]
  };

  var response = await client.Messages.Create(parameters);
  Console.WriteLine(response);
  ```

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

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeSonnet5_5,
  	MaxTokens: 16000,
  	Thinking: anthropic.ThinkingConfigParamUnion{
  		OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{},
  	},
  	OutputConfig: anthropic.OutputConfigParam{
  		Effort: anthropic.OutputConfigEffortHigh, // or Max, Xhigh, Medium, Low
  	},
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response)
  ```

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

  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_SONNET_5_5)
      .maxTokens(16000L)
      .thinking(ThinkingConfigAdaptive.builder().build())
      .outputConfig(OutputConfig.builder()
          .effort(OutputConfig.Effort.HIGH) // or MAX, XHIGH, MEDIUM, LOW
          .build())
      .addUserMessage("...")
      .build();

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

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

  $message = $client->messages->create(
      maxTokens: 16000,
      messages: [['role' => 'user', 'content' => '...']],
      model: 'claude-sonnet-5-5',
      thinking: ['type' => 'adaptive'],
      outputConfig: ['effort' => 'high'], // or 'max', 'xhigh', 'medium', 'low'
  );
  ```

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

  message = client.messages.create(
    model: "claude-sonnet-5-5",
    max_tokens: 16000,
    thinking: {
      type: "adaptive"
    },
    output_config: {
      effort: "high" # or "max", "xhigh", "medium", "low"
    },
    messages: [
      { role: "user", content: "..." }
    ]
  )
  ```
</CodeGroup>

**샘플링 매개변수를 지정하면 오류가 반환됩니다.** Claude Sonnet 4.6 및 이전 모델과 Claude Haiku 4.5는 `temperature`, `top_p`, `top_k`를 허용합니다. Claude Sonnet 5.5에서는 이 매개변수에 기본값이 아닌 값을 지정하면 400 오류가 반환되므로, 해당 매개변수를 제거하세요.

**사고 텍스트는 기본적으로 생략됩니다.** [응답에서 사고 처리하기](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#thinking-in-responses)를 참조하세요.

### 기타 변경 사항

* **토큰 수 약 30% 증가:** Claude Sonnet 5.5는 Claude Sonnet 5와 같은 토크나이저를 사용합니다. 따라서 같은 텍스트라도 Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Haiku 4.5보다 토큰이 약 30% 더 많이 생성되며, 정확한 비율은 콘텐츠에 따라 다릅니다. [토큰 카운팅](https://platform.claude.com/docs/ko/build-with-claude/token-counting)으로 토큰 수를 다시 계산하고, `max_tokens`와 비용을 다시 검토하세요.
* **노력 수준:** `xhigh`가 새로 추가되었고, 각 수준이 재보정되었습니다. [권장 변경 사항](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#recommended-changes)을 참조하세요.
* **이미지:** Claude Sonnet 5.5는 고해상도 이미지 등급을 사용하며, 긴 변 기준 최대 2576픽셀, 이미지당 최대 4,784개의 시각 토큰을 지원합니다. Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Haiku 4.5의 한도는 1568픽셀, 1,568 토큰입니다. 예를 들어 2000×1500 이미지는 Claude Sonnet 5.5에서 약 2.5배 많은 토큰을 사용합니다. [해상도 및 토큰 비용](https://platform.claude.com/docs/ko/build-with-claude/vision#evaluate-image-size)을 참조하세요.

### Claude Sonnet 4.5 이하에서 마이그레이션하기

Claude Sonnet 4.5, Claude Sonnet 4 또는 Claude 3.7 Sonnet의 경우, 먼저 앞의 모든 섹션을 적용한 다음 아래 변경 사항을 적용하세요.

**Prefill은 오류를 반환합니다.** Claude Sonnet 5.5는 Claude Sonnet 4.6 및 Claude Sonnet 5와 마찬가지로 미리 채워진 마지막 어시스턴트 턴을 400 오류로 거부합니다. Claude Sonnet 4.5, Claude Haiku 4.5 및 이전 모델은 이를 허용합니다. 오류 내용은 다음과 같습니다:

```text wrap
This model does not support assistant message prefill. The conversation must end with a user message.
```

각 prefill을 그 용도에 따라 대체하세요:

* **출력 형식:** [구조화된 출력](https://platform.claude.com/docs/ko/build-with-claude/structured-outputs)을 사용하거나, 분류에는 enum 필드가 있는 도구를 사용하세요. Amazon Bedrock에서는 Claude Sonnet 5.5에 구조화된 출력을 사용할 수 없습니다. 그곳에서는 프롬프트에 형식을 설명하거나 `strict` 없이 도구를 사용하고, 코드에서 출력을 검증하세요.
* **서두:** 시스템 프롬프트에서 직접적인 답변을 요청하세요.
* **원치 않는 거부:** 일반적으로 사용자 메시지의 명확한 지침으로 충분합니다.
* **이어쓰기:** 사용자 메시지로 옮기세요. 예: "이전 응답이 중단되었으며 `[previous_response]`(으)로 끝났습니다. 중단된 부분부터 이어서 작성하세요."
* **컨텍스트 리마인더:** 사용자 턴에 넣으세요.

**도구 입력 이스케이프.** 도구 호출 인수의 이스케이프 방식이 다를 수 있습니다. `input`을 표준 JSON 파서로 파싱하세요.

**컴퓨터 사용.** Claude Sonnet 5.5는 `computer_20250124`를 허용하지 않습니다. [컴퓨터 사용 표](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#computer-use-toolset)를 참조하세요.

**Effort.** Claude Sonnet 4.5에는 effort 매개변수가 없습니다. [권장 변경 사항](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#recommended-changes)에 설명된 대로 effort 수준을 명시적으로 설정하세요.

**컨텍스트 및 출력.** Claude Sonnet 5.5는 베타 헤더 없이 더 큰 컨텍스트 윈도우와 더 높은 출력 한도를 제공합니다. [모델 페이지](https://platform.claude.com/docs/ko/models/sonnet-5-5/overview)를 참조하세요. 컨텍스트 윈도우 관련 베타 헤더를 모두 제거하세요.

**베타 헤더.** 적응형 사고는 자동으로 인터리빙되므로 `interleaved-thinking-2025-05-14`를 제거하세요. `fine-grained-tool-streaming-2025-05-14`를 필요한 각 도구의 `eager_input_streaming: true`로 대체하세요. 해당 헤더는 컴퓨터 사용 또는 브라우저 사용 툴셋 항목과 함께 사용하면 400 오류를 반환합니다. [세분화된 도구 스트리밍](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/fine-grained-tool-streaming)을 참조하세요.

**구조화된 출력.** `output_format` 매개변수는 지원 중단되었으며 향후 제거될 예정입니다. 그래도 사용하려면 `structured-outputs-2025-11-13` 베타 헤더를 추가하세요. 이 헤더가 없으면 API는 400 오류를 반환합니다. 대신 `output_config.format`을 사용하세요.

### Claude Sonnet 4 이하에서 마이그레이션하기

Claude Sonnet 4는 Claude API에서 종료되었지만 Amazon Bedrock과 Google Cloud에서는 계속 사용할 수 있습니다. Claude 3.7 Sonnet은 종료되었습니다. 두 모델 중 어느 모델에서 옮기든, 먼저 앞의 모든 섹션을 적용한 다음 아래 변경 사항을 적용하세요.

* **도구 버전:** `text_editor_20250728`을 사용하세요. 이 버전의 도구 이름은 `str_replace_based_edit_tool`이며, `undo_edit` 명령은 지원하지 않습니다. 코드 실행에는 `code_execution_20260521`을 사용하세요. [텍스트 편집기 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/text-editor-tool)와 [코드 실행 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/code-execution-tool#upgrade-to-latest-tool-version)를 참조하세요.
* **중지 이유:** `refusal`을 처리하세요. 또한 Claude 4.5 이상 모델은 컨텍스트 윈도우 한도에 도달하면 `model_context_window_exceeded`로 중지됩니다. [중지 이유 처리](https://platform.claude.com/docs/ko/build-with-claude/handling-stop-reasons)를 참조하세요.
* **후행 줄바꿈:** Claude 4.5 이상 모델은 도구 호출의 문자열 매개변수에서 후행 줄바꿈을 제거하지 않고 유지합니다.
* **레거시 베타 헤더:** `token-efficient-tools-2025-02-19` 및 `output-128k-2025-02-19`를 제거하세요.
* **프롬프트:** [프롬프팅 모범 사례](https://platform.claude.com/docs/ko/build-with-claude/prompt-engineering/claude-prompting-best-practices)를 기준으로 프롬프트를 검토하세요.

## Claude Haiku 4.5에서 Claude Sonnet 5.5로 마이그레이션하기

먼저 [Claude Sonnet 4.5 이하에서 마이그레이션하기](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#migrating-from-sonnet-45)까지(해당 섹션 포함) 모든 섹션을 적용하되, Claude Sonnet 4 하위 섹션은 건너뛰세요. 그런 다음 아래 변경 사항을 적용하세요.

* **모델 ID:** `claude-haiku-4-5-20251001` 또는 별칭 `claude-haiku-4-5`를 `claude-sonnet-5-5`로 바꾸세요.
* **비용:** 토큰당 가격이 더 높고, 같은 텍스트에서 더 많은 토큰이 생성됩니다. 토큰 수를 다시 계산하고 비용 기준선을 다시 설정하세요. [Claude 가격](https://platform.claude.com/docs/ko/about-claude/pricing)을 참조하세요.
* **프롬프트 캐싱:** 캐시할 수 있는 최소 프롬프트 길이가 4,096 토큰에서 [Claude Sonnet 5.5의 최소값](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#other-changes-from-claude-sonnet-5)으로 줄어듭니다.
* **"Interleaved thinking"(인터리브 사고):** 적응형 사고는 베타 헤더 없이도 도구 호출 사이에서 자동으로 실행됩니다.
* **라우팅:** Claude Sonnet 5.5는 Claude Haiku 4.5의 사고 블록을 읽을 수 있으므로, Claude Haiku 4.5에서 Claude Sonnet 5.5로 넘어간 대화는 기존 추론을 유지합니다. 반대로 Claude Haiku 4.5로 다시 넘어간 대화에서는 Claude Sonnet 5.5의 사고 블록이 제거됩니다.