Steering et mise en file

Comprenez la différence entre steering (immediate) et queueing (enqueue) dans Laravel Copilot SDK, et sachez lequel utiliser en pratique dans Laravel.

​

Steering et mise en file

Dans un flux typique d’application Laravel, vous utiliserez rarement le steering directement. Le modèle synchrone de Laravel en tire peu de bénéfices ; la mise en file par défaut convient dans la plupart des cas.

Pour envoyer un message à un agent en cours de traitement, il existe deux modèles : steering et queueing (mise en file).

​

Vue d’ensemble

Tous les appels send() / sendAndWait() / sendAndStream() / Copilot::run() acceptent un paramètre $mode.

Mode	Comportement
"enqueue" (défaut)	Traité en file d’attente une fois le tour courant terminé
"immediate" (steering)	Injecté immédiatement dans le tour en cours d’exécution

​

Steering ("immediate")

Injecte le message directement dans le tour en cours de l’agent. Celui-ci reçoit le message en temps réel et ajuste sa réponse. À utiliser lorsque vous souhaitez rediriger sans interrompre le travail en cours.

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

Copilot::start(function (CopilotSession $session) {
    // Démarre une tâche longue
    $messageId = $session->send(prompt: 'Refactor the authentication module to use sessions');

    // Réoriente pendant que l'agent travaille
    $session->send(
        prompt: 'Actually, use JWT tokens instead of sessions',
        mode: 'immediate',
    );

    // Attend l'état inactif
    $response = $session->sendAndWait(prompt: 'Summarize what you did');
});

Le steering est en best-effort. Si l’agent s’est déjà engagé dans un appel d’outil, il sera appliqué après la fin de cet appel mais dans le même tour. Si le message de steering arrive après la fin du tour, il est automatiquement basculé dans la file.

​

Queueing ("enqueue")

Ajoute le message à la file, traité séquentiellement après la fin du tour courant. Chaque message en file s’exécute comme un tour indépendant. C’est le comportement par défaut si $mode est omis.

Copilot::start(function (CopilotSession $session) {
    // Démarre la première tâche
    $session->send(prompt: 'Set up the project structure');

    // Empile les tâches suivantes pendant que l'agent travaille
    $session->send(prompt: 'Add unit tests for the auth module', mode: 'enqueue');
    $session->send(prompt: 'Update the README with setup instructions', mode: 'enqueue');

    // Attend que la file se vide
});

​

Approche pratique dans Laravel

Dans Laravel, le style dominant est synchrone via Copilot::run() ou sendAndWait(). Ces méthodes envoient un message et attendent l’état inactif ; il n’y a donc pas d’occasion d’interrompre l’agent, et $mode n’a pas vraiment de sens.

// Copilot::run() appelle sendAndWait() en interne :
// spécifier mode n'a donc pas d'effet utile
$response = Copilot::run(prompt: 'Tell me something about Laravel.');

// Dans une session, si vous n'appelez que sendAndWait() successivement, c'est aussi inutile
Copilot::start(function (CopilotSession $session) {
    $r1 = $session->sendAndWait(prompt: 'First task');
    $r2 = $session->sendAndWait(prompt: 'Second task');
});

Le steering ("immediate") prend son sens lorsque vous envoyez send() de façon asynchrone et que vous pouvez intervenir en parallèle dans le tour courant depuis un autre message. Dans le flux synchrone de Laravel, il est difficile de créer une telle fenêtre : il est en général approprié de ne pas spécifier $mode et de conserver le défaut.

​

Lequel utiliser ?

Situation	Modèle
L’agent part dans la mauvaise direction	Steering ("immediate")
Vous avez une nouvelle tâche pour ensuite	Queueing ("enqueue")
Exécuter plusieurs tâches à la suite	Queueing ("enqueue")
Application Laravel classique	Défaut (pas de $mode)

​

Bonnes pratiques

• Par défaut, mise en file — omettre $mode (ou passer "enqueue") convient à la plupart des cas et donne un comportement prévisible.
• Steering pour corriger — n’utilisez "immediate" que quand l’agent fait manifestement fausse route.
• Messages de steering concis — courts et compréhensibles dans le contexte courant. Un steering long et complexe peut aggraver la confusion.
• Évitez le steering en rafale — plusieurs steerings rapprochés peuvent dégrader la qualité du tour. Si un changement important s’impose, il peut être préférable d’interrompre le tour et de recommencer.

​

Voir aussi

• Utilisation de base
• Streaming
• send / on

Pour les dernières informations, consultez le dépôt GitHub.