TL;DR
Claude Sonnet 5.5는 범위가 명확한 코딩, 문서, 도구 활용 워크플로에 적합한 고속 모델입니다. Anthropic은 동일한 표준 토큰 요율에서 Sonnet 5 대비 출력 속도가 30% 이상 빨라졌다고 보고합니다. CometAPI 키, 모델 ID claude-sonnet-5-5, 간단한 Messages 또는 Chat Completions 요청부터 시작하세요. 기존 에이전트는 롤아웃 전 사고 과정, 도구 선택, 히스토리 재생을 재검증해야 합니다.
핵심 정리
- Claude Sonnet 5.5를 사용하고, 요청 형식을 사용 중인 엔드포인트에 맞추세요.
- 이미지, 도구, 긴 컨텍스트를 추가하기 전에 짧은 요청 1건부터 시작하세요.
- Claude 고유 제어가 필요하면 Messages를, 기존 OpenAI SDK 앱에는 Chat Completions를 사용하세요.
- 기존 에이전트 루프를 마이그레이션하기 전에 사고 과정과 도구 선택 변화를 점검하세요.
- 트래픽 확대 전에 승인된 작업 품질, 지연 시간, 토큰 사용량, 캐시 적중률을 비교하세요.
Claude Sonnet 5.5란?
Claude Sonnet 5.5 API는 Anthropic의 Sonnet 5.5 모델을 위한 프로그래매틱 인터페이스입니다. 소프트웨어 개발, 리포지토리 분석, 고객 지원 자동화, 문서 처리, 이미지 이해, 도구 활용 에이전트, 구조화된 전문 워크플로 같은 작업을 위해 설계되었습니다.
Anthropic은 Sonnet 5.5를 Claude 5.5 제품군의 두 번째 모델인 Opus 5.5를 보완하는 더 빠르고 저렴한 모델로 포지셔닝하며, 범위가 명확한 코딩, 버그 수정, 문서 및 슬라이드 작성, 일상적인 전문 업무에 최적화되어 있다고 설명합니다. 개발자는 CometAPI에서 claude-sonnet-5-5로 Claude Sonnet 5.5 API에 액세스할 수 있습니다.
| Specification | Claude Sonnet 5.5 |
|---|---|
| Provider | Anthropic |
| Model ID | claude-sonnet-5-5 |
| Release date | September 28, 2026 |
| Context window | 1M tokens |
| Maximum synchronous output | 128K tokens |
| Batch maximum output | Up to 300K tokens in supported beta configuration |
| Inputs | Text, images |
| Output | Text |
| Thinking | Adaptive thinking |
| Default Claude API effort | High |
| Knowledge cutoff | June 2026 |
| Input price (Anthropic / CometAPI) | $2.00 / $1.60 per 1M tokens |
| Output price (Anthropic / CometAPI) | $10.00 / $8.00 per 1M tokens |
Anthropic은 1M 토큰 컨텍스트 윈도와 128K 동기 출력 한도를 확인했습니다. 배치 출력은 Message Batches와 output-300k-2026-03-24 베타 헤더를 통해서만 300K 토큰에 도달할 수 있습니다. Gateway 기능 지원은 모델 수준 지원과 별도로 확인해야 합니다.
공식 벤치마크에서 Claude Sonnet 5.5 성능은?
아래 간결한 비교는 API 도입 전에 평가할 워크로드를 식별하는 데 도움이 됩니다. 벤치마크 결과는 자체 프롬프트와 도구 루프 테스트를 대체하지 않습니다.
| Benchmark | Claude Sonnet 5.5 | Claude Sonnet 5 | Claude Opus 5.5 |
|---|---|---|---|
| Terminal-Bench 4.0 | 70.6% | 10.3% | 66.4% at Xhigh |
| FrontierCode 1.1 Main | 46.2% at Max / 52.1% at Xhigh | 42.4% | 54.4% |
| CursorBench 4.0 | 55.5% | 34.1% | 57.8% |
| GDPval-AA v2.1 | 1844 | 1449 | 1846 |
| OSWorld 2.1, partial | 80.1% | 57.0% | 81.8% |
| AA-Briefcase v1.1 | 1811 | 1359 | 1822 |
| Humanity’s Last Exam, with tools | 64.5% | 54.9% | 67.7% |
| Chartography, no tools | 61.6% | 15.6% | 64.4% |
Anthropic의 벤치마크 결과와 평가 노트는 이 비교의 근거를 제공합니다. Opus 5.5의 Terminal-Bench 결과는 Xhigh effort를 사용합니다. FrontierCode는 Sonnet 5.5에 대해 Max와 Xhigh 결과를 별도로 보고합니다. OSWorld는 부분 평가입니다. GDPval-AA와 AA-Briefcase는 Artificial Analysis가 사전 배포된 Claude Platform에서 구조화 출력 버그가 있는 상태로 실행했고, 이 버그가 Sonnet 5.5의 점수를 과소평가했을 가능성이 있습니다. Anthropic은 이후 버그가 수정되었다고 밝혔습니다. 이러한 결과는 프로덕션 성능을 보장하기보다 워크로드 테스트를 안내하는 용도로 사용해야 합니다. Humanity’s Last Exam은 도구를 사용하며, Chartography는 사용하지 않습니다. 새로 추가된 행은 Anthropic의 공개 점수를 사용합니다. 아래 원본 이미지는 유지되며, 확장된 표에는 세 가지 추가 평가가 포함됩니다.
공식 Claude Sonnet 5.5 벤치마크 비교
Sonnet 5 대비 Claude Sonnet 5.5 API의 변경점
| Dimension | Claude Sonnet 5.5 | Migration impact |
|---|---|---|
| Output speed | 30%+ faster reported generation | Re-baseline latency |
| Official token rates | Same $2 input / $10 output per MTok | Compare total task cost |
| Lowest thinking setting | between_tools replaces disabled | Update thinking configuration |
| Forced tool choice | any and named forcing rejected | Use auto; sequence required steps in code |
| Thinking history | Signed to conversation and account | Preserve blocks and stable history |
| Computer use compatibility | computer_20251124 rejected on Claude API / Google Cloud | Migrate to computer_toolset_20260801; verify gateway support |
| Advisor model compatibility | Earlier advisor pairings rejected | Choose a supported advisor, such as Opus 5.5 |
사고 과정, 도구 선택, 히스토리 재생에 대한 마이그레이션 변화는 기존 에이전트 루프에 영향을 줍니다. 표는 이러한 운영상의 변화를 요약하며, 완전한 기능 목록은 아닙니다.
점검해야 할 중대한 변경 사항
다섯 가지 중대한 변경 사항을 모두 점검하세요: disabled 사고 과정을 between_tools로 교체, 강제 도구 선택 제거, 호환 가능한 사고 블록과 변경되지 않은 대화 히스토리 보존, Claude API 및 Google Cloud에서 computer_20251124를 computer_toolset_20260801로 마이그레이션, 지원되지 않는 advisor 페어링 교체. Amazon Bedrock은 여전히 computer_20251124를 허용합니다. 지원되지 않는 advisor에는 Opus 4.8, 4.7, 4.6, Sonnet 5, Sonnet 4.6, Haiku 5.5가 포함됩니다. Opus 5.5는 지원되는 대체 중 하나입니다. 응답 블록을 유형별로 읽으세요. 롤아웃 전에 플랫폼 및 게이트웨이 호환성을 확인하세요. 공식 마이그레이션 가이드를 참조하세요.
추가 기능 및 워크플로 변경
공식 기능 가이드를 사용해 진행 상황 업데이트, 메시지별 effort, 대화 중간 제어를 검토하세요. 베타 기능 활성화 전 게이트웨이 지원을 확인하세요.
Claude Sonnet 5.5 API 사용 전 준비 사항
- CometAPI 계정, API 키, 모델 액세스, 사용 가능한 청구 잔액
- cURL이 있는 터미널; SDK 예제를 위한 Python과 pip 또는 Node.js와 npm
- 선택한 엔드포인트:
/v1/messages또는/v1/chat/completions - 서버 환경에 저장된
COMETAPI_KEY, 그리고https://api.cometapi.com에 대한 네트워크 액세스 - 짧은 테스트 프롬프트, 사용 가능한 출력/완료 상태/토큰 사용량에 대한 명확한 확인
CometAPI를 통해 Claude Sonnet 5.5 API에 접근하는 방법
| API style | Endpoint | Best for |
|---|---|---|
| Claude-native Messages API | POST /v1/messages | Claude 고유 도구, 사고 제어, 에이전트 워크플로, Anthropic 응답 구조 |
| OpenAI-compatible Chat Completions | POST /v1/chat/completions | 기존 OpenAI SDK 프로젝트, 모델 라우터, 크로스 모델 애플리케이션 |
Claude의 동작 자체가 중요할 때는 Messages API를 선택하세요. 이미 동일한 추상화 계층에서 Claude, GPT, Gemini, DeepSeek 등의 모델을 전환하는 애플리케이션이라면 OpenAI 호환 API를 선택하세요.
1단계: API 키 저장
CometAPI API 키 콘솔에서 키를 생성한 뒤 런타임 환경에 설정하세요.
POSIX 셸에서 CometAPI 키 설정
export COMETAPI_KEY="YOUR_COMETAPI_KEY"
PowerShell에서 CometAPI 키 설정
$env:COMETAPI_KEY="YOUR_COMETAPI_KEY"
2단계: 첫 Messages 요청 보내기
Anthropic 호환 Messages 요청 보내기
curl https://api.cometapi.com/v1/messages \
-H "Authorization: Bearer $COMETAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 2048,
"messages": [{"role": "user", "content": "Explain exponential backoff in three bullet points."}]
}'
추가 제어를 더하기 전에 content 블록, stop_reason, usage를 점검하세요. 위 cURL 구문은 POSIX 셸을 사용합니다.
3단계: Anthropic Python SDK 사용
Anthropic Python SDK 설치
pip install anthropic
Anthropic SDK로 텍스트 블록과 usage 읽기
import os
import anthropic
anthropic_client = anthropic.Anthropic(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com",
)
response = anthropic_client.messages.create(
model="claude-sonnet-5-5",
max_tokens=4096,
messages=[{"role": "user", "content": "Review this migration plan and list the three biggest risks."}],
)
for block in response.content:
if block.type == "text":
print(block.text)
print("Completion:", response.stop_reason)
print("Usage:", response.usage)
4단계: OpenAI Python SDK 사용
OpenAI Python SDK 설치
pip install openai
OpenAI 호환 Chat Completions로 Sonnet 5.5 호출
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1",
)
response = client.chat.completions.create(
model="claude-sonnet-5-5",
messages=[
{
"role": "system",
"content": "You are a concise software engineering assistant."
},
{
"role": "user",
"content": "Review this function and identify the highest-risk bug."
}
],
)
print(response.choices[0].message.content)
이 방법은 애플리케이션이 이미 OpenAI SDK 인터페이스를 사용하는 경우 유용합니다. 기본 텍스트 통합은 새 base URL, API 키, 모델 ID만으로 충분할 수 있지만, 프로덕션 마이그레이션에서는 지원되는 매개변수, 응답 형식, 도구 호출, 스트리밍 이벤트, 타임아웃, 토큰 집계를 반드시 검증하세요.
5단계: Node.js에서 JavaScript 사용
OpenAI Node.js SDK 설치
npm install openai
Node.js ES 모듈에서 Sonnet 5.5 호출
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.COMETAPI_KEY,
baseURL: "https://api.cometapi.com/v1",
});
const response = await client.chat.completions.create({
model: "claude-sonnet-5-5",
messages: [
{
role: "user",
content: "Create a TypeScript function that validates an email address.",
},
],
});
console.log(response.choices[0].message.content);
백엔드 Node.js 애플리케이션의 경우, COMETAPI_KEY는 브라우저 클라이언트로 전송하지 말고 서버 환경에 보관하세요.
Claude Sonnet 5.5의 사고 과정과 Effort 레벨
API 기본값은 high effort이며, Claude 애플리케이션과 Claude Code는 medium을 사용합니다. 수락된 작업 품질, 지연 시간, 토큰 비용에 따라 effort를 선택하세요. 아래 표는 공식 분류가 아닌 편집적 출발점입니다.
| Workload | Suggested starting effort |
|---|---|
| Extraction | Low |
| Classification | Low |
| Routine support response | Low or Medium |
| Code explanation | Medium |
| Bug fixing | Medium |
| Repository-level coding | High |
| Complex agent workflow | High |
| Expensive production review | High, then evaluate against Opus |
| Demanding, long-horizon coding or agent work | Xhigh, only when evaluation shows a quality gain |
| Most capability-sensitive tasks with an accepted cost budget | Max, only when evaluation justifies additional latency and tokens |
모든 요청에 자동으로 최고 effort를 할당하지 마세요. 추가적인 추론이 도구 호출과 출력 길이를 늘려 에이전트 워크로드 비용을 유의미하게 증가시킬 수 있습니다. 작업 수준 평가로 설정을 선택하세요. Xhigh와 Max에서는 adaptive thinking을 사용한 뒤, 낮은 레벨과 수락된 작업 품질 및 총비용을 비교하세요. 공식 effort 가이드를 참고하세요.
Messages를 통해 Effort 구성
아래 예시는 앞서 초기화한 Anthropic 클라이언트를 사용합니다. 롤아웃 전에 CometAPI 경로에서도 동일한 제어를 테스트하세요.
adaptive thinking과 high effort 구성
response = anthropic_client.messages.create(
model="claude-sonnet-5-5",
max_tokens=8192,
thinking={"type": "adaptive"},
output_config={"effort": "high"},
messages=[{"role": "user", "content": "Audit this service migration plan."}],
)
선행 사고 과정 끄기
thinking={"type": "between_tools"}를 low, medium, high에서 사용하세요. Xhigh나 max에는 adaptive thinking을 사용하세요. between_tools는 display나 budget_tokens 필드를 받지 않으며 대화 중 effort 변경을 허용하지 않습니다.
도구 루프에서 사고 과정 보존
도구 결과를 추가하기 전에 원래 assistant content 블록을 반환하세요. 보존되는 사고 과정은 모델, 대화 접두사, 생성한 계정에 따라 달라집니다. 접두사 바인딩은 2026-08-31 00:00 UTC 이후 생성된 계정의 Claude API, Amazon Bedrock, Google Cloud에서 기본적으로 적용됩니다. 모든 게이트웨이가 동일한 바인딩 제어를 노출한다고 가정하지 마세요.
Claude Sonnet 5.5 응답 스트리밍 방법
긴 응답 스트리밍
스트리밍은 채팅 인터페이스, 코딩 도우미, 긴 응답에서 유용하며, 사용자가 생성 완료 전에 출력을 볼 수 있습니다.
OpenAI 호환 Chat Completions로 텍스트 스트리밍
from openai import OpenAI
import os
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1",
)
stream = client.chat.completions.create(
model="claude-sonnet-5-5",
messages=[
{
"role": "user",
"content": "Explain how a retrieval-augmented generation pipeline works."
}
],
stream=True,
)
for chunk in stream:
if not chunk.choices:
continue
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="", flush=True)
스트리밍은 일반적으로 생성된 토큰 수를 줄이지 않습니다. 주된 이점은 체감 지연 시간입니다. 애플리케이션은 중단된 스트림, 부분 출력, 네트워크 재시도, 취소를 명시적으로 처리해야 합니다.
자동 선택으로 도구 사용
tool_choice={"type": "auto"}를 사용하세요. 모든 도구 이름과 인수를 검증하고, 권한 부여와 타임아웃을 적용하며, 구조화된 결과를 반환하고, 반복 횟수를 제한하세요. 필수 도구 실행은 애플리케이션 오케스트레이션에 포함되어야 합니다.
티켓 조회 도구 정의 및 자동 선택 요청
tools = [{
"name": "lookup_ticket",
"description": "Retrieve a support ticket by ID",
"input_schema": {
"type": "object",
"properties": {"ticket_id": {"type": "string"}},
"required": ["ticket_id"],
"additionalProperties": False,
},
}]
response = anthropic_client.messages.create(
model="claude-sonnet-5-5",
max_tokens=4096,
tools=tools,
tool_choice={"type": "auto"},
messages=[{"role": "user", "content": "Look up ticket T-123 and summarize its status."}],
)
tool_use 블록은 작업을 요청하며, 이 첫 호출이 실행을 수행하지는 않습니다. 서버에서 요청을 검증하고 작업을 실행한 뒤 assistant content를 변경하지 않고 추가하고, 일치하는 tool_result를 전송하세요. 이 예시의 스키마는 여전히 애플리케이션 검증이 필요합니다. 선택한 경로에서의 엄격한 도구 지원은 따로 확인해야 합니다.
반복 컨텍스트를 위한 프롬프트 캐싱
프롬프트 캐싱은 시스템 정책, 도구 스키마, 리포지토리 맵, 제품 문서, 재사용 지침, 참조 매뉴얼처럼 동일한 대규모 접두사가 반복적으로 포함되는 요청에 유용합니다.
Sonnet 5.5는 최소 512 토큰의 캐시 가능한 프롬프트 접두사를 요구합니다. 더 짧은 접두사는 cache_control이 있더라도 캐싱 없이 처리됩니다. cache_creation_input_tokens와 cache_read_input_tokens를 확인하세요. 둘 다 0이면 캐시가 사용되지 않은 것입니다. 게이트웨이 경로에서 지원을 확인하세요. 프롬프트 캐싱 레퍼런스를 참조하세요.
동적 요청 콘텐츠 앞에 안정적인 컨텍스트를 배치
Stable system instructions
Stable tools
Stable repository or knowledge context
---------------- cache boundary ----------------
Current user request
Current retrieved context
현재 CometAPI 캐시 읽기 요율은 백만 토큰당 $0.16으로, 신규 입력 $1.60 대비 저렴합니다. 캐시 쓰기는 별도 과금됩니다. 절감 효과를 추정하기 전에 usage 메타데이터에서 캐시 적중을 확인하세요.
캐싱은 대규모 컨텍스트 접두사를 턴마다 재사용하는 코딩 에이전트와 엔터프라이즈 어시스턴트에 특히 유용합니다. 다만 접두사를 자주 다시 작성하면 기대한 이점이 대부분 사라질 수 있습니다.
선택한 엔드포인트 스키마로 이미지 전송
Sonnet 5.5는 텍스트와 이미지를 입력으로 받습니다. 아래 JSON은 OpenAI 호환 Chat Completions 페이로드이며, 예시 이미지 URL은 공개적으로 접근 가능한 소유 이미지로 교체하세요. Messages는 다른 이미지 블록 스키마를 사용합니다.
Chat Completions 페이로드로 이미지 전송
{
"model": "claude-sonnet-5-5",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Find the three most important UI problems in this screenshot."
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/interface.png"
}
}
]
}
]
}
멀티모달 요청 형식은 Claude 고유 인터페이스와 OpenAI 호환 인터페이스 간에 다를 수 있으므로, 두 형식이 상호 교환 가능하다고 가정하지 말고 실제로 배포하는 엔드포인트의 스키마를 사용하세요.
안전장치와 데이터 보존 처리
거부와 폴백 동작을 명시적인 애플리케이션 상태로 기록하세요. Anthropic은 서비스의 안전장치와 무데이터 보존 가용성을 설명합니다. 프로덕션 자료를 전송하기 전에 게이트웨이의 적용 가능한 보존 및 라우팅 구성을 별도로 검증하세요.
Claude Sonnet 5.5 vs Sonnet 5 vs Opus 5.5
아래 정성적 라벨은 작업 범위에 기반한 편집적 라우팅 가이드이며, 공식 성능 등급이 아닙니다. 대표 워크로드에서 반드시 검증하세요. 상세 아키텍처는 벤치마크 점수로 추론하지 않습니다.
| Dimension | Claude Sonnet 5 | Claude Sonnet 5.5 | Claude Opus 5.5 |
|---|---|---|---|
| Routine coding | Strong | Stronger and faster | Often unnecessary |
| Repository work | Strong | Very strong | Best fit for harder cases |
| Well-scoped agents | Strong | Primary fit | Useful for harder workflows |
| Ambiguous long-running work | Good | Very good | Primary fit |
| Output speed | Baseline | 30%+ faster than Sonnet 5 | 저비용 처리량보다 역량에 더 최적화 |
| Official input | $2/M | $2/M | $4/M |
| Official output | $10/M | $10/M | $20/M |
| Typical production role | 기존 Sonnet 워크로드 | 기본 Sonnet 후보 | 에스컬레이션/고난도 티어 |
| Context window | 1M tokens | 1M tokens | 1M tokens |
| Input / output | Text and images / text | Text and images / text | Text and images / text |
| Thinking | Adaptive | Adaptive; between_tools at high or below | Adaptive, always on |
| API availability | 기존 CometAPI 통합 | CometAPI Messages 및 호환 Chat Completions | CometAPI를 통해 사용 가능 |
어려운 작업을 에스컬레이션 모델로 라우팅
Routine task
↓
Claude Sonnet 5.5
↓
Confidence / validation failure?
├── No → Return result
└── Yes → Escalate difficult case
↓
Opus-class model
이 라우팅 패턴은 비용을 낮추면서도 어려운 사례에 대해 더 강력한 추론 티어에 접근할 수 있게 해줍니다.
CometAPI를 통한 Claude Sonnet 5.5 가격
| Pricing type | Anthropic | CometAPI |
|---|---|---|
| Input | $2.00 / 1M tokens | $1.60 / 1M tokens |
| Output | $10.00 / 1M tokens | $8.00 / 1M tokens |
| Cache read | $0.10 / 1M tokens | $0.16 / 1M tokens |
| Cache write (5-minute TTL) | $2.50 / 1M tokens | $2.00 / 1M tokens |
2026-10-10 기준 확인: CometAPI 입력/출력은 백만 토큰당 $1.60/$8로 유지되며, Anthropic의 $2/$10 대비 20% 낮습니다. CometAPI 캐시 읽기/쓰기 요율은 $0.16/$2이며, Anthropic의 현재 캐시 읽기/쓰기는 5분 쓰기 기준 $0.10/$2.50입니다. 출시 페이지에는 여전히 $0.20 캐시 읽기가 표시되지만, 이 개정은 현재 캐싱 레퍼런스를 사용합니다. 게이트웨이 가격은 독립적으로 변경될 수 있습니다.
토큰 가격과 작업 비용의 차이는 에이전트 애플리케이션에서 중요합니다. 코딩 에이전트는 생성 토큰이 적더라도 도구 호출 여러 번, 캐시 읽기, 코드 점검, 재시도, 검증을 수행할 수 있습니다. 따라서 성공적으로 완료된 작업당 비용이 입력 토큰 가격보다 보통 더 유의미합니다.
신규 입력 및 출력 토큰 요금 추산
Input:
100,000 / 1,000,000 × $1.60 = $0.16
Output:
5,000 / 1,000,000 × $8.00 = $0.04
Estimated model-token cost:
$0.20
도구 비용, 캐시 작업, 반복 에이전트 단계, 기타 과금 기능은 최종 비용을 변경할 수 있습니다.
2026-10-10에 CometAPI의 현재 모델 페이지와 대조 점검: 신규 입력/출력 가격은 변동이 없어, 100,000 신규 입력과 5,000 출력 토큰의 예시는 여전히 $0.16 + $0.04 = $0.20입니다. 캐시 쓰기, 캐시 읽기, 도구 비용, 재시도는 제외됩니다. 예산 책정 전에 경로별 과금 방식을 재확인하세요.
승인된 작업당 비용 통제
모델을 즉시 교체하지 않고도 지출을 줄이는 실용적 방법이 여럿 있습니다. 첫째, 완료 기준을 명확히 정의하세요:
집중된 응답 승인 형식 정의
Return only:
1. the root cause;
2. the affected file;
3. the smallest safe fix;
4. one regression test.
둘째, 전송 전에 검색된 컨텍스트를 다듬으세요. 1M 토큰 컨텍스트 윈도는 용량 한도일 뿐 목표가 아닙니다. 셋째, 프롬프트 캐싱으로 안정적인 컨텍스트를 재사용하세요. 넷째, 모든 요청에 High를 설정하기보다 워크로드별로 effort를 선택하세요. 다섯째, 승인된 작업당 비용을 측정하세요:
승인된 작업당 비용 계산
Total API cost
÷
Number of outputs accepted without rework
더 저렴한 요청이더라도 추가 재시도, 수정, 도구 호출을 유발한다면 더 저렴한 워크플로가 아닐 수 있습니다.
Sonnet 5에서 Claude Sonnet 5.5 API로 마이그레이션하는 방법
- 롤백을 위해 이전 프로덕션 구성을 유지하세요.
- 모델 ID를 claude-sonnet-5에서 claude-sonnet-5-5로 변경하세요.
- 위에서 설명한 사고 과정, 도구 선택, 히스토리 변화를 적용하세요.
- 도구, 이미지, 스트리밍을 포함한 대표 요청을 재생하세요.
- 승인된 출력, 인간 수정률, p50/p95 지연 시간, 총 작업 비용을 비교하세요.
- 재시도, 거부, 취소, 중단된 스트림을 테스트하세요.
- usage 메타데이터에서 캐시 적중과 출력 예산 동작을 확인하세요.
- 소규모 트래픽 카너리를 배포하고, 승인 임계값 통과 후에만 확장하세요.
Claude Sonnet 5.5 API 오류 문제 해결
| Symptom | What to check |
|---|---|
| 400: invalid thinking setting | High 이하에서 disabled를 between_tools로 교체하세요. Xhigh/max에는 adaptive를 사용하세요. |
| 400: forced tool selection | any 또는 이름 지정 강제 도구 선택을 제거하고 auto를 사용하세요. |
| 400 after replaying history | 접두사 바인딩이 적용된 계정의 경우, 서명된 사고 과정과 그 이전 히스토리를 변경하지 마세요. 모델/계정 호환성과 선택한 경로를 확인하세요. |
| 401 / 403 | 자격 증명, 권한, 모델 액세스를 확인하세요. |
| 429 / retryable 5xx | 지터가 있는 경계 지수 백오프를 사용하고 제공되는 경우 Retry-After를 준수하세요. |
| Response contains no ordinary text | content 타입, 완료 상태, 거부, 폴백 동작을 점검하세요. |
| Output ends early | stop_reason 또는 finish_reason을 확인하고 출력 예산을 조정하며 스트리밍을 사용하세요. |
| Cache never hits | 안정적인 접두사와 캐시 usage 메타데이터를 확인하세요. |
| Stream disconnects | 부분 출력을 보존하고 애플리케이션 멱등성 규칙에 따라 재시도하세요. |
형식 오류나 인증 실패를 동일하게 재시도하지 마세요. 중단된 에이전트 실행을 재생할 때 중복 도구 작업을 방지하세요.
Claude Sonnet 5.5 프로덕션 모범 사례
워크로드를 선택하고, 승인 게이트를 정의하고, 전체 애플리케이션을 평가하세요. 모델 ID, 엔드포인트, effort, 지연 시간, 토큰 및 캐시 사용량, 도구 실패, 완료 상태, 승인된 작업 결과를 로깅하세요. 키는 서버 측에 보관하고 타임아웃, 경계 재시도, 에이전트 반복 제한을 구성하세요.
워크플로 품질과 신뢰성 측정
| Metric | Why it matters |
|---|---|
| Task success rate | 실제 워크플로 완료를 측정 |
| Human correction rate | 숨은 품질 문제를 드러냄 |
| Input tokens | 컨텍스트 비용을 통제 |
| Output tokens | 생성 비용을 통제 |
| Cache-hit rate | 캐싱 가치 판단 |
| Tool-call count | 비효율적 에이전트 탐지 |
| Invalid tool calls | 오케스트레이션 신뢰성 측정 |
| Retry rate | API 또는 워크플로 불안정성 노출 |
| p50 latency | 전형적인 사용자 경험 |
| p95 latency | 롱테일 사용자 경험 |
| Cost per accepted task | 품질과 경제성을 연결 |
코딩 에이전트의 경우, 통과한 테스트, 불필요하게 수정된 파일, 되돌린 패치, 인간 개입 없이 성공적으로 완료된 비율도 추적하세요.
예시: 범위가 명확한 리포지토리 버그 수정
실패하는 테스트, 관련 소스 파일, 기대 동작을 제공하세요. 회귀 검사를 포함한 집중된 패치를 요청하세요. 승인 게이트는 재현 가능한 수정, 관련 테스트 통과, 무관한 편집 없음입니다. 승인된 패치 대비 총 API 및 도구 비용을 비교하세요.
예시: 지원 티켓 분류
고객 이슈와 승인된 지식 기반 문서를 검색하세요. 문제를 분류하고, 근거가 있는 응답을 작성하며, 에스컬레이션이 필요한 사례를 표시하도록 요청하세요. 모델의 주장과 검색 자료가 일치하고, 라우팅 결정이 지원 정책을 따를 때만 결과를 승인하세요.
예시: 문서와 스크린샷 검토
승인된 절차와 해당 인터페이스의 스크린샷을 제공하세요. 관련 구절과 보이는 UI 요소를 인용해 불일치를 요청하세요. 절차 변경 전 검토자가 결과를 반드시 확인하도록 하세요.
결론
Claude Sonnet 5.5는 팀에 빠른 코딩, 지원, 문서, 도구 활용 워크플로를 위한 실용적인 후보를 제공합니다. 작동하는 CometAPI 요청부터 시작하고, 애플리케이션에 필요한 제어를 추가하세요.
마이그레이션은 모델 ID 교체만으로 끝나지 않습니다. 사고 과정 설정, 자동 도구 선택, 응답 파싱, 히스토리 재생을 점검하세요. 워크로드 평가에서 품질, 지연 시간, 비용의 균형이 수용 가능할 때 모델을 승격하고, 승인 게이트를 통과하지 못하는 작업을 위해 더 강력한 티어를 예약하세요.
FAQ
다운타임 없이 Claude Sonnet 5.5 API 키를 교체하려면?
서버 측 시크릿 매니저에 키를 저장하고, 워커가 애플리케이션 코드에 임베드하지 않고 자격 증명을 다시 로드하도록 하세요. 공급자가 키 중첩 활성화를 지원한다면, 교체 키를 먼저 도입하고, 작은 요청으로 검증한 뒤, 워커를 점진적으로 전환하고, 이전 키를 폐기하세요. 전환 중 인증 오류를 모니터링하고 두 키 모두 로깅하지 마세요.
워커 재시작 후 Claude Sonnet 5.5 작업을 재개하려면?
작업 식별자, 마지막 완료 단계, 요청 구성, 도구 실행 기록을 영속화하세요. 검증된 체크포인트에서 재개합니다. 도구 작업을 재생하기 전에 이미 완료되었는지, 반복 실행이 안전한지 확인하세요. 저장된 대화록만으로는 중복 티켓, 메시지, 데이터베이스 쓰기를 방지할 수 없습니다.
시간이 지나며 Claude Sonnet 5.5 동작 변화를 어떻게 감지하나요?
수락된 답변 또는 수락 검사, SDK 버전, 요청 설정이 포함된 날짜 표시 평가 세트를 유지하세요. 공급자, SDK, 프롬프트, 라우팅 변경 후와 주기적으로 다시 실행하세요. 작업 성공, 수정률, 지연 시간, 총비용을 비교하세요. 계정에서 버전 고정을 제공한다면, 그 보장을 의존하기 전에 확인하세요. 중요 워크플로를 위해 롤백 경로를 유지하세요.
