세션 예산

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

세션 생성 시 예산 설정

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

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    budget={
        "type": "limit",
        "max_list_cost": {"amount": "125", "currency": "USD"},
    },
)
print(session.id, session.budget.max_list_cost.amount)  # sesn_01... 125

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

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

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

정가 비용 측정 방식

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

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

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

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

세션이 예산에 도달할 때

상한은 요청 도중이 아니라 모델 요청 사이에 적용됩니다. 각 모델 요청 전에 플랫폼은 세션이 소비한 정가 비용을 확인하며, 그 합계가 상한에 도달하면 모든 스레드가 다음 요청 전에 일시 중지됩니다. 합계를 상한 너머로 올린 요청은 세션이 아직 상한 미만일 때 승인된 것이므로 끝까지 실행됩니다. 그 결과 일시 중지된 세션에 기록된 list_cost는 max_list_cost와 같거나 약간 초과한 값이 됩니다. 예를 들어 "50"(50센트)으로 상한이 설정된 세션은 list_cost가 "53"인 상태로 일시 중지될 수 있습니다. 이는 예상된 동작이며 청구 오류가 아닙니다. 상한을 초과하는 모델 지출은 스레드당 최대 모델 요청 1회의 비용입니다. 해당 요청의 응답에 포함된 도구 호출은 여전히 실행되며, 그 웹 검색과 실행 시간도 정가 비용에 포함됩니다. 예산을 정확한 중단 지점이 아닌 새 작업에 대한 한도로 취급하고, 이 여유분을 고려하여 상한 크기를 정하세요.

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

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

워크플로 실행이 열려 있는 경우, 아직 유휴 상태가 아닌 각 실행에도 workflow_run.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는 허용되며, 이벤트 목록에 나타나지 않습니다. 모든 스레드가 이미 일시 중지되어 있으므로 어떤 스레드도 중지하지 않습니다. 계속하려면 예산을 변경하거나 제거하세요.

세션에 열려 있는 워크플로 실행이 있는 경우, 다른 시점의 인터럽트와 마찬가지로 이 인터럽트가 실행을 일시 중지할 수 있습니다. 인터럽트로 일시 중지된 실행은 예산을 변경하거나 제거해도 재개되지 않습니다. 계속하려면 예산을 변경하거나 제거한 다음, 에이전트에게 실행을 계속하도록 요청하는 user.message를 보내세요. 실행이 열려 있는 세션 인터럽트를 참조하세요.

예산에 도달한 세션 재개

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

예산으로 인해 일시 중지된 각 워크플로 실행에도 workflow_run.status_running 이벤트가 전송됩니다. 중단으로 인해 일시 중지된 실행은, 그 중단이 세션이 예산에 도달해 있는 동안 전송되었더라도, 일시 중지된 상태로 유지되며 해당 업데이트로는 workflow_run.status_running 이벤트를 받지 않습니다. 이러한 실행을 계속하려면 에이전트에게 실행을 계속하도록 요청하는 user.message를 전송하세요. 실행이 열려 있는 세션 중단하기를 참조하세요.

예산 변경

새로운 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센트 이상 높게 설정하세요. 보고된 값은 반올림되어 있어 검사에 사용되는 정확한 소비 비용보다 약간 낮을 수 있습니다.

updated_session = client.beta.sessions.update(
    session.id,
    budget={
        "type": "limit",
        "max_list_cost": {"amount": "500", "currency": "USD"},
    },
)
print(updated_session.budget.max_list_cost.amount)  # 500

예산 제거

상한을 완전히 제거하려면 budget=None을 전달하세요. 예산으로 인해 일시 중지된 작업이 재개되며, 결과로 발생하는 session.updated 이벤트에는 budget이 null로 설정되어 있습니다.

unbudgeted_session = client.beta.sessions.update(session.id, budget=None)
print(unbudgeted_session.budget)  # None

지출 모니터링

세션 객체에는 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이 포함됩니다. 이 이벤트는 이벤트 목록과 세션 스트림에 나타납니다. 세션은 중지 이유와 관계없이 유휴 상태가 되기 직전에 이 이벤트를 하나 발생시키므로, 예산에 도달한 세션은 항상 예산 도달 idle 이벤트 직전에 이 이벤트를 발생시킵니다.

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

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

멀티에이전트 세션에는 모든 스레드가 공유하는 단일 예산이 있으며, 스레드별 상한은 없습니다. 각 스레드의 소비는 해당 스레드를 처리한 모델 기준으로 산정되며, 공유 상한에 도달하면 스레드는 독립적으로 일시 중지됩니다. 어드바이저 상담도 어드바이저 모델의 요금으로 산정되어 동일한 예산에 포함됩니다. 한 스레드가 budget_reached에서 일시 중지되는 동안 다른 스레드는 진행 중인 요청을 완료할 수 있습니다.

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

배포의 예산

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

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

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

정가가 없는 모델

예산은 플랫폼이 가격을 산정할 수 있는 소비만 추적할 수 있습니다. 다음 중 하나라도 공개 정가가 없는 모델을 사용하면 예산이 설정된 세션 생성이 400 오류로 거부됩니다:

• 세션의 에이전트
• subagents 또는 workflows의 predefined_agents 목록에 있는 모든 에이전트
• 에이전트의 멀티에이전트 구성에 설정된 어드바이저

오류에는 해당 모델에 사용할 수 있는 정가가 없다고 명시됩니다.

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

오류 참조

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

제공 여부