Skip to content

forcedotcom/sf-skills / plugins/builder/agentforce-adlc/skills/agentforce-architecture-analyze

agentforce-architecture-analyze

Verified

Declared architecture snapshot for one Agentforce agent: planner, topics, actions, flows, Apex, prompt templates, and NGA plugins. Renders a human-readable architecture document and Mermaid invocation graph from design-time metadata (not runtime audit rows). TRIGGER when user asks to describe, diagram, inventory, audit, document, or diff (e.g. v3 vs v5) the architecture / action tree / topic structure / tool inventory of a specific agent by agent API name in a specific org. DO NOT TRIGGER for runtime session traces, conversation transcripts, generation timings, or gateway audit chains — this skill reads design-time metadata only (use agentforce-d360-analyze for session traces).

FileKindSize
README.mdmarkdown8.5 KB
SKILL.mdskill md17.5 KB
assets/cli/describe_sobject.yamlconfig317 B
assets/cli/describe_tooling_sobject.yamlconfig347 B
assets/cli/list_metadata_genaiprompttemplate.yamlconfig342 B
assets/cli/org_display.yamlconfig280 B
assets/cli/retrieve_genai_plugin.yamlconfig391 B
assets/cli/show_access_token.yamlconfig700 B
assets/mermaid/action_tree.mmdother986 B
assets/mermaid/data_flow.mmdother893 B
assets/mermaid/dependency_graph.mmdother810 B
assets/mermaid/invocation_sequence.mmdother1004 B
assets/mermaid/planner_state.mmdother813 B
assets/soql/apex_class_bodies_by_ids.soqlother103 B
assets/soql/apex_class_bodies_by_names.soqlother102 B
assets/soql/bot_definition_details.soqlother152 B
assets/soql/bot_version_lookup.soqlother186 B
assets/soql/flow_definition_by_ids.soqlother115 B
assets/soql/flow_definition_ids_by_names.soqlother146 B
assets/soql/flow_definition_view_by_durable_ids.soqlother180 B
assets/soql/flow_metadata_by_id.soqlother73 B
assets/soql/functions_by_plugins.soqlother317 B
assets/soql/planner_attrs_by_parent_ids.soqlother156 B
assets/soql/planner_bundle_functions.soqlother93 B
assets/soql/planner_definition_by_agent_chain.soqlother174 B
assets/soql/plugin_functions_by_plugin_ids.soqlother93 B
assets/soql/plugin_instructions_by_plugin_ids.soqlother168 B
assets/soql/plugins_by_planner.soqlother199 B
references/architecture_sections.mdmarkdown8.3 KB
references/contract.jsonconfig11.7 KB
references/soql_fields.mdmarkdown24.6 KB
scripts/_shared/__init__.pyscript82 B
scripts/_shared/fs_guard.pyexecutablescript12.8 KB
scripts/_shared/paths.pyscript3.9 KB
scripts/_shared/runtime.pyscript2.0 KB
scripts/_shared/sql.pyscript355 B
scripts/cache_check.pyexecutablescript8.9 KB
scripts/config.pyscript5.9 KB
scripts/emit_env.pyexecutablescript5.1 KB
scripts/emit_result.pyexecutablescript10.7 KB
scripts/fetch_soql.pyscript26.1 KB
scripts/finalize.pyexecutablescript11.8 KB
scripts/main.pyscript113.9 KB
scripts/metadata_listing.pyscript9.5 KB
scripts/parallel_retrieve.pyscript3.3 KB
scripts/parse_bundle.pyexecutablescript7.9 KB
scripts/parse_wave.pyexecutablescript36.1 KB
scripts/probe_channels.pyscript11.1 KB
scripts/render_architecture.pyscript40.0 KB
scripts/resolve_bot.pyexecutablescript9.4 KB
scripts/resolve_invocation_target.pyscript4.8 KB
scripts/rest_client.pyscript33.7 KB
scripts/retrieve_planner.pyscript464 B
scripts/sanitize.pyexecutablescript1013 B
scripts/sf_cli.pyscript12.3 KB
scripts/soql_loader.pyscript11.1 KB
scripts/summarize_tree.pyexecutablescript4.6 KB
scripts/tests/__init__.pyscript0 B
scripts/tests/_bootstrap.pyscript843 B
scripts/tests/fixtures/__init__.pyscript0 B
scripts/tests/fixtures/genai_payloads.pyscript12.5 KB
scripts/tests/test_cache_check.pyscript12.6 KB
scripts/tests/test_cache_check_main.pyscript10.4 KB
scripts/tests/test_config.pyscript3.8 KB
scripts/tests/test_end_to_end_fixture.pyscript26.2 KB
scripts/tests/test_finalize.pyscript11.2 KB
scripts/tests/test_flow_children_inflation.pyscript25.6 KB
scripts/tests/test_fs_guard.pyscript4.3 KB
scripts/tests/test_iterative_wave_b.pyscript19.0 KB
scripts/tests/test_main_pipeline.pyscript145.1 KB
scripts/tests/test_parallel_retrieve.pyscript4.8 KB
scripts/tests/test_parse_bundle.pyscript15.6 KB
scripts/tests/test_parse_wave.pyscript26.9 KB
scripts/tests/test_parse_wave_classifiers.pyscript8.6 KB
scripts/tests/test_parse_wave_helpers.pyscript14.3 KB
scripts/tests/test_parse_wave_main.pyscript16.4 KB
scripts/tests/test_per_branch_visited.pyscript9.5 KB
scripts/tests/test_probe_channels.pyscript13.3 KB
scripts/tests/test_probe_cli_recipes.pyscript8.2 KB
scripts/tests/test_render_architecture.pyscript32.7 KB
scripts/tests/test_resolve_bot.pyscript7.5 KB
scripts/tests/test_resolve_creds.pyscript12.0 KB
scripts/tests/test_resolve_invocation_target.pyscript5.2 KB
scripts/tests/test_rest_client.pyscript49.8 KB
scripts/tests/test_runtime_override.pyscript3.9 KB
scripts/tests/test_sf_cli.pyscript17.3 KB
scripts/tests/test_signature_stamping.pyscript18.0 KB
scripts/tests/test_skill_md_pipeline_block.pyscript12.7 KB
scripts/tests/test_soql_loader.pyscript21.3 KB
scripts/tests/test_summarize_tree.pyscript8.9 KB
scripts/tests/test_write_emit_ctx.pyscript19.2 KB
scripts/write_emit_ctx.pyexecutablescript14.1 KB

scripts/parse_bundle.py

View on GitHub
#!/usr/bin/env python3
"""Parse Bot.bot + GenAiPlannerBundle → _bundle_parsed.json + PLANNER_NAME.

Replaces old agent Phase 2a (Bot.bot planner-name extraction via XPath-ish
walk) + Phase 2c (bundle XML → topics/plannerActions + generation classifier).

Step 1 — planner name:
  Read $WORK_DIR/sf_meta/wave1_bot/unpackaged/bots/*.bot XML.
  Path: /Bot/botVersions[fullName==$AGENT_VERSION]/conversationDefinitionPlanners[0]
         /genAiPlannerName (fallback: plannerName, fullName)

Step 2 — bundle (only if planner name resolved AND bundle dir exists):
  Read $WORK_DIR/sf_meta/wave1_bundle/unpackaged/genAiPlannerBundles/<plannerName>/
       *.genAiPlannerBundle
  Extract: plannerType, description, masterLabel, localTopics[] with inline
  localActions[], and (classic-only) plannerActions[].
  Classify generation:
    plannerType startswith "AiCopilot__"  → classic
    plannerType startswith "Atlas__"      → nga
    else                                   → unknown

Emits:
  $WORK_DIR/_bundle_parsed.json   (full structured extraction)
  $WORK_DIR/_agent_generation.txt (generation string, newline-terminated)
  stdout: `PLANNER_NAME=<shlex-quoted>\nAGENT_GENERATION=<shlex-quoted>`
          + log lines (topic counts, action counts) for human readability.

If Bot.bot has no <conversationDefinitionPlanners>, prints `PLANNER_NAME=''`
and exits 0 — caller treats the tree as partial.

Usage:
    eval "$(python3 parse_bundle.py)"

Inputs (env):
    WORK_DIR       required
    AGENT_VERSION  required — used to pin the right <botVersions> element

Outputs:
    files (above)
    stdout eval-friendly K=V lines
    exit 0 always (no recoverable error condition; missing XML → empty planner)
"""
import json
import os
import pathlib
import shlex
import sys
import xml.etree.ElementTree as ET


NS = {"sf": "http://soap.sforce.com/2006/04/metadata"}


def _t(el, p):
    if el is None:
        return None
    x = el.find(p, NS)
    return x.text if x is not None else None


def classify_generation(planner_type: str) -> str:
    if not planner_type:
        return "unknown"
    if planner_type.startswith("AiCopilot__"):
        return "classic"
    if planner_type.startswith("Atlas__"):
        return "nga"
    return "unknown"


def extract_planner_name(work_dir: pathlib.Path, target_ver: str) -> str:
    bots_dir = work_dir / "sf_meta" / "wave1_bot" / "unpackaged" / "bots"
    if not bots_dir.exists():
        return ""
    for bot_file in bots_dir.glob("*.bot"):
        try:
            root = ET.parse(bot_file).getroot()
        except ET.ParseError:
            continue
        for bv in root.findall("sf:botVersions", NS):
            full = _t(bv, "sf:fullName") or _t(bv, "sf:developerName")
            if target_ver and full != target_ver:
                continue
            for cdp in bv.findall("sf:conversationDefinitionPlanners", NS):
                n = (_t(cdp, "sf:genAiPlannerName")
                     or _t(cdp, "sf:plannerName")
                     or _t(cdp, "sf:fullName"))
                if n:
                    return n
    return ""


def extract_bundle(work_dir: pathlib.Path, planner_name: str) -> dict:
    bundle = {
        "plannerType": None,
        "plannerName": planner_name or None,
        "generation": "unknown",
        "description": None,
        "masterLabel": None,
        "topics": [],
        "plannerActions": [],
    }

    planner_root = work_dir / "sf_meta" / "wave1_bundle" / "unpackaged" / "genAiPlannerBundles"
    if not planner_root.exists():
        return bundle

    for bundle_dir in planner_root.iterdir():
        if not bundle_dir.is_dir():
            continue
        bundle_xml = list(bundle_dir.glob("*.genAiPlannerBundle"))
        if not bundle_xml:
            continue
        try:
            root = ET.parse(bundle_xml[0]).getroot()
        except ET.ParseError as e:
            sys.stderr.write(f"parse_bundle.py: XML parse error on {bundle_xml[0]}: {e}\n")
            continue

        bundle["plannerType"] = _t(root, "sf:plannerType")
        bundle["generation"] = classify_generation(bundle["plannerType"])
        bundle["description"] = _t(root, "sf:description")
        bundle["masterLabel"] = _t(root, "sf:masterLabel")

        for lt in root.findall("sf:localTopics", NS):
            tname = _t(lt, "sf:developerName") or _t(lt, "sf:fullName")
            if not tname:
                continue
            topic = {
                "name": tname,
                "localDeveloperName": _t(lt, "sf:localDeveloperName"),
                "masterLabel": _t(lt, "sf:masterLabel"),
                "description": _t(lt, "sf:description"),
                "canEscalate": (_t(lt, "sf:canEscalate") or "false").lower() == "true",
                "pluginType": _t(lt, "sf:pluginType"),
                "actions": [],
            }
            for la in lt.findall("sf:localActions", NS):
                aname = _t(la, "sf:developerName") or _t(la, "sf:fullName")
                if not aname:
                    continue
                topic["actions"].append({
                    "name": aname,
                    "localDeveloperName": _t(la, "sf:localDeveloperName"),
                    "masterLabel": _t(la, "sf:masterLabel"),
                    "description": _t(la, "sf:description"),
                    "invocationTarget": _t(la, "sf:invocationTarget"),
                    "invocationTargetType": (_t(la, "sf:invocationTargetType") or "").strip(),
                    "source": _t(la, "sf:source"),
                })
            bundle["topics"].append(topic)

        for pa in root.findall("sf:plannerActions", NS):
            aname = _t(pa, "sf:developerName") or _t(pa, "sf:fullName")
            if not aname:
                continue
            bundle["plannerActions"].append({
                "name": aname,
                "localDeveloperName": _t(pa, "sf:localDeveloperName"),
                "masterLabel": _t(pa, "sf:masterLabel"),
                "description": _t(pa, "sf:description"),
                "invocationTarget": _t(pa, "sf:invocationTarget"),
                "invocationTargetType": (_t(pa, "sf:invocationTargetType") or "").strip(),
                "source": _t(pa, "sf:source"),
            })
        break  # first bundle dir is enough
    return bundle


def atomic_write(path: pathlib.Path, content: str) -> None:
    tmp = path.with_suffix(path.suffix + ".tmp")
    tmp.write_text(content)
    os.replace(tmp, path)


def main() -> int:
    try:
        work_dir = pathlib.Path(os.environ["WORK_DIR"])
        agent_version = os.environ["AGENT_VERSION"]
    except KeyError as e:
        sys.stderr.write(f"parse_bundle.py: missing env {e}\n")
        return 1

    # Step 1: planner name
    planner_name = extract_planner_name(work_dir, agent_version)

    # Step 2: bundle (only if planner resolved)
    bundle = extract_bundle(work_dir, planner_name) if planner_name else {
        "plannerType": None, "plannerName": None, "generation": "unknown",
        "description": None, "masterLabel": None, "topics": [], "plannerActions": [],
    }

    atomic_write(work_dir / "_bundle_parsed.json", json.dumps(bundle, indent=2))
    atomic_write(work_dir / "_agent_generation.txt", bundle["generation"] + "\n")

    # Log lines (stderr would be lost via eval; use stderr for logs not shell-consumed)
    total_actions = (
        sum(len(t["actions"]) for t in bundle["topics"]) + len(bundle["plannerActions"])
    )
    sys.stderr.write(
        f"[parse_bundle] plannerName={planner_name!r} "
        f"plannerType={bundle['plannerType']!r} generation={bundle['generation']}\n"
        f"[parse_bundle]   topics={len(bundle['topics'])} "
        f"topic-scope-actions={sum(len(t['actions']) for t in bundle['topics'])} "
        f"bundle-scope-actions={len(bundle['plannerActions'])} total={total_actions}\n"
    )

    # Eval-friendly stdout
    sys.stdout.write(f"PLANNER_NAME={shlex.quote(planner_name)}\n")
    sys.stdout.write(f"AGENT_GENERATION={shlex.quote(bundle['generation'])}\n")
    return 0


if __name__ == "__main__":
    sys.exit(main())
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall