Sonnet 5에서 5.5로 바꾸기 전에 볼 범위
Anthropic은 2026년 9월 28일 Claude Sonnet 5.5를 발표했습니다. 같은 날 Claude Platform 릴리스 노트에는 Claude API, Claude in Amazon Bedrock, Claude Platform on AWS, Claude on Google Cloud, Claude in Microsoft Foundry에서 쓸 수 있다는 출시 항목과 함께 "Code written for Claude Sonnet 5 can break on Claude Sonnet 5.5 in five ways."라는 문장이 올라왔습니다. Sonnet 5용으로 짠 코드가 5.5에서 5개 항목 때문에 동작하지 않을 수 있다는 뜻입니다. 에이전트를 운영한다면 모델 이름만 바꿔 배포하기 전에 코드를 먼저 점검해야 합니다.
릴리스 노트가 꼽은 항목은 thinking을 끄는 방법, 강제 도구 호출, 모델과 대화에 묶인 thinking 블록, Claude API와 Google Cloud에서 예전 computer_20251124 컴퓨터 사용 도구를 받지 않는 점, advisor 도구가 Claude Opus 4.8·Opus 4.7·Sonnet 5를 조언 모델로 받지 않는 점입니다. 같은 날 계정에 묶인 thinking 블록도 별도 항목으로 공지됐습니다. 이 글은 강제 도구 호출, thinking을 끈 설정, 계정에 묶인 thinking 블록을 자세히 다루고, 나머지 항목은 아래 점검표에 한 줄씩 넣었습니다. 성능과 가격 비교는 다루지 않습니다. 아래 그림은 에이전트 요청 1건을 구성 요소로 나누고 각 변경이 어디에 해당하는지 표시했습니다.
교체 일정도 함께 정해야 합니다. 2026년 9월 30일 릴리스 노트에는 Claude Sonnet 4.5(claude-sonnet-4-5-20250929) 지원 중단 공지가 올라왔고, Claude API에서의 종료 예정일은 2026년 11월 30일입니다. 릴리스 노트는 Sonnet 5.5로 옮기라고 권합니다. 마이그레이션 가이드에는 4.5에서 옮길 때 추가로 바꿀 항목(어시스턴트 프리필 제거 등)이 따로 정리돼 있으니, 아직 4.5를 쓰는 에이전트가 있다면 이 글의 항목과 함께 그 절도 확인하십시오.
강제 도구 호출은 400 오류가 납니다
Claude Platform 릴리스 노트에 따르면 Sonnet 5.5에서는 강제 도구 호출, 즉 tool_choice 유형을 any나 tool로 지정한 요청이 400 오류를 반환합니다. tool_choice는 요청을 보낼 때 모델의 도구 사용 방식을 정하는 설정입니다. 마이그레이션 가이드는 토큰 수 계산(token counting) 엔드포인트에서도 같은 오류가 난다고 적었습니다.
예시로, 고객 문의가 들어오면 첫 요청에서 분류 도구를 반드시 부르도록 tool_choice를 tool로 지정해 둔 에이전트를 생각해 보겠습니다. 이 에이전트는 모델 이름만 바꾸면 첫 요청부터 400 오류를 받습니다. 결과를 정해진 형식으로 받으려고 특정 도구 호출을 강제해 둔 추출 작업도 같은 영향을 받습니다.
마이그레이션 가이드는 tool_choice를 auto로 보내고 해당 도구에 strict: true를 지정해 입력이 스키마와 맞도록 하라고 안내합니다. 이렇게 바꾸면 모델이 도구를 부르지 않고 답할 수도 있으므로, 언제 그 도구를 쓸지 프롬프트에 적으라고 합니다. Amazon Bedrock에서는 Sonnet 5.5에 strict 도구 사용을 포함한 구조화 출력을 쓸 수 없어, auto만 보내고 도구 입력은 코드에서 검증하라고 적었습니다. 작성자 해석으로는, 강제 호출에 기대던 분류·추출 단계라면 도구가 호출되지 않은 응답을 어떻게 처리할지도 코드에 넣어 두어야 합니다.
작성자는 오류 처리 코드도 함께 보기를 권합니다. 재시도 로직이 400 오류를 일시 장애로 보고 같은 요청을 반복하게 짜여 있다면, 교체 직후 대기 시간과 호출 횟수만 늘고 에이전트는 계속 멈춰 있게 됩니다. 400은 요청 형식에서 생기는 오류이므로 재시도 대상에서 빠져 있는지 확인합니다.
thinking을 끄고 쓰던 에이전트는 between_tools로 바꿉니다
Anthropic 발표문은 Sonnet을 thinking 없이 쓰고 있다면 Sonnet 5.5로 옮기기 전에 새 between_tools 설정으로 바꿔야 하며, 이 설정이 응답 전에 먼저 하는 thinking(up-front thinking)을 끈 상태로 유지한다고 안내합니다. thinking은 모델이 답을 내기 전에 거치는 추론 과정을 가리킵니다. 릴리스 노트는 요청 형식도 적었습니다. thinking 값을 "disabled" 대신 {"type": "between_tools"}로 보내고, effort(추론 강도) 설정은 high 이하로 두어야 합니다.
마이그레이션 가이드에 따르면 Sonnet 5.5에 disabled를 보내면 400 invalid_request_error가 나고, between_tools를 xhigh나 max effort와 함께 보내도 400 오류가 납니다. between_tools에는 display나 budget_tokens 같은 다른 필드를 붙일 수 없고, 대화 중간에 effort를 바꿀 수도 없습니다. 도구 호출 사이에 모델이 쓰는 짧은 진행 메모는 thinking 블록으로 반환됩니다.
응답 속도나 비용을 이유로 thinking을 꺼 둔 에이전트라면 이 항목이 해당합니다. 이런 설정은 코드에 직접 적혀 있기도 하고, 환경 변수나 설정 파일에 따로 있기도 합니다. 개발·스테이징·운영 환경의 thinking 값과 effort 값을 모두 찾아 모델 이름과 같은 배포에서 바꿔야 한 환경만 예전 설정으로 400 오류를 내는 일을 막을 수 있습니다.
thinking 블록은 만든 계정 안에서만 쓰입니다
Claude Platform 릴리스 노트에는 "Thinking blocks that Claude Sonnet 5.5 produces work only in the account that produced them, or in an account linked to it."라는 문장이 있습니다. Sonnet 5.5가 만든 thinking 블록은 그 블록을 만든 계정이나 그 계정에 연결된 계정에서만 동작한다는 뜻입니다. 릴리스 노트는 다른 계정이 이 블록을 보내면 API가 모델이 보기 전에 블록을 빼고 요청은 그대로 성공한다고 적었습니다. 이전 모델이 만든 블록은 영향을 받지 않습니다.
요청이 성공하므로 오류 기록만 봐서는 블록이 빠졌는지 알 수 없습니다. 대화 기록에 이전 응답의 thinking 블록을 담아 다음 요청에 다시 보내는 에이전트라면 계정이 바뀌는 흐름을 찾아야 합니다. 예시로, 대화 기록을 저장소에 보관했다가 다른 계정의 API 키로 이어서 처리하는 구조, 개발 계정에서 쌓은 대화 기록을 운영 계정에서 다시 쓰는 테스트, 협력사 계정과 대화 기록을 주고받는 연동이 여기에 해당할 수 있습니다.
어떤 계정이 연결된 계정으로 인정되는지는 릴리스 노트에 적혀 있지 않으니, 릴리스 노트가 안내하는 Preserved thinking 문서에서 확인하십시오. 마이그레이션 가이드는 이와 별도로 Sonnet 5.5의 thinking 블록이 앞선 대화 내용에 서명돼 있어, 2026년 8월 31일 00:00 UTC 이후 만든 계정에서는 앞부분 기록을 고친 뒤 블록을 다시 보내면 400 오류가 난다고 적었습니다. 대화 기록은 뒤에 덧붙이는 방식(append-only)으로만 쓰라는 안내도 있습니다. 긴 대화를 중간에 요약하거나 고쳐 쓰는 에이전트라면 이 부분도 함께 확인해야 합니다.
교체 전 점검표
아래 표의 원문 근거 칸은 공식 문서의 내용이고, 코드에서 찾을 것과 교체 전 확인할 일은 작성자가 구성했습니다. 마지막 2줄은 이 글에서 자세히 다루지 않은 릴리스 노트 항목입니다.
| 항목 | 원문 근거 | 코드에서 찾을 것 | 교체 전 확인할 일 |
|---|---|---|---|
| 강제 도구 호출 | tool_choice 유형 any와 tool은 400 오류 (릴리스 노트) | tool_choice를 지정하는 모든 요청 | auto와 strict 도구로 바꾸고, 400 오류가 재시도 대상에서 빠져 있는지 확인 |
| thinking을 끈 설정 | disabled 대신 between_tools, effort는 high 이하 (릴리스 노트) | 환경별 thinking·effort 설정 값 | 개발·스테이징·운영 설정을 모델 이름과 함께 바꿨는지 확인 |
| 계정에 묶인 thinking 블록 | 다른 계정이 보내면 오류 없이 블록이 빠짐 (릴리스 노트) | 대화 기록을 다른 계정으로 넘기는 흐름 | 계정이 바뀌는 단계를 목록으로 만들고 연결 계정 조건을 문서로 확인 |
| 대화 기록 수정 | 2026년 8월 31일 이후 만든 계정은 앞부분을 고친 뒤 블록을 다시 보내면 400 오류 (마이그레이션 가이드) | 대화 기록을 요약하거나 고쳐 쓰는 코드 | 기록을 뒤에 덧붙이는 방식으로만 쓰는지 확인 |
| 컴퓨터 사용 도구 | Claude API·Google Cloud에서 computer_20251124를 받지 않음 (릴리스 노트) | 컴퓨터 사용 도구 버전 | 마이그레이션 가이드의 도구 버전 표에 맞춰 바꿨는지 확인 |
| advisor 도구 | Opus 4.8·Opus 4.7·Sonnet 5를 조언 모델로 받지 않음 (릴리스 노트) | advisor 도구의 조언 모델 설정 | 지원하는 조언 모델로 바꿨는지 확인 |
이번 주에 해 볼 첫 단계
운영 중인 에이전트 저장소 1곳을 골라 tool_choice, thinking·effort 설정, 대화 기록을 저장하거나 고쳐 쓰거나 다른 계정으로 넘기는 코드를 검색하고, 위 표의 코드에서 찾을 것 칸을 채워 보십시오. 해당하는 코드가 나오면 스테이징 계정에서 대표 대화 1건을 Sonnet 5.5로 실행해 400 오류가 나는지, thinking 설정이 의도대로 적용되는지 확인합니다. 표의 나머지 항목도 해당 여부를 표시한 뒤에 운영 환경의 모델 이름을 claude-sonnet-5-5로 바꾸십시오.
이 글은 Claude Platform 릴리스 노트, Anthropic 발표문, 마이그레이션 가이드를 읽고 정리했으며 직접 실행해 확인하지는 않았습니다.