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

# Steering e queueing

> Descrive la differenza tra steering (immediate) e queueing (enqueue) di Laravel Copilot SDK e come sceglierli in modo pratico in Laravel.

## Steering e queueing

<Info>
  Nel flusso di una tipica applicazione Laravel raramente serve usare lo steering direttamente. Il pattern di esecuzione sincrono di Laravel non ne beneficia molto, quindi in genere è più adatta la gestione con il queueing predefinito.
</Info>

Per inviare messaggi mentre l'agente sta elaborando, esistono due pattern: **steering** e **queueing**.

## Panoramica

`send()` / `sendAndWait()` / `sendAndStream()` / `Copilot::run()` accettano tutti un parametro `$mode`.

| Modalità                 | Comportamento                                                                    |
| ------------------------ | -------------------------------------------------------------------------------- |
| `"enqueue"` (default)    | Il messaggio viene messo in coda dopo il completamento del turn corrente         |
| `"immediate"` (steering) | Viene iniettato immediatamente interrompendo il turn attualmente in elaborazione |

## Steering (`"immediate"`)

Inietta un messaggio direttamente nel turn che l'agente sta elaborando. L'agente riceve il messaggio in tempo reale e adatta la sua risposta. Da usare quando vuoi correggere la direzione senza interrompere il lavoro in corso.

```php theme={null}
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Contracts\CopilotSession;

Copilot::start(function (CopilotSession $session) {
    // Avvia un task lungo
    $messageId = $session->send(prompt: 'Refactor the authentication module to use sessions');

    // Correggi la direzione mentre l'agente elabora
    $session->send(
        prompt: 'Actually, use JWT tokens instead of sessions',
        mode: 'immediate',
    );

    // Attendi finché non torna idle
    $response = $session->sendAndWait(prompt: 'Summarize what you did');
});
```

<Warning>
  Lo steering è best-effort. Se l'agente ha già committato una chiamata a strumento, si applica dopo il completamento di tale chiamata ma viene elaborato nello stesso turn. Se il messaggio di steering arriva dopo il completamento del turn, viene spostato automaticamente in coda.
</Warning>

## Queueing (`"enqueue"`)

Aggiunge il messaggio alla coda e lo elabora nell'ordine dopo il completamento del turn corrente. Ogni messaggio in coda viene eseguito come turn indipendente. È il comportamento predefinito se ometti `$mode`.

```php theme={null}
Copilot::start(function (CopilotSession $session) {
    // Avvia il primo task
    $session->send(prompt: 'Set up the project structure');

    // Mentre l'agente elabora, aggiungi task successivi in coda
    $session->send(prompt: 'Add unit tests for the auth module', mode: 'enqueue');
    $session->send(prompt: 'Update the README with setup instructions', mode: 'enqueue');

    // Attendi finché la coda non si svuota
});
```

## Considerazioni pratiche in Laravel

In Laravel prevale un pattern sincrono che usa `Copilot::run()` o `sendAndWait()`. Poiché questi inviano il messaggio e attendono lo stato idle, **non c'è occasione di interrompere l'agente mentre elabora e `$mode` non ha praticamente significato**.

```php theme={null}
// Poiché Copilot::run() richiama internamente sendAndWait(),
// specificare mode non ha senso

$response = Copilot::run(prompt: 'Tell me something about Laravel.');

// Anche in sessione, se ci si limita a chiamare in sequenza sendAndWait() non serve
Copilot::start(function (CopilotSession $session) {
    $r1 = $session->sendAndWait(prompt: 'First task');
    $r2 = $session->sendAndWait(prompt: 'Second task');
});
```

Lo steering (`"immediate"`) è utile quando invii messaggi in modo asincrono con `send()` e, in parallelo, un altro messaggio interviene nel turn in corso. Nel flusso sincrono di Laravel è difficile creare questa opportunità, quindi **in generale è più appropriato non specificare `$mode` e lasciare il default**.

## Quale usare

| Situazione                                     | Pattern                          |
| ---------------------------------------------- | -------------------------------- |
| L'agente sta andando nella direzione sbagliata | Steering (`"immediate"`)         |
| Hai pensato a cosa fare dopo                   | Queueing (`"enqueue"`)           |
| Vuoi eseguire più task in sequenza             | Queueing (`"enqueue"`)           |
| App Laravel standard                           | Default (`$mode` non necessario) |

## Best practice

* **Il default è queueing** — omettere `$mode` (o specificare `"enqueue"`) è adatto nella maggior parte dei casi. Comportamento prevedibile.
* **Lo steering è per correzioni** — usa `"immediate"` solo quando l'agente sta chiaramente sbagliando.
* **Messaggi di steering concisi** — mantieni messaggi brevi comprensibili nel contesto attuale. Messaggi lunghi e complessi generano confusione.
* **Evita steering consecutivi** — inviarne molti in poco tempo può ridurre la qualità del turn. Se serve un cambio drastico di direzione, può essere più appropriato interrompere il turn e ricominciare.

## Riferimenti

* [Uso di base](/it/packages/laravel-copilot-sdk/bare-usage)
* [Streaming](/it/packages/laravel-copilot-sdk/streaming)
* [send-on](/it/packages/laravel-copilot-sdk/send-on)

<Info>
  Per le informazioni più recenti fai riferimento al [repository GitHub](https://github.com/invokable/laravel-copilot-sdk).
</Info>