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가 바뀌지 않는다는 것이다. 캐시 키에 영향을 주는 부분은 그대로이고, 변경분은 대화 흐름의 일부로 삽입된다.

배치 규칙

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

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" 파라미터는 이 흐름을 서버 안에서 처리한다.

동작 방식

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

거절 카테고리와 폴백 모델

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

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

가용 범위 제한

폴백 모델의 응답은 폴백 모델 요금으로 청구된다. 주 모델이 응답 생성 전에 거절했다면 주 모델 요금은 청구되지 않는다(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 호출 안에서 에이전트 루프가 시작된다.

웹훅 생명주기 이벤트 확장

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

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

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

운영 체크리스트

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에는 기존 코드에 영향을 줄 수 있는 변경이 있다.

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 전환 시점이 미공개다.

References

• Claude Platform release notes — July 24, 2026
• Refusals and fallback — Claude Platform Docs
• Mid-conversation system messages — Claude Platform Docs
• Claude Managed Agents: Sessions — Claude Platform Docs
• Claude Managed Agents: Webhooks — Claude Platform Docs
• What's new in Claude Opus 5
• Claude Developer Platform Updates July 2026 — Releasebot
• Anthropic API release notes 2026 — fazm.ai