Anthropic이 Claude 개발자 문서에 베타 기능 메시지별 effort 조정을 추가했다. 개발자는 여러 턴으로 이어지는 대화 중간에 특수한 system 메시지를 끼워 넣어, 이후 답변의 추론 단계를 high에서 low로, 또는 그 반대로 바꿀 수 있다. 요청 최상위의 effort 설정은 건드리지 않아도 되고, 이미 캐시된 대화 앞부분도 그대로 캐시 적중을 얻는다.
문서가 제시한 작성법은 짧다. messages 배열에 role이 system이고 content가 빈 배열인 메시지를 추가하고, 그 안에 output_config.effort의 새 값을 넣은 뒤, 요청 헤더에 mid-conversation-output-config-2026-07-01을 붙이면 된다. 예시에서는 최상위 effort를 high로 두고, 모델이 먼저 높은 단계로 SQLite에서 PostgreSQL로 옮기는 3단계 계획을 세운다. 이어서 low 단계의 system 메시지를 끼워 넣고 사용자가 계획을 한 문장으로 줄여 달라고 요청하면, 이 턴은 낮은 단계로 답한다.
새 단계는 어느 턴부터 적용되나
적용 시점은 이 메시지를 어디에 두느냐에 따라 달라지며, 규칙이 꽤 세세하게 적혀 있다.
- 새로운 입력이 담긴 user 메시지 바로 뒤에 두면, Claude는 그 턴의 답변부터 새 단계를 쓴다.
- 그 밖의 위치, 예를 들어 assistant 응답과 다음 user 메시지 사이에 두면 새 단계는 그다음에 오는 새 입력이 담긴 user 메시지부터 적용된다.
- tool_result만 담긴 user 메시지는 새 입력으로 치지 않으므로, 도구 호출이 몇 번 오가더라도 전환이 일어나지 않는다.
새 단계는 뒤에 오는 다른 메시지가 다시 바꿀 때까지 계속 유지된다. 문서는 이 메시지를 이미 보낸 내용의 맨 끝에 두고, 이후 요청에서도 그대로 유지해야 한다고 특별히 당부한다. 이미 보낸 턴 앞에 끼워 넣거나, 나중에 위치를 옮기거나 삭제해서는 안 된다. 보존된 사고(preserved thinking)를 지원하는 모델에서는 이런 변경이 있으면 해당 메시지 뒤에 이어지는 assistant 턴의 사고 블록이 무효가 된다.
오류 상황도 분명히 정리돼 있다. 베타 헤더 없이 system 메시지에 output_config를 쓰면 "Extra inputs are not permitted"라는 안내와 함께 400이 반환된다. 헤더를 붙였더라도 Claude Fable 5처럼 지원하지 않는 모델이면 마찬가지로 400이다. between_tools 사고 모드를 켠 Sonnet 5.5와 사고를 끈 Haiku 5.5에서도 도중에 단계를 바꿀 수 없으며, 문서는 이 두 경우에 적응형 사고(adaptive thinking)를 쓰라고 권한다.
예전에는 어떻게 했고, 무엇이 줄어드나
effort는 원래 요청 단위 매개변수로, 요청 최상위에 적는 값이었다. 같은 대화에서 앞부분은 신중하게 생각하고 뒷부분은 빠르게 답하게 하고 싶다면, 두 요청 사이에 최상위 값을 바꾸는 수밖에 없었다. 이 방식에 대한 문서의 평가는 직설적이다. 최상위 값을 바꾸면 프롬프트 캐시가 처음부터 다시 계산되고, 앞서 쌓인 긴 컨텍스트는 캐시 미스로 다시 과금된다는 것이다.
"A per-message change leaves everything before it unchanged, so the cached prefix still matches." (메시지별로 단계를 바꾸면 그 앞의 내용은 한 글자도 달라지지 않으므로 캐시된 프리픽스가 그대로 일치한다.)
문서는 놓치기 쉬운 세부 사항도 언급한다. Claude Fable 5.1에서는 최상위 값을 바꿔도 모델을 유도하는 효과 자체가 그다지 믿을 만하지 않다. 앞선 몇 턴의 답변이 이전 단계에 맞춰 작성돼 있어서, 모델이 자신의 이전 스타일과 일관성을 유지하려는 경향이 있기 때문이다. 메시지별 전환은 '여기서부터 단계를 바꾼다'는 지시를 대화 자체에 적어 넣기 때문에, 모델이 그 전환 지점을 볼 수 있다.
가장 실용적인 곳은 오래 도는 에이전트 루프다. 코딩 에이전트가 높은 단계로 코드베이스를 읽고 수정 방안을 정한 다음, 이후 수십 턴의 실행과 확인은 낮은 단계로 돌릴 수 있다. 그동안 컨텍스트 앞부분은 변하지 않으므로 캐시 적중률에 영향이 없다. 예전에는 단계의 유연성과 캐시의 경제성 중 하나를 골라야 했지만, 이제는 둘 다 얻을 수 있다.
고객 지원이나 질의응답 앱에서도 쓸 수 있다. 대화 초반에 사용자가 복잡한 장애를 설명하면 모델이 높은 단계로 진단한다. 원인이 좁혀진 뒤 사용자가 "두 번째 단계에서 정확히 어디를 누르나요"처럼 추가 질문만 한다면, 낮은 단계로 내려 답하게 해서 응답을 훨씬 빠르게 만들 수 있다. 반대로 가벼운 잡담 중에 사용자가 갑자기 계약서를 던져 놓고 조항별 검토를 요청하면, 앱이 일시적으로 단계를 높일 수 있다. 이런 전환은 예전에는 캐시를 포기하거나 아예 전환하지 않는 쪽이었다.
지원 범위
모델 쪽에서는 Fable 5.2, Mythos 5.2, Fable 5.1, Mythos 5.1, Opus 5.5, Opus 5, Sonnet 5.5, Haiku 5.5가 모두 베타 목록에 올라 있으며, 모델마다 지원하는 클라우드 플랫폼은 완전히 같지 않다. 플랫폼 쪽에서는 Claude API, Amazon Bedrock, Claude Platform on AWS, Google Cloud의 두 가지 관리형 제공 방식, Microsoft Foundry가 모두 베타로 표시돼 있다. Bedrock InvokeModel 인터페이스를 쓰는 개발자는 베타 값을 요청 헤더가 아니라 요청 본문의 anthropic_beta 배열에 넣어야 한다.
Managed Agents는 아직 이 기능을 지원하지 않으며, 문서가 제시하는 대안은 세션 단위로 에이전트의 모델 설정을 덮어쓰는 것이다. 기능은 아직 베타 단계이고, 베타 헤더 이름에 들어 있는 날짜는 API 버전 식별자다. 정식 버전이 나온 뒤 표기가 바뀔지 여부는 문서에 언급이 없다.
참고 출처: Claude 개발자 문서 Per-message effort 페이지(베타 헤더 이름, 모델·플랫폼 목록, 적용 위치 규칙, 오류 메시지 확인), CocoLoop, Claude 개발자 문서 effort 매개변수 설명.