Anthropic, Claude Opus 5.5 마이그레이션 가이드 공개

Anthropic이 Claude Opus 5.5 모델의 공식 마이그레이션 및 프롬프팅 가이드를 공개했다. Opus 5.5는 긴 에이전트 코딩과 지식 노동에 최적화되었으며, Opus 5 대비 출력 토큰 생성 속도가 30% 이상 빠르고 동일 작업에 더 적은 토큰을 사용한다. 가격은 입력 $4/1M 토큰, 출력 $20/1M 토큰으로 Opus 5($5/$25)보다 저렴하다.

주요 API 구조 변화

Opus 5.5로 마이그레이션 시 기존 코드에서 400 오류를 방지하기 위해 다음 사항들을 반드시 수정해야 한다.

• Thinking 강제 활성화: thinking: {"type": "disabled"} 옵션이 제거되어 항상 켜진다. 대신 effort 파라미터(low, medium, high, xhigh, max)로 조절하며, 기본값은 high에서 **medium**으로 변경되었다.
• Tool Choice 제한: any, tool 타입이 거부되며 auto 또는 none만 허용된다. 강제 도구 호출이 필요한 경우 Strict tool use나 프롬프트 지시로 대체해야 한다.
• Sampling 파라미터 제거: temperature, top_p, top_k는 기본값 외 설정 시 거부된다.
• Prefill 제거: Assistant 턴으로 끝나는 messages가 거부되며, Structured Outputs나 시스템 프롬프트로 대체해야 한다.
• Computer Use 도구 변경: Claude API와 Google Cloud에서는 computer_toolset_20260801만 지원되며, 이전 computer_20251124는 거부된다 (Amazon Bedrock은 기존 도구 지원 유지).

응답 처리 및 마이그레이션 주의사항

• Thinking 블록 위치: 응답 시작 시 thinking 블록이 먼저 올 수 있어, 위치 기반(content[0]) 읽기 코드를 type 필드 기반으로 수정해야 한다.
• 도구 루프 유지: 직전 assistant 응답의 thinking 블록은 수정 없이 그대로 반환해야 하며, 편집 시 오류가 발생한다.
• 생각 텍스트 표시: 기본값 display: "omitted"에서는 thinking 필드가 비어 있다. 요약이 필요하면 display: "summarized" 또는 베타 기능인 "updates"를 설정해야 한다.
• 모델 간 호환성: Opus 5.5의 thinking 블록은 Opus 5 및 이전 모델에서 읽을 수 있으나, Fable 5.1/Mythos 5.1 외의 다른 모델로 라우팅 시 thinking 블록이 무시될 수 있다.

프롬프팅 가이드 및 성능 팁

• Effort 조정: Opus 5.5의 medium effort는 Opus 5의 high effort와 동등하거나 더 나은 성능을 제공한다. 비용과 지연 시간을 줄이기 위해 low 또는 medium부터 시작하여 측정하는 것이 권장된다.
• 무인 에이전트 안정성: 조기 종료를 방지하기 위해 시스템 프롬프트에 체크리스트 기반의 계속 진행 지시를 추가하고, stop_reason: "end_turn" 처리 로직을 강화해야 한다.
• 안전장치 거절: stop_reason: "refusal" 시 stop_details 객체를 통해 정책 카테고리(cyber, bio, reasoning_extraction 등)를 확인할 수 있으며, 서버 측 대체(fallback) 기능을 활용할 수 있다.