Bracket : LLMエージェントの実行完結性を契約ベースで判定するPythonライブラリ

LLMエージェントは「ファイルを読んだ」「テストを実行した」と報告しても、実際にはその手順を飛ばしていることがあります。LangGraph や Google ADK のようなエージェントフレームワークは実行自体はうまく行いますが、必要な手順を踏んだかどうかまでは検証しません。

Bracket は、このギャップを埋める小さな Python ライブラリです。実行中の証拠（ファイル読み取り、ファイル変更、コマンド実行、LLM 呼び出しなど）を収集し、事前定義した契約条件と照合して pass/fail を機械的に判定します。LLM が判定するのではなく、コードで定義されたルールが判定します。

解決する問題

• エージェントがファイルを読まずに修正したふりをするケースを検出（read-before-write）
• 「テスト通過確認」のような検証ステップをパイプラインに強制的に注入
• 実行ログを保存し、判定ルールが変わったときに過去の実行を再判定（replay）
• 複数のフレームワークを混在利用する際に検証ロジックを単一化

内蔵プロファイル

• code_change - read-before-write、file changed、verification command が必須
• research - file read、web fetch、grounding evidence
• file_task - file changed、artifact emitted
• text_answer - grounding evidence

すべてのプロファイルには「intent resolved」と「hard failure なし」の条件が含まれます。

対象ユーザーと効果

• エージェントパイプラインを本番環境に載せる必要がある開発者: 「tests pass」のような条件を明示的な契約にして回帰を防止
• 複数のエージェントフレームワークを比較・評価中のチーム: LangChain / LangGraph / Google ADK アダプターがあり、フレームワークを切り替えても同じ判定基準を維持
• Eval / regression パイプラインの運用担当者: .bracket/runs/* JSON ログにより過去の実行を一括再判定可能

インストールと例 pip install bracket

from bracket import Harness, ExecutionContract

contract = ExecutionContract.code_change(goal="Fix failing test") harness = Harness(app_name="my-agent", artifact_dir=".bracket") run = harness.start_run(contract)

run.record_file_read("app.py", byte_count=1842) run.record_file_changed("app.py") run.record_command("pytest tests/", exit_code=0, kind="verification")

result = harness.finish_run_sync(run, final_output="Fixed the bug.") print(result.verdict.outcome) # VERIFIED / BLOCKED / PARTIAL

Python 3.12+、コア部分は外部依存なし。LangChain / LangGraph / Google ADK アダプターは extras として選択インストール可能。

Bracket が目指していないもの

• エージェントフレームワークの代替ではない（LangGraph などと併用）
• Guardrails ではない（入出力フィルタリングではなく実行過程の検証）
• Observability ツールではない（ログビューアではなく pass/fail 判定器）
• Eval プラットフォームではない（応答品質ではなく実行完結性を検証）