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

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

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

Claude Sonnet 5.5의 가격은 Claude Sonnet 5와 동일하지만, 프롬프트 캐시 읽기는 예외로 백만 토큰당 $0.10 USD이며 이는 Claude Sonnet 5 요금의 절반입니다. [가격](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”(노력 수준)을 설정하며, 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), [어시스턴트 프리필](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: 2026-10-21" \
    -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.type === "text");
  console.log(textBlock?.text);
  ```

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

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeSonnet5_5,
      MaxTokens = 4096,
      Messages = [
          new UserMessageParam
          {
              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: Model::CLAUDE_SONNET_5_5,
      outputConfig: ['effort' => 'medium'],
  );

  echo "Stop reason: {$message->stopReason}", PHP_EOL;
  foreach ($message->content as $block) {
      if ($block instanceof \Anthropic\Messages\TextBlock) {
          echo $block->text, PHP_EOL;
      }
  }
  ```

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

  message = client.messages.create(
    model: Anthropic::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.is_a?(Anthropic::Models::TextBlock)
  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에서는 해당 요청이 사고 없이 실행되었습니다. 사전 사고 없이 계속 실행하려면 [사전 사고 끄기](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`를 읽는 코드는 작동하지 않습니다.
* **“Tool use”(도구 사용) 루프에서 빈 블록을 포함하여 `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` 노력 수준에서 허용됩니다. `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`를 사용하면 대화 도중에 노력 수준을 변경할 수 없습니다: 적용 중인 수준과 다른 메시지별 `output_config.effort`는 400 오류를 반환합니다. 턴마다 노력 수준을 다르게 하려면 적응형 사고를 사용하세요. 프롬프팅 안내는 [사전 사고 없이 실행하기](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: 2026-10-21" \
    -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 UserMessageParam { 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: 2026-10-21" \
    -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 UserMessageParam { 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 도구로 대체하세요.
* 대화를 [추가 전용(append-only)](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#thinking-blocks)으로 유지하세요.
* 컴퓨터 사용을 `fine-grained-tool-streaming-2025-05-14` 베타 헤더 없이 [도구 세트](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#computer-use-toolset)로 옮기세요. Amazon Bedrock에서는 `computer_20251124`도 작동합니다.
* [어드바이저 도구를](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 또는 이전

* [어시스턴트 프리필](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#migrating-from-sonnet-45)을 대체하세요.
* 도구 호출 입력은 표준 JSON 파서로 파싱하세요.
* `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) 또는 해당 별칭을 대체하세요.
* 더 높은 토큰당 가격으로 비용 기준선을 다시 설정하세요.
* 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)을 참조하세요.

이전 (Claude Sonnet 5):

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -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 is 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 UserMessageParam { 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 도구 사용: 모든 호출이 도구의 input_schema와 일치합니다
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -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 is 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 도구 사용: 모든 호출이 도구의 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 도구 사용: 모든 호출이 도구의 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 UserMessageParam
          {
              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 도구 사용: 모든 호출이 도구의 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 및 [이전 모델](https://platform.claude.com/docs/ko/build-with-claude/preserved-thinking#earlier-models)의 사고 블록을 읽습니다. Claude API 및 Claude Models on Google Cloud (Google managed)에서는 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)를 참조하세요.

사고 블록이 [접두사 검사](https://platform.claude.com/docs/ko/build-with-claude/preserved-thinking/prefix-checks#prefix-check)를 통과하도록 대화를 추가 전용(append-only)으로 유지하세요. 지침 또는 도구를 변경하려면 [대화 중 시스템 메시지 및 도구 변경](https://platform.claude.com/docs/ko/build-with-claude/mid-conversation-system-messages)을 참조하세요.

[“prefix check”(접두사 검사)](https://platform.claude.com/docs/ko/build-with-claude/preserved-thinking/prefix-checks#prefix-check)를 통과하지 못하면 [400 오류](https://platform.claude.com/docs/ko/api/errors#thinking-block-conversation-mismatch)가 발생할 수도 있고 발생하지 않을 수도 있습니다. 두 경우를 모두 식별하고 처리하려면 [사고 블록에 대한 접두사 검사](https://platform.claude.com/docs/ko/build-with-claude/preserved-thinking/prefix-checks)를 참조하세요.

접두사 검사는 Claude API 및 [일부 클라우드 플랫폼](https://platform.claude.com/docs/ko/build-with-claude/preserved-thinking#feature-availability)에서 실행됩니다.

Claude Sonnet 5.5 사고 블록은 해당 블록을 생성한 계정 또는 그 계정에 연결된 계정에서만 작동합니다. [보존된 사고](https://platform.claude.com/docs/ko/build-with-claude/preserved-thinking#account-bound-thinking)를 참조하세요.

### 일부 컴퓨터 사용 도구 버전은 지원되지 않습니다

Claude Sonnet 5.5는 `computer_toolset_20260801` 도구 세트를 통해 컴퓨터 사용을 지원합니다. Amazon Bedrock에서는 Claude Sonnet 5.5가 `computer-use-2025-11-24` 베타 헤더와 함께 `computer_20251124` 도구도 허용합니다. Claude Sonnet 5.5는 Claude API에서의 `computer_20251124`처럼 허용하지 않는 컴퓨터 사용 도구 버전에 대해 400 오류를 반환합니다. `computer_20250124`는 어떤 플랫폼에서도 허용하지 않습니다.

도구 세트를 사용하는 통합은 변경할 필요가 없습니다. 도구 세트로 옮기려면 `computer_20251124` 또는 `computer_20250124`를 `computer_toolset_20260801`로 대체하고, 해당 버전의 베타 헤더를 제거하세요. 요청 및 에이전트 루프 변경 사항은 [`computer_20251124`에서 마이그레이션](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124)을 참조하세요.

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

### 어드바이저 도구가 허용하는 어드바이저가 줄었습니다

[어드바이저 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/advisor-tool)를 사용할 때 Claude Sonnet 5.5 실행자에는 다음 어드바이저 중 하나가 필요합니다: Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5, Claude Fable 5.1, Claude Fable 5.2, Claude Mythos 5, Claude Mythos 5.1 또는 Claude Mythos 5.2. 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"`:** 요청이 다른 사용 정책 영역에 해당합니다. 무해한 작업도 이 범주를 유발할 수 있습니다.

Claude API 및 [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/ko/build-with-claude/claude-models-on-google-cloud/anthropic-managed)에서 베타로 제공되는 [서버 측 폴백](https://platform.claude.com/docs/ko/build-with-claude/refusals-and-fallback#server-side-fallback)(`fallbacks: "default"`)은 `"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”(프롬프트 캐싱):** 캐시 가능한 최소 프롬프트는 512 토큰으로, Claude Sonnet 5, Claude Sonnet 4.6 및 Claude Sonnet 4.5의 1,024 토큰에서 줄어들었습니다. [프롬프트 캐싱](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에서와 동일한 양의 사고를 생성하지는 않습니다. 워크로드가 에이전트형이거나 지연 시간에 민감한 경우가 아니라면 `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로 마이그레이션하기

먼저 `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: 2026-10-21" \
    -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 UserMessageParam { 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: Model::CLAUDE_SONNET_4_6,
      thinking: ['type' => 'enabled', 'budgetTokens' => 10000],
  );
  ```

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

  message = client.messages.create(
    model: Anthropic::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: 2026-10-21" \
    -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 UserMessageParam { 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: 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: Anthropic::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>

**샘플링 매개변수를 지정하면 오류가 반환됩니다.** `temperature`, `top_p`, `top_k`를 제거하세요.

**사고 텍스트는 기본적으로 생략됩니다.** [응답에서 사고 처리하기](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`와 비용을 재검토하세요.
* **노력 수준:** Claude Sonnet 5.5는 `xhigh`를 지원하며, 수준이 재보정되었습니다. [권장 변경 사항](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#recommended-changes)을 참조하세요.
* **이미지:** Claude Sonnet 5.5는 고해상도 이미지 등급을 사용하며, 긴 변 기준 최대 2,576픽셀, 이미지당 최대 4,784개의 시각 토큰을 지원합니다. Claude Sonnet 4.6, Claude Sonnet 4.5 및 Claude Haiku 4.5는 1,568픽셀 및 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에서는 먼저 앞의 모든 섹션을 적용한 다음 아래 변경 사항을 적용하세요.

**프리필은 오류를 반환합니다.** 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.
```

각 프리필을 그 용도에 따라 대체하세요:

* **출력 형식:** [구조화된 출력](https://platform.claude.com/docs/ko/build-with-claude/structured-outputs)을 사용하거나, 분류에는 enum 필드가 있는 도구를 사용하세요.
* **서두:** “system prompt”(시스템 프롬프트)에서 직접적인 답변을 요청하세요.
* **원치 않는 거부:** 일반적으로 사용자 메시지의 명확한 지침으로 충분합니다.
* **이어쓰기:** 사용자 메시지로 옮기세요. 예: "이전 응답이 중단되어 `[previous_response]`로 끝났습니다. 중단된 부분부터 계속하세요."
* **컨텍스트 알림:** 사용자 턴에 넣으세요.

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

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

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

**컨텍스트 및 출력.** Claude Sonnet 5.5는 더 큰 컨텍스트 윈도우와 더 높은 출력 한도를 제공합니다. [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에서 종료되었지만 Claude Models on Google Cloud (Google managed) 및 Amazon Bedrock에서는 사용할 수 있습니다. Claude 3.7 Sonnet은 종료되었습니다. 두 모델 중 어느 모델에서 옮기든, 먼저 앞의 모든 섹션을 적용한 다음 아래 변경 사항을 적용하세요:

* **도구 버전:** 도구 이름 `str_replace_based_edit_tool`과 함께 `undo_edit` 명령 없이 `text_editor_20250728`을 사용하세요. `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 하위 섹션을 건너뛰고 [Claude Sonnet 4.5 또는 이전 모델에서 마이그레이션하기](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#migrating-from-sonnet-45)까지의 모든 섹션을 적용하세요. 그런 다음 아래 변경 사항을 적용하세요:

* **모델 ID:** `claude-haiku-4-5-20251001` 또는 별칭 `claude-haiku-4-5`를 `claude-sonnet-5-5`로 교체하세요.
* **비용:** 토큰당 가격이 더 높고, 동일한 텍스트가 더 많은 토큰을 생성합니다. 토큰을 다시 계산하고 비용 기준선을 다시 설정하세요. [가격](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)으로 줄어듭니다.
* **인터리브 사고:** 적응형 사고는 도구 호출 사이에서 자동으로 실행됩니다.
* **라우팅:** Claude Sonnet 5.5는 Claude Haiku 4.5 사고 블록을 읽습니다. 상위 모델로 이동하는 대화는 추론을 유지합니다. Claude Haiku 4.5로 다시 내려가는 대화는 Claude Sonnet 5.5의 블록을 제외합니다.