Skip to content

Commit b40d286

Browse files
actions-useractions-user
committed
feat: Release Skills Renaming by domain first convention @W-23187998@
1 parent a95d0d3 commit b40d286

1,674 files changed

Lines changed: 345090 additions & 10 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎skills/activating-datacloud/CREDITS.md‎

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎skills/agentforce-architecture-analyze/README.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# agentforce-architecture-analyze
2+
3+
Declared architecture snapshot for a single Agentforce agent: planner + topics + actions + flows + Apex + prompts + NGA plugins. Reads design-time metadata only (`BotDefinition` + `GenAi*` Tooling objects + Metadata API retrieve) — no runtime audit data.
4+
5+
Input: an `agent_api_name` (the `BotDefinition.DeveloperName`) and an org alias. Optional `agent_version_api_name` to pin a version; otherwise the active `BotVersion` resolves.
6+
7+
Output: two files under `~/.vibe/data/agentforce-architecture-analyze/<org_id15>/<agent>__<version>/` — a normalized `<agent>_<ver>_metadata_tree.json` and a human-readable `<agent>_<ver>_architecture.md`. Override with `--data-dir <path>` (other runtimes pass this to land artifacts under their own distribution layout).
8+
9+
---
10+
11+
## Runtime budget
12+
13+
**30–45s typical, ≤60s hard cap** on the reference fixtures.
14+
15+
A naive sequential implementation (Metadata API retrieves only) would take 90–220s. Speedup: **3–5×**.
16+
17+
Scaling note: large bots with many flows scale approximately linearly in flow count. Each Flow metadata retrieve is an individual SOQL round-trip; a 20-flow bot takes proportionally longer than a 5-flow bot. The 7 planner-side Tooling SOQL fan-outs are constant-cost (single fan-out regardless of bot size); the flow/apex body fetch wave scales with ref count.
18+
19+
---
20+
21+
## Prerequisites
22+
23+
| Tool | Why |
24+
|---|---|
25+
| `sf` CLI (authenticated against the target org) | Shells `sf org display --target-org <alias> --json` for access token, and `sf sobject describe` for the 7-day channel probe |
26+
| Python 3.10+ | `pathlib`, dataclasses, `\|` union types, `concurrent.futures` |
27+
28+
---
29+
30+
## Usage
31+
32+
Invoked conversationally through whatever skill-aware runtime hosts it. Example prompts:
33+
34+
| User says | Skill does |
35+
|---|---|
36+
| `document the architecture of MyAgent in my-org-alias` | Resolve active version, fetch tree, render architecture.md + Mermaid |
37+
| `draw the invocation graph for MySalesAgent v5 in my-org-alias-3` | Same, pinned to v5 |
38+
| `what tools does MyAgent2 have in my-org-alias-2` | Fetch tree, surface the plugin/function inventory from the rendered architecture.md |
39+
| `re-fetch the architecture of MyAgent — I think metadata changed` | Pass `--force` to bypass the cache |
40+
41+
See `SKILL.md` for the full flag table and sample prompts.
42+
43+
---
44+
45+
## Directory layout
46+
47+
```
48+
agentforce-architecture-analyze/
49+
├── SKILL.md Skill contract (inputs, outputs, pipeline, invariants)
50+
├── README.md This file
51+
├── assets/
52+
│ ├── soql/*.soql Tooling + Data SOQL templates
53+
│ ├── cli/*.yaml sf CLI recipes (subprocess invocation specs)
54+
│ └── mermaid/*.mmd Mermaid templates for the invocation graph
55+
├── references/
56+
│ ├── soql_fields.md Per-sObject field reference (13 sObjects)
57+
│ ├── architecture_sections.md Section-by-section structure of the rendered architecture.md
58+
│ └── contract.json metadata_tree.json schema contract
59+
├── scripts/
60+
│ ├── _shared/ Path helpers + fs_guard validators + sql escapers
61+
│ ├── main.py Orchestrator entry point
62+
│ ├── config.py Shared paths, cache TTLs, validated path builders
63+
│ ├── soql_loader.py Template loader with fs_guard-validated substitution
64+
│ ├── sf_cli.py sf CLI subprocess wrapper (yaml.safe_load + stderr redaction)
65+
│ ├── rest_client.py urllib wrapper (Authorization-stripping redirect handler)
66+
│ ├── resolve_bot.py BotDefinition + BotVersion + planner name lookup
67+
│ ├── retrieve_planner.py Metadata retrieve for GenAiPlannerBundle + NGA plugins
68+
│ ├── parallel_retrieve.py 7-channel parallel Tooling SOQL fan-out
69+
│ ├── parse_bundle.py XML → normalized node shapes
70+
│ ├── parse_wave.py BFS expansion of flow/apex/prompt refs
71+
│ ├── probe_channels.py 7-day-TTL channel describe probe
72+
│ ├── cache_check.py Asset-hash-aware cache freshness
73+
│ ├── finalize.py Merge waves → metadata_tree.json
74+
│ ├── render_architecture.py architecture.md + Mermaid graph
75+
│ ├── resolve_invocation_target.py ID-prefix router for NGA InvocationTargets
76+
│ └── tests/ Unit + integration tests (unittest)
77+
└── tools/
78+
├── emit_env.py Env-var emit helper (Phase 0.5)
79+
├── emit_result.py Final RESULT block renderer
80+
├── sanitize.py Stdin → safe-string filter
81+
└── write_emit_ctx.py Per-phase ctx writer
82+
```
83+
84+
---
85+
86+
## Architecture
87+
88+
### Channel strategy — SOQL-first
89+
90+
```
91+
Seed query: planner_definition_by_agent_chain (chain-LIKE lookup → planner id)
92+
93+
6 parallel Tooling SOQL channels (keyed on the resolved planner id):
94+
- plugins_by_planner
95+
- planner_bundle_functions (join)
96+
- functions_by_plugins
97+
- planner_attrs_by_parent_ids
98+
- plugin_functions_by_plugin_ids (join)
99+
- plugin_instructions_by_plugin_ids
100+
101+
+ Data API SOQL for Flow / Apex bodies (batched by id list)
102+
+ Metadata retrieve ONLY for:
103+
- GenAiPromptTemplate (prompt bodies)
104+
- NGA external plugins (when planner is ConcurrentMultiAgentOrchestration etc.)
105+
```
106+
107+
Most of the 3–5× speedup over a naive Metadata-API-only implementation comes from collapsing a sequential zip-retrieve chain into a single Tooling SOQL fan-out.
108+
109+
### Planner normalization — classic ReAct vs NGA
110+
111+
One tree shape, two planner families:
112+
113+
| `PlannerType` examples | Family | InvocationTarget style |
114+
|---|---|---|
115+
| `ReactAiPlannerV1`, `SequentialPlannerIntentClassifier` | Classic ReAct | DeveloperName strings |
116+
| `ConcurrentMultiAgentOrchestration`, `AnthropicCompatibleV1` | NGA | Sometimes 15/18-char Ids (ID-prefix routed) |
117+
118+
`resolve_invocation_target.py` routes NGA InvocationTargets by Salesforce ID prefix (`01p` → ApexClass, `301` → Flow, etc.). Unknown prefixes become `_unresolved[]` entries with `reason="unknown-id-prefix:<prefix>"` — never silently dropped.
119+
120+
### Cache layers
121+
122+
1. **Tree cache** — `metadata_tree.json` is reused unless `--force`. Cache key includes asset-hashes of every SOQL / YAML / Mermaid template shipped with the skill, so changing a template busts the cache automatically.
123+
2. **Channel probe cache** — 7-day TTL on `sf sobject describe` results for the 13 sObjects the skill touches. `--reprobe` forces a refresh (needed after Salesforce quarterly releases that rename / remove fields). Mandatory-field gate: a probe that sees any mandatory field missing (per `probe_channels.MANDATORY_FIELDS`) flips `status: PROBE_FAILED` so the caller surfaces a clean error.
124+
125+
---
126+
127+
## Key behaviors
128+
129+
### Idempotence
130+
131+
Re-running the same `(org, agent, version)` overwrites prior artifacts in place. Safe to run repeatedly during development.
132+
133+
### Partial-results surfacing
134+
135+
No silent drops. Any unresolved ref — unknown ID prefix, failed SOQL, missing describe field — lands in `_unresolved[]` with a `reason=...` string. Top-level `STATUS` is `OK` on a clean run, `PARTIAL_OK` when any channel degrades.
136+
137+
### Cycle handling
138+
139+
Per-branch ancestor-path cycle detection is the primary termination primitive: the same flow visited along its own ancestor chain emits `_cycle_back_to:<path>` instead of recursing. `MAX_BFS_DEPTH=20` is a defensive last-resort guard against pathological graphs that evade per-branch detection; real-world agents bottom out well before that.
140+
141+
---
142+
143+
## Troubleshooting
144+
145+
| Symptom | Fix |
146+
|---|---|
147+
| `sf org display failed` | Re-authenticate: `sf org login web --alias <alias>` |
148+
| `INVALID_FIELD` from a SOQL asset | Salesforce renamed / removed the field in a quarterly release. Run with `--reprobe` to refresh the 7-day channel cache and pick up the new schema |
149+
| `STATUS=PROBE_FAILED` on first run | Channel probe saw a mandatory field missing. Check `channels.json` under the probe cache dir for which sObject / field — may require org-side feature enablement |
150+
| Tree for classic ReAct agent shows `_unresolved` entries for NGA plugins | Expected — the NGA external-plugin retrieve is skipped when the planner shape is classic. Those entries can be ignored |
151+
152+
---
153+
154+
## Author
155+
156+
Raghul Jayagopal (RJ), Salesforce ANZ FDE.

0 commit comments

Comments
 (0)