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

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 do turno e enfileiramento armazena mensagens em buffer para processamento sequencial (FIFO, first-in-first-out) após a conclusão do turno atual.

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

Modo	Comportamento	Caso de uso

          `"immediate"` (direção) | Injetado no turno LLM **atual** | "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 direcionamento e enfileiramento, consulte o repositório github/copilot-sdk.

Direção (modo imediato)

O direcionamento 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. Para Java, consulte o github/copilot-sdk-java repositório.

Como a direção funciona internamente

1. A mensagem é adicionada à fila ImmediatePromptProcessor do runtime.
2. Antes da próxima solicitação do LLM no turno atual, o processador injeta 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 o turno for concluído antes que a mensagem de direcionamento seja processada, ela será movida automaticamente para a fila regular para o próximo turno.

Fila (modo de enfileiramento)

O enfileiramento armazena em buffer as mensagens a 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. Para Java, consulte o github/copilot-sdk-java repositório.

Como a fila funciona internamente

1. A mensagem é adicionada à sessão itemQueue como um QueuedItem.
2. Quando o turno atual for concluído e a sessão ficar ociosa, processQueuedItems() é executado.
3. Os itens são removidos da fila na ordem FIFO, cada mensagem dispara um turno de agente completo.
4. Se uma mensagem de direcionamento estava pendente quando o turno 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.

Combinar direcionamento e enfileiramento

Você pode usar os dois padrões juntos em uma única sessão. O direcionamento afeta o turno 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. Para Java, consulte o github/copilot-sdk-java repositório.

Escolher entre direcionamento e enfileiramento

Scenario	Padrão	Por que
O agente está indo pelo caminho errado	Direcção	Redireciona o turno atual sem perder o progresso
Você pensou em algo que o agente também deveria fazer	Enfileiramento	Não interrompe o trabalho atual; é executado 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

Criar uma interface de usuário com direcionamento e enfileiramento

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 sessão SDK do Copilot para direcionar e enfileirar 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.
  

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

•           **Manter as mensagens de direcionamento 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 direcionamento para fila** — se uma mensagem de direcionamento chegar após a conclusão do turno, ela será movida automaticamente para a fila. Crie sua interface do usuário para refletir essa transição.