> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 스티어링과 큐잉

> Laravel Copilot SDK의 steering(immediate)과 queueing(enqueue)의 차이와 Laravel에서의 실용적인 사용 구분을 설명합니다.

## 스티어링과 큐잉

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

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

## 개요

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

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

## 스티어링(`"immediate"`)

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

```php theme={null}
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');
});
```

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

## 큐잉(`"enqueue"`)

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

```php theme={null}
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`는 실질적으로 의미가 없습니다**.

```php theme={null}
// 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"`는 에이전트가 명백히 잘못된 것을 하고 있는 경우에 한정해서 사용합니다.
* **스티어링 메시지는 간결하게** — 현재 컨텍스트에서 이해할 수 있는 짧은 메시지로 합니다. 길고 복잡한 스티어링 메시지는 오히려 혼란을 초래합니다.
* **연속 스티어링은 피할 것** — 짧은 시간에 여러 스티어링을 보내면 턴의 품질이 저하될 가능성이 있습니다. 대폭적인 방향 전환이 필요한 경우에는 턴을 중단하고 처음부터 다시 하는 편이 적절한 경우도 있습니다.

## 참고

* [기본 사용법](/ko/packages/laravel-copilot-sdk/bare-usage)
* [Streaming](/ko/packages/laravel-copilot-sdk/streaming)
* [send-on](/ko/packages/laravel-copilot-sdk/send-on)

<Info>
  최신 정보는 [GitHub 저장소](https://github.com/invokable/laravel-copilot-sdk)를 참고하세요.
</Info>


## Related topics

- [Laravel Nightwatch 입문](/ko/blog/nightwatch-introduction.md)
- [알림 채널 - LINE SDK for Laravel](/ko/packages/laravel-line-sdk/notification.md)
- [이벤트와 리스너](/ko/events.md)
- [Laravel Console Starter](/ko/packages/laravel-console-starter/index.md)
- [Pest PHP로 시작하는 Laravel 테스트](/ko/blog/pest-introduction.md)