세션 예산

세션 예산은 세션을 생성할 때 설정하는 선택적 하드 지출 상한선입니다. 플랫폼은 세션이 소비하는 모든 항목을 공개 정가(세션의 list cost(정가 비용))로 지속적으로 계산하며, 해당 비용이 예산에 도달하면 새로운 모델 요청 발행을 중단합니다. 상한선을 넘는 시점에 진행 중이던 요청은 여전히 완료되므로, 최종 정가 비용은 예산을 약간 초과할 수 있습니다. 예산에 도달한 세션은 종료되지 않고 일시 중지되어 idle(유휴) 상태가 되며, 예산을 변경하거나 제거하면 작업이 자동으로 재개됩니다. 배포도 동일한 예산을 받아 시작하는 각 세션에 적용합니다. 배포의 예산을 참조하세요.



세션 생성 시 예산 설정

세션을 생성할 때 선택적 budget 필드를 전달하세요:

session=$(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 @- <<EOF
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "2500", "currency": "USD"}
  }
}
EOF
)
SESSION_ID=$(jq -r '.id' <<< "$session")

budget 객체에는 두 개의 필드가 있습니다:

• type은 항상 "limit"입니다.
• max_list_cost는 상한선 자체입니다. amount는 선행 0이 없는 문자열로 작성된 미국 센트 단위의 정수입니다("2500"은 $25.00이고 "50"은 50센트입니다). 0보다 커야 합니다. "25.00"과 같은 소수 형식은 거부됩니다. 금액이 숫자가 아닌 문자열인 이유는 부동소수점 반올림이 적용되지 않도록 하기 위함입니다. currency는 대문자 ISO-4217 통화 코드이며, USD가 유일하게 지원되는 통화입니다.

예산은 세션이 생성될 때만 첨부할 수 있습니다. 예산이 없는 기존 세션에 예산을 추가하면 400 오류와 함께 거부됩니다. 예산이 설정된 세션의 상한선은 언제든지 변경하거나 제거할 수 있습니다.



정가 비용 측정 방식

플랫폼은 세션이 소비하는 항목을 공개 정가로 지속적으로 계산합니다:

• 모델 토큰: 제공된 각 모델의 정가 기준
• 웹 검색: 검색 1,000건당 $10
• 세션 실행 시간: 시간당 $0.08

이 누적 달러 총액이 세션의 list cost(정가 비용)이며, 예산이 비교하는 대상입니다. 정가 비용은 계약된 가격이 아닙니다. 조직이 할인을 협상한 경우, 세션은 정가 총액이 상한선에 도달할 때 상한선에 도달하며, 실제 청구되는 지출은 상한선보다 낮을 수 있습니다.

적용은 반올림되지 않은 정확한 정가 비용을 사용합니다. 세션 및 해당 이벤트에 보고되는 list_cost 수치는 가장 가까운 센트로 반올림된 정수 센트이므로, 보고된 수치는 적용에 사용되는 정확한 금액에서 최대 0.5센트 차이가 날 수 있습니다.



세션이 예산에 도달할 때

상한선은 요청 도중이 아니라 모델 요청 사이에 적용됩니다. 각 모델 요청 전에 플랫폼은 세션의 소비된 정가 비용을 확인하며, 해당 총액이 상한선에 도달하면 모든 스레드가 다음 요청 전에 일시 중지됩니다. 총액을 상한선 너머로 넘긴 요청은 세션이 아직 상한선 아래에 있을 때 허용되어 완료까지 실행되므로, 일시 중지된 세션의 기록된 list_cost는 max_list_cost와 같거나 약간 초과한 값으로 표시됩니다. 예를 들어 "50"(50센트)으로 제한된 세션은 list_cost가 "53"인 상태로 일시 중지될 수 있습니다. 이는 청구 오류가 아니라 예상된 동작이며, 초과분은 스레드당 하나의 모델 요청으로 제한됩니다. 예산을 정확한 중단 지점이 아니라 새로운 작업에 대한 한계로 간주하고, 이 한 요청만큼의 여유를 고려하여 상한선을 설정하세요.

예산에 도달한 세션은 stop_reason이 budget_reached인 상태로 유휴 상태가 됩니다. 종료되지 않으며, 다른 유휴 세션과 마찬가지로 기록과 샌드박스가 보존됩니다. 이벤트 스트림에서는 다음 순서로 표시됩니다:

1. 각 스레드가 일시 중지될 때 stop_reason이 budget_reached인 session.thread_status_idle 이벤트.
2. 세션의 누적 사용량 및 정가 비용이 포함된 session.usage 이벤트.
3. stop_reason이 budget_reached인 session.status_idle 이벤트. 사용량 이벤트는 항상 이 유휴 이벤트 바로 앞에 나타납니다.

마지막 요청이 상한선을 넘으면서 동시에 턴을 완료한 스레드는 자체 session.thread_status_idle 이벤트에서 end_turn을 보고하지만, 세션은 여전히 budget_reached를 보고합니다. 세션이 예산에서 일시 중지되었다는 신호로는 세션 수준의 stop_reason을 사용하세요.



상한선에서 허용되는 이벤트

세션이 예산에 도달했거나 초과한 동안에는 이미 진행 중인 작업을 정리하는 이벤트만 허용됩니다:

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

user.message와 같이 새로운 작업을 시작하는 이벤트는 이 목록을 명시한 400 오류와 함께 거부됩니다. 정리된 결과는 새로운 모델 요청을 트리거하지 않고 기록되며, 세션은 예산에서 일시 중지된 상태를 유지합니다.

세션이 예산에서 일시 중지된 동안(모든 스레드가 상한선에서 일시 중지됨) 전송된 user.interrupt는 허용되지만 무시됩니다. 이벤트 목록에 나타나지 않으며 아무것도 변경하지 않습니다. 계속하려면 예산을 변경하거나 제거하세요.



예산에 도달한 세션 재개

세션 업데이트로 예산을 변경하거나 제거하세요. 업데이트가 수락되면 세션의 일시 중지된 작업이 자동으로 재개되며, 추가 클라이언트 작업은 필요하지 않습니다.



예산 변경

새로운 max_list_cost로 세션을 업데이트하세요. 새 값은 현재 상한선보다 높거나 낮을 수 있지만, 세션의 소비된 정가 비용보다 엄격히 커야 합니다. 그렇지 않으면 budget.max_list_cost must be greater than the session's consumed list cost라는 400 오류와 함께 업데이트가 거부됩니다. 세션이 일시 중지될 때 소비된 비용은 일반적으로 이전 상한선을 약간 초과한 상태이므로, 새 값은 이전 max_list_cost가 아니라 세션에 보고된 usage.list_cost를 기준으로 설정하세요. 해당 수치보다 1센트 이상 높게 설정하세요. 보고된 값은 반올림되어 검사에 사용되는 정확한 소비 비용보다 약간 낮을 수 있습니다.

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 @- <<'EOF'
{
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "4000", "currency": "USD"}
  }
}
EOF



예산 제거

상한선을 완전히 제거하려면 budget을 null로 설정하세요. 세션의 일시 중지된 작업이 재개되며, 결과로 나타나는 session.updated 이벤트는 budget이 null로 설정된 상태로 전달됩니다.

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": null}'



지출 모니터링

세션 객체는 budget과 추적된 지출이 포함된 usage 객체를 전달합니다. usage.list_cost는 세션의 소비된 정가 비용이고, usage.active_seconds는 런타임 비용이 계산되는 실행 시간입니다. budget_reached에서 일시 중지된 세션에서는 usage.list_cost가 max_list_cost와 같거나 약간 초과한 값으로 표시될 것으로 예상하세요. 상한선을 넘은 요청이 일시 중지 전에 완료되었기 때문입니다. 세션 수준의 active_seconds는 동시 스레드의 겹치는 활동을 한 번만 계산합니다. 스레드 조회 응답은 스레드별로 계산된 동일한 두 필드를 스레드 자체의 usage에 전달합니다. 스레드별 수치는 독립적으로 반올림되며 세션의 실행 시간 비용을 제외하므로, 세션의 list_cost와 정확히 합산되지 않습니다. 예산이 적용되는 대상은 세션 수치입니다.

session.usage 이벤트는 세션의 누적 사용량 및 추적된 정가 비용의 스냅샷입니다. 세션의 토큰 총계, list_cost, active_seconds, server_tool_use 요청 수(web_search_requests는 요청당 정가 비용에 반영되며, web_fetch_requests는 웹 가져오기 요청에 요청당 요금이 없고 측정되지 않으므로 0으로 표시됨), 그리고 세션의 budget 에코(세션에 예산이 없으면 null)를 전달합니다. 이벤트 목록과 세션 스트림에 나타납니다. 세션은 중지 이유와 관계없이 유휴 상태가 되기 직전에 하나를 내보내므로, 예산에 도달한 세션은 항상 budget-reached 유휴 이벤트 직전에 하나를 내보냅니다.

스트림 및 세션 객체에서 사용량을 읽는 방법은 사용량 추적을 참조하세요.



멀티에이전트 세션의 예산

멀티에이전트 세션은 모든 스레드에서 공유되는 단일 예산을 가지며, 스레드별 상한선은 없습니다. 각 스레드의 소비는 자체 제공 모델의 가격으로 계산되며, 공유 상한선에 도달하면 스레드가 독립적으로 일시 중지됩니다. Advisor(어드바이저) 상담은 어드바이저 모델의 요율로 계산되어 동일한 예산에 반영됩니다. 한 스레드가 budget_reached에서 일시 중지되는 동안 다른 스레드는 진행 중인 요청을 완료할 수 있습니다.

대기 중인 요청은 상한선보다 우선합니다. 한 스레드가 requires_action을 기다리고 다른 스레드가 budget_reached에서 일시 중지된 세션은 세션 수준에서 requires_action을 보고합니다. 대기 중인 요청은 여전히 응답이 필요하며, 이에 응답하는 것은 예산이 차단하지 않는 정리 이벤트입니다.



배포의 예산

배포는 생성하거나 업데이트할 때 동일한 budget 객체를 받습니다:

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

상한선은 배포가 시작하는 각 세션에 복사되므로, 배포의 누적 지출이 아니라 각 실행을 개별적으로 제한합니다. 배포의 예산을 변경하면 이후에 배포가 시작하는 세션에 적용되며, 이미 실행 중인 세션에는 적용되지 않습니다. 세션과 달리 배포의 예산은 null로 지운 후 나중에 다시 설정할 수 있습니다. 각 실행에 예산 설정을 참조하세요.



정가가 없는 모델

예산은 플랫폼이 가격을 계산할 수 있는 소비만 추적할 수 있습니다. 에이전트 또는 멀티에이전트 로스터의 에이전트나 어드바이저가 공개 정가가 없는 모델을 사용하는 예산 설정 세션을 생성하면, 해당 모델에 대한 정가를 사용할 수 없다는 400 오류와 함께 거부됩니다.

예산이 설정된 세션의 사용량에 정가가 없는 모델이 포함되면, 예산은 더 이상 세션의 지출을 측정할 수 없습니다. 세션은 stop_reason이 budget_reached인 상태로 일시 중지될 수 있으며, 예산 변경은 거부됩니다. 세션을 재개하려면 예산을 제거하세요.



오류 참조

예산 관련 요청은 다음 경우에 거부됩니다: