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

# Session 的 AI Credits 上限

> 使用 sessionLimits 為 Copilot Session 設定 AI Credits 上限,並處理與上限相關的事件及上限用盡時的確認提示。

使用 `sessionLimits` 可為 Copilot Session 目前的計費週期設定 AI Credits 的軟性上限。建立 Session 與恢復 Session 時皆可設定。

## 設定上限

將上限值傳給 `SessionLimitsConfig` 的 `maxAiCredits`。用量會在每次模型呼叫完成後檢查,因此單一回應可能會超過設定值。超過上限後,runtime 會阻擋下一次的模型呼叫。

```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.session_limits_changed` (`SessionEventType::SESSION_SESSION_LIMITS_CHANGED`) | 實際生效的 Session 上限變更時。若 `sessionLimits` 為 `null`,表示不套用上限。 | `sessionLimits.maxAiCredits`(選填) |
| `session.usage_checkpoint` (`SessionEventType::SESSION_USAGE_CHECKPOINT`) | runtime 為了恢復或計費而記錄累計用量時。 | `totalNanoAiu`、`totalPremiumRequests`(選填) |
| `session_limits_exhausted.requested` (`SessionEventType::SESSION_LIMITS_EXHAUSTED_REQUESTED`) | 達到上限,需由使用者決定後 Session 才能繼續時。 | `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()` 將使用者的選擇回傳給 runtime。`action` 請指定 `SessionLimitsExhaustedResponseAction` 的 case。

```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,
        ),
    ),
);
```

可用的 action 如下:

* `Add`:在目前的上限上追加指定的 AI Credits。請指定 `additionalAiCredits`。
* `Set`:將上限變更為新的絕對值。請指定 `maxAiCredits`。
* `Unset`:移除 Session 上限。
* `Cancel`:不變更上限,取消被阻擋的模型請求。

> [!WARNING]
>
> 使用 `session_limits_exhausted.requested` 與 `session_limits_exhausted.completed` 的上限用盡確認流程及相關的回應 API 為實驗性功能。未來可能會變更或移除。


## Related topics

- [Laravel AI SDK 的 Agent 中介層](https://kawax.biz/zh-TW/advanced/ai-sdk-agent-middleware.md)
- [Laravel AI SDK](https://kawax.biz/zh-TW/ai-sdk.md)
- [Laravel AI SDK 的 Amazon Bedrock 驅動](https://kawax.biz/zh-TW/packages/laravel-amazon-bedrock.md)
- [SessionEvent](https://kawax.biz/zh-TW/packages/laravel-copilot-sdk/session-event.md)
- [Session](https://kawax.biz/zh-TW/session.md)


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