Nachrichtensteuerung und Warteschlangenverwaltung im Copilot-SDK

          Copilot SDK ist zurzeit in öffentliche Vorschau. Funktionalität und Verfügbarkeit können geändert werden.

Zwei Interaktionsmuster ermöglichen es Benutzern, Nachrichten zu senden, während der Agent bereits arbeitet: Steuerung leitet den Agent mitten in der Runde um, und Warteschlange puffert Nachrichten für die sequentielle Verarbeitung (first-in-first-out (FIFO)), nachdem die aktuelle Runde abgeschlossen ist.

Wenn eine Sitzung aktiv eine Runde verarbeitet, können eingehende Nachrichten in einem von zwei Modi über das Feld mode auf MessageOptions zugestellt werden:

Modus	Verhalten	Anwendungsfall

          `"immediate"` (Lenkung) | In den **aktuellen** LLM-Turn eingeschleust | "Erstellen Sie diese Datei tatsächlich nicht – verwenden Sie einen anderen Ansatz" |

| "enqueue" (Warteschlangen) | In Warteschlange gestellt und verarbeitet nach Beendigung der aktuellen Runde | „Danach korrigieren der Tests“ |

Ein Sequenzdiagramm des Flows zur Steuerung und Warteschlange finden Sie im github/copilot-sdk Repository.

Lenkung (Sofortiger Modus)

Die Lenkung sendet eine Nachricht, die direkt in den aktuellen Spielzug des Agenten eingespeist wird. Der Agent sieht die Nachricht in Echtzeit und passt seine Antwort entsprechend an – nützlich für die Kurskorrektur, ohne die Drehung abzubrechen.

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",
});

Beispiele in Python, Go und .NET finden Sie im github/copilot-sdk Repository. Java finden Sie im github/copilot-sdk-java Repository.

Funktionsweise der Steuerung intern

1. Die Nachricht wird der ImmediatePromptProcessor Warteschlange der Runtime hinzugefügt.
2. Vor der nächsten LLM-Anfrage innerhalb des aktuellen Turns fügt der Prozessor die Nachricht in die Kommunikation ein.
3. Der Agent sieht die Lenkungsnachricht als neue Benutzernachricht und passt seine Antwort an.
4. Wenn die Runde abgeschlossen ist, bevor die steuernde Nachricht verarbeitet wurde, wird sie automatisch in die reguläre Warteschlange für die nächste Runde verschoben.

Warteschlangen (Enqueue-Modus)

In der Warteschlange werden Nachrichten gepuffert, die nach Abschluss der aktuellen Runde der Reihe nach verarbeitet werden. Jede in die Warteschlange eingereihte Nachricht startet einen eigenen vollständigen Durchlauf. Dies ist der Standardmodus – wenn Sie weglassen mode, verwendet "enqueue"das SDK .

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

Beispiele in Python, Go und .NET finden Sie im github/copilot-sdk Repository. Java finden Sie im github/copilot-sdk-java Repository.

Wie die Warteschlange intern funktioniert

1. Die Nachricht wird dem itemQueue der Sitzung als QueuedItem hinzugefügt.
2. Wenn die aktuelle Runde abgeschlossen ist und die Sitzung inaktiv wird, wird processQueuedItems() ausgeführt.
3. Die Nachrichten werden in der FIFO-Reihenfolge abgearbeitet - jede Nachricht triggert eine vollständige Runde des Agenten.
4. Wenn bei Beendigung der Runde eine Steuerungsnachricht anstand, wird sie an den Anfang der Warteschlange verschoben.
5. Die Verarbeitung wird fortgesetzt, bis die Warteschlange leer ist, und die Sitzung gibt ein Leerlaufereignis aus.

Kombination von Steuerung und Warteschlangenverwaltung

Sie können beide Muster in einer einzigen Sitzung verwenden. Die Steuerung wirkt sich auf die aktuelle Runde aus, während die Nachrichten in der Warteschlange auf ihre eigene Runde warten:

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",
});

Ein Beispiel in Python finden Sie im github/copilot-sdk Repository. Java finden Sie im github/copilot-sdk-java Repository.

Auswahl zwischen Lenkung und Warteschlangen

Szenario	Schema	Warum?
Der Agent geht auf den falschen Pfad.	Lenkung	Leitet den aktuellen Vorgang um, ohne den Fortschritt zu verlieren
Sie dachten an etwas, was der Agent auch tun sollte	Warteschlangenbildung	Unterbricht die aktuelle Arbeit nicht; wird als nächstes ausgeführt
Agent ist dabei, einen Fehler zu machen	Lenkung	Greift ein, bevor der Fehler begangen wird
Sie möchten mehrere Vorgänge verketten	Warteschlangenbildung	FIFO-Sortierung gewährleistet vorhersehbare Ausführung
Sie möchten der aktuellen Aufgabe Kontext hinzufügen	Lenkung	Der Agent bezieht sie in sein aktuelles Reasoning ein
Sie möchten unverbundene Anfragen in Batches zusammenfassen	Warteschlangenbildung	Jede erhält ihre eigene vollständige Runde mit sauberem Kontext

Erstellen einer Benutzeroberfläche mit Steuerung und Warteschlangen

Hier ist ein Muster zum Erstellen einer interaktiven Benutzeroberfläche, die beide Modi unterstützt:

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
    }
}

API-Referenz

Sie können die Sitzungs-API Copilot SDK verwenden, um Sitzungen zu steuern und in die Warteschlange zu stellen.

Nachrichtenoptionen

Sprache	Feld	Typ	Vorgabe	Beschreibung
Node.js	mode	"enqueue" | "immediate"	"enqueue"	Nachrichtenübermittlungsmodus
Python	mode	Literal["enqueue", "immediate"]	"enqueue"	Nachrichtenübermittlungsmodus
Los geht's	Mode	string	"enqueue"	Nachrichtenübermittlungsmodus
.NET	Mode	string?	"enqueue"	Nachrichtenübermittlungsmodus

Liefermodi

Modus	Auswirkung	Während einer aktiven Drehung	Während des Leerlaufs
"enqueue"	Warteschlange für nächsten Schritt	Wartezeiten in der FIFO-Warteschlange	Startet sofort eine neue Drehung.
"immediate"	In die aktuelle Runde einfügen	Vor dem nächsten LLM-Aufruf eingefügt	Startet sofort eine neue Drehung.

Bewährte Methoden

•           **Standard für Warteschlangen**-Verwenden Sie `"enqueue"` (oder lassen Sie `mode` weg) für die meisten Nachrichten. Es ist vorhersagbar und riskiert keine Unterbrechung der laufenden Arbeit.
  

•         **Behalten Sie sich die Steuerung für Korrekturen vor** – Verwenden Sie `"immediate"`, wenn der Agent aktiv fehlerhaft handelt und Sie ihn korrigieren müssen, bevor es weitergeht.
  

•         **Halten Sie die Lenkungsnachrichten kurz –** Der Agent muss die Kurskorrektur schnell verstehen. Lange, komplexe Lenkungsmeldungen können den aktuellen Kontext verwirren.
  

•         **Nicht übersteuern** – Mehrere schnelle Lenkmeldungen können die Drehqualität beeinträchtigen. Wenn Sie die Richtung erheblich ändern müssen, sollten Sie die Drehung abbrechen und neu beginnen.
  

•         **Anzeigen des Warteschlangenstatus in der Benutzeroberfläche** – Zeigen Sie die Anzahl der in die Warteschlange eingereihten Nachrichten an, damit Benutzer wissen, was aussteht. Warten Sie auf Idle-Ereignisse, um die Anzeige zu löschen.
  

•           **Handhaben Sie den Fallback von Steuerung zu Warteschlange**-Wenn eine Nachricht zur Steuerung eintrifft, nachdem die Runde abgeschlossen ist, wird sie automatisch in die Warteschlange verschoben. Entwerfen Sie Ihre Benutzeroberfläche so, dass sie diesen Übergang widerspiegelt.