> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 세션 AI 크레딧 한도

> sessionLimits로 Copilot 세션에 AI 크레딧 한도를 설정하고, 한도 관련 이벤트와 한도 소진 프롬프트를 처리합니다.

`sessionLimits`를 사용하면 Copilot 세션의 현재 집계 기간에 대해 소프트 AI 크레딧 한도를 설정할 수 있습니다. 세션 생성 시와 재개 시 모두 설정할 수 있습니다.

## 한도 설정

`SessionLimitsConfig`의 `maxAiCredits`에 한도를 전달합니다. 사용량은 각 모델 호출이 완료된 후에 확인되므로, 하나의 응답이 설정값을 초과할 수 있습니다. 한도를 초과하면 런타임은 다음 모델 호출을 차단합니다.

```php theme={null}
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ResumeSessionConfig;
use Revolution\Copilot\Types\Rpc\SessionLimitsConfig;
use Revolution\Copilot\Types\SessionConfig;

Copilot::start(function (CopilotSession $session) {
    $session->sendAndWait(prompt: 'Tell me something about Laravel.');
}, config: new SessionConfig(
    sessionLimits: new SessionLimitsConfig(maxAiCredits: 30.0),
));

Copilot::client()->resumeSession(
    'existing-session-id',
    new ResumeSessionConfig(
        sessionLimits: new SessionLimitsConfig(maxAiCredits: 30.0),
    ),
);
```

`SessionConfig`와 `ResumeSessionConfig` 모두 `sessionLimits`를 `SessionLimitsConfig` 인스턴스 또는 배열로 받습니다.

## 한도 이벤트

세션 이벤트를 수신하여 한도 변경에 대응하고, 한도에 도달했을 때 사용자에게 확인을 요청할 수 있습니다.

| 이벤트 | 발생 시점 | 주요 데이터 |
| - | - | - |
| `session.session_limits_changed` (`SessionEventType::SESSION_SESSION_LIMITS_CHANGED`) | 유효한 세션 한도가 변경되었을 때. `sessionLimits`가 `null`이면 한도가 적용되지 않습니다. | `sessionLimits.maxAiCredits` (선택) |
| `session.usage_checkpoint` (`SessionEventType::SESSION_USAGE_CHECKPOINT`) | 런타임이 재개 또는 집계를 위해 누적 사용량을 기록할 때. | `totalNanoAiu`, `totalPremiumRequests` (선택) |
| `session_limits_exhausted.requested` (`SessionEventType::SESSION_LIMITS_EXHAUSTED_REQUESTED`) | 한도에 도달하여 세션을 계속하기 전에 사용자의 판단이 필요할 때. | `requestId`, `maxAiCredits`, `usedAiCredits` |
| `session_limits_exhausted.completed` (`SessionEventType::SESSION_LIMITS_EXHAUSTED_COMPLETED`) | 한도 소진 프롬프트가 해결되었을 때. | `requestId`, `response.action`, `response.additionalAiCredits` (선택), `response.maxAiCredits` (선택) |

예를 들어 `SESSION_LIMITS_EXHAUSTED_REQUESTED`를 수신하면 이벤트 데이터를 사용해 확인 UI를 표시합니다.

```php theme={null}
use Revolution\Copilot\Enums\SessionEventType;
use Revolution\Copilot\Types\SessionEvent;

$session->on(function (SessionEvent $event): void {
    if ($event->is(SessionEventType::SESSION_LIMITS_EXHAUSTED_REQUESTED)) {
        $requestId = $event->data['requestId'];
        $maxAiCredits = $event->data['maxAiCredits'];
        $usedAiCredits = $event->data['usedAiCredits'];

        // $requestId를 사용해 확인 UI 표시
    }
});
```

## 한도 소진에 응답하기

`handlePendingSessionLimitsExhausted()`로 사용자의 선택을 런타임에 반환합니다. `action`에는 `SessionLimitsExhaustedResponseAction`의 케이스를 지정합니다.

```php theme={null}
use Revolution\Copilot\Enums\SessionLimitsExhaustedResponseAction;
use Revolution\Copilot\Types\Rpc\UIHandlePendingSessionLimitsExhaustedRequest;
use Revolution\Copilot\Types\Rpc\UISessionLimitsExhaustedResponse;

$session->rpc()->ui()->handlePendingSessionLimitsExhausted(
    new UIHandlePendingSessionLimitsExhaustedRequest(
        requestId: $requestId,
        response: new UISessionLimitsExhaustedResponse(
            action: SessionLimitsExhaustedResponseAction::Add,
            additionalAiCredits: 10.0,
        ),
    ),
);
```

사용 가능한 액션은 다음과 같습니다.

* `Add`: 현재 한도에 지정한 AI 크레딧을 추가합니다. `additionalAiCredits`를 지정합니다.
* `Set`: 한도를 새로운 절대값으로 변경합니다. `maxAiCredits`를 지정합니다.
* `Unset`: 세션 한도를 해제합니다.
* `Cancel`: 한도를 변경하지 않고 차단된 모델 요청을 취소합니다.

> [!WARNING]
>
> `session_limits_exhausted.requested`와 `session_limits_exhausted.completed`를 사용하는 한도 소진 프롬프트 흐름 및 관련 응답 API는 실험적 기능입니다. 향후 변경되거나 삭제될 수 있습니다.


## Related topics

- [Laravel Cloud — Laravel 전용 PaaS의 전모](https://kawax.biz/ko/blog/laravel-cloud.md)
- [세션](https://kawax.biz/ko/session.md)
- [Laravel AI SDK용 Amazon Bedrock 드라이버](https://kawax.biz/ko/packages/laravel-amazon-bedrock.md)
- [세션 재개](https://kawax.biz/ko/packages/laravel-copilot-sdk/resume.md)
- [세션 훅](https://kawax.biz/ko/packages/laravel-copilot-sdk/hooks.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.