Nachrichtensteuerung und Warteschlangenverwaltung im Copilot-SDK

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

Mit zwei Interaktionsmustern können Benutzer Nachrichten senden, während der Agent bereits arbeitet: Die Steuerung leitet den Agent während des Zuges um, und das Warteschlangenpuffern von Nachrichten für die sequenzielle Verarbeitung (First-in-first-out (FIFO)) nach Abschluss des aktuellen Zyklus.

Wenn eine Sitzung aktiv eine Interaktion verarbeitet, können eingehende Nachrichten auf eine von zwei Arten über das mode-Feld zugestellt werden:MessageOptions

Modus	Verhalten	Anwendungsfall

          `"immediate"` (Lenkung) | In die **aktuelle** LLM-Umwandlung eingefügt | "Erstellen Sie diese Datei tatsächlich nicht – verwenden Sie einen anderen Ansatz" |

| "enqueue" (Warteschlangen) | In die Warteschlange eingereiht und verarbeitet nach Abschluss des aktuellen Durchgangs | "Danach beheben Sie auch die Tests" |

Ein Sequenzdiagramm des Steuerungs- und Warteschlangenflusses 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.

Funktionsweise der Steuerung intern

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

Warteschlangen (Enqueue-Modus)

Das Warteschlangenpuffer speichert Nachrichten, die sequenziell verarbeitet werden, nachdem die aktuelle Bearbeitung abgeschlossen ist. 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.

Funktionsweise der Warteschlangen intern

1. Die Nachricht wird der Sitzung itemQueue als eine QueuedItemhinzugefügt.
2. Wenn der aktuelle Vorgang abgeschlossen ist und die Sitzung im Leerlauf ist, wird processQueuedItems() ausgeführt.
3. Elemente werden in FIFO-Reihenfolge aus der Warteschlange entfernt – jede Nachricht löst einen vollständigen agentengesteuerten Vorgang aus.
4. Wenn beim Ende der Wende eine Lenkungsmeldung aussteht, 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 Lenkung wirkt sich auf die aktuelle Drehung aus, während Nachrichten in der Warteschlange auf ihre eigenen Drehungen 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.

Auswahl zwischen Lenkung und Warteschlangen

Szenario	Schema	Warum?
Der Agent geht auf den falschen Pfad.	Lenkung	Leitet den aktuellen Turn um, ohne den Fortschritt zu verlieren.
Sie dachten an etwas, was der Agent auch tun sollte	Warteschlangenbildung	Stört 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	Agent integriert es in seine aktuelle Begründung
Sie möchten unabhängige Anforderungen zusammenfassen.	Warteschlangenbildung	Jeder bekommt seinen eigenen vollständigen Schritt mit klarem 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 Drehung einfügen	Vor dem nächsten LLM-Aufruf eingefügt	Startet sofort eine neue Drehung.

Bewährte Methoden

•         **Voreinstellung auf Warteschlange setzen** – Verwenden Sie `"enqueue"` für die meisten Nachrichten (oder `mode` auslassen). 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. Lauschen Sie auf Leerlaufereignisse, um die Anzeige zu löschen.
  

•         **Bearbeiten Sie den Fallback vom Steuerungsvorgang zur Warteschlange**– Wenn eine Steuerungsnachricht nach dem Abschluss des Steuerungsvorgangs eingeht, wird sie automatisch in die Warteschlange verschoben. Entwerfen Sie Ihre Benutzeroberfläche so, dass sie diesen Übergang widerspiegelt.