Flottenmodus

Wann der Flottenmodus verwendet werden sollte

Der Flottenmodus ist nützlich, wenn die Arbeit vor der Ausführung unterteilt 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; heften Sie sowohl das SDK als auch die Copilot CLI Runtime an, wenn Ihre Anwendung von ihnen abhängt.

Innerhalb einer Sitzung

Die Verbindungsmethode ist session.fleet.start. Der optionale prompt ist mit den Anweisungen für die Flottenorchestrierung der Runtime kombiniert.

Codesprachen navigation

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.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::rpc::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 dieser Verzweigung wurde in java/src/main/java keine Java-Bindung gefunden, daher werden Java-Beispiele nicht angegeben, bis die Oberfläche verfügbar ist.

Vom Planmodus

Bei Benutzeroberflächen im Planmodus kann die Bereitstellung der Flotte über die Rückgabe der Ausgangsaktion autopilot_fleet gestartet werden. Die generierten Sitzungsereignistypen beschreiben sie wie:

type ExitPlanModeAction =
  | "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 auf dem Laufenden bleiben soll.

Wie Sub-Agenten zusammenarbeiten

Der Flottenmodus beruht auf einem expliziten Koordinationsstatus statt auf implizitem gemeinsam genutztem Speicher. Der übergeordnete Agent unterteilt die Arbeit in Todos, jeder Unter-Agent besitzt einen Todo, und der Orchestrator beauftragt Worker, 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 durchläuft einen kleinen Zustandsautomaten:

pending -> in_progress -> done
                       \-> blocked

Ein Unter-Agent sollte:

genau ein verfügbares Todo beanspruchen und dazu status = 'in_progress' festlegen,
nur innerhalb des Umfangs dieses Todos arbeiten,
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 der Ausführung, abgeschlossen oder blockiert ist.

Lifecycle Hooks

Der Fleet-Modus ruft Unteragenten über den Aufgabenmechanismus der Laufzeitumgebung auf. Die Runtime gibt Hook-Aktivitäten für Toolaufrufe durch Unter-Agents aus: Im Änderungsprotokoll zur Runtime 1.0.52 wird vermerkt, dass preToolUse, postToolUse, subagentStart und subagentStop für Toolaufrufe von Unter-Agents korrekt ausgelöst werden.

In dieser Verzweigung wurde kein dedizierter SDK-Hook-Rückruf für subagentStart oder subagentStop in der öffentlichen SDK-Oberfläche 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.

Codesprachen navigation

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 Runtime kann über --plugin-dir Plug-Ins laden. Auf diese Weise geladene Plug-Ins können ihre Agents im Prompt-Modus als verfügbare task(agent_type=...)-Unter-Agent-Typen registrieren, was bedeutet, dass der Flottenmodus Aufgaben an diese über Plug-Ins bereitgestellte Workertypen zuweisen 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.
Weisen Sie jedem Unter-Agent jeweils genau ein Todo zu.
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.
Beauftragen Sie nicht einen einzelnen Unter-Agent im Hintergrund; verwenden Sie stattdessen einen synchronen Aufruf oder Batch für mehrere Worker gleichzeitig.
Vermeiden Sie die Zuweisung überlappender Dateien an verschiedene Bearbeiter, es sei denn, der übergeordnete Agent wird Konflikte ausdrücklich abgleichen.
Sorgen Sie dafür, dass jeder Worker meldet, was er geändert hat, wie er 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 Anleitung der Runtime. Aber ob es sich um eine stabile Erweiterbarkeitsoption 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 von Unter-Agents aus einem Plug-In wird in der Runtime-Ebene über --plugin-dir konfiguriert; in dieser Verzweigung wurde keine Hilfsfunktion zur Plug-In-Registrierung auf SDK-Ebene geprüft.
In der Java SDK-Quelle in dieser Verzweigung wurde keine systemeigenen Java-Bindungen für session.fleet.start 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

Wann der Flottenmodus verwendet werden sollte

Starten des Flottenmodus

Innerhalb einer Sitzung

Codesprachen navigation

Vom Planmodus

Wie Sub-Agenten zusammenarbeiten

Lifecycle Hooks

Codesprachen navigation

Plugin-Unteragenten

Bewährte Methoden

Einschränkungen und offene Fragen

Siehe auch