Flottenmodus

Wann der Flottenmodus verwendet werden sollte

Der Flottenmodus ist nützlich, wenn die Arbeit vor der Ausführung dekompiliert werden kann und jede Einheit ausgeführt werden kann, ohne auf die anderen zu warten.

Geeignete Optionen sind:

Multi-Datei-Refactorings, bei denen jeder Worker für eine Datei, ein Paket oder ein Sprach-SDK zuständig ist.
Batchüberprüfungen, bei denen jeder Mitarbeiter eine separate Diff-, Modul- oder Warnungsgruppe überprüft.
Parallele Forschung in unabhängigen Repositorys, Diensten oder Featurebereichen.
Die Dokumentation wird aktualisiert, wo jeder Mitarbeiter eine Seite oder ein Thema besitzt.
Migrationsaufgaben, bei denen jeder Mitarbeiter ein eigenes Segment überprüfen und zurückmelden kann.

Vermeiden Sie den Flottenmodus für:

Sequenzielle Vorgänge, bei denen Schritt 2 die konkrete Ausgabe aus Schritt 1 benötigt.
Eng gekoppelte Bearbeitungen, bei denen Die Mitarbeiter für die gleichen Dateien kämpfen würden.
Kleine Aufgaben, die ein synchroner Sub-Agent oder der übergeordnete Agent schnell abschließen kann.
Aufgaben, die kontinuierliche gemeinsame Abstimmung statt klarer Zuständigkeit erfordern.

Der Flottenmodus funktioniert am besten, wenn die übergeordnete Sitzung klare Arbeitseinheiten erstellen kann, einen Besitzer pro Einheit zuweisen und definieren kann, was jeder Mitarbeiter zurückgeben muss.

Starten des Flottenmodus

Das SDK stellt den Flottenmodus über den Session-RPC-Namespace in mehreren Sprachen bereit. Die Bindung ist in der generierten RPC-Oberfläche experimentell; legen Sie sowohl das SDK als auch die Copilot-CLI-Laufzeitumgebung auf feste Versionen fest, wenn Ihre Anwendung davon abhängt.

Innerhalb einer Sitzung

Die Drahtmethode lautet session.fleet.start. Das optionale prompt wird mit den Anweisungen für die Flottenorchestrierung der Runtime kombiniert.

TypeScript

const result = await session.rpc.fleet.start({
    prompt: "Refactor each SDK package independently, then summarize the changes.",
});

if (result.started) {
    console.log("Fleet mode started");
}

Python

from copilot.generated.rpc import FleetStartRequest

result = await session.rpc.fleet.start(
    FleetStartRequest(
        prompt="Review each service independently, then summarize the risks."
    )
)

if result.started:
    print("Fleet mode started")

package main

import (
    "context"
    "fmt"

    copilot "github.com/github/copilot-sdk/go"
    "github.com/github/copilot-sdk/go/rpc"
)

func main() {
    ctx := context.Background()
    client := copilot.NewClient(nil)
    session, err := client.CreateSession(ctx, &copilot.SessionConfig{})
    if err != nil {
        return
    }

    prompt := "Update each package independently, then report validation results."
    result, err := session.RPC.Fleet.Start(ctx, &rpc.FleetStartRequest{
        Prompt: &prompt,
    })
    if err != nil {
        return
    }
    if result.Started {
        fmt.Println("Fleet mode started")
    }
}

prompt := "Update each package independently, then report validation results."
result, err := session.RPC.Fleet.Start(ctx, &rpc.FleetStartRequest{
    Prompt: &prompt,
})
if err != nil {
    return err
}
if result.Started {
    fmt.Println("Fleet mode started")
}

.NET

using GitHub.Copilot;

await using var client = new CopilotClient();
await using var session = await client.CreateSessionAsync(new SessionConfig());

var result = await session.Rpc.Fleet.StartAsync(
    "Audit each project independently, then summarize the findings.");

if (result.Started)
{
    Console.WriteLine("Fleet mode started");
}

var result = await session.Rpc.Fleet.StartAsync(
    "Audit each project independently, then summarize the findings.");

if (result.Started)
{
    Console.WriteLine("Fleet mode started");
}

Rust

use github_copilot_sdk::generated::api_types::FleetStartRequest;

let result = session
    .rpc()
    .fleet()
    .start(FleetStartRequest {
        prompt: Some("Research each crate independently, then summarize the plan.".into()),
    })
    .await?;

if result.started {
    println!("Fleet mode started");
}

Native typisierte Bindings für den Flottenmodus wurden in Node.js/TypeScript, Python, Go, .NET und Rust verifiziert. In diesem Branch wurde in java/src/main/java keine Java-Bindung gefunden, daher werden Java-Beispiele ausgelassen, bis diese Oberfläche verfügbar ist.

Vom Planmodus

Benutzeroberflächen im Planmodus können die Bereitstellung der Flotte starten, indem sie die autopilot_fleet Exit-Aktion zurückgeben. Die generierten Sitzungsereignistypen beschreiben sie wie:

type PlanModeExitAction =
  | "exit_only"
  | "interactive"
  | "autopilot"
  /** Exit plan mode and continue with parallel autonomous workers. */
  | "autopilot_fleet";

Verwenden Sie diese Methode, wenn ein Benutzer einen Plan genehmigt, der bereits unabhängige Arbeitsaufgaben enthält. Verwenden Sie autopilot für einen einzelnen autonomen Worker und interactive, wenn der Benutzer eingebunden bleiben soll.

Wie Sub-Agenten zusammenarbeiten

Der Flottenmodus beruht auf einem expliziten Koordinationsstatus statt auf implizitem gemeinsam genutztem Speicher. Der übergeordnete Agent dekompiliert die Arbeit in Todos, jeder Unter-Agent besitzt einen Todo- und der Orchestrator verteilt Mitarbeiter, deren Abhängigkeiten bereits abgeschlossen sind.

Das kanonische Schema lautet:

CREATE TABLE todos (
    id TEXT PRIMARY KEY,
    title TEXT NOT NULL,
    description TEXT,
    status TEXT DEFAULT 'pending'
);

CREATE TABLE todo_deps (
    todo_id TEXT,
    depends_on TEXT,
    PRIMARY KEY (todo_id, depends_on)
);

Jeder Todo bewegt sich durch einen kleinen Zustandsautomat:

pending -> in_progress -> done
                       \-> blocked

Ein Unter-Agent sollte:

Beanspruchen Sie genau eine verfügbare Aufgabe, indem Sie status = 'in_progress' festlegen.
Arbeiten Sie nur im Umfang dieses Todos.
Speichern Sie das Ergebnis in der Konversation oder in der Ausgabe der entsprechenden Aufgabe.
Legen Sie status = 'done' fest, wenn Sie fertig sind.
Legen Sie fest status = 'blocked' , wann der Vorgang nicht fortgesetzt werden kann, und schließen Sie den Grund ein.

Der Orchestrator kann Aufgaben finden, deren Abhängigkeiten mit einer Abfrage wie der folgenden erfüllt sind:

SELECT t.*
FROM todos t
WHERE t.status = 'pending'
  AND NOT EXISTS (
      SELECT 1
      FROM todo_deps td
      JOIN todos dep ON td.depends_on = dep.id
      WHERE td.todo_id = t.id
        AND dep.status != 'done'
  );

Dieses Muster weist jedem Worker eine klare Zuständigkeit zu und ermöglicht es der übergeordneten Sitzung, nachzuvollziehen, was bereit, in Ausführung, abgeschlossen oder blockiert ist.

Lifecycle Hooks

Der Fleet-Modus ruft Unteragenten über den Aufgabenmechanismus der Laufzeitumgebung auf. Die Runtime meldet Hook-Aktivität für Sub-Agent-Toolaufrufe: Im Änderungsprotokoll zu Runtime 1.0.52 wird vermerkt, dass preToolUse, postToolUse, subagentStart und subagentStop für Sub-Agent-Toolaufrufe korrekt ausgelöst werden.

Ein dedizierter SDK-Hook-Rückruf für subagentStart oder subagentStop wurde in der öffentlichen SDK-Oberfläche auf dieser Verzweigung nicht gefunden. Nutzer des SDK können die Aktivität des Sub-Agents über den generischen Sitzungsereignisstrom beobachten, der Ereignisse wie subagent.started, subagent.completed, subagent.failed, subagent.selected und subagent.deselected enthält.

TypeScript

session.on((event) => {
    if (event.type === "subagent.started") {
        console.log(`Started ${event.data.agentDisplayName}`);
    }

    if (event.type === "subagent.completed") {
        console.log(`Completed ${event.data.agentDisplayName}`);
    }
});

Python

import asyncio
from copilot import CopilotClient
from copilot.session import PermissionHandler

async def main():
    client = CopilotClient()
    await client.start()
    session = await client.create_session(
        on_permission_request=PermissionHandler.approve_all,
    )

    def handle_event(event):
        if event.type == "subagent.started":
            print(f"Started {event.data.agent_display_name}")
        elif event.type == "subagent.completed":
            print(f"Completed {event.data.agent_display_name}")

    unsubscribe = session.on(handle_event)

asyncio.run(main())

def handle_event(event):
    if event.type == "subagent.started":
        print(f"Started {event.data.agent_display_name}")
    elif event.type == "subagent.completed":
        print(f"Completed {event.data.agent_display_name}")

unsubscribe = session.on(handle_event)

Informationen zur Hookkonfiguration, die bereits auf der SDK-Ebene verfügbar gemacht wird, finden Sie unter Arbeiten mit Hooks. Informationen zu Event-Payloads von Sub-Agents finden Sie unter Angepasste Agents und Orchestrierung von Unteragenten.

Plugin-Unteragenten

Die Laufzeit kann Plug-Ins mit --plugin-dir laden. Plugins, die auf diese Weise geladen werden, können ihre Agenten im Prompt-Modus als verfügbare task(agent_type=...) Sub-Agent-Typen registrieren, was bedeutet, dass der Flottenmodus Aufgaben an diese von Plugins bereitgestellten Workertypen weiterleiten kann.

Dies ist derzeit eher ein Konfigurationsmuster auf Runtime-Ebene als eine dokumentierte Registrierungs-API auf SDK-Ebene. Konfigurieren Sie die Copilot CLI-Laufzeit mit dem Plug-In-Verzeichnis, und verbinden Sie dann den SDK-Client mit dieser Laufzeit. Native SDK-Hilfsprogramme zum Registrieren von Plug-In-Sub-Agent-Typen können in Zukunft hinzugefügt werden.

Konzeptionell kann eine Flottenaufforderung dann nach einem bestimmten Arbeitstyp fragen:

Use task(agent_type="security-review") for each independent package.
Run the workers in parallel and summarize only high-confidence findings.

Halten Sie die vom Plug-In bereitgestellten Sub-Agent-Typen schmal und beschreibend, damit der Orchestrator sie zuverlässig auswählen kann.

Bewährte Methoden

Zerlegen Sie die Arbeit in unabhängige Einheiten, bevor Sie den Flottenmodus starten.
Minimieren Sie Abhängigkeiten zwischen Todos; Abhängigkeiten reduzieren Parallelität.
Geben Sie jedem Todo eine dauerhafte ID, einen klaren Titel und eine vollständige Beschreibung.
Sorgen Sie dafür, dass jeder Sub-Agent zu jedem Zeitpunkt genau eine Aufgabe hat.
Verwenden Sie Hintergrund-Unteragenten für echte parallele Verarbeitung.
Verwenden Sie synchrone Sub-Agent-Aufrufe für serialisierte Schritte oder Validierungsgates.
Stellen Sie jedem Sub-Agent einen vollständigen Kontext zur Verfügung; Sub-Agents sind über Anrufe hinweg statuslos.
Fügen Sie Dateipfade, Befehle, erwartete Ausgaben und Einschränkungen in jede Arbeitsaufforderung ein.
Starten Sie keinen einzelnen Sub-Agenten im Hintergrund; verwenden Sie stattdessen einen synchronen Aufruf oder bündeln Sie mehrere Worker parallel.
Vermeiden Sie die Zuweisung überlappender Dateien an verschiedene Bearbeiter, es sei denn, der übergeordnete Agent wird Konflikte ausdrücklich abgleichen.
Fordern Sie alle Mitarbeiter auf, zu melden, was sie geändert hat, wie sie die Änderung überprüft hat und was blockiert bleibt.
Lassen Sie den übergeordneten Agent das kombinierte Ergebnis überprüfen, nachdem die Mitarbeiter fertig sind.

Einschränkungen und offene Fragen

Der Flottenmodus wird über generierte Sitzungs-RPC-Bindungen bereitgestellt und ist in mehreren SDKs als experimentell gekennzeichnet.
Das SQL-Todos-Muster ist das kanonische Koordinationsmodell in der Laufzeitanleitung, aber ob es sich um einen stabilen Erweiterbarkeitsvertrag für SDK-Consumer handelt, ist nach wie vor eine offene Frage.
subagentStart und subagentStop sind Namen von Laufzeit-Hooks; dieser Branch stellt SDK-Nutzern den Lebenszyklus von Sub-Agents über den generischen Sitzungsereignisstrom bereit und nicht über dedizierte Hook-Callbacks.
Die Registrierung des Sub-Agenten des Plug-ins wird in der Laufzeitschicht über --plugin-dir konfiguriert; in diesem Branch wurde keine Hilfsfunktion zur Plug-in-Registrierung auf SDK-Ebene festgestellt.
Java systemeigene typierte Bindungen für session.fleet.start wurden in der Java SDK-Quelle in dieser Verzweigung nicht gefunden.
Der Flottenmodus ersetzt nicht die Überprüfung durch den übergeordneten Agenten. Parallele Worker können inkonsistente Annahmen erzeugen, die der Orchestrator abgleichen muss.

In diesem Artikel