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 worker pode validar sua própria fatia e reportar.

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 vinculação é experimental na superfície RPC gerada; fixe o SDK e o runtime da CLI do Copilot se seu aplicativo depender disso.

De dentro de uma sessão

O método de conexão é session.fleet.start. O prompt opcional é combinado com as instruções de orquestração de frota do runtime.

Idiomas de código 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");
}

Associações tipadas nativas para o modo de frota foram verificadas em Node.js/TypeScript, Python, Go, .NET e Rust. Uma vinculação Java não foi encontrada em java/src/main/java nesta ramificação, portanto, os exemplos em Java são omitidos até que essa superfície esteja disponível.

A partir do modo de planejamento

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

type ExitPlanModeAction =
  | "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 principal decompõe o trabalho em tarefas (todos), cada subagente é responsável por uma tarefa e o orquestrador despacha os trabalhadores 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 tarefa passa por uma pequena máquina de estados:

pending -> in_progress -> done
                       \-> blocked

Um subagente deve:

Reivindique exatamente uma tarefa pronta definindo status = 'in_progress'.
Trabalhe apenas no escopo dessa tarefa.
Armazene seu resultado na conversa ou na saída da tarefa relevante.
Defina status = 'done' quando estiver concluído.
Defina status = 'blocked' quando não puder continuar e inclua o motivo.

O orquestrador pode encontrar trabalhos cujas dependências foram satisfeitas 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 proprietário claro a cada trabalhador e permite que a sessão principal raciocine sobre 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 ambiente de execução emite atividade de gancho para chamadas de ferramentas de subagentes: o changelog do ambiente de execução 1.0.52 observa que preToolUse, postToolUse, subagentStart e subagentStop são disparados corretamente para chamadas de ferramentas de subagentes.

Não foi encontrado um retorno de chamada de gancho de SDK dedicado para subagentStart ou subagentStop na superfície 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.

Idiomas de código 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)

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

Subagentes de plug-in

O ambiente de execução pode carregar plug-ins com --plugin-dir. Plug-ins carregados dessa forma podem registrar seus agentes como tipos de subagentes task(agent_type=...) disponíveis no modo de prompt, o que significa que o modo de frota pode despachar para esses tipos de trabalhadores fornecidos pelo plug-in.

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 de trabalhador específico:

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.
Atribua a cada tarefa um ID permanente, um título claro e uma descrição completa.
Faça com que cada subagente seja responsável por exatamente uma tarefa por 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 o contexto completo; os subagentes não mantêm estado entre as chamadas.
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 resolva os conflitos explicitamente.
Exigir que todo colaborador relate o que mudou, como validou a mudança e o que ainda permanece bloqueado.
Faça com que o agente pai verifique o resultado combinado após a conclusão dos trabalhadores.

Limitações e perguntas abertas

O modo frota é exposto por meio de vinculações RPC de sessão geradas e está marcado como experimental em vários SDKs.
O padrão de tarefas SQL é o modelo de coordenação canônico nas diretrizes de tempo de execução, mas se ele é um contrato de extensibilidade estável para consumidores do SDK ainda é uma questão em aberto.
subagentStart e subagentStop são nomes de ganchos de tempo de execução; este ramo expõe o ciclo de vida do subagente para consumidores do SDK por meio do fluxo de eventos de sessão genérico, não por retornos de chamada de gancho dedicados.
O registro do subagente do plug-in é configurado na camada de tempo de execução por meio de --plugin-dir; Nenhuma função auxiliar de registro de plug-in em nível de SDK foi verificada nesta ramificação.
Não foram encontradas associações tipadas nativas do Java para session.fleet.start no código-fonte do SDK Java nesta ramificação.
O modo frota não elimina a necessidade de revisão pelo agente pai. Os trabalhadores paralelos podem produzir pressupostos inconsistentes que o orquestrador precisa conciliar.

Neste artigo

Quando usar o modo de frota

Iniciando o modo de frota

De dentro de uma sessão

Idiomas de código navigation

A partir do modo de planejamento

Como os sub-agentes são coordenados

Ganchos do ciclo de vida

Idiomas de código navigation

Subagentes de plug-in

Práticas recomendadas

Limitações e perguntas abertas

Consulte também