Claude Code agent_summary 비용, 평균 2%와 16.4%가 갈리는 이유와 재는 법

Claude Code 백그라운드 에이전트의 상태 문구는 토큰을 얼마나 쓰나? Anthropic 이 텔레메트리로 잰 지난주 전체 평균은 비용의 약 2%다. 그런데 백그라운드 에이전트 위주로 일한 한 팀에서는 본 대화보다 많은 16.4%가 나왔다. 2026년 10월 30일 기준으로 이 요청을 끄는 공식 설정은 없다. 그러니 OpenTelemetry(OTel, 관측 데이터를 내보내는 표준) 이벤트에서 query_source 가 agent_summary 인 요청부터 모아 내 몫을 재는 편이 낫다.

01 서너 단어 상태 문구에 에이전트 기록 전체가 실린다

백그라운드 에이전트는 터미널을 붙잡지 않고 뒤에서 계속 도는 Claude Code 대화다. 이런 에이전트를 띄우면 에이전트 패널에 각자 지금 무엇을 하는지 짧은 문구가 붙는데, 그 문구를 만드는 요청이 agent_summary 다. Flamerix AI 가 공개한 gist 에 따르면 일하는 에이전트마다 대략 30초에 한 번, 그 에이전트가 쓰는 모델(대개 Opus)에 지금까지 쌓인 기록을 통째로 넘기고 3~5단어짜리 상태를 받아 온다. 받아 온 문구는 패널 표시에만 쓰이고 대화 기록에는 붙지 않는다.

gist 가 정리한 이력으로는 관련 코드가 2월에 처음 들어갔고 3월에 SDK 옵션으로 열렸다. 대화형 백그라운드 에이전트에서 기본으로 켜진 것은 8월 13일 배포판(2.1.232)부터다. Flamerix 의 주간 추정 비용에서 이 요청이 차지한 몫은 7월에 3.5~7%였다가 10월 중순에는 약 16%까지 올랐다.

공식 문서의 Agent view 행 요약과는 다른 기능이다. Agent view 는 여러 백그라운드 세션을 한 화면에 모아 보는 연구 프리뷰 기능으로, 문서는 그 행 요약을 Haiku급 모델이 턴이 끝날 때와 긴 턴 중 몇 분마다 새로 쓴다고 적었다. 반면 agent_summary 는 에이전트 자신의 모델로 30초마다 돈다. 이번에 연 공식 문서(모니터링·Agent view)에는 agent_summary 라는 이름이 나오지 않는다. 이 글은 이 요청 하나의 비용과 재는 법, 줄이는 법만 다루고 대화 압축이나 세션 제목 생성 같은 다른 보조 요청은 범위 밖에 둔다.

02 측정치는 2%에서 26%까지 벌어진다

같은 기능을 두고 나온 숫자를 출처별로 모았다. 어느 것도 청구서가 아니고, API 정가로 환산한 추정 비용이거나 토큰 수다.

Flamerix 는 숫자 몇 개를 더 내놓았다. 이 요청 비용의 96%는 Opus 에서 나왔고, 출력 토큰 하나당 입력 토큰은 약 9,000개였다. 요약을 막는 훅을 건 뒤 이틀 동안은 비용과 요청 몫이 모두 0%로 떨어졌다.

03 왜 Anthropic 평균 2%와 측정치 16.4%가 갈리나

분모가 다르기 때문이다. Anthropic 의 2%는 텔레메트리를 보내는 사용자 전체로 나눈 값이라, 백그라운드 에이전트를 거의 띄우지 않는 사람까지 섞여 있다. Claude Code 팀에서 일한다고 밝힌 HN 댓글 작성자는 이 요청이 거의 다 터미널에서 나오고, 터미널만 보면 약 6%라고 덧붙였다. 16.4%를 두고는 백그라운드 에이전트를 주로 돌리는 팀의 수치로 보이며 흔한 세션 같지는 않다고 답했다. 쉬는 에이전트에는 요약 요청이 가지 않는다는 점도 밝혔다.

이슈 #86879 참여자들의 관찰은 그 차이가 어디서 나는지 보여 준다. 비용은 에이전트가 해낸 일의 양보다 동시에 띄운 하위 에이전트 수, 돌아간 시간, 문맥 크기를 따라 늘었다. 매번 기록 전체를 다시 보내므로 오래 도는 에이전트일수록 한 번에 보내는 양도 커지고 보내는 횟수도 쌓인다. 앞 표에서 하위 에이전트가 4개뿐인 세션이 26%로 가장 높게 나온 것도 이 구조로 설명된다. 보고자는 한 에이전트의 문맥이 약 38만 토큰까지 커졌고, 그 크기라면 상태 문구 하나에만 시간당 캐시 읽기 토큰 약 4,500만 개가 든다고 계산했다.

근거의 무게도 따로 매겨야 한다. 2%는 Anthropic 이 자기 텔레메트리로 잰 값이고, 외부에서 같은 조건으로 다시 잰 출처는 이번에 찾지 못했다. 16.4%는 한 팀이 한 주 동안 잰 사례다. 평균이 낮다고 내 사용량도 괜찮다는 근거가 되지 않고, 16.4%가 누구에게나 들어맞지도 않는다. 사용 방식에 따라 몇 배씩 갈리는 값이라 자기 숫자를 재는 수밖에 없다.

04 비용은 캐시를 놓친 소수의 요청에서 크게 난다

요약 요청 하나의 입력은 에이전트 기록 전체이고 출력은 아주 짧다. 이슈 #86879 보고자는 한 번에 받는 출력이 65토큰 안팎이라고 적었다. 그러니 값은 입력을 어떤 단가로 읽느냐, 곧 프롬프트 캐시(앞서 보낸 같은 앞부분을 싸게 다시 읽게 해 주는 기능)에 걸렸느냐에서 갈린다.

2026년 10월 Anthropic 프롬프트 캐싱 문서 기준으로 캐시 읽기는 기본 입력 단가의 0.1배이고, Opus 5.5·Sonnet 5.5 는 0.05배다. 5분짜리 캐시 쓰기는 1.25배다. 캐시는 기본 5분 동안 살아 있고, 읽힐 때마다 추가 비용 없이 연장된다. 캐시에 걸린 요약 요청은 기록을 정가의 10분의 1(Opus 5.5 라면 20분의 1)로 읽지만, 놓치면 같은 기록을 정가 그대로 읽는다.

Flamerix 의 측정이 이 차이를 숫자로 보여 준다. 요약 요청의 약 98%는 캐시를 읽었는데, 캐시를 놓친 2% 남짓이 이 기능 비용의 3분의 1 넘게를 차지했다. 이슈 참여자들은 압축된 번들 코드를 읽고, 이 요청이 도구를 모두 막은 채 한 턴만 돌며 세션 기록에 남지 않고 캐시에 새로 쓰지도 않도록(skipCacheWrite) 짜여 있다고 적었다. 커뮤니티가 코드에서 읽어 낸 내용이고 Anthropic 이 확인한 설명은 아니다.

Anthropic 의 대응은 두 갈래다. 팀원은 가장 비싼 경우, 곧 캐시를 놓친 요약을 고친 수정을 2.1.311(10월 26일 빌드)부터 내보냈다고 HN 에 적었다. 공식 변경 기록의 2.1.311 항목에서는 요약 요청을 직접 다룬 줄을 찾지 못했고, 호출 횟수도 그대로다. Flamerix 는 2분 30초 남짓 도는 하위 에이전트 하나로 빌드마다 시험했는데, 10월 27일 빌드(2.1.312)도 그 전 빌드들처럼 훅이 없으면 요약을 다섯 번 보냈다.

다른 갈래는 더 싼 방식이다. gist 에 따르면 10월 23일 빌드(2.1.310)에 전체 기록 대신 약 2,000토큰짜리 메모를 보내고 더 작은 모델에 맡길 수도 있는 short 모드가 들어갔다. 이 모드는 서버 플래그로만 바뀌고 기본은 꺼져 있다. 팀원도 짧은 메모를 작은 모델에 보내는 훨씬 싼 모드를 만드는 중이라고 했지만, 켜는 시점은 밝히지 않았다.

05 내 몫은 OTel 이벤트의 query_source 로 잰다

세션 기록 파일을 합산하는 기존 비용 도구로는 이 요청이 보이지 않는다. 요청이 디스크의 세션 기록에 남지 않기 때문이다. 이슈 #104358 보고자는 세션 14개에서 기록 기반 합계가 Claude Code 내부 비용 집계보다 1.35~2.13배 낮았고, 하위 에이전트가 많은 세션일수록 차이가 컸다고 적었다. 그 차이에는 agent_summary 말고 다른 보조 요청과 기록에서 빠진 출력 토큰도 섞여 있다.

Claude Code 는 OTel 로 API 요청마다 claude_code.api_request 이벤트를 낸다. 공식 문서대로 로그 이벤트를 켜는 설정은 아래와 같고, 엔드포인트는 각자 쓰는 수집기 주소로 바꾸면 된다.

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com
claude

Claude Code 에는 기본 프로토콜이 없어서 OTEL_EXPORTER_OTLP_PROTOCOL 을 꼭 정해야 한다. 이벤트는 기본 5초마다 나간다. 메트릭만 켜서는 부족하다. 비용 메트릭 claude_code.cost.usage 의 query_source 는 공식 문서상 main·subagent·auxiliary 세 갈래뿐이라 agent_summary 를 따로 떼어 볼 수 없다. Flamerix 도 이벤트를 query_source 로 묶어 쟀다.

한 주쯤 모은 뒤 query_source 별로 cost_usd 합과 요청 수를 내면 전체에서 agent_summary 가 차지하는 비율이 나온다. agent_summary 요청을 input_tokens 크기순으로 늘어놓으면 캐시를 놓친 소수가 비용을 얼마나 끌어올리는지도 보인다. 구독으로 쓴다면 이 달러 값은 청구액이 아니라 사용 한도에서 빠지는 몫으로 읽는다.

06 공식 끄기 설정은 없고, 남은 길마다 대가가 있다

gist 작성자가 바이너리를 살펴본 바로는 켜는 쪽 설정만 있다. SDK 옵션 agentProgressSummaries 는 기본값이 false 지만 다른 조건과 OR 로 묶여 있어 끄는 데 쓸 수 없고, 문서에 없는 환경 변수 CLAUDE_CODE_AGENT_PROGRESS_SUMMARIES 도 켜기만 한다. 간격은 서버 플래그가 30~240초 안에서 정하는데 기본값이 이미 하한이다. 이름이 그럴듯한 DISABLE_NON_ESSENTIAL_MODEL_CALLS 는 바이너리에 아예 없다.

요청을 실제로 줄이는 길은 아래 다섯이다.

훅은 요약 타이머만 골라 막는다

마지막 줄의 훅은 Flamerix 가 MIT 라이선스로 공개한 no-agent-summary.js 다. Bun(Claude Code 실행 파일이 쓰는 자바스크립트 런타임)이 시작할 때 먼저 불러오는 preload 스크립트로, 전역 setTimeout 을 감싼다. 타이머 콜백의 소스를 Function.prototype.toString 으로 읽어 요약 타이머를 가리키는 문자열이 보이면, 지연 시간을 2³¹−1ms 로 잡아 사실상 울리지 않는 빈 타이머를 대신 돌려준다. 실행 파일이 미리 컴파일된 바이트코드라 파일을 고쳐도 소용이 없고, API 클라이언트가 전역 fetch 를 거치지도 않아 이 방법을 골랐다고 작성자는 설명했다.

export BUN_OPTIONS=--preload=/absolute/path/to/no-agent-summary.js
export CC_AGENT_SUMMARY_LOG=/absolute/path/to/agent-summary.log
claude daemon stop --any

데몬과 백그라운드 세션은 자신을 띄운 클라이언트의 환경을 물려받으므로, 데몬을 내린 뒤 열린 세션도 모두 다시 띄운다. --preload 뒤를 띄어 쓰면 다른 bun 하위 명령이 깨진다는 보고가 있어 = 로 붙인다. CC_AGENT_SUMMARY_MODE=pass 로 두면 훅은 올라가되 타이머를 막지 않으니 전후 비교에 쓸 수 있다. 걸렸는지는 세 가지로 확인한다. 로그의 preload active mode=off 줄, 백그라운드 에이전트를 1~2분 돌렸을 때 나오는 summary timer #1 suppressed 줄, OTel 의 agent_summary 요청 수 0 이다.

대가가 적지 않다. 훅은 문자열을 보고 타이머를 고르므로, 업데이트에서 로그 문구가 바뀌거나 타이머가 다른 API 로 옮겨 가면 경고 없이 요약이 다시 켜진다. 모든 Claude Code 프로세스 안에서 도는 코드라는 점도 걸린다. 이슈 #86879 에는 최신판을 curl 로 받아 바로 실행하는 설치 방식을 경계하는 댓글이 달렸다. 작성자가 직접 검증한 환경은 Linux 이고(macOS·Windows 는 다른 사용자 보고만 있다), gist 는 클라이언트 동작을 바꾸는 일이 서비스 약관과 부딪칠 수 있다고 스스로 적었다.

끄면 무엇을 잃는지는 출처마다 말이 다르다. gist 는 하위 에이전트·백그라운드 에이전트·포크 스킬은 그대로 돌고 패널 상태만 멈춘다고 했다. 팀원은 이 요약을 사용자뿐 아니라 Claude Code 자신도 기록을 읽지 않고 각 에이전트의 진행을 파악하는 데 쓴다고 했다. 이번 출처로는 어느 쪽이 맞는지 가릴 수 없다. 훅을 쓴다면 pass 와 off 를 번갈아 두고 작업 결과가 달라지는지 직접 보는 편이 낫다.

07 백그라운드 에이전트를 여럿, 오래 돌리는 팀만 먼저 재 보면 된다

이 비용이 닿는 쪽은 Claude Code 를 대화형 터미널에서 쓰며 백그라운드 에이전트를 동시에 여럿, 오래 돌리는 개인과 팀이다. Pro·Max 구독이라면 청구서는 그대로인 대신 사용 한도가 빨리 준다. Agent view 문서도 백그라운드 세션 하나하나가 구독 한도를 따로 쓴다고 적었다. HN 토론에는 주간 한도가 예상보다 빨리 줄었다는 보고가 여럿 올라왔지만, 그 가운데 얼마가 이 요청 때문인지는 가려지지 않았다. API 키로 쓴다면 이 몫이 토큰 요금에 그대로 얹힌다.

하지 않아도 되는 경우도 있다. 백그라운드 에이전트를 쓰지 않거나 띄우더라도 금방 끝나는 작업 한두 개라면, 비용이 에이전트 수·시간·문맥 크기를 따라 느는 구조상 몫이 커질 여지가 적다. 쉬는 에이전트에는 요청이 가지 않는다는 것이 팀원의 설명이다. 다만 긴 명령을 기다리는 에이전트는 쉬는 것으로 치지 않는다. 이슈 #86879 의 통제 시험에서는 sleep 20 만 여덟 번 되풀이하는 하위 에이전트에도 30초 남짓마다 요약이 나갔고, 에이전트가 끝나서야 멈췄다. 긴 빌드·테스트를 걸어 둔 에이전트도 그동안 계속 요약된다는 뜻이다.

CI·cron 처럼 claude -p 로 돌리는 비대화형 실행은 요약이 기본으로 꺼져 있다고 이슈 참여자가 번들에서 읽었고, Flamerix 도 -p 시험에서는 환경 변수로 일부러 켰다. 다만 gist 작성자는 포크 하위 에이전트와 포크 스킬은 SDK 모드에서도 요약된다고 답했으니, Agent SDK 로 에이전트를 짠 팀은 한 번 재 보는 편이 안전하다.

줄이는 순서는 되돌리기 쉬운 것부터 잡는 편이 낫다. 빌드 업데이트와 에이전트 수 조절은 잃는 것이 없고 언제든 되돌릴 수 있다. 환경 변수 두 개는 바로 효과가 나지만 기능을 함께 끈다. 훅은 지우면 되돌아오지만, 업데이트마다 확인하는 손과 모든 프로세스에 남의 코드를 들이는 보안 부담, 약관 문제를 함께 진다. Anthropic 이 더 싼 모드를 만들고 있다고 밝힌 만큼, 몫이 크지 않은 팀이라면 들이는 품에 비해 기다리는 쪽이 낫다.

1. 한 주 동안 OTel 이벤트를 모아 agent_summary 의 비용·요청 몫을 낸다.
2. 2.1.311 이후 빌드로 올리고, 전후로 agent_summary 요청의 input_tokens 분포를 비교한다.
3. 몫이 한 자릿수 초반이면 여기서 멈추고 공식 설정이나 싼 모드를 기다린다.
4. 두 자릿수라면 동시에 띄우는 백그라운드 에이전트 수와 수명부터 줄이고, 포크 모드가 꼭 필요하지 않으면 CLAUDE_CODE_FORK_SUBAGENT=0 을 시험한다.
5. 훅은 마지막에 두고, 코드를 읽어 본 사본 고정과 업데이트마다 재확인을 조건으로 건다.
6. 공식 끄기 설정을 요청한 이슈 #86879(아직 열려 있다)와 변경 기록의 short 모드 소식을 지켜본다.

08 자주 묻는 질문

disableAgentView 를 켜면 agent_summary 도 멈추나?

확인되지 않았다. 공식 문서는 같은 일을 환경 변수 CLAUDE_CODE_DISABLE_AGENT_VIEW 로도 할 수 있다고 적었고, 관리자가 관리 설정으로 강제할 수도 있다. HN 에서 이 설정을 켠 채 쓰는 사용자가 요약 요청까지 멈추는지 물었지만 답이 달리지 않았다. 켰다면 OTel 에서 agent_summary 요청 수를 직접 보는 수밖에 없다.

세션 기록에서 빠지는 요청은 agent_summary 하나뿐인가?

아니다. 이슈 #104358 은 자동 모드 분류기, 대화 압축(compact), 세션 제목 생성, 메모리 추출, 프롬프트 제안 같은 보조 요청도 기록에 줄이 남지 않는다고 적었다. 보고자 계산으로는 기록 기반 합계와 내부 집계의 차이 가운데 약 58%가 이런 요청에서, 약 42%가 하위 에이전트 기록에서 빠진 출력 토큰에서 나왔다.

훅이 Claude Code 를 느리게 하지는 않나?

gist 작성자가 잰 한 번의 측정에서는 claude --version 이 약 10ms 에서 약 17ms 로 늘었다. 훅은 서로 다른 타이머 콜백마다 소스를 한 번만 읽고 결과를 캐시해 둔다.