agent_api_name

$ARGUMENTS

--agent

--org

Which agent should I document, and in which org?

I need:

• Agent API name — the

  DeveloperName

  of the

  BotDefinition

  (e.g.

  MyAgent

  ,

  MySalesAgent

  ). Not the label.
• Org alias — for

  sf

  CLI auth (the alias you configured with

  sf org login

  )

Optional:

• Version — an

  agent_version_api_name

  like

  v5

  . If omitted, I'll resolve the active

  BotVersion

  .

• --force

  — ignore cached tree; re-fetch everything.

• --reprobe

  — re-run the 7-day channel-probe cache (only needed after a Salesforce release).

I'll run the metadata pipeline inline. Artifacts land under

~/.vibe/data/investigating-agentforce-architecture/<org_id15>/<agent_api_name>__<agent_version>/

(overridable with

--data-dir

).

Which agent should I document, and in which org?

I need:

• Agent API name — the BotDefinition.DeveloperName (e.g.

  MyAgent

  )
• Org alias — for

  sf

  CLI auth (the alias you configured with

  sf org login

  )

Optional flags:

• --version v5

  — pin a specific BotVersion (default: Active+highest)

• --force

  — bypass cache

• --reprobe

  — force channel-probe refresh

• --parallelism N

  — ThreadPoolExecutor size (default 5)

• --max-mermaid-nodes N

  — cap Mermaid node count (default 80) USAGE exit 2 fi

resolve_bot.py        → BotDefinition + BotVersion + planner name lookup
retrieve_planner.py   → Metadata API zip retrieve for GenAiPlannerBundle (+ NGA plugins if present)
parallel_retrieve.py  → 6 parallel Tooling SOQL channels fan out from the planner id
                          (resolved by the `planner_definition_by_agent_chain` seed query):
                          - plugins_by_planner (GenAiPluginDefinition)
                          - planner_bundle_functions (GenAiPlannerFunctionDef join)
                          - functions_by_plugins (GenAiFunctionDefinition)
                          - planner_attrs_by_parent_ids (GenAiPlannerAttrDefinition)
                          - plugin_functions_by_plugin_ids (GenAiPluginFunctionDef join)
                          - plugin_instructions_by_plugin_ids (GenAiPluginInstructionDef)
parse_bundle.py       → parse retrieved XML into normalized node shapes
parse_wave.py         → BFS expansion: flow/apex/prompt refs discovered in nodes
                          → SOQL for Flow/Apex bodies (batched by id list)
                          → Metadata retrieve ONLY for GenAiPromptTemplate (+ NGA external plugins conditionally)
finalize.py           → merge waves into metadata_tree.json
render_architecture.py → <agent>_<ver>_architecture.md + Mermaid invocation graph (capped at --max-mermaid-nodes)

• Tooling SOQL for every normalized tree node (planner, plugins, functions, plugin-functions, plugin-instructions, planner-functions, planner-attrs) — 6 parallel channels keyed on planner id, plus the

  planner_definition_by_agent_chain

  seed query that resolves the planner id from the agent chain.
• Data API SOQL for Flow (by id) and Apex (by id or name) bodies — batched.
• Metadata retrieve only for two cases: (a)

  GenAiPromptTemplate

  (prompt bodies aren't cleanly exposed via Tooling SOQL), and (b) NGA external plugins when the planner is Native Generative Agent shape (skipped for classic ReAct).

• Tree cache:

  metadata_tree.json

  is reused unless

  --force

  is passed. Cache key includes the asset-hash of every

  .soql

  /

  .yaml

  /

  .mmd

  template bundled with the skill — bump a template, the cache busts automatically.
• Channel probe cache: 7-day TTL on the per-org

  sf sobject describe

  results that validate every field name the SOQL assets reference. A Salesforce quarterly release that renames / removes a field triggers

  status: PROBE_FAILED

  ;

  --reprobe

  forces a refresh.

• references/soql_fields.md

  — per-sObject field reference for the 13 sObjects this skill touches (2 Data API + 11 Tooling), with

  [mandatory]

  vs

  [optional]

  tags. Load when the user asks about a specific field, or when debugging an

  INVALID_FIELD

  SOQL error.

• references/contract.json

  — machine-readable schema for

  metadata_tree.json

  . Load when writing downstream tooling that consumes the tree.

• references/architecture_sections.md

  — section-by-section structure of the rendered

  <agent>_<ver>_architecture.md

  .

• Pipeline is deterministic. Same

  (org, agent, version)

  + static org metadata → byte-identical

  <agent>_<ver>_metadata_tree.json

  and

  <agent>_<ver>_architecture.md

  . Only manifest timestamps drift across re-runs.
• Forward-only traversal. Every discovered ref goes forward from planner → children. No backward lookups.
• Partial results are surfaced, not silenced. Any unresolved reference lands in

  _unresolved[]

  with

  reason=...

  .

  STATUS=PARTIAL_OK

  if any channel failed;

  STATUS=OK

  only on a clean run.
• Cycle detection is per-branch. Same flow visited along its own ancestor chain emits

  _cycle_back_to:<path>

  instead of recursing. A defensive

  MAX_BFS_DEPTH=20

  guard backs the per-branch ancestor set; real-world agents bottom out well before either limit fires. (Earlier docs claimed a hard cap of 5; that was the historical limit and was abandoned because shared utility flows like

  handleFlowFault

  tripped it on every nested tree — see

  config.MAX_BFS_DEPTH

  for the rationale.)
• Child ordering is alphabetical by

  api_name

  (case-insensitive). Topics come before non-topic plannerActions at the root level. Flow-actionCall order is NOT sorted — that's the flow author's execution sequence.