> ## 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 credit limits

> Set an AI credit limit on Copilot sessions with sessionLimits, and handle limit-related events and exhausted-limit prompts.

Use `sessionLimits` to set a soft AI credit limit for the current accounting window of a Copilot session. You can set it both when creating and when resuming a session.

## Set a limit

Pass the limit to `maxAiCredits` on `SessionLimitsConfig`. Usage is checked after each model call completes, so a single response can exceed the configured value. Once the limit is exceeded, the runtime blocks the next model call.

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

Both `SessionConfig` and `ResumeSessionConfig` accept `sessionLimits` as either a `SessionLimitsConfig` instance or an array.

## Limit events

Listen to session events to react to limit changes and to prompt the user when the limit is reached.

| Event | When it fires | Main data |
| - | - | - |
| `session.session_limits_changed` (`SessionEventType::SESSION_SESSION_LIMITS_CHANGED`) | The effective session limits change. If `sessionLimits` is `null`, no limit applies. | `sessionLimits.maxAiCredits` (optional) |
| `session.usage_checkpoint` (`SessionEventType::SESSION_USAGE_CHECKPOINT`) | The runtime records aggregate usage for resuming or accounting. | `totalNanoAiu`, `totalPremiumRequests` (optional) |
| `session_limits_exhausted.requested` (`SessionEventType::SESSION_LIMITS_EXHAUSTED_REQUESTED`) | The limit is reached and the user must decide before the session continues. | `requestId`, `maxAiCredits`, `usedAiCredits` |
| `session_limits_exhausted.completed` (`SessionEventType::SESSION_LIMITS_EXHAUSTED_COMPLETED`) | The exhausted-limit prompt is resolved. | `requestId`, `response.action`, `response.additionalAiCredits` (optional), `response.maxAiCredits` (optional) |

For example, when you receive `SESSION_LIMITS_EXHAUSTED_REQUESTED`, use the event data to show a confirmation 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'];

        // Show a confirmation UI using $requestId
    }
});
```

## Respond to an exhausted limit

Send the user's choice back to the runtime with `handlePendingSessionLimitsExhausted()`. Set `action` to a `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,
        ),
    ),
);
```

The available actions are:

* `Add`: Adds the given AI credits to the current limit. Set `additionalAiCredits`.
* `Set`: Changes the limit to a new absolute value. Set `maxAiCredits`.
* `Unset`: Removes the session limit.
* `Cancel`: Cancels the blocked model request without changing the limit.

> [!WARNING]
>
> The exhausted-limit prompt flow using `session_limits_exhausted.requested` and `session_limits_exhausted.completed`, and the related response API, are experimental. They may change or be removed in the future.


## Related topics

- [Amazon Bedrock driver for Laravel AI SDK](https://kawax.biz/en/packages/laravel-amazon-bedrock.md)
- [Laravel AI SDK](https://kawax.biz/en/ai-sdk.md)
- [Laravel Agent Detector — AI agent detection package](https://kawax.biz/en/blog/agent-detector-introduction.md)
- [SessionEvent](https://kawax.biz/en/packages/laravel-copilot-sdk/session-event.md)
- [Agent Middleware in Laravel AI SDK](https://kawax.biz/en/advanced/ai-sdk-agent-middleware.md)


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