Claude Opus 5.5로 마이그레이션하기
Claude Opus 5.5로 마이그레이션하기 (Migrating to Claude Opus 5.5)
이 가이드는 Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 및 그 이전 Opus 모델, 그리고 Claude Sonnet 5에서 Claude Opus 5.5로 옮길 때 필요한 코드 변경 사항을 정리한 문서예요. 오류를 반환하는 요청 설정, 모든 응답에 나타나는 thinking 블록, 그리고 시작 모델별 체크리스트를 함께 다룹니다.
출처: 문서
본문
/claude-api migrate this project to claude-opus-5-5
이 스킬은 코드베이스 전체에 걸쳐 대상 모델에 맞는 모델 ID 교체와, 필요시 호환성 파괴 파라미터 변경, 프리필 대체, effort 보정을 적용한 다음, 수동으로 확인할 항목의 체크리스트를 생성해요. 파일을 편집하기 전에 마이그레이션 범위(전체 작업 디렉터리, 하위 디렉터리, 또는 특정 파일 목록)를 확인하라고 요청해요. 이 스킬은 Amazon Bedrock과 AWS 위의 Claude Platform 클라이언트도 감지해 해당 플랫폼의 모델 ID 형식과 기능 변경을 조정해요.
이 페이지는 Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 및 그 이전 Opus 모델, 또는 Claude Sonnet 5에서 Claude Opus 5.5로 이동하기 위한 코드 변경 사항을 나열해요. 모든 독자는 Claude Opus 5.5에 대한 모든 요청이 만족해야 하는 조건과 모든 응답에서 thinking 처리를 읽어야 해요. 그런 다음 현재 모델에 해당하는 섹션으로 가세요. 각 섹션의 첫 문장이 여러분에게 적용되는 다른 섹션들을 알려줘요. 마이그레이션 체크리스트는 시작 모델별 모든 변경을 나열해요.
Claude Opus 5.5는 Claude Opus 5보다 비용이 낮아요(입력/출력 백만 토큰당 $4 / $20 USD, 비교 $5 / $25. Claude 가격 참고). 기능 지원은 Claude Opus 5.5의 새로운 기능을, 동작 차이와 모델별 프롬프팅 패턴은 Claude Opus 5.5 프롬프팅을 참고하세요.
Claude Opus 5.5에 대한 모든 요청이 만족해야 하는 조건
어떤 모델에서 오든 claude-opus-5-5에 대한 요청은 다음을 충족해야 해요. 설정이 거부된다고 표시된 항목은 API가 400 오류를 반환해요.
- 모델 ID: 날짜 접미사가 없는 고정 모델 ID인
claude-opus-5-5를 사용하세요. Amazon Bedrock, AWS 위의 Claude Platform, Google Cloud, Microsoft Foundry에서는 해당 플랫폼의 모델 ID를 사용하세요. 제공 (Availability)을 참고하세요. - Thinking:
thinking필드를 보내지 않거나, 동등한thinking: {"type": "adaptive"}를 보내세요. adaptive thinking은 항상 켜져 있어요.thinking: {"type": "disabled"}와 수동 thinking 예산(thinking: {"type": "enabled", "budget_tokens": N})은 거부돼요. thinking의 before and after를 참고하세요. - Effort: thinking 깊이를 제어하는 유일한 요청 파라미터인 effort 파라미터로 thinking 깊이를 제어하세요. 다섯 단계(
low,medium,high,xhigh,max)가 모두 지원되며 기본값은medium이에요. Claude Opus 5.5 권장 effort 수준을 참고하세요. - 도구 선택:
tool_choice{"type": "auto"}(기본값) 또는{"type": "none"}을 사용하세요.{"type": "any"}또는{"type": "tool", "name": "..."}로 도구 호출을 강제하는 것은 거부돼요. tool choice의 before and after를 참고하세요. - 샘플링 파라미터:
temperature,top_p,top_k를 생략하거나 기본값으로 두세요. 다른 값은 거부돼요. 프롬프팅으로 모델 동작을 안내하세요. - 프리필:
messages를 프리필된 assistant 턴으로 끝내지 마세요. 거부돼요. 대신 구조화된 출력이나 시스템 프롬프트 지시를 사용하세요. - 컴퓨터 사용: Claude API와 Google Cloud에서 컴퓨터 사용을
computer_toolset_20260801툴셋으로 선언하세요. 이전computer_20251124도구는 거기서 거부돼요. 컴퓨터 사용 호환성 파괴 변경을 참고하세요. - 컨텍스트 창: 컨텍스트 창 베타 헤더가 필요하지 않아요. 1M 토큰 컨텍스트 창이 기본값이며, 이전 모델을 위해 보낸 헤더는 효과가 없어요.
다음 요청은 목록의 모든 항목을 충족해요: effort가 설정되어 있고 thinking 필드가 없어요. 텍스트를 출력하는 SDK 탭은 thinking 블록이 먼저 오기 때문에 블록 유형으로 텍스트를 선택해요.
ant messages create \
--model claude-opus-5-5 \
--max-tokens 4096 \
--output-config '{effort: medium}' \
--message '{role: user, content: "Analyze the trade-offs between microservices and monolithic architectures"}'
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Analyze the trade-offs between microservices and monolithic architectures",
}
],
output_config={"effort": "medium"},
)
for block in response.content:
if block.type == "text":
print(block.text)
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
messages: [
{
role: "user",
content: "Analyze the trade-offs between microservices and monolithic architectures"
}
],
output_config: {
effort: "medium"
}
});
const textBlock = response.content.find(
(block): block is Anthropic.TextBlock => block.type === "text"
);
console.log(textBlock?.text);
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_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(message);
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_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)
}
for _, block := range response.Content {
if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
fmt.Println(textBlock.Text)
}
}
import com.anthropic.models.messages.OutputConfig;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_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.content().stream()
.flatMap(block -> block.text().stream())
.forEach(textBlock -> IO.println(textBlock.text()));
}
$client = new Client();
$message = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Analyze the trade-offs between microservices and monolithic architectures']
],
model: 'claude-opus-5-5',
outputConfig: ['effort' => 'medium'],
);
foreach ($message->content as $block) {
if ($block->type === 'text') {
echo $block->text, PHP_EOL;
}
}
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
messages: [
{ role: "user", content: "Analyze the trade-offs between microservices and monolithic architectures" }
],
output_config: {
effort: "medium"
}
)
message.content.each do |block|
puts block.text if block.type == :text
end
모든 응답에서 thinking 처리
Claude Opus 5.5의 모든 요청에서 thinking이 실행되므로, 모든 응답이 thinking 블록으로 시작할 수 있고 max_tokens은 thinking과 텍스트를 모두 포함해요. 코드가 이미 thinking 켜짐으로 실행 중이라면 항목 1~3은 아마 이미 갖춰져 있을 거예요. 항목 4와 5를 확인하세요. thinking 없이 실행됐다면, 이전 모델에서는 각 항목이 변경 사항이에요.
-
max_tokens은 thinking과 텍스트를 모두 포함: Claude Opus 4.8 및 그 이전 Opus 모델에서는thinking필드가 없는 요청이 thinking 없이 실행돼요. Claude Opus 5와 Claude Sonnet 5는thinking: {"type": "disabled"}를 허용해요. Claude Opus 5.5에서는 모든 요청이 adaptive thinking으로 실행돼요.max_tokens은 thinking과 응답 텍스트를 포함한 총 출력의 하드 한도로 유지되므로, thinking 없이 실행되던 워크로드는 이를 다시 검토하세요. thinking 토큰은 thinking 텍스트가 반환되지 않아도 출력 토큰으로 과금되므로, 그런 워크로드는 요청당 더 많은 출력 토큰을 생성할 수 있어요. 비용 제어를 참고하세요. thinking에 더 적은 토큰을 쓰려면 effort 수준을 낮추세요.xhigh또는maxeffort로 실행한다면 모델이 생각하고 행동할 여유가 있도록 큰max_tokens을 설정하세요. 64k 토큰에서 시작해 조정하세요. 프롬프트가 thinking 없이 실행되도록 튜닝되었다면 thinking 비활성화용으로 작성된 프롬프트를 참고하세요. -
응답이 thinking 블록으로 시작함: 응답이 첫
text블록 전에 하나 이상의thinking블록으로 시작할 수 있어요.content[0].text처럼 위치로 답변을 읽는 코드나 첫content_block_start이벤트를 텍스트로 취급하는 스트림 핸들러는 이런 응답에서 깨져요. 대신type필드로 콘텐츠 블록을 선택하세요:type이"text"인 블록에서text를 읽고, 스트림 이벤트를 처리할 때 블록 유형을 기준으로 분기하세요. -
도구 사용 루프에서 thinking 블록을 수정 없이 다시 전달: 도구 사용 루프를 실행한다면 각 assistant 응답의
thinking블록을 도구 결과를 반환할 때thinking필드가 빈 블록을 포함해 완전하고 수정 없이 API로 다시 전달하세요. 콘텐츠 블록을 유형별로 필터링하거나 재구성하지 말고 받은 대로 assistant 메시지를 그대로 에코하세요. API는 편집, 재정렬, 부분 삭제된 thinking 블록을 400 오류로 거부해요. thinking 블록 보존을 참고하세요. -
Thinking 텍스트가 기본적으로 생략됨:
thinking.display는"omitted"로 기본설정되므로,thinking블록이signature와 함께 빈thinking필드로 도착해요.thinking필드를 표시 텍스트로만 취급하세요. 읽을 수 있는 요약을 받으려면thinking.display를"summarized"로 설정하세요:```python Python thinking = { "type": "adaptive", "display": "summarized", } ``` const thinking = { type: "adaptive", display: "summarized" };var thinking = new ThinkingConfigAdaptive { Display = Display.Summarized };thinking := anthropic.ThinkingConfigParamUnion{ OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{ Display: anthropic.ThinkingConfigAdaptiveDisplaySummarized, }, }ThinkingConfigAdaptive thinking = ThinkingConfigAdaptive.builder() .display(ThinkingConfigAdaptive.Display.SUMMARIZED) .build();$thinking = ['type' => 'adaptive', 'display' => 'summarized'];thinking = { type: "adaptive", display: "summarized" }제품이 추론을 사용자에게 스트리밍한다면 기본 설정이 출력 시작 전에 긴 멈춤으로 나타나요. thinking 중에 보이는 진행 상황을 복원하려면
display: "summarized"를 설정하세요. thinking 표시 제어를 참고하세요. -
도구 호출 사이의 텍스트가 thinking 블록으로 도착: 모델이 도구 호출 사이에 쓰는 짧은 메모가
thinking블록으로 돌아오며, 기본 표시에서 비어 있어요. 도구 호출 사이의 텍스트가 thinking 블록으로 반환됨을 참고하세요.
시작 모델별 마이그레이션 체크리스트
그룹을 아래로 내려가며 현재 모델을 명명한 그룹에서 멈추세요. 그 시점까지의 모든 항목이 여러분에게 적용돼요. Claude Opus 5라면 첫 그룹이 전체 목록이에요. Claude Sonnet 5라면 첫 그룹과 마지막 그룹을 적용하세요.
모든 시작 모델
- 모델 ID를
claude-opus-5-5로 업데이트하세요. thinking: {"type": "disabled"}와thinking: {"type": "enabled", ...}를 제거하세요. 대신 effort 수준을 선택하세요.effort를 명시적으로 설정하세요. 기본값은medium이며, Claude Opus 5의 기본값은high예요.tool_choice유형any와tool을auto+ 엄격한 도구 사용 또는 구조화된 출력으로 바꾸세요.- Claude API나 Google Cloud에서 컴퓨터 사용을 사용한다면
computer_20251124대신computer_toolset_20260801(베타 헤더 없음)을 선언하고 에이전트 루프를 툴셋에 맞게 업데이트하세요. Amazon Bedrock에서는computer_20251124를 유지하세요. 다른 플랫폼은 컴퓨터 사용 도구의 호환성 섹션을 확인하세요. - 라우터나 폴백이 대화를 Claude Opus 5.5에서 다른 모델로 옮길 수 있다면, 그 모델이 Claude Opus 5.5의 thinking 블록 없이 실행될 것으로 예상하세요(Claude API의 Claude Fable 5.1과 Claude Mythos 5.1은 예외이며 그것들을 유지해요). Claude Opus 5.5 자체는 Claude Opus 5 및 그 이전 Opus, Sonnet, Haiku 모델의 thinking은 읽지만 Claude Fable이나 Claude Mythos 모델의 thinking은 읽지 않아요.
- 콘텐츠 블록을
type으로 읽고, 도구 사용 루프에서thinking블록을 수정 없이 다시 전달하세요. - 인터페이스가 도구 호출 사이의 텍스트를 렌더링한다면
display: "updates"(베타) 또는"summarized"를 설정하고 비어 있지 않은thinking블록을 렌더링하세요. - 코드가 대화 중간에 이전 턴,
system프롬프트,tools를 편집한다면 보존된 thinking을 따르세요. stop_reason: "refusal"을 처리하고 폴백을 구성하세요.- 선택한 effort 수준에서 비용과 지연 시간을 다시 기준선으로 잡으세요.
- 코드가 thinking을 비활성화했다면 thinking과 응답 텍스트를 포함하는
max_tokens을 다시 검토하세요.xhigh또는maxeffort에서는 64k에서 시작하세요. 모든 응답에서 thinking 처리를 참고하세요.
Claude Opus 4.8 이하
thinking필드 없이 실행되던 워크로드를 검토하세요. Claude Opus 5.5에서는 thinking과 함께 실행되며 thinking을 비활성화할 수 없어요. 총 출력(thinking + 응답 텍스트)의 하드 한도로 유지되는max_tokens을 다시 검토하고, thinking을 덜 원하는 곳에서는effort를 낮추세요. thinking 토큰은 출력 토큰으로 과금되므로 이런 워크로드는 요청당 더 많은 출력 토큰을 생성할 수 있어요.thinking필드를 파싱하는 코드가 그것을 표시 텍스트로만 취급하는지 확인하세요. 읽을 수 있는 요약을 받으려면display: "summarized"를 설정하세요.- 캐싱 최소값 근처의 프롬프트를 검토하세요. 512 토큰 이상의 프롬프트는 캐시 항목을 만들 수 있어요.
- 조직에 Priority Tier 약정이 있다면 용량을 별도로 계획하세요. Priority Tier는 Claude Opus 5.5에서 지원되지 않아요.
xhigh또는maxeffort로 실행한다면max_tokens을 시작점으로 최소 64k까지 올리세요.- 에이전트 워크로드에는 작업 예산(task budgets)(베타)과 대화 중간 도구 변경(베타)을 고려하세요.
Claude Opus 4.7 이하
- 이전 모델에 맞춰 조정된 설정을 그대로 가져오지 말고 자체 평가에서 새 effort 스윕을 실행하세요.
- 컨텍스트 창 베타 헤더를 제거하세요.
- 지시를 업데이트하기 위해 대화 기록을 재구축한다면, 프롬프트 캐시 히트를 보존하기 위해 대화 중간 시스템 메시지로 전환하는 것을 고려하세요.
- 거절 시
stop_details를 읽는지 stop-reason 처리를 확인하세요. - fast mode를 원한다면(Claude Opus 4.7은 거부함) Claude API에서
fast-mode-2026-02-01베타 헤더로speed: "fast"를 설정하세요.
Claude Opus 4.6 이하
- 요청 페이로드에서
temperature,top_p,top_k를 제거하세요. thinking: {"type": "enabled", "budget_tokens": N}을thinking: {"type": "adaptive"}+ effort 파라미터로 바꾸거나thinking필드를 완전히 제거하세요. adaptive thinking은 항상 켜져 있어요.- UI가 thinking 콘텐츠를 표시한다면 thinking 요약에 명시적으로 옵트인하세요.
- 업데이트된 토큰화에서 종단 간 비용과 지연 시간을 재벤치마크하세요.
- 압축 트리거를 포함해 업데이트된 토큰화를 반영하도록
max_tokens을 재튜닝하세요. - 클라이언트 측 토큰 수 추정을 다시 테스트하세요.
- 애플리케이션이 이미지를 보낸다면 고해상도 이미지 지원에 맞춰 예산을 다시 세우세요(전체 해상도 이미지당 최대 약 3배 더 많은 이미지 토큰). 추가 디테일이 필요하지 않다면 보내기 전에 다운샘플하세요.
- 모델에서 포인팅이나 바운딩 박스 좌표를 사용한다면 배율 변환을 제거하세요. Claude Opus 4.7 이후 모델에서는 좌표가 실제 이미지 픽셀과 1:1이에요.
- Claude Opus 4.7에서 시작된 동작 변경을 검토하세요.
- 제품이 합법적인 보안 작업을 한다면 Cyber Verification Program에 신청해 사이버 콘텐츠에 대한 더 낮은 제한에 접근하세요.
Claude Opus 4.5 이하
- assistant 메시지 프리필을 제거하세요. Claude Opus 4.6이 이미 거부해요.
- 도구 호출 JSON 파싱이 표준 JSON 파서를 사용하는지 확인하세요.
client.beta.messages.create에서client.messages.create로 이동하세요. adaptive thinking과 effort는 베타 네임스페이스가 필요 없어요.effort-2025-11-24베타 헤더를 제거하세요 (effort 파라미터는 그것을 요구하지 않아요).fine-grained-tool-streaming-2025-05-14베타 헤더를 제거하세요.interleaved-thinking-2025-05-14베타 헤더를 제거하세요 (adaptive thinking이 interleaved thinking을 자동으로 활성화해요).output_format을output_config.format으로 마이그레이션하세요 (해당되는 경우).
Claude 4.1 이하
- 도구 버전을 업데이트하세요 (
text_editor_20250728,code_execution_20260521). refusalstop reason을 처리하세요.model_context_window_exceededstop reason을 처리하세요.- 후행 개행에 대한 도구 문자열 파라미터 처리를 확인하세요.
- 레거시 베타 헤더(
token-efficient-tools-2025-02-19,output-128k-2025-02-19)를 제거하세요. - 프롬프팅 모범 사례에 따라 프롬프트를 검토하고 업데이트하세요.
Claude Sonnet 5 전용
- 지시를 업데이트하기 위해 대화 기록을 재구축한다면, 프롬프트 캐시 히트를 보존하기 위해 대화 중간 시스템 메시지로 전환하는 것을 고려하세요.
- 캐싱 최소값 근처의 프롬프트를 검토하세요. 512 토큰 이상의 프롬프트는 캐시 항목을 만들 수 있어요.
Claude Opus 5에서 Claude Opus 5.5로 마이그레이션
먼저 Claude Opus 5.5에 대한 모든 요청이 만족해야 하는 조건과 모든 응답에서 thinking 처리를 읽으세요. 모든 시작 모델은 이 섹션의 변경이 필요해요. 그것들은 Claude Opus 5.5가 거부하는 요청 설정과 함께 따라오는 응답 변경이에요. 이 섹션의 체크리스트는 마이그레이션 체크리스트의 첫 그룹이에요.
모델 이름 업데이트
model = "claude-opus-5" # Before
model = "claude-opus-5-5" # After
claude-opus-5-5는 claude-opus-5와 같은 방식인 날짜 접미사가 없는 고정 모델 ID예요. Amazon Bedrock, AWS 위의 Claude Platform, Google Cloud, Microsoft Foundry에서는 해당 플랫폼의 모델 ID를 사용하세요. 제공 (Availability)을 참고하세요.
호환성 파괴 변경
각 변경은 Claude Opus 5.5의 새로운 기능에 설명되어 있고, 이 섹션에서는 각각의 코드 변경을 보여줘요.
Thinking을 비활성화할 수 없음
thinking: {"type": "disabled"}와 thinking: {"type": "enabled", "budget_tokens": N}은 모두 400 오류를 반환해요 ("thinking.type.disabled" is not supported for this model. 또는 "thinking.type.enabled" is not supported for this model.). thinking 필드를 제거하고 effort 수준을 선택하세요. 토큰을 절약하려고 thinking을 비활성화했던 곳에서는 더 낮은 수준을 사용하세요. 그러면 응답이 thinking 블록으로 시작하므로 type으로 콘텐츠 블록을 선택하고 도구 결과와 함께 thinking 블록을 수정 없이 다시 전달하세요. Thinking을 비활성화할 수 없음을 참고하세요.
Before. Claude Opus 5는 이 요청을 허용하고, Claude Opus 5.5는 400 오류로 거부해요:
ant messages create \
--model claude-opus-5 \
--max-tokens 16000 \
--thinking '{type: disabled}' \
--message '{role: user, content: "..."}'
client.messages.create(
model="claude-opus-5",
max_tokens=16000,
thinking={"type": "disabled"},
messages=[{"role": "user", "content": "..."}],
)
await client.messages.create({
model: "claude-opus-5",
max_tokens: 16000,
thinking: { type: "disabled" },
messages: [{ role: "user", content: "..." }]
});
await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5,
MaxTokens = 16000,
Thinking = new ThinkingConfigDisabled(),
Messages = [new() { Role = Role.User, Content = "..." }],
});
client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 16000,
Thinking: anthropic.ThinkingConfigParamUnion{
OfDisabled: &anthropic.ThinkingConfigDisabledParam{},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
},
})
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(16000L)
.thinking(ThinkingConfigDisabled.builder().build())
.addUserMessage("...")
.build();
client.messages().create(params);
$client->messages->create(
model: Model::CLAUDE_OPUS_5,
maxTokens: 16000,
thinking: ThinkingConfigDisabled::with(),
messages: [['role' => 'user', 'content' => '...']],
);
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5,
max_tokens: 16000,
thinking: Anthropic::ThinkingConfigDisabled.new,
messages: [{ role: "user", content: "..." }]
)
After:
# thinking is always on; effort is the control
ant messages create \
--model claude-opus-5-5 \
--max-tokens 16000 \
--output-config '{effort: low}' \
--message '{role: user, content: "..."}'
client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
output_config={"effort": "low"}, # thinking is always on; effort is the control
messages=[{"role": "user", "content": "..."}],
)
await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 16000,
output_config: { effort: "low" }, // thinking is always on; effort is the control
messages: [{ role: "user", content: "..." }]
});
await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 16000,
OutputConfig = new() { Effort = Effort.Low }, // thinking is always on; effort is the control
Messages = [new() { Role = Role.User, Content = "..." }],
});
client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 16000,
OutputConfig: anthropic.OutputConfigParam{
Effort: anthropic.OutputConfigEffortLow, // thinking is always on; effort is the control
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
},
})
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(16000L)
// thinking is always on; effort is the control
.outputConfig(OutputConfig.builder()
.effort(OutputConfig.Effort.LOW)
.build())
.addUserMessage("...")
.build();
client.messages().create(params);
$client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 16000,
// thinking is always on; effort is the control
outputConfig: OutputConfig::with(effort: Effort::LOW),
messages: [['role' => 'user', 'content' => '...']],
);
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 16000,
# thinking is always on; effort is the control
output_config: { effort: Anthropic::OutputConfig::Effort::LOW },
messages: [{ role: "user", content: "..." }]
)
강제 도구 사용 미지원
tool_choice 유형 any와 tool은 토큰 계산 엔드포인트를 포함해 400 오류를 반환해요 (tool_choice: type "tool" and "any" are not supported for this model.). 엄격한 도구 사용이나 구조화된 출력과 함께 auto를 사용하고, 프롬프트에서 도구가 적용되는 시점을 말하세요. 엄격한 도구 사용은 JSON Schema의 일부만 허용하므로, strict: true를 추가하기 전에 각 도구의 input_schema를 확인하세요. 스키마의 모든 객체는 additionalProperties: false를 설정해야 해요. JSON Schema 제한을 참고하세요. 강제 도구 사용 미지원을 참고하세요.
Before. Claude Opus 5는 이 요청을 허용하고, Claude Opus 5.5는 400 오류로 거부해요:
ant messages create <<'YAML'
model: claude-opus-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
client.messages.create(
model="claude-opus-5",
max_tokens=1024,
tools=tools,
tool_choice={"type": "tool", "name": "get_weather"},
messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)
await client.messages.create({
model: "claude-opus-5",
max_tokens: 1024,
tools,
tool_choice: { type: "tool", name: "get_weather" },
messages: [{ role: "user", content: "What's the weather in Paris?" }]
});
await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5,
MaxTokens = 1024,
Tools = [.. tools],
ToolChoice = new ToolChoiceTool { Name = "get_weather" },
Messages = [new() { Role = Role.User, Content = "What's the weather in Paris?" }],
});
client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 1024,
Tools: tools,
ToolChoice: anthropic.ToolChoiceParamOfTool("get_weather"),
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather in Paris?")),
},
})
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(1024L)
.tools(tools)
.toolChoice(ToolChoiceTool.of("get_weather"))
.addUserMessage("What's the weather in Paris?")
.build();
client.messages().create(params);
$client->messages->create(
model: Model::CLAUDE_OPUS_5,
maxTokens: 1024,
tools: $tools,
toolChoice: ToolChoiceTool::with(name: 'get_weather'),
messages: [['role' => 'user', 'content' => "What's the weather in Paris?"]],
);
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5,
max_tokens: 1024,
tools: tools,
tool_choice: Anthropic::ToolChoiceTool.new(name: "get_weather"),
messages: [{ role: "user", content: "What's the weather in Paris?" }]
)
After:
ant messages create <<'YAML'
model: claude-opus-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: every call matches the tool's input_schema
strict: true
tool_choice:
type: auto
messages:
- role: user
content: What's the weather in Paris? Use the get_weather tool.
YAML
client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
# strict tool use: every call matches the tool's 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.",
}
],
)
await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
// strict tool use: every call matches the tool's 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."
}
]
});
await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
// strict tool use: every call matches the tool's 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.",
},
],
});
// strict tool use: every call matches the tool's 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.ModelClaudeOpus5_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."),
),
},
})
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
// strict tool use: every call matches the tool's 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);
$client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 1024,
// strict tool use: every call matches the tool's 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.",
],
],
);
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
# strict tool use: every call matches the tool's 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." }
]
)
Thinking 블록이 모델과 대화에 묶임
Claude API에서 Claude Fable 5.1과 Claude Mythos 5.1은 Claude Opus 5.5 thinking 블록을 읽어요. 다른 어떤 모델도 그러지 않아요. 대화를 Claude Opus 5.5에서 다른 모델로 옮기는 라우터나 폴백은 그 턴을 그것들 없이 실행해요. 반대 방향으로 Claude Opus 5.5는 Claude Opus 5 및 그 이전 Opus, Sonnet, Haiku 모델의 thinking 블록은 읽지만 Claude Fable이나 Claude Mythos 모델의 것은 읽지 않아요. 블록이 유효하게 유지되도록 대화를 append-only로 유지하세요(대화 중간에 system 프롬프트, tools, 또는 이전 메시지를 편집하지 마세요). Claude Code, claude.ai, Claude Managed Agents, Claude Agent SDK는 이미 그렇게 해요. 모든 플랫폼에서 강제는 Claude Fable 5.1과 일치해요. 2026년 8월 31일 00:00 UTC 이후 생성된 계정은 그런 편집 후 thinking 블록을 재생하면 기본적으로 400 오류를 반환해요. append-only 통합에는 코드 변경이 없어요. Thinking 블록이 모델과 대화에 묶임과 보존된 thinking을 참고하세요.
Claude API와 Google Cloud에서는 computer_20251124 컴퓨터 사용 도구 미지원
Claude API와 Google Cloud에서 computer_20251124 유형의 tools 항목은 400 오류를 반환해요 ('claude-opus-5-5' does not support tool types: computer_20251124., 뒤에 모델이 허용하는 도구 유형이 따라옴). 대신 computer_toolset_20260801 툴셋을 선언하세요: 베타 헤더를 제거하고 name이나 표시 크기 없이 항목을 보내세요. 에이전트 루프에서 멤버 tool_use 블록(동작은 input.action이 아니라 블록의 name)을 처리하고, 턴마다 여러 개를 처리하며, 모든 결과에 toolset_name을 에코하세요. 요청 변경은 아래에 있고, 에이전트 루프 변경은 computer_20251124에서 마이그레이션에 나열되어 있어요. Amazon Bedrock에서는 이전 computer_20251124 도구가 Claude Opus 5와 마찬가지로 Claude Opus 5.5에서 계속 동작하므로 변경이 필요 없어요. 다른 플랫폼은 컴퓨터 사용 도구의 호환성 섹션을 참고하세요. Claude API와 Google Cloud에서는 computer_20251124 컴퓨터 사용 도구 미지원을 참고하세요.
Before. Claude Opus 5는 이 요청을 허용하고, Claude API와 Google Cloud에서 Claude Opus 5.5는 400 오류로 거부해요:
ant beta:messages create \
--model claude-opus-5 \
--max-tokens 4096 \
--beta computer-use-2025-11-24 \
--tool '{
type: computer_20251124,
name: computer,
display_width_px: 1024,
display_height_px: 768
}' \
--message '{role: user, content: "Open the display settings."}'
client.beta.messages.create(
model="claude-opus-5",
max_tokens=4096,
betas=["computer-use-2025-11-24"],
tools=[
{
"type": "computer_20251124",
"name": "computer",
"display_width_px": 1024,
"display_height_px": 768,
}
],
messages=[{"role": "user", "content": "Open the display settings."}],
)
await client.beta.messages.create({
model: "claude-opus-5",
max_tokens: 4096,
betas: ["computer-use-2025-11-24"],
tools: [
{
type: "computer_20251124",
name: "computer",
display_width_px: 1024,
display_height_px: 768
}
],
messages: [{ role: "user", content: "Open the display settings." }]
});
await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5,
MaxTokens = 4096,
Betas = [AnthropicBeta.ComputerUse2025_11_24],
Tools =
[
new BetaToolComputerUse20251124
{
DisplayWidthPx = 1024,
DisplayHeightPx = 768,
},
],
Messages = [new() { Role = Role.User, Content = "Open the display settings." }],
});
client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 4096,
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaComputerUse2025_11_24},
Tools: []anthropic.BetaToolUnionParam{
{OfComputerUseTool20251124: &anthropic.BetaToolComputerUse20251124Param{
DisplayWidthPx: 1024,
DisplayHeightPx: 768,
}},
},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Open the display settings.")),
},
})
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(4096L)
.addBeta(AnthropicBeta.COMPUTER_USE_2025_11_24)
.addTool(BetaToolComputerUse20251124.builder()
.displayWidthPx(1024L)
.displayHeightPx(768L)
.build())
.addUserMessage("Open the display settings.")
.build();
client.beta().messages().create(params);
$client->beta->messages->create(
model: Model::CLAUDE_OPUS_5,
maxTokens: 4096,
betas: [AnthropicBeta::COMPUTER_USE_2025_11_24],
tools: [
BetaToolComputerUse20251124::with(
displayWidthPx: 1024,
displayHeightPx: 768,
),
],
messages: [['role' => 'user', 'content' => 'Open the display settings.']],
);
client.beta.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5,
max_tokens: 4096,
betas: [Anthropic::AnthropicBeta::COMPUTER_USE_2025_11_24],
tools: [
Anthropic::Beta::BetaToolComputerUse20251124.new(
name: :computer,
display_width_px: 1024,
display_height_px: 768
)
],
messages: [{ role: "user", content: "Open the display settings." }]
)
After:
# no beta header; the toolset entry takes no name or display size
ant messages create \
--model claude-opus-5-5 \
--max-tokens 4096 \
--tool '{type: computer_toolset_20260801}' \
--message '{role: user, content: "Open the display settings."}'
client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
# no beta header; the toolset entry takes no name or display size
tools=[{"type": "computer_toolset_20260801"}],
messages=[{"role": "user", "content": "Open the display settings."}],
)
await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
// no beta header; the toolset entry takes no name or display size
tools: [{ type: "computer_toolset_20260801" }],
messages: [{ role: "user", content: "Open the display settings." }]
});
await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
// no beta header; the toolset entry takes no name or display size
Tools = [new ComputerToolset20260801()],
Messages = [new() { Role = Role.User, Content = "Open the display settings." }],
});
client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
// no beta header; the toolset entry takes no name or display size
Tools: []anthropic.ToolUnionParam{
{OfComputerToolset20260801: &anthropic.ComputerToolset20260801Param{}},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Open the display settings.")),
},
})
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
// no beta header; the toolset entry takes no name or display size
.addTool(ComputerToolset20260801.builder().build())
.addUserMessage("Open the display settings.")
.build();
client.messages().create(params);
$client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 4096,
// no beta header; the toolset entry takes no name or display size
tools: [ComputerToolset20260801::with()],
messages: [['role' => 'user', 'content' => 'Open the display settings.']],
);
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 4096,
# no beta header; the toolset entry takes no name or display size
tools: [Anthropic::ComputerToolset20260801.new],
messages: [{ role: "user", content: "Open the display settings." }]
)
도구 호출 사이의 텍스트가 thinking 블록으로 반환됨
Claude Opus 5에서는 모델이 도구 호출 사이에 쓰는 텍스트가 text 블록으로 돌아와요. Claude Opus 5.5에서는 Claude Fable 5.1과 마찬가지로 그 내레이션이 진행 상황 업데이트 thinking 블록으로 돌아오며, 각 도구 호출 전에 최대 하나예요. 기본 thinking.display인 "omitted"에서는 그 thinking 필드가 비어 있어요. 어떤 요청도 실패하지 않지만, 그 텍스트를 진행 상황 업데이트로 사용자에게 스트리밍하는 애플리케이션은 도구 호출 사이에 조용해져요. 업데이트를 복원하려면 thinking 블록에서 읽고 텍스트를 반환하는 display 값을 설정하세요: "updates"(베타, thinking-display-updates-2026-08-18 헤더)는 추론은 숨기면서 진행 상황 업데이트를 반환하고, "summarized"는 둘 다 섞어서 반환해요. 그런 다음 각 비어 있지 않은 thinking 블록을 그것이 앞서는 tool_use 블록 앞에 렌더링하고, 블록들을 나머지 assistant 턴과 함께 변경 없이 다시 전달하세요. 사용자 대상 진행 상황 업데이트를 참고하세요.
안전 분류기와 폴백
Claude Opus 5.5는 stop_reason: "refusal"을 stop_details 카테고리와 함께 반환할 수 있어요. 그 분류기는 Claude Opus 5보다 더 넓은 범주의 집합을 다뤄요. 그래서 "cyber"에 더해 "bio", "reasoning_extraction" 같은 stop_details.category 값을 기대하세요. 거절 카테고리 표를 참고하세요. 거절을 처리하고 서버 측 폴백이나 자체 재시도를 구성하세요(서버 측 폴백은 "reasoning_extraction"으로 거절된 요청은 재시도하지 않아요. 그 거절은 여러분에게 반환돼요). 거절 및 폴백과 안전장치 거절을 참고하세요.
권장 변경
- Effort 스윕을 다시 실행하세요. Effort는 Claude Opus 5.5에서 유일한 thinking 제어이며 기본값은
medium이고(Claude Opus 5는high), 그래서effort를 생략한 요청은 이제medium으로 실행돼요. 품질이 유지되는 곳에서는 낮추고, 가장 까다로운 작업에서는 높이세요. Effort를 참고하세요. - 모델별 프롬프트 지시를 다시 평가하세요. Claude Opus 5의 동작에 맞춰 튜닝된 지시가 더 이상 필요하지 않을 수 있어요. Claude Opus 5.5 프롬프팅을 참고하세요. thinking 비활성화로 실행했다면 thinking 비활성화용으로 작성된 프롬프트도 참고하세요.
- 프로덕션 트래픽을 전환하기 전에 개발 환경에서 테스트하세요.
Claude Opus 4.8에서 Claude Opus 5.5로 마이그레이션
먼저 Claude Opus 5.5에 대한 모든 요청이 만족해야 하는 조건, 모든 응답에서 thinking 처리, Claude Opus 5에서 Claude Opus 5.5로 마이그레이션을 읽으세요. 대체할 모델 ID로 claude-opus-4-8을 사용하세요. 그 마지막 섹션은 Claude Opus 4.8의 코드에 그대로 적용되는데, Claude Opus 4.8은 Claude Opus 5와 마찬가지로:
thinking: {"type": "disabled"}, 강제 도구 선택,computer_20251124도구를 허용해요.- 도구 호출 사이의 텍스트를
text블록으로 반환해요. - 기본 effort가
high예요.
이 섹션은 Claude Opus 4.8과 Claude Opus 5 사이에 변경된 것을 추가해요. 체크리스트는 마이그레이션 체크리스트의 처음 두 그룹을 참고하세요.
변경된 내용
-
thinking이 생략된 요청에도 실행됨: Claude Opus 4.8에서는 요청하지 않으면 thinking이 꺼져 있어요. Claude Opus 5.5에서는
thinking필드가 없는 요청이 thinking과 함께 실행되므로, 그 코드에는 모든 응답에서 thinking 처리의 모든 항목이 변경 사항이에요. 코드가thinking필드를 보낸 적이 없다면 thinking의 before and after에서 제거할 것이 없어요. -
프롬프트 캐싱 최소값 낮아짐: Claude Opus 5.5의 최소 캐시 가능 프롬프트 길이는 Claude Opus 4.8의 1,024 토큰에서 512 토큰으로 낮아졌어요. Claude Opus 4.8에서 캐시하기엔 너무 짧았던 프롬프트가 코드 변경 없이 캐시 항목을 만들 수 있어요. 모델별 최소값은 프롬프트 캐싱을 참고하세요.
-
Priority Tier 미지원: Priority Tier는 Claude Opus 5.5에서 지원되지 않으며, Claude Opus 4.8은 유지돼요. 조직에 Priority Tier 약정이 있다면 용량을 별도로 계획하세요.
권장 변경
필수는 아니지만 경험을 개선할 수 있어요:
-
작업 예산(task budgets) 고려 (베타): 에이전트 워크로드에서 작업 예산은 전체 에이전트 루프에 대한 토큰 수를 모델에 알려줘요.
task-budgets-2026-03-13베타 헤더를 요구해요. -
대화 중간 도구 변경 고려 (베타): 대화 중간 도구 변경(베타 헤더
mid-conversation-tool-changes-2026-07-01)은 Claude API, Amazon Bedrock, Google Cloud에서 제공돼요. 대화의 턴 사이에 이전 턴의 프롬프트 캐시 히트를 무효화하지 않고 도구를 추가하거나 제거할 수 있어요. 헤더가 없으면 변경된 도구 목록은 캐시된 프리픽스를 무효화해요.
Claude Opus 4.7에서 Claude Opus 5.5로 마이그레이션
먼저 Claude Opus 5.5에 대한 모든 요청이 만족해야 하는 조건, 모든 응답에서 thinking 처리, Claude Opus 5에서 Claude Opus 5.5로 마이그레이션, Claude Opus 4.8에서 Claude Opus 5.5로 마이그레이션을 읽으세요. 대체할 모델 ID로 claude-opus-4-7을 사용하세요. 그 섹션들은 Claude Opus 4.7의 코드에 그대로 적용돼요. Claude Opus 4.8과 마찬가지로 thinking: {"type": "disabled"}, 강제 도구 선택, computer_20251124 도구를 허용해요. 기본 effort가 high이고 요청하지 않으면 thinking 없이 실행돼요.
이 섹션은 Claude Opus 4.7 이후에 변경된 것을 추가해요. 코드가 Claude Opus 4.6 이하라면 이 섹션 후에 Claude Opus 4.6 및 그 이전 Opus 모델에서 Claude Opus 5.5로 마이그레이션을 계속 읽으세요. Claude Opus 4.7에서 효력을 발생한 호환성 파괴 변경을 추가해요. 체크리스트는 마이그레이션 체크리스트의 처음 세 그룹을 참고하세요.
변경된 내용
이 항목들 중 어느 것도 이전 섹션들의 호환성 파괴 변경에 추가하지 않아요. 모델 ID를 바꾼 후 확인할 가치가 있어요.
-
Effort 수준 재조정: 각 effort 수준 뒤의 토큰 할당이 Claude Opus 4.7과 비교해 Claude Opus 5.5에서 바뀌어요. 기본값은
medium이고, Claude Opus 4.7의 기본값은high예요. Claude Opus 4.7에 맞춰 조정된 설정을 그대로 가져오지 말고 자체 평가에서 새 effort 스윕을 실행하세요. Effort를 참고하세요. -
1M 컨텍스트 창이 기본값: Claude Opus 5.5는 베타 헤더 없이 기본값으로 전체 1M 토큰 컨텍스트 창을 제공해요. 클라이언트가 이전 모델 호환성을 위해 컨텍스트 창 베타 헤더를 전달한다면 제거하세요.
-
대화 중간 시스템 메시지: Claude API, Amazon Bedrock, Google Cloud에서 Claude Opus 5.5는
messages배열의 사용자 턴 직후에role: "system"메시지를 허용해요(배치 규칙 적용). 처음부터 적용되는 지시에는 최상위system필드를 사용하세요. Claude Opus 4.7은messages의role: "system"을 400 오류로 거부해요. 지시를 업데이트하기 위해 전체 메시지 기록을 재구축하는 코드 경로를 유지한다면, 그것을 단순화하고 이전 턴의 프롬프트 캐시 히트를 보존할 수 있어요. -
거절 stop details: 모델이 요청을 거절할 때 Claude Opus 5.5는
refusalstop reason과 함께 거절의 카테고리를 명명하는stop_details객체를 반환해요. Claude Opus 4.7도 같은 객체를 반환하므로, stop-reason 처리가 아직 읽지 않는다면에만 관련돼요. 베타 헤더는 필요 없고 옵트아웃도 없어요. stop-reason 처리가 아직 읽지 않는다면 Stop reasons 처리를 참고하세요. Claude Opus 5.5는 더 많은 카테고리로 거절해요. 안전 분류기와 폴백을 참고하세요. -
Fast mode: Claude Opus 5.5는 Claude API에서 fast mode(연구 프리뷰)를 지원해요. Fast mode는 Claude Opus 4.7에서 제공되지 않으며
speed: "fast"가 있는 요청은 오류를 반환해요.fast-mode-2026-02-01베타 헤더로speed: "fast"를 설정하세요. -
컴퓨터 사용 툴셋과 브라우저 사용 도구: Claude API와 Google Cloud에서 Claude Opus 5.5는
computer_toolset_20260801툴셋으로 컴퓨터 사용과, 웹 페이지 내 작업을 위한 브라우저 사용 도구를 지원해요. Claude Opus 4.7은 둘 다 지원하지 않아요. 그 플랫폼에서 Claude Opus 5.5는 이전computer_20251124도구를 허용하지 않아요. 컴퓨터 사용 호환성 파괴 변경을 참고하세요.
Claude Opus 4.6 및 그 이전 Opus 모델에서 Claude Opus 5.5로 마이그레이션
먼저 모든 이전 섹션을 페이지 순서대로 읽으세요. 그것들은 Claude Opus 5.5에 대한 모든 요청이 만족해야 하는 조건, 모든 응답에서 thinking 처리, 그리고 Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7 섹션이에요. 그 섹션들은 Claude Opus 4.6의 코드에 그대로 적용돼요. Claude Opus 4.7과 마찬가지로 thinking: {"type": "disabled"}, 강제 도구 선택, computer_20251124 도구를 허용해요. 기본 effort가 high이고 요청하지 않으면 thinking 없이 실행돼요. Claude Opus 4.5 및 그 이전 Opus 모델도 thinking: {"type": "disabled"}와 강제 도구 선택을 허용하고, 요청하지 않으면 thinking 없이 실행되므로 그 섹션들이 그것들에도 적용돼요.
이 섹션은 대체할 모델 ID로 claude-opus-4-6을 사용해 Claude Opus 4.7에서 변경된 것을 추가해요. 그 두 하위 섹션은 Claude Opus 4.5 이하와 Claude 4.1 이하의 독자를 위해 그 이전에 변경된 것을 추가해요. 체크리스트는 마이그레이션 체크리스트에서 여러분의 모델을 명명한 그룹까지 참고하세요.
호환성 파괴 변경
-
Extended thinking 제거됨:
thinking: {"type": "enabled", "budget_tokens": N}은 Claude Opus 4.7 이상 모델에서 더 이상 지원되지 않으며 400 오류를 반환해요. adaptive thinking(thinking: {"type": "adaptive"})으로 전환하고 thinking 깊이를 제어하려면 effort 파라미터를 사용하세요. Claude Opus 5.5에서는 adaptive thinking이 항상 켜져 있어요:thinking: {"type": "adaptive"}는 유효하고thinking필드를 완전히 생략하는 것과 동등해요.Before (Claude Opus 4.6):
```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHR...KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-4-6", "max_tokens": 16000, "thinking": { "type": "enabled", "budget_tokens": 10000 }, "messages": [ { "role": "user", "content": "..." } ] }' ``` ant messages create <<'YAML' model: claude-opus-4-6 max_tokens: 16000 thinking: type: enabled budget_tokens: 10000 messages: - role: user content: "..." YAMLclient.messages.create( model="claude-opus-4-6", max_tokens=16000, thinking={"type": "enabled", "budget_tokens": 10000}, messages=[{"role": "user", "content": "..."}], )await client.messages.create({ model: "claude-opus-4-6", max_tokens: 16000, thinking: { type: "enabled", budget_tokens: 10000 }, messages: [{ role: "user", content: "..." }] });using Anthropic; using Anthropic.Models.Messages; AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = "claude-opus-4-6", MaxTokens = 16000, Thinking = new ThinkingConfigEnabled(budgetTokens: 10000), Messages = [new() { Role = Role.User, Content = "..." }] }; var response = await client.Messages.Create(parameters); Console.WriteLine(response);client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: "claude-opus-4-6", MaxTokens: 16000, Thinking: anthropic.ThinkingConfigParamOfEnabled(10000), Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("...")), }, }) if err != nil { log.Fatal(err) } fmt.Println(response)AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model("claude-opus-4-6") .maxTokens(16000L) .enabledThinking(10000L) .addUserMessage("...") .build(); Message response = client.messages().create(params); IO.println(response);$client = new Client(); $message = $client->messages->create( maxTokens: 16000, messages: [['role' => 'user', 'content' => '...']], model: 'claude-opus-4-6', thinking: ['type' => 'enabled', 'budget_tokens' => 10000], );client = Anthropic::Client.new message = client.messages.create( model: "claude-opus-4-6", max_tokens: 16000, thinking: { type: "enabled", budget_tokens: 10000 }, messages: [ { role: "user", content: "..." } ] )After (Claude Opus 5.5), 모델 ID,
thinking,output_config줄이 다릅니다:```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHR...KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 16000, "thinking": { "type": "adaptive" }, "output_config": { "effort": "high" }, "messages": [ { "role": "user", "content": "..." } ] }' ``` ant messages create <<'YAML' model: claude-opus-5-5 max_tokens: 16000 thinking: type: adaptive output_config: effort: high messages: - role: user content: "..." YAMLclient.messages.create( model="claude-opus-5-5", max_tokens=16000, thinking={"type": "adaptive"}, output_config={"effort": "high"}, # or "max", "xhigh", "medium", "low" messages=[{"role": "user", "content": "..."}], )await client.messages.create({ model: "claude-opus-5-5", max_tokens: 16000, thinking: { type: "adaptive" }, output_config: { effort: "high" }, // or "max", "xhigh", "medium", "low" messages: [{ role: "user", content: "..." }] });using Anthropic; using Anthropic.Models.Messages; AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = "claude-opus-5-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);client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: "claude-opus-5-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)AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model("claude-opus-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);$client = new Client(); $message = $client->messages->create( maxTokens: 16000, messages: [['role' => 'user', 'content' => '...']], model: 'claude-opus-5-5', thinking: ['type' => 'adaptive'], outputConfig: ['effort' => 'high'], // or 'max', 'xhigh', 'medium', 'low' );client = Anthropic::Client.new message = client.messages.create( model: "claude-opus-5-5", max_tokens: 16000, thinking: { type: "adaptive" }, output_config: { effort: "high" # or "max", "xhigh", "medium", "low" }, messages: [ { role: "user", content: "..." } ] )Adaptive thinking은 프롬프팅과 effort 파라미터를 통해 조정 가능하며, 이 파라미터가 모델이 얼마나 추론할지 제어하는 방법으로 thinking 예산을 대체해요.
budget_tokens값을 변환하지 말고 자체 평가에서 effort 스윕을 실행하세요. effort 수준 표는 각 수준을 언제 사용할지 설명하고, Claude Opus 5.5 권장 effort 수준은 이 모델을 다뤄요. -
샘플링 파라미터 제거됨: Claude Opus 4.7 및 그 이후 모델(Claude Opus 5.5 포함)에서
temperature,top_p,top_k를 비기본값으로 설정하면 400 오류를 반환해요. Python SDK(1.0 이상)는 그것들을 정의하지 않으며, 전달하면TypeError가 발생해요. 가장 안전한 마이그레이션 경로는 요청 페이로드에서 이 파라미터들을 완전히 생략하는 것이에요. 프롬프팅이 Claude Opus 5.5에서 모델 동작을 안내하는 권장 방식이에요. 결정성을 위해temperature = 0을 사용했었다면, 이전 모델에서도 동일한 출력을 보장하지 않았다는 점에 주의하세요. -
Thinking 콘텐츠가 기본적으로 생략됨: thinking 블록은 Claude Opus 4.7 이상 모델의 응답 스트림에 여전히 나타나지만, 명시적으로 옵트인하지 않으면
thinking필드가 비어 있어요. Claude Opus 4.6(기본값이 요약 thinking 텍스트를 반환하던)에서 온 무언의 변경이에요. 복원하려면 모든 응답에서 thinking 처리의 항목 4를 참고하세요. -
토큰 계산 업데이트: Claude Opus 4.7은 새 토크나이저를 도입했고, 이후 Opus 모델(Claude Opus 5.5 포함)도 그것을 사용해요. 이것은 광범위한 작업에서 성능 향상에 기여하며, Claude Opus 4.7 이전 모델과 비교해 텍스트 처리 시 대략 1배에서 1.35배 많은 토큰을 사용할 수 있어요(콘텐츠에 따라 최대 약 35% 증가).
/v1/messages/count_tokens는 Claude Opus 4.6 때보다 Claude Opus 5.5에 대해 다른 토큰 수를 반환해요. 토큰 효율은 워크로드 형태에 따라 다를 수 있어요.압축 트리거를 포함해 추가 여유를 주도록
max_tokens파라미터를 업데이트하고, 토큰을 클라이언트 측에서 추정하거나 고정 토큰 대 문자 비율을 가정하는 코드 경로를 다시 테스트하세요. 토큰 계산 엔드포인트로 확인하세요. 프롬프팅 개입,task_budget,effort가 비용 제어에 도움이 될 수 있어요. 이 제어들은 모델 지능과 상충될 수 있어요. -
프리필 제거(Claude Opus 4.6에서 이미 시행됨): assistant 메시지 프리필은 Claude Opus 4.6 이상 Opus 모델(Claude Opus 5.5 포함)에서 400 오류를 반환해요. 그래서 Claude Opus 4.5 이하에서 온 경우에만 변경 사항이에요. 대신 구조화된 출력, 시스템 프롬프트 지시, 또는
output_config.format을 사용하세요.
동작 변경
Claude Opus 4.7은 API 호환성 파괴가 아닌 Claude Opus 4.6과의 동작 차이를 도입했어요. 다음 세 가지가 코드나 스캐폴딩에 영향을 줘요:
-
에이전트 트레이스의 내장 진행 상황 업데이트: Claude Opus 4.7은 긴 에이전트 트레이스 전반에 걸쳐 사용자에게 더 규칙적이고 고품질의 업데이트를 제공해요. 중간 상태 메시지("도구 호출 3회마다 진행 상황 요약")를 강제하기 위해 스캐폴딩을 추가했다면 제거해 보세요. Claude Opus 5.5에서 이 업데이트는
thinking블록으로 도착하며 기본thinking.display에서 비어 있어요. 받으려면 도구 호출 사이의 텍스트가 thinking 블록으로 반환됨을 참고하세요. 길이와 내용을 만들려면 사용자 대상 진행 상황 업데이트를 참고하세요. -
실시간 사이버 보안 안전장치: Claude Opus 4.7에서 새로 추가되었으며, 금지되거나 고위험 주제가 포함된 요청은 거절로 이어질 수 있어요. 침투 테스트, 취약점 연구, 레드팀 같은 합법적인 보안 작업은 Cyber Verification Program에 신청해 제한 완화를 요청하세요. 신청 경로는 Claude에 어떻게 접근하는지에 따라 달라요.
-
고해상도 이미지 지원: Claude Opus 4.7은 고해상도 이미지 지원을 갖춘 첫 Claude 모델이에요. 최대 이미지 해상도는 이전 모델의 1,568픽셀에서 긴 쪽 기준 2,576픽셀로 증가했어요. 이것은 비전 중심 워크로드에서 성능 향상을 열어주며 특히 컴퓨터 사용, 스크린샷 이해, 문서 분석에 가치가 있어요.
고해상도 지원은 자동이며 베타 헤더나 클라이언트 측 옵트인이 필요 없어요. 계획할 두 가지가 있어요:
- 전체 해상도 이미지는 이전 모델보다 최대 약 3배 더 많은 이미지 토큰을 사용할 수 있어요(이전 캡이 이미지당 약 1,600토큰이었던 것에 비해 이미지당 최대 4,784토큰). 이미지 중심 워크로드의
max_tokens과 비용 기대치를 다시 예산으로 잡거나, 추가 디테일이 필요하지 않다면 보내기 전에 다운샘플하세요. - 모델이 반환하는 포인팅 및 바운딩 박스 좌표는 Claude Opus 4.7에서 실제 이미지 픽셀과 1:1이므로 배율 변환이 필요 없어요.
자세한 내용은 Claude Opus 4.7의 고해상도 이미지 지원을 참고하세요.
- 전체 해상도 이미지는 이전 모델보다 최대 약 3배 더 많은 이미지 토큰을 사용할 수 있어요(이전 캡이 이미지당 약 1,600토큰이었던 것에 비해 이미지당 최대 4,784토큰). 이미지 중심 워크로드의
프롬프트 측 차이는 Claude Opus 5.5 프롬프팅과 프롬프팅 모범 사례를 참고하세요.
Claude Opus 4.5 이하에서 마이그레이션
Claude Opus 4.5, Claude Opus 4.1, 또는 그 이전 모델에서 Claude Opus 5.5로 직접 마이그레이션한다면 이 페이지를 위에서부터 읽으세요. 먼저 모든 이전 섹션을 페이지 순서대로 읽으세요. 그런 다음 이 섹션 앞부분의 Claude Opus 4.6에서 마이그레이션하기 위한 호환성 파괴 변경을 읽으세요. 그런 다음 Claude Opus 4.5와 Claude Opus 4.7 사이에 효력을 발생한 다음 누적 변경 사항을 적용하세요. Claude Opus 4.1 이하라면 이 하위 섹션 후에 Claude 4.1 이하에서 마이그레이션을 계속 읽으세요.
호환성 파괴 변경
-
프리필 제거는 Claude Opus 4.6에서 마이그레이션하기 위한 호환성 파괴 변경에서 다뤄요.
-
도구 파라미터 따옴표 처리: Claude Opus 4.6 이상 모델은 도구 호출 인자에서 약간 다른 JSON 문자열 이스케이핑을 만들 수 있어요(예: 유니코드 이스케이프나 슬래시 이스케이프 처리의 차이). 도구 호출
input을 JSON 파서 대신 원시 문자열로 파싱한다면 파싱 로직을 확인하세요. 표준 JSON 파서(json.loads()또는JSON.parse()같은)는 이 차이를 자동으로 처리해요.
권장 변경
첫 번째 항목은 Claude Opus 5.5에서 필수이고, 나머지는 권장이에요.
-
Adaptive thinking으로 마이그레이션 (필수):
thinking: {"type": "enabled", "budget_tokens": N}은 Claude Opus 4.7 이상 모델에서 400 오류를 반환해요. before and after는 Claude Opus 4.6에서 마이그레이션하기 위한 호환성 파괴 변경의 항목 1이에요. 마이그레이션은 또한client.beta.messages.create에서client.messages.create로 이동해요. adaptive thinking과 effort는 베타 SDK 네임스페이스나 베타 헤더를 요구하지 않아요. -
Effort 베타 헤더 제거: effort 파라미터는 베타 헤더를 요구하지 않아요. 요청에서
betas=["effort-2025-11-24"]를 제거하세요. -
Fine-grained tool streaming 베타 헤더 제거: Fine-grained tool streaming은 베타 헤더를 요구하지 않아요. 요청에서
betas=["fine-grained-tool-streaming-2025-05-14"]를 제거하세요. -
Interleaved thinking 베타 헤더 제거: adaptive thinking으로 interleaved thinking은 adaptive thinking을 지원하는 모든 모델에서 자동이에요. 요청에서
betas=["interleaved-thinking-2025-05-14"]를 제거하세요. -
output_config.format으로 마이그레이션: 구조화된 출력을 사용한다면
output_format={...}를output_config={"format": {...}}로 업데이트하세요. API는 여전히 더 이상 사용되지 않는output_format파라미터를 허용하지만, 향후 모델 릴리스에서 제거될 거예요. Python SDK(1.0 이상)는client.beta.messages.create()나count_tokens()에서output_format={...}을 허용하지 않아요.parse()와stream()헬퍼의output_format=Model인자는 변함이 없어요.
Claude 4.1 이하에서 마이그레이션
Claude Opus 4.1 또는 그 이전 모델에서 Claude Opus 5.5로 직접 마이그레이션한다면, 먼저 Claude Opus 4.5 이하에서 마이그레이션의 모든 것을 적용하세요. 그 하위 섹션은 모든 이전 섹션으로 시작하므로, 사실상 이 페이지를 위에서부터 읽게 돼요. 그런 다음 이 하위 섹션의 추가 변경을 적용하세요.
추가 호환성 파괴 변경
-
샘플링 파라미터 제거: 샘플링 파라미터 제거됨에서 다뤄요.
-
도구 버전 업데이트
Claude 3.x 모델에서 마이그레이션할 때의 호환성 파괴 변경이에요. 현재 도구 버전으로 업데이트하세요.
undo_edit명령을 사용하는 코드는 제거하세요.```python Python # Before tools = [{"type": "text_editor_20250124", "name": "str_replace_editor"}] After
tools = [{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]
```typescript TypeScript // Before const legacyTools = [{ type: "text_editor_20250124", name: "str_replace_editor" }]; // After const tools = [{ type: "text_editor_20250728", name: "str_replace_based_edit_tool" }];var parameters = new MessageCreateParams { // Before: {"type": "text_editor_20250124", "name": "str_replace_editor"} // After: Tools = [new ToolTextEditor20250728()], // ... };params := anthropic.MessageNewParams{ // Before: {"type": "text_editor_20250124", "name": "str_replace_editor"} // After: Tools: []anthropic.ToolUnionParam{ {OfTextEditor20250728: &anthropic.ToolTextEditor20250728Param{}}, }, // ... }MessageCreateParams params = MessageCreateParams.builder() // Before: {"type": "text_editor_20250124", "name": "str_replace_editor"} // After: .addTool(ToolTextEditor20250728.builder().build()) // ... .build();$message = $client->messages->create( // Before: ['type' => 'text_editor_20250124', 'name' => 'str_replace_editor'] // After: tools: [new ToolTextEditor20250728()], // ... );# Before legacy_tools = [{type: "text_editor_20250124", name: "str_replace_editor"}] # After tools = [{type: "text_editor_20250728", name: "str_replace_based_edit_tool"}]- 텍스트 편집기:
text_editor_20250728과str_replace_based_edit_tool을 사용하세요. 자세한 내용은 텍스트 편집기 도구 문서를 참고하세요. - 코드 실행:
code_execution_20260521으로 업그레이드하세요. 마이그레이션 지침은 코드 실행 도구 문서를 참고하세요. - 컴퓨터 사용: Claude API와 Google Cloud에서 Claude Opus 5.5는 컴퓨터 사용을
computer_toolset_20260801툴셋으로만 허용해요. 이전computer_20250124와computer_20251124도구는 거기서 거부돼요. 컴퓨터 사용 호환성 파괴 변경을 참고하세요.
- 텍스트 편집기:
-
refusalstop reason 처리거절 stop reason 처리를 위해 애플리케이션을 업데이트하세요:
```python Python response = client.messages.create(...) if response.stop_reason == "refusal": # Handle refusal appropriately pass
```typescript TypeScript const response = await client.messages.create(/* ... */); if (response.stop_reason === "refusal") { // Handle refusal appropriately }var response = await client.Messages.Create(...); if (response.StopReason?.Value() == StopReason.Refusal) { // Handle refusal appropriately }response, _ := client.Messages.New(ctx, params) // your existing request if response.StopReason == anthropic.StopReasonRefusal { // Handle refusal appropriately }Message response = client.messages().create(...); StopReason reason = response.stopReason().orElse(StopReason.END_TURN); if (reason.equals(StopReason.REFUSAL)) { // Handle refusal appropriately }$response = $client->messages->create(...); if ($response->stopReason === 'refusal') { // Handle refusal appropriately }response = client.messages.create(...) if response.stop_reason == :refusal # Handle refusal appropriately end -
model_context_window_exceededstop reason 처리Claude 4.5 이상 모델은 요청된
max_tokens한도가 아니라 컨텍스트 창 한도에 도달해 생성이 멈추면model_context_window_exceededstop reason을 반환해요. 애플리케이션을 업데이트해 이 새 stop reason을 처리하세요:```python Python response = client.messages.create(...) if response.stop_reason == "model_context_window_exceeded": # Handle context window limit appropriately pass
```typescript TypeScript const response = await client.messages.create(/* ... */); if (response.stop_reason === "model_context_window_exceeded") { // Handle context window limit appropriately }var response = await client.Messages.Create(...); if (response.StopReason?.Raw() == "model_context_window_exceeded") { // Handle context window limit appropriately }response, _ := client.Messages.New(ctx, params) // your existing request if response.StopReason == "model_context_window_exceeded" { // Handle context window limit appropriately }Message response = client.messages().create(...); StopReason reason = response.stopReason().orElse(StopReason.END_TURN); if (reason.equals(StopReason.of("model_context_window_exceeded"))) { // Handle context window limit appropriately }$response = $client->messages->create(...); if ($response->stopReason === 'model_context_window_exceeded') { // Handle context window limit appropriately }response = client.messages.create(...) if response.stop_reason == :model_context_window_exceeded # Handle context window limit appropriately end -
도구 파라미터 처리 검증 (후행 개행)
Claude 4.5 이상 모델은 이전에 제거되던 도구 호출 문자열 파라미터의 후행 개행을 보존해요. 도구가 도구 호출 파라미터에 대한 정확한 문자열 매칭에 의존한다면 로직이 후행 개행을 올바르게 처리하는지 확인하세요.
-
동작 변경에 맞게 프롬프트 업데이트
Claude 4 이상 모델은 더 간결하고 직접적인 커뮤니케이션 스타일을 가지며 명시적인 지시를 요구해요. 최적화 지침은 프롬프팅 모범 사례를 검토하세요.
추가 권장 변경
- 레거시 베타 헤더 제거:
token-efficient-tools-2025-02-19와output-128k-2025-02-19를 제거하세요. 모든 Claude 4 이상 모델은 내장된 토큰 효율적 도구 사용을 가지며 이 헤더들은 효과가 없어요.
Claude Sonnet 5에서 Claude Opus 5.5로 마이그레이션
Claude Opus 5.5에 대한 모든 요청이 만족해야 하는 조건, 모든 응답에서 thinking 처리, Claude Opus 5에서 Claude Opus 5.5로 마이그레이션을 읽으세요. 대체할 모델 ID로 claude-sonnet-5를 사용하세요. 그 마지막 섹션은 Claude Sonnet 5의 코드에 그대로 적용되는데, Claude Sonnet 5는 Claude Opus 5와 마찬가지로:
- 기본값으로 thinking 켜짐으로 실행되고 어떤 effort 수준에서든
thinking: {"type": "disabled"}를 허용해요. - 강제 도구 선택과
computer_20251124도구를 허용해요. - 도구 호출 사이의 텍스트를
text블록으로 반환해요. - 기본 effort가
high예요.
수동 extended thinking, 비기본 샘플링 파라미터, assistant 프리필은 두 모델 모두에서 400 오류를 반환하므로 거기서는 변하지 않아요. Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 섹션의 필수 변경은 여러분에게 적용되지 않아요.
변경된 내용
-
대화 중간 시스템 메시지: Claude API, Amazon Bedrock, Google Cloud에서 Claude Opus 5.5는
messages배열의 사용자 턴 직후에role: "system"메시지를 허용해요(배치 규칙 적용). 이 기능은 Claude Sonnet 5에서 제공되지 않아요. 지시를 업데이트하기 위해 전체 메시지 기록을 재구축하는 코드 경로를 유지한다면, 그것을 단순화하고 이전 턴의 프롬프트 캐시 히트를 보존할 수 있어요. -
프롬프트 캐싱 최소값 낮아짐: Claude Opus 5.5의 최소 캐시 가능 프롬프트 길이는 Claude Sonnet 5의 1,024 토큰에서 512 토큰으로 낮아졌어요. Claude Sonnet 5에서 캐시하기엔 너무 짧았던 프롬프트가 코드 변경 없이 캐시 항목을 만들 수 있어요. 모델별 최소값은 프롬프트 캐싱을 참고하세요.