observing-agentforce

Agentforce オブザーバビリティ

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

3 フェーズのワークフロー：

• 観察 -- Data Cloud から STDM セッションをクエリします（利用可能な場合）。それ以外の場合は、フォールバックとしてテストスイートを実行し、ローカルトレースでプレビューします
• 再現 -- sf agent preview を使用して、問題のある会話をライブでシミュレートします
• 改善 -- .agent ファイルを直接編集し、検証して、公開し、確認します

---

プラットフォームに関する注意事項

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

---

ルーティング

開始する前に、以下の入力を収集してください。

• 組織のエイリアス（必須）
• エージェント API 名（プレビューとデプロイに必須。指定されていない場合は確認してください）
• エージェントファイルのパス（任意）-- .agent ファイルへのパス。通常は force-app/main/default/aiAuthoringBundles/<AgentName>/<AgentName>.agent です。指定されていない場合は自動検出します。
• セッション ID（任意）-- 特定のセッションを分析します。指定されていない場合は、過去 7 日間のセッションをクエリします。
• 遡る日数（任意。デフォルトは 7）

ユーザー入力から目的を判断してください。

• 具体的なアクションの指定なし -> 3 つすべてのフェーズを実行します：観察 -> 問題を明らかにする -> 再現および／または改善を希望するかユーザーに確認します
• 「分析」／「セッション」／「問題は何か」 -> フェーズ 1 のみを実行し、次のステップを提案します
• 「再現」／「テスト」／「プレビュー」 -> フェーズ 2（問題がまだ特定されていない場合は、まずフェーズ 1 を実行します）
• 「修正」／「改善」／「更新」 -> フェーズ 3（問題がまだ特定されていない場合は、まずフェーズ 1 を実行します）

エージェント名を解決する

STDM にクエリする前に、ユーザーが指定したエージェント名を組織内で照合し、正確な 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 フラグでは、_vN の接尾辞を除いた DeveloperName を使用します（例：「OrderService」）

次の値を保存してください。

• AGENT_MASTER_LABEL -- findSessions() のエージェントフィルター用
• AGENT_API_NAME -- _vN を除いた DeveloperName。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 -- ローカルで見つからない場合は、組織から取得する：

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: ブロック
• reasoning: instructions: を含む start_agent または subagent ブロック
• 各サブエージェントに、それぞれ異なる instructions: の内容が設定されていること（サブエージェント間で同一ではないこと）

解決したパスを AGENT_FILE として保存し、フェーズ 3 で使用してください。

---

フェーズ 0：データスペースの特定

STDM クエリを実行する前に、正しい Data Cloud Data Space 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" のエントリのみを対象にします。
• アクティブな Data Space がちょうど 1 つの場合は自動的に使用し、ユーザーに「使用する Data Space：<name>」と確認します。
• アクティブな Data Space が複数ある場合は、一覧（ラベル + 名前）を表示し、どれを使用するかユーザーに尋ねます。

選択した name の値を DATA_SPACE として保存し、以降のすべての手順で使用します。

前提条件の確認：STDM DMO

ヘルパークラスをデプロイした後（手順 1.0）、簡単なプローブを実行して、STDM Data Model Object が 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）を利用できません。有効にするには、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 のない組織	即時に実行可能、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 つ（description: のキーワードから）、主要なアクションごとに 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 の指示に「あなたはルーターのみです。質問に直接回答してはいけません。」を追加します。

1-ALT.5 分類して提示する

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

---

フェーズ 1：観察 -- STDM のクエリ

STDM クエリの詳細、Apex サービスのデプロイ、レスポンスの解析については、references/stdm-queries.md を参照してください。

1.0 ヘルパークラスのデプロイ（組織ごとに1回）

AgentforceOptimizeService Apex クラスを組織にデプロイします。まず、すでにデプロイされているか確認してください。

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 が空の結果を返す場合は、Phase 1-ALT に切り替えます。

1.2 会話の詳細を取得する

最大5件のセッション（最新のものから）について、getMultipleConversationDetails() を使います。メッセージ、ステップ、トピック、アクション結果を含む、ターンごとのデータが返されます。

1.2b LLM のプロンプトと応答を取得する（任意）

LOW adherence が検出された場合は、getLlmStepDetails() を使って実際の LLM プロンプトと応答を取得します。

1.2c 集計メトリクスを取得する（推奨される最初のステップ）

getAggregatedMetrics() を使って、セッション率、上位インテント、品質分布、RAG 平均値を含む、全体的な健全性ダッシュボードを取得します。

1.2d モーメントインサイトを取得する（セッションごとの詳細）

getMomentInsights() を使って、セッションごとのインテントの概要、品質スコア（1～5）、リトリーバーのメトリクスを取得します。

1.2e 可観測性クエリを実行する（RAG の詳細分析）

runObservabilityQuery() を使って、KnowledgeGap、Hallucination、RetrievalQuality、AnswerRelevancy、Leaderboard を対象とした RAG 分析を行います。

1.3 会話を再構成する

各セッションについて、ConversationData JSON からターンごとのタイムラインを表示します。

1.4 問題を特定する

問題パターンの一覧表と分類カテゴリの詳細は、references/issue-classification.md を参照してください。

各セッションで次の問題を確認します：アクションエラー、サブエージェントの誤ルーティング、アクションの欠落、誤った入力、変数の取得失敗、遷移なし、アクションの遅延、LOW adherence、セッションの放棄、応答のないサブエージェント、公開時のドリフト、ハブが応答しないアンチパターン、エントリーでの直接回答、安全性の問題。

優先度：P1 = アクションエラー、誤ルーティング、LOW adherence。P2 = アクションの欠落、変数のバグ、ナレッジギャップ。P3 = パフォーマンス、セッションの放棄。

1.5 調査結果とエージェント設定の根拠を提示する

分析したセッション、根本原因カテゴリ別に分類した問題、改善効果の推定値を提示します。その後、自動的に .agent ファイルの分析に進み、根本原因を確認します。

構造分析の全チェック項目、相互参照の手順、公開時のドリフト検出の詳細は、references/issue-classification.md を参照してください。

組織から .agent ファイルを取得し、自動チェック（サブエージェント数とアクションブロック数の比較、応答しないハブの検出、孤立したアクション、サブエージェント間の変数依存関係）を実行して、STDM の症状とファイル構造を相互参照します。

---

Phase 2: 再現 -- ライブプレビュー

プレビューの全手順、トレース診断コマンド、分類基準の詳細は、references/reproduce-reference.md を参照してください。

Phase 1 で確認した問題ごとにテストシナリオを1つ作成します。--authoring-bundle を指定して、各シナリオを sf agent preview で実行します（ローカルのトレースが生成されます）。各シナリオを3回実行して、次のように分類します。

判定	基準
[CONFIRMED]	3回中3回で同じ障害が発生
[INTERMITTENT]	3回中1～2回で障害が発生
[NOT REPRODUCED]	3回中3回で成功

[CONFIRMED] と [INTERMITTENT] の問題のみ Phase 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

---

Phase 3: 改善 -- .agent ファイルを直接編集する

事前確認、修正内容の対応付け、指示の原則、回帰の防止、デプロイチェーン、検証、安全性の再検証、テストケースの作成に関する全手順は、references/improve-reference.md を参照してください。

3.0 事前確認

編集する前に、すべてのアクションの対象が存在し、組織に登録されていることを確認します。対象がない場合は、スタブのデプロイ、アクションの削除、UI による登録、ルーティングのみの修正を続行する、という選択肢を提示します。

3.1-3.3 問題のマッピング、編集、指示の原則

確認済みの各問題を、.agent ファイル内の修正箇所（説明、指示、アクション、バインディング、遷移）にマッピングします。対象を絞って変更するには Edit ツールを使用します。指示の原則に従い、アクションを明示的に指定し、前提条件を示し、範囲を絞り、ペルソナは system: 内のみに記述します。

3.4 リグレッションの防止

編集前にベースラインを確立します。編集は最小限にします。編集のたびに直ちにテストします。公開サイクルごとに修正は1つにします。サブエージェント間の依存関係を確認します。隣接するサブエージェントもテストします。

3.5 修正の適用

.agent ファイルを読み取り、Edit ツールで編集します（インデントにはタブを使用します）。差分を表示します。

3.6 検証、デプロイ、公開、有効化

# Validate (dry run)
sf agent validate authoring-bundle --json --api-name <AGENT_API_NAME> -o <org>

# Publish (compile + deploy + activate)
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 のテストケースを更新

確認済みの問題から、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 フィールドスキーマ、データ階層、品質に関する注意事項、エージェント名の解決