observing-agentforce

Agentforce 可观测性

使用会话跟踪数据和实时预览测试，改进 Agentforce Agent。

三阶段工作流：

• 观察 -- 从 Data Cloud 查询 STDM 会话（如果可用），否则运行测试套件并使用本地跟踪数据进行预览
• 复现 -- 使用 sf agent preview 实时模拟有问题的对话
• 改进 -- 直接编辑 .agent 文件，进行验证、发布并确认

---

平台说明

• 以下 Shell 示例使用 bash 语法。在 Windows 上，请使用 PowerShell 等效命令或 Git Bash。
• 在 Windows 上，将 python3 替换为 python。
• 将 /tmp/ 替换为 $env:TEMP\（PowerShell）或 %TEMP%\（cmd）。
• 如果未安装 jq，请将 jq 替换为 python -c "import json,sys; ..."。

---

路由

开始前收集以下信息：

• Org 别名（必需）
• Agent API 名称（预览和部署必需；如果未提供，请询问）
• Agent 文件路径（可选）-- .agent 文件的路径，通常为 force-app/main/default/aiAuthoringBundles/<AgentName>/<AgentName>.agent。如果未提供，则自动检测。
• 会话 ID（可选）-- 分析指定会话；如果未提供，则查询最近 7 天的会话
• 回溯天数（可选，默认值为 7）

根据用户输入确定意图：

• 未指定具体操作 -> 运行全部三个阶段：观察 -> 找出问题 -> 询问用户是否要复现和/或改进
• "analyze" / "sessions" / "what's wrong" -> 仅运行第 1 阶段，然后建议后续步骤
• "reproduce" / "test" / "preview" -> 运行第 2 阶段（如果尚无待处理的问题，先运行第 1 阶段）
• "fix" / "improve" / "update" -> 运行第 3 阶段（如果尚无待处理的问题，先运行第 1 阶段）

解析 Agent 名称

执行任何 STDM 查询前，先在 org 中解析用户提供的 Agent 名称，以获取准确的 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 筛选条件
• AGENT_API_NAME -- 不带 _vN 后缀的 DeveloperName，用于 sf agent CLI 命令
• PLANNER_ID -- 此 Agent 的 Salesforce 记录 ID

查找 .agent 文件

步骤 1 -- 在本地搜索：

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

如果用户提供了 Agent 文件路径，请直接使用。否则，搜索与 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: 块
• 包含带有 reasoning: instructions: 的 start_agent 或 subagent 块
• 每个子 Agent 都应具有不同的 instructions: 内容（子 Agent 之间不能完全相同）

将解析出的路径保存为 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 是 Beta 命令——不要添加 --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" 的条目。
• 如果恰好存在一个 Active 数据空间，则自动使用它，并向用户确认：“正在使用数据空间：<name>”。
• 如果存在多个 Active 数据空间，则显示列表（标签 + 名称），并询问用户要使用哪一个。

将选定的 name 值保存为 DATA_SPACE，供后续所有步骤使用。

前置条件检查：STDM DMO

部署辅助类（步骤 1.0）后，运行快速探测，确认 Data Cloud 中存在 STDM 数据模型对象：

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 文件推导测试话语（如果没有测试套件）

如果不存在测试套件，则推导测试话语：每个非入口子 Agent 一个（根据 description: 关键词），每个关键操作一个，一个护栏测试，以及一个多轮测试。

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 本地跟踪诊断

问题类型	跟踪命令
子 Agent 路由错误	jq -r '.plan[] | select(.type=="NodeEntryStateStep") | .data.agent_name' "$TRACE"
未调用操作	jq -r '.plan[] | select(.type=="EnabledToolsStep") | .data.enabled_tools[]' "$TRACE"
遵循度低	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 获取真实的子 Agent 调用链。

入口 Agent 直接作答（SMALL_TALK 模式）： 如果 start_agent 跟踪数据显示 SMALL_TALK grounding，且转换工具可见但均未调用，则在 start_agent 指令中添加“你只是一个路由器。不要直接回答问题。”

1-ALT.5 分类并呈现

使用 references/issue-classification.md 中的类别对问题进行分类。呈现发现结果后，自动继续进行 Agent 配置证据分析。

---

阶段 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 返回空结果，则切换到阶段 1-ALT。

1.2 获取对话详情

对最多 5 个会话（按时间从近到远）使用 getMultipleConversationDetails()。该方法会返回逐轮数据，包括消息、步骤、主题和操作结果。

1.2b 获取大模型提示词/响应（可选）

检测到 LOW 遵循度时，使用 getLlmStepDetails() 获取实际的大模型提示词和响应。

1.2c 获取聚合指标（建议首先执行）

使用 getAggregatedMetrics() 获取高级健康状况仪表板：会话率、热门意图、质量分布和 RAG 平均值。

1.2d 获取时刻洞察（单个会话详情）

使用 getMomentInsights() 获取每个会话的意图摘要、质量评分（1-5）和检索器指标。

1.2e 运行可观测性查询（深入分析 RAG）

使用 runObservabilityQuery() 进行有针对性的 RAG 分析：KnowledgeGap、Hallucination、RetrievalQuality、AnswerRelevancy、Leaderboard。

1.3 重构对话

根据每个会话的 ConversationData JSON，呈现逐轮时间线。

1.4 识别问题

完整的问题模式表和分类类别：请参阅 references/issue-classification.md

检查每个会话是否存在：操作错误、子 Agent 路由错误、缺少操作、输入错误、变量捕获失败、没有转换、操作缓慢、LOW 遵循度、会话被放弃、失效的子 Agent、发布漂移、死中心反模式、入口直接作答以及安全问题。

优先级：P1 = 操作错误、路由错误、LOW 遵循度；P2 = 缺少操作、变量错误、知识缺口；P3 = 性能、会话被放弃。

1.5 呈现发现和 Agent 配置证据

呈现已分析的会话、按根因类别归组的问题以及提升预估。然后自动继续分析 .agent 文件，以确认根因。

完整的结构分析检查、交叉引用流程和发布漂移检测：请参阅 references/issue-classification.md

从组织中获取 .agent 文件，运行自动检查（子 Agent 数量与操作块数量对比、死中心检测、孤立操作、跨子 Agent 变量依赖），并根据文件结构交叉核对 STDM 症状。

---

阶段 2：复现 -- 实时预览

完整的预览流程、轨迹诊断命令和分类标准：请参阅 references/reproduce-reference.md

根据阶段 1 中确认的每个问题构建一个测试场景。使用 sf agent preview 和 --authoring-bundle 运行每个场景（生成本地轨迹）。每个场景运行 3 次，并进行分类：

判定	标准
[CONFIRMED]	3 次运行中有 3 次出现相同故障
[INTERMITTENT]	3 次运行中有 1-2 次出现故障
[NOT REPRODUCED]	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 预检

编辑前，确认所有操作目标均存在且已在组织中注册。如果缺少目标，请提供以下选项：部署存根、移除操作、通过 UI 注册，或仅继续进行路由修复。

3.1-3.3 映射问题、编辑并遵循指令原则

将每个已确认的问题映射到 .agent 文件中的修复位置（description、instructions、actions、bindings、transitions）。使用 Edit 工具进行有针对性的修改。遵循指令原则：明确命名操作、说明前置条件、严格限定范围，并且只在 system: 中设置角色设定。

3.4 防止回归

编辑前建立基线。尽量减少修改。每次编辑后立即测试。每个发布周期只修复一个问题。检查跨子 Agent 的依赖关系。测试相邻的子 Agent。

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>

如果发布失败，则使用 deploy + activate 作为回退方案（注意：此方案不完整——不会将 reasoning: actions: 传播到实时元数据）。

3.7 验证

修复后运行 Phase 2 场景。检查跟踪记录，确认路由、依据、工具和变量均正确。24-48 小时后，重新运行 Phase 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	Phase 2 预览流程、跟踪诊断、分类标准
references/improve-reference.md	Phase 3 编辑、部署链路、验证、安全性、测试用例
references/stdm-schema.md	DMO 字段架构、数据层级、质量说明、Agent 名称解析