Modo flota

Cuándo usar el modo de flota

El modo de flota es útil cuando el trabajo se puede descomponer antes de ejecutarlo y cada unidad puede ejecutarse sin esperar a las demás.

Entre las opciones adecuadas se incluyen:

• Refactorizaciones de varios archivos donde cada trabajador posee un archivo, un paquete o un SDK de lenguaje.
• Revisiones por lotes en las que cada trabajador revisa por separado un conjunto de cambios, un módulo o un grupo de alertas.
• Investigación paralela en repositorios, servicios o áreas de características independientes.
• La documentación se actualiza donde cada trabajador posee una página o tema.
• Tareas de migración en las que cada trabajador puede validar su propia porción e informar del resultado.

Evite el modo de gestión de flotas para:

• Tareas secuenciales en las que el paso 2 necesita la salida concreta del paso 1.
• Ediciones fuertemente acopladas en las que los trabajadores competirían por los mismos archivos.
• Tareas pequeñas que un subagente sincrónico o el agente primario pueden finalizar rápidamente.
• Tareas que requieren un razonamiento compartido de forma continua en lugar de una responsabilidad claramente definida.

El modo de flota funciona mejor cuando la sesión primaria puede crear unidades de trabajo claras, asignar un propietario por unidad y definir lo que cada trabajador debe devolver.

Inicio del modo de flota

El SDK expone el modo de flota a través del espacio de nombres RPC de sesión en varios idiomas. El enlace es experimental en la superficie RPC generada; ancle tanto el SDK como el entorno de ejecución de la CLI de Copilot si la aplicación depende de él.

Desde dentro de una sesión

El método de cableado es session.fleet.start. El prompt opcional se combina con las instrucciones de orquestación de flotas del entorno de ejecución.

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

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

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

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

Los enlaces con tipo nativo para el modo de flota se comprobaron en Node.js/TypeScript, Python, Go, .NET y Rust. No se encontró ningún binding de Java en java/src/main/java en esta rama, por lo que se omiten los ejemplos de Java hasta que esa interfaz esté disponible.

Desde el modo de plan

Las interfaces de usuario del modo de planificación pueden iniciar el despliegue de la flota devolviendo la acción de salida autopilot_fleet. Los tipos de eventos de sesión generados lo describen como:

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

Úselo cuando un usuario aprueba un plan que ya contiene elementos de trabajo independientes. Se usa autopilot para un único trabajador autónomo y interactive cuando el usuario debe permanecer en el bucle.

Cómo se coordinan los subagentes

El modo de flota se basa en el estado de coordinación explícito en lugar de en la memoria compartida implícita. El agente principal descompone el trabajo en tareas, cada subagente se encarga de una tarea y el orquestador despacha a los trabajadores cuyas dependencias ya se han completado.

El esquema canónico es:

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)
);

Cada tarea pasa por una pequeña máquina de estados:

pending -> in_progress -> done
                       \-> blocked

Un subagente debe:

1. Reclamar exactamente una tarea pendiente lista para realizar estableciendo status = 'in_progress'.
2. Trabajar únicamente en el ámbito de esa tarea pendiente.
3. Almacene el resultado en la conversación o en la salida de la tarea correspondiente.
4. Establecer status = 'done' cuando haya finalizado.
5. Establezca status = 'blocked' cuándo no puede continuar e incluya el motivo.

El orquestador puede encontrar tareas cuyas dependencias se cumplan mediante una consulta como:

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'
  );

Este patrón asigna a cada trabajador un responsable claro y permite a la sesión principal determinar qué está listo, en ejecución, completado o bloqueado.

Enlaces de ciclo de vida

El modo de flota invoca subagentes a través del mecanismo de tareas del entorno de ejecución. El entorno de ejecución emite actividad de los enlaces para las llamadas a herramientas de subagentes: el registro de cambios de la versión 1.0.52 de tiempo de ejecución señala que preToolUse, postToolUse, subagentStart y subagentStop se activan correctamente para las llamadas a herramientas de subagentes.

No se encontró una función de devolución de llamada de enlace del SDK específica para subagentStart o subagentStop en la API pública del SDK de esta rama. Los consumidores del SDK pueden observar la actividad del subagente a través del flujo genérico de eventos de sesión, que incluye eventos como subagent.started, subagent.completed, subagent.failed, subagent.selected y subagent.deselected.

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}`);
    }
});

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)

Para consultar la configuración de hooks que ya está expuesta en la capa del SDK, consulte Trabajar con enlaces. Para las cargas útiles de eventos de subagente, consulte Agentes personalizados y orquestación de subagentes.

Subagentes del complemento

El entorno de ejecución puede cargar complementos con --plugin-dir. Los complementos cargados de esta manera pueden registrar sus agentes como tipos de subagente disponibles task(agent_type=...) en modo de indicación, lo que significa que el modo de flota puede asignar esos tipos de trabajadores proporcionados por los complementos.

Actualmente, se trata de un patrón de configuración en tiempo de ejecución, en lugar de una API de registro documentada a nivel de SDK. Configure el entorno de ejecución de la CLI de Copilot con el directorio del complemento y, a continuación, conecte el cliente del SDK a ese tiempo de ejecución. En el futuro, podrían añadirse utilidades del SDK nativo para registrar tipos de subagentes de complementos.

Conceptualmente, una solicitud de flota puede entonces solicitar un tipo de trabajador específico:

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

Mantenga los tipos de subagente proporcionados por complementos estrechos y descriptivos para que el orquestador pueda elegirlos de forma confiable.

procedimientos recomendados

• Descompone el trabajo en unidades independientes antes de iniciar el modo de flota.
• Minimizar las dependencias entre tareas; las dependencias reducen el paralelismo.
• Asigne a cada tarea un identificador duradero, un título claro y una descripción completa.
• Haga que cada subagente tenga asignada exactamente una tarea a la vez.
• Use subagentes en segundo plano para trabajar realmente en paralelo.
• Use llamadas de subagente sincrónicas para pasos serializados o puertas de validación.
• Proporcione a cada subagente el contexto completo; los subagentes no tienen estado entre llamadas.
• Incluya rutas de acceso de archivo, comandos, salidas esperadas y restricciones en cada solicitud de trabajo.
• No envíe un único subagente en segundo plano; prefiera una llamada síncrona o agrupe varios procesos de trabajo en paralelo.
• Evite asignar archivos solapados a distintos trabajadores, a menos que el agente padre vaya a resolver los conflictos explícitamente.
• Requerir que cada trabajador notifique lo que ha cambiado, cómo validó el cambio y qué permanece bloqueado.
• Haga que el agente primario compruebe el resultado combinado después de que finalicen los trabajos.

Limitaciones y preguntas abiertas

• El modo de flota se expone a través de las vinculaciones RPC de sesión generadas y está marcado como experimental en varios SDK.
• El patrón SQL todos es el modelo de coordinación canónico en la guía de ejecución, pero sigue siendo una cuestión abierta si constituye un contrato de extensibilidad estable para los usuarios del SDK.

•           `subagentStart` y `subagentStop` son nombres de enlaces en tiempo de ejecución; en esta rama se expone el ciclo de vida del subagente a los consumidores del SDK a través del flujo genérico de eventos de sesión, y no mediante devoluciones de llamada de enlaces específicos.
  

• El registro del subagente del plugin se configura en la capa de ejecución a través de --plugin-dir; no se verificó ningún asistente para registrar plugins a nivel de SDK en esta rama.
• No se han encontrado enlaces tipados nativos de Java para session.fleet.start en el código fuente del SDK de Java de esta rama.
• El modo de flota no elimina la necesidad de revisión por parte del agente primario. Los trabajos paralelos pueden producir suposiciones incoherentes que el orquestador debe conciliar.

Consulte también

• Agentes personalizados y orquestación de subagentes
• Trabajar con enlaces