세션 예산

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

세션 생성 시 예산 설정

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

# 금액이 숫자가 아닌 문자열로 전송되도록 따옴표를 유지하세요.
SESSION_ID=$(ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID" \
  --budget '{type: limit, max_list_cost: {amount: "125", currency: USD}}' \
  --transform id --raw-output)

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

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

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

정가 비용 측정 방식

플랫폼은 세션이 소비하는 것을 공개 정가 기준으로 지속적으로 가격을 산정합니다:

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

이 누적 달러 합계가 세션의 정가 비용이며, 예산은 이 값과 비교됩니다. 정가 비용은 계약 가격이 아닙니다. 조직이 할인을 협상한 경우, 세션은 정가 합계가 상한에 도달할 때 상한에 도달하며, 실제 청구되는 지출은 상한보다 낮을 수 있습니다.

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

세션이 예산에 도달할 때

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

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

1. 각 스레드가 일시 중지될 때 stop_reason이 budget_reached인 session.thread_status_idle 이벤트
2. 세션의 누적 사용량과 정가 비용이 포함된 session.usage 이벤트
3. stop_reason이 budget_reached인 session.status_idle 이벤트. 사용량 이벤트는 항상 이 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로 세션을 업데이트하세요. 새 값은 현재 상한보다 높거나 낮을 수 있지만, 세션의 소비된 정가 비용보다 반드시 커야 합니다. 그렇지 않으면 업데이트가 400 오류로 거부됩니다: budget.max_list_cost must be greater than the session's consumed list cost. 세션이 일시 중지될 때 소비된 비용은 보통 이전 상한을 약간 초과하므로, 새 값은 이전 max_list_cost가 아닌 세션의 보고된 usage.list_cost를 기준으로 정하세요. 해당 수치보다 1센트 이상 높게 설정하세요. 보고된 값은 반올림되어 있어 검사에 사용되는 정확한 소비 비용보다 약간 낮을 수 있습니다.

ant beta:sessions update \
  --session-id "$SESSION_ID" \
  --budget '{type: limit, max_list_cost: {amount: "500", currency: USD}}'

예산 제거

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

ant beta:sessions update --session-id "$SESSION_ID" --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, 그리고 웹 가져오기 요청에는 요청당 요금이 없고 계량되지 않으므로 0으로 표시되는 web_fetch_requests), 그리고 세션의 budget 사본(세션에 예산이 없으면 null)을 포함합니다. 이벤트 목록과 세션 스트림에 나타납니다. 세션은 중지 사유와 관계없이 idle 상태가 되기 직전에 이 이벤트를 하나 발행하므로, 예산에 도달한 세션은 항상 예산 도달 idle 이벤트 직전에 이 이벤트를 발행합니다.

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

멀티에이전트 세션의 예산

멀티에이전트 세션은 모든 스레드가 공유하는 단일 예산을 가지며, 스레드별 상한은 없습니다. 각 스레드의 소비는 해당 스레드에 제공된 모델 기준으로 산정되며, 공유 상한에 도달하면 스레드가 독립적으로 일시 중지됩니다. 어드바이저 자문은 어드바이저 모델의 요율로 산정되어 동일한 예산에 포함됩니다. 한 스레드가 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인 상태로 일시 중지될 수 있으며, 예산 변경은 거부됩니다. 세션을 재개하려면 예산을 제거하세요.

오류 참조

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