インストール
インストルメンテーション
各スコープが実際に送出するイベント:
スコープ内のコードは
session_id や agent_id を省略できます。スコープはコンテキスト変数にIDをバインドし、すべてのイベント呼び出しがそこから読み取るため、関数にIDを引き回す必要はありません。
3つのスコープはいずれも async with と with の両方で動作します。
エージェントをネストするとツリーが構築されます。parent_id と深さはスタックから自動計算されます:
スコープの終了方法
agent() は例外を自動で処理します:
エラーは
agent_end の前に送出されます。これはダッシュボードが agent_end でスパンを閉じるため、それ以降に発生したイベントはどのスパンにも帰属しなくなるためです。キャンセルは失敗ではないため、キャンセルされた実行はエラーサーフェスを汚染しません。例外は常に再送出されます。スコープが例外を握りつぶすことはありません。
イベントメソッド
6つのファミリーに分類された15のメソッドがあります。ほとんどはペアで提供されます — オープナーを送出し、次にクローザーを送出すると、SDKがその間のスパンを計測します。2つの人間ファミリーは方向が逆です。
どのフレームワークも後者のペアを通知しないため、常に自分で送出する必要があります。
使用例
エージェントフレームワークなしで、OpenAI APIに対してツール呼び出しループを実行する例:docs/manual/examples/ に含まれています。
スレッドと非同期
コンテキスト変数はasyncioタスクに自動的に伝播します。新しいスレッドには伝播しません。スレッドは空のコンテキストで開始されるためです。propagate() なしでは、ワーカーのイベントがセッションなしで着信する代わりに、修正方法を示す TypeError が発生します。これは意図的な設計です。セッションのないイベントはインジェスト側でスキップされつつ 200 が返されるため、無音の失敗となります。それを防ぐためにIDレイヤーが存在します。
アダプターのないフレームワークへのインストルメンテーション
どのエージェントフレームワークにも同じ3つの接合点があります。それらをマッピングすれば、完全なトレースが得られます — 4つの既存アダプターもこれ以上のことはしていません。1
実行を囲む
2
各ツールを囲む
フレームワークのツールラッパーまたはミドルウェアに相当する箇所に追加します。
3
各モデル呼び出しをペアにする
手動計装と自動計装は組み合わせ可能です。 手書きスコープ内で実行されるアダプターは、そのセッションに参加し、そのエージェントを親として設定します。2つのツリーではなく1つのツリーが得られるため、対応フレームワークと独自フレームワークを同時に計装する際に便利です。
AutoGenアダプターがない理由
AutoGenアダプターがない理由
2つの理由があります。上記の3つの接合点が、その両方に対する答えです:
autogen-coreは2025年9月以降メンテナンスされていません。- AG2には他のフレームワークのフックに相当するプロセス全体の登録ポイントがないため、計装するにはすべての構築箇所でエージェントをラップする必要があります。
詳細
記録の実際の仕組みについて。始めるために必要な知識ではありません。フレームワークごとの記録の形
フレームワークごとの記録の形
すべての記録は同じ形をしています。スパンが開き、その中に作業がネストされ、各オープンイベントに対応するクローズイベントがあります。ペアが基本単位です。各クローズイベントには、SDKがオープンイベントからの経過時間として計測したdurationが含まれます。以下は各フレームワークの実際の1回の実行 — SDKに同梱されているサンプルから取得、モデル名は正規化済み。1回の呼び出しでどれだけ多くの情報が返されるかに注目してください。ノードがフックペアになるため、エージェントリストを埋め尽くすことなくノードごとのレイテンシを確認できます。
- LangGraph
- CrewAI
- LlamaIndex
- Pydantic AI
- Custom agents
14 events
セッションの開始と終了
セッションの開始と終了
セッション終了イベントは存在しません。 セッションは閉じるものではなく、同じ
session_id を共有するイベントのグループです。ステータスはトレースの形状から導出されます:つまり、すべてのペアが閉じられるとセッションが終了します。アダプターは
agent_end を自動送出し、テアダウン時にはまだ開いているものをすべて閉じてincompleteとしてマークします — クラッシュした実行は永遠にハングするのではなく、visible gapを持つ done として落ち着きます。これが、1つのセッションが2回の呼び出しにまたがれる理由です。LangGraphの
interrupt() は実行を一時停止し、ルートスパンを意図的に開いたままにします。再開する呼び出しがそれを閉じます。両方の呼び出しが1つのセッションです。ID: session_id、agent_id、および発行者
ID: session_id、agent_id、および発行者
session_id と agent_id はすべてのイベントメソッドでオプションです。省略した場合、囲んでいるスコープから解決されます:TypeError が発生します(インジェストはセッションなしのイベントをスキップしつつ 200 を返します)。スコープはコンテキスト変数にIDをバインドします。asyncioタスクには自動的に伝播しますが、新しいスレッドには伝播しません — ワーカーを failproofai_sdk.propagate() でラップしてください。どのIDを誰が発行するか
アダプターが session_id を解決する方法
最初のマッチが優先されます:- 明示的な
session_idオプション - 呼び出しごとのメタデータ
- 囲んでいる
session()スコープ - フレームワークのメタデータ
- フレームワーク独自の実行ID
agent_id は低カーディナリティに保つ
すべてのダッシュボードサーフェスの主要ファセットであり、LowCardinality(String) カラムです。実行ごとの値を使用するとカラムが劣化し、フィルターのドロップダウンが実行1件につき1エントリで埋まります。アダプターはそのカラムを守ります:実際のIDは
fw_agent_id / fw_run_id に保持されるため、ファセットにならずともクエリ可能です。イベントタイプの一覧 — およびフレームワークごとの記録内容
イベントタイプの一覧 — およびフレームワークごとの記録内容
上記の実行から計測した、フレームワークごとの記録内容:
ダッシュはそのフレームワークにその概念がないことを意味します。
human_pause と human_interrupt は人間がエージェントに働きかけることを表しており、どのフレームワークも通知しません — これらは自分で送出してください。ペア、相関、およびduration
ペア、相関、およびduration
イベントは単独では届きません。1つがスパンを開き、1つが閉じます。クローズイベントには、SDKがオープンイベントからの経過時間として計測したdurationが含まれます。
相関ルール
- マッチするクロージングイベントには同じ
tool_call_id、hook_id、pause_id、またはinput_idを再利用してください。 - SDKは
tool_result、hook_completed、agent_resume、human_inputのduration_msを計算します。これらのメソッドに渡すとValueErrorが発生します。 duration_msはmodel_responseでは受け付けられます。これは実際のプロバイダーレイテンシを知っているのが呼び出し側だけだからです。整数でなければなりません — floatを渡すと呼び出し箇所でValueErrorが発生します(サーバーはそのカラムを符号なし32ビット整数として読み取るため、それ以外はNULLとして保存されます)。- 相関キーはkindとsessionでスコープされます。ツール呼び出しとフックは同じIDを安全に共有でき、2つの並行セッションは衝突なく同じIDを再利用できます。agentによるスコープはありません。あるエージェントで開かれ別のエージェントで閉じられたペアも相関します。これはマルチエージェントフレームワークでは通常のケースです。
request_idはmodel_requestとmodel_responseをペアリングします。指定しない場合、モデルイベントはエージェントごとの順序でペアリングされるため、並行呼び出しではペアが誤ります。- プロセスをまたいで分割されたペアはダウンストリームで相関しますが、SDKはプロセス内のdurationを計算できません。
- ペンディングマップは最大10,000エントリを保持し、満杯になると最古のエントリを削除します。
パッケージの内容と instrument() によるフレームワーク検出の仕組み
パッケージの内容と instrument() によるフレームワーク検出の仕組み
failproofai-sdk をインストールすると、4つのアダプターを含むすべてがインストールされます。extrasが引き込むのはアダプターではなくフレームワークです。import failproofai_sdk は契約上ゼロ依存であり、--no-deps でビルド済みwheelをインストールするテストと、どのフレームワークも sys.modules に到達しないことを証明するテストによって強制されます。自動検出はインストール済みパッケージリストではなく
sys.modules を読み取ります。インストールはしてあるがインポートしていないフレームワークは計装されず、代わりにインポートされることもありません。現在の状態を確認するには:CrewAIがインストールされていないマシンで 代わりに例外を発生させるには
instrument("crewai") を呼び出しても例外は発生しません。 警告をログに記録して () を返すため、1つのフレームワークが欠けていても他を計装するプロセスが停止することはありません。警告には元の ImportError が含まれており、そのメッセージに正確なインストールコマンドが示されています — 修正方法はログに記録されており、隠されていません。FAILPROOFAI_SDK_STRICT=1 を設定してください。このフラグは一度だけ読み取られてキャッシュされます。実行中に設定するのではなく、プロセス起動前にエクスポートしてください。イベントがCloudに届くまでの流れ
イベントがCloudに届くまでの流れ
Spoolがこれを安全にする理由です。エージェントはネットワークをブロックすることなく動作し、Cloudの障害は消失したイベントではなくディレクトリの増大として現れます。各フラッシュは1つのバッチファイルを書き込みます。
.tmp で書き始め、次に fsync、そしてアトミックリネームを行います:.jsonl のみを読み取るため、書き込み途中のファイルを読むことは決してありません。ファイル名にはタイムスタンプ、プロセスID、シーケンス番号が含まれるため、2つのプロセスが同じミリ秒にフラッシュしても衝突しません。キューの上限は10,000イベントで、それを超えると最古のものを削除してログに記録します。デーモンはバッチを送信します。バッチを開いたり書き換えたりしません。編集はデーモンが自身のイベントを書き込む場所で実行されます — バッチが送信される場所ではありません。そのため、APIキーを含むプロンプトやツール引数は、到着時もそのままの状態です。これは意図的な設計です。これらはご自身の計装コールであり、送受信中に書き換えることは、送出したイベントと受け取るイベントが異なるものになることを意味します。デーモンは送信後数ミリ秒以内に各バッチを削除するため、
ls はコレクターと競合し、実際に送出したイベントのごく一部しか表示されません — 何も記録していないSDKと区別がつきません。イベントが実際に届いたかどうかはダッシュボードで確認してください。Spoolが埋まる様子を観察するには、先にデーモンを停止してください。計装が失敗した場合
計装が失敗した場合
すべてのコールバックは再送出のみを行うラッパー内で実行されます。コードは1つの
try の中に置かれ、SDKが行うすべての処理はその外側で実行されます。デフォルトは本番環境では適切ですが、デバッグ時には不適切です。「クラッシュしなかった」ことしか証明できないためです。隠れた失敗を顕在化させるには
FAILPROOFAI_SDK_STRICT=1 を設定してください。よくある問題
スパンが終わらない
スパンが終わらない
オープンイベントに対応するクローズイベントがありません。
model_request に model_response がない、または tool_use に tool_result がない状態です。スコープを使用してください。本体が例外を送出した場合でもペアが保証されます。イベントメソッドを直接呼び出す場合は try と finally を使用してください。duration_ms を渡すと ValueError が発生する
duration_ms を渡すと ValueError が発生する
tool_result、hook_completed、agent_resume、human_input では、対応するオープンイベントからの経過時間として計測されるため拒否されます。model_response では受け付けられます。実際のプロバイダーレイテンシを知っているのが呼び出し側だけだからです。整数でなければなりません。ワーカースレッドのイベントで TypeError が発生する
ワーカースレッドのイベントで TypeError が発生する
スレッドがコンテキストを継承していません。callableを
failproofai_sdk.propagate() でラップしてください。スレッドと非同期 を参照してください。追加フィールドが消えた、または既存フィールドを上書きした
追加フィールドが消えた、または既存フィールドを上書きした
追加フィールドは最後にマージされます。
model や outcome など実際のフィールドと同じ名前を使用すると上書きされ、保存されるカラムが変わります。独自フィールドには名前空間を付けてください。アダプターは fw_ プレフィックスを使用しています。エージェントフィルターのエントリが数千件ある
エージェントフィルターのエントリが数千件ある
agent_id は低カーディナリティのファセットですが、実行IDを設定しています。ロール名やノード名を使用し、実際のIDはペイロードフィールドに格納してください。次のステップ
仕組みを理解する
ペア、ID、セッションのライフサイクル、配信の詳細。
トレースを読む
記録したセッションの因果関係をたどる。
フレームワークアダプター
LangGraph、CrewAI、LlamaIndex、Pydantic AI。

