在 Copilot SDK 中引导和排队消息

注意

          Copilot SDK 当前处于 技术预览版. 功能和可用性可能会发生更改。

两种交互模式允许用户在代理正常工作时发送消息：引导可以中途重定向代理，排队则将消息缓冲，以便在当前轮次完成后按顺序（先入先出，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 存储库。

队列在内部的工作原理

消息作为QueuedItem添加到会话的itemQueue中。
当当前轮次完成并且会话变为空闲时， 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 排序可确保可预测的执行
你想要将上下文添加到当前任务	转向	代理将其合并到其当前推理中
你想要对不相关的请求进行批处理	队列	每个实例都获得其完整的轮次，并具有清晰的上下文

使用排队和转向构建用户界面

下面是用于生成支持这两种模式的交互式 UI 的模式：

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 参考

可以使用 Copilot SDK 会话 API 来引导和队列会话。

消息选项

语言	领域	类型	默认	说明
Node.js	`mode`	`"enqueue" \| "immediate"`	`"enqueue"`	消息传送模式
Python	`mode`	`Literal["enqueue", "immediate"]`	`"enqueue"`	消息传送模式
Go	`Mode`	`string`	`"enqueue"`	消息传送模式
.NET	`Mode`	`string?`	`"enqueue"`	消息传送模式

传递模式

模式	Effect	在活动回合期间	空闲期间
`"enqueue"`	排队等待下一轮	在 FIFO 队列中等待	立即启动新轮次
`"immediate"`	注入到当前回合	在下一次 LLM 调用之前注入	立即启动新轮次

注意

当会话处于空闲状态（未处理）时，这两种模式的行为方式相同 — 消息会立即启动新的轮次。

最佳做法

        **默认为排队** - 对大多数消息使用 `"enqueue"` （或省略 `mode`）。 这是可预测的，不会有中断正在进行的工作的风险。

        **保留更正指导** - 当代理正在积极执行错误操作时使用 `"immediate"` ，并且你需要在操作进一步之前对其进行重定向。

        **保持引导消息简洁** — 代理需要快速了解方向调整。 长而复杂的转向消息可能会混淆当前上下文。

        **不要过度转向** - 多次快速转向可能会降低驾驶表现。 如果需要显著更改方向，请考虑中止轮次并重新开始。

        **在 UI 中显示队列状态** - 显示排队消息数，以便用户知道挂起的内容。 监听空闲事件以清除显示。

        **处理引导到队列的回退** — 如果引导消息在操作完成后到达，它将自动移动到队列。 设计 UI 以反映此转换。

谁可以使用此功能？

在本文中