[Claude API] 대화 중간에 툴 바꿔도 프롬프트 캐시가 안 깨져요

[Claude API] 대화 중간에 툴 바꿔도 프롬프트 캐시가 안 깨져요

대화 중간에 툴을 바꿔도 프롬프트 캐시가 안 깨져요. Anthropic이 7월 24일 Opus 5와 함께 mid-conversation tool changes 베타를 열었기 때문이에요. 에이전트를 오래 굴리는 쪽이면 비용으로 연결되는 변화로 보여요.

01. 지금까지는 툴 하나만 건드려도 캐시가 통째로 날아갔어요

프롬프트 캐시는 요청 앞부분을 tools, system, messages 순서로 해싱해요. 캐시가 맞으려면 이 앞부분이 최근 요청과 캐시 브레이크포인트까지 바이트 단위로 같아야 해요.

문제는 tools 배열이 그 맨 앞에 있다는 점이에요. 툴 하나를 빼거나 설명 한 줄을 고치면 해시가 달라지고 그 뒤 대화 전체가 캐시를 놓쳐요. 공식 문서 설명 기준으로, 턴이 쌓인 세션일수록 다시 읽어야 할 양이 커지는 구조예요.

02. tools는 그대로 두고 system 메시지로 켜고 꺼요

새 방식은 쓸 툴을 처음에 tools 배열에 전부 선언해둬요. 그다음 대화 중간에 role이 system인 메시지를 넣고, 그 안의 tool_addition과 tool_removal 블록으로 특정 툴을 그 지점부터 열거나 닫아요.

블록 안의 tool 필드는 툴을 새로 정의하는 게 아니라 이름으로 참조만 해요. MCP connector 툴은 서버 안의 툴 하나만 지목할 수도 있어요. 서버 전체를 한 덩이로 참조하는 것도 돼요.

tools에 넣어두되 처음부터 보여주고 싶지 않은 툴은 defer_loading을 켜면 돼요. 그러면 tool_addition이 꺼낼 때까지 모델 쪽에는 안 보여요.

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    betas=["mid-conversation-tool-changes-2026-07-01"],
    # 툴 전체를 여기 선언해두고 이 배열은 이후 손대지 않음
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather for a location.",
            "input_schema": {
                "type": "object",
                "properties": {"location": {"type": "string"}},
                "required": ["location"],
            },
        },
    ],
    messages=[
        {"role": "user", "content": "Say OK."},
        # 여기서부터 get_weather 회수. 앞 턴이 그대로라 캐시 프리픽스가 유지됨
        # (실제 캐시 적립은 cache_control 을 켠 요청에서)
        {"role": "system", "content": [
            {"type": "tool_removal",
             "tool": {"type": "tool_reference", "name": "get_weather"}},
        ]},
    ],
)

03. 베타 헤더가 필요하고 Sonnet 5는 목록에 없어요

요청에 mid-conversation-tool-changes-2026-07-01 베타 헤더를 넣어야 동작해요. 문서 기준으로 지원 모델은 Fable 5, Mythos 5, Opus 4.8, Opus 5 네 개이고 Claude API와 Amazon Bedrock, Google Cloud에서 쓸 수 있어요.

Sonnet 5는 지원 목록에 없어요. 비용 때문에 Sonnet 계열로 에이전트를 돌리는 경우라면 아직 순서가 안 온 기능이에요.

04. system 메시지를 아무 자리에나 못 넣어요

system 메시지는 user 턴 바로 뒤, 또는 서버 툴 결과로 끝나는 assistant 턴 바로 뒤에 와야 해요. 그리고 messages 배열의 마지막이거나 바로 뒤에 assistant 턴이 와야 해요. tool_result를 담은 user 턴 뒤도 허용이라서 에이전트 루프에서는 툴 결과 바로 다음이 자리예요.

assistant의 tool_use 블록과 그에 답하는 tool_result 사이에는 못 넣어요. 그 밖의 위치는 400 에러예요. tools에 선언 안 된 이름을 참조해도 400이 떨어져요.

캐시는 opt-in이에요. 요청에 cache_control이 없으면 애초에 캐시가 안 만들어지니 지킬 것도 없어요.

문서가 드는 상황은 긴 세션 도중의 정책 변경, 툴 가용성 같은 상태 변화, 에이전트 루프 중간에 들어온 사용자 입력 전달이에요. 전환할 때마다 캐시를 새로 쓰던 비용이 빠지는 구조인데, 실제로 얼마나 줄어드는지는 툴 정의 크기와 대화 길이에 달려서 직접 재보고 판단할 부분이에요.

출처: Claude Docs — Mid-conversation system messages and tool changes, Claude Platform release notes (2026-07-24)

이 글은 공식 발표 내용을 정리한 것이고, Anthropic으로부터 어떤 형식의 협찬도 받지 않았습니다.