agentforce-observe

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

Updated Jul 2, 2026
One-click install
npx skills add https://github.com/padjei/SF_Build --skill agentforce-observe-padjei
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: agentforce-observe
Source: https://github.com/padjei/SF_Build/tree/main/.claude/skills/agentforce-observe
Command: npx skills add https://github.com/padjei/SF_Build --skill agentforce-observe-padjei

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Production Agentforce agents can misroute conversations, fail to invoke actions, or drift from instructions, but these failures are hard to diagnose without visibility into real session data. This Skill queries Session Trace Data Model (STDM) records from Data Cloud, reproduces failures in live preview, and applies targeted fixes to the .agent file. ## Core Features & Use Cases - Session Trace Analysis: Query STDM sessions, conversation details, LLM prompts, aggregated metrics, and RAG quality scores from Data Cloud via a deployable Apex helper class. - Issue Classification: Detect and categorize misroutes, action errors, dead subagents, dead hubs, LOW instruction adherence, knowledge gaps, and safety issues with priority levels. - Reproduce and Fix Workflow: Reproduce confirmed issues with sf agent preview and local traces, then edit the .agent file, validate, publish, and verify with regression test cases. - Use Case: An admin reports that a support agent gives generic answers instead of checking order status. Use this Skill to query the last 7 days of sessions, confirm the action is never invoked, reproduce it in preview, fix the subagent instructions, and publish the corrected agent. ## Quick Start Analyze the recent production sessions of my Agentforce agent in org alias myorg and tell me what is going wrong.

Frequently Asked Questions about agentforce-observe

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I analyze Agentforce agent session traces in production?▼

Query the Session Trace Data Model in Data Cloud using the AgentforceOptimizeService Apex helper class, which returns sessions, turn-by-turn conversation details, and quality metrics as JSON. The Skill then classifies issues like misroutes, action errors, and LOW instruction adherence.

How to reproduce an Agentforce agent failure locally?▼

Use sf agent preview with the --authoring-bundle flag to compile from the local .agent file and generate local trace files. Run each failing utterance three times and classify the result as CONFIRMED, INTERMITTENT, or NOT REPRODUCED before attempting fixes.

What if Data Cloud STDM is not available in my org?▼

The Skill falls back to a Phase 1-ALT path using test suites and sf agent preview with local trace analysis. You get instant traces with full LLM prompts and variable state, but no real production user data.

Why does my Agentforce agent give generic answers instead of calling actions?▼

Common causes include missing reasoning actions blocks in the subagent, vague instructions, or publish drift where the bundle was deployed but never properly published. The Skill cross-references STDM symptoms against the .agent file structure to confirm the root cause.

Can I fix agent issues by editing GenAiPluginDefinition metadata directly?▼

No. The .agent file is the single source of truth; fixes must be applied to it and deployed via sf agent validate and sf agent publish. Directly patching GenAiPluginInstructionDef or related BPO objects is explicitly prohibited.