스티어링과 큐잉

일반적인 Laravel 애플리케이션의 흐름에서는 스티어링을 직접 사용하는 경우가 거의 없습니다. Laravel의 동기적 실행 패턴에서는 혜택을 받기 어려워 기본적으로 기본 큐잉 운영이 적합합니다.

에이전트가 처리 중에 메시지를 보내는 방법으로 스티어링과 큐잉의 2가지 패턴이 있습니다.

개요

send() / sendAndWait() / sendAndStream() / Copilot::run() 모두에 $mode 매개변수가 있습니다.

모드	동작
`"enqueue"`(기본값)	현재 턴이 완료된 후에 큐로 처리됨
`"immediate"`(스티어링)	현재 처리 중인 턴에 끼어들어 즉시 주입됨

스티어링(`"immediate"`)

에이전트가 처리 중인 턴에 직접 메시지를 주입합니다. 에이전트는 실시간으로 메시지를 받아 응답을 조정합니다. 진행 중인 작업을 중단하지 않고 방향을 수정하려는 경우에 사용합니다.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Contracts\CopilotSession;

Copilot::start(function (CopilotSession $session) {
    // 장시간 걸리는 태스크 시작
    $messageId = $session->send(prompt: 'Refactor the authentication module to use sessions');

    // 에이전트가 처리 중에 방향 수정
    $session->send(
        prompt: 'Actually, use JWT tokens instead of sessions',
        mode: 'immediate',
    );

    // 아이들 상태가 될 때까지 대기
    $response = $session->sendAndWait(prompt: 'Summarize what you did');
});

스티어링은 best-effort입니다. 에이전트가 이미 도구 호출을 커밋한 경우, 그 도구 호출 완료 후에 적용되지만 동일 턴 내에서 처리됩니다. 턴이 완료된 후에 스티어링 메시지가 도착한 경우 자동으로 큐로 이동합니다.

큐잉(`"enqueue"`)

메시지를 큐에 추가하고 현재 턴이 완료된 다음 순차적으로 처리합니다. 각 큐된 메시지는 독립된 턴으로 실행됩니다. $mode를 생략한 경우의 기본 동작입니다.

Copilot::start(function (CopilotSession $session) {
    // 최초 태스크 시작
    $session->send(prompt: 'Set up the project structure');

    // 에이전트가 처리 중에 후속 태스크를 큐에 추가
    $session->send(prompt: 'Add unit tests for the auth module', mode: 'enqueue');
    $session->send(prompt: 'Update the README with setup instructions', mode: 'enqueue');

    // 큐가 비워질 때까지 대기
});

Laravel에서의 실용적인 사고방식

Laravel에서는 Copilot::run()이나 sendAndWait()를 사용하는 동기적 패턴이 중심입니다. 이들은 메시지를 보내고 아이들 상태가 될 때까지 대기하므로 에이전트가 처리 중에 끼어들 기회가 없고, $mode는 실질적으로 의미가 없습니다.

// Copilot::run()은 내부적으로 sendAndWait()를 호출하기 때문에
// mode를 지정해도 의미가 없음

$response = Copilot::run(prompt: 'Tell me something about Laravel.');

// 세션 내에서도 sendAndWait()를 순서대로 호출할 뿐이라면 불필요
Copilot::start(function (CopilotSession $session) {
    $r1 = $session->sendAndWait(prompt: 'First task');
    $r2 = $session->sendAndWait(prompt: 'Second task');
});

스티어링("immediate")이 진가를 발휘하는 것은 send()로 비동기적으로 메시지를 보내면서 병렬로 다른 메시지로 진행 중인 턴에 개입할 수 있는 경우입니다. Laravel의 동기적 처리 흐름에서는 그 기회를 만들기 어렵기 때문에 기본적으로는 $mode를 지정하지 않고 기본 상태로 두는 것이 적절합니다.

어느 쪽을 사용해야 하는가

상황	패턴
에이전트가 잘못된 방향으로 진행 중	스티어링(`"immediate"`)
다음에 할 일이 떠올랐음	큐잉(`"enqueue"`)
여러 태스크를 순서대로 실행하고 싶음	큐잉(`"enqueue"`)
일반적인 Laravel 앱	기본값(`$mode` 불필요)

베스트 프랙티스

기본은 큐잉 — $mode를 생략(또는 "enqueue"를 지정)하는 것이 대부분의 경우에 적절합니다. 예측 가능한 동작을 합니다.
스티어링은 수정용으로 — "immediate"는 에이전트가 명백히 잘못된 것을 하고 있는 경우에 한정해서 사용합니다.
스티어링 메시지는 간결하게 — 현재 컨텍스트에서 이해할 수 있는 짧은 메시지로 합니다. 길고 복잡한 스티어링 메시지는 오히려 혼란을 초래합니다.
연속 스티어링은 피할 것 — 짧은 시간에 여러 스티어링을 보내면 턴의 품질이 저하될 가능성이 있습니다. 대폭적인 방향 전환이 필요한 경우에는 턴을 중단하고 처음부터 다시 하는 편이 적절한 경우도 있습니다.

참고

최신 정보는 GitHub 저장소를 참고하세요.