Python SDK

AIエージェントが本番環境で何をしたかを正確に把握する: すべてのエージェント実行、ツール呼び出し、モデルリクエスト、フック、および人間の介入。Failproof AI Observability Python SDKは、エージェントコードの内側からその実行履歴を記録し、何が起きたかをデバッグ・監査・評価できるようにします。Failproof AI Observabilityでエージェントを観測したい場合にご利用ください。内部では、SDKが構造化イベントをローカルのJSONLファイルに書き込み、コレクターデーモンがそれらを自動的に収集してプラットフォームに送信します。これらのファイルを自分で管理する必要はありません。

ヒント: Failproof AI Observabilityを初めてお使いですか？このページはSDKイベントの完全なリファレンスです。

インストール

SDKは公開パッケージインデックスではなく、プライベートホイールとしてお客様に配布されます。取得・インストール・バージョン固定の方法はオンボーディングで説明しています。アクセスが必要な場合は Failproof AI の担当者にお問い合わせください。インストール後、以下で確認してください:

python -c "import agenteye; print(agenteye.__version__)"

コーディングエージェントに統合作業をすべて任せたい場合は、Python SDK Agent Skill をご利用ください。インストールパスを把握し、計装ポイントを計画・実装して、イベントが正しく届いているか検証します。

クイックスタート

import agenteye

agenteye.configure(environment="production")

agenteye.event.agent_start(session_id="run-001", agent_id="planner", goal="answer user query")

agenteye.event.tool_use(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",
    tool_call_id="toolu_01",
    input={"query": "latest AI research"},
)

agenteye.event.tool_result(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",
    tool_call_id="toolu_01",
    output={"results": ["..."]},
)

agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="success")

実際の呼び出しへの計装

実際には、既存のエージェントコードをラップします。モデル呼び出しの前に model_request、後に model_response を配置することで、2つのイベントが実際のリクエストをまたぎ、Failproof AI Observabilityがペアとして関連付けられるようになります:

import anthropic
import agenteye

agenteye.configure(environment="production")
client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Summarise today's incidents."}]

agenteye.event.model_request(
    session_id="run-001",
    agent_id="planner",
    model="claude-sonnet-4-6",
    messages=messages,
)

reply = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=512,
    messages=messages,
)

agenteye.event.model_response(
    session_id="run-001",
    agent_id="planner",
    model=reply.model,
    stop_reason=reply.stop_reason,
    input_tokens=reply.usage.input_tokens,
    output_tokens=reply.usage.output_tokens,
    content=[block.model_dump() for block in reply.content],
)

ツール呼び出しも同様に tool_use と tool_result でラップし、ペア間で同じ tool_call_id を使い回します。ダッシュボードに届いたイベントは、タイプ別に色分けされ、環境・エージェント・セッションでフィルタリングできます:

ライブイベントストリーム。イベントタイプ別に色分けされ、環境・エージェント・セッションでフィルタリング可能

configure()

agenteye.configure(
    base_dir=None,           # Path | str | None. デフォルト: $AGENTEYE_HOME または ~/.agenteye
    flush_interval=0.5,      # float, フラッシュサイクルの間隔（秒）
    environment=None,        # str | None. デプロイ環境ラベル
)

event.* を呼び出す前に一度だけ呼び出してください。省略しても問題ありません。デフォルト設定でそのまま動作します。すべての引数はキーワード専用です。上記のように名前で渡してください。 base_dir が None（デフォルト）の場合、SDKは $AGENTEYE_HOME が設定されていればそれを使用し、未設定の場合は ~/.agenteye にフォールバックします。これはコレクター自身の解決方法と一致しているため、AGENTEYE_ENVIRONMENT 環境変数ひとつで SDK とコレクター両方のイベントスプールを共有設定できます。

環境

すべてのイベントにデプロイ環境のラベルを付けます（production、staging、qa、canary など）。一度設定するだけで、SDKがすべてのイベントに自動的に付加します。 オプション1: configure() 経由:

agenteye.configure(environment="production")

オプション2: 環境変数経由:

export AGENTEYE_ENVIRONMENT=production

優先順位: configure(environment=...) が環境変数より優先されます。どちらも設定されていない場合、デフォルトは "dev" です。環境の値はダッシュボードのファーストクラスフィルターとして表示され、高速クエリのためサーバーに保存されます。

警告: 環境の値にリテラルのカンマ , を含めることはできません。ダッシュボードのフィルターはワイヤー上でカンマ区切りのマルチセレクトを使用するため（?environment=prod,staging）、prod,blue という名前の環境は2つの値に分割されます。カンマを含む環境名のイベントはインジェスト時に拒否されます。

データとプライバシー

SDKは明示的に渡したフィールドのみを記録します。プロンプト、メッセージ、ツールの入出力、モデルのコンテンツは、event.* 呼び出しに渡した場合にのみキャプチャされます。プロセスからの暗黙的な読み取りやキャプチャは一切行いません。未設定のフィールドはイベントから完全に省略され、ディスクに書き込まれません。そのため、データのマスキングはお客様の判断と責任で行ってください。プロンプトやツールのペイロードに保存したくないPIIや機密情報が含まれている場合は、イベントメソッドに渡す前にそれらを除去またはマスクしてください。

イベントリファレンス

ほとんどのイベントは相関IDを共有する開始/終了ペアで構成されています: tool_use と tool_result は tool_call_id を共有し、hook_triggered と hook_completed は hook_id を共有し、human_wait と human_input は input_id を共有します。開始イベントを発行し、処理を実行してから、同じIDで終了イベントを発行してください。Failproof AI Observabilityがペアを照合し duration_ms を自動計算するため、duration_ms を自分で渡す必要はありません。

セッションのgit形式の実行グラフとイベントタイムライン。ペアイベントから再構築され、ツール・モデル・フックの内訳パネルを表示

すべてのイベントメソッドに以下の2フィールドが必須です:

フィールド	型	説明
`session_id`	`str`	トップレベルのエージェント実行を識別する
`agent_id`	`str`	セッション内でイベントを発行したエージェントを識別する

すべてのメソッドはカスタムメタデータ用の任意の **kwargs も受け付けます（カスタムフィールド参照）。

`event.agent_start()`

エージェントが作業を開始したときに発行されます。

agenteye.event.agent_start(
    session_id="run-001",
    agent_id="planner",
    goal="answer user query",   # str | None
    parent_id=None,             # str | None - ネストされたエージェントの親 agent_id
)

`event.agent_end()`

エージェントが作業を完了したときに発行されます。

agenteye.event.agent_end(
    session_id="run-001",
    agent_id="planner",
    outcome="success",          # str | None
    summary="Answered query",   # str | None
)

`event.tool_use()`

エージェントがツールを呼び出したときに発行されます。tool_result とペアにしてください。SDKが duration_ms を自動計算します。

agenteye.event.tool_use(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",     # str, 必須
    tool_call_id="toolu_01",    # str, 必須 - 対応する tool_result との相関キー
    input={"query": "..."},     # dict | None
)

`event.tool_result()`

ツールが返答したときに発行されます。tool_call_id を通じて tool_use と関連付けられます。

agenteye.event.tool_result(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",
    tool_call_id="toolu_01",        # 対応する tool_use と一致させる必要があります
    output={"results": ["..."]},    # Any | None
    error=None,                     # str | None - ツールが例外を発生させた場合に設定
    # duration_ms は自動計算されます - 渡さないでください
)

`event.model_request()`

LLMにプロンプトを送信する直前に発行されます。

agenteye.event.model_request(
    session_id="run-001",
    agent_id="planner",
    model="claude-sonnet-4-6", # str | None - 任意のプロバイダー/モデル文字列。検証なし
    messages=[                   # list[dict] | None - 会話のターン
        {"role": "user", "content": "..."},
    ],
    system="You are helpful.",   # Any | None - 文字列またはコンテンツブロックのリスト
    tools=[                      # list[dict] | None - モデルに提供するツールスキーマ
        {"name": "search", "input_schema": {"type": "object"}},
    ],
)

messages のエントリはプレーン文字列の content でも、Anthropic形式のブロックリストの content でも受け付けます。サンプリングパラメータ（temperature、max_tokens など）は追加のkwargsとして渡せます。

`event.model_response()`

LLMがレスポンスを返したときに発行されます。

agenteye.event.model_response(
    session_id="run-001",
    agent_id="planner",
    model="claude-sonnet-4-6", # str | None - 任意のプロバイダー/モデル文字列。検証なし
    stop_reason="end_turn",     # str | None
    input_tokens=1024,          # int | None
    output_tokens=256,          # int | None
    content=[                    # Any | None - 文字列またはコンテンツブロックのリスト
        {"type": "text", "text": "..."},
    ],
    role="assistant",            # str | None
)

content はプレーン文字列（汎用プロバイダー）またはAnthropic形式のコンテンツブロックのリストを受け付けます。ツール呼び出しは {"type": "tool_use", ...} ブロックとして content 内に含まれます。別途 tool_calls フィールドはありません。

`event.hook_triggered()`

フックが発火したときに発行されます。hook_completed とペアにしてください。SDKが duration_ms を自動計算します。

agenteye.event.hook_triggered(
    session_id="run-001",
    agent_id="planner",
    hook_name="pre_tool_use",   # str, 必須
    hook_id="hook-abc",         # str, 必須 - 相関キー
    trigger_event="tool_use",   # str | None
    input={"tool": "search"},   # Any | None
)

`event.hook_completed()`

フックが完了したときに発行されます。hook_id を通じて hook_triggered と関連付けられます。

agenteye.event.hook_completed(
    session_id="run-001",
    agent_id="planner",
    hook_name="pre_tool_use",
    hook_id="hook-abc",         # 対応する hook_triggered と一致させる必要があります
    outcome="allow",            # str | None
    output=None,                # Any | None
    error=None,                 # str | None
    # duration_ms は自動計算されます - 渡さないでください
)

`event.error()`

未処理のエラーが発生したときに発行されます。

agenteye.event.error(
    session_id="run-001",
    agent_id="planner",
    error_type="TimeoutError",  # str, 必須
    message="timed out",        # str, 必須
    traceback="Traceback...",   # str | None
)

ヒューマン・イン・ザ・ループイベント

ヒューマン・イン・ザ・ループイベントは、エージェントの実行に人間が介入する瞬間（承認待ち、入力提供、一時停止、またはエージェントの停止）を監視するためのものです。これらのイベントにより、人間が応答するまでの時間を計測し（SDKがペアイベントの duration_ms を自動計算します）、誰がエージェントを一時停止または中断したかを監査し、ダッシュボードに表示される承認・監視ワークフローを構築できます。

`event.human_wait()`

エージェントが人間からの入力を待つために実行を一時停止したときに発行されます。human_input とペアにしてください。SDKが duration_ms（人間が応答するまでの時間）を自動計算します。

agenteye.event.human_wait(
    session_id="run-001",
    agent_id="planner",
    input_id="inp-abc",                          # str, 必須 - 対応する human_input との相関キー
    prompt="Do you approve this action?",        # str | None - 人間に表示される質問
    options=["approve", "reject", "defer"],      # list[str] | None - 人間に提示される選択肢
    reason="approval_required",                  # str | None - 待機している理由
)

`event.human_input()`

人間が入力を提供してエージェントが再開したときに発行されます。input_id を通じて human_wait と関連付けられます。duration_ms は自動計算されるため、呼び出し元から渡してはいけません。

agenteye.event.human_input(
    session_id="run-001",
    agent_id="planner",
    input_id="inp-abc",    # str, 必須 - 対応する human_wait と一致させる必要があります
    response="approve",    # str | None - 人間の回答（自由テキストまたは選択肢）
    # duration_ms は自動計算されます - 渡さないでください
)

`event.human_pause()`

人間がエージェントを能動的に一時停止したとき（例: ダッシュボードのコントロール経由）に発行されます。エージェントは中断されますが、終了はしません。

agenteye.event.human_pause(
    session_id="run-001",
    agent_id="planner",
    reason="user_requested",  # str | None
    user_id="usr_42",         # str | None - エージェントを一時停止した人
)

`event.human_interrupt()`

人間がエージェントの実行中に能動的に停止させたときに発行されます。human_pause とは異なり、エージェントの作業は中断ではなく終了します。

agenteye.event.human_interrupt(
    session_id="run-001",
    agent_id="planner",
    reason="output_incorrect",       # str | None
    user_id="usr_42",                # str | None - エージェントを中断した人
    at_step="tool_use:web_search",   # str | None - 停止時にエージェントが実行していた処理
)

カスタムフィールド

追加のキーワード引数は、標準フィールドの後にイベントへ付加されます:

agenteye.event.tool_use(
    session_id="run-001",
    agent_id="planner",
    tool_name="db_query",
    tool_call_id="toolu_02",
    tenant_id="acme",           # カスタムフィールド
    region="us-east-1",         # カスタムフィールド
)

timestamp、type、environment は予約済みであり、カスタムフィールドとして渡すと ValueError（Reserved field names cannot be used as custom fields: [...]）が発生します。session_id と agent_id はすべてのイベントメソッドの必須パラメータであり、2回渡すことはできません。その場合、Pythonは TypeError を発生させます。環境の設定には configure(environment=...) または AGENTEYE_ENVIRONMENT 変数を使用してください。ペイロードのフィールドをクエリしたい場合は、構造化JSONで保持してください。JSON がネイティブにサポートしない値（日時、UUID、Decimal、セット、バイト、モデルオブジェクトなど）は文字列に変換されるため、記録は安全に続行されます。

イベントの書き込み方法

イベントはプロセス内でバッファリングされ、flush_interval 秒ごと（デフォルト500ms）にディスクにフラッシュされます。各フラッシュは1つのJSONLファイルを書き込みます:

~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl

コレクターはこのディレクトリを監視し、ファイルを自動的にアップロードします。これらのファイルを直接管理する必要はありません。各ファイルはアトミックに書き込まれます: SDKは一時ファイルに書き込んだ後、所定の場所にリネームするため、コレクターが書きかけのファイルを読み取ることはありません。プロセス終了時にも最終フラッシュが実行されるため、最後のインターバルでバッファリングされたイベントが失われることはありません。コレクターがオフラインの場合、イベントはディスク上にファイルとして蓄積され、コレクターが復帰次第送信されます。

次のステップ

イベントストリーム: これらのイベントがリアルタイムで届く様子を、タイプ別の色分けと環境・エージェント・セッションによるフィルタリングで確認できます。
セッション: ペアイベントが各エージェント実行を実行グラフとタイムラインとしてどのように再構築するかを確認できます。

Overview

Features

SDK and CLI

Administration

インストール

クイックスタート

実際の呼び出しへの計装

configure()

環境

データとプライバシー

イベントリファレンス

`event.agent_start()`

`event.agent_end()`

`event.tool_use()`

`event.tool_result()`

`event.model_request()`

`event.model_response()`

`event.hook_triggered()`

`event.hook_completed()`

`event.error()`

ヒューマン・イン・ザ・ループイベント

`event.human_wait()`

`event.human_input()`

`event.human_pause()`

`event.human_interrupt()`

カスタムフィールド

イベントの書き込み方法

次のステップ

​インストール

​クイックスタート

​実際の呼び出しへの計装

​configure()

​環境

​データとプライバシー

​イベントリファレンス

​event.agent_start()

​event.agent_end()

​event.tool_use()

​event.tool_result()

​event.model_request()

​event.model_response()

​event.hook_triggered()

​event.hook_completed()

​event.error()

​ヒューマン・イン・ザ・ループ イベント

​event.human_wait()

​event.human_input()

​event.human_pause()

​event.human_interrupt()

​カスタムフィールド

​イベントの書き込み方法

​次のステップ

インストール

クイックスタート

実際の呼び出しへの計装

configure()

環境

データとプライバシー

イベントリファレンス

`event.agent_start()`

`event.agent_end()`

`event.tool_use()`

`event.tool_result()`

`event.model_request()`

`event.model_response()`

`event.hook_triggered()`

`event.hook_completed()`

`event.error()`

ヒューマン・イン・ザ・ループイベント

`event.human_wait()`

`event.human_input()`

`event.human_pause()`

`event.human_interrupt()`

カスタムフィールド

イベントの書き込み方法

次のステップ