Claude Managed Agents 비용 제한: max_list_cost 설정과 중단 후 재개

이 글에서 사용하는 주요 용어 정의

용어정의

Managed Agents	Anthropic이 실행 루프와 인프라를 제공하는 에이전트 API 제품
세션	에이전트의 작업과 이벤트 이력을 관리하는 실행 단위
list cost	공개 정가로 계산한 누적 사용 비용
max_list_cost	세션에 설정하는 정가 비용 상한
budget_reached	예산 도달로 작업이 일시 정지됐다는 중단 사유

세션 생성 시 budget을 지정하면 장시간 에이전트 작업에 비용 한도를 둘 수 있습니다. 2026-10-09 기준 Managed Agents API의 베타 기능입니다.

> - 25달러 예산의 amount는 센트 단위 문자열 "2500"입니다.
> - 진행 중 요청은 완료되므로 최종 비용이 한도를 넘을 수 있습니다.
> - idle 상태에서는 중단 사유를 확인한 뒤 재개 여부를 판단합니다.

max_list_cost로 25달러 예산 설정하기

에이전트·실행 환경 식별자와 budget.type: limit을 지정합니다. 다음은 Anthropic Start a session 기반의 실행 미검증 예제입니다.

POST /v1/sessions 요청 본문에서 두 식별자를 실제 값으로 교체하세요.

{
  "agent": "교체할_에이전트_ID",
  "environment_id": "교체할_환경_ID",
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "2500", "currency": "USD"}
  }
}

공식 요청에는 인증 키 외에 anthropic-version: 2023-06-01, anthropic-beta: managed-agents-2026-04-01, JSON 콘텐츠 유형 헤더가 필요합니다. 예산 없이 만든 세션에는 나중에 예산을 추가할 수 없습니다.

amount는 양수 정수 문자열이며 선행 0을 쓰지 않습니다. "25.00"처럼 달러 소수값을 보내면 거절되고, 통화는 USD만 지원합니다. 이 입력 제약은 Anthropic Session budgets 문서에서 확인했습니다.

비용이 한도를 넘는 이유는 무엇인가요?

상한 검사는 모델 요청 사이에 이루어집니다. 한도에 도달할 때 진행 중이던 요청은 끝까지 실행되므로 스레드별 모델 요청 1회분의 초과 여유를 고려해야 합니다. 초과율이 일정한 것은 아닙니다.

Anthropic Session budgets에 따르면 모델 토큰·웹 검색·세션 실행시간이 정가 비용에 포함됩니다. 계약 할인을 적용한 청구액과는 차이가 있을 수 있습니다. 이 설정을 조직 전체의 월 청구액 상한으로 해석해서는 안 됩니다.

idle이면 작업이 끝난 건가요?

idle만으로 성공 처리해서는 안 됩니다. Anthropic Session event stream 문서처럼 session.status_idle 이벤트의 stop_reason.type을 함께 읽으세요.

중단 사유의미와 다음 처리

end_turn	턴 종료 또는 사용자 인터럽트. 결과를 확인합니다.
requires_action	도구 결과나 승인 응답 대기. 해당 요청에 응답합니다.
budget_reached	예산 도달. 소비액을 확인하고 예산 변경을 판단합니다.

예산 도달 상태에서 새 user.message를 보내면 400 오류가 발생합니다. 도구 응답·승인 등 기존 작업을 정리하는 이벤트는 허용되지만, 예산 정지를 해제하지는 않습니다.

비용은 세션의 usage.list_cost로 확인합니다. Anthropic Inspect sessions and track usage 문서에 따르면 스레드별 비용은 각각 반올림되고 세션 실행시간 비용이 빠지므로, 단순 합계가 세션 비용과 같지 않을 수 있습니다.

멀티에이전트는 세션 예산을 공유합니다. 도구 응답 대기가 겹치면 requires_action이 우선할 수 있어 사용량도 확인해야 합니다(Session budgets).

예산을 바꾸면 어떻게 재개되나요?

POST /v1/sessions/{session_id}로 예산을 갱신합니다. 새 한도는 이미 소비한 정가 비용보다 커야 하며, 유효한 변경을 받아들이면 일시 정지된 작업이 자동 재개됩니다. 다음은 소비액이 30달러 미만일 때만 사용할 수 있는 실행 미검증 본문 예제입니다.

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

판정에는 반올림 전 비용이 쓰입니다. 공식 Session budgets 문서는 표시된 usage.list_cost보다 최소 1센트 높게 설정하라고 설명합니다. 이는 갱신을 위한 최소 여유이지, 남은 작업을 마칠 수 있다는 보장은 아닙니다.

Anthropic Update Session 명세의 갱신 규칙은 다음과 같습니다.

• budget 생략: 기존 예산 유지. 객체 전달: 예산 교체.
• budget: null: 예산 제거. 제거 후 같은 세션에 재설정할 수 없습니다.
• 소비액 이하로 갱신: budget_not_raised. 예산 없는 세션에 추가: budget_create_only 오류 이유가 적용됩니다.

아직 소비액이 충분히 낮다면 기존 한도를 낮추는 것도 가능합니다. terminated 상태에는 이 예산 갱신 규칙을 적용할 수 없습니다.

테스트 세션에 작은 예산을 설정하고 budget_reached 처리부터 확인하세요. 다음 한도는 소비액과 남은 작업을 보고 정하는 것을 권합니다. 실제 API 호출·청구 대조는 수행하지 않았으며, 베타 명세는 적용 직전에 재확인해야 합니다.

참고 링크

• Anthropic — Session budgets
• Anthropic — Session event stream