Claude Agent SDK 헤드리스 과금 분리와 CI 비용 설계

자동화 실행은 구독 한도 밖에서 과금된다

Anthropic은 2026년 6월 15일부터 Claude Agent SDK와 GitHub Actions를 통한 헤드리스(Headless) 사용량을 인터랙티브 Claude Code 구독 한도에서 완전히 분리한다고 발표했다. 분리된 사용량은 달러 크레딧 기반 종량제(Pay-as-you-go)로 청구된다. 같은 시기에 동적 워크플로우(Dynamic Workflows)가 연구 미리보기(Research Preview)로 공개되면서 CI/CD 파이프라인과 자율 에이전트의 비용 구조도 다시 설계해야 하는 상황이 됐다.

이전에는 개발자가 직접 사용하는 Claude Code와 사람 없이 실행되는 자동화가 하나의 Pro/Max 구독 한도를 공유했다. 헤드리스 작업이 많아질수록 대화형 개발에 쓸 수 있는 토큰 풀이 줄어드는 충돌이 생겼다. 새 구조에서는 자동화 사용량을 별도 미터(Meter)로 보내 실제 소비한 만큼 크레딧에서 차감한다.

분류 기준은 실행 컨텍스트(Execution Context)다. Claude Code CLI가 TTY(tty) 세션에서 동작하면 인터랙티브 사용량으로 처리되어 구독 한도에 포함된다. TTY가 없는 GitHub Actions Runner, Docker 컨테이너, cron job에서는 헤드리스 사용량으로 분류되어 크레딧 풀에 청구된다. 이 판별은 Claude Code CLI가 자동으로 처리하므로 개발자가 별도 플래그를 지정할 필요는 없다.

⤢✕

Agent SDK가 오케스트레이션하는 서브에이전트(Sub-agent)도 헤드리스 범주에 들어간다. Claude Code를 오케스트레이터로 두고 여러 작업 에이전트를 병렬 실행한다면 멀티에이전트 파이프라인 전체가 크레딧 과금 대상이다.

구독과 크레딧을 나눠 관리하는 미터링 구조

새 모델에서는 구독(Subscription)과 크레딧(Credit)이 병렬로 작동한다. Pro 구독($20/월)과 Max 구독($100/월, $200/월)은 인터랙티브 사용량에 월간 한도를 제공한다. 헤드리스 사용량은 이 한도와 별개로 달러 크레딧에서 빠져나가며, 크레딧은 따로 구매하거나 자동 충전(Auto-recharge)으로 보충한다.

롤오버 없는 종량제도 구독 한도와 구별되는 지점이다. 크레딧은 매월 초기화되지 않고 구매 시점부터 12개월간 유효하지만, 월별 구독 한도처럼 잔액이 이월(Rollover)되는 구조는 아니다. 스프린트 집중 기간에는 소비량이 커지고 유휴 기간에는 거의 사용하지 않는 프로젝트의 불규칙한 패턴에 대응할 수 있다.

청구할 때는 입력 토큰(Input Token)과 출력 토큰(Output Token)을 구분한다. 캐시 읽기(Cache Read)와 캐시 쓰기(Cache Write)에도 서로 다른 요율을 적용한다. 따라서 Agent SDK의 프롬프트 캐싱(Prompt Caching)은 헤드리스 비용을 낮추는 주요 수단이 된다. 같은 시스템 프롬프트와 긴 컨텍스트를 반복하는 CI 파이프라인의 캐시 히트율은 60-80%에 달할 수 있으며, 그만큼 실효 단가를 크게 낮춘다.

사용 유형	과금 기준	한도 초과 시	캐싱 적용
인터랙티브	구독 월간 한도	속도 제한 또는 추가 구매	해당 없음
헤드리스 CI	달러 크레딧 종량제	자동 충전 또는 실행 중단	입력 토큰 캐시 할인
Agent SDK 서브에이전트	달러 크레딧 종량제	실행 중단 (에러 반환)	시스템 프롬프트 캐시
GitHub Actions	달러 크레딧 종량제	워크플로우 실패 처리	컨텍스트 캐시

실행 중 계획이 바뀌면 비용 경계도 달라진다

동적 워크플로우는 에이전트가 실행 도중 작업 계획을 고치고 새로운 서브태스크를 만들 수 있게 한다. 미리 정한 태스크 그래프를 순차 또는 병렬로 실행하는 정적 워크플로우(Static Workflow)와 달리, 실행 중 발견한 정보를 바탕으로 다음 계획을 수정한다.

비용에는 상반된 영향을 준다. 필요 없는 태스크를 일찍 끝내거나 더 효율적인 경로를 고르면 총 토큰 소비가 줄 수 있다. 반대로 동적 확장(Dynamic Expansion)이 발생하면 예상보다 많은 서브에이전트가 생성되어 비용이 급증할 수 있다. 이런 비예측성은 동적 워크플로우가 연구 미리보기 상태에 머무는 이유이기도 하다.

CI/CD에 적용할 때는 먼저 경계를 정해야 한다. 최대 재귀 깊이(Max Recursion Depth)와 최대 서브에이전트 수(Max Sub-agent Count)를 제한해 확장 범위를 통제한다. 이어 크레딧 소비가 설정한 임계값을 넘으면 Slack이나 PagerDuty로 알림을 보내도록 웹훅을 구성한다. 각 실행에는 프로젝트 ID, 팀 ID, 리포지토리 ID를 태그로 붙여 비용이 어느 조직과 코드베이스에서 발생했는지 추적한다.

연구 미리보기 기능은 비프로덕션(Non-production) 테스트 파이프라인에 먼저 적용하고, 크레딧 소비 패턴이 안정된 뒤 프로덕션으로 확장하는 방식이 적합하다.

월간 비용은 실행량과 분기 구조로 예측한다

구독 방식에서는 월간 최대 비용이 구독료로 제한됐다. 헤드리스 사용량이 종량제로 분리되면 에이전트 실행 빈도와 처리 복잡도에 따라 비용이 선형적으로 증가하므로 별도의 예측 모델이 필요하다.

평균 에이전트 실행 시간(Average Agent Run Duration)은 태스크 하나가 소비하는 총 토큰 수의 기댓값과 연결된다. 에이전트 실행 빈도(Agent Invocation Frequency)는 PR당, 커밋당 또는 시간당 평균 호출 횟수를 나타낸다. 캐시 히트율(Cache Hit Rate)은 시스템 프롬프트와 컨텍스트 재사용에 따른 실효 단가를 좌우한다. 멀티에이전트 분기 계수(Multi-agent Branching Factor)는 오케스트레이터 하나가 평균적으로 생성하는 서브에이전트 수를 표현한다.

예측식은 다음과 같이 구성할 수 있다.

월간 예상 크레딧 소비 = (평균 입력 토큰 × 입력 단가 × (1 - 캐시 히트율 × 캐시 할인율) + 평균 출력 토큰 × 출력 단가) × 평균 분기 계수 × 월간 실행 횟수

실제 파이프라인에서 30일 파일럿을 돌려 각 변수의 실측값을 모은 다음, 99th 퍼센타일 시나리오에 맞춰 예산 상한을 정하고 자동 충전 한도(Auto-recharge Cap)를 구성하는 방식이 권장된다.

Anthropic과 OpenAI의 분리 방식은 출발점이 다르다

Anthropic의 이번 전환은 OpenAI가 Assistants API와 Responses API에 적용한 에이전트 레이어 종량제와 같은 방향을 향한다. 다만 구독과 API를 분리한 시점과 플랫폼 구조에는 차이가 있다.

OpenAI의 ChatGPT Plus 구독($20/월)은 웹 인터페이스 사용에 한정되고 API 사용량은 처음부터 별도로 청구됐다. 인터랙티브와 헤드리스가 플랫폼 레이어에서 이미 분리된 셈이다. Anthropic은 구독 모델로 시작한 Claude Code가 Agent SDK와 CI 사용까지 포괄하면서 과금 구조의 불일치가 생겼고, 이번 변경으로 두 경로를 분리했다.

Claude Sonnet 4.5는 입력 $3/MTok, 출력 $15/MTok이며 캐시 읽기는 $0.30/MTok이다. GPT-4o는 입력 $2.50/MTok, 출력 $10/MTok으로 GPT-4o가 소폭 저렴하다. 그러나 Anthropic의 프롬프트 캐싱 효율이 더 높아 긴 컨텍스트를 반복해서 쓰는 경우에는 실효 단가가 역전되기도 한다.

항목	Anthropic Claude Code	OpenAI Codex CLI
인터랙티브 과금	구독 한도 내 포함	API 토큰 종량제
헤드리스/CI 과금	달러 크레딧 종량제 (신규)	API 토큰 종량제 (기존)
구독-API 분리 구조	이번에 도입	처음부터 분리
동적 워크플로우 지원	연구 미리보기	미제공 (계획 중)
캐시 할인율	입력 토큰의 90%	입력 토큰의 50%
멀티에이전트 오케스트레이션	공식 Agent SDK 제공	Responses API 기반

TCO에 거버넌스 운영비가 더해진다

과금 분리 뒤 기업의 AI 도구 총비용(TCO: Total Cost of Ownership)은 구독료, 헤드리스 크레딧, 거버넌스 인프라 비용으로 구성된다. 100인 개발팀이 Max 구독($200/월/인) 100개를 유지하면 구독료만 월 $20,000이며, 여기에 CI/CD 파이프라인이 사용하는 헤드리스 크레딧이 추가된다.

사용량을 통제하려면 Anthropic 콘솔의 Usage API를 Datadog이나 Grafana에 연동해 팀별 크레딧 소비를 실시간 대시보드로 보여줄 수 있어야 한다. 워크플로우마다 최대 크레딧 한도를 코드 수준에서 설정하고, 이를 넘으면 에러를 발생시켜 파이프라인을 중단하는 예산 가드레일(Budget Guardrail)도 필요하다. Claude Agent SDK에서는 max_tokens_per_run 파라미터와 budget_tokens 옵션이 이 역할을 맡는다.

리포지토리, 팀, 기능별 비용을 분류하면 FinOps 프로세스에 연결할 수 있다. GitHub Actions 워크플로우 파일에 X-Cost-Center 헤더를 포함하는 관례를 수립하면 사후 집계가 쉬워진다.

자동화 워크플로우는 헤드리스 경로로만 실행되도록 강제하고, CI 파이프라인 첫 단계에서 런타임 컨텍스트를 검증해야 한다. 그래야 헤드리스 작업이 인터랙티브 구독 풀을 소진하는 상황을 막을 수 있다.

과금 라우팅을 미터링 아키텍처로 읽기

이번 사례는 사용량 기반 과금(Usage-based Pricing)이 에이전트 시스템에 적용되는 방식을 보여준다. 소비한 만큼 지불(Pay-per-use)하는 SaaS 구조로 전환해, 가변적인 자동화 워크로드와 Flat-rate 구독 사이의 충돌을 분리했다.

미터링은 사용량 수집(Collection), 집계(Aggregation), 속성 부여(Attribution), 청구(Billing)로 이어진다. TTY 감지 결과에 따라 과금 경로를 나누는 방식은 실행 컨텍스트를 기준으로 사용 유형을 분류하는 패턴이다.

동적 워크플로우처럼 에이전트가 자율적으로 작업을 확장하면 비용도 예측 범위를 벗어날 수 있다. 그래서 예산 가드레일과 사용량 알림을 사후 운영 장치가 아니라 시스템 설계의 일부로 다뤄야 한다.

2026년 이후에는 실행 시간(Execution Time), 호출 횟수(Invocation Count), 성과(Outcome)를 기준으로 한 여러 과금 모델이 경쟁할 전망이다. 기업에는 자사 에이전트의 사용 패턴에 맞는 요금제를 선택하고 협상하는 역량이 FinOps의 핵심 스킬로 부상할 것이다.

인터랙티브 구독과 헤드리스 크레딧이 분리되면서 자동화 비용의 발생 지점은 더 명확해졌다. 그 대신 CI/CD와 멀티에이전트 실행을 얼마나 확장할지, 어디에서 멈출지, 어느 팀의 비용으로 기록할지를 기업이 직접 설계해야 한다. 헤드리스 파이프라인의 사용량 측정, 예산 제한, 비용 속성 추적이 이 구조를 운영하는 중심축이다.