---
read_when:
    - 自動返信の実行や並行性を変更する場合
summary: 受信自動返信実行を直列化するコマンドキュー設計
title: コマンドキュー
x-i18n:
    generated_at: "2026-04-25T13:45:59Z"
    model: gpt-5.4
    provider: openai
    source_hash: 0c027be3e9a67f91a49c5d4d69fa8191d3e7651265a152c4723b10062b339f2a
    source_path: concepts/queue.md
    workflow: 15
---

すべての受信チャネルの自動返信実行は、小さなインプロセスキューを通じて直列化されます。これにより、複数のエージェント実行が衝突するのを防ぎつつ、セッション間では安全な並列性を維持できます。

## 理由

- 自動返信実行は高コストになり得るため（LLM 呼び出し）、複数の受信メッセージが近いタイミングで到着すると衝突する可能性があります。
- 直列化により、共有リソース（セッションファイル、ログ、CLI stdin）の競合を避けられ、上流のレート制限に達する可能性も下がります。

## 仕組み

- レーン対応の FIFO キューが、各レーンを設定可能な並行数上限で排出します（未設定レーンのデフォルトは 1、main のデフォルトは 4、subagent は 8）。
- `runEmbeddedPiAgent` は **セッションキー**（レーン `session:<key>`）単位でキューに入れ、セッションごとに同時実行が1つだけになることを保証します。
- 各セッション実行はその後 **グローバルレーン**（デフォルトでは `main`）にキューされ、全体の並列性は `agents.defaults.maxConcurrent` で上限が決まります。
- 詳細ログが有効な場合、キューされた実行は、開始までに約2秒以上待ったときに短い通知を出します。
- タイピングインジケーターは、順番待ち中でもユーザー体験が変わらないよう、対応チャネルではキュー投入時に即座に発火します。

## キューモード（チャネルごと）

受信メッセージは、現在の実行をステアしたり、フォローアップターンを待ったり、その両方を行えます:

- `steer`: 現在の実行に即座に注入します（次の Tool 境界の後に保留中の Tool 呼び出しをキャンセルします）。ストリーミングでない場合は `followup` にフォールバックします。
- `followup`: 現在の実行が終了した後の次のエージェントターンに向けてキューします。
- `collect`: キューされたすべてのメッセージを **1回の** フォローアップターンにまとめます（デフォルト）。メッセージの対象チャネル/スレッドが異なる場合は、ルーティングを維持するため個別に排出されます。
- `steer-backlog`（別名 `steer+backlog`）: 今すぐステアし、**かつ** そのメッセージをフォローアップターン用に保持します。
- `interrupt`（レガシー）: そのセッションのアクティブ実行を中断し、最新メッセージを実行します。
- `queue`（レガシーエイリアス）: `steer` と同じです。

steer-backlog は、ステアされた実行の後にフォローアップ応答が返る可能性があることを意味するため、
ストリーミング画面では重複に見える場合があります。受信メッセージごとに
1つの応答を望むなら、`collect` または `steer` を推奨します。
スタンドアロンコマンドとして `/queue collect` を送信する（セッションごと）か、`messages.queue.byChannel.discord: "collect"` を設定してください。

デフォルト（config で未設定の場合）:

- すべての画面 → `collect`

`messages.queue` でグローバルまたはチャネルごとに設定します:

```json5
{
  messages: {
    queue: {
      mode: "collect",
      debounceMs: 1000,
      cap: 20,
      drop: "summarize",
      byChannel: { discord: "collect" },
    },
  },
}
```

## キューオプション

オプションは `followup`、`collect`、`steer-backlog` に適用されます（また、`steer` が `followup` にフォールバックした場合にも適用されます）:

- `debounceMs`: フォローアップターンを開始する前に静穏状態を待ちます（「continue, continue」を防ぎます）。
- `cap`: セッションごとの最大キューメッセージ数。
- `drop`: オーバーフローポリシー（`old`、`new`、`summarize`）。

summarize はドロップされたメッセージの短い箇条書きを保持し、それを合成フォローアッププロンプトとして注入します。
デフォルト: `debounceMs: 1000`、`cap: 20`、`drop: summarize`。

## セッションごとの上書き

- スタンドアロンコマンドとして `/queue <mode>` を送信すると、現在のセッション用にそのモードが保存されます。
- オプションは組み合わせ可能です: `/queue collect debounce:2s cap:25 drop:summarize`
- `/queue default` または `/queue reset` でセッション上書きをクリアします。

## スコープと保証

- Gateway 返信パイプラインを使用するすべての受信チャネルの自動返信エージェント実行に適用されます（WhatsApp web、Telegram、Slack、Discord、Signal、iMessage、webchat など）。
- デフォルトレーン（`main`）は、受信 + メイン Heartbeat 用のプロセス全体スコープです。複数セッションを並列に許可するには `agents.defaults.maxConcurrent` を設定してください。
- 追加レーン（例: `cron`、`subagent`）が存在する場合があり、バックグラウンドジョブは受信返信をブロックせずに並列実行できます。これらの切り離された実行は [background tasks](/ja-JP/automation/tasks) として追跡されます。
- セッションごとのレーンにより、特定のセッションに対して同時に1つのエージェント実行だけが触れることが保証されます。
- 外部依存関係やバックグラウンドワーカースレッドは不要で、純粋な TypeScript + promises です。

## トラブルシューティング

- コマンドが停止しているように見える場合は、詳細ログを有効にし、「queued for …ms」という行を探してキューが排出されていることを確認してください。
- キューの深さが必要な場合は、詳細ログを有効にしてキュー時間の行を確認してください。

## 関連

- [Session management](/ja-JP/concepts/session)
- [Retry policy](/ja-JP/concepts/retry)
