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

​

計装は書きやすい分、静かに間違えやすい

​

スキルの動作手順

1. 計画する。 エージェントのループを読み込み、あなたにしか答えられない 2 つの問いを立てます。「1 回の実行とは何か（session_id）」と「識別可能なアクターは誰か（agent_id）」です。コードを書く前にこれを合意します。後から変更すると履歴が分断され、トレンドが壊れるからです。
2. 実装する。 すべての呼び出し箇所に渡すのではなく、1 回の実行につき 1 度だけアイデンティティをバインドし、並行処理に安全な設計を選択します。単純な近道では、並行する 2 つの実行が 1 つのセッションに無言で混入してしまうため、この選択が重要です。
3. 検証する。 エージェントを実行し、生成されたイベントファイルを読み込んで、agent_start が存在するか、環境が正しいか、1 回の実行が 1 つのセッションを生成しているかを確認します。

​

他のスキルとの関係

​

前提条件

1. Python 3.10 以上 と計装したいエージェントのコードベース。
2. SDK。 パブリックのパッケージインデックスではなく、プライベートの wheel としてお客様に配布されます。入手方法とインストール方法はオンボーディング時にご案内します。スキルはインストールパスを把握しており、見つからない場合は推測せずに確認します。
3. それだけ。 ダッシュボードへのログイン、API キー、ネットワーク接続は不要です。SDK が書き込んだイベントファイルを使って検証するため、オフラインで作業を完了し、証明できます。

​

入手方法

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

​

手動インストール

• Claude Code: agenteye-python-sdk/ フォルダを ~/.claude/skills/（すべてのプロジェクト）または <your-repo>/.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 エージェントスキル: テレメトリの読み返し。