Gestión y puesta en cola de mensajes en el SDK de Copilot

          SDK de Copilot actualmente está en Versión preliminar técnica. La funcionalidad y la disponibilidad están sujetas a cambios.

Dos patrones de interacción permiten a los usuarios enviar mensajes mientras el agente ya está funcionando: redirección redirige al agente a mitad del turno, y poner en cola los mensajes para el procesamiento secuencial (primero en entrar, primero en salir (FIFO)) tras completar el turno actual.

Cuando una sesión procesa activamente un turno, los mensajes entrantes se pueden entregar en uno de los dos modos a través del mode campo en MessageOptions:

Modo	Comportamiento	Caso de uso

          `"immediate"` (dirección) | Insertado en el turno LLM **actual** | De hecho, no cree ese archivo, sino que use un enfoque diferente. |

| "enqueue" (puesta en cola) | Puesto en cola y procesado después de que finalice el turno actual | "Después de esto, también corrija las pruebas" |

Para obtener un diagrama de secuencia del flujo de dirección y cola, consulte el github/copilot-sdk repositorio.

Dirección (modo inmediato)

El sistema de control envía un mensaje que se inserta directamente en el turno actual del agente. El agente ve el mensaje en tiempo real y ajusta su respuesta en consecuencia, útil para corregir el curso sin anular el 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 obtener ejemplos en Python, Go y .NET, consulte el github/copilot-sdk repositorio.

Funcionamiento interno del sistema de dirección

1. El mensaje se añade a la cola de ejecución del entorno de ImmediatePromptProcessor.
2. Antes de la siguiente solicitud LLM dentro del turno actual, el procesador inserta el mensaje en la conversación.
3. El agente ve el mensaje de dirección como un nuevo mensaje de usuario y ajusta su respuesta.
4. Si el giro se completa antes de procesar el mensaje de control, este se mueve automáticamente a la cola normal para el siguiente ciclo.

Puesta en cola (modo de puesta en cola)

Poner en cola los mensajes que se van a procesar secuencialmente después de que finalice el turno actual. Cada mensaje en cola inicia su propio turno completo. Este es el modo predeterminado: si omite mode, el SDK usa "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 obtener ejemplos en Python, Go y .NET, consulte el github/copilot-sdk repositorio.

Funcionamiento interno del sistema de colas

1. El mensaje se agrega a la sesión itemQueue como un QueuedItem.
2. Cuando se completa el turno actual y la sesión deja de estar inactiva, processQueuedItems() se ejecuta.
3. Los elementos se quitan en orden FIFO: cada mensaje desencadena un ciclo completo de acción del agente.
4. Si un mensaje de dirección estaba pendiente cuando finalizó el turno, se mueve al frente de la cola.
5. El procesamiento continúa hasta que la cola está vacía y la sesión emite un evento inactivo.

Combinación de encaminamiento y gestión de colas

Puede usar ambos patrones juntos en una sola sesión. La dirección afecta al turno actual mientras los mensajes en cola esperan sus propios turnos:

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 obtener un ejemplo en Python, consulte el github/copilot-sdk repositorio.

Elección entre la dirección y la cola

Escenario	Modelo	Por qué
El agente va por la ruta incorrecta	Dirección	Redirige el turno actual sin perder el progreso.
Pensaste en algo que el agente también debería hacer	Colocando en cola	No interrumpe el trabajo actual; se ejecuta a continuación
El agente está a punto de cometer un error	Dirección	Interviene antes de cometer el error
Quiere encadenar varias tareas	Colocando en cola	La ordenación de FIFO garantiza una ejecución predecible
Quiere agregar contexto a la tarea actual.	Dirección	El agente lo incorpora en su razonamiento actual
Usted quiere agrupar solicitudes no relacionadas por lotes	Colocando en cola	Cada uno obtiene su propio ciclo completo con contexto claro

Creación de una interfaz de usuario con control y gestión de colas

Este es un patrón para crear una interfaz de usuario interactiva que admita ambos 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
    }
}

Referencia de las API

Puede utilizar la API de sesión SDK de Copilot para gestionar y poner en cola las sesiones.

Opciones de Mensaje

Language	Campo	Tipo	Predeterminado	Descripción
Node.js.	mode	"enqueue" | "immediate"	"enqueue"	Modo de entrega de mensajes
Python	mode	Literal["enqueue", "immediate"]	"enqueue"	Modo de entrega de mensajes
Go	Mode	string	"enqueue"	Modo de entrega de mensajes
.NET	Mode	string?	"enqueue"	Modo de entrega de mensajes

Modos de entrega

Modo	Efecto	Durante el turno activo	Durante el tiempo de inactividad
"enqueue"	Cola para el próximo turno	Espera en la cola FIFO	Inicia un nuevo turno inmediatamente
"immediate"	Insertar en el turno actual	Insertado antes de la siguiente llamada LLM	Inicia un nuevo turno inmediatamente

procedimientos recomendados

•         **Valor predeterminado para poner en cola**: use `"enqueue"` (o omita `mode`) para la mayoría de los mensajes. Es predecible y no corre el riesgo de interrumpir el trabajo en curso.
  

•         **Reserva la dirección para correcciones**: Use `"immediate"` cuando el agente esté haciendo activamente lo incorrecto y usted necesite redirigirlo antes de que vaya más allá.
  

•         **Mantener los mensajes de dirección concisos**: el agente debe comprender rápidamente la corrección del curso. Los mensajes de dirección complejos largos pueden confundir el contexto actual.
  

•         **No sobregire**—varios mensajes rápidos de dirección pueden degradar la calidad del giro. Si necesita cambiar significativamente la dirección, considere la posibilidad de anular el turno e iniciarlo de nuevo.
  

•         **Mostrar el estado de la cola en la interfaz de usuario**: muestra el número de mensajes en cola para que los usuarios sepan lo que está pendiente. Monitoree los eventos inactivos para limpiar la pantalla.
  

•         **Manejar el mecanismo de encaminamiento a cola**: si llega un mensaje de encaminamiento después de que el turno se complete, se mueve automáticamente a la cola. Diseñe la interfaz de usuario para reflejar esta transición.