Steering y queueing

En el flujo habitual de una aplicación Laravel apenas se usa steering directamente. En los patrones de ejecución síncrona de Laravel es difícil aprovecharlo, y lo normal es operar con el queueing por defecto.

Hay dos patrones para enviar mensajes mientras el agente está procesando: steering y queueing.

Resumen

Todos los métodos send() / sendAndWait() / sendAndStream() / Copilot::run() aceptan el parámetro $mode.

Modo	Comportamiento
`"enqueue"` (por defecto)	Se procesa como cola después de completar el turn actual
`"immediate"` (steering)	Se inyecta inmediatamente interrumpiendo el turn en curso

Steering (`"immediate"`)

Inyecta el mensaje directamente en el turn que el agente está procesando. El agente lo recibe en tiempo real y ajusta la respuesta. Se usa cuando quieres cambiar de dirección sin interrumpir el trabajo en curso.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Contracts\CopilotSession;

Copilot::start(function (CopilotSession $session) {
    // Inicia una tarea larga
    $messageId = $session->send(prompt: 'Refactor the authentication module to use sessions');

    // Corrige la dirección mientras el agente está procesando
    $session->send(
        prompt: 'Actually, use JWT tokens instead of sessions',
        mode: 'immediate',
    );

    // Espera hasta que llegue al estado idle
    $response = $session->sendAndWait(prompt: 'Summarize what you did');
});

El steering es best-effort. Si el agente ya ha comprometido una tool call, se aplica tras completar dicha tool call, pero dentro del mismo turn. Si el mensaje de steering llega después de terminar el turn, se mueve automáticamente a la cola.

Queueing (`"enqueue"`)

Añade el mensaje a la cola y lo procesa en orden una vez completado el turn actual. Cada mensaje encolado se ejecuta como un turn independiente. Es el comportamiento por defecto si omites $mode.

Copilot::start(function (CopilotSession $session) {
    // Inicia la primera tarea
    $session->send(prompt: 'Set up the project structure');

    // Encola tareas siguientes mientras el agente está procesando
    $session->send(prompt: 'Add unit tests for the auth module', mode: 'enqueue');
    $session->send(prompt: 'Update the README with setup instructions', mode: 'enqueue');

    // Espera hasta que la cola quede vacía
});

Enfoque práctico en Laravel

En Laravel es habitual usar patrones síncronos con Copilot::run() o sendAndWait(). Como envían el mensaje y esperan hasta el estado idle, no hay oportunidad de interrumpir al agente mientras procesa, así que $mode es prácticamente irrelevante.

// Como Copilot::run() invoca internamente sendAndWait(),
// no tiene sentido indicar mode
$response = Copilot::run(prompt: 'Tell me something about Laravel.');

// Dentro de una sesión, si solo llamas a sendAndWait() en orden, tampoco lo necesitas
Copilot::start(function (CopilotSession $session) {
    $r1 = $session->sendAndWait(prompt: 'First task');
    $r2 = $session->sendAndWait(prompt: 'Second task');
});

El steering ("immediate") es útil cuando envías mensajes de forma asíncrona con send() y, en paralelo, puedes intervenir sobre el turn en curso con otro mensaje. En el flujo síncrono habitual de Laravel es difícil crear esa oportunidad, así que en general lo adecuado es no indicar $mode y dejar el valor por defecto.

¿Cuál usar?

Situación	Patrón
El agente va en la dirección equivocada	Steering (`"immediate"`)
Se te ocurre lo siguiente que hay que hacer	Queueing (`"enqueue"`)
Ejecutar varias tareas en orden	Queueing (`"enqueue"`)
Aplicación Laravel normal	Por defecto (`$mode` no hace falta)

Buenas prácticas

El valor por defecto es queueing: en la mayoría de casos, omitir $mode (o indicar "enqueue") es lo adecuado. Ofrece un comportamiento predecible.
Usa steering para correcciones: reserva "immediate" para cuando el agente esté haciendo claramente algo mal.
Mensajes de steering breves: mensajes cortos y comprensibles en el contexto actual. Los mensajes de steering largos y complejos generan más confusión.
Evita el steering encadenado: enviar varios steerings en poco tiempo puede degradar la calidad del turn. Si se requiere un cambio grande de dirección, a veces es mejor interrumpir el turn y empezar de nuevo.

Referencias

Consulta la información más reciente en el repositorio de GitHub.