agentforce-observe

Agentforce Observability

セッションのトレースデータとライブプレビューのテストを使用して、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; ..." に置き換えてください。

---

ルーティング

開始前に、以下の入力情報を収集します。

• 組織エイリアス（必須） -- 認証済みである必要があります（未認証の場合は sf org login web を実行）
• エージェント API 名（プレビューとデプロイに必須。指定されていない場合は確認してください）
• エージェントファイルのパス（任意） -- .agent ファイルのパス。通常は force-app/main/default/aiAuthoringBundles/<AgentName>/<AgentName>.agent です。指定されていない場合は自動検出します。
• セッション ID（任意） -- 特定のセッションを分析します。指定がない場合は直近 7 日間をクエリします
• 遡る日数（任意、デフォルトは 7）
• アラート所有者ユーザー（任意、アラートのみ） -- 一覧表示／管理するアラートのユーザー。デフォルトでは現在のユーザーです

ユーザーの入力から意図を判断します。

• 具体的な操作の指定なし -> 3 つの分析フェーズすべてを実行します：Observe -> 問題を提示 -> Reproduce および／または Improve を実行するかユーザーに確認します
• 「analyze」／「sessions」／「what's wrong」 -> フェーズ 1 のみを実行し、次のステップを提案します
• 「reproduce」／「test」／「preview」 -> フェーズ 2（問題がまだ特定されていない場合は、先にフェーズ 1 を実行）
• 「fix」／「improve」／「update」 -> フェーズ 3（問題がまだ特定されていない場合は、先にフェーズ 1 を実行）
• 「create alert」／「set up monitoring」／「alert me when」 -> AHM（作成）
• 「list alerts」／「show my alerts」／「update alert」／「delete alert」 -> AHM（一覧表示／PUT による更新／削除）
• 「get / list notifications」／「notifications for a specific alert」／「have my alerts fired」／「why isn't my alert firing」 -> AHM：ヘッダー X-UNS-Type-Filter: all を指定して通知を取得し、ステータスと一覧を報告します。特定のアラートの場合は、metricId ではなく targetPageRef.state.c__alertId の alertId でフィルタリングします（15／18 文字に対応）。加えて Incidents ビューとメトリックの確認を行います

エージェント名の解決

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> --simulate-actions -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 デプロイヘルパークラス（組織ごとに一度）

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 と検出された場合は、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 の状態、セッションの放棄、デッドサブエージェント、公開時のずれ、デッドハブのアンチパターン、エントリーが直接回答する問題、安全性の問題を確認します。

音声エージェント（modality voice:ブロックがある場合）： 以下も確認します。

• 応答の冗長さ — エージェントの応答が3文を超える場合はすべてフラグを付けます（音声 UX のアンチパターン。無音／ナッジタイマーのトリガーにもなります）
• 応答内の視覚的な書式 — 音声でレンダリングされないリスト、リンク、Markdown
• 確認パターンの欠落 — データを変更するアクションで、重要な詳細を言い返して確認しない
• 音声接続設定の欠落 — 音声エージェントにVoiceCallIdリンク変数（@VoiceCall.Id）またはconnection customer_web_client:ブロックがない、あるいは存在しないconnection voice:ブロックが追加されている
• レイテンシのアンチパターン — トレースのステップ所要時間を、/agentforce-generateのreferences/voice-latency-heuristics.mdにある、フィールドで検証済みのパターンと照合します。ライブ通話経路上での同期書き込み、推論を行う LLM にそのまま返される大容量の検索結果、外部呼び出しの連鎖、過度に細分化されたサブエージェントのルーティング、確認フレーズのない遅いアクションを確認します。レイテンシの修正は、純粋に手順に関するもの（確認フレーズ、ターンの長さ、読み上げ形式のルール）でない限り、フラグのみとします。
• TTS の音声の乱れ／読み上げ形式ルールの欠落 — アクションの出力や応答において、読み上げ形式の指示ルールなしに価格、電話番号、ID が表示されている場合

優先度：P1＝アクションエラー、誤ルーティング、アドヒアランスが LOW の状態。P2＝アクションの欠落、変数の不具合、ナレッジの不足。P3＝パフォーマンス、セッションの放棄、音声 UX の問題、音声のレイテンシに関するアンチパターン。

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> --simulate-actions -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>

これらのコマンドは Salesforce プロジェクトディレクトリから実行してください。start には --authoring-bundle を指定したアクションモード（--simulate-actions または --use-live-actions）が必要です。このフラグは send と end では拒否されます。

トレースの場所： .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 ツールで編集して差分を表示します。ファイルの構造的なインデントをそのまま維持して、必要最小限の編集を行い、異なるスタイルが混在するファイルを作らないようにします。新しいファイルはスペース 4 つで作成します。正規化が必要な場合は、構造的なインデント全体を別の変更として変換し、検証します。タブでインデントされたファイルを部分的に変換しないでください。

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 検証

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

3.7b 安全性の再確認（必須）

変更した .agent ファイルに対して、安全性レビュー（/agentforce-generate の Section 15）を再実行します。BLOCK の検出結果を新たに引き起こす変更はすべて元に戻します。

3.8 Testing Center のテストケースを更新する

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

---

エージェントヘルスモニタリング（AHM）

AHM アラートの全手順――POST スキーマ、列挙型、SDM／メトリック／エージェントの検出、しきい値、メトリックの検証、トラブルシューティングについては、references/ahm-alerts.md を参照してください。

リアクティブな Observe フェーズを補完するプロアクティブな機能です。AHM データアラートは、エージェントのメトリック（エスカレーション、デフレクションなど）がしきい値を超えると発火します。tableau/dataAlerts（dataAlertType: "agenthealthmonitoring"）に対して sf api request rest を実行して操作します。現時点では sf agent alert サブコマンドはありません。dataspace にはフェーズ 0を再利用してください。POST ボディを作成し、SDM、その _mtc メトリック ID、エージェントのフィルター値をまずリファレンスに従って検出してから、次の操作を行います。

# List/describe -- resolve owner id first (required); single-alert GET is 405 => list + filter client-side
USER_ID=$(sf org display user --target-org <org> --json | python3 -c 'import sys,json;print(json.load(sys.stdin)["result"]["id"])')
sf api request rest "/services/data/v66.0/tableau/dataAlerts?ownerId=$USER_ID" -o <org>
# Create / PUT update-in-place / delete (204). PUT & DELETE are addressed by $ALERT_ID in the path; PUT takes the full POST-style body. Bodies per reference into a 0600 mktemp file.
sf api request rest "/services/data/v66.0/tableau/dataAlerts" -X POST -H "Content-Type: application/json" -b "@$body" -o <org>
sf api request rest "/services/data/v66.0/tableau/dataAlerts/$ALERT_ID" -X PUT -H "Content-Type: application/json" -b "@$body" -o <org>
sf api request rest "/services/data/v66.0/tableau/dataAlerts/$ALERT_ID" -X DELETE -o <org> --include
# Notifications REQUIRE header X-UNS-Type-Filter: all (else custom-types-only => AHM empty = false 0). Report status + list.
sf api request rest "/services/data/v66.0/connect/notifications/status" -H "X-UNS-Type-Filter: all" -o <org>
sf api request rest "/services/data/v66.0/connect/notifications"        -H "X-UNS-Type-Filter: all" -o <org>
# AHM notifications: type=templatized_data_alert; no per-alert endpoint. Attribute by alertId in targetPageRef.state.c__alertId (15/18-char-safe), NOT metricId (collides).

すべてのアラート作業で注意すべき、見落としやすいサイレント失敗の落とし穴：

• しきい値は表示上のパーセンテージではなく、0～1 の比率です。5% は "0.05"、"1" は 100% を意味します。
• POST のフィールド名／大文字・小文字の使い方は GET と異なります。POST では alertName ではなく utterance を使い、識別子の type は PascalCase です。そのため、GET のレスポンスをそのまま POST にコピーすると失敗します。
• 通知には X-UNS-Type-Filter: all が必要です。これがないと connect/notifications* はカスタムタイプのみを返すため、AHM 通知（タイプ templatized_data_alert）は結果に含まれません。リストが空でも、「発火したことがない」という意味ではなく、誤検知です。

---

リファレンスファイル

リファレンス	内容
references/stdm-queries.md	STDM クエリの手順、Apex サービスのデプロイ、レスポンスの解析
references/ahm-alerts.md	AHM データアラートの作成／一覧表示／更新／削除、トリガー履歴、SDM／メトリック／エージェントの検出、しきい値のスキーマ、メトリックの検証
references/issue-classification.md	問題パターンの表、根本原因のカテゴリ、構造分析の確認項目
references/reproduce-reference.md	フェーズ 2 のプレビュー手順、トレースの診断、分類基準
references/improve-reference.md	フェーズ 3 の編集、デプロイチェーン、検証、安全性、テストケース
references/stdm-schema.md	DMO フィールドスキーマ、データ階層、品質に関する注記、エージェント名の解決