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

# Limiti di crediti AI della sessione

> Imposta un limite di crediti AI sulle sessioni Copilot con sessionLimits e gestisci gli eventi relativi al limite e le richieste di limite esaurito.

Usa `sessionLimits` per impostare un limite flessibile (soft limit) di crediti AI per la finestra di contabilizzazione corrente di una sessione Copilot. Puoi impostarlo sia alla creazione sia alla ripresa di una sessione.

## Impostare un limite

Passa il limite a `maxAiCredits` di `SessionLimitsConfig`. L'utilizzo viene verificato al termine di ogni chiamata al modello, quindi una singola risposta può superare il valore configurato. Una volta superato il limite, il runtime blocca la chiamata al modello successiva.

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

Sia `SessionConfig` sia `ResumeSessionConfig` accettano `sessionLimits` come istanza di `SessionLimitsConfig` oppure come array.

## Eventi del limite

Ascolta gli eventi della sessione per reagire alle modifiche del limite e per chiedere conferma all'utente quando il limite viene raggiunto.

| Evento | Quando viene emesso | Dati principali |
| - | - | - |
| `session.session_limits_changed` (`SessionEventType::SESSION_SESSION_LIMITS_CHANGED`) | I limiti effettivi della sessione cambiano. Se `sessionLimits` è `null`, non si applica alcun limite. | `sessionLimits.maxAiCredits` (opzionale) |
| `session.usage_checkpoint` (`SessionEventType::SESSION_USAGE_CHECKPOINT`) | Il runtime registra l'utilizzo aggregato per la ripresa o la contabilizzazione. | `totalNanoAiu`, `totalPremiumRequests` (opzionale) |
| `session_limits_exhausted.requested` (`SessionEventType::SESSION_LIMITS_EXHAUSTED_REQUESTED`) | Il limite è stato raggiunto e l'utente deve decidere prima che la sessione prosegua. | `requestId`, `maxAiCredits`, `usedAiCredits` |
| `session_limits_exhausted.completed` (`SessionEventType::SESSION_LIMITS_EXHAUSTED_COMPLETED`) | La richiesta di limite esaurito è stata risolta. | `requestId`, `response.action`, `response.additionalAiCredits` (opzionale), `response.maxAiCredits` (opzionale) |

Ad esempio, quando ricevi `SESSION_LIMITS_EXHAUSTED_REQUESTED`, usa i dati dell'evento per mostrare un'interfaccia di conferma.

```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'];

        // Mostra un'interfaccia di conferma usando $requestId
    }
});
```

## Rispondere a un limite esaurito

Invia la scelta dell'utente al runtime con `handlePendingSessionLimitsExhausted()`. Imposta `action` su un caso di `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,
        ),
    ),
);
```

Le azioni disponibili sono:

* `Add`: aggiunge i crediti AI indicati al limite corrente. Imposta `additionalAiCredits`.
* `Set`: cambia il limite con un nuovo valore assoluto. Imposta `maxAiCredits`.
* `Unset`: rimuove il limite della sessione.
* `Cancel`: annulla la richiesta al modello bloccata senza modificare il limite.

> [!WARNING]
>
> Il flusso di richiesta di limite esaurito che utilizza `session_limits_exhausted.requested` e `session_limits_exhausted.completed`, e la relativa API di risposta, sono sperimentali. Potrebbero cambiare o essere rimossi in futuro.


## Related topics

- [Ripresa della sessione](https://kawax.biz/it/packages/laravel-copilot-sdk/resume.md)
- [Hook di sessione](https://kawax.biz/it/packages/laravel-copilot-sdk/hooks.md)
- [Eventi del ciclo di vita della sessione](https://kawax.biz/it/packages/laravel-copilot-sdk/session-lifecycle-event.md)
- [Contesto e filtraggio della sessione](https://kawax.biz/it/packages/laravel-copilot-sdk/session-context.md)
- [laravel/agent-skills — la raccolta ufficiale di skill per agenti AI di Laravel](https://kawax.biz/it/blog/agent-skills-introduction.md)


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