Mensagens de direção e fila no SDK do Copilot

          SDK do Copilot está atualmente em versão prévia técnica. A funcionalidade e a disponibilidade estão sujeitas a alterações.

Dois padrões de interação permitem que os usuários enviem mensagens enquanto o agente já está em operação: direcionamento redireciona o agente no meio da atividade e enfileiramento armazena mensagens em buffer para processamento sequencial (FIFO, first-in-first-out) após a conclusão da atividade atual.

Quando uma sessão está processando ativamente uma vez, as mensagens de entrada podem ser entregues em um dos dois modos por meio do mode campo no MessageOptions:

Modo	Comportamento	Caso de uso

          `"immediate"` (direção) | Injetado na **atual** etapa do LLM | "Na verdade, não crie esse arquivo — use uma abordagem diferente" |

| "enqueue" (enfileiramento) | Enfileirado e processado após a conclusão do turno atual | "Depois disso, corrija também os testes" |

Para obter um diagrama de sequência do fluxo de roteamento e enfileiramento, consulte o github/copilot-sdk repositório.

Direção (modo imediato)

O controle envia uma mensagem que é injetada diretamente no turno atual do agente. O agente vê a mensagem em tempo real e ajusta sua resposta adequadamente, sendo útil para correção de curso sem anular o turno.

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
await client.start();

const session = await client.createSession({
    model: "gpt-4.1",
    onPermissionRequest: async () => ({ kind: "approved" }),
});

// Start a long-running task
const msgId = await session.send({
    prompt: "Refactor the authentication module to use sessions",
});

// While the agent is working, steer it
await session.send({
    prompt: "Actually, use JWT tokens instead of sessions",
    mode: "immediate",
});

Para obter exemplos em Python, Go e .NET, consulte o github/copilot-sdk repositório.

Como a direção funciona internamente

1. A mensagem é adicionada à fila do ImmediatePromptProcessor runtime.
2. Antes da próxima solicitação do LLM no turno atual, o processador insere a mensagem na conversa.
3. O agente vê a mensagem de direção como uma nova mensagem de usuário e ajusta sua resposta.
4. Se a curva for concluída antes que a mensagem de direção seja processada, ela será movida automaticamente para a fila regular para a próxima curva.

Fila (modo de enfileiramento)

O enfileiramento armazena em buffer as mensagens para serem processadas sequencialmente após a conclusão do turno atual. Cada mensagem enfileirada inicia seu próprio turno completo. Esse é o modo padrão, se você omitir mode, o SDK usará "enqueue".

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
await client.start();

const session = await client.createSession({
    model: "gpt-4.1",
    onPermissionRequest: async () => ({ kind: "approved" }),
});

// Send an initial task
await session.send({ prompt: "Set up the project structure" });

// Queue follow-up tasks while the agent is busy
await session.send({
    prompt: "Add unit tests for the auth module",
    mode: "enqueue",
});

await session.send({
    prompt: "Update the README with setup instructions",
    mode: "enqueue",
});

// Messages are processed in FIFO order after each turn completes

Para obter exemplos em Python, Go e .NET, consulte o github/copilot-sdk repositório.

Como a fila funciona internamente

1. A mensagem é adicionada à sessão itemQueue como um QueuedItem.
2. Quando a rodada atual for concluída e a sessão ficar ociosa, processQueuedItems() executa.
3. Os itens são desqueados na ordem FIFO, cada mensagem dispara uma curva agente completa.
4. Se uma mensagem de direção estava pendente quando a curva terminou, ela é movida para a frente da fila.
5. O processamento continua até que a fila esteja vazia e, em seguida, a sessão emitirá um evento ocioso.

Combinando direção e fila

Você pode usar os dois padrões juntos em uma única sessão. O controle de direção afeta o movimento atual enquanto as mensagens enfileiradas esperam sua vez.

const session = await client.createSession({
    model: "gpt-4.1",
    onPermissionRequest: async () => ({ kind: "approved" }),
});

// Start a task
await session.send({ prompt: "Refactor the database layer" });

// Steer the current work
await session.send({
    prompt: "Make sure to keep backwards compatibility with the v1 API",
    mode: "immediate",
});

// Queue a follow-up for after this turn
await session.send({
    prompt: "Now add migration scripts for the schema changes",
    mode: "enqueue",
});

Para obter um exemplo em Python, consulte o github/copilot-sdk repositório.

Escolhendo entre direção e fila

Scenario	Padrão	Por que
O agente está indo pelo caminho errado	Direcção	Redireciona a curva atual sem perder o progresso
Você pensou em algo que o agente também deveria fazer	Enfileiramento	Não interrompe o trabalho atual; executa em seguida
O agente está prestes a cometer um erro	Direcção	Intervém antes que o erro seja cometido
Você deseja encadear várias tarefas	Enfileiramento	A ordenação FIFO garante uma execução previsível
Você deseja adicionar contexto à tarefa atual	Direcção	O Agente incorpora-o ao seu raciocínio atual
Você deseja enviar em lote solicitações não relacionadas	Enfileiramento	Cada um obtém seu próprio turno completo com contexto limpo

Criando uma interface do usuário com direção e fila

Aqui está um padrão para criar uma interface do usuário interativa que dá suporte a ambos os modos:

import { CopilotClient, CopilotSession } from "@github/copilot-sdk";

interface PendingMessage {
    prompt: string;
    mode: "immediate" | "enqueue";
    sentAt: Date;
}

class InteractiveChat {
    private session: CopilotSession;
    private isProcessing = false;
    private pendingMessages: PendingMessage[] = [];

    constructor(session: CopilotSession) {
        this.session = session;

        session.on((event) => {
            if (event.type === "session.idle") {
                this.isProcessing = false;
                this.onIdle();
            }
            if (event.type === "assistant.message") {
                this.renderMessage(event);
            }
        });
    }

    async sendMessage(prompt: string): Promise<void> {
        if (!this.isProcessing) {
            this.isProcessing = true;
            await this.session.send({ prompt });
            return;
        }

        // Session is busy — let the user choose how to deliver
        // Your UI would present this choice (e.g., buttons, keyboard shortcuts)
    }

    async steer(prompt: string): Promise<void> {
        this.pendingMessages.push({
            prompt,
            mode: "immediate",
            sentAt: new Date(),
        });
        await this.session.send({ prompt, mode: "immediate" });
    }

    async enqueue(prompt: string): Promise<void> {
        this.pendingMessages.push({
            prompt,
            mode: "enqueue",
            sentAt: new Date(),
        });
        await this.session.send({ prompt, mode: "enqueue" });
    }

    private onIdle(): void {
        this.pendingMessages = [];
        // Update UI to show session is ready for new input
    }

    private renderMessage(event: unknown): void {
        // Render assistant message in your UI
    }
}

Referência de API

Você pode usar a API de SDK do Copilot sessão para gerenciar e organizar em fila sessões.

Opções de Mensagem

Linguagem	Campo	Tipo	Default	Descrição
Node.js	mode	"enqueue" | "immediate"	"enqueue"	Modo de entrega de mensagens
Python	mode	Literal["enqueue", "immediate"]	"enqueue"	Modo de entrega de mensagens
Go	Mode	string	"enqueue"	Modo de entrega de mensagens
.NET	Mode	string?	"enqueue"	Modo de entrega de mensagens

Modos de entrega

Modo	Efeito	Durante o turno ativo	Durante a inatividade
"enqueue"	Fila para a próxima curva	Esperas na fila FIFO	Inicia uma nova curva imediatamente
"immediate"	Injetar no turno atual	Injetado antes da próxima chamada LLM	Inicia uma nova curva imediatamente

Práticas recomendadas

•         **Definir como padrão o enfileiramento** — Usar `"enqueue"` (ou omitir `mode`) para a maioria das mensagens. É previsível e não corre o risco de interromper o trabalho em andamento.
  

•         **Reserve o direcionamento exclusivamente para correções** — use `"immediate"` quando o agente estiver fazendo algo errado ativamente e for necessário redirecioná-lo antes que ele avance ainda mais.
  

•         **Mantenha as mensagens de direção concisas**: o agente precisa entender rapidamente a correção do curso. Mensagens de direção longas e complexas podem confundir o contexto atual.
  

•         **Não direcione demais**— várias mensagens de direção rápidas podem prejudicar a qualidade da curva. Se você precisar alterar significativamente a direção, considere anular a curva e iniciar novamente.
  

•         **Mostrar o estado da fila na interface do usuário** — exiba o número de mensagens enfileiradas para que os usuários saibam o que está pendente. Monitore eventos de inatividade para limpar a tela.
  

•         **Manipular o fallback de direção para fila** — se uma mensagem de direção chegar após a conclusão da curva, ela será movida automaticamente para a fila. Crie sua interface do usuário para refletir essa transição.