agentguard47

AgentGuard

Python の実行時チェックで、暴走するエージェントを止めます。

AgentGuard は、計測機能を組み込んだ Python コードで、予算、ツール呼び出しの繰り返し、再試行、経過時間をチェックします。ガードは例外を発生させるため、アプリケーションは次の操作を停止できます。基本 SDK には実行時依存関係がなく、アカウントも必要ありません。

名称について： このリポジトリは agent47、PyPI パッケージは agentguard47、Python のインポート名は agentguard です。AgentGuard 2.0.0 には Python 3.11 以降が必要です。Python 3.9 または 3.10 では、agentguard47==1.4.0 に固定してください。アップグレードする前に、Python 移行ガイドをご覧ください。

はじめに

仮想環境にインストールしてから、オフラインチェックを実行します。

python -m pip install agentguard47
agentguard doctor
agentguard demo

doctor はインストールとローカルトレースの書き込みをチェックします。demo は、プロバイダーキーやネットワークアクセスなしで、予算、ループ、再試行による停止を試します。出力を確認するには、コマンドが表示するトレースのパスをたどってください。 agentguard demo --feedback は、ローカルで秘匿化したレポートを出力します。データが送信されることはありません。

PowerShell に新規インストールし、すぐに実行できる未加工のスターターを使う場合は、公開リリースの手順に従ってください。

停止レシートを共有する（2.0.0 の新機能）

agentguard receipt agentguard_demo_traces.jsonl は、各停止のレシートを出力します。トレースの SHA-256 はバーコードとして表示されます。PR や issue に貼り付けるには、--format markdown を追加します。ハッシュはトレースファイルを識別するものであり、署名ではありません。この停止レシートには、対象となるガードによる拒否が記録されます。Anthropic 公式の/receiptsプラグインは、過去の Claude Code の作業（デフォルトでは30日分）を要約します。どちらの出力も、支出が防止されたことを証明したり、署名付きの証明書を提供したりするものではありません。agentguard receipt コマンドに変更はありません。

Claude Code セッションをガードする（2.0.0 の新機能）

agentguard hook claude-code --install --write

これにより、同一のツール呼び出しが3回連続した場合と、すでに2回失敗した呼び出しを拒否する Claude Code フックがインストールされます。「同一」の判定では JSON のキー順は無視されますが、値の大文字・小文字と空白は区別されます。オプションの no_progress_max ルールを有効にすると、入力が変化していても、空の結果または同じエラー結果が繰り返された後にツール呼び出しを拒否します。デフォルトでは無効です。拒否時には生の入力は含まれず、.agentguard/claude-code/trace.jsonl に記録されます。 この機能がチェックするのはツール呼び出しであり、トークン数やサブスクリプションの利用枠ではありません。Claude Code フックガイドをご覧ください。

スクリプトを編集せずにガードする（2.0.0で追加）

agentguard run --budget-usd 5 agent.py

これはOpenAIとAnthropicのクライアントにパッチを適用してから、同じインタープリターでagent.pyを実行します。設定は、フラグ、環境変数、.agentguard.jsonの順に読み込まれます。ガードによって停止した場合は、終了コード1で終了します。実行のたびに、トレースのパスが標準エラー出力に表示され、agentguard receiptですぐに利用できます。agentguard run python -m mypkgも動作します。制限は、クライアントに自分でパッチを適用した場合と同じです。適用範囲を参照してください。

サブプロセスは別のインタープリターを起動するため、親プロセスからはパッチが適用されません。分離され、インストルメント化されていない子プロセスは、ガード対象のスクリプトが終了した後も実行を続けることがあります。オフラインでの再現では、ネットワークに接続せず、シミュレーションによる2回の呼び出しでこの制限を示します。

agentguard runは、OllamaなどのOpenAI互換URLを使用するローカルモデルも含め、パッチが適用されたすべての呼び出しに有料料金を適用します。そのため、費用がかからないモデルでも、ドル単位の予算によって停止することがあります。ローカルモデルを使用する場合は、スクリプト内でfree_local_clients=[client]とBudgetGuardのトークン上限または呼び出し上限を指定してクライアントにパッチを適用し、pythonでスクリプトを実行してください。無料のローカルクライアントを参照してください。

3回目の呼び出しの前に停止する

これをbudget_demo.pyとして保存し、python budget_demo.pyを実行してください。ネットワークリクエストは発生しません。

from agentguard import BudgetExceeded, BudgetGuard

budget = BudgetGuard(max_calls=2)
completed = 0

for _ in range(3):
    try:
        budget.check()  # Check before the operation.
        # Put your provider or tool call here.
        completed += 1
        budget.consume(calls=1)  # Record the completed operation.
    except BudgetExceeded:
        print(f"Stopped before call {completed + 1}")

assert completed == 2

期待される出力：Stopped before call 3。

言い換えを繰り返すループを停止する

停止したエージェントは、リトライのたびに言い換えることが多いため、呼び出しがまったく同じ内容で繰り返されないことがあります。max_no_progressは結果を数えます。同じツールからN回連続で空の結果が返るか、同じエラーが返ると、引数にかかわらず実行を停止します。normalize=Trueは、引数の値に含まれる大文字・小文字と空白を保持したまま、コンテナを正規化します。どちらのオプションもデフォルトでは無効です。

from agentguard import LoopDetected, LoopGuard

loop = LoopGuard(normalize=True, max_no_progress=3)

for pattern in ["retry_count", "retryCount", "retries"]:
    loop.check("grep", {"pattern": pattern})
    matches = []  # Put your search here. This one finds nothing.
    try:
        loop.record_result("grep", matches, tool_args={"pattern": pattern})
    except LoopDetected as stop:
        print(stop)

期待される出力：No progress: grep came back empty 3 times in a row (limit: 3). Change the approach instead of rewording the call. trace_toolでラップした関数は、結果を自動的にガードに渡します。その間に別の結果が返ると回数がリセットされるため、ページネーションや編集後のテストのサイクルでは誤って停止しません。

プロバイダーに接続する

プロバイダーのクライアントは別途インストールしてください。OpenAIの場合：

python -m pip install openai

from agentguard import BudgetGuard, JsonlFileSink, Tracer, patch_openai

budget = BudgetGuard(max_cost_usd=5.00)
tracer = Tracer(
    service="my-agent",
    sink=JsonlFileSink(".agentguard/traces.jsonl"),
)
patch_openai(tracer, budget_guard=budget)
# Make your OpenAI chat.completions.create or responses.create calls after this setup.

パッチを適用する前に作成した標準のOpenAIクライアントも、パッチ適用前に取得したリソースオブジェクトも対象になります。リクエストの送信、バインド済みメソッドの保存、またはレスポンスヘルパー（生のものやストリーミング用のもの）の保存を行う前に、パッチを有効にしてください。保存済みの参照が元の呼び出し可能オブジェクトを保持している場合があります。有効化した後に作り直してください。patch_openai_async()は非同期クライアントを対象とし、agentguard.init()は両方を有効にします。適用範囲を参照してください。

パッチは、記録済みの使用量をディスパッチ前に確認し、レスポンスの使用量をその後に記録します。ストリーミング呼び出しでは、最終的な使用量が届いてから記録します。レスポンスによって、残りのコスト上限やトークン上限を超えることがあります。同時リクエストでは、容量は予約されません。Chat Completionsのストリームでは、呼び出し側がすでに指定していない限り、include_usageをリクエストします。

OpenAI Agents SDKはresponses.createを使用するため、Runnerの実行前にagentguard.init()を呼び出すと、すべてのモデル呼び出しが予算の対象になります（例）。ホスト型ツールとbackground=Trueのレスポンスは対象外です。セットアップ、トレース、フレームワークのスターターについては、スタートガイドを参照してください。

強制の仕組み

flowchart TD
    accTitle: AgentGuard operation checks
    accDescr: Check a limit before an operation, then record usage.
    A[Instrumented operation] --> B{Guard check}
    B -->|Limit reached| C[Raise exception]
    B -->|Allowed| D[Run operation]
    D --> E[Record usage and trace]
    E --> A

文章で表すと、操作の前にチェックし、許可されていれば実行してから、使用状況を記録します。ガード例外が発生すると、制御はアプリケーションのエラーハンドラーに戻ります。

ガード	チェック内容	発生する例外
BudgetGuard	記録された呼び出し数、トークン数、または推定コスト	BudgetExceeded
LoopGuard	ツールの繰り返し呼び出し。言い換えられた呼び出しも検出するには、normalize=True と max_no_progress=N を有効にします	LoopDetected
FuzzyLoopGuard	ツールの呼び出し頻度と交互に呼び出すパターン	LoopDetected
RetryGuard	ツールごとの再試行回数	RetryLimitExceeded
TimeoutGuard	チェック時の経過時間	TimeoutExceeded
RateLimitGuard	1分間のスライディングウィンドウ内の呼び出し数	BudgetExceeded
X402SpendGuard	支払いコールバックの前に支払い額をチェックします	BudgetExceeded

タスクの予算には、BudgetGuard.goal(...) を使用します。シグネチャとデフォルト値については、ガードのソース と 公開エクスポート をご覧ください。

予算は実行をまたいで保持することもできます。JsonFileStateStore、共有の key、および日次カウンター用の period="day" を設定します。80% 到達時に警告するには、warn_at_pct=0.8 と on_warning コールバックを設定します。ワーカー間でストアとキーを共有するには、明示的な設定が必要です。子エージェントへの予算の継承は自動ではありません。月次の SDK 制限は実装されていません。機能マトリックスをご覧ください。

制限とセキュリティ

• ガードが対象とするのは、計装した操作です。パッケージをインストールしても、Cursor、Claude Code、その他のエージェントのすべてのアクションを傍受するわけではありません。
• ガードはサンドボックスでも権限システムでもありません。許可された操作であっても、破壊的な結果を招く可能性があります。
• タイムアウトチェックでは、すでにブロックされている関数を中断したり、プロバイダーのサーバー上で実行中のエージェントをキャンセルしたりすることはできません。
• コストの推定値は請求額ではありません。報告されたコストを指定するか、推定では不十分な場合は厳密なコスト解決を使用してください。
• 記録済み予算の事前チェックでは、保存された使用量がすでに上限に達している場合、次の計装済み呼び出しを拒否します。同時に実行中のリクエストを予約したり、次の応答を予測したり、プロバイダーのサブスクリプションに上限を設けたりするものではありません。強制の境界をご覧ください。
• 基本 SDK は標準ライブラリを使用します。オプションのフレームワーク用追加機能をインストールすると、サードパーティーの依存関係が追加されるため、個別にセキュリティレビューを行う必要があります。
• オプションの [crewai] 追加機能は ChromaDB を取得します。2026-09-12 の監査では、PYSEC-2026-311 / CVE-2026-45829 を含む、未解決のアドバイザリーが 4 件見つかりました。この追加機能をインストールする前に、そのリスクを確認してください。基本 SDK のインストールには ChromaDB は含まれません。
• トレースの内容にはアプリケーションデータが含まれる場合があります。共有したり、リモートの送信先を設定したりする前に、内容を確認してください。

セキュリティに関する報告、日付付きの依存関係監査、および リリースノートをご覧ください。監査結果が示すのは記録された時点の状況であり、恒久的な安全性を保証するものではありません。

ローカルトレースとオプションのホスト型取り込み

SDK は、無料で利用できるローカルでの確認手段です。まずローカルで始めてください。履歴の保持、アラート、チームでの可視性、支出の推移、ホスト型の意思決定履歴、またはダッシュボードで管理するリモートキルシグナルが必要になった場合にのみ、ホスト型の取り込みを追加してください。

ローカルガードが引き続き強制の主体となります。HttpSink はトレースイベントと意思決定イベントをミラーリングしますが、それ自体でリモートキルシグナルを実行することはありません。設定する前に、ダッシュボードの仕様をご覧ください。

ローカルでの使用には、ホスト型イベントの上限、保持期間、API キーの割り当てはありません。ネットワークへの送信には、HttpSink や OpenTelemetry エクスポーターなど、設定したインテグレーションが必要です。

ローカル SDK から情報が外部へ送信されることはありません。AgentGuard のウェブサイトでは、オプションのホスト型サービスについて説明しています。

ドキュメント

目的	こちらをご覧ください
呼び出しを実際に停止する経路を確認する	適用境界
インストールして初回実行を追跡する	はじめに
ガイドとソース参照を探す	ドキュメントインデックス
実行可能な例を試す	例
LangChain、LangGraph、または CrewAI に接続する	統合ガイド
MCP を通じてホストされたデータを調べる	読み取り専用の TypeScript MCP サーバー
MCP を通じてローカルの予算ツールを使う	Python 予算 MCP サーバー
AI アシスタントでナビゲートする	AI ドキュメントインデックス
修正に貢献する	貢献ガイド
変更内容を確認する	変更履歴

サポートとメンテナンス

Patrick Hughes がメンテナンスしています。 バグを報告する際は、パッケージのバージョン、最小限の再現手順、期待される結果を添えて こちらからお知らせください。脆弱性は SECURITY.md を通じて報告してください。

ソースメタデータでブランチのバージョンを定義しています。PyPI バッジは 公開済みのバージョンにリンクしています。ドキュメントの例とローカルリンクは CI でテストされます。 PyPI の README は、この README と変更履歴から生成されます。

MIT ライセンス。