Claude Sonnet 5 마이그레이션: 1M 컨텍스트보다 먼저 봐야 할 API 변경점

Claude Sonnet 5가 공개되면서 개발자가 먼저 확인해야 할 지점은 “성능이 좋아졌다”가 아니라 “기존 호출이 그대로 통과하느냐”입니다. Anthropic 릴리스 노트 기준으로 Sonnet 5는 1M 토큰 컨텍스트, 128k 최대 출력, 도구 사용과 Managed Agents 기능을 이어받았습니다. 동시에 몇 가지 API 계약이 바뀌었습니다. 운영 중인 서비스라면 모델명만 바꿔 배포하는 방식은 위험합니다.

이번 글은 신규 모델 홍보가 아니라 마이그레이션 관점에서 정리합니다. 특히 API 파라미터, 토큰 비용, 스트리밍, Managed Agents 운영 항목을 먼저 보겠습니다.

무엇이 바뀌었나

Claude Sonnet 5의 핵심 변경점은 네 가지입니다.

• 모델명은 claude-sonnet-5입니다.
• 2026년 8월 31일까지 입력 $2 / 출력 $10 per MTok의 introductory pricing이 적용되고, 이후 표준 가격은 입력 $3 / 출력 $15 per MTok로 안내됐습니다.
• 1M 토큰 컨텍스트와 128k 최대 출력 토큰을 지원합니다.
• adaptive thinking이 기본값으로 켜졌고, 기존 manual extended thinking 파라미터는 제거됐습니다.

여기서 실제 장애를 만드는 부분은 세 번째보다 네 번째입니다. 기존 코드에 thinking: { type: "enabled", budget_tokens: N } 같은 수동 사고 예산 설정이 남아 있으면 400 에러가 날 수 있습니다. 또한 temperature, top_p, top_k를 비기본값으로 설정한 호출도 거절될 수 있다고 문서에 명시되어 있습니다.

모델 교체 PR에서 가장 먼저 볼 파일은 “프롬프트”가 아니라 API 클라이언트 래퍼입니다. 모든 호출 지점에서 샘플링 파라미터를 공통으로 주입하고 있지 않은지 확인해야 합니다.

왜 1M 컨텍스트가 비용 이슈가 되나

1M 컨텍스트는 긴 문서, 코드베이스, 고객 로그를 한 번에 넣을 수 있다는 장점이 있습니다. 하지만 운영 비용은 컨텍스트 길이에 선형으로 반응합니다. 더 중요한 점은 Sonnet 5가 새 tokenizer를 사용하며 같은 텍스트가 약 30% 더 많은 토큰으로 계산될 수 있다는 안내입니다.

예를 들어 기존 Sonnet 4.6 기준으로 200k 토큰이던 입력이 Sonnet 5에서 260k 토큰 수준으로 측정될 수 있습니다. 가격표만 비교하면 싸 보이는 호출도 실제 토큰 수가 늘면 예상 청구액이 달라집니다.

따라서 마이그레이션 전에는 최소 3종류의 샘플을 토큰 카운팅해야 합니다.

1. 짧은 채팅형 요청: 5~20턴의 일반 사용 패턴
2. 긴 문서형 요청: PDF, 코드, 로그를 포함한 상위 10% 요청
3. 에이전트형 요청: 도구 호출 기록과 중간 결과가 누적되는 요청

평균값만 보면 안 됩니다. 장애와 비용 초과는 대부분 p95, p99 요청에서 발생합니다.

깨지기 쉬운 API 호출 패턴

마이그레이션 때 자주 놓치는 패턴은 다음과 같습니다.

1. 공통 옵션으로 temperature를 넣는 코드

많은 서비스가 모델별 차이를 숨기기 위해 defaultOptions를 둡니다. 여기에 temperature: 0.2가 들어 있으면 Sonnet 5 호출에서 바로 문제가 될 수 있습니다.

안전한 구조는 모델별 allowlist입니다.

• Sonnet 4.x: 기존 옵션 유지
• Sonnet 5: 기본 샘플링만 허용
• 실험 모델: 별도 플래그로만 접근

2. manual thinking budget을 유지하는 코드

수동 extended thinking은 Sonnet 5에서 제거됐습니다. 과거에는 “복잡한 요청에는 budget_tokens를 높인다”는 방식이 통했습니다. 이제는 adaptive thinking을 전제로 프롬프트와 task boundary를 정리하는 쪽이 맞습니다.

3. 긴 컨텍스트를 캐시 없이 매번 재전송하는 코드

1M 컨텍스트가 가능하다는 말은 1M 컨텍스트를 매번 보내도 된다는 뜻이 아닙니다. 장기 대화, 문서 분석, 코드 리뷰 서비스라면 요약, 검색, 청크 캐시, 결과 재사용 레이어가 필요합니다.

Managed Agents 쪽 변경점

이번 릴리스에는 Claude Managed Agents 관련 변경도 같이 들어왔습니다. session event streams는 event_deltas[] 쿼리 파라미터로 메시지 생성 중간 텍스트를 미리 받을 수 있습니다. 사용자-facing 제품에서는 “응답이 멈춘 것처럼 보이는 문제”를 줄이는 데 도움이 됩니다.

또한 세션 목록 조회에 backward pagination이 추가됐고, 세션 생성 시 특정 agent 설정을 세션 단위로 override할 수 있습니다. 운영 관점에서는 꽤 큽니다. 기존에는 agent 설정을 바꾸려면 배포 단위로 건드려야 했지만, 이제 특정 고객, 특정 실험, 특정 장애 재현 세션에만 모델·시스템 프롬프트·도구·MCP 서버를 바꿔 볼 수 있습니다.

다만 override 기능은 거버넌스가 없으면 곧바로 혼란이 됩니다. 누가 어떤 세션에서 어떤 설정을 덮어썼는지 로그를 남기고, 운영 환경에서는 allowlist 기반으로 제한하는 게 좋습니다.

마이그레이션 순서

실무에서는 아래 순서가 안전합니다.

1. 호출 래퍼에서 Sonnet 5 금지 파라미터를 탐지합니다.
2. 샘플 로그 100~1,000건으로 토큰 수를 다시 계산합니다.
3. 동일 입력을 Sonnet 4.6과 Sonnet 5에 보내 품질 차이를 비교합니다.
4. 에러율, 지연 시간, 출력 길이, 비용을 별도 지표로 봅니다.
5. 내부 사용자 또는 낮은 트래픽 경로부터 라우팅 비율을 올립니다.

여기서 “응답 품질이 좋아 보인다”는 주관 평가만으로 배포하면 안 됩니다. 특히 개발자 도구, 고객 지원 자동화, 리포트 생성처럼 결과 검증이 가능한 제품은 평가셋을 먼저 만들어야 합니다.

바로 적용할 체크리스트

• claude-sonnet-5 호출에 temperature, top_p, top_k 비기본값이 들어가지 않는지 확인
• thinking.budget_tokens 등 manual extended thinking 설정 제거
• 기존 대표 요청의 토큰 수를 Sonnet 5 기준으로 재측정
• p95 입력 길이와 p99 비용을 별도 계산
• Managed Agents override 사용 시 감사 로그 추가
• 스트리밍 UI는 event delta 기반으로 중간 상태 표시 검토
• 모델 라우팅을 feature flag로 분리해 즉시 롤백 가능하게 유지

Sonnet 5의 큰 컨텍스트는 장점입니다. 하지만 운영팀 입장에서는 API 계약 변경, tokenizer 변경, 비용 분포 변경이 먼저입니다. 모델을 바꾸기 전에 호출 경로를 정리하면, 새 모델의 이점도 훨씬 안전하게 가져갈 수 있습니다.