カスタムエージェント

すべての設定・メソッド・フィールドの説明です。初めてインストルメント化する場合はガイドから始めてください — このページはリファレンス用です。

カスタムエージェントガイド

インストール、インストルメント化、イベントメソッド、実装例、よくある問題。

フレームワークを使用していますか？

LangChain、CrewAI、LlamaIndex、Pydantic AI は1回の呼び出しで自動的にインストルメント化されます。

Python 3.10 以降。実行時の依存関係なし。

インストール

pip install failproofai-sdk

パッケージは failproofai-sdk としてインストールされ、Python では failproofai_sdk としてインポートします。failproofai-sdk[langgraph] のようなフレームワーク追加パッケージはフレームワーク本体もインストールしますが、アダプターは常にベースのホイールに含まれています。

Failproof デーモンへの接続

ダッシュボード
CLI

Admin → Keys に移動し、events:add 権限を持つキーを作成します。
エージェントマシン上で Failproof デーモンをクラウドに接続します。
インストルメント化したセッションを1つ実行し、Observe → Events でその正確な ID を確認します。
Observe → Sessions に移動し、同じ環境を選択して再構成されたトレースを開きます。

failproofai config \
  --connect https://app.befailproof.ai \
  --token <events-add-key>
failproofai config --status

設定

import failproofai_sdk

failproofai_sdk.configure(
    base_dir=None,
    flush_interval=0.5,
    environment="production",
)

引数	説明
`environment`	すべてのイベントに付くラベル — `production`、`staging`、`prod-eu` など。デフォルトは `dev`。
`flush_interval`	バックグラウンドスレッドがディスクに書き込む頻度（秒）。デフォルトは `0.5`。
`base_dir`	書き込み先。デフォルトはデーモンのスプールで、特別な理由がない限りこのままにしてください。

環境変数で設定する場合:

変数	説明
`AGENTEYE_ENVIRONMENT`	コードを変更せずに `environment` を設定します。ラベルがアプリではなくデプロイメントに属する場合に使用します。`configure()` の引数はこれより優先されます。
`FAILPROOFAI_HOME`	スプールを保持する Failproof AI のルートディレクトリを変更します。
`FAILPROOFAI_SDK_STRICT`	`1` に設定すると、インストルメント化エラーがログ記録ではなく例外として発生します。
`FAILPROOFAI_SDK_STRICT_INTEGRATIONS`	`1` に設定すると、フレームワークの互換性問題が警告を出して続行するのではなく例外として発生します。

environment にカンマを使用しないでください。 インジェストはそのフィールドをカンマで分割してフィルターを構築し、ラベルにカンマが含まれるイベントはすべてスキップされます — そのため実行全体がサイレントに消えてしまいます。prod,eu ではなく prod-eu と記述してください。configure(environment="prod,eu") は即座に例外を発生させるので問題にすぐ気づけます。AGENTEYE_ENVIRONMENT は例外を発生させられません（呼び出し元がないため）— 1回警告を出して dev にフォールバックします。

イベントはメモリ内でキューに入れられ、flush_interval 秒ごとにバックグラウンドで書き込まれます。インタープリター終了時に最終フラッシュが行われます。プロセスが強制終了された場合、まだ書き込まれていないデータは失われます。

ID

すべてのイベントはセッションとエージェントに属します。スコープが両方を自動的に設定するため、通常は渡す必要はありません:

with failproofai_sdk.session():
    with failproofai_sdk.agent("planner"):
        failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1")

session_id や agent_id を明示的に渡すことも可能で、その値が優先されます。バインドも渡しもされていない場合、クラウドが静かに破棄するようなイベントを送信するのではなく、TypeError が発生します。

ID はコンテキスト変数で管理されます。asyncio タスクには自動的に引き継がれますが、新しいスレッドには引き継がれません — ワーカーを failproofai_sdk.propagate() でラップしないと、そのイベントは未紐付けになります。

イベントカタログ

15のメソッドがあります。ほとんどはペアになっています — オープナーを呼び出してからクローザーを呼び出すと、SDK がその間隔を計測します。

	オープン	クローズ
エージェント	`agent_start`	`agent_end`
	`agent_pause`	`agent_resume`
モデル	`model_request`	`model_response`
ツール	`tool_use`	`tool_result`
フック	`hook_triggered`	`hook_completed`
人間	`human_wait`	`human_input`

単独で使用するものが3つあります: error、human_pause、human_interrupt。

メソッドごとの全フィールド

すべてのメソッドは session_id と agent_id も受け取りますが、スコープが自動的に設定します。None のままの値は JSON の null として送信されるのではなく省略され、すべてのメソッドは None を返します。

メソッド	必須	任意
`agent_start`	—	`goal`, `parent_id`
`agent_end`	—	`outcome`, `summary`
`agent_pause`	`pause_id`	`reason`, `user_id`
`agent_resume`	`pause_id`	`reason`, `user_id`
`model_request`	—	`model`, `messages`, `system`, `tools`, `request_id`
`model_response`	—	`model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role`, `request_id`, `duration_ms`
`tool_use`	`tool_name`, `tool_call_id`	`input`
`tool_result`	`tool_name`, `tool_call_id`	`output`, `error`
`hook_triggered`	`hook_name`, `hook_id`	`trigger_event`, `input`
`hook_completed`	`hook_name`, `hook_id`	`outcome`, `output`, `error`
`error`	`error_type`, `message`	`traceback`
`human_wait`	`input_id`	`prompt`, `options`, `reason`
`human_input`	`input_id`	`response`
`human_pause`	—	`reason`, `user_id`
`human_interrupt`	—	`reason`, `user_id`, `at_step`

実行を失敗としてマークするには、outcome が failed、error、timeout、または rejected のいずれかでなければなりません。惜しい "failure" を含め、それ以外はすべて成功とみなされます。

ペアリングと所要時間

ルールは1つ: クローズイベントにオープナーと同じ ID を渡すこと。 それがペアリングの方法であり、SDK が間隔を計測できる理由です。

ペア	マッチング基準
`tool_use` → `tool_result`	`tool_call_id`
`hook_triggered` → `hook_completed`	`hook_id`
`agent_pause` → `agent_resume`	`pause_id`
`human_wait` → `human_input`	`input_id`
`model_request` → `model_response`	`request_id`

duration_ms を自分で渡さないでください。 SDK が計測し、渡すと ValueError が発生します。唯一の例外は model_response で、実際のプロバイダーレイテンシを知っているのはあなただけです。ミリ秒の整数値を渡してください — float を渡すと例外が発生します。このカラムは 32 ビット整数のため、float だと空になってしまいます。

エッジケース

ID はペアの種類ごと、セッションごとに一意であれば十分です。 ツール呼び出しとフックが同じ ID を共有することも、同時に実行中の2つのセッションが同じ ID を再利用しても衝突しません。
エージェントにスコープされません。 あるエージェントの下でオープンされ、別のエージェントの下でクローズされたペアも正しくマッチします — マルチエージェントコードでは通常のケースです。
request_id は任意ですが推奨します。 これがないと、モデルイベントは到着順にペアリングされるため、同じエージェント内の2つの並行呼び出しが誤ってペアリングされる可能性があります。
プロセスをまたいだペアはクラウドでも正しくマッチしますが、SDK は計測できません — どのプロセスも両方のハーフを見ていないためです。
最大 10,000 個のオープナーがクローザーを待機できます。 それを超えると最も古いものが破棄されるため、リークが無限に増え続けることはありません。

独自フィールド

渡した追加のキーワードはイベントとともに保存されます:

failproofai_sdk.event.tool_use(
    tool_name="search", tool_call_id="c1",
    fw_tenant="acme", fw_region="eu-west-1",     # 独自フィールド
)

後でクエリしたい場合は JSON 型を使用してください。それ以外 — UUID、datetime、Decimal、set、bytes、モデルオブジェクト — は文字列として保存されます。

フィールド名にプレフィックスを付けてください。 追加フィールドは最後に適用されるため、model、tool_name、outcome という名前のフィールドは実際の値をサイレントに上書きします。フレームワークアダプターは fw_ を使用しているので、同様にすれば衝突しません。これがスペルミスのある任意フィールドがエラーにならない理由でもあります — 単に新しいカスタムフィールドになるだけです。クラウドで標準フィールドが見当たらない場合は、まずスペルを確認してください。

以下の5つの名前は予約済みで、使用すると拒否されます: timestamp、session_id、agent_id、type、environment。

配信と確認

ダッシュボード
CLI

Observe → Events で、最初に agent_start が存在し、最後に agent_end が存在することを確認します。次に Observe → Sessions を開いて、モデル、ツール、人間、フック、エラーのイベントが意図した順序で表示されていることを確認します。セッション ID をトラブルシューティングの主要キーとして使用してください。

failproofai flush --wait --timeout 60
failproofai config --status
fp sessions --since 1h --env production --session-id <session-id>
fp events --since 1h --session-id <session-id> --full

クラウドが空の場合は $FAILPROOFAI_HOME/custom-agents/events、それ以外は ~/.failproofai/custom-agents/events を確認してください。JSONL ファイルがあれば SDK からの送信が証明されます。スプールが増加し続ける場合はデーモンの設定または配信の問題、スプールが空の場合はインストルメント化またはプロセスのライフタイムの問題です。

スプールはデーモンが停止しているときのみ確認してください。デーモンが動作中の場合、数ミリ秒ごとにバッチを収集・削除するため、ディレクトリ一覧はコレクターと競合し、実際に送信されたイベント数より大幅に少なく表示されます。

カスタムランタイムでの障害防止

監査結果とリンクされたトレースを使用して、安全でないアクション、必要なエビデンス、意図したレスポンスを定義します。カスタムエンフォースメントの統合では、実行前にアクションを公開し、その構造化された入力をポリシーエンジンに渡して、resulting allow、instruct、または deny の決定を適用する必要があります。 Failproof AI にお問い合わせください。ランタイムのモデル、ツール、ライフサイクル境界をポリシーフックにマッピングし、統合の検証をお手伝いします。

Connect your agents

Reference

カスタムエージェント