Agentforce の可観測性

セッショントレースデータとライブプレビューテストを使用して Agentforce エージェントを改善します。

3フェーズワークフロー:

• 観察 (Observe) -- Data Cloud から STDM セッションを照会、または テストスイート + ローカルトレースを実行 (フォールバック)
• 再現 (Reproduce) -- sf agent preview を使用して問題のある会話をライブシミュレーション
• 改善 (Improve) -- .agent ファイルを直接編集、検証、パブリッシュ、確認

---

プラットフォーム注記

• 以下のシェル例は bash 構文を使用しています。Windows では PowerShell に相当するコマンドまたは Git Bash を使用してください。
• Windows では python3 を python に置き換えてください。
• /tmp/ を $env:TEMP\ (PowerShell) または %TEMP%\ (cmd) に置き換えてください。
• jq がインストールされていない場合は jq を python -c "import json,sys; ..." に置き換えてください。

---

ルーティング

開始する前に、これらの入力を収集します:

• Org エイリアス (必須)
• エージェント API 名 (プレビューとデプロイに必須; 指定されていない場合は質問)
• エージェントファイルパス (オプション) -- .agent ファイルへのパス。通常は force-app/main/default/aiAuthoringBundles/<AgentName>/<AgentName>.agent。指定されていない場合は自動検出
• セッション ID (オプション) -- 特定のセッションを分析; 不在の場合は過去 7 日間を照会
• 遡る日数 (オプション、デフォルト 7)

ユーザー入力から意図を判定します:

• 特定のアクションなし -> 3つのフェーズすべてを実行: 観察 -> 問題を表示 -> ユーザーに再現および/または改善を希望するかどうかを確認
• 「分析」/ 「セッション」/ 「何が間違っているか」 -> フェーズ 1 のみ、次にステップを提案
• 「再現」/ 「テスト」/ 「プレビュー」 -> フェーズ 2 (問題が手元にない場合は最初にフェーズ 1 を実行)
• 「修正」/ 「改善」/ 「更新」 -> フェーズ 3 (問題が手元にない場合は最初にフェーズ 1 を実行)

エージェント名の解決

STDM クエリを実行する前に、ユーザー指定のエージェント名を org に対して解決して、正確な MasterLabel と DeveloperName を取得します:

sf data query --json \
  --query "SELECT Id, MasterLabel, DeveloperName FROM GenAiPlannerDefinition WHERE MasterLabel LIKE '%<user-provided-name>%' OR DeveloperName LIKE '%<user-provided-name>%'" \
  -o <org>

• MasterLabel = STDM findSessions と Agent Builder UI で使用される表示名 (例: "Order Service")
• DeveloperName = メタデータで使用されるバージョンサフィックス付き API 名 (例: "OrderService_v9")
• sf agent preview/activate/publish の --api-name フラグは DeveloperName を除外した _vN サフィックスを使用 (例: "OrderService")

これらの値を格納します:

• AGENT_MASTER_LABEL -- findSessions() エージェントフィルター用
• AGENT_API_NAME -- DeveloperName から _vN サフィックスを除外、sf agent CLI コマンド用
• PLANNER_ID -- このエージェントの Salesforce レコード ID

.agent ファイルの配置

ステップ 1 -- ローカルで検索:

find <project-root>/force-app/main/default/aiAuthoringBundles -name "*.agent" 2>/dev/null

ユーザーがエージェントファイルパスを指定した場合は、そのパスを直接使用します。それ以外の場合は、AGENT_API_NAME に一致するファイルを検索します。

ステップ 2 -- ローカルで見つからない場合は org から取得:

sf project retrieve start --json --metadata "AiAuthoringBundle:<AGENT_API_NAME>" -o <org>

既知の不具合: sf project retrieve start はダブルネストパスを作成します: force-app/main/default/main/default/aiAuthoringBundles/...。取得直後に修正してください:

if [ -d "force-app/main/default/main/default/aiAuthoringBundles" ]; then
  mkdir -p force-app/main/default/aiAuthoringBundles
  cp -r force-app/main/default/main/default/aiAuthoringBundles/* \
    force-app/main/default/aiAuthoringBundles/
  rm -rf force-app/main/default/main
fi

ステップ 3 -- 取得したファイルを検証:

.agent ファイルを読み込み、適切な Agent Script 構造を確認します:

• instructions: を持つ system: ブロック
• developer_name: を持つ config: ブロック
• instructions: を持つ start_agent または subagent ブロック
• 各サブエージェントは異なる instructions: コンテンツを持つべき (サブエージェント間で同一ではない)

解決したパスを AGENT_FILE として フェーズ 3 に格納します。

---

フェーズ 0: データスペースの検出

STDM クエリを実行する前に、正しい Data Cloud データスペース API 名を判定します。

sf api request rest "/services/data/v63.0/ssot/data-spaces" -o <org>

注: sf api request rest はベータコマンドです -- --json フラグを追加しないでください (このフラグはサポートされていないため、エラーが発生します)。

レスポンス形式は以下の通りです:

{
  "dataSpaces": [
    {
      "id": "0vhKh000000g3DjIAI",
      "label": "default",
      "name": "default",
      "status": "Active",
      "description": "Your org's default data space."
    }
  ],
  "totalSize": 1
}

name フィールドは AgentforceOptimizeService に渡す API 名です。

判定ロジック:

• コマンドが失敗した場合 (例: 404 またはパーミッションエラー) は、'default' にフォールバックし、それを前提条件として記録します。
• status: "Active" のエントリのみにフィルタリングします。
• 正確に 1 つのアクティブなデータスペースが存在する場合は、自動的に使用し、ユーザーに確認します: 「使用中のデータスペース: <name>」。
• 複数のアクティブなデータスペースが存在する場合は、リスト (ラベル + 名前) を表示し、ユーザーにどちらを使用するかを確認します。

選択した name 値を DATA_SPACE として以降のすべてのステップに格納します。

前提条件チェック: STDM DMOs

ヘルパークラス (ステップ 1.0) をデプロイした後、STDM データモデルオブジェクトが Data Cloud に存在することを確認するため、簡単なプローブを実行します:

sf apex run -o <org> -f /dev/stdin << 'APEX'
ConnectApi.CdpQueryInput qi = new ConnectApi.CdpQueryInput();
qi.sql = 'SELECT ssot__Id__c FROM "ssot__AiAgentSession__dlm" LIMIT 1';
try {
    ConnectApi.CdpQueryOutputV2 out = ConnectApi.CdpQuery.queryAnsiSqlV2(qi, '<DATA_SPACE>');
    System.debug('STDM_CHECK:OK rows=' + (out.data != null ? out.data.size() : 0));
} catch (Exception e) {
    System.debug('STDM_CHECK:FAIL ' + e.getMessage());
}
APEX

STDM_CHECK:FAIL の場合: STDM は有効化されていません。ユーザーに通知し、フェーズ 1-ALT に切り替えます:

STDM (Session Trace Data Model) はこの org では利用できません。有効化するには: Setup -> Data Cloud -> Data Streams に移動し、「Agentforce Activity」がアクティブであることを確認してください。 フォールバックで進めます: テストスイート + ローカルトレース。

STDM_CHECK:OK の場合、フェーズ 1 (STDM パス) に進みます。

---

フェーズ 1-ALT: STDM なし観察 (フォールバックパス)

STDM が利用できない場合、テストスイートと sf agent preview --authoring-bundle をローカルトレース分析で使用します。

データソース	使用時期	利点	欠点
STDM (フェーズ 1)	履歴本番分析	実ユーザーデータ、ボリューム	Data Cloud 必須、15 分遅延
テストスイート + ローカルトレース (フェーズ 1-ALT)	開発反復、STDM なし org	即時、完全な LLM プロンプト、変数状態	プレビューのみ、実ユーザーデータなし

1-ALT.1 既存テストスイート実行 (利用可能な場合)

sf agent test list --json -o <org>
sf agent test run --json --api-name <TestSuiteName> --wait 10 --result-format json -o <org> | tee /tmp/test_run.json
JOB_ID=$(python3 -c "import json; print(json.load(open('/tmp/test_run.json'))['result']['runId'])")
sf agent test results --json --job-id "$JOB_ID" --result-format json -o <org>

1-ALT.2 .agent ファイルからテスト発話を導出 (テストスイートなしの場合)

テストスイートが存在しない場合は、発話を導出します: エントリ以外のサブエージェント 1 つあたり 1 つ (description: キーワードから)、主要アクション 1 つあたり 1 つ、ガードレールテスト 1 つ、マルチターンテスト 1 つ。

1-ALT.3 --authoring-bundle でプレビュー (ローカルトレース)

各テスト発話をプレビューで実行してローカルトレースファイルを生成します:

sf agent preview start --json --authoring-bundle <BundleName> -o <org> | tee /tmp/preview_start.json
SESSION_ID=$(python3 -c "import json; print(json.load(open('/tmp/preview_start.json'))['result']['sessionId'])")

sf agent preview send --json --session-id "$SESSION_ID" --authoring-bundle <BundleName> \
  --utterance "$UTT" -o <org> | tee /tmp/preview_response.json

sf agent preview end --json --session-id "$SESSION_ID" --authoring-bundle <BundleName> -o <org>

トレースファイルの位置: .sfdx/agents/{BundleName}/sessions/{sessionId}/traces/{planId}.json

1-ALT.4 ローカルトレース診断

問題タイプ	トレースコマンド
サブエージェント誤ルーティング	jq -r '.plan[] | select(.type=="NodeEntryStateStep") | .data.agent_name' "$TRACE"
アクション未呼び出し	jq -r '.plan[] | select(.type=="EnabledToolsStep") | .data.enabled_tools[]' "$TRACE"
LOW アドヒアランス	jq -r '.plan[] | select(.type=="ReasoningStep") | {category, reason}' "$TRACE"
変数キャプチャ失敗	jq -r '.plan[] | select(.type=="VariableUpdateStep") | .data.variable_updates[]' "$TRACE"
曖昧な指示	jq -r '.plan[] | select(.type=="LLMStep") | .data.messages_sent[0].content' "$TRACE"

DefaultTopic トレースの特異性: --authoring-bundle を使用する場合、ルート .topic フィールドはルーティングが機能しても "DefaultTopic" を表示することがあります。実際のサブエージェントチェーンには常に NodeEntryStateStep.data.agent_name を使用します。

エントリが直接回答 (SMALL_TALK パターン): start_agent トレースが SMALL_TALK グラウンディングと表示される遷移ツール、しかしどれも呼び出されていない場合、start_agent 指示に「You are a router only. Do NOT answer questions directly.」を追加してください。

1-ALT.5 分類して提示

references/issue-classification.md のカテゴリを使用して問題を分類します。結果を提示した後、自動的にエージェント設定証拠分析に進みます。

---

フェーズ 1: 観察 -- STDM を照会

STDM クエリの完全な詳細、Apex サービスデプロイメント、レスポンス解析: references/stdm-queries.md を参照

1.0 ヘルパークラスをデプロイ (org 1 つあたり 1 回)

AgentforceOptimizeService Apex クラスを org にデプロイします。最初に既にデプロイされているかどうかを確認します:

sf data query --json --query "SELECT Id, Name FROM ApexClass WHERE Name = 'AgentforceOptimizeService'" -o <org>

デプロイされていない場合は、スキルディレクトリからコピーしてデプロイします。完全なステップについては references/stdm-queries.md を参照してください。

1.1 セッションを検索

findSessions() を使用して最近のセッションを照会します。Apex デバッグログから DEBUG|STDM_RESULT: を解析します。findSessions が空を返す場合は、フェーズ 1-ALT に切り替えます。

1.2 会話詳細を取得

最大 5 つのセッション (最新順) に getMultipleConversationDetails() を使用します。メッセージ、ステップ、トピック、アクション結果を含むターンバイターンデータを返します。

1.2b LLM プロンプト/レスポンスを取得 (オプション)

LOW アドヒアランスが検出された場合、実際の LLM プロンプトとレスポンスを取得するには getLlmStepDetails() を使用します。

1.2c 集約メトリクスを取得 (推奨される最初のステップ)

高レベルの健康ダッシュボードには getAggregatedMetrics() を使用: セッションレート、トップ意図、品質分布、RAG 平均。

1.2d モーメントインサイトを取得 (セッションあたりの詳細)

セッションあたりの意図要約、品質スコア (1-5)、リトリーバーメトリクスについては getMomentInsights() を使用します。

1.2e 可観測性クエリを実行 (RAG ディープダイブ)

ターゲット RAG 分析については runObservabilityQuery() を使用: KnowledgeGap、Hallucination、RetrievalQuality、AnswerRelevancy、Leaderboard。

1.3 会話を再構成

各セッションの ConversationData JSON からターンバイターンタイムラインをレンダリングします。

1.4 問題を特定

完全な問題パターンテーブルと分類カテゴリ: references/issue-classification.md を参照

各セッションで以下をチェック: アクションエラー、サブエージェント誤ルーティング、アクション欠落、不正な入力、変数キャプチャ失敗、遷移なし、遅いアクション、LOW アドヒアランス、放棄されたセッション、デッドサブエージェント、パブリッシュドリフト、デッドハブ アンチパターン、エントリが直接回答、セーフティ問題。

優先度: P1 = アクションエラー、誤ルーティング、LOW アドヒアランス; P2 = アクション欠落、変数バグ、知識ギャップ; P3 = パフォーマンス、放棄されたセッション。

1.5 結果を提示してエージェント設定証拠を確認

分析したセッション、根本原因カテゴリでグループ化した問題、向上推定を提示します。その後、自動的に .agent ファイルを分析して根本原因を確認します。

完全な構造分析チェック、相互参照手順、パブリッシュドリフト検出: references/issue-classification.md を参照

org から .agent ファイルを取得し、自動化チェック (サブエージェント数 vs アクションブロック、デッドハブ検出、孤立したアクション、クロスサブエージェント変数依存) を実行し、STDM 症状をファイル構造と相互参照します。

---

フェーズ 2: 再現 -- ライブプレビュー

完全なプレビュー手順、トレース診断コマンド、分類基準: references/reproduce-reference.md を参照

フェーズ 1 の確認された問題あたり 1 つのテストシナリオを構築します。各シナリオを sf agent preview で --authoring-bundle を使用して実行 (ローカルトレースを生成)。各シナリオを 3 回 実行し、分類します:

判定	基準
[CONFIRMED]	3/3 回で同じ障害
[INTERMITTENT]	1-2/3 回で障害
[NOT REPRODUCED]	3/3 回でパス

[CONFIRMED] および [INTERMITTENT] の問題のみがフェーズ 3 に進みます。

主要コマンド:

sf agent preview start --json --authoring-bundle <Name> -o <org>
sf agent preview send --json --session-id "$SID" --utterance "<text>" --authoring-bundle <Name> -o <org>
sf agent preview end --json --session-id "$SID" --authoring-bundle <Name> -o <org>

トレースの位置: .sfdx/agents/{Name}/sessions/{sessionId}/traces/{planId}.json

---

フェーズ 3: 改善 -- .agent ファイルを直接編集

プレフライトチェック、修正マッピング、指示原則、リグレッション防止、デプロイメントチェーン、検証、セーフティ再検証、テストケース作成の完全な手順: references/improve-reference.md を参照

3.0 プレフライト

編集する前に、すべてのアクションターゲットが存在し、org に登録されていることを確認します。ターゲットが欠落している場合は、オプションを提示: スタブをデプロイ、アクションを削除、UI 経由で登録、またはルーティングのみの修正で進行。

3.1-3.3 問題をマップ、編集、指示原則に従う

確認された各問題を .agent ファイル内の修正位置にマップ (説明、指示、アクション、バインディング、遷移)。Edit ツールを使用してターゲット変更を行います。指示原則に従う: アクションを明示的に名前付け、事前条件を述べ、スコープを厳しく、ペルソナを system: のみに保つ。

3.4 リグレッション防止

編集する前にベースラインを確立します。最小限の編集を行います。各編集直後にテストします。パブリッシュサイクルあたり 1 修正。クロスサブエージェント依存を確認します。隣接するサブエージェントをテストします。

3.5 修正を適用

.agent ファイルを読み込み、Edit ツール (インデントのためのタブ) で編集し、diff を表示します。

3.6 検証、デプロイ、パブリッシュ、有効化

# 検証 (ドライラン)
sf agent validate authoring-bundle --json --api-name <AGENT_API_NAME> -o <org>

# パブリッシュ (コンパイル + デプロイ + 有効化)
sf agent publish authoring-bundle --json --api-name <AGENT_API_NAME> -o <org>

パブリッシュが失敗した場合は、デプロイ + 有効化フォールバックを使用 (注: 不完全 -- ライブメタデータに reasoning: actions: を伝播しない)。

3.7 検証

修正後、フェーズ 2 シナリオを実行します。トレースで正しいルーティング、グラウンディング、ツール、変数を確認します。24-48 時間後、フェーズ 1 を再実行してベースラインと比較します。

3.7b セーフティ再検証 (必須)

修正済み .agent ファイルに対してセーフティレビュー (/developing-agentforce のセクション 15 を参照) を再実行します。BLOCK 検出を導入する変更は元に戻します。

3.8 テストセンターテストケースを更新

Testing Center YAML 形式で確認された問題からリグレッションテストケースを作成します。sf agent test create でデプロイし、以前破損していたすべてのシナリオがパスすることを確認します。

---

参照ファイル

参照	内容
references/stdm-queries.md	STDM クエリ手順、Apex サービスデプロイメント、レスポンス解析
references/issue-classification.md	問題パターンテーブル、根本原因カテゴリ、構造分析チェック
references/reproduce-reference.md	フェーズ 2 プレビュー手順、トレース診断、分類基準
references/improve-reference.md	フェーズ 3 編集、デプロイメントチェーン、検証、セーフティ、テストケース
references/stdm-schema.md	DMO フィールドスキーマ、データ階層、品質注記、エージェント名解決