Show HN: LoopGain – max_iterationsではなく制御理論でエージェントループを停止
Show HN: LoopGain – Stop agent loops with control theory, not max_iterations (github.com)
要約
LoopGainは、AIエージェントのループが収束した時点でリアルタイムに検出し、停止させるオープンソースのコストコントローラーです。固定の最大反復回数ではなく、収束を基準にすることで、APIコストを大幅に削減し、処理速度を向上させながら品質を維持します。LangGraph、CrewAI、AutoGenなどの主要なフレームワークに対応しています。
全文翻訳
AIエージェントループのためのオープンソースコストコントローラー。
AIエージェントループは、停止すべき時を知らないと時間と費用を浪費します。LoopGainはループをリアルタイムで測定し、収束した瞬間に停止させ、固定のmax_iterationsキャップに達する前にロールバックします。これにより、無駄な反復処理を防ぎます。
ベンチマーク — 10個のワークロードセルで2,000回のペアトライアル (自分で実行可能):
max_iter=20と比較してAPI支出が92.8%削減 — ベンチマーク総支出 $27.05 → $1.94- 約15倍高速 — トライアルあたりの中央値壁時計時間 30.9秒 → 2.1秒
- 品質は維持され、速度のために犠牲にされていない — 自然分布ワークロード (W1–W4, ほとんどのセルでCIはnullを除く) でのジャッジ勝率 0.50–0.63、エンジニアリングされた失敗ワークロード (W5) で 0.92–0.95。1,800回のジャッジ比較で0.678の加重選好度
- 6つのキル基準のうちゼロが発火 (すべて実行前にしきい値とともに事前登録済み)
正直な限界、 upfront: LoopGainは収束を検出しますが、正しさは検出しません — これ以上反復しても役に立たない時はわかりますが、その答えが正しいかはわかりません。また、エラー信号の背後にある検証器の性能に依存します。できないことの全リストはこちら →
[画像: PyPI] [画像: Python] [画像: License] [画像: Tests]
ホーム: loopgain.ai
測定可能なエラー信号を持つあらゆる反復AIワークフローに対応 — 検証・修正ループ、洗練パス、ツール使用リトライチェーン、自己修正RAG、リンターフィードバック付きコード生成、多段階推論ループなど。LangGraph, CrewAI, AutoGen, LangChain, OpenAI Agents SDK, および Claude Agent SDK 用の事前構築済みアダプター。カスタムスタックの場合は、生のAPI経由でドロップインできます。純粋なPythonで、ランタイム依存関係はありません。
なぜ
本番環境のエージェントループでは、終了ポリシーとして普遍的にmax_iterations=Nが使用されています。これはエージェンティックAIの残念なデフォルトです。計算資源を無駄にするか(ループが遅すぎる場合に停止)、悪い出力を出荷するか(ループが早すぎる場合に停止)のどちらかになります。LoopGainはこれを、バークハウゼン基準に基づいた制御理論的な停止・ロールバックポリシーに置き換えます。これは電気工学のフィードバック発振器解析 (1921年) の基礎的な結果です。
インストール
pip install loopgain
純粋なPythonで、依存関係なし、Python 3.10+をサポートします。
Claude Codeを使用していますか? loopgain-pluginは、ラップ可能なループ(リテラル、再帰、グラフサイクル、セマンティック)をリポジトリ全体でスキャンし、レビュー済みの差分を一度に1つのファイルずつ提案します(自動適用はしません)。
/plugin marketplace add loopgain-ai/loopgain-plugin
/plugin install loopgain
使用方法
3行のコードで、測定可能なエラー信号を持つあらゆる反復ループをラップできます。
from loopgain import LoopGain
lg = LoopGain(target_error=0.1)
while lg.should_continue():
errors = verifier.verify(output)
lg.observe(errors, output=output)
output = reviser.revise(output, errors)
result = lg.result
print(result.outcome) # "converged" | "oscillating" | "diverged" | "stalled" | "max_iterations"
print(result.best_output) # 最もエラーが少なかったイテレーションの出力
print(result.iterations_used)
print(result.savings_vs_fixed_cap)
observe()は、数値のエラー量、または任意のシーケンス(その長さが量になる)を受け入れます。output=...を渡すと、これまでの最良のバッファが有効になります。
エラー信号の定義
提供していただく唯一のものはエラー信号です。これは、現在の出力がどれだけ間違っているかを示す、各イテレーションごとの単一の非負の数値です。小さいほど良く、ゼロは完了を意味します。LoopGainはそのループが何をしているかを知りません。ただその数値の軌跡を監視し、続行するか、停止するか、ロールバックするかを決定します。
あなたのループには、出力がまだ良くないことを知る方法が既にあります(そうでなければ、修正を続けないでしょう)。それを数値に変換してください。
| ループ | エラー信号 = |
|---|---|
| エージェンティックコーディング (コード作成 → テスト実行) | 失敗したテストの数 (10 → 3 → 0) |
| JSON / 構造化抽出 | スキーマ違反の数 |
| 自己修正RAG | まだ欠けている必須ファクトの数 |
| LLMジャッジによる自己洗練 | ジャッジの目標からのギャップ (例: 10 − quality_score) |
| リンター/フォーマットループ | リンターエラー数 |
唯一のルールは、非負であること、そして出力が改善するにつれて小さくなることです。問題点の生のリストを直接渡しても機能します。observe()はリストの長さを量として使用します(例: 失敗したテストのリストを渡す)。
品質が曖昧で自然な「ゼロ」がない場合は、target_error=Noneで実行してください。LoopGainは、そのプラトーがどこであっても、数値が改善しなくなったときに停止します。正確なターゲットを待つのではなく。
停止/続行の各決定は、この1つの数値から行われるため、LoopGainは提供されたエラー信号の良さと同じくらいしか正しくありません。出力品質を真に追跡するものを選択してください。
仕組み
LoopGainは各イテレーションで経験的なループゲイン(Aβ = E(n) / E(n-1))を測定し、可視化のために平滑化された時系列として公開します。しかし、決定エンジンは完全なエラー軌跡を4つの特徴量で分類します。
E_ratio = E_current / E_first # 累積減少量
slope_log = log10(E) のOLS傾き # 幾何学的トレンド方向
slope_p = 傾きのt検定p値 # 統計的有意性
osc_std = detrended log10(E) の標準偏差 # 発振の大きさ
軌跡を次の5つの名前付き状態のいずれかにルーティングします。
| 状態 | 条件 | アクション |
|---|---|---|
FAST_CONVERGE | 累積減少量が E_first の10%以下 | 続行 |
CONVERGING | 傾きが負で p < 0.05、または累積が50%以下 | 続行、上向きのドリフトに注意 |
STALLING | 有意な傾きがなく、検出可能な発振もない | 2回連続で読み取った後に停止 — これまでの最良のものを返す |
OSCILLATING | 傾きが平坦で残差分散が大きい | 停止 — これまでの最良のものを返す |
DIVERGING | 傾きが正で p < 0.05 かつ累積が110%超 | 中止 — これまでの最良のものにロールバック |
さらにショートサーキットがあります。観測されたエラーがtarget_error以下に低下した場合、ループは即座にTARGET_MET状態で停止します。デフォルトのtarget_error=0.0は、正確にゼロエラーでショートサーキットします(検証駆動型ループの自然な完了信号)。target_error=Noneを渡すと、ショートサーキットを無効にし、安定性検出のみに依存します。
決定は意図的に保守的です。ノイズの多い実際のLLMエラー系列での誤検出中止を防ぐために、統計的有意性と意味のある累積的な動きの両方を必要とします。N=1000の決定論的モック軌跡の5つのレジーム全体で98.8%のマクロ平均精度で検証済み(RESULTS_v2_classifier.md参照)。STALLINGの天井約94%は、分類器の弱点ではなく、t検定の避けられない5%のタイプIエラー率です。
推奨最小値: 6イテレーションで信頼性の高いトレンドの有意性を確保できます。n≤4ではt検定は著しく検出力が低い(df=2ではp<0.05のために|t|>4.3が必要)ため、証拠が薄い場合、分類器は保守的にSTALLINGにフォールバックします。しきい値は分析的に導出されており(制御理論+統計的慣習)、適合されたものではありません。本番トレースがある場合は、ワークロード固有の証拠でTrajectoryThresholds引数を使用して調整してください。
レガシー単一特徴量分類器: 元のv0.1単一Aβバンド分類器(しきい値0.3 / 0.85 / 0.95 / 1.05)は、バンドを特定のワークロードに経験的に調整した呼び出し元のために、LoopGain(classifier='legacy_bands')を介して引き続き利用可能です。
これまでの最良のロールバック
LoopGainは、観測されたすべての出力をエラースコアとペアにしてバッファに保持します。終了時に、最後のイテレーションではなくargmin(error)を返します。
| 終端状態 | 返される出力 |
|---|---|
TARGET_MET | 現在の出力(定義により最良) |
OSCILLATING | バッファ内の最もエラーの少ないイテレーション |
DIVERGING | 最もエラーの少ないイテレーション(最後のイテレーションではない) |
これにより、発散検出が「ゴミで中止」から「これまでに見た最良のもので中止」に変わります。これは無料の品質フロアです。
フリート全体での表示(オプションのダッシュボード)
ライブラリ自体が製品全体です。テレメトリはオプトインであり、セルフホスト可能です。チーム全体で各ループの安定性、コスト、ロールバックのフリートビューが必要な場合は、テレメトリレシーバーで供給されるホスト型ダッシュボードがあります。
[画像: LoopGainダッシュボード — フリート全体のループヘルス、収束、無駄、ロールバック]
ライブデモを開く → — サインアップ不要、実際のベンチマークデータ。
レシーバーとダッシュボードはどちらもオープンソースです。セルフホストすれば、テレメトリを完全に管理下に置くことができます。
リポジトリ
| リポジトリ | 内容 |
|---|---|
| loopgain | このライブラリ — Apache-2.0の制御ループ(現在地) |
| telemetry-receiver | 匿名化されたループテレメトリを取り込むCloudflare Worker |
| dashboard | フリートダッシュボード — セルフホスト可能 |
| loopgain-bench | 上記の数値の背後にある再現可能な2,000トライアルベンチマーク |
| loopgain-plugin | Claude Codeプラグイン — リポジトリ内のラップ可能なループをスキャンし、レビュー済みの差分を提案 |
LoopGainが保証すること、しないこと
LoopGainは、ループが改善を停止した時点でループを停止させることでコストを節約します — 反復回数が少なくなり、トークンも少なくなります。当社の公開ベンチマークでは、max_iterations=20と比較して、出力品質を維持しながら、総API支出が92.8%削減されました。正直な限界が2つあります。
- 節約額はワークロードによって異なります。 通常、迅速に成功するループは最も節約できます(約96%)。敵対的で失敗しやすいループは、節約額が少なくなります(約78–84%)。見出しは平均値です。数値を引用する前に、ご自身のループでベンチマークを実行してください。
- LoopGainは収束を検出しますが、正しさは検出しません。 エラー信号が改善を停止した時点で停止します。これは、これ以上反復しても役に立たないことを意味しますが、ループが成功したことを意味するわけではありません。ベンチマークでは品質を維持しました(より悪い出力で早期に停止することはめったにありませんでした。誤停止率は≤4.5%でした)。しかし、ループはエラーがゼロを超えていても停滞する可能性があります。例えば、2つのテストが失敗した状態でプラトーになることがあります。したがって、
result.best_error(またはご自身のパス/フェイル)を、出力を信頼する前に確認してください。もしターゲットを下回ってプラトーになった場合、それはLoopGainが見ることのできない品質ギャップであり、再実行を強制する誤停止は節約額を食い潰す唯一の方法です。LoopGainはいつ停止するかを決定し、あなたは答えが十分に良いかどうかを決定します。 - LoopGainは検証器と同じくらいしか正しくありません。 提供されたエラー信号に基づいて動作します。検証器がゼロエラーを報告した場合、LoopGainはそれを信頼して停止します。したがって、盲点のある検証器は、まだ間違っている答えに対して成功を報告する可能性があり、LoopGainは自信を持ってそこで停止します。これは上記のプラトーケースとは異なります。エラーはゼロと読み取られ、ループはクリーンな成功のように見えます。そのため、LoopGainもその収束信号もそれをフラグ立てできません。停止の品質は、エラー信号の背後にあるチェックの品質によって制限されます。ベンチマークのコード生成ワークロードでこれを測定しました。収束した実行の4.5%(355件中16件)は、ループが実行したすべてのチェックに合格しましたが、保持された完全なテストスイートには失敗しました。これはフロアであり、シーリングではありません。なぜなら、そこでのループ内検証器は強力だったからです。より弱い検証器は、より多くのものを露出させます。(上記の≤4.5%の誤停止率とは異なります。数値は一致しますが、失敗モードは異なります)。LoopGainを、あなたが費用をかけられる最も強力な検証器と組み合わせてください — サンプルサブセットに対する実行可能テスト、バイブレーションに対するスキーマまたはタイプチェック、ループが最適化しなかった保持チェックなど。強力な検証器の設計方法は、まさにこのためのフィールドガイドです。
APIリファレンス
LoopGain(target_error=0.0, max_iterations=50, thresholds=None, trajectory_thresholds=None, classifier='trajectory', smoothing_window=3, assumed_fixed_cap=10)
モニターを構築します。
target_error— 観測されたエラーがこれ以下に低下した場合に停止します。デフォルトの0.0は、正確にゼロエラーでショートサーキットします(検証駆動型ループの自然な完了信号)。ショートサーキットを完全に無効にするにはNoneを渡します。max_iterations— ハードセーフティバックストップ。デフォルトは50なので、ループが決して無制限に実行されることはありません。安定性判定は通常、これよりずっと前に終了します。完全に無制限のループ(target_errorまたは停止状態に到達することが保証されている場合にのみ安全)をオプトインするにはNoneを、よりタイトにキャップするには小さい整数を渡します。thresholds— レガシー単一Aβバンド分類器用のカスタムThresholdBands。classifier='trajectory'の場合は無視されます。trajectory_thresholds— マルチ特徴量分類器(デフォルト)用のカスタムTrajectoryThresholds。ワークロード固有の証拠がある場合にのみ上書きします。classifier—'trajectory'(デフォルト、v0.2マルチ特徴量分類器)または'legacy_bands'(v0.1単一Aβバンド分類器)。smoothing_window— 平滑化されたAβ系列のEMAウィンドウ(分類器の選択に関わらず常に維持されます)。デフォルトは3。assumed_fixed_cap—savings_vs_fixed_capの計算に使用されます。デフォルトは10。
lg.observe(errors, output=None) -> str
このイテレーションのエラーとオプションの出力を記録します。現在の状態名を返します。errorsは数値(直接使用)または任意のシーケンス(長さが量として使用)を受け入れます。
lg.should_continue() -> bool
終端状態が発火するとFalseを返します。
lg.state -> str
現在の状態名。INIT, FAST_CONVERGE, CONVERGING, STALLING, OSCILLATING, DIVERGING, TARGET_MET, MAX_ITERATIONSのいずれかです。対応する終端result.outcome値は、converged, oscillating, diverged, stalled(v0.2トラジェクトモードのみ — STALLINGは2回連続の読み取り後に終了)、max_iterations、またはin_progressです。
lg.result -> LoopGainResult
outcome, iterations_used, best_index, best_output, best_error, convergence_profile, error_history, savings_vs_fixed_capを含む終端結果。ループの途中で安全に呼び出せます。
lg.send_telemetry(endpoint=None, token=None, workload_id=None, timeout=2.0, allow_insecure=False, framework=None, loop_type=None, team=None, include_per_iteration=True, retries=2, retry_backoff=0.25, actual_dollars_spent=None, actual_dollars_saved=None) -> bool
オプトイン。 ループ終了後に単一の匿名化されたテレメトリPOSTを送信します。ベストエフォート — 例外は発生せず、2xxでTrue、それ以外でFalseを返します。アダプターはframeworkを自動スタンプします。loop_typeとteamは、ダッシュボードでフィルターとして表示される自由形式のラベルです。include_per_iteration=Falseを渡すと、集計サマリーのみを送信します。
endpointとtokenはオプションです(v0.6.3+)。LOOPGAIN_TELEMETRY_ENDPOINTとLOOPGAIN_TELEMETRY_TOKENがエクスポートされている場合、単なるlg.send_telemetry()で完全に設定されます。エンドポイントはレシーバーのベースURL(https://telemetry.loopgain.ai)または完全な/v1/aggregateパスのいずれかです。何も設定されていない場合 — Falseを返し、何も送信しません。
actual_dollars_spentとactual_dollars_savedはオプションのリアルコストフィールドです(v0.6.1+)。実際に測定されたドル額がある場合にのみ入力してください — 合計された実際のAPI使用量 x リスト価格、または実際に実行されたペアベースライン比較実行。計算で推定されたものではありません。入力されると、ダッシュボードは反復回数 x $/イテレーションの推定値ではなく、実際の数値を表示します。推定値をこのフィールド経由で渡すと、テナントのデータ消費者の全員に、あなただけでなく、真実として提示されます。
from loopgain import LoopGain
lg = LoopGain(target_error=0.1)
# ... ループを実行 ...
lg.send_telemetry(workload_id="my-rag-pipeline") # 環境からのエンドポイント/トークン (v0.6.3+)
実際のループを配線する前にパイプラインを検証してください — loopgain doctorは、小さなインプロセスループ(モデル呼び出しなし、$0)を実行し、1つのテストイベントを送信します。
export LOOPGAIN_TELEMETRY_ENDPOINT="https://telemetry.loopgain.ai"
export LOOPGAIN_TELEMETRY_TOKEN="lgk_..."
loopgain doctor
# -> イベントがレシーバーによって受け入れられる -> ダッシュボードに 'loopgain-doctor' として表示される
推奨設定: トークンをソースの外に保存します。2つのクリーンなオプションがあります。
# オプションA: 環境変数 (最も簡単)
export LOOPGAIN_TELEMETRY_ENDPOINT="https://telemetry.loopgain.ai/v1/aggregate"
export LOOPGAIN_TELEMETRY_TOKEN="lgk_..." # ~/.zshrc または ~/.bashrc に追加
# オプションB: macOS Keychain (より安全)
pip install keyring
python3 -c "import keyring; keyring.set_password('loopgain', 'telemetry', input('Token: '))"
# その後コード内で: keyring.get_password('loopgain', 'telemetry')
送信されるもの: 状態遷移、Aβサマリー(最小/最大/中央値)、ロールバックフラグ、使用されたイテレーション数、節約額、ライブラリバージョン、オプションの不透明なworkload_id、しきい値設定、時間バケット化されたタイムスタンプ — そして、include_per_iteration=Falseを渡さない限り、長さ制限付きのイテレーションごとの軌跡(平滑化されたAβ値と数値のエラー量。これはダッシュボードの収束プロファイルスクラビングを駆動します)。
決して送信されないもの: プロンプト、完了、エラー内容、出力バッファ、またはベアラートークン以外の顧客ID。 数値のエラー量は送信されます(これらはループゲイン信号です)。エラー内容は決して送信されません。プライバシー契約は、tests/test_telemetry.pyのペイロード形状ユニットテストによって強制されます。
telemetry.loopgain.aiのホストされたエンドポイントは、許容される宛先の一つです。レシーバーとダッシュボードはどちらもオープンソースです。セルフホストすれば、テレメトリを完全に管理下に置くことができます。
これは匿名使用テレメトリと同じではありません。
send_telemetryはあなたのループデータをあなたのダッシュボードに送信し、あなたがそれを呼び出した場合にのみ送信します。別途、オプトインのファネルテレメトリが以下に説明されています。両者はデータやコードを共有しません。
匿名ファネルテレメトリ(オプトイン、デフォルトオフ)
LoopGainは匿名使用カウントを報告できます。これにより、単独のメンテナーはライブラリが実際に使用されているかどうかを知ることができます — インストール → 最初のobserve() → 定期的な使用。これはオプトインであり、デフォルトで拒否されます。明示的にオンにしない限り何も送信されません。
loopgain telemetry --show # ステータス + 送信される内容の正確な表示
loopgain telemetry --enable # オプトイン (または: export LOOPGAIN_TELEMETRY=1)
loopgain telemetry --disable # オプトアウト (または: export LOOPGAIN_TELEMETRY=0)
DO_NOT_TRACK=1はハードオプトアウトとして尊重され、CI環境は自動検出されてサイレントに拒否されます。有効な場合、ペイロードにはローカルで生成されたランダムID(マシンから派生しない)、時間バケット化されたタイムスタンプ、ライブラリ/Python/OSバージョン、使用中のアダプター、および大まかな結果カウントのみが含まれます。プロンプト、出力、エラー内容、キー、パス、IPアドレスは収集されません。配信はバッチ処理され、非同期で、httpsのみで、失敗してもサイレントです — ループを壊すことは決してありません。詳細とプライバシー契約: TELEMETRY.md。
LoopGainが役に立つ場合は、オプトインすることがプロジェクトをサポートする最も安価な方法です — これらのカウントは、単独でメンテナンスされているライブラリが誰かの役に立っているかを知る唯一のシグナルです。
コマンドラインインターフェース
loopgain --version # または: loopgain version
loopgain telemetry --show # 匿名ファネルテレメトリの検査/制御
python -m loopgain telemetry --show # 同等、コンソールスクリプトなし
フレームワークアダプター
loopgain.integrationsの下の薄いラッパーは、各主要エージェントフレームワークのイテレーションをLoopGainモニターで駆動し、テレメトリにframework="<name>"を自動スタンプします。フレームワーク自体はオプションの依存関係です — 必要なものを追加でインストールしてください。
pip install 'loopgain[langgraph]' # LangGraph
pip install 'loopgain[crewai]' # CrewAI
pip install 'loopgain[autogen]' # AutoGen v0.4+
pip install 'loopgain[langchain]' # LangChain (create_agent / AgentExecutor)
pip install 'loopgain[openai-agents]' # OpenAI Agents SDK
pip install 'loopgain[claude-agent-sdk]' # Anthropic Claude Agent SDK
pip install 'loopgain[all]' # 全て6つ
すべてのアダプターは、LoopGainインスタンスと、提供するerror_fnを受け取ります。フレームワークはエラー信号が何であるかを知らないため、アダプターも知りません。error_fnは非負の数値(またはイテレーションをスキップする場合はNone)を返します。
LangGraph
graph.stream(input, stream_mode="updates")を駆動します。各更新は1つのイテレーションです。
from loopgain import LoopGain
from loopgain.integrations import LangGraphAdapter
graph = build_my_verify_revise_graph().compile()
lg = LoopGain(target_error=0.1, max_iterations=20)
adapter = LangGraphAdapter(
lg=lg,
error_fn=lambda update: len(update.get("verifier", {}).get("errors", [])),
)
final_state = adapter.run(graph, {"draft": initial})
lg.send_telemetry(
endpoint=os.environ["LOOPGAIN_TELEMETRY_ENDPOINT"],
token=os.environ["LOOPGAIN_TELEMETRY_TOKEN"],
workload_id="rag-rewrite",
framework=adapter.framework_name, # "langgraph", 自動スタンプ
)
完全なトレースが必要な場合はadapter.stream(...)が各項目をyieldし、非同期error_fnを受け入れるのはadapter.arun(...) / adapter.astream(...)です。
CrewAI
Crewのstep_callbackおよび/またはtask_callbackにインストールします。ループに一致する粒度を選択してください — タスク内の洗練にはstep_error_fn、タスク間の洗練にはtask_error_fn。
from crewai import Crew
from loopgain import LoopGain
from loopgain.integrations import CrewAIAdapter
lg = LoopGain(target_error=0.1, max_iterations=20)
adapter = CrewAIAdapter(
lg=lg,
task_error_fn=lambda task_output: count_failed_checks(task_output.raw),
)
crew = Crew(agents=[...], tasks=[...])
adapter.install(crew)
result = crew.kickoff()
adapter.uninstall() # または `with CrewAIAdapter(...) as a:` コンテキストを使用
lg.send_telemetry(
endpoint=...,
token=...,
framework=adapter.framework_name, # "crewai"
)
アダプターは、既にインストールされているコールバックとチェーンします。既存のインストルメンテーションは上書きされません。
AutoGen (v0.4+)
team.run_stream(task=...)をラップします。検証・修正ローテーションでは、verifierからのメッセージのみをフィルタリングするためにobserve_sources={"verifier"}を使用し、observe()を駆動するのはそれだけです。
from autogen_agentchat.teams import RoundRobinGroupChat
from loopgain import LoopGain
from loopgain.integrations import AutoGenAdapter
team = RoundRobinGroupChat(participants=[generator, verifier])
lg = LoopGain(target_error=0.1, max_iterations=20)
adapter = AutoGenAdapter(
lg=lg,
error_fn=lambda msg: parse_verifier_score(msg.content),
observe_sources={"verifier"},
)
result = await adapter.run(team, task="...")
lg.send_telemetry(
endpoint=...,
token=...,
framework=adapter.framework_name, # "autogen"
)
adapter.run(...)にcancellation_tokenを渡すと、LoopGainが終端状態(ターゲット到達、発振、発散)に達したときにアダプターがそれをキャンセルします。レガシーv0.2のConversableAgent.initiate_chat APIはサポートされていません。v0.4イベント駆動ランタイムを使用してください。
LangChain
.stream(input, **kwargs) / .astream(input, **kwargs)を公開する任意のLangChainエージェントに対してダックタイピングします。現在のlangchain.agents.create_agent() (v1+)とレガシーAgentExecutorの両方です。アダプターは**stream_kwargsをそのまま転送するため、error_fnが見るチャンク形状はエージェントが出力する形状と同じです。
from langchain.agents import create_agent
from loopgain import LoopGain
from loopgain.integrations import LangChainAdapter
agent = create_agent(model="gpt-5-nano", tools=[get_weather])
lg = LoopGain(target_error=0.0, max_iterations=20)
def error_fn(chunk):
if chunk.get("type") != "updates":
return None
# 未解決のツール呼び出しをカウントします。エージェントがツール呼び出しを停止すると0になります。
return sum(
1 for _, update in chunk["data"].items()
if getattr(update.get("messages", [None])[-1], "tool_calls", None)
)
adapter = LangChainAdapter(lg=lg, error_fn=error_fn)
final = adapter.run(
agent,
{"messages": [{"role": "user", "content": "What's the weather?"}]},
stream_mode="updates",
version="v2",
)
lg.send_telemetry(
endpoint=...,
token=...,
framework=adapter.framework_name, # "langchain"
)
レガシーAgentExecutorの場合: stream_mode / version kwargsをドロップするだけです。yieldされる各チャンクはステップごとのAddableDictです(error_fnでintermediate_stepsまたは終端のoutputキーを解析します)。
OpenAI Agents SDK
Runner.run_streamed(agent, input).stream_events()をラップします。SDKは非同期ファーストです。アダプターはそれをミラーリングします。run_syncヘルパーは、同期呼び出し元のために非同期パスをasyncio.runでラップします。
from agents import Agent, function_tool
from loopgain import LoopGain
from loopgain.integrations import OpenAIAgentsAdapter
agent = Agent(name="Reviser", instructions="...", tools=[...])
lg = LoopGain(target_error=0.0, max_iterations=20)
def error_fn(event):
# デフォルトではrun_item_stream_eventのみを観測します。検証器が報告した失敗数をツール出力から取得します。
if event.item.type == "tool_call_output_item":
return float(event.item.output.get("failures", 0))
return None
adapter = OpenAIAgentsAdapter(lg=lg, error_fn=error_fn)
result = await adapter.run(agent, input="Fix the bug.")
print(result.final_output)
lg.send_telemetry(
endpoint=...,
token=...,
framework=adapter.framework_name, # "openai-agents"
)
デフォルトでは、アダプターはrun_item_stream_eventのみをerror_fnに転送します。すべてのイベント(生のトークンデルタやエージェントハンドオフ通知を含む)を表示するには、observe_event_types=Noneを渡します。LoopGainが終端状態に達すると、アダプターは基盤となるRunResultStreamingに.cancel()をベストエフォートで呼び出します。
Claude Agent SDK
Anthropicのclaude_agent_sdk.query(prompt=..., options=...)非同期イテレーターをラップします。デフォルトではAssistantMessageのみを観測します(UserMessage / SystemMessage / ResultMessageはスキップ)。observe_message_types=Noneまたはカスタムタプルでオーバーライドできます。
from claude_agent_sdk import ClaudeAgentOptions, TextBlock
from loopgain import LoopGain
from loopgain.integrations import ClaudeAgentSDKAdapter
def error_fn(message):
# 自己検証ペルソナが出力する`FAIL:`マーカーをカウントします。
for block in getattr(message, "content", []):
if isinstance(block, TextBlock):
return float(block.text.count("FAIL:"))
return None
lg = LoopGain(target_error=0.0, max_iterations=20)
adapter = ClaudeAgentSDKAdapter(lg=lg, error_fn=error_fn)
options = ClaudeAgentOptions(system_prompt="Self-verify each draft.")
result = await adapter.run(
prompt="Write a haiku about feedback loops.",
options=options,
)
lg.send_telemetry(
endpoint=...,
token=...,
framework=adapter.framework_name, # "claude-agent-sdk"
)
双方向のClaudeSDKClientユースケースでは、prompt=...の代わりにmessage_iterator=client.receive_messages()を渡します。
カスタム統合
アダプターがないフレームワークの場合、生のLoopGain.observe() APIは任意のイテラブルに対して機能します。アダプターはそれぞれ100〜200行です。loopgain/integrations/{langgraph,crewai,autogen,langchain,openai_agents,claude_agent_sdk}.pyのいずれかをコピーして開始点としてください。
ステータス
初期パブリックリリース。 コアライブラリが出荷されました(現在のバージョン: 上部のPyPIバッジを参照)。フレームワークアダプター(LangGraph、CrewAI、AutoGen、LangChain、OpenAI Agents SDK、Claude Agent SDK)はオプションの追加機能としてインストール可能です。クラウド集計テレメトリレシーバーとダッシュボードは、個別のオープンソースリポジトリとして稼働しています。数学とAPIサーフェスは安定しています。
これはアルファソフトウェアです。本番環境での使用で設計上の問題が表面化した場合、1.0より前にAPIが変更される可能性があります。バージョンをピン留めしてください。
ライセンス
背景
LoopGainは、バークハウゼン安定基準(Heinrich Barkhausen、1921年 — フィードバックアンプが発振する時期を予測する基礎的な結果)をAIエージェントフィードバックループに適用します。この基準は元々、電子発振器が発振を維持するかどうかを予測する方法でしたが、エラー信号をアタッチできるあらゆるフィードバックループにきれいにマッピングできることが判明しました。
最も明確な要約: 測定可能なエラー信号を持つ反復AIループはフィードバックシステムです。比率E(n) / E(n-1)は、その経験的なループゲインです。バークハウゼン結果は、ループゲインが1未満なら収束し、1に等しければ発振し、1より大きければ発散することを示しています。LoopGainはこれを具体化します。ループの現在のバンドを分類し、何をすべきかを決定します — 停止、続行、またはこれまでに見た最良の出力にロールバックします。
実際に応用されるループの種類:
- 検証・修正ループ (GVRパターン) — ジェネレーターが生成し、検証器が問題を見つけ、修正者が修正します。エラー = 問題数または重み付けスコア。
- 洗練ループ — 初期出力、改善のために反復します。エラー = 目標仕様からの距離 / ルブリックスコア。
- ツール使用リトライチェーン — エージェントがツールを呼び出し、エラー/成功を受け取り、リトライします。エラー = 連続失敗回数または集計スコア。
- 自己修正RAG — 検索、生成、評価、再検索します。エラー = 評価の深刻度または幻覚スコア。
- リンター/テストフィードバック付きコード生成 — 生成、テスト/リンター実行、修正、繰り返し。エラー = 失敗したテスト数またはリンター違反数。
- 多段階推論ループ — ReActスタイルの思考/行動/観察イテレーション。エラー = エージェントの品質評価者が返すもの。
- カスタムフィードバックループ — ループが成功するにつれてゼロに向かうべき数値を生成できるあらゆるもの。