Orientation et mise en file d’attente des messages dans le SDK Copilot

Deux modèles d’interaction permettent aux utilisateurs d’envoyer des messages pendant que l’agent fonctionne déjà : le pilotage redirige l’agent en cours de tâche, et la mise en file d’attente défère les messages pour un traitement séquentiel (premier entré, premier sorti (FIFO)) une fois le tour actuel terminé.

Lorsqu’une session traite activement un tour, les messages entrants peuvent être remis dans l’un des deux modes via le mode champ sur MessageOptions:

Mode	Comportement	Cas d’utilisation
"immediate" (direction)	Injecté dans le tour actuel du LLM	« En fait, ne créez pas ce fichier , utilisez une approche différente »
"enqueue" (mise en file d’attente)	Mis en file d’attente et traité une fois le tour actuel terminé	« Après cela, corrigez également les tests »

Pour obtenir un diagramme séquentiel du flux de direction et de mise en file d’attente, consultez le github/copilot-sdk référentiel.

Direction (mode immédiat)

Le pilotage envoie un message qui est injecté directement dans le tour actuel de l’agent. Il est utile pour corriger la trajectoire sans interrompre l'échange ; l'agent voit le message en temps réel et ajuste sa réponse en conséquence.

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
await client.start();

const session = await client.createSession({
    model: "gpt-4.1",
    onPermissionRequest: async () => ({ kind: "approved" }),
});

// Start a long-running task
const msgId = await session.send({
    prompt: "Refactor the authentication module to use sessions",
});

// While the agent is working, steer it
await session.send({
    prompt: "Actually, use JWT tokens instead of sessions",
    mode: "immediate",
});

Pour obtenir des exemples dans Python, Go et .NET, consultez le github/copilot-sdk référentiel. Pour Java, consultez le github/copilot-sdk-java référentiel.

Fonctionnement interne de la direction

1. Le message est ajouté à la file d’attente du ImmediatePromptProcessor runtime.
2. Avant la requête LLM suivante au sein du tour actuel, le processeur injecte le message dans la conversation.
3. L’agent voit le message de direction comme un nouveau message utilisateur et ajuste sa réponse.
4. Si le tour se termine avant le traitement du message de direction, il est automatiquement déplacé vers la file d’attente normale pour le tour suivant.

Mise en file d’attente (mode d’enfilement)

La mise en file d’attente stocke les messages pour qu’ils soient traités séquentiellement après la fin du tour en cours. Chaque message mis en file d’attente démarre son propre tour complet. Il s’agit du mode par défaut : si vous omettez mode, le Kit de développement logiciel (SDK) utilise "enqueue".

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
await client.start();

const session = await client.createSession({
    model: "gpt-4.1",
    onPermissionRequest: async () => ({ kind: "approved" }),
});

// Send an initial task
await session.send({ prompt: "Set up the project structure" });

// Queue follow-up tasks while the agent is busy
await session.send({
    prompt: "Add unit tests for the auth module",
    mode: "enqueue",
});

await session.send({
    prompt: "Update the README with setup instructions",
    mode: "enqueue",
});

// Messages are processed in FIFO order after each turn completes

Pour obtenir des exemples dans Python, Go et .NET, consultez le github/copilot-sdk référentiel. Pour Java, consultez le github/copilot-sdk-java référentiel.

Fonctionnement interne de la mise en file d’attente

1. Le message est ajouté à la session itemQueue en tant que QueuedItem.
2. Une fois le tour actuel terminé et que la session devient inactive, processQueuedItems() s’exécute.
3. Les éléments sont mis en file d’attente dans l’ordre FIFO : chaque message déclenche un tour agentique complet.
4. Si un message de direction était en attente lorsque le tour s’est terminé, il est déplacé vers l’avant de la file d’attente.
5. Le traitement se poursuit jusqu’à ce que la file d’attente soit vide, puis que la session émet un événement inactif.

Combinaison du pilotage et de la file

Vous pouvez utiliser les deux modèles ensemble dans une seule session. Le pilotage affecte le tour en cours tandis que les messages en file d’attente attendent leur propre tour :

const session = await client.createSession({
    model: "gpt-4.1",
    onPermissionRequest: async () => ({ kind: "approved" }),
});

// Start a task
await session.send({ prompt: "Refactor the database layer" });

// Steer the current work
await session.send({
    prompt: "Make sure to keep backwards compatibility with the v1 API",
    mode: "immediate",
});

// Queue a follow-up for after this turn
await session.send({
    prompt: "Now add migration scripts for the schema changes",
    mode: "enqueue",
});

Pour obtenir un exemple dans Python, consultez le github/copilot-sdk référentiel. Pour Java, consultez le github/copilot-sdk-java référentiel.

Choix entre la direction et la file d’attente

Scénario	Modèle	Pourquoi
L’agent prend le mauvais chemin	Direction	Redirige le tour actuel sans perdre de progression
Vous avez pensé à quelque chose que l’agent devrait également faire	Mise en file d’attente	Ne perturbe pas le travail en cours ; s’exécute ensuite
L’agent est sur le point de faire une erreur	Direction	Intervient avant que l’erreur ne soit commise
Vous souhaitez chaîner plusieurs tâches	Mise en file d’attente	L’ordre FIFO garantit l’exécution prévisible
Vous souhaitez ajouter un contexte à la tâche actuelle	Direction	Agent l’intègre dans son raisonnement actuel
Vous souhaitez traiter des demandes non liées en lot	Mise en file d’attente	Chacun bénéficie de son propre tour complet avec un contexte vierge

Création d’une interface utilisateur avec pilotage et mise en file d’attente

Voici un modèle permettant de créer une interface utilisateur interactive qui prend en charge les deux modes :

import { CopilotClient, CopilotSession } from "@github/copilot-sdk";

interface PendingMessage {
    prompt: string;
    mode: "immediate" | "enqueue";
    sentAt: Date;
}

class InteractiveChat {
    private session: CopilotSession;
    private isProcessing = false;
    private pendingMessages: PendingMessage[] = [];

    constructor(session: CopilotSession) {
        this.session = session;

        session.on((event) => {
            if (event.type === "session.idle") {
                this.isProcessing = false;
                this.onIdle();
            }
            if (event.type === "assistant.message") {
                this.renderMessage(event);
            }
        });
    }

    async sendMessage(prompt: string): Promise<void> {
        if (!this.isProcessing) {
            this.isProcessing = true;
            await this.session.send({ prompt });
            return;
        }

        // Session is busy — let the user choose how to deliver
        // Your UI would present this choice (e.g., buttons, keyboard shortcuts)
    }

    async steer(prompt: string): Promise<void> {
        this.pendingMessages.push({
            prompt,
            mode: "immediate",
            sentAt: new Date(),
        });
        await this.session.send({ prompt, mode: "immediate" });
    }

    async enqueue(prompt: string): Promise<void> {
        this.pendingMessages.push({
            prompt,
            mode: "enqueue",
            sentAt: new Date(),
        });
        await this.session.send({ prompt, mode: "enqueue" });
    }

    private onIdle(): void {
        this.pendingMessages = [];
        // Update UI to show session is ready for new input
    }

    private renderMessage(event: unknown): void {
        // Render assistant message in your UI
    }
}

Référence d’API

Vous pouvez utiliser l'API de session SDK Copilot pour diriger et mettre en file d'attente les sessions.

Options de message

Language	Champ	Type	Par défaut	Description
Node.JS	mode	"enqueue" | "immediate"	"enqueue"	Mode de remise des messages
Python	mode	Literal["enqueue", "immediate"]	"enqueue"	Mode de remise des messages
Allez	Mode	string	"enqueue"	Mode de remise des messages
.NET	Mode	string?	"enqueue"	Mode de remise des messages

Modes de livraison

Mode	Résultat	Pendant le tour actif	Pendant l’inactivité
"enqueue"	File d’attente pour le prochain tour	Attend dans la file d’attente FIFO	Démarre immédiatement un nouveau tour
"immediate"	Injecter dans le tour en cours	Injecté avant l’appel LLM suivant	Démarre immédiatement un nouveau tour

Bonnes pratiques

• Mise en file d’attente par défaut : utilisez "enqueue" (ou omettez mode) pour la plupart des messages. Il est prévisible et ne risque pas de perturber les travaux en cours.
• Réservez la direction pour les corrections : utilisez "immediate" quand l’agent fait activement la mauvaise chose et que vous devez le rediriger avant d’aller plus loin.
• Gardez les messages clairs et concis : l’agent doit rapidement comprendre la correction du cap. Les messages de direction longs et complexes peuvent confondre le contexte actuel.
• Évitez de surdiriger : plusieurs messages de direction rapides peuvent dégrader la qualité du virage. Si vous devez changer de direction de manière significative, envisagez d’arrêter le tour et de commencer frais.
• Afficher l’état de la file d’attente dans votre interface utilisateur : affichez le nombre de messages mis en file d’attente afin que les utilisateurs sachent ce qui est en attente. Écoutez les événements d’inactivité pour effacer l’affichage.

•           **Gérer le passage du pilotage à la file d’attente** — Si un message de pilotage arrive après la fin du tour, il est automatiquement déplacé dans la file d’attente. Concevez votre interface utilisateur pour refléter cette transition.