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

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.

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.

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');
});

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.

​

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.

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.

// 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
• Streaming
• send-on

Per le informazioni più recenti fai riferimento al repository GitHub.