サブエージェント

サブエージェントは、既存のエージェント実行から生成されるバックグラウンドエージェント実行です。独自のセッション（agent:<agentId>:subagent:<uuid>）で実行され、完了すると、リクエスターチャットチャネルに結果をアナウンスします。

スラッシュコマンド

現在のセッションのサブエージェント実行を検査または制御するには、/subagentsを使用します:

  • /subagents list
  • /subagents stop <id|#|all>
  • /subagents log <id|#> [limit] [tools]
  • /subagents info <id|#>
  • /subagents send <id|#> <message>

/subagents infoは、実行メタデータ（ステータス、タイムスタンプ、セッションID、トランスクリプトパス、クリーンアップ）を表示します。

主な目標:

  • メイン実行をブロックせずに「リサーチ/長いタスク/遅いツール」作業を並列化します。
  • デフォルトでサブエージェントを分離します（セッション分離 + オプションのサンドボックス化）。
  • ツールサーフェスを誤用しにくくします: サブエージェントはデフォルトでセッションツールを取得しません。
  • ネストされたファンアウトを回避します: サブエージェントはサブエージェントを生成できません。

コストに関する注意事項: 各サブエージェントには独自のコンテキストとトークン使用量があります。ヘビーまたは反復的なタスクの場合は、サブエージェントに安価なモデルを設定し、メインエージェントを高品質なモデルに保ちます。これは、agents.defaults.subagents.modelまたはエージェントごとのオーバーライドを介して設定できます。

ツール

sessions_spawnを使用します:

  • サブエージェント実行を開始します（deliver: false、グローバルレーン: subagent）
  • 次に、アナウンスステップを実行し、リクエスターチャットチャネルにアナウンス返信を投稿します
  • デフォルトモデル: agents.defaults.subagents.model（またはエージェントごとのagents.list[].subagents.model）を設定しない限り、呼び出し元を継承します。明示的なsessions_spawn.modelはまだ優先されます。

ツールパラメータ:

  • task（必須）
  • label?（オプション）
  • agentId?（オプション。許可されている場合、別のエージェントIDの下で生成）
  • model?（オプション。サブエージェントモデルをオーバーライドします。無効な値はスキップされ、サブエージェントはデフォルトモデルで実行され、ツール結果に警告が表示されます）
  • thinking?（オプション。サブエージェント実行の思考レベルをオーバーライドします）
  • runTimeoutSeconds?（デフォルト0。設定されている場合、サブエージェント実行はN秒後に中止されます）
  • cleanup?（delete|keep、デフォルトkeep）

許可リスト:

  • agents.list[].subagents.allowAgents: agentIdを介してターゲットにできるエージェントIDのリスト（任意を許可するには["*"]）。デフォルト: リクエスターエージェントのみ。

発見:

  • sessions_spawnに現在許可されているエージェントIDを確認するには、agents_listを使用します。

自動アーカイブ:

  • サブエージェントセッションは、agents.defaults.subagents.archiveAfterMinutes（デフォルト: 60）後に自動的にアーカイブされます。
  • アーカイブはsessions.deleteを使用し、トランスクリプトを*.deleted.<timestamp>に名前変更します（同じフォルダー）。
  • cleanup: "delete"は、アナウンス後すぐにアーカイブします（名前変更を介してトランスクリプトを保持します）。
  • 自動アーカイブはベストエフォートです。ゲートウェイが再起動すると、保留中のタイマーは失われます。
  • runTimeoutSecondsは自動アーカイブしません。実行を停止するだけです。セッションは自動アーカイブまで残ります。

認証

サブエージェント認証は、セッションタイプではなくエージェントIDによって解決されます:

  • サブエージェントセッションキーはagent:<agentId>:subagent:<uuid>です。
  • 認証ストアは、そのエージェントのagentDirからロードされます。
  • メインエージェントの認証プロファイルは、フォールバックとしてマージされます。エージェントプロファイルは、競合時にメインプロファイルをオーバーライドします。

注意: マージは追加的なので、メインプロファイルは常にフォールバックとして利用可能です。エージェントごとの完全に分離された認証はまだサポートされていません。

アナウンス

サブエージェントは、アナウンスステップを介して報告します:

  • アナウンスステップは、サブエージェントセッション内で実行されます（リクエスターセッションではありません）。
  • サブエージェントが正確にANNOUNCE_SKIPと返信した場合、何も投稿されません。
  • それ以外の場合、アナウンス返信は、フォローアップagent呼び出し（deliver=true）を介してリクエスターチャットチャネルに投稿されます。
  • アナウンス返信は、利用可能な場合、スレッド/トピックルーティングを保持します（Slackスレッド、Telegramトピック、Matrixスレッド）。
  • アナウンスメッセージは、安定したテンプレートに正規化されます:
    • Status: 実行結果から派生（success、error、timeout、またはunknown）。
    • Result: アナウンスステップからのサマリーコンテンツ（欠落している場合は(not available)）。
    • Notes: エラーの詳細とその他の有用なコンテキスト。
  • Statusは、モデル出力から推測されません。ランタイム結果シグナルから取得されます。

アナウンスペイロードには、最後に統計行が含まれます（ラップされている場合でも）:

  • ランタイム（例: runtime 5m12s）
  • トークン使用量（入力/出力/合計）
  • モデル価格が設定されている場合の推定コスト（models.providers.*.models[].cost）
  • sessionKey、sessionId、トランスクリプトパス（メインエージェントがsessions_historyを介して履歴をフェッチしたり、ディスク上のファイルを検査できるように）

ツールポリシー（サブエージェントツール）

デフォルトでは、サブエージェントはセッションツールを除くすべてのツールを取得します:

  • sessions_list
  • sessions_history
  • sessions_send
  • sessions_spawn

設定を介してオーバーライドします:

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 1
      }
    }
  },
  tools: {
    subagents: {
      tools: {
        // denyが優先されます
        deny: ["gateway", "cron"],
        // allowが設定されている場合、許可のみになります（denyはまだ優先されます）
        // allow: ["read", "exec", "process"]
      }
    }
  }
}

並行性

サブエージェントは、専用のインプロセスキューレーンを使用します:

  • レーン名: subagent
  • 並行性: agents.defaults.subagents.maxConcurrent（デフォルト8）

停止

  • リクエスターチャットで/stopを送信すると、リクエスターセッションが中止され、それから生成されたアクティブなサブエージェント実行が停止します。

制限事項

  • サブエージェントアナウンスはベストエフォートです。ゲートウェイが再起動すると、保留中の「アナウンスバック」作業は失われます。
  • サブエージェントは、依然として同じゲートウェイプロセスリソースを共有します。maxConcurrentを安全弁として扱ってください。
  • sessions_spawnは常に非ブロッキングです: すぐに{ status: "accepted", runId, childSessionKey }を返します。
  • サブエージェントコンテキストは、AGENTS.md + TOOLS.mdのみを注入します（SOUL.md、IDENTITY.md、USER.md、HEARTBEAT.md、またはBOOTSTRAP.mdはありません）。
← ドキュメントに戻る