# Agentforce Observe

Analyze production Agentforce agent behavior using session traces and Data Cloud, and...

- Repository: https://github.com/forcedotcom/sf-skills (1134 stars)
- Category: Testing
- License: Apache-2.0
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add forcedotcom/sf-skills --skill agentforce-observe -g -a claude-code -y`
Codex: `npx skills add forcedotcom/sf-skills --skill agentforce-observe -g -a codex -y`
Cursor: `npx skills add forcedotcom/sf-skills --skill agentforce-observe -g -a cursor -y`
Gemini CLI: `npx skills add forcedotcom/sf-skills --skill agentforce-observe -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add forcedotcom/sf-skills`

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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

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

The rest: https://github.com/forcedotcom/sf-skills/blob/HEAD/plugins/builder/agentforce-adlc/skills/agentforce-observe/SKILL.md