Сообщения управления и очереди в SDK Copilot

Примечание.

          Второй пилот SDK в настоящее время находится в Technical Preview. Функциональность и доступность могут меняться.

Два паттерна взаимодействия позволяют пользователям отправлять сообщения, пока агент уже работает: управление перенаправляет агента в середине хода, а очередь буферных сообщений для последовательной обработки (первый вошёл — первый ушёл (FIFO)) после завершения текущего хода.

Когда сессия активно обрабатывает ход, входящие сообщения могут доставляться в одном из двух режимов через mode поле на MessageOptions:

Режим	Поведение	Сценарий использования

          `"immediate"` (рулевое управление) | Вводится в **текущий** ход LLM | «На самом деле, не создавай этот файл — используй другой подход» |

| "enqueue" (очередь) | Поставлен в очередь и обработан после окончания текущего хода | «После этого тоже починьте тесты» |

Для диаграммы последовательности потока управления и очереди см. репозиторийgithub/copilot-sdk.

Рулевое управление (режим мгновенности)

Управление посылает сообщение, которое вводится непосредственно в текущий оборот агента. Агент видит сообщение в реальном времени и корректирует его ответ — полезно для коррекции курса без прерывания хода.

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

Примеры в Python, Go и .NET см. репозиторийgithub/copilot-sdk.

Как работает внутреннее управление

Сообщение добавляется в очередь ImmediatePromptProcessor среды выполнения.
Перед следующим запросом LLM в текущем ходу процессор вводит сообщение в разговор.
Агент воспринимает сообщение управления как сообщение нового пользователя и корректирует его ответ.
Если поворот завершается до обработки сообщения о рулевом управлении, оно автоматически переводится в обычную очередь на следующий поворот.

Примечание.

Сообщения управления — это лучшее усилие в текущем ходу. Если агент уже выполнил вызов инструмента, управление вступает в силу после завершения этого вызова, но всё ещё в пределах того же хода.

Очередь (режим очереди)

Очередь буферизирует сообщения для последовательной обработки после завершения текущего хода. Каждое очередное сообщение начинает свой полный ход. Это режим по умолчанию — если пропустить mode, SDK использует "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

Примеры в Python, Go и .NET см. репозиторийgithub/copilot-sdk.

Как работает внутренняя очередь

Сообщение добавляется в сессию itemQueue в виде QueuedItem.
Когда текущий ход заканчивается и сессия становится бездействующей, processQueuedItems() он запускается.
Элементы выставляются из очереди в порядке FIFO — каждое сообщение запускает полный агентный ход.
Если сообщение о управлении было ожидающим на момент окончания поворота, оно переносится в начало очереди.
Обработка продолжается до тех пор, пока очередь не опустеет, после чего сессия выпускает событие простоя.

Совмещение рулевого управления и очереди

Вы можете использовать оба узора вместе за одну сессию. Управление влияет на текущий ход, пока сообщения в очереди ждут своих ходов:

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

Для примера в Python см. github/copilot-sdk репозиторий.

Выбор между рулём и очередью

Сценарий	Рисунок	Почему
Агент идёт по неправильному пути	Рулевое управление	Перенаправляет текущий ход без потери прогресса
Вы придумали, что агент тоже должен сделать	Поставлено в очередь	Не мешает текущей работе; Следующие сезоны
Агент вот-вот совершит ошибку	Рулевое управление	Вмешивается до совершения ошибки
Нужно объединять несколько задач в цепочку	Поставлено в очередь	Порядок FIFO обеспечивает предсказуемое выполнение
Вы хотите добавить контекст к текущей задаче	Рулевое управление	Агент включает это в свою текущую логику
Вы хотите делать пакетные несвязанные запросы	Поставлено в очередь	Каждый из них получает свой полный ход с чистым контекстом

Создание интерфейса с управлением и очередями

Вот схема создания интерактивного интерфейса, поддерживающего оба режима:

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
    }
}

Справочник по API

Вы можете использовать Второй пилот SDK API сессий для управления и очереди сессий.

MessageOptions

Язык	Поле	Тип	По умолчанию	Описание
Node.js	`mode`	`"enqueue" \| "immediate"`	`"enqueue"`	Режим доставки сообщений
Python	`mode`	`Literal["enqueue", "immediate"]`	`"enqueue"`	Режим доставки сообщений
Вперед	`Mode`	`string`	`"enqueue"`	Режим доставки сообщений
.NET	`Mode`	`string?`	`"enqueue"`	Режим доставки сообщений

Режимы доставки

Режим	Эффект	Во время активного поворота	Во время простоя
`"enqueue"`	Очередь на следующий ход	Ожидания в очереди FIFO	Сразу начинает новый ход
`"immediate"`	Впрыск в ход тока	Введено перед следующим вызовом LLM	Сразу начинает новый ход

Примечание.

Когда сессия находится в режиме простоя (не обрабатывается), оба режима ведут себя одинаково — сообщение сразу начинает новый ход.

Лучшие практики

        **По умолчанию очередь** — используйте `"enqueue"` (или опускайте `mode`) для большинства сообщений. Это предсказуемо и не мешает работе в процессе.

        **Резервируйте рулевое управление для исправлений** — используйте `"immediate"` тогда, когда агент активно делает что-то не так, и вам нужно перенаправить его, прежде чем он пойдёт дальше.

        **Держите сообщения управления лаконичными** — агенту нужно быстро понять корректировку курса. Длинные, сложные сообщения управления могут запутать текущий контекст.

        **Не** переусердствуйте — несколько сообщений о быстром рулевом управлении могут ухудшить качество поворота. Если нужно сильно изменить направление, подумайте о том, чтобы прервать поворот и начать с чистого листа.

        **Покажите состояние очереди в интерфейсе** — откажите количество поставленных в очередь сообщений, чтобы пользователи знали, что ожидается. Прислушивайтесь к событиям простоя, чтобы очистить дисплей.

        **Обрабатывайте запасной вариант руления в очередь** — если после завершения поворота приходит сообщение о рулевом управлении, оно автоматически переносится в очередь. Спроектируйте свой интерфейс так, чтобы отражать этот переход.

Сообщения управления и очереди в SDK Copilot

Кто может использовать эту функцию?

В этой статье

Рулевое управление (режим мгновенности)

Как работает внутреннее управление

Очередь (режим очереди)

Как работает внутренняя очередь

Совмещение рулевого управления и очереди

Выбор между рулём и очередью

Создание интерфейса с управлением и очередями

Справочник по API

MessageOptions

Режимы доставки

Лучшие практики