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

# Steering 與 Queueing

> 說明 Laravel Copilot SDK 的 steering(immediate)與 queueing(enqueue)差異,以及在 Laravel 中的實際使用建議。

## Steering 與 Queueing

<Info>
  在一般 Laravel 應用程式流程中,幾乎沒有直接使用 steering 的場景。Laravel 的同步執行模式難以受益於此,基本上採用預設的 queueing 運作即可。
</Info>

Agent 處理過程中傳送訊息有兩種模式:**Steering** 與 **Queueing**。

## 概觀

`send()` / `sendAndWait()` / `sendAndStream()` / `Copilot::run()` 皆有 `$mode` 參數。

| 模式                      | 動作                        |
| ----------------------- | ------------------------- |
| `"enqueue"`(預設)         | 在目前 turn 完成之後以 queue 形式處理 |
| `"immediate"`(steering) | 中斷目前正在處理的 turn 並立即注入      |

## Steering(`"immediate"`)

直接將訊息注入 Agent 目前正在處理的 turn。Agent 會即時接收訊息並調整回應。適合在不中斷正在進行的作業下修正方向。

```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');

    // 在 Agent 處理中修正方向
    $session->send(
        prompt: 'Actually, use JWT tokens instead of sessions',
        mode: 'immediate',
    );

    // 等待進入 idle 狀態
    $response = $session->sendAndWait(prompt: 'Summarize what you did');
});
```

<Warning>
  Steering 屬於 best-effort。若 Agent 已經送出工具呼叫,則會在該工具呼叫完成後才套用,並在同一個 turn 內處理。若 steering 訊息在 turn 結束後才到達,會被自動移至 queue。
</Warning>

## Queueing(`"enqueue"`)

將訊息加入 queue,並在目前 turn 完成後依序處理。每個 queue 中的訊息會作為獨立的 turn 執行。這是省略 `$mode` 時的預設動作。

```php theme={null}
Copilot::start(function (CopilotSession $session) {
    // 啟動最初的任務
    $session->send(prompt: 'Set up the project structure');

    // 在 Agent 處理中把後續任務加入 queue
    $session->send(prompt: 'Add unit tests for the auth module', mode: 'enqueue');
    $session->send(prompt: 'Update the README with setup instructions', mode: 'enqueue');

    // 等待 queue 空到
});
```

## Laravel 的實務考量

Laravel 主要使用 `Copilot::run()` 或 `sendAndWait()` 等同步模式。這些會傳送訊息並等待進入 idle,因此 **在 Agent 處理期間沒有機會插入,`$mode` 實質上沒有意義**。

```php theme={null}
// Copilot::run() 內部呼叫 sendAndWait(),
// 因此指定 mode 沒有意義

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

// 在 Session 中若只是依序呼叫 sendAndWait() 也不需要
Copilot::start(function (CopilotSession $session) {
    $r1 = $session->sendAndWait(prompt: 'First task');
    $r2 = $session->sendAndWait(prompt: 'Second task');
});
```

Steering(`"immediate"`)發揮作用的場景,是用 `send()` 非同步傳送訊息,同時另以其他訊息並行介入進行中的 turn。Laravel 的同步流程難以製造這種時機,**因此基本上不指定 `$mode`,維持預設即可**。

## 應該使用哪一個

| 情境            | 模式                      |
| ------------- | ----------------------- |
| Agent 走錯方向    | Steering(`"immediate"`) |
| 想到下一步要做的事     | Queueing(`"enqueue"`)   |
| 想依序執行多個任務     | Queueing(`"enqueue"`)   |
| 一般 Laravel 應用 | 預設(不需要 `$mode`)         |

## 最佳實踐

* **預設使用 queueing** — 省略 `$mode`(或指定 `"enqueue"`)在多數情境下都是合適的。行為可預測。
* **Steering 用於修正** — `"immediate"` 僅在 Agent 明顯做錯事時才使用。
* **Steering 訊息應簡潔** — 使用能於目前 context 理解的短訊息。長而複雜的 steering 訊息反而會造成混亂。
* **避免連續 steering** — 短時間內傳送多次 steering 可能導致 turn 品質下降。若需大幅轉向,直接中斷 turn 重新開始有時反而更適當。

## 參考

* [基本用法](/zh-TW/packages/laravel-copilot-sdk/bare-usage)
* [Streaming](/zh-TW/packages/laravel-copilot-sdk/streaming)
* [send-on](/zh-TW/packages/laravel-copilot-sdk/send-on)

<Info>
  最新資訊請參閱 [GitHub 儲存庫](https://github.com/invokable/laravel-copilot-sdk)。
</Info>


## Related topics

- [send() 與 on()](/zh-TW/packages/laravel-copilot-sdk/send-on.md)
- [Queue 與 Job](/zh-TW/queues.md)
- [授權（Gate 與 Policy）](/zh-TW/authorization.md)
- [Laravel 與 AI 開發](/zh-TW/ai.md)
- [tap() helper 與 Tappable trait](/zh-TW/advanced/tap.md)