Modo de frota

Quando usar o modo de frota

O modo frota é útil quando o trabalho pode ser decomposto antes da execução e cada unidade pode ser executada sem esperar pelas outras.

Os bons ajustes incluem:

Refatorações em vários arquivos, em que cada agente fica responsável por um arquivo, pacote ou SDK de linguagem.
Revisões em lote em que cada revisor verifica um diff, módulo ou grupo de alertas separado.
Busca paralela em repositórios, serviços ou áreas de funcionalidade independentes.
Atualizações da documentação em que cada colaborador é responsável por uma página ou tópico.
Tarefas de migração em que cada trabalhador pode validar sua própria fatia e relatar de volta.

Evite o modo de frota para:

Tarefas sequenciais em que a etapa 2 precisa da saída concreta da etapa 1.
Edições fortemente acopladas, em que os colaboradores concorreriam pelos mesmos arquivos.
Pequenas tarefas que um subagente síncrono ou o agente pai podem concluir rapidamente.
Tarefas que exigem raciocínio compartilhado contínuo em vez de responsabilidade claramente definida.

O modo de frota funciona melhor quando a sessão principal pode criar unidades de trabalho claras, atribuir um responsável a cada unidade e definir o que cada trabalhador deve retornar.

O SDK expõe o modo de frota por meio do namespace RPC de sessão em vários idiomas. A associação é experimental na superfície RPC gerada; fixe o SDK e o Copilot runtime da CLI se o aplicativo depender dele.

De dentro de uma sessão

O método com fio é session.fleet.start. O prompt opcional é combinado às instruções de orquestração da frota do runtime.

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

Associações tipadas nativas para o modo de frota foram verificadas em Node.js/TypeScript, Python, Go, .NET e Rust. Não foi encontrado um binding de Java em java/src/main/java nesta ramificação, portanto os exemplos em Java foram omitidos até que esse recurso esteja disponível.

Do modo de plano

As interfaces de usuário do modo de planejamento podem iniciar a implantação de frota retornando a ação de saída autopilot_fleet. Os tipos de evento de sessão gerados descrevem-no como:

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

Use isto quando um usuário aprova um plano que já contém itens de trabalho independentes. Use autopilot para um único agente autônomo e interactive quando o usuário deve continuar envolvido no processo.

Como os sub-agentes são coordenados

O modo de frota depende do estado de coordenação explícita em vez da memória compartilhada implícita. O agente pai decompõe o trabalho em tarefas, cada subagente fica responsável por uma tarefa, e o orquestrador aciona os agentes de trabalho cujas dependências já foram concluídas.

O esquema canônico é:

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 todo passa por um computador de estado pequeno:

pending -> in_progress -> done
                       \-> blocked

Um subagente deve:

Atribua exatamente uma tarefa pronta ao definir status = 'in_progress'.
Trabalhe somente no escopo desse todo.
Armazene o resultado na conversa ou na saída da tarefa correspondente.
Defina status = 'done' quando estiver concluído.
Defina status = 'blocked' quando não puder continuar e inclua o motivo.

O orquestrador pode encontrar uma tarefa cujas dependências foram atendidas com uma 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'
  );

Esse padrão atribui um responsável claro a cada trabalhador e permite que a sessão pai determine o que está pronto, em execução, concluído ou bloqueado.

Ganchos do ciclo de vida

O modo de frota invoca sub-agentes por meio do mecanismo de tarefa do runtime. O runtime emite eventos de hook para chamadas de ferramenta de subagente: o changelog do runtime 1.0.52 informa que preToolUse, postToolUse, subagentStart e subagentStop são acionados corretamente para chamadas de ferramenta de subagente.

Não foi encontrado um callback de hook dedicado do SDK para subagentStart ou subagentStop na API pública do SDK nesta ramificação. Os consumidores do SDK podem observar a atividade do subagente por meio do fluxo de eventos de sessão genérica, que inclui eventos como subagent.started, , subagent.completed, subagent.failed``subagent.selectede subagent.deselected.

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)

Para a configuração de gancho que já está exposta na camada do SDK, consulte Trabalhando com ganchos. Para as cargas úteis de eventos do subagente, consulte Agentes personalizados e orquestração de subagentes.

Subagentes de plug-in

O runtime pode carregar plug-ins com --plugin-dir. Os plugins carregados dessa forma podem registrar seus agentes como tipos de subagente disponíveis task(agent_type=...) no modo de prompt, o que significa que o modo de frota pode direcionar tarefas para esses tipos de agentes de trabalho fornecidos por esses plugins.

Atualmente, esse é um padrão de configuração em nível de runtime em vez de uma API de registro no nível do SDK documentada. Configure o runtime da CLI Copilot com o diretório do plug-in e conecte o cliente do SDK a esse runtime. Funções auxiliares nativas do SDK para registrar tipos de subagente de plugin poderão ser adicionadas futuramente.

Conceitualmente, um prompt de frota pode então solicitar um tipo específico de trabalhador:

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

Mantenha os tipos de sub-agente fornecidos pelo plug-in estreitos e descritivos para que o orquestrador possa escolhê-los de forma confiável.

Práticas recomendadas

Decompor o trabalho em unidades independentes antes de iniciar o modo de frota.
Minimizar dependências entre tarefas; as dependências reduzem o paralelismo.
Dê a cada todo uma ID durável, um título claro e uma descrição completa.
Faça com que cada sub-agente assuma exatamente uma tarefa de cada vez.
Use subagentes em segundo plano para realizar trabalho realmente em paralelo.
Use chamadas de subagente síncronas para etapas serializadas ou portões de validação.
Forneça a cada subagente um contexto completo; os subagentes não mantêm estado de uma chamada para outra.
Inclua caminhos de arquivo, comandos, saídas esperadas e restrições em cada prompt de trabalho.
Não despache um único subagente em segundo plano; prefira uma chamada síncrona ou agrupar vários trabalhadores em paralelo.
Evite atribuir arquivos sobrepostos a diferentes trabalhadores, a menos que o agente pai reconcilie os conflitos explicitamente.
Exigir que todo colaborador relate o que mudou, como validou a mudança e o que ainda permanece bloqueado.
Fazer com que o agente pai verifique o resultado combinado após a conclusão dos trabalhos.

Limitações e perguntas abertas

O modo de frota é exposto por meio de associações RPC de sessão geradas e é marcado como experimental em vários SDKs.
O padrão SQL todos é o modelo canônico de coordenação na orientação de runtime, mas a questão de saber se ele é um contrato estável de extensibilidade para consumidores do SDK continua em aberto.
subagentStart e subagentStop são nomes de hooks de runtime; esta ramificação expõe o ciclo de vida do subagente aos consumidores do SDK por meio do fluxo genérico de eventos da sessão, e não de callbacks dedicados.
O registro do subagente do plug-in é configurado na camada de execução por meio de --plugin-dir; nenhum helper de registro de plug-in no nível do SDK foi identificado neste ramo.
Java associações de tipo nativo para session.fleet.start não foram encontradas na origem do SDK Java neste branch.
O modo Fleet não elimina a necessidade de revisão do agente pai. Os trabalhadores paralelos podem produzir pressupostos inconsistentes que o orquestrador precisa conciliar.

Neste artigo