코필로트 SDK에서 메시지 조정 및 큐 대기

활성 코필로트 SDK 세션으로 메시지를 보내 중간에 전환하거나 후속 작업을 대기열에 추가합니다.

누가 이 기능을 사용할 수 있나요?

GitHub 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 참조하세요.

조향의 내부 작동 원리

  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. 메시지는 세션의 itemQueue에 QueuedItem로 추가됩니다.
  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 참조

세션 API를 코필로트 SDK 사용하여 세션을 조정하고 큐에 대기할 수 있습니다.

메시지 옵션

언어분야유형기본값설명
Node.JSmode"enqueue" | "immediate""enqueue"메시지 배달 모드
파이썬modeLiteral["enqueue", "immediate"]"enqueue"메시지 배달 모드
이동Modestring"enqueue"메시지 배달 모드
.NETModestring?"enqueue"메시지 배달 모드

배송 모드

모드영향활성 턴 중유휴 상태
"enqueue"다음 턴을 위한 대기열FIFO 큐에서 대기새 턴을 즉시 시작합니다.
"immediate"현재 턴에 삽입다음 LLM 호출 전에 주입됨새 턴을 즉시 시작합니다.

참고

세션이 유휴 상태(처리되지 않음)이면 두 모드가 동일하게 작동합니다. 메시지가 즉시 새 턴을 시작합니다.

모범 사례

  •         **기본적으로 대기열에 추가됨**—대부분의 메시지에 `"enqueue"`을 사용하거나 `mode`을 생략합니다. 예측 가능하며 진행 중인 작업을 방해할 위험이 없습니다.

  •         **조정 작업을 위한 조향 예약** - 에이전트가 잘못된 작업을 적극적으로 하고 있을 때, 그 작업이 더 진행하기 전에 리디렉션해야 할 때 `"immediate"`을 사용하십시오.

  •         **조향 메시지를 간결하게 유지**합니다. 에이전트는 과정 수정 사항을 신속하게 이해해야 합니다. 길고 복잡한 조향 메시지는 현재 컨텍스트를 혼동할 수 있습니다.

  •         **과도하게 조종하지 마세요**. 여러 빠른 스티어링 메시지는 턴 품질을 저하시킬 수 있습니다. 방향을 크게 변경해야 하는 경우 턴을 중단하고 새로 시작하는 것이 좋습니다.

  •         **UI에 큐 상태 표시** - 사용자가 보류 중인 내용을 알 수 있도록 큐에 대기 중인 메시지 수를 표시합니다. 유휴 상태 이벤트를 수신 대기하여 화면을 초기화합니다.

  •         **조향-대기열로 전환 처리** - 턴이 완료된 후 조향 메시지가 도착하면 자동으로 대기열로 이동합니다. 이 전환을 반영하도록 UI를 디자인합니다.