Failproof AI Observability Python SDK エージェントスキル

​

計装は書くのは簡単、気づかぬうちに間違えるのも簡単

​

スキルが行うこと（順番に）

1. 計画。 エージェントのループを読み込み、あなたにしか答えられない 2 つの質問をします。「1 回の実行とは何か（session_id）」と「識別可能なアクターは誰か（agent_id）」です。コードを書く前にこれらを合意します。後から変更すると履歴が分断され、トレンドが壊れるからです。
2. 実装。 呼び出しのたびに渡すのではなく、実行ごとに 1 度だけ ID をバインドし、並行処理に安全な形式を選択します。これは重要な細部です。安易なショートカットは、重複する 2 つの実行を無音で 1 つのセッションに混在させてしまいます。
3. 検証。 エージェントを実行して生成されたイベントファイルを読み込み、agent_start が存在するか、環境が正しいか、1 回の実行で 1 つのセッションが生成されたかを確認します。

​

他のスキルとの関係

​

前提条件

1. Python 3.10 以上 と計装対象のエージェントコードベース。
2. SDK。 公開インデックスではなくプライベートホイールとして顧客に配布されます。取得方法とインストール方法はオンボーディングで説明されます。スキルはインストールパスを把握しており、見つからない場合は推測せずに確認します。
3. それ以外は不要。 ダッシュボードへのログイン、API キー、ネットワーク接続は必要ありません。スキルは SDK が書き出すイベントファイルに対して検証するため、オフラインで完了・証明できます。

​

入手方法

npx skills add FailproofAI/skills --skill agenteye-python-sdk -a claude-code

​

手動でインストールする場合

• Claude Code: agenteye-python-sdk/ フォルダを ~/.claude/skills/（すべてのプロジェクト）または <リポジトリ>/.claude/skills/（そのリポジトリのみ）にコピーします。Claude Code は自動的に検出します。/skills リストで確認するか、対応するタスクを尋ねるだけで使えます。
• Codex: Codex も同じ SKILL.md を読み込みます。同梱の agents/openai.yaml に allow_implicit_invocation: true が設定されているため、タスクが一致すれば自動的に選択されます。明示的に呼び出す場合は $agenteye-python-sdk を使用します。

​

セッションの流れ

you   ▸ Add Failproof AI Observability to this agent.

agent ▸ Read your loop — one tool dispatcher in tools.py, one Anthropic
        wrapper in llm.py. Two questions before I write anything.

        What counts as one run? You handle requests concurrently, so I'd
        use the request id you already have in ctx.request_id — then a
        session here and a request in your logs are the same string.

        And who are the actors? I see a planner path and a researcher
        path. Label them separately, or is that one agent to you?

you   ▸ Request id is right. They're one agent, call it "assistant".

agent ▸ Done. Wrapped the dispatcher and the LLM client; agent_start and
        agent_end bracket handle_request, including the error path. Used
        a context-local for identity — your dispatcher runs tools in a
        thread pool, and the simpler approach would have mixed concurrent
        runs into one session without complaining.

        Verified against a real run: 11 events across 4 files —
        agent_start, model_request/response, tool_use/tool_result x3,
        agent_end (outcome=success). environment=production, one session
        per request, durations paired.

        One thing I did NOT do: your worker pool in batch.py submits
        straight to the executor, so events from there would be dropped.
        Want me to fix those too?

​

使い方の例

• 「エージェントがダッシュボードに表示されない」 → 順番に確認します: イベントが書き込まれているか、agent_start はあるか、環境は正しいか、コレクターは同じ場所を読んでいるか。
• 「すべて dev として記録されている」 → 環境が設定されていないか、後続の呼び出しでリセットされています。
• 「トークンのトラッキングを追加して」 → LLM ラッパーを見つけて、モデル、停止理由、使用量を記録します。
• 「サブエージェントも計装して」 → 1 つのセッション、異なるエージェントラベル、親の下にネスト。
• 「計装のテストを書いて」 → SDK を一時ディレクトリに向け、書き込まれたイベントをアサートします。

​

注意事項

​

次のステップ

• Python SDK: このスキルが自動化する処理の背後にある完全なイベントリファレンス — すべてのイベントタイプとフィールド。
• Sessions: イベントが記録されると計装が生み出すもの。
• Evaluator エージェントスキル: 実行が記録されたら次のステップ — スコアリング。
• CLI エージェントスキル: テレメトリの読み取り。