orchestrator

Orchestrator

Orchestrator を使うと、現在のエージェントが他のエージェントを連携させられます。このスキルがインターフェースであり、その基盤で動作する orchestrator CLI が決定論的な制御プレーンです。

開始

1. このファイルと同じ場所にある PREFERENCES.md を読みます。User Preferences の下にあるコメント以外の内容だけを適用します。No preferences set. と書かれている場合は、状況に応じて判断します。
2. 現在のユーザーリクエストに明示的な指示がある場合は、保存済みの設定より優先します。
3. orchestrator --help で CLI を確認します。見つからず、npm が利用可能な場合は、npm install -g @backnotprop/orchestrator-cli でインストールします。
4. 現在のコマンド仕様を確認するには、orchestrator help --json --compact を実行します。
5. ランタイムが利用可能か不確かな場合は、orchestrator doctor --json --compact を実行します。runtimeSummary.availableIds にあるものだけを選びます。
6. 正確なモデル値を選ぶ前に、orchestrator models <runtime> --json --compact を実行します。

例に登場するからといって、ランタイムやモデルが存在すると決めつけないでください。

設定

設定は、呼び出し元のエージェントに対するルーティングポリシーです。以下を指定することがあります。

• 作業の種類ごとに使用するランタイムまたはモデル
• 使用するフォールバックとその順序
• 作業を複数のエージェントに分担させるか、1 つのエージェントに任せるか
• プロバイダーの利用枠を使い切った場合の対応

次の優先順位に従います。

1. 現在のリクエストに対する明示的な指示
2. PREFERENCES.md
3. ランタイムとプロバイダーの最新情報
4. 最善の判断

設定に記載された名称と、構成済みのランタイムおよびモデルの値との対応が明確な場合は、それらを対応付けます。その対応が重要であり、かつ不明確な場合は、ユーザーに一度だけ確認します。設定によって無関係な作業が許可されることはなく、タスクの安全性が損なわれることもありません。

利用状況に応じて設定が変わる場合は、orchestrator limits --json --compact を実行します。利用枠のデータを取得できない場合は、使い切ったのではなく不明として扱います。優先する選択肢が利用できない、使い切られている、または明らかに失敗する場合に限り、設定済みのフォールバックに従います。すべての選択肢を使い切った場合に一時停止するポリシーであれば、何も起動せず、ユーザーに通知します。

モデルの選択

ユーザーがモデルを指定していない場合は、--model を省略します。その場合、インストール済みのランタイムが現在のデフォルトを選びます。

正確なモデル値を渡す前に、次を実行します。

orchestrator models <runtime> --json --compact

• ユーザーのリクエストと設定のラベルを models[].id または models[].displayName と照合し、一致した id を --model に渡します。
• 「latest」または「best」は、返された defaultModel、alias、または router を使って解決します。バージョンのように見える名前を並べ替えたり、記憶を頼りに推測したりしないでください。
• partial は有用ではあるものの、不完全な情報として扱います。たとえば Claude Code は、正確なカタログではなく、現在のファミリーのエイリアスを公開しています。
• 情報を取得できない場合、リクエストで正確な選択が求められていなければ、--model を省略します。
• 利用できない正確なモデルを、現在のリクエストまたは設定でフォールバックが定義されていない限り、黙って別のモデルに置き換えないでください。
• 説明や機能が重要な場合は、返された fullModels.args を実行します。

モデル値はプロバイダー固有の値のまま変更せずに渡します。

1 つの作業を委任する

名前付きタスクを使い、返された ID を保持します。

orchestrator launch codex --name "inspect store" --json --compact --brief "Inspect the task store."
orchestrator read <task-id|prefix> --wait --json --compact

正確なローカルコマンドには shell を使います。レビュー、実装、調査、探索、分析には AI ランタイムを使います。

複数のエージェントに分担する

互いに独立した作業は、別々のタスクとして起動します。複数のタスクをまとめて開始する場合は、マニフェストを使います。

{
  "schemaVersion": 1,
  "tasks": [
    {
      "runtime": "claude-code",
      "name": "review tests",
      "task": "Find the highest-risk missing tests."
    },
    {
      "runtime": "grok",
      "name": "inspect api",
      "task": "Inspect the API boundary for bugs."
    }
  ]
}

orchestrator launch -f agents.json --json --compact --brief
orchestrator ps --json --compact --active --brief
orchestrator read <task-id> <task-id> --wait --json --compact

複数のタスク ID を 1 つの引用符付き文字列にまとめないでください。

Orchestrator に連携を任せる

ユーザーが Orchestrator 自体に委任の計画と管理を求めている場合は、親エージェントを使います。

orchestrator run --background --name "repo work" --json --compact "Delegate independent work, wait for every child, then synthesize the result."

簡易版の doctor の結果で parent.canRun: true が返された場合は、リクエストを parent.run.argsPrefix または parent.run.backgroundArgsPrefix に追加します。

作業を管理する

orchestrator ps --json --compact --active --brief
orchestrator ps -A --json --compact --active --brief
orchestrator watch <task-id> --agent-only --json
orchestrator read <task-id>... --wait --json --compact
orchestrator logs <task-id> --follow
orchestrator events <task-id> --agent-only --json --compact
orchestrator resume <task-id> --json --compact "Continue from the prior result."
orchestrator interrupt <task-id> --json --compact --reason "no longer needed"

• JSON で返される、移植性の高い commands.*.args と stop.args を優先してください。
• 返された引数配列は argv 配列として扱ってください。
• 次のステップで結果が必要な場合は、繰り返しポーリングする代わりに read --wait を使用してください。
• 正規化されたライブイベントには watch を、生のプロバイダー出力には logs を使用してください。
• プロバイダーのメタデータが保存され、ランタイムが再開に対応している場合に限り、完了したタスクを再開してください。
• 古くなった作業、重複した作業、不要になった作業を停止してください。
• 作業を引き渡す際は、タスク ID、ランタイム、モデル、ステータスを報告してください。

ランタイムに関する注意事項

組み込みの起動先には、claude-code、codex、codex-app-server、copilot、grok、pi、shell があります。設定で組み込みの起動先を無効にしたり、カスタムのランタイム ID を追加したりできます。

単発の Codex 作業には codex を使用してください。Codex の作業で繰り返しメッセージを送る必要がある場合、ネイティブの目標、指示の調整、または永続的なプロバイダースレッドが必要な場合は、codex-app-server --session を優先してください。

orchestrator launch codex-app-server --session --name "deep worker" --json --compact --brief
orchestrator send <task-id> --wait --json --compact "Inspect the current bottlenecks."
orchestrator goal start <task-id> --wait --json --compact "Improve the system."

ユーザーが上限を明示的に求めていない限り、目標のトークン予算は設定しないでください。

クリーンアップの範囲

特定のタスク ID を優先してください。ワークスペース全体のクリーンアップは、意図的に行う場合に限ってください。

orchestrator interrupt --active --json --compact --reason "cleanup"

全ワークスペースのクリーンアップは、ユーザーが明示的に要求した場合に限ってください。

orchestrator interrupt -A --active --yes --json --compact --reason "cleanup"