Managed Agents 세션 예산

고급

What you'll learn

단일 Managed Agents 세션이 쓸 수 있는 금액을 US 센트 정수로 시작 전에 상한을 설정
세션이 budget_reached에서 일시정지될 때 발화하는 4단계 이벤트 시퀀스 읽기
요청 하나 분량의 초과 이해 — $0.50 상한이 $0.53에서 멈출 수 있는 이유와 그에 맞게 사이징하는 법
상한을 올리거나 제거해 일시정지된 세션 재개 — 그리고 제거가 단방향인 이유
예약된 배포에 실행별 상한을 걸어 반복 실행이 폭주 지출로 흘러가지 않게 하기
세션 예산과 Messages API 태스크 예산(권고적, 토큰 기반, 단일 루프) 구분하기

자율적인 Managed Agents 세션은 새벽 3시에 깨어나 어려운 도구 결과를 응시하다가 루프를 돌기 시작할 수 있습니다. 상한이 없으면 유일한 백스톱은 조직의 속도 제한이나 커피 후에 누군가가 읽을 모니터링 알림뿐입니다. 세션 예산은 Anthropic의 1급 해결책입니다: 세션 생성 시 설정하고 모델 요청 사이에 플랫폼이 시행하는 하드 달러 상한.

지금까지 만든 어떤 "비용 경보"와도 다른 두 가지:

상한은 사후에 웹훅이 아니라 플랫폼 측에서 각 모델 요청 전에 시행됩니다. 예산이 걸린 세션은 스스로 일시정지합니다.
상한은 US 센트 정수로, Anthropic의 공식 정가로 계산합니다 — 계약가가 아닙니다. 조직에 할인이 있으면 세션은 정가 달러로 상한에 도달하고 청구되는 지출은 그보다 낮게 나옵니다.

세션 예산 vs 태스크 예산 — 혼동 금지

이제 Claude 플랫폼에는 두 개의 "예산" 프리미티브가 있습니다. 서로 다른 문제를 해결합니다.

	세션 예산 (이 페이지)	태스크 예산 (Messages API)
표면	Managed Agents 세션 / 배포	Messages API 단일 에이전틱 루프
단위	US 달러, 센트 정수	토큰
시행	하드 — 플랫폼이 세션을 일시정지	권고적 — 모델이 스스로 조절
누가 읽는가	플랫폼의 비용 회계	모델이 지침으로
상한에서 일어나는 일	`stop_reason: "budget_reached"`, 세션이 유휴 상태로	모델이 마무리하고 반환

무인 실행에 하드 스톱이 필요하면 세션 예산. 하나의 루프 안에서 모델이 스스로 페이스를 조절하게 하려면 태스크 예산. 둘은 조합됩니다 — Managed Agents 세션이 세션 예산을 가지면서 그 안에서 하는 중첩된 Messages API 도구 호출이 자체 태스크 예산을 가질 수 있습니다.

세션 생성 시 예산 설정

POST /v1/sessions에 선택적 budget 필드를 전달:

$25.00로 상한이 걸린 세션 만들기

curl -fsSL https://api.anthropic.com/v1/sessions \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d '{
  "agent": "'"$AGENT_ID"'",
  "environment_id": "'"$ENVIRONMENT_ID"'",
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "2500", "currency": "USD"}
  }
}'

budget 오브젝트는 정확히 두 필드:

type은 항상 "limit". 오늘 다른 종류는 없으며, 필드가 존재하는 이유는 미래의 시행 형태가 기존 클라이언트를 깨뜨리지 않기 위함.
max_list_cost가 상한 자체. amount는 문자열로 된 US 센트 정수 — "2500"은 $25.00, "50"은 50 센트, "1"은 1 센트. "25.00" 같은 소수 형태는 400으로 거부됨. 문자열 형식은 의도적: 부동소수 반올림이 상한을 건드리지 않음. currency는 대문자 ISO-4217 코드이며, 오늘은 USD만 지원됨.

Watch out

예산은 세션 생성 시에만 첨부 가능. 예산 없이 생성된 이미 실행 중인 세션에 예산을 추가하면 400을 반환 — 미리 계획할 것.
amount는 센트 정수의 문자열. "25.00"은 거부됨. "0"은 거부됨. "-1"은 거부됨.

정가 비용 측정 방식

플랫폼은 세션이 소비하는 것을 공식 정가로 계속 계산하며, 이 누적 합계를 세션의 **정가 비용(list cost)**이라고 부릅니다. 세 가지가 여기에 들어갑니다:

모델 토큰, 각 서빙 모델의 정가로. 멀티에이전트 세션에서는 각 스레드의 토큰이 해당 스레드 모델의 가격으로 계산됨.
웹 검색, 1,000 요청당 $10 (즉 검색당 1 센트).
세션 실행 시간, 활성 세션 시간 시간당 $0.08.

웹 fetch 요청은 미터 중립: server_tool_use 카운터에 나타나지만 요청당 요금이 없고 예산에 반영되지 않음.

내재화할 만한 두 가지 회계 세부사항:

시행은 정확한 반올림되지 않은 정가 비용을 사용. 세션 및 이벤트 오브젝트에 표시되는 list_cost는 센트 정수로 반올림되므로 보고된 수치는 시행 검사가 읽는 값에서 반 센트 정도 어느 방향으로든 벗어날 수 있음. 반올림된 두 값을 비교해 플랫폼이 "센트를 잊었다"고 결론짓지 말 것.
멀티에이전트 세션에서 세션 레벨의 active_seconds는 겹치는 스레드 활동을 한 번만 계산 (병렬 작업의 실행 시간을 이중 청구하지 않기 위해). 스레드별 active_seconds는 스레드별로 계산되고 세션의 실행 시간 비용을 제외하므로 스레드 list_cost를 합해도 세션 list_cost와 같지 않음. 세션 수치를 믿을 것 — 상한은 그것에 대해 시행됨.

요청 하나 분량의 초과

세션 예산에서 가장 놀라운 것이자 알림을 여기에 맞춰 설계해야 하는 것.

상한은 요청 사이에 확인되지 요청 중간이 아님. 각 요청 전에 플랫폼이 세션의 소비된 정가 비용을 읽고, 상한에 도달하면 모든 스레드가 다음 요청 전에 일시정지. 총합을 상한 너머로 넘긴 요청은 세션이 여전히 상한 아래일 때 입장했고 완료까지 실행됨.

결과: "50" (50 센트)로 상한이 걸린 세션이 list_cost "53"에서 일시정지될 수 있음. 이는 청구 버그가 아님. 초과는 스레드당 모델 요청 하나로 제한되지만 — 여러 동시 스레드가 있는 멀티에이전트 로스터에서는 그 "하나"가 곱해짐.

Pro tip

max_list_cost를 새 작업의 경계로 다루고 정확한 정지점으로 여기지 말 것. 지출이 절대 $X를 넘지 않도록 보장해야 하면 상한을 X - (max_request_cost * concurrent_threads)로 설정. 값비싼 Opus 호출을 하는 25스레드 멀티에이전트 세션에서는 여유가 의미 있을 수 있음.

세션이 예산에 도달하면 벌어지는 일

예산에 도달한 세션은 죽지 않고 유휴 상태가 되며, 히스토리와 샌드박스는 보존됨. 이벤트 스트림에서 순서대로 다음을 볼 수 있음:

Guided walkthrough1 of 4

각 스레드가 진행 중인 요청을 마치면 stop_reason: "budget_reached"로 idle 이벤트를 발화. 마지막 요청이 자체 턴을 완료한 스레드는 자체 이벤트에서 stop_reason: "end_turn"으로 보고할 수도 있지만 — 세션 레벨 이벤트는 여전히 budget_reached로 보고. 세션 레벨 신호를 믿을 것.

상한에서 세션이 여전히 받아들이는 이벤트

상한에서 일시정지되는 동안 세션은 이미 진행 중인 작업을 정산하는 이벤트만 받아들임:

user.tool_confirmation
user.tool_result
user.custom_tool_result
user.interrupt

user.message — 새 작업을 시작하는 것 — 는 위 목록을 정확히 명명하는 400 오류로 거부됨. 완전히 일시정지된 세션에 보내진 user.interrupt는 받아들여지고 조용히 무시됨 (이벤트 목록에도 나타나지 않음). 진행 중인 도구를 정산해도 새 모델 요청이 트리거되지 않으며, 세션은 일시정지 상태를 유지.

재개: 예산 변경 또는 제거

정확히 두 개의 레버.

예산 변경

새로운 max_list_cost로 PATCH (또는 SDK의 update)를 전송. 새 값은 이전 상한보다 높거나 낮을 수 있음 — 그러나 반드시 세션의 소비된 정가 비용보다 엄격히 커야 함, 그렇지 않으면 다음을 받음:

400 budget.max_list_cost must be greater than the session's consumed list cost

Watch out

세션이 일시정지될 때 소비된 비용이 대개 이전 상한을 약간 넘어 앉기 때문에, 새 값은 이전 max_list_cost가 아니라 세션의 보고된 usage.list_cost를 기준으로 할 것. 새 상한을 보고된 수치보다 최소 1센트 위로 설정 — 보고된 값은 반올림되어 검사가 사용하는 정확한 소비 비용보다 살짝 아래에 앉을 수 있음.

상한을 $40.00로 올리기

curl -sS --fail-with-body "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d '{"budget": {"type": "limit", "max_list_cost": {"amount": "4000", "currency": "USD"}}}'

허용된 업데이트는 일시정지된 작업을 자동으로 재개함. 다른 것을 보낼 필요 없음.

예산 제거

budget을 null로 설정하면 상한이 사라짐. 세션이 재개되고 결과로 발생하는 session.updated 이벤트는 budget: null을 담음.

{"budget": null}

Watch out

제거는 단방향임. 예산이 제거된 세션은 새 예산을 받을 수 없음 — 이는 "예산은 생성 시에만"이라는 규칙이 제거에 적용된 것과 같은 규칙. 세션에 상한을 유지하고 싶다면 항상 변경하세요. 세션을 의식적으로 조직의 정상 지출 제한에 돌려줄 때만 제거하세요.

배포에서의 예산 — 실행별, 누적 아님

예약된 배포는 같은 budget 오브젝트를 받아들임:

{
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "2000", "currency": "USD"}
  }
}

상한은 배포가 시작하는 각 세션에 복사됨. 각 실행을 개별적으로 제한 — 배포의 모든 실행 누적 지출을 제한하지 않음. 매일 크론과 월 30회 실행이 있는 $20 배포 예산은 따라서 정가 비용으로 최대 ~$600까지 태울 수 있으며, $20가 아님.

세션 예산과의 두 가지 추가 차이:

배포의 예산 변경은 그 이후 배포가 시작하는 세션에 적용 — 이미 실행 중인 세션은 생성 시 부여된 예산을 유지.
세션과 달리 배포의 예산은 null로 지울 수 있고 나중에 다시 설정 가능. 단방향 제거 규칙은 세션 레벨 규칙이지 배포 레벨 규칙이 아님.

멀티에이전트, 어드바이저, 공유 상한

멀티에이전트 세션은 모든 스레드에 걸친 단일 공유 예산을 가짐 — 스레드별 상한은 없음. 각 스레드의 소비는 자체 서빙 모델로 계산되며, 공유 상한에 도달하면 스레드들이 독립적으로 일시정지. 한 스레드는 budget_reached에서 일시정지되어 있고 다른 스레드는 여전히 진행 중인 요청을 마무리하고 있을 수 있음.

어드바이저 상담도 같은 예산에 반영되며, 어드바이저 모델의 요금으로 계산. 그래서 $10 예산 세션에서 Sonnet-5 실행자가 상담하는 Opus-5 어드바이저는 같은 풀에서 끌어씀. 비용 최적화를 위해 어드바이저 패턴을 사용한다면 실행자만이 아니라 두 계층 모두에 맞춰 상한을 크기 조정할 것.

한 가지 중요한 타이 브레이커: 대기 중인 요청이 상한을 앞섬. 한 스레드가 requires_action (예: user.tool_confirmation)을 기다리고 있고 다른 스레드가 budget_reached에서 일시정지되어 있으면, 세션은 최상위 수준에서 requires_action을 보고 — 그 요청에 답하는 것은 예산이 차단하지 않는 정산 이벤트이기 때문. 오퍼레이터 UI는 requires-action 프롬프트를 먼저 표시해야 함.

정가가 없는 모델

예산은 플랫폼이 가격을 매길 수 있는 소비만 추적할 수 있음. 두 가지 실패 모드:

생성 시: 자체 에이전트 — 또는 멀티에이전트 로스터의 어떤 에이전트나 어드바이저 — 가 공식 정가가 없는 모델을 사용하는 예산 세션을 생성하면 정확히 no list price is available for the model이라는 메시지와 함께 400을 반환. 아직 가격이 매겨지지 않은 프리뷰/리서치 프리뷰 모델 포함.
생성 후: 예산 세션의 사용량이 (예: 세션 레벨 오버라이드가 추가한 로스터 항목을 통해) 가격이 없는 모델을 포함하게 되면, 예산은 더 이상 지출을 측정할 수 없음. 세션은 여전히 stop_reason: "budget_reached"로 일시정지될 수 있고 예산 변경 시도는 거부됨. 유일한 복구는 예산을 제거하는 것 — 이는 위의 규칙대로 단방향임. 로스터를 이것이 실행 중에 발생할 수 없도록 설계할 것.

오류 레퍼런스

예산 관련 400 조건의 전체 목록:

조건	상태
세션이 예산에 도달하거나 초과했을 때 작업 시작 이벤트(예: `user.message`) 전송	400 (오류가 허용된 정산 이벤트를 명명)
예산이 세션의 소비된 정가 비용 이하로 설정됨	400
예산 없이 생성된 세션에 예산이 추가되거나 제거 후 다시 추가됨	400
`amount`가 센트 정수가 아니거나(예: `"25.00"`) 0 또는 음수, 또는 `currency`가 `USD`가 아님	400
예산이 걸린 생성이 공식 정가가 없는 모델을 참조	400

운영 체크리스트

세션 예산을 켜는 날 런북에 넣을 만한 여섯 가지:

Guided walkthrough1 of 6

요청 하나 분량의 초과와 평소보다 긴 실행 한 번에 대한 여유를 주세요. 센트 정수만 — "25.00" 금지.

크로스 AI 노트: 다른 플랫폼은 어떻게 다루는가

주요 호스팅 에이전트 플랫폼 중 어느 것도 Anthropic의 8월 7일 릴리스 전에는 동등한 프리미티브를 출시하지 않음. 2026-08-11 기준 다른 곳에서 근사할 수 있는 것:

OpenAI: 조직 레벨의 월간 지출 제한과 프로젝트별 사용 제한이 존재하지만, 실행별이 아니며 Assistants / Responses API 세션을 루프 중간에 일시정지할 수 없음. 토큰 스트림을 감시하는 자체 웹훅으로 백스톱.
Google Vertex AI (Gemini): 프로젝트 레벨 쿼터와 (Cloud Billing을 통한) 청구 예산은 비동기 — 알림은 주지만 에이전트를 인라인으로 일시정지하지 않음.
AWS Bedrock: 모델 호출 쿼터는 초당/분당 하드 상한이지 세션별 달러 상한이 아님. 세션 레벨 지출 게이팅은 사용자 책임.
서드파티 게이트웨이 (LiteLLM, OpenRouter, Portkey): 모두 도달 시 HTTP 오류를 반환하는 키별 예산 상한을 제공 — 세션 예산에 형태상 더 가깝지만 "일시정지 및 재개" 동작은 1급 프리미티브가 아님.

비용이 Managed Agents vs 게이트웨이와 함께 홈롤링된 루프를 평가하는 바로 그 이유라면, 우아한 일시정지를 갖춘 세션별 하드 상한은 이번 주 실제 차별화 지점.

Key takeaways

세션 예산은 Managed Agents 세션에 대한 하드, 플랫폼 시행 USD 상한으로, 공식 정가로 계산되며 세션 생성 시에만 설정됨
stop_reason은 budget_reached. session.thread_status_idle → session.usage → session.status_idle 순서를 기대 — 그 순서에 맞춰 핸들러를 구축
소비된 비용은 상한을 약간(스레드당 요청 하나까지) 넘어 앉을 수 있음 — 그 초과를 염두에 두고 상한을 크기 조정
재개하려면 상한을 현재 list_cost보다 엄격히 큰 값으로 변경; budget: null로 완전히 제거 — 그러나 제거는 단방향
배포 예산은 실행별이지 누적 아님. $20 실행당 상한이 있는 매일 작업은 $20 월간 상한이 아님
세션 예산(하드, USD, 플랫폼 시행)과 Messages API 태스크 예산(권고적, 토큰, 모델 시행)을 혼동하지 말 것

자기 점검

0/4

max_list_cost가 "50" (50 센트)인 세션을 만들었습니다. 세션이 usage.list_cost "53"에서 일시정지됩니다. 무슨 일이 일어난 것입니까?
예산 없이 생성된 세션이 한 시간 동안 실행 중입니다. 상한을 걸고 싶다는 것을 깨달았습니다. 무엇을 할 수 있습니까?
매일 크론에 $20 실행당 예산이 있는 배포가 있습니다. 30일 월간에 걸쳐 배포가 발생시킬 수 있는 최대 정가 비용은?
예산이 걸린 세션이 budget_reached에서 일시정지되어 있습니다. user.message를 보내 계속하라고 요청합니다. 무슨 일이 일어납니까?

Managed Agents — 이 예산이 걸리는 코디네이터 + 세션 멘탈 모델
Managed Agents 메모리 저장소 — 2026년 7월 지속적 메모리 베타
Managed Agents의 노력 튜닝 — 에이전트 생성 시 설정하는 다른 큰 비용 레버
어드바이저 도구 — Sonnet이 일하고 Opus가 생각한다 (그 비용은 세션 예산에 반영됨)
에이전트가 토큰을 태우는 이유 — $1 턴을 $50 루프로 바꾸는 설계 패턴
프로바이더별 AI 비용 — 크로스 모델 컨텍스트
자율 실행 강화 — 비용 상한은 세 가드레일 중 하나이지 셋이 아니므로

세션 예산 vs 태스크 예산 — 혼동 금지​

세션 생성 시 예산 설정​

$25.00로 상한이 걸린 세션 만들기

정가 비용 측정 방식​

요청 하나 분량의 초과​

세션이 예산에 도달하면 벌어지는 일​

상한에서 세션이 여전히 받아들이는 이벤트​

재개: 예산 변경 또는 제거​

예산 변경​

상한을 $40.00로 올리기

예산 제거​

배포에서의 예산 — 실행별, 누적 아님​

멀티에이전트, 어드바이저, 공유 상한​

정가가 없는 모델​

오류 레퍼런스​

운영 체크리스트​

크로스 AI 노트: 다른 플랫폼은 어떻게 다루는가​

자기 점검​

자기 점검

다음​

세션 예산 vs 태스크 예산 — 혼동 금지

세션 생성 시 예산 설정

정가 비용 측정 방식

요청 하나 분량의 초과

세션이 예산에 도달하면 벌어지는 일

상한에서 세션이 여전히 받아들이는 이벤트

재개: 예산 변경 또는 제거

예산 변경

예산 제거

배포에서의 예산 — 실행별, 누적 아님

멀티에이전트, 어드바이저, 공유 상한

정가가 없는 모델

오류 레퍼런스

운영 체크리스트

크로스 AI 노트: 다른 플랫폼은 어떻게 다루는가

자기 점검

다음