observing-agentforce

Analyze production Agentforce agent behavior using session traces and Data Cloud. 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. DO NOT TRIGGER when: user creates, modifies, or debugs .agent files during development (use developi

608stars215forksUpdated 6/25/2026

Developer Tools #debugging #observability #data-cloud #agentforce #salesforce

Security Assessment

Safe(100/100)

Detected risks:

Agent-reviewed override(rm -rf targets a generated Salesforce scaffold subdir (force-app/main/default/main) in a documented setup step; 'eval (' is a substring of 'retrieval (' in a metrics reference. Both benign.)

Security Score100/100

About observing-agentforce

Observing Agentforce analyzes production Agentforce agent behavior using session trace data and live preview testing, helping investigate failures, regressions, and performance issues. It triggers when a user queries STDM session data or Data Cloud trace records, investigates production agent problems, asks about session traces or agent metrics, or wants to reproduce a reported production issue in preview. It deliberately does not trigger for authoring-time work such as creating or debugging .agent files (developing-agentforce), writing or running test specs (testing-agentforce), or deploying and publishing agents.

The workflow has three phases. Observe queries STDM (Session Trace Data Model) sessions from Data Cloud when available, or falls back to running test suites plus `sf agent preview` with local traces. Reproduce uses `sf agent preview` to simulate problematic conversations live. Improve edits the .agent file directly, validates, publishes, and verifies. Before any STDM query, the skill resolves the user-provided agent name against the org to get the exact MasterLabel (used by findSessions and the Agent Builder UI) and DeveloperName (the API name with a version suffix), noting that `sf agent` CLI commands use the DeveloperName without the _vN suffix. It locates the .agent file locally under force-app and, if absent, retrieves it from the org -- fixing a known double-nested path bug from `sf project retrieve start` -- then validates the file's Agent Script structure.

Phase 0 discovers the correct Data Cloud Data Space via a REST request to the data-spaces endpoint (a beta command that must not take --json), filters to Active spaces, and either auto-selects a single space or asks the user to choose. A prerequisite probe runs Apex against the STDM Data Model Objects to confirm they exist; on failure the skill explains how to enable Agentforce activity in Data Cloud and switches to the fallback path of test suites and local traces, which trades real user data for instant, full-prompt visibility. Platform notes cover bash-versus-PowerShell equivalents and substitutes for jq. The skill is scoped to Claude Code and uses Bash, Read, Write, Edit, Glob, and Grep, accepting arguments such as an org alias, an optional agent file path, session id, and a look-back day count.

FAQ

When should this skill be used instead of the other Agentforce skills?

Use it to analyze production agent behavior from session traces or Data Cloud, investigate failures or regressions, or reproduce a reported issue in preview. Do not use it for authoring .agent files (developing-agentforce), writing test specs (testing-agentforce), or deploying and publishing agents.

What happens if STDM is not available in the org?

A prerequisite Apex probe checks the STDM Data Model Objects; if it fails, STDM is not activated. The skill informs the user how to enable Agentforce activity in Data Cloud and switches to Phase 1-ALT, observing via test suites and `sf agent preview` with local traces.

Why does it resolve the agent name before querying?

It resolves the name against the org to get the exact MasterLabel (used by findSessions and Agent Builder) and DeveloperName (API name with a version suffix). The `sf agent` CLI commands use the DeveloperName without the _vN suffix, so the correct value matters.

How does it find the Data Cloud Data Space?

Phase 0 calls the data-spaces REST endpoint (a beta command that must not include --json), filters to Active spaces, auto-selects when exactly one exists, and asks the user to choose when multiple do. If the call fails it falls back to 'default' and notes the assumption.

What tools and inputs does it require?

It is scoped to Claude Code and uses Bash, Read, Write, Edit, Glob, and Grep. It requires an org alias and the agent API name for preview and deploy, and optionally accepts an agent file path, session IDs, and a look-back day count (default 7).