agentforce-observe

Name: agentforce-observe
Author: SalesforceAIResearch

178installs37forks

How to install agentforce-observe?

salesforceairesearch/agentforce-adlc/agentforce-observe

$npx -y skills add SalesforceAIResearch/agentforce-adlc --skill agentforce-observe

Installs into the current project.

Summary

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

Files · 1

View on GitHub

SKILL.md

1	# Agentforce Observability
2
3	Improve Agentforce agents using session trace data and live preview testing.
4
5	Three-phase workflow:
6	- Observe -- Query STDM sessions from Data Cloud (if available), OR run test suites + preview with local traces as fallback
7	- Reproduce -- Use `sf agent preview` to simulate problematic conversations live
8	- Improve -- Edit the `.agent` file directly, validate, publish, verify
9
10	---
11
12	## Platform Notes
13
14	- Shell examples below use bash syntax. On Windows, use PowerShell equivalents or Git Bash.
15	- Replace `python3` with `python` on Windows.
16	- Replace `/tmp/` with `$env:TEMP\` (PowerShell) or `%TEMP%\` (cmd).
17	- Replace `jq` with `python -c "import json,sys; ..."` if jq is not installed.
18
19	---
20
21	## Routing
22
23	Gather these inputs before starting:
24
25	- Org alias (required)
26	- Agent API name (required for preview and deploy; ask if not provided)
27	- Agent file path (optional) -- path to the `.agent` file, typically `force-app/main/default/aiAuthoringBundles/<AgentName>/<AgentName>.agent`. Auto-detect if not provided.
28	- Session IDs (optional) -- analyze specific sessions; if absent, query last 7 days
29	- Days to look back (optional, default 7)
30
31	Determine intent from user input:
32
33	- No specific action -> run all three phases: Observe -> surface issues -> ask if user wants to Reproduce and/or Improve
34	- "analyze" / "sessions" / "what's wrong" -> Phase 1 only, then suggest next steps
35	- "reproduce" / "test" / "preview" -> Phase 2 (run Phase 1 first if no issues in hand)
36	- "fix" / "improve" / "update" -> Phase 3 (run Phase 1 first if no issues in hand)
37
38	### Resolve agent name
39
40	Before any STDM query, resolve the user-provided agent name against the org to get the exact `MasterLabel` and `DeveloperName`:
41
42	```bash
43	sf data query --json \
44	--query "SELECT Id, MasterLabel, DeveloperName FROM GenAiPlannerDefinition WHERE MasterLabel LIKE '%<user-provided-name>%' OR DeveloperName LIKE '%<user-provided-name>%'" \
45	-o <org>
46	```
47
48	- `MasterLabel` = display name used by STDM `findSessions` and Agent Builder UI (e.g. "Order Service")
49	- `DeveloperName` = API name with version suffix used in metadata (e.g. "OrderService_v9")
50	- The `--api-name` flag for `sf agent preview/activate/publish` uses `DeveloperName` without the `_vN` suffix (e.g. "OrderService")
51
52	Store these values:
53	- `AGENT_MASTER_LABEL` -- for `findSessions()` agent filter
54	- `AGENT_API_NAME` -- `DeveloperName` without `_vN` suffix, for `sf agent` CLI commands
55	- `PLANNER_ID` -- the Salesforce record ID for this agent
56
57	### Locate the .agent file
58
59	Step 1 -- Search locally:
60
61	```bash
62	find <project-root>/force-app/main/default/aiAuthoringBundles -name "*.agent" 2>/dev/null
63	```
64
65	If the user provided an agent file path, use that directly. Otherwise, search for files matching `AGENT_API_NAME`.
66
67	Step 2 -- If not found locally, retrieve from the org:
68
69	```bash
70	sf project retrieve start --json --metadata "AiAuthoringBundle:<AGENT_API_NAME>" -o <org>
71	```
72
73	> Known bug: `sf project retrieve start` creates a double-nested path: `force-app/main/default/main/default/aiAuthoringBundles/...`. Fix it immediately after retrieve:
74
75	```bash
76	if [ -d "force-app/main/default/main/default/aiAuthoringBundles" ]; then
77	mkdir -p force-app/main/default/aiAuthoringBundles
78	cp -r force-app/main/default/main/default/aiAuthoringBundles/* \
79	force-app/main/default/aiAuthoringBundles/
80	rm -rf force-app/main/default/main
81	fi
82	```
83
84	Step 3 -- Validate the retrieved file:
85
86	Read the `.agent` file and verify it has proper Agent Script structure:
87	- `system:` block with `instructions:`
88	- `config:` block with `developer_name:`
89	- `start_agent` or `subagent` blocks with `reasoning: instructions:`
90	- Each subagent should have distinct `instructions:` content (not identical across subagents)
91
92	Store the resolved path as `AGENT_FILE` for Phase 3.
93
94	---
95
96	## Phase 0: Discover Data Space
97
98	Before running any STDM query, determine the correct Data Cloud Data Space API name.
99
100	```bash
101	sf api request rest "/services/data/v63.0/ssot/data-spaces" -o <org>
102	```
103
104	Note: `sf api request rest` is a beta command -- do not

People who liked this also viewed

6 picks

Type

agentforce-observe

178installs37forks

View on GitHub

How to install agentforce-observe?

salesforceairesearch/agentforce-adlc/agentforce-observe

$npx -y skills add SalesforceAIResearch/agentforce-adlc --skill agentforce-observe

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Agentforce Observability
2
3	Improve Agentforce agents using session trace data and live preview testing.
4
5	Three-phase workflow:
6	- Observe -- Query STDM sessions from Data Cloud (if available), OR run test suites + preview with local traces as fallback
7	- Reproduce -- Use `sf agent preview` to simulate problematic conversations live
8	- Improve -- Edit the `.agent` file directly, validate, publish, verify
9
10	---
11
12	## Platform Notes
13
14	- Shell examples below use bash syntax. On Windows, use PowerShell equivalents or Git Bash.
15	- Replace `python3` with `python` on Windows.
16	- Replace `/tmp/` with `$env:TEMP\` (PowerShell) or `%TEMP%\` (cmd).
17	- Replace `jq` with `python -c "import json,sys; ..."` if jq is not installed.
18
19	---
20
21	## Routing
22
23	Gather these inputs before starting:
24
25	- Org alias (required)
26	- Agent API name (required for preview and deploy; ask if not provided)
27	- Agent file path (optional) -- path to the `.agent` file, typically `force-app/main/default/aiAuthoringBundles/<AgentName>/<AgentName>.agent`. Auto-detect if not provided.
28	- Session IDs (optional) -- analyze specific sessions; if absent, query last 7 days
29	- Days to look back (optional, default 7)
30
31	Determine intent from user input:
32
33	- No specific action -> run all three phases: Observe -> surface issues -> ask if user wants to Reproduce and/or Improve
34	- "analyze" / "sessions" / "what's wrong" -> Phase 1 only, then suggest next steps
35	- "reproduce" / "test" / "preview" -> Phase 2 (run Phase 1 first if no issues in hand)
36	- "fix" / "improve" / "update" -> Phase 3 (run Phase 1 first if no issues in hand)
37
38	### Resolve agent name
39
40	Before any STDM query, resolve the user-provided agent name against the org to get the exact `MasterLabel` and `DeveloperName`:
41
42	```bash
43	sf data query --json \
44	--query "SELECT Id, MasterLabel, DeveloperName FROM GenAiPlannerDefinition WHERE MasterLabel LIKE '%<user-provided-name>%' OR DeveloperName LIKE '%<user-provided-name>%'" \
45	-o <org>
46	```
47
48	- `MasterLabel` = display name used by STDM `findSessions` and Agent Builder UI (e.g. "Order Service")
49	- `DeveloperName` = API name with version suffix used in metadata (e.g. "OrderService_v9")
50	- The `--api-name` flag for `sf agent preview/activate/publish` uses `DeveloperName` without the `_vN` suffix (e.g. "OrderService")
51
52	Store these values:
53	- `AGENT_MASTER_LABEL` -- for `findSessions()` agent filter
54	- `AGENT_API_NAME` -- `DeveloperName` without `_vN` suffix, for `sf agent` CLI commands
55	- `PLANNER_ID` -- the Salesforce record ID for this agent
56
57	### Locate the .agent file
58
59	Step 1 -- Search locally:
60
61	```bash
62	find <project-root>/force-app/main/default/aiAuthoringBundles -name "*.agent" 2>/dev/null
63	```
64
65	If the user provided an agent file path, use that directly. Otherwise, search for files matching `AGENT_API_NAME`.
66
67	Step 2 -- If not found locally, retrieve from the org:
68
69	```bash
70	sf project retrieve start --json --metadata "AiAuthoringBundle:<AGENT_API_NAME>" -o <org>
71	```
72
73	> Known bug: `sf project retrieve start` creates a double-nested path: `force-app/main/default/main/default/aiAuthoringBundles/...`. Fix it immediately after retrieve:
74
75	```bash
76	if [ -d "force-app/main/default/main/default/aiAuthoringBundles" ]; then
77	mkdir -p force-app/main/default/aiAuthoringBundles
78	cp -r force-app/main/default/main/default/aiAuthoringBundles/* \
79	force-app/main/default/aiAuthoringBundles/
80	rm -rf force-app/main/default/main
81	fi
82	```
83
84	Step 3 -- Validate the retrieved file:
85
86	Read the `.agent` file and verify it has proper Agent Script structure:
87	- `system:` block with `instructions:`
88	- `config:` block with `developer_name:`
89	- `start_agent` or `subagent` blocks with `reasoning: instructions:`
90	- Each subagent should have distinct `instructions:` content (not identical across subagents)
91
92	Store the resolved path as `AGENT_FILE` for Phase 3.
93
94	---
95
96	## Phase 0: Discover Data Space
97
98	Before running any STDM query, determine the correct Data Cloud Data Space API name.
99
100	```bash
101	sf api request rest "/services/data/v63.0/ssot/data-spaces" -o <org>
102	```
103
104	Note: `sf api request rest` is a beta command -- do not

People who liked this also viewed

6 picks

Type