sgr-agent-core を採用する前に読む: SGR 二段階推論と 3 種のエージェント実装
Schema-Guided Reasoning (SGR) has agentic system design created by neuraldeep community
ひと目でわかる
- これは何？
- Schema-Guided Reasoning を中核に据えた Python 製エージェントフレームワーク。BaseAgent の二段階アーキテクチャ、OpenAI 互換 REST API、ACP 対応までを、設定ファイルと起動コマンドの粒度で確認する。
- 誰に向いている？
- 採用を検討すべきなのは、OpenAI 互換エンドポイントを自前で立て、検索と推論を分離した調査エージェントを YAML で組み替えたいチームである。逆に、単発のチャット応答や低レイテンシの対話ボットが目的なら、二段階の推論ステップはオーバーヘッドにしかならない。
- 商用利用できる？
- できます。MIT は寛容なライセンスで、著作権表示とライセンス表示を残せば、使用・改変・販売が可能です。
- 今もメンテナンスされている？
- されています。最後のコミットは 20 日前です。
- 何の言語で書かれている？
- 主に Python です（GitHub の言語統計による）。
回答はプロジェクトの GitHub データ（最終同期：2026年9月15日）と当サイトの分析に基づくもので、法的助言ではありません。
オープンソース詳細解説
SGR が解こうとしている問題は何か
通常の function calling は、モデルがどのツールをどの引数で呼ぶかを一発で決める。検索クエリの設計、結果の取捨選択、追加検索の要否判断がすべて同じ生成ステップに同居するため、ツール選択の失敗と推論の失敗が区別できない。README は SGR を「structured reasoning with flexible tool selection」と表現しており、この 2 つを別のステップに分けるのが狙いである。
対象読者は、調査タスクをエージェントに任せたいが、モデルの内部で何が起きているかを追跡したい開発者だ。README が挙げる用途は deep research、つまり複数回の検索と本文抽出を経て回答を組み立てるワークロードである。単発の質疑応答ではなく、途中経過を検証できることに価値がある場面向けと言える。
BaseAgent の二段階アーキテクチャと 3 つのエージェント種別
README によれば、コアは拡張可能な BaseAgent インターフェースで、二段階アーキテクチャを実装する。その上に複数の研究エージェント実装が載る構成である。提供される種別は SGRAgent、ToolCallingAgent、SGRToolCallingAgent の 3 つ。名前から読み取れる範囲では、SGR のスキーマ誘導推論のみを使うもの、通常の function calling のみを使うもの、両者を組み合わせるものという区分になる。
ここで注意したいのは、README が各クラスの内部ステップや遷移条件を説明していない点だ。二段階が具体的に何と何を指すのか、スキーマがどこで定義されるのかは、この資料からは確定できない。設計思想としては筋が通っているが、実装の詳細はリポジトリのコードか公式ドキュメントを読む必要がある。ツール側は検索、推論、確認応答（clarification）の 3 系統が用意されると記載されている。clarification が組み込まれているのは実用的で、エージェントが情報不足を検出したときにユーザーへ問い返す経路が想定されていることになる。
起動経路が 3 つある: sgr、sgrsh、sgracp
配布形態は 2 通り。Docker イメージ ghcr.io/vamplabai/sgr-agent-core:latest を使う方法と、pip install sgr-agent-core でライブラリとして入れる方法である。Docker の場合、ホスト側に logs と reports を作成し、README の例では sudo chmod 777 を与えてから、examples/sgr_deep_research を読み取り専用でマウントする。設定ファイルはイメージ内の /app/examples/sgr_deep_research/config.yaml を指す。
HTTP サーバーは sgr コマンドで起動する。sgr --config-file examples/sgr_deep_research/config.yaml、短縮形は sgr -c である。同じ処理は python -m sgr_agent_core.server --config-file ... でも起動できると README に注記がある。ポートは Docker 例で 8010、Swagger UI は /docs にある。
対話用の CLI は sgrsh。引数なしで起動するとインタラクティブチャットになり、sgrsh "Найди цену биткоина" のように単発クエリも渡せる。--agent sgr_agent でエージェントを選び、-c config.yaml -a sgr_agent の組み合わせも可能。カレントディレクトリの config.yaml を自動で探す挙動が README に明記されている。
3 つ目が sgracp で、Agent Client Protocol を stdio 上の newline-delimited JSON-RPC で話す。sgracp --config examples/sgr_deep_research/config.yaml で起動し、config.yaml の acp ブロックで公開するエージェントを選ぶ。acp: agent: sgr_agent のように書き、省略時は最初のエージェント定義が使われる。エディタ側から同じ YAML 設定でエージェントを呼べる点は、HTTP サーバーを別途立てたくない場合の逃げ道になる。
config.yaml で実際に触るキー
README が名前を挙げている設定キーは限られている。llm.api_key は必須で、OpenAI API キーを入れる。tools.web_search_tool.api_key と tools.extract_page_content_tool.tavily_api_key は Tavily 用で、いずれも optional と明記されている。つまり Tavily なしでも起動はできるが、その場合 Web 検索とページ本文抽出の品質は別途用意したツールに依存することになる。
ACP を使う場合のみ acp.agent を追加する。Docker 例では設定ファイルを読み取り専用でマウントしているため、コンテナ内から設定を書き換える運用は想定されていない。設定変更はホスト側で行う。
もう 1 点、Docker 手順で sudo chmod 777 logs reports を実行しているのは、コンテナ内のプロセスがホストのバインドマウントに書き込むための権限調整である。ここは利便性を優先した指示で、本番運用では所有者を合わせる方向に置き換えるのが妥当だ。README はその代替手順を示していない。
SimpleQA の数値と、それが示していないもの
README には SimpleQA ベンチマークの比較画像と、gpt-4.1-mini での数値が載っている。Accuracy 86.08%、Correct 3,724、Incorrect 554、Not Attempted 48。詳細は benchmark/simpleqa_benchmark_results.md にあるという案内である。
この数値をどう扱うかは慎重でありたい。単一モデル、単一ベンチマークでの結果であり、検索ツールの構成やプロンプト、試行回数は README からは分からない。Not Attempted が 48 件あることは、回答を放棄する経路が存在することを示す。無回答を誤答と区別して集計している点は評価できるが、実運用でその 48 件がどう扱われるかは別問題である。ベンチマークは採用判断の材料の 1 つであって、根拠にはならない。自分のドメインのクエリで sgrsh から同じ構成を流し、Correct と Not Attempted の比率を自分の目で見るほうが早い。
向かないケースと、代わりの選択肢
このフレームワークが向かないのは、1 回のモデル呼び出しで完結するタスクだ。SGR は推論とツール選択を分ける分だけステップ数が増える。要約、分類、単純な抽出に使うと、遅延とトークン消費だけが増えて精度は上がらない可能性が高い。また、ツールを持たない純粋な対話エージェントにも二段階構成は過剰である。
代替として素直なのは、OpenAI の function calling を直接使う実装、あるいは LangGraph のようなグラフベースのオーケストレーションだ。違いは制御の置き場所にある。素の function calling はツール選択も推論もモデルに委ね、開発者はツール定義だけを書く。LangGraph はノードとエッジをコードで明示し、状態遷移を開発者が握る。sgr-agent-core はその中間で、推論の型をスキーマとして与えつつ、ツール選択の自由度はモデルに残す。YAML でエージェントを差し替えたいが、グラフを自分で組みたくはない、という位置に収まる。
もう 1 つの論点はモデル依存だ。README は OpenAI 互換の LLM であればローカルモデルでも動くと述べている。ただし SGR の効果はスキーマに従って構造化出力を出せるかどうかにかかっている。小さいローカルモデルでスキーマ遵守が崩れる場合、二段階構成の利点は失われる。ここは検証するしかない。
保守コストとライセンスの確認点
リリースは 0.7.1（2026-07-15）、0.7.0（2026-03-18）、0.6.0（2026-01-24）と、マイナー番号が 0 のまま約 2 か月から 3 か月間隔で進んでいる。0.x 系である以上、設定キーやエージェント種別の名前が破壊的に変わる前提で運用したほうがよい。config.yaml をバージョン管理下に置き、更新時に差分を確認する運用が現実的である。
テストカバレッジが包括的であることと Docker 対応が README に書かれているが、具体的なカバレッジ率や CI 構成はこの資料からは確認できない。依存関係の更新頻度も不明である。
ライセンスは MIT。商用利用や改変、再配布の制約は比較的緩い。ただし、同梱の Tavily 連携や OpenAI API の利用には別途それぞれの利用規約と従量課金がかかる。MIT はあくまでこのリポジトリのコードに対する条件であり、外部 API の契約条件は別に確認する必要がある。ここは法務判断ではなく、契約範囲の確認事項として扱ってほしい。
最後に実務的な注意点を 1 つ。Docker 手順の chmod 777 をそのまま本番に持ち込まないこと。logs と reports の所有者をコンテナ実行ユーザーに合わせる形へ置き換えるのが先である。
編集部の結論
採用を検討すべきなのは、OpenAI 互換エンドポイントを自前で立て、検索と推論を分離した調査エージェントを YAML で組み替えたいチームである。逆に、単発のチャット応答や低レイテンシの対話ボットが目的なら、二段階の推論ステップはオーバーヘッドにしかならない。導入前に確認すべきは 3 点。examples/sgr_deep_research/config.yaml.example をコピーして llm.api_key を設定し、sgr -c で起動して /docs に到達できるか。使うエージェント種別を SGRAgent、ToolCallingAgent、SGRToolCallingAgent のどれにするか。そして SimpleQA の 86.08% が gpt-4.1-mini 単一モデルでの数値であり、自分のモデルと検索ツールで再現するかどうか。
コミュニティノート