/agentforce-observe

name: agentforce-observe
description: "Analyze production Agentforce agent behavior using session traces and Data Cloud, and manage Agent Health Monitoring (AHM) alerts. TRIGGER when: user queries STDM session data or Data Cloud trace records; investigates production agent failures, regressions, or performance issues; asks about session traces, conversation logs, or agent metrics; wants to reproduce a reported production issue in preview; runs findSessions or trace analysis queries; creates, lists, updates, or deletes an AHM data alert on an agent metric (escalation rate, deflection, etc.); asks why an alert is not firing or wants to check whether alerts have fired (notification counts, or the per-alert Incidents view). DO NOT TRIGGER when: user creates, modifies, or debugs .agent files during development (use agentforce-generate); writes or runs test specs (use agentforce-test); uses sf agent preview for local development iteration; deploys or publishes agents."
allowed-tools: Bash Read Write Edit Glob Grep
metadata:
  relatedSkills:
    - "agentforce-generate"
    - "agentforce-test"
  version: "0.9"
  domains: ["Agentforce", "Data 360"]
  cliTools:
    - tool: ["git"]
      semver: ">=2.0.0"
    - tool: ["jq"]
      semver: ">=1.6.0"
    - tool: ["python3"]
      semver: ">=3.10.0"
    - tool: ["sf"]
      semver: ">=2.136.8"

Agentforce Observability

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

---

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.

---

Routing

Gather these inputs before starting:

• **Org alias** (required) -- must be authenticated (else `sf org login web`)
• **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)
• **Alert owner user** (optional, alerts only) -- user whose alerts to list/manage; defaults to the current user

Determine intent from user input:

• **No specific action** -> run all three analysis 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)
• **"create alert" / "set up monitoring" / "alert me when"** -> AHM (create)
• **"list alerts" / "show my alerts" / "update alert" / "delete alert"** -> AHM (list / update via PUT / delete)
• **"get / list notifications" / "notifications for a specific alert" / "have my alerts fired" / "why isn't my alert firing"** -> AHM: fetch notifications with header `X-UNS-Type-Filter: all`, report status + list; for a specific alert, filter by alertId from `targetPageRef.state.c__alertId` (15/18-char-safe), not metricId (+ Incidents view + metric verify)

Resolve agent name

Before any STDM query, resolve the user-provided agent name against the org to get the exact `MasterLabel` and `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")

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

Locate the .agent file

**Step 1 -- Search locally:**

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:**

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

**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` or `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.

---

Phase 0: Discover Data Sp