Claude API July 2026: 캐시를 유지하며 도구를 바꾸고 거절을 자동 재시도하는 방법

왜 지금 봐야 하나

긴 에이전트 대화에서 도구 목록이 중간에 바뀌면 어떤 일이 생기는가. 지금까지는 최상위 tools 배열을 교체해야 했고, 그 순간 프롬프트 캐시가 무효화됐다. 캐시 미스는 비용과 지연을 동시에 높인다.

2026년 7월 24일, Anthropic은 이 문제를 직접 해결하는 두 기능을 베타로 공개했다.

Mid-conversation tool changes: 대화 도중 도구를 추가·제거하되 캐시는 그대로 보존
Server-side fallback default mode: 모델이 요청을 거절했을 때 Anthropic 권장 폴백 모델로 자동 재시도

같은 날 베타 헤더 날짜가 각각 2026-07-01로 찍혀 있어 설계는 7월 초에 확정됐음을 알 수 있다.

같은 주 7월 22일에는 Claude Managed Agents에도 변화가 있었다. 세션 시작 시 초기 이벤트를 심을 수 있고, 환경·메모리 스토어 생명주기를 폴링 없이 웹훅으로 추적할 수 있게 됐다.

이 챕터에서는 두 핵심 기능의 작동 방식, 사용 경계, 운영 체크리스트를 정리한다.

Mid-Conversation Tool Changes: 도구를 바꿔도 캐시가 살아있다

문제 맥락

Claude의 프롬프트 캐시는 요청의 앞부분이 이전 요청과 동일할 때 적중한다. tools 배열은 최상위 레벨에 있으므로, 여기에 도구를 하나라도 추가·제거하면 이후의 모든 캐시 접두어가 깨진다.

수십 턴이 쌓인 에이전트 세션에서 단계별로 다른 도구 세트가 필요할 때 이 문제가 표면화된다.

새 방식: 시스템 메시지로 도구 변경 전달

베타 헤더 mid-conversation-tool-changes-2026-07-01을 사용하면 role: "system" 중간 메시지에 tool_addition / tool_removal 블록을 담아 보낼 수 있다. 최상위 tools 배열은 그대로 두고, 변경분만 추가로 보내는 방식이다.

# tool_addition 예시 (anthropic-beta: mid-conversation-tool-changes-2026-07-01)
{
  "role": "system",
  "content": [
    {
      "type": "tool_addition",
      "tools": [
        {
          "name": "run_sql",
          "description": "Execute a read-only SQL query",
          "input_schema": { ... }
        }
      ]
    }
  ]
}

# tool_removal 예시
{
  "role": "system",
  "content": [
    {
      "type": "tool_removal",
      "tool_names": ["web_search"]
    }
  ]
}

캐시 보존 원리

기존 방식 (tools 배열 교체)

system prompt (캐시됨)

tools: [A, B] (캐시됨)

↓ 도구 C 추가

tools: [A, B, C] ← 캐시 미스

이후 모든 메시지 재계산

새 방식 (mid-conv tool change)

system prompt (캐시 유지)

tools: [A, B] (캐시 유지)

… 기존 대화 (캐시 유지)

system: tool_addition C ← 새 블록만 추가

이후 메시지: [A, B, C]로 동작

지원 모델

Claude Fable 5

Claude Mythos 5

Claude Opus 4.8

Claude Opus 5

Mid-Conversation Tool Changes의 캐시 보존 구조

핵심은 최상위 tools가 바뀌지 않는다는 것이다. 캐시 키에 영향을 주는 부분은 그대로이고, 변경분은 대화 흐름의 일부로 삽입된다.

배치 규칙

시스템 메시지 배치에는 제약이 있다.

규칙	내용
`role: "system"` 위치	반드시 `user` 턴 다음에 위치
빈 content	허용 안 됨
`tool_addition` 후 동일 이름 재추가	오류
`tool_removal` 시 존재하지 않는 도구	오류
최상위 `tools`와의 관계	누적 적용. 최상위 정의가 기준이 됨

Mid-conversation system messages(5월 28일 GA)와 함께 사용하면 시스템 프롬프트와 도구 세트를 모두 캐시를 유지하며 변경할 수 있다.

Server-Side Fallback Default Mode: 거절을 한 번의 API 호출로 처리

배경

Claude Fable 5 출시(6월 9일) 이후, stop_reason: "refusal"을 반환하는 경우가 생겼다. 거절이 발생하면 클라이언트는 직접 다른 모델에 재시도해야 했다. API 왕복이 두 번 발생하고, 어느 모델로 재시도할지도 직접 결정해야 했다.

server-side-fallback-2026-07-01 베타 헤더와 fallbacks: "default" 파라미터는 이 흐름을 서버 안에서 처리한다.

동작 방식

fallbacks 없음 (기존)

클라이언트 → Fable 5 요청

Fable 5 → refusal (stop_reason: "refusal")

클라이언트 로직: 카테고리 확인

클라이언트 → 다른 모델 재시도

2회 왕복, 클라이언트 측 분기 필요

fallbacks: "default" (신규)

클라이언트 → Fable 5 + fallbacks: "default"

Fable 5 거절 시: API 서버가 카테고리 파악

Anthropic 권장 모델로 자동 재시도

클라이언트 ← 최종 응답 (어떤 모델이 답했는지 표시)

1회 왕복, 분기 없음

Server-Side Fallback Default Mode 요청 흐름

응답 바디에는 어떤 모델이 최종 답변을 생성했는지 명시된다. 클라이언트는 stop_reason이 "end_turn"인지 "refusal"인지 확인하는 기존 로직 대신, 응답 모델 필드만 확인하면 된다.

거절 카테고리와 폴백 모델

stop_details.category 필드로 거절 이유를 확인할 수 있다.

카테고리	의미	Anthropic 권장 폴백
`cyber`	사이버 보안 관련 거절	모델별 권장사항
`bio`	생물학적 위험 관련 거절	모델별 권장사항
`reasoning_extraction`	모델 출력 역공학 시도 거절	모델별 권장사항

"default" 모드는 카테고리별로 Anthropic이 권장하는 폴백을 자동 적용한다. 구체적인 모델 매핑은 Anthropic이 관리하며 변경될 수 있다.

가용 범위 제한

플랫폼	지원 여부
Claude API (직접)	✅
Claude Platform on AWS	✅
Amazon Bedrock	❌
Google Cloud Vertex AI	❌
Microsoft Foundry	❌
Message Batches API	❌

폴백 모델의 응답은 폴백 모델 요금으로 청구된다. 주 모델이 응답 생성 전에 거절했다면 주 모델 요금은 청구되지 않는다(6월 2일 GA).

Claude Managed Agents: 7월 22일 업데이트

세션 초기 이벤트 심기

POST /v1/sessions 시 initial_events를 함께 보내면 세션 생성과 동시에 에이전트 루프가 시작된다. 기존에는 세션을 만든 뒤 별도 요청으로 이벤트를 보내야 했다.

# initial_events로 세션 생성 + 루프 시작을 한 번에
{
  "agent_id": "ag_xxx",
  "initial_events": [
    {
      "type": "user.message",
      "content": "데이터베이스 마이그레이션 상태를 확인해줘"
    }
  ]
}

initial_events는 최대 50개의 user.message와 user.define_outcome 이벤트를 담을 수 있다. 비어 있지 않은 리스트를 보내면 같은 API 호출 안에서 에이전트 루프가 시작된다.

웹훅 생명주기 이벤트 확장

환경과 메모리 스토어 생명주기를 이제 폴링 없이 웹훅으로 추적할 수 있다.

이벤트 타입	설명
`environment.created`	샌드박스 환경 생성
`environment.ready`	환경 준비 완료
`environment.stopped`	환경 중지
`environment.deleted`	환경 삭제
`memory_store.created`	메모리 스토어 생성
`memory_store.updated`	메모리 스토어 내용 변경
`memory_store.deleted`	메모리 스토어 삭제

에이전트 버전 필드 선택적으로 변경

에이전트 업데이트 시 version 필드가 이제 선택 사항이다.

`version` 유무	동작
명시	낙관적 잠금: 버전 불일치 시 409 에러
생략	무조건 업데이트 적용

운영 체크리스트

Mid-Conversation Tool Changes 도입 시

[ ] 베타 헤더 추가: anthropic-beta: mid-conversation-tool-changes-2026-07-01을 요청 헤더에 포함한다.
[ ] 최상위 tools 배열 고정: 가장 기본적인 도구 세트를 최상위에 두고 변경하지 않는다. 세션 내 추가/제거는 중간 시스템 메시지로 처리한다.
[ ] 배치 규칙 확인: tool_addition/tool_removal은 반드시 user 턴 다음 system 메시지에 넣는다.
[ ] 캐시 히트율 측정: cache diagnostics(cache-diagnosis-2026-04-07 베타 헤더)와 함께 사용해 실제 캐시 히트율 변화를 측정한다.
[ ] 중복 추가 방지: 이미 존재하는 도구를 tool_addition으로 보내면 오류가 발생한다. 현재 활성 도구 목록을 상태로 관리한다.

Server-Side Fallback 도입 시

[ ] 베타 헤더 추가: anthropic-beta: server-side-fallback-2026-07-01.
[ ] 파라미터 추가: 요청 바디에 "fallbacks": "default" 추가.
[ ] 플랫폼 확인: Bedrock·Vertex·Microsoft Foundry에서는 동작하지 않는다.
[ ] 청구 분리: 폴백 모델 사용 시 폴백 모델 요금이 청구된다. 예산 모델을 재검토한다.
[ ] 응답 모델 로깅: 어떤 모델이 최종 응답을 생성했는지 응답 바디에서 로깅해 거절 패턴을 추적한다.
[ ] 거절 모니터링: stop_reason: "refusal" + stop_details.category 로그를 남겨 거절 빈도와 카테고리를 파악한다.

병행 참고: 7월 24일 Claude Opus 5 행동 변화

이날 같이 출시된 Claude Opus 5에는 기존 코드에 영향을 줄 수 있는 변경이 있다.

변화	영향
`thinking: {"type": "disabled"}`를 `effort: xhigh` 또는 `max`와 함께 사용	400 에러 (Opus 4.8에서는 허용됐음)
Opus 5 기본값 `effort`	`high`
프롬프트 캐시 최소 길이	Opus 4.8과 동일 (1,024 토큰)

Opus 5는 7월 24일 GA이며 모델 ID는 claude-opus-5. Fable 5와 마찬가지로 mid-conversation-tool-changes-2026-07-01도 지원된다.

Open Questions

tool_addition/tool_removal이 누적 적용될 때 세션 전체의 유효 도구 목록을 서버가 어떻게 추적하는지, 클라이언트 측에서 명시적으로 조회하는 방법이 문서화되어 있지 않다.
Server-side fallback에서 Anthropic이 권장하는 카테고리별 폴백 모델 매핑이 공개 문서에 명시되어 있지 않다. 구현 전 테스트로 확인 필요.
initial_events 50개 제한의 근거(실용적 상한인지, 기술적 상한인지)가 문서화되어 있지 않다.
Mid-conversation tool changes 베타 헤더의 GA 전환 시점이 미공개다.