AIエージェントの「見えないバグ」：ツール呼び出しの無視という構造的欠陥

AIエージェントの開発において、最も厄介な欠陥は「ロジックが正しく見えるが、実際にはエラーを無視して処理が進んでいる」ケースである。LLMがツール呼び出しからエラーレスポンスを受け取ったにもかかわらず、そのエラーを無視して次のステップへ進んでしまう。これは単なる出力の品質問題ではなく、エージェントの制御フローが構造的に壊れていることを意味する。

従来のテスト手法は「出力が期待値と一致するか」を検証するものであり、これは論理的な正しさを問う。一方、本記事で扱うのは構造的な整合性である。つまり、エラーが返された後にその結果が副作用のある処理に渡されていないか、呼び出しの引数がスキーマに適合しているか、といった実行トレースの構造そのものに対する検証である。

この構造的欠陥は、LLMの出力判定に依存せず、実行トレースの静的解析だけで検出可能である。本記事では、その決定論的な検出アプローチとCIへの組み込み方を解説する。

tracelintの原理：LLM依存のない決定論的チェックランナー

tracelintは、LLMによる判定を行わず、実行トレースを読み取って構造的なバグを決定論的にフラグ付けするランナーである。同一のトレースに対しては常に同一の結果を返すため、CIパイプラインにおける再現性の問題が本質的に消える。

設計面では、MITライセンスで公開されており、Python 3.10〜3.12に対応する。依存関係はjsonschemaとstdlibのみであり、仮想環境の構築コストが極めて低い。これはSREチームがCI環境に追加する際の摩擦を最小限に抑える意図がうかがえる。

入力形式として、OpenInference（OpenTelemetryのセマンティック規約に基づくLLM呼び出し追跡仕様）、Langfuse、OpenAIメッセージ形式などを直接読み取れる。OpenInferenceはArize PhoenixやAXとネイティブに連携しており、OpenTelemetry互換の観測基盤を既に構築しているチームにとっては、追加のインストルメンテーションなしで導入できる。

検出ルールとトレードオフ：何を守り、何を許容するか

tracelintの検出ルールは、CIへの影響度に応じて二層に分類される。必須ルールは安全性の根幹に関わるものであり、違反時にCIを即座に失敗させる。一方、候補ルールはヒューリスティックな警告として扱われ、CIの通過を妨げない。

必須ルールとして、R1（ツール呼び出しの引数がJSON Schemaに違反）、R6（引数が有効なJSONでない）、R2a（ツールがエラーを返した）、R2b（エラー結果が後の副作用のある呼び出しで再利用された）がある。これらは「エージェントが壊れている」ことを示す直接的な証拠であり、例外を許容する合理的な根拠がほぼ存在しない。

候補ルールとして、R3（推論の起源から導出できない値、いわゆる幻覚的な引数）、R4・R5（ループや冗長な呼び出し）がある。これらの検出にはコンテキスト依存の判断が関わるため、誤検出の確率が高い。CIを失敗させると開発者の信頼を損なうため、警告としてログに出力する設計が推奨される。

すべての警告をエラーに昇格させると、ルール追加のたびにメンテナンスコストが増大し、最終的にチームがゲートを無視する状態に陥る。リスクベースでフィルタリングし、必須ルールを厳格に守りつつ候補ルールは段階的に評価する運用が現実的である。

分類検出対象CIへの影響判断根拠
必須（R1, R6）JSON Schema違反・無効なJSON失敗構造的に不正な呼び出し
必須（R2a, R2b）エラー返却・エラー結果の再利用失敗制御フローの破綻
候補（R3）幻覚的な引数値警告コンテキスト依存・誤検出リスク
候補（R4, R5）ループ・冗長な呼び出し警告ヒューリスティック判定

CIゲート設計：exit codeに基づくパイプライン制御

tracelintはexit codeで結果を明確に区別する。0はクリーン（欠陥なし）、2は構造的欠陥の検出、3は入力エラー（トレースファイルの形式不正など）を示す。この三値の区別が重要であり、特に3は「トレースが読めなかった」という運用上の問題であり、エージェントの品質問題ではない。

CIスクリプトではexit code 2のみをビルド失敗として扱う。0は正常終了、3は警告ログの出力として処理する。この設計により、LLMの確率的な振る舞いによる一時的なエラー（候補ルールの警告）と、構造的なバグ（必須ルールの違反）を混同せずに処理できる。

flowchart TD
    A["CIジョブ開始"] --> B["エージェント実行トレースを生成"]
    B --> C["tracelintを実行"]
    C --> D{"exit code"}
    D -->|"0"| E["パスト: 正常終了"]
    D -->|"2"| F["失敗: 構造的欠陥を検出"]
    D -->|"3"| G["警告: 入力エラーをログ出力"]

実装手順：ローカル検証からCI統合までのステップ

まずローカルで動作を確認する。pip installでtracelintをインストールし、demoコマンドを実行するとHTMLレポートが生成される。このレポートを手動で確認し、どのルールがどの程度の頻度で発火するかを把握しておくことが重要である。

次に、エージェントコード側でOpenInference形式のトレースデータを出力するように変更する。既存の観測基盤がOpenTelemetry互換であれば、インストルメンテーションライブラリの追加で済む場合が多い。

CI上の統合は最小限のスクリプトで実装できる。tracelintを実行し、exit code 2の場合にビルドを失敗させる。以下は概念例である（実際のシェル構文はCIプロバイダに合わせて調整すること）。

# 概念例: CIスクリプトの骨子
tracelint run --input traces/agent_run.json
exit_code=$?
if [ $exit_code -eq 2 ]; then
  echo "構造的欠陥を検出しました"
  exit 1
elif [ $exit_code -eq 3 ]; then
  echo "警告: トレースの入力エラー"
fi

設計上の落とし穴と回避策

トレースフォーマットの互換性：OpenInference以外の形式（例えば独自フォーマット）を使用している場合、tracelintが直接読み取れる形式への変換レイヤーが必要になる。変換ロジック自体がバグの温床になるため、可能な限り標準形式に統一することを優先すべきである。

過剰な警告の抑制：初期段階で候補ルールの警告が大量に出力されると、開発者がレポートを開かなくなる。導入直後は必須ルールのみを有効にし、候補ルールは数週間運用して誤検出率を確認した上で段階的に有効化していくアプローチが現実的である。

依存関係の最小化の限界：stdlibとjsonschemaのみという制約は環境構築の簡素化に大きく寄与する。ただし、高度な解析（例えばトレース間の相関分析や時間軸上のパターン検出）には限界がある。将来的には外部ツールとの連携が必要になる可能性を設計段階で考慮しておくとよい。

まとめ：信頼性の高いAIエージェント開発への一歩

tracelintの導入により、LLMの非決定性を品質ゲートから排除し、構造的整合性のみでデプロイ可否を判定できる。exit code 2という単一のシグナルで「このエージェントは構造的に壊れている」を決定論的に伝えられる点が、従来のLLM-as-a-judge方式との本質的な違いである。

CIゲートとして組み込むことで、デプロイ前に「見えないバグ」をブロックする安全網が得られる。今後はより高度なルールの追加や、追加のトレースフォーマットへの対応が進むことで、エージェントの品質保証の標準的な構成要素として定着することが期待される。

関連記事

参考

本記事は海外の技術トレンド「Your agent ignored a failed tool call. Here's how to catch that in CI.」（DEV）で話題のテーマをもとに、両儀システムソリューションズが独自に解説したものです。

記事一覧に戻る