sf-ai-agentforce-observability: Agentforce Session Tracing 抽出と分析

このスキルは、単なるテストではなく トレースベースの可観測性 が必要な場合に使用します。Session Tracing Data Model (STDM) レコード抽出、Parquet データセット操作、セッションタイムラインの再構築、トピック/アクションレイテンシーの分析、または Data 360 テレメトリからのエージェント動作デバッグを行います。

このスキルがタスクを所有する場合

以下の作業に sf-ai-agentforce-observability を使用してください:

• Data 360 / Session Tracing の抽出
• Agentforce テレメトリからの .parquet ファイル
• セッションタイムラインの再構築
• トピックルーティング、アクション失敗、またはレイテンシーのトレースベースデバッグ
• 大規模テレメトリデータセットの Polars / PyArrow ベース分析

以下の場合は他のスキルに委譲してください:

• エージェントの正式なテスト → sf-ai-agentforce-testing
• Apex ログのデバッグ → sf-debug
• エージェント自体の作成または再構成 → sf-ai-agentforce または sf-ai-agentscript

---

存在する必要な前提条件

抽出前に以下を確認してください:

• Data 360 が有効になっている
• Session Tracing が有効になっている
• Salesforce Standard Data Model のバージョンが十分である
• 組織で Einstein / Agentforce 機能が有効になっている
• Data 360 アクセス用の JWT / ECA 認証が構成されている

認証が不足している場合は以下に委譲してください:

• sf-connected-apps

詳細なセットアップガイド:

• references/auth-setup.md

---

このスキルが対応する内容

コアストレージ / 分析モデル

• Data 360 API 経由の抽出
• ストレージ効率のための Parquet
• 大規模遅延分析のための Polars

コア STDM エンティティ

最小限、以下の作業を想定してください:

• session
• interaction / turn
• interaction step
• moment
• message

GenAI Trust Layer / 監査レコードも、コンテンツ品質と生成デバッグに関連する可能性があります。

完全なスキーマ:

• references/data-model-reference.md

---

最初に収集すべき必須コンテキスト

以下を確認または推測してください:

• ターゲット組織のエイリアス
• 時間ウィンドウまたは日付範囲
• エージェントフィルター (該当する場合)
• 目標が抽出、概要分析、または単一セッションデバッグのいずれであるか
• 抽出データの出力場所
• ユーザーがディスク上に Parquet ファイルを既に持っているかどうか

---

推奨ワークフロー

1. セットアップと認証を確認

Data 360 トレースが存在し、JWT/ECA 認証が機能していることを確認します。

2. 抽出モードを選択

ニーズ	デフォルトのアプローチ
最近のテレメトリスナップショット	直近 N 日間を抽出
焦点を絞った調査	日付とエージェントでフィルタリングして抽出
壊れた会話 1 つ	単一セッションツリーを抽出またはデバッグ
継続的な使用状況分析	段階的な抽出

3. Parquet に抽出

抽出ロジックを再実装するのではなく、scripts/ の提供されたスクリプトを使用してください。

4. Polars で分析

一般的な分析目標:

• セッションボリュームと期間
• トピック分布
• アクションステップの失敗
• レイテンシーのボトルネック
• 放棄 / エスカレーションパターン
• セッションレベルのタイムラインの再構築

5. 調査結果を次のアクションに変換

典型的な成果:

• トピック不一致 → ルーティングまたは説明を改善
• アクション失敗 → Flow / Apex 実装を検査
• レイテンシーの問題 → ダウンストリームアクションパスを最適化
• テストギャップ → ターゲット設定されたエージェントテストを追加

---

高シグナル運用ルール

• STDM を 読み取り専用テレメトリ として扱う
• 摂取ラグを予期する。これは完全なリアルタイムデバッグではありません
• 日付フィルターと焦点を絞った抽出を使用して、不要なボリューム / クエリコストを回避する
• アドホック JSON よりも耐久性のある分析のために Parquet を推奨
• 大規模データセットに遅延 Polars パターンを使用

一般的な落とし穴:

• データが欠落していることが問題を意味すると想定し、実はトレースが有効になっていない場合
• 日付またはエージェントフィルターなしで膨大で広範なクエリを実行
• このスキル内でエージェントを修正しようとし、作成 / テストスキルに委譲する代わり

---

出力形式

完了時に、この順序で報告してください:

1. 抽出または分析されたデータ
2. スコープ (組織、日付、エージェントフィルター、セッション ID)
3. 主な調査結果
4. 根本原因の可能性
5. 推奨される次のスキル / 次のアクション

推奨される形式:

Observability task: <extract / analyze / debug-session>
Scope: <org, dates, agents, session ids>
Artifacts: <directories / parquet files>
Findings: <latency, routing, action, quality, abandonment patterns>
Root cause: <best current explanation>
Next step: <testing, agent fix, flow fix, apex fix>

---

クロススキル統合

ニーズ	委譲先	理由
認証 / JWT セットアップ	sf-connected-apps	Data 360 アクセス
エージェントルーティング / 動作の修正	sf-ai-agentscript	作成の修正
正式な回帰 / カバレッジテスト	sf-ai-agentforce-testing	再現可能なテストループ
Flow バックアップアクションのデバッグ	sf-flow	宣言型修復
Apex バックアップアクションのデバッグ	sf-debug または sf-apex	コード / ログ調査

---

リファレンスマップ

ここから始める

• README.md
• references/basic-extraction.md
• references/filtered-extraction.md
• references/cli-reference.md

データモデル / クエリ

• references/data-model-reference.md
• references/query-patterns.md
• references/client-demo-queries.md

分析 / デバッグ

• references/analysis-cookbook.md
• references/analysis-examples.md
• references/debugging-sessions.md
• references/polars-cheatsheet.md
• references/agent-execution-lifecycle.md

認証 / トラブルシューティング

• references/auth-setup.md
• references/troubleshooting.md
• references/billing-and-troubleshooting.md
• references/builder-trace-api.md
• scripts/

---

スコアガイド

スコア	意味
90+	テレメトリベースの強力な診断
75–89	軽微なギャップのある有用な分析
60–74	部分的な可視性のみ
< 60	不十分な証拠。より多くのテレメトリを収集