OpenSparX/MasterAgent

OpenSparX / MasterAgent – 小型で組み込み可能なC++エージェントランタイム

概要

• ローカルファーストなAIエージェントを構築するためのオープンソースのC++17ライブラリ（および付属のCLI）です。ユーザーの発話を決定論的な正確なフレーズのスキル（モデル不要）と照合します。スキルが一致しない場合、シンプルなHTTP/JSON APIを介してローカルでホストされたLLM（例：llama-server）にリクエストを転送できます。
• ランタイムはツール定義（名前、引数のJSONスキーマ）を検証し、宣言されたツールのみが呼び出され、パラメータがチェックされることを保証します。ツールの結果は構造化されたJSONとして呼び出し元に返されます。
• 完全にオフライン（libcurlやSQLiteなし）で実行することも、モデル呼び出しのためのオプションのHTTPサポートや、永続的なリクエストレシートのためのオプションのSQLiteストレージを使用して実行することも可能です。

主な機能

機能	仕組み
正確なフレーズのスキル	事前に登録されたフレーズが決定論的なコールバックをトリガーし、モデルをバイパスします。
ツールの登録と検証	開発者はJSONスキーマのような記述とC++コールバックを提供し、ランタイムは実行前にツール名と引数をチェックします。
ローカルモデル統合	MASTER_AGENT_ENABLE_HTTP=ON でビルドすると、CLIはOpenAI互換の /v1/chat/completions エンドポイントを実装するサーバー（例：GGUFモデルを提供するllama-cppサーバー）と通信できます。
永続的なリクエストレシート	SQLiteを有効にすると、各リクエストに一意のIDが付与されます。重複呼び出しはデデュプリケートされ、結果がリプレイされるため、クラッシュ復旧や UNKNOWN 状態の手動調整が可能になります。
コンテキストとキャンセル	すべてのツール呼び出しは、セッションID、リクエストID、冪等キー、期限、および協調キャンセル用トークンを受け取ります。
CLIとSDK	sparx コマンドラインツールがフローを実演します。SDKはCMake経由でインストールし、MasterAgent::Core（およびオプションで MasterAgent::Http）としてリンクできます。
拡張可能なサンプル	参考用の「インベントリエージェント」は、外部HTTPサービスの呼び出し、冪等レシートのコミット、および失われたレスポンスからの復旧方法を示しています。
テストと評価	CIはユニットテスト、合成評価、およびSDK、CLI、サンプルコンシューマーをビルドするパッケージングスクリプトを実行します。

典型的なワークフロー

1. ツールの定義 – C++で各ツールを名前、パラメータスキーマ、および実際の作業を実行するコールバック（例：車のエアコンコントローラーとの通信）で登録します。
2. 正確なフレーズスキルの追加 – 固定されたユーザーの発話（例："把空调调到22度"）を適切なツールを呼び出すコールバックにマッピングします。
3. ビルド – cmake -S . -B build -DCMAKE_BUILD_TYPE=Release（HTTPアダプターを削除するには -DMASTER_AGENT_ENABLE_HTTP=OFF、SQLiteを削除するには -DMASTER_AGENT_ENABLE_STORAGE=OFF を追加）。
4. 実行 – ./build/cli/sparx run --input '把空调调到22度'。ランタイムはフレーズを照合し、ツールを検証し、コールバックを実行してJSONレシートを出力します。
5. オプションのモデル – 正確なフレーズが一致しない場合、ローカルLLMサーバーを起動し、--endpoint 127.0.0.1:8080 --model local を指定してCLIを呼び出します。モデルはJSON形式のツール呼び出しまたはプレーンなJSONレスポンスを返す必要があり、不正な出力は拒否されます。
6. 永続化と復旧 – --state ./state/agent.db --session alice --request-id ac-001 を指定してレシートをSQLiteに保存します。クラッシュ後、sparx recover --state ./state/agent.db を実行すると、成功した結果がリプレイされ、未完了のものは手動調整のために UNKNOWN としてフラグが立てられます。

なぜ重要なのか

• 決定論の優先 – モデルなしで既知のコマンドを処理することで、システムはハルシネーションを回避し、再現可能な動作を保証します。
• 安全性 – ツール名と引数は厳密に検証されます。ランタイムは、モデルの不確かな出力からツール呼び出しを推測することはありません。
• ローカルファースト – クラウドサービスは不要です。すべてがラップトップ、エッジデバイス、またはコンテナ内で実行可能です。
• 耐久性 – SQLiteレシートはシンプルな監査証跡を提供し、ビジネス上重要な操作（例：在庫の減算）に対して「正確に1回」のセマンティクスを実現します。

はじめに

# Clone and build (Ubuntu example)
git clone https://github.com/OpenSparX/MasterAgent.git
cd MasterAgent
sudo apt-get install libcurl4-openssl-dev libsqlite3-dev   # optional deps
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel 4
ctest --test-dir build --output-on-failure

# Run the demo (no model needed)
./build/cli/sparx demo automotive
./build/cli/sparx run --input '把空调调到22度'

ライセンス – Apache-2.0。

---

上記の詳細はすべてリポジトリのREADMEから直接引用したものであり、追加の機能は推論されていません。