• 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

• 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.

• 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)

• 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)

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

  = 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")

• 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

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

AGENT_API_NAME

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:

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

.agent

• system:

  block with

  instructions:

• config:

  block with

  developer_name:

• start_agent

  or

  topic

  blocks with

  reasoning: instructions:

• Each topic should have distinct

  instructions:

  content (not identical across topics)

AGENT_FILE

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

• 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.

name

DATA_SPACE

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 (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.

STDM_CHECK:OK

Full STDM query details, Apex service deployment, and response parsing: see

references/stdm-queries.md

Full issue pattern table and classification categories: see

references/issue-classification.md

.agent

Full structural analysis checks, cross-reference procedures, and publish drift detection: see

references/issue-classification.md

.agent

Full preview procedures, trace diagnosis commands, and classification criteria: see

references/reproduce-reference.md

sf agent preview

--authoring-bundle

[CONFIRMED]

[INTERMITTENT]

[NOT REPRODUCED]

[CONFIRMED]

[INTERMITTENT]

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

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