在 Copilot SDK 中对消息进行引导和排队

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

两种交互模式允许用户在代理正常工作时发送消息：引导 可以中途重定向代理，排队 则将消息缓冲，以便在当前轮次完成后按顺序（先入先出，FIFO）处理。

当会话正在主动处理一个轮次时，传入消息可以通过 MessageOptions 上的 mode 字段以两种方式之一进行传递。

模式	行为	用例

          `"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 存储库。

内部转向工作原理

1. 该消息将添加到运行时的 ImmediatePromptProcessor 队列中。
2. 在当前轮次中的下一个 LLM 请求之前，处理器会将消息注入到会话中。
3. 代理将引导消息视为新用户消息并调整其响应。
4. 如果在处理引导消息之前轮次已完成，则该消息会自动移到下一个轮次的常规队列中。

排队（入队模式）

排队操作将缓冲消息，以便在当前轮次结束后按顺序处理。 每个排队的消息都会启动其自己的完整轮次。 这是默认模式 - 如果省略 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 存储库。

排队的内部工作原理

1. 消息作为 QueuedItem 添加到会话的 itemQueue 中。
2. 当当前轮次完成并且会话变为空闲时， processQueuedItems() 将运行。
3. 项目按 FIFO 顺序出队，每个消息都会触发一个完整的代理操作周期。
4. 如果轮次结束时有引导信息待处理，则将其移到队列前面。
5. 处理将持续进行，直至队列为空，当队列为空时，会话将触发一个空闲事件。

组合转向和排队

可以在单个会话中同时使用这两种模式。 当排队的消息等待自己的轮次时，引导操作会影响当前轮次：

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

下面是用于生成支持这两种模式的交互式 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 以反映此转换。