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

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