AIチュートリアル

Sprix SAGE RouterでAIエージェントのタスクをルーティング

Sprix SAGE Routerのインストール方法、エージェントとタスクの依存関係のモデル化、実行可能なルートの選択、割り当ての確認、実行結果を活用した今後の意思決定の改善方法を解説します。さらに、A2A統合、制約、ベンチマーク、この初期段階のリサーチプレビューに関する実践的なガイダンスも紹介します。

2026年8月20日約17分で読了

Sprix SAGE Routerとは？

Sprix SAGE Routerは、作業開始後にAIエージェントがタスクをどのように実行すべきかを判断するための、オープンソースのPython研究プロジェクトです。SAGEはState-Aware Graph Exchangeの略です。エージェントの発見とタスク実行の間で動作し、現在の進捗、能力、権限、コスト、レイテンシ、依存関係、コンテキスト転送による損失を考慮しながら、実行可能なエージェント構成を選択します。

ルーターは、次の3つの実行モードを比較します。

SELF：能力と蓄積されたコンテキストが十分な場合、現在のエージェントが単独で続行します。
COLLABORATE：現在のエージェントが主体性を保持し、補完的なエージェントが不足している要件をカバーします。
HANDOFF：コンテキスト転送のコストを上回る専門性の優位性がある場合、別のエージェントが完全に引き継ぎます。

SAGEはAgent2Agentプロトコルの上位レイヤーに配置されるよう設計されています。A2Aは、相互運用可能なAgent Card、タスク、メッセージ、アーティファクト、認証、トランスポートを定義します。SAGEが扱うのは別の問いです。つまり、どの適格な構成が、どのモードで、なぜタスクを実行すべきかという問いです。

現在のプロトタイプはルーティングの判断を返します。エージェントにタスクを送信する機能はないため、選択されたルートの実行はA2Aクライアントまたは別の実行レイヤーが担う必要があります。

主なルーティング機能

SAGEは、ルーティング、スケジューリング、オンライン学習を、検証可能な1つの意思決定プロセスに統合します。主な機能は次のとおりです。

3モードルーティング：SELF、COLLABORATE、HANDOFFの候補を同じ効用目的のもとで競わせます。
進捗を考慮した再計画：蓄積された進捗、実行中のエージェント、失敗、完了したタスクノード、転送可能なコンテキストにより、切り替えの価値があるかどうかを判断できます。
補完的なチーム選択：高順位のエージェントを重複して集めるのではなく、不足要件のカバー範囲を増やすチームを評価します。
コンテキスト別の信頼性：信頼性を単一の全体的な評判スコアに集約せず、エージェントと要件の組み合わせごとに学習します。
タスクDAGスケジューリング：要件を実行エージェントに割り当て、依存関係エッジによって実行順序、通信トポロジー、クリティカルパスのレイテンシを決定します。
範囲を限定した探索：単一の貪欲な選択ではなく、複数の協働チーム候補のプレフィックスをビームサーチで評価します。
制約優先のフィルタリング：予測品質にかかわらず、不適格なエージェントをランキング前に除外します。
証拠を考慮した学習：要件スコア、実際のコスト、実際のレイテンシによって、信頼性、相乗効果、成功モデル、入札精度を更新できます。
監査可能な結果：選択されたモード、割り当て、トポロジー、予測成功率、カバー率、コスト、レイテンシ、リスク、効用、判断理由を確認できます。

アルゴリズムによるルートの評価方法

SAGEは各タスク要件について、全体的な信頼性と要件に応じた信頼性を組み合わせ、エージェントの調整済み能力を推定します。チームのカバー率は、メンバーが有用で重複しない能力を提供すると高くなります。その後、残りの各要件を、調整済み能力が最も高いチームメンバーに割り当てます。

スケジューラーは要件DAGに従います。1つのエージェントに割り当てられた作業は直列化され、異なるエージェントに割り当てられた独立した作業は並列実行できます。候補チームを構築した後、SAGEはチーム全体のコストとクリティカルパスのレイテンシが、タスクの予算と期限に収まるかを確認します。

実行可能な候補は、予測される成功価値と、コスト、レイテンシ、リスク、コンテキスト転送による損失、調整オーバーヘッド、不確実性のバランスを取る効用関数で順位付けされます。これにより、引き継ぎによって有用なコンテキストが失われすぎる場合には、より優れた専門エージェントが現在のエージェントに敗れることもあります。また、補完的なチームが、名声は高いものの冗長なエージェントの集まりを上回ることも可能にします。

プロジェクトのインストールと検証

前提条件

リファレンス実装にはPython 3.10以降が必要です。プロジェクトのREADMEによると、実行時の依存関係はありません。

リポジトリをクローンする

git clone https://github.com/wang2122/sprix-sage-router.git
cd sprix-sage-router
python demo.py

demo.pyスクリプトでは、エンドツーエンドの例を読みやすい形で確認できます。リポジトリはsprix_sage.pyを通じて実装を直接公開しているため、クイックスタートで別途パッケージのインストールコマンドを実行する必要はありません。

テストとベンチマークを実行する

python -m unittest -v
python benchmark.py

単体テストでは、ルーターが期待どおりに動作することを検証します。ベンチマークでは、決定論的なシードを使って外部の非線形シミュレーターを実行し、SAGEの静的版とオンライン版を、より単純なルーティング戦略と比較できます。

最初のルーティングシナリオを作成する

ステップ1：コア型をインポートする

from sprix_sage import (
    Agent,
    ExecutionOutcome,
    Requirement,
    SAGERouter,
    Task,
)

この例では、候補の記述にAgentを使用し、作業の定義にRequirementとTaskを使用します。また、SAGERouterでルートを選択し、実行後の証拠をExecutionOutcomeで返します。

ステップ2：利用可能なエージェントを定義する

agents = [
    Agent(
        "planner",
        {"planning": 0.92, "coding": 0.55},
        cost=0.08,
        latency_ms=900,
    ),
    Agent(
        "coder",
        {"planning": 0.35, "coding": 0.96},
        cost=0.12,
        latency_ms=1200,
    ),
]

各エージェントには、識別子、能力ベクトル、コスト見積もり、レイテンシ見積もりがあります。ここでは、plannerは計画立案を得意とし、coderはコーディングをより得意とします。この違いにより、SAGEはエージェントを単一の総合スコアで順位付けするのではなく、協調や引き継ぎを検討する理由を持ちます。

ステップ3：要件と依存関係をモデル化する

task = Task(
    "build-feature",
    requirements=(
        Requirement("planning", 0.4),
        Requirement(
            "coding",
            0.6,
            depends_on=("planning",),
        ),
    ),
    value=1.0,
    budget=0.30,
    deadline_ms=4000,
    progress=0.35,
)

このタスクには、重み付きの要件が2つ含まれています。コーディング要件は計画立案に依存しているため、小さなDAGが形成され、コーディングの前に計画立案を完了する必要があります。また、このタスクには制約付きルーティングに必要な値も指定されています。

valueは、成功時の完了価値を表します。
budgetは、許容可能なコストを制限します。
deadline_msは、スケジュール可能なレイテンシを制限します。
progressは、実行がすでに35パーセント完了していることをルーターに伝えます。

進捗が重要なのは、実行途中で担当を変更すると、コンテキスト転送による損失が発生する可能性があるためです。したがって、専門エージェントの能力上の優位性だけで、引き継ぎが最適な経路になるとは限りません。

ステップ4：タスクをルーティングする

router = SAGERouter(
    agents,
    incumbent_id="planner",
)

decision = router.route(task)

print(decision.mode)
print(decision.assignments)
print(decision.topology)

現担当エージェントとは、現在そのタスクを担当しているエージェントです。routeを呼び出すと、実行可能なSELF、COLLABORATE、HANDOFFの候補が比較されます。返される決定は、次のようなフィールドで確認できます。

選択された実行モードを示すdecision.mode。
要件とエージェントの役割割り当てを示すdecision.assignments。
依存関係によって生じる通信構造を示すdecision.topology。

この特定のシナリオが常に特定のモードになると考えてはいけません。結果は、ルーターの調整済み見積もり、制約、進捗、学習済みの状態によって変わります。

実行結果から学習する

ルーティングはワークフローの前半にすぎません。選択されたエージェントがタスクを実行したら、利用可能な最も有力な証拠をルーターに返します。

router.record_outcome(
    decision,
    ExecutionOutcome(
        success=0.9,
        requirement_scores={
            "planning": 0.95,
            "coding": 0.86,
        },
        actual_cost=0.19,
        actual_latency_ms=1450,
    ),
)

全体の成功値は、タスクレベルの結果をルーターに提供します。要件別のスコアは、より正確なクレジット割り当てを可能にし、すべてのチームメイトに同じクレジットが与えられるのを防ぎます。実際のコストとレイテンシは、今後の予測やプロバイダーの見積もりの調整に役立ちます。

ルーティングとフィードバックを繰り返すことで、オンラインSAGEは、コンテキスト依存の信頼度、ペア効果、成功予測、入札の精度を改善できます。効果的に学習するには、結果を一貫して記録し、利用可能な場合は大まかな成功ラベルよりも測定された証拠を優先してください。

SAGEをA2Aシステムと統合する

本番環境での統合では、プロトコルやマーケットプレイスのシグナルをSAGEの内部表現に変換できます。

AgentCard.skillsを能力ベクトルに正規化する。
セキュリティ要件を、厳格な権限フィルターとして使用する。
スコアリングの前に、サポートされる入力モードと出力モードの互換性を確認する。
タスクの状態、成果物、完了済みのDAGノード、障害を、現在の実行状態と転送損失の見積もりにマッピングする。
プロバイダーの見積もりを、コスト、レイテンシ、信頼度を含む入札として表現する。
完了したタスクの評価を使用して、コンテキスト依存の信頼度、ペア残差、成功予測、入札の精度を更新する。

SAGEが決定を返したら、A2Aクライアントはメッセージ送信、ストリーミング、タスクのポーリング、キャンセルなどのプロトコル操作を使って実行できます。境界は明確に保ってください。SAGEは経路を選択して説明し、A2A層は通信と実行を処理します。

高度な利用のヒント

タスクを意味のあるDAGとしてモデル化する

すべての要件を平坦なリストに並べるのではなく、実際の実行順序を表すために依存関係を使用します。正確な依存関係により、SAGEは直列作業と並列作業を区別し、より有用なクリティカルパスのレイテンシ見積もりを生成できます。

相補的な能力の記述を優先する

エージェントの能力は要件レベルで記述します。単一の広範なスコアでは、計画立案、コーディング、調査などのスキルの違いが隠れてしまい、コンテキスト依存の信頼度や役割割り当てが弱くなります。

権限を厳格な制約として扱う

予測品質を使ってアクセスルールを上書きしないでください。SAGEの権限優先設計では、候補の順位付け前に、対象外のエージェントを除外することが想定されています。互換性、認証、ポリシーのチェックも同様に、実行前に行う必要があります。

現実的な予算と期限を使用する

SAGEは候補の構築時と、チームレベルの両方で制約を確認します。タスク固有の予算と期限を指定し、個々には魅力的なエージェントの組み合わせでも、合計コストやクリティカルパスが実行不可能な場合には選択されないようにします。

モードだけでなく決定内容を確認する

割り当て、トポロジー、カバレッジ、予測成功率、コスト、レイテンシ、リスク、効用、根拠を確認します。監査証跡から、その経路が真の補完性、現担当のコンテキスト保持、転送損失の低減、制約の実行可能性のいずれを理由に選択されたのかを明らかにできます。

見積もりの精度を測定する

実行後の実際のコストとレイテンシを返します。観測値がなければ、ルーターは提示された信頼度、価格、所要時間が信頼できるかどうかを判断するための根拠を十分に得られません。

共通の効用でトレードオフを評価する

付属の合成ベンチマークによると、オンラインSAGEは、一覧にあるベースラインよりも高いシミュレーション品質と共通効用を達成する一方、静的SAGEより多くのコストを費やします。この明確なトレードオフは重要です。ルーティングでは、能力のみを基準にしたスコアの背後にコストを隠すべきではありません。

このベンチマークは合成的なものであり、実世界での優位性を示す証拠ではありません。実運用での評価には、代表的な実行、強力なルーティングベースライン、キャリブレーション分析、マーケットプレースのトレース再生、異種エージェント、敵対的条件が必要です。

研究プレビューの制限を理解する

SAGEは初期段階の研究プレビューであり、本番環境におけるサービスレベルの保証でも、査読済みの成果でもありません。その軽量な学習ポリシーは、実際のトレースに基づく学習や、因果的なオフポリシー評価に取って代わるものではありません。

READMEでは、本番環境にデプロイする前に、キャリブレーション済みの評価器、認証済みID、署名付きの能力メタデータ、プライバシーおよびセキュリティレビュー、永続的なイベント駆動型リカバリ、モニタリング、タスク固有の検証を行うことを推奨しています。A2Aの発見、実行、ストリーミング、キャンセルに対応する実アダプターは、分散サービス運用や人手による承認ゲートと同様に、今後のロードマップ項目です。

リポジトリのリソース

sprix_sage.pyには、コンテキスト対応ルーター、DAGスケジューラー、ビームサーチ、オンライン更新が含まれています。
demo.pyでは、エンドツーエンドの例を実行できます。
benchmark.pyには、外部シミュレーターと共通効用のベースラインが含まれています。
test_sprix_sage.pyには、動作に関するユニットテストが含まれています。
ALGORITHM.mdには、形式的な目的関数、探索プロセス、クレジット割り当て、制限事項が記載されています。
GitHubリポジトリには、コントリビューション、セキュリティ、ガバナンス、ライセンスに関する情報が含まれています。

結論

Sprix SAGE Routerは、状態を考慮したエージェントマッチングの実用的なリファレンス実装を提供します。作業を要件DAGとして表現し、共有制約の下でSELF、COLLABORATE、HANDOFFを比較し、実行結果をルーターにフィードバックすることで、予測品質と運用コストの両方を考慮した、監査可能なマルチエージェント意思決定を試すことができます。

まずはdemo.pyから始め、最小限の例を再現し、すべてのルーティング判断を確認して、テストと合成ベンチマークを実行してください。実際のA2Aデプロイでは、別途実行アダプターを追加し、環境に応じて必要となる認証、セキュリティ、可観測性、リカバリ、検証の作業を完了してください。