sf-ai-agentforce-observability

sf-ai-agentforce-observability：Agentforce セッショントレースの抽出と分析

ユーザーが単なるテストではなく、トレースベースの可観測性を必要としている場合にこのスキルを使用します。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 エンティティ

最低限、次の項目を扱います。

• セッション
• インタラクション／ターン
• インタラクションステップ
• モーメント
• メッセージ

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	証拠が不十分です。テレメトリーをさらに収集してください