agentforce-observe

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agentforce Observability

Agentforce 可观测性

Improve Agentforce agents using session trace data and live preview testing.

Three-phase workflow:

Observe -- Query STDM sessions from Data Cloud (if available), OR run test suites + preview with local traces as fallback
Reproduce -- Use
```
sf agent preview
```
to simulate problematic conversations live
Improve -- Edit the
```
.agent
```
file directly, validate, publish, verify

利用会话追踪数据和实时预览测试优化Agentforce Agent。

三阶段工作流：

观测 -- 从Data Cloud查询STDM会话（若可用），或运行测试套件 + 以本地追踪作为备选方案进行预览
复现 -- 使用
```
sf agent preview
```
实时模拟有问题的对话
优化 -- 直接编辑
```
.agent
```
文件，验证、发布并确认效果

Platform Notes

平台说明

Shell examples below use bash syntax. On Windows, use PowerShell equivalents or Git Bash.
Replace
```
python3
```
with
```
python
```
on Windows.
Replace
```
/tmp/
```
with
```
$env:TEMP\
```
(PowerShell) or
```
%TEMP%\
```
(cmd).
Replace
```
jq
```
with
```
python -c "import json,sys; ..."
```
if jq is not installed.

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

Routing

路由逻辑

Gather these inputs before starting:

Org alias (required)
Agent API name (required for preview and deploy; ask if not provided)
Agent file path (optional) -- path to the
```
.agent
```
file, typically
```
force-app/main/default/aiAuthoringBundles/<AgentName>/<AgentName>.agent
```
. Auto-detect if not provided.
Session IDs (optional) -- analyze specific sessions; if absent, query last 7 days
Days to look back (optional, default 7)

Determine intent from user input:

No specific action -> run all three phases: Observe -> surface issues -> ask if user wants to Reproduce and/or Improve
"analyze" / "sessions" / "what's wrong" -> Phase 1 only, then suggest next steps
"reproduce" / "test" / "preview" -> Phase 2 (run Phase 1 first if no issues in hand)
"fix" / "improve" / "update" -> Phase 3 (run Phase 1 first if no issues in hand)

开始前收集以下输入信息：

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

根据用户输入判断意图：

无特定操作 -> 运行全部三个阶段：观测 -> 呈现问题 -> 询问用户是否需要复现和/或优化
包含"analyze" / "sessions" / "what's wrong" -> 仅运行第一阶段，之后建议下一步操作
包含"reproduce" / "test" / "preview" -> 运行第二阶段（若未掌握问题，先运行第一阶段）
包含"fix" / "improve" / "update" -> 运行第三阶段（若未掌握问题，先运行第一阶段）

Resolve agent name

解析Agent名称

Before any STDM query, resolve the user-provided agent name against the org to get the exact

MasterLabel

and

DeveloperName

bash

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
```
= display name used by STDM
```
findSessions
```
and Agent Builder UI (e.g. "Order Service")
```
DeveloperName
```
= API name with version suffix used in metadata (e.g. "OrderService_v9")

The

--api-name

flag for

sf agent preview/activate/publish

uses

DeveloperName

without the

_vN

suffix (e.g. "OrderService")

Store these values:

```
AGENT_MASTER_LABEL
```
-- for
```
findSessions()
```
agent filter
```
AGENT_API_NAME
```
--
```
DeveloperName
```
without
```
_vN
```
suffix, for
```
sf agent
```
CLI commands
```
PLANNER_ID
```
-- the Salesforce record ID for this agent

在执行任何STDM查询前，将用户提供的Agent名称与组织进行匹配，获取准确的

MasterLabel

和

DeveloperName

：

bash

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

Locate the .agent file

定位.agent文件

Step 1 -- Search locally:

bash

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

If the user provided an agent file path, use that directly. Otherwise, search for files matching

AGENT_API_NAME

Step 2 -- If not found locally, retrieve from the org:

bash

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

Known bug:
sf project retrieve start
creates a double-nested path:
force-app/main/default/main/default/aiAuthoringBundles/...
. Fix it immediately after retrieve:

bash

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

Step 3 -- Validate the retrieved file:

Read the

.agent

file and verify it has proper Agent Script structure:

```
system:
```
block with
```
instructions:
```
```
config:
```
block with
```
developer_name:
```

start_agent

subagent

blocks with

reasoning: instructions:

Each subagent should have distinct
```
instructions:
```
content (not identical across subagents)

Store the resolved path as

AGENT_FILE

for Phase 3.

步骤1 -- 本地搜索：

bash

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

若用户提供了Agent文件路径，则直接使用该路径。否则，搜索与

AGENT_API_NAME

匹配的文件。

步骤2 -- 若本地未找到，从组织中获取：

bash

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

已知问题：
sf project retrieve start
会创建双重嵌套路径：
force-app/main/default/main/default/aiAuthoringBundles/...
。获取后立即修复：

bash

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脚本结构：

包含带
```
instructions:
```
的
```
system:
```
块
包含带
```
developer_name:
```
的
```
config:
```
块

包含带

reasoning: instructions:

的

start_agent

或

subagent

块

每个subagent应具有不同的
```
instructions:
```
内容（subagent之间内容不重复）

将解析后的路径存储为

AGENT_FILE

，用于第三阶段。

Phase 0: Discover Data Space

阶段0：发现数据空间

Before running any STDM query, determine the correct Data Cloud Data Space API name.

bash

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

Note:

sf api request rest

is a beta command -- do not add

--json

(that flag is unsupported and causes an error).

The response shape is:

json

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

The

name

field is the API name to pass to

AgentforceOptimizeService

Decision logic:

If the command fails (e.g. 404 or permission error), fall back to
```
'default'
```
and note it as an assumption.
Filter to only
```
status: "Active"
```
entries.
If exactly one active Data Space exists, use it automatically and confirm to the user: "Using Data Space:
```
<name>
```
".
If multiple active Data Spaces exist, show the list (label + name) and ask the user which to use.

Store the selected

name

value as

DATA_SPACE

for all subsequent steps.

在执行任何STDM查询前，确定正确的Data Cloud数据空间API名称。

bash

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

注意：

sf api request rest

是beta版命令 -- 请勿添加

--json

（该参数不被支持，会导致错误）。

响应格式如下：

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"
```
的条目。
若恰好存在一个活跃数据空间，则自动使用该空间并向用户确认："正在使用数据空间：
```
<name>
```
"。
若存在多个活跃数据空间，则显示列表（标签+名称）并询问用户使用哪个。

将选定的

name

值存储为

DATA_SPACE

，用于后续所有步骤。

Prerequisite check: STDM DMOs

前置检查：STDM DMO

After deploying the helper class (step 1.0), run a quick probe to verify the STDM Data Model Objects exist in Data Cloud:

bash

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

If
STDM_CHECK:FAIL
: STDM is not activated. Inform the user and switch to Phase 1-ALT:

STDM (Session Trace Data Model) is not available in this org. To enable: Setup -> Data Cloud -> Data Streams and verify "Agentforce Activity" is active. Proceeding with fallback: test suites + local traces.

If
STDM_CHECK:OK
, proceed to Phase 1 (STDM path).

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

bash

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-备选方案：

此组织中未启用STDM（会话追踪数据模型）。启用方法：设置 -> Data Cloud -> 数据流，确认"Agentforce Activity"已激活。将使用备选方案继续：测试套件 + 本地追踪。

若返回
STDM_CHECK:OK
，则进入阶段1（STDM路径）。

Phase 1-ALT: Observe Without STDM (Fallback Path)

阶段1-备选方案：无STDM时的观测（ fallback路径）

When STDM is not available, use test suites and

sf agent preview --authoring-bundle

with local trace analysis.

Data source	When to use	Pros	Cons
STDM (Phase 1)	Historical production analysis	Real user data, volume	Requires Data Cloud, 15-min lag
Test suites + local traces (Phase 1-ALT)	Dev iteration, orgs without STDM	Instant, full LLM prompt, variable state	Preview only, no real user data

当STDM不可用时，使用测试套件和

sf agent preview --authoring-bundle

进行本地追踪分析。

数据源	使用场景	优势	劣势
STDM（阶段1）	历史生产环境分析	真实用户数据，数据量大	需要Data Cloud，存在15分钟延迟
测试套件 + 本地追踪（阶段1-备选方案）	开发迭代、无STDM的组织	即时性，完整LLM提示，变量状态可见	仅预览环境，无真实用户数据

1-ALT.1 Run existing test suite (if available)

1-备选方案.1 运行现有测试套件（若可用）

bash

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>

bash

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 Derive test utterances from .agent file (if no test suite)

1-备选方案.2 从.agent文件推导测试语句（若无测试套件）

If no test suite exists, derive utterances: one per non-entry subagent (from

description:

keywords), one per key action, one guardrail test, one multi-turn test.

若不存在测试套件，则推导测试语句：每个非入口subagent对应一条（从

description:

关键字提取），每个关键操作对应一条，一条防护测试语句，一条多轮对话测试语句。

1-ALT.3 Preview with

--authoring-bundle

(local traces)

1-备选方案.3 使用

--authoring-bundle

进行预览（本地追踪）

Run each test utterance through preview to generate local trace files:

bash

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>

Trace file location:

.sfdx/agents/{BundleName}/sessions/{sessionId}/traces/{planId}.json

将每条测试语句通过预览运行，生成本地追踪文件：

bash

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 Local trace diagnosis

1-备选方案.4 本地追踪诊断

Issue type	Trace command
Subagent misroute	`jq -r '.plan[] \| select(.type=="NodeEntryStateStep") \| .data.agent_name' "$TRACE"`
Action not called	`jq -r '.plan[] \| select(.type=="EnabledToolsStep") \| .data.enabled_tools[]' "$TRACE"`
LOW adherence	`jq -r '.plan[] \| select(.type=="ReasoningStep") \| {category, reason}' "$TRACE"`
Variable capture fail	`jq -r '.plan[] \| select(.type=="VariableUpdateStep") \| .data.variable_updates[]' "$TRACE"`
Vague instructions	`jq -r '.plan[] \| select(.type=="LLMStep") \| .data.messages_sent[0].content' "$TRACE"`

DefaultTopic trace quirk: With

--authoring-bundle

, the root

.topic

field often shows

"DefaultTopic"

even when routing works. Always use

NodeEntryStateStep.data.agent_name

for the real subagent chain.

Entry answering directly (SMALL_TALK pattern): If

start_agent

trace shows

SMALL_TALK

grounding and transition tools visible but none invoked, add "You are a router only. Do NOT answer questions directly." to

start_agent

instructions.

问题类型	追踪命令
Subagent路由错误	`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

查看真实的subagent调用链。

入口直接回复（SMALL_TALK模式）： 若

start_agent

追踪显示SMALL_TALK基础设置和过渡工具可见但未被调用，请在

start_agent

指令中添加"你仅作为路由使用。请勿直接回答问题。"

1-ALT.5 Classify and present

1-备选方案.5 分类并呈现结果

Classify issues using the categories in

references/issue-classification.md

. After presenting findings, automatically proceed to agent config evidence analysis.

使用

references/issue-classification.md

中的类别对问题进行分类。呈现结果后，自动进入Agent配置证据分析环节。

Phase 1: Observe -- Query STDM

阶段1：观测 -- 查询STDM

Full STDM query details, Apex service deployment, and response parsing: see
references/stdm-queries.md

STDM查询详情、Apex服务部署和响应解析：请查看
references/stdm-queries.md

1.0 Deploy helper class (once per org)

1.0 部署辅助类（每个组织部署一次）

Deploy

AgentforceOptimizeService

Apex class to the org. Check if already deployed first:

bash

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

If not deployed, copy from skill directory and deploy. See

references/stdm-queries.md

for full steps.

将

AgentforceOptimizeService

Apex类部署到组织。先检查是否已部署：

bash

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

若未部署，则从技能目录复制并部署。完整步骤请查看

references/stdm-queries.md

。

1.1 Find sessions

1.1 查找会话

Query recent sessions using

findSessions()

. Parse

DEBUG|STDM_RESULT:

from the Apex debug log. If

findSessions

returns empty, switch to Phase 1-ALT.

使用

findSessions()

查询近期会话。从Apex调试日志中解析

DEBUG|STDM_RESULT:

。若

findSessions

返回空结果，则切换到阶段1-备选方案。

1.2 Get conversation details

1.2 获取对话详情

Use

getMultipleConversationDetails()

for up to 5 sessions (most recent first). Returns turn-by-turn data with messages, steps, topics, and action results.

使用

getMultipleConversationDetails()

获取最多5个会话的详情（按时间从新到旧排序）。返回包含消息、步骤、主题和操作结果的逐轮对话数据。

1.2b Get LLM prompt/response (optional)

1.2b 获取LLM提示/响应（可选）

When LOW adherence detected, use

getLlmStepDetails()

to get the actual LLM prompt and response.

检测到低合规性时，使用

getLlmStepDetails()

获取实际的LLM提示和响应。

1.2c Get aggregated metrics (recommended first step)

1.2c 获取聚合指标（推荐第一步）

Use

getAggregatedMetrics()

for high-level health dashboard: session rates, top intents, quality distribution, RAG averages.

使用

getAggregatedMetrics()

获取高级健康仪表盘：会话率、热门意图、质量分布、RAG平均值。

1.2d Get moment insights (per-session detail)

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

Use

getMomentInsights()

for intent summaries, quality scores (1-5), and retriever metrics per session.

使用

getMomentInsights()

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

1.2e Run observability queries (RAG deep-dive)

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

Use

runObservabilityQuery()

for targeted RAG analysis: KnowledgeGap, Hallucination, RetrievalQuality, AnswerRelevancy, Leaderboard.

使用

runObservabilityQuery()

进行针对性RAG分析：KnowledgeGap、Hallucination、RetrievalQuality、AnswerRelevancy、Leaderboard。

1.3 Reconstruct conversations

1.3 重构对话

Render turn-by-turn timeline from

ConversationData

JSON for each session.

从每个会话的

ConversationData

JSON中渲染逐轮对话时间线。

1.4 Identify issues

1.4 识别问题

Full issue pattern table and classification categories: see
references/issue-classification.md

Check each session for: action errors, subagent misroutes, missing actions, wrong inputs, variable capture failures, no transitions, slow actions, LOW adherence, abandoned sessions, dead subagents, publish drift, dead hub anti-pattern, entry answering directly, and safety issues.

Priority: P1 = action errors, misroutes, LOW adherence; P2 = missing actions, variable bugs, knowledge gaps; P3 = performance, abandoned sessions.

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

检查每个会话是否存在以下问题：操作错误、subagent路由错误、缺失操作、输入错误、变量捕获失败、无过渡、操作缓慢、低合规性、会话中断、无效subagent、发布漂移、无效枢纽反模式、入口直接回复、安全问题。

优先级：P1 = 操作错误、路由错误、低合规性；P2 = 缺失操作、变量bug、知识缺口；P3 = 性能问题、会话中断。

1.5 Present findings and agent config evidence

1.5 呈现结果和Agent配置证据

Present sessions analyzed, issues grouped by root cause category, and uplift estimate. Then automatically proceed to analyze the

.agent

file to confirm root causes.

Full structural analysis checks, cross-reference procedures, and publish drift detection: see
references/issue-classification.md

Retrieve the

.agent

file from the org, run automated checks (subagent count vs action blocks, dead hub detection, orphan actions, cross-subagent variable dependencies), and cross-reference STDM symptoms against the file structure.

呈现已分析的会话、按根因分类的问题以及优化预估。然后自动获取

.agent

文件进行分析，确认根因。

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

从组织中获取

.agent

文件，运行自动化检查（subagent数量与操作块对比、无效枢纽检测、孤立操作、跨subagent变量依赖），并将STDM症状与文件结构进行交叉验证。

Phase 2: Reproduce -- Live Preview

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

Full preview procedures, trace diagnosis commands, and classification criteria: see
references/reproduce-reference.md

Build one test scenario per confirmed issue from Phase 1. Run each through

sf agent preview

with

--authoring-bundle

(generates local traces). Run each scenario 3 times and classify:

Verdict	Criteria
`[CONFIRMED]`	Same failure in 3/3 runs
`[INTERMITTENT]`	Failure in 1-2 of 3 runs
`[NOT REPRODUCED]`	Passes in 3/3 runs

Only

[CONFIRMED]

and

[INTERMITTENT]

issues proceed to Phase 3.

Key commands:

bash

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>

Trace location:

.sfdx/agents/{Name}/sessions/{sessionId}/traces/{planId}.json

完整的预览流程、追踪诊断命令和分类标准：请查看
references/reproduce-reference.md

针对阶段1中确认的每个问题构建一个测试场景。通过

sf agent preview

结合

--authoring-bundle

运行每个场景（生成本地追踪）。每个场景运行3次并分类：

结论	判定标准
`[CONFIRMED]`	3次运行均出现相同故障
`[INTERMITTENT]`	1-2次运行出现故障
`[NOT REPRODUCED]`	3次运行均通过

仅

[CONFIRMED]

和

[INTERMITTENT]

问题进入阶段3。

关键命令：

bash

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: Improve -- Edit .agent File Directly

阶段3：优化 -- 直接编辑.agent文件

Full procedures for pre-flight checks, fix mapping, instruction principles, regression prevention, deployment chain, verification, safety re-verification, and test case creation: see
references/improve-reference.md

完整的预检流程、修复映射、指令原则、回归预防、部署链、验证、安全重验证和测试用例创建：请查看
references/improve-reference.md

3.0 Pre-flight

3.0 预检

Verify all action targets exist and are registered in the org before editing. If targets are missing, present options: deploy stubs, remove actions, register via UI, or proceed with routing-only fixes.

编辑前验证所有操作目标在组织中存在并已注册。若目标缺失，则提供选项：部署存根、移除操作、通过UI注册或仅进行路由修复。

3.1-3.3 Map issue, edit, and follow instruction principles

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

Map each confirmed issue to a fix location in the

.agent

file (description, instructions, actions, bindings, transitions). Use the Edit tool for targeted changes. Follow instruction principles: name actions explicitly, state pre-conditions, scope tightly, keep persona in

system:

only.

将每个确认的问题映射到

.agent

文件中的修复位置（描述、指令、操作、绑定、过渡）。使用编辑工具进行针对性修改。遵循指令原则：明确命名操作、说明前置条件、严格限定范围、仅在

system:

块中定义角色。

3.4 Regression prevention

3.4 回归预防

Establish baseline before editing. Make minimal edits. Test immediately after each edit. One fix per publish cycle. Check cross-subagent dependencies. Test adjacent subagents.

编辑前建立基准。尽量最小化修改。每次编辑后立即测试。每次发布仅修复一个问题。检查跨subagent依赖。测试相邻subagent。

3.5 Apply fixes

3.5 应用修复

Read the

.agent

file, edit with the Edit tool (tabs for indentation), show the diff.

读取

.agent

文件，使用编辑工具进行编辑（使用制表符缩进），显示差异。

3.6 Validate, deploy, publish, activate

3.6 验证、部署、发布、激活

bash

undefined

bash

undefined

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>


If publish fails, use deploy + activate fallback (note: incomplete -- does not propagate `reasoning: actions:` to live metadata).

sf agent publish authoring-bundle --json --api-name <AGENT_API_NAME> -o <org>


若发布失败，则使用部署+激活的备选方案（注意：该方案不完整 -- 不会将`reasoning: actions:`同步到实时元数据）。

3.7 Verify

3.7 验证

Run Phase 2 scenarios post-fix. Check trace for correct routing, grounding, tools, and variables. After 24-48 hours, re-run Phase 1 to compare against baseline.

修复后运行阶段2的场景。检查追踪文件中的路由、基础设置、工具和变量是否正确。24-48小时后，重新运行阶段1并与基准进行对比。

3.7b Safety re-verification (required)

3.7b 安全重验证（必填）

Re-run safety review (

Section 15 of /agentforce-generate

) on the modified

.agent

file. Revert any changes that introduce BLOCK findings.

对修改后的

.agent

文件重新运行安全审核（

/agentforce-generate

的第15节）。若修改引入BLOCK级问题，则回滚更改。

3.8 Update Testing Center test cases

3.8 更新测试中心测试用例

Create regression test cases from confirmed issues in Testing Center YAML format. Deploy with

sf agent test create

and verify all previously-broken scenarios pass.

将确认的问题转化为测试中心YAML格式的回归测试用例。使用

sf agent test create

部署并验证所有之前故障的场景均已通过。

Reference Files

参考文件

Reference	Contents
`references/stdm-queries.md`	STDM query procedures, Apex service deployment, response parsing
`references/issue-classification.md`	Issue pattern table, root cause categories, structural analysis checks
`references/reproduce-reference.md`	Phase 2 preview procedures, trace diagnosis, classification criteria
`references/improve-reference.md`	Phase 3 editing, deployment chain, verification, safety, test cases
`references/stdm-schema.md`	DMO field schemas, data hierarchy, quality notes, agent name resolution

参考文件	内容
`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字段 schema、数据层级、质量说明、Agent名称解析

agentforce-observe

Original

Translation

Agentforce Observability

Agentforce 可观测性

Platform Notes

平台说明

Routing

路由逻辑

Resolve agent name

解析Agent名称

Locate the .agent file

定位.agent文件

Phase 0: Discover Data Space

阶段0：发现数据空间

Prerequisite check: STDM DMOs

前置检查：STDM DMO

Phase 1-ALT: Observe Without STDM (Fallback Path)

阶段1-备选方案：无STDM时的观测（ fallback路径）

1-ALT.1 Run existing test suite (if available)

1-备选方案.1 运行现有测试套件（若可用）

1-ALT.2 Derive test utterances from .agent file (if no test suite)

1-备选方案.2 从.agent文件推导测试语句（若无测试套件）

1-ALT.3 Preview with --authoring-bundle (local traces)

1-备选方案.3 使用--authoring-bundle进行预览（本地追踪）

1-ALT.4 Local trace diagnosis

1-备选方案.4 本地追踪诊断

1-ALT.5 Classify and present

1-备选方案.5 分类并呈现结果

Phase 1: Observe -- Query STDM

阶段1：观测 -- 查询STDM

1.0 Deploy helper class (once per org)

1.0 部署辅助类（每个组织部署一次）

1.1 Find sessions

1.1 查找会话

1.2 Get conversation details

1.2 获取对话详情

1.2b Get LLM prompt/response (optional)

1.2b 获取LLM提示/响应（可选）

1.2c Get aggregated metrics (recommended first step)

1.2c 获取聚合指标（推荐第一步）

1.2d Get moment insights (per-session detail)

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

1.2e Run observability queries (RAG deep-dive)

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

1.3 Reconstruct conversations

1.3 重构对话

1.4 Identify issues

1.4 识别问题

1.5 Present findings and agent config evidence

1.5 呈现结果和Agent配置证据

Phase 2: Reproduce -- Live Preview

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

Phase 3: Improve -- Edit .agent File Directly

阶段3：优化 -- 直接编辑.agent文件

3.0 Pre-flight

3.0 预检

3.1-3.3 Map issue, edit, and follow instruction principles

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

3.4 Regression prevention

3.4 回归预防

3.5 Apply fixes

3.5 应用修复

3.6 Validate, deploy, publish, activate

3.6 验证、部署、发布、激活

Validate (dry run)

验证（试运行）

Publish (compile + deploy + activate)

发布（编译 + 部署 + 激活）

3.7 Verify

3.7 验证

3.7b Safety re-verification (required)

3.7b 安全重验证（必填）

3.8 Update Testing Center test cases

3.8 更新测试中心测试用例

Reference Files

参考文件

1-ALT.3 Preview with
`--authoring-bundle`
(local traces)

1-备选方案.3 使用
`--authoring-bundle`
进行预览（本地追踪）