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/resolve_invocation_target.py

View on GitHub
"""NGA InvocationTarget ID-prefix router.

NGA bots store Salesforce Ids in GenAiFunctionDefinition.InvocationTarget,
not DeveloperNames. This module resolves the kind by the 3-char key prefix.

unknown prefixes MUST NEVER raise — Salesforce is free to introduce
new NGA target types (e.g., a hypothetical `0aN...` AgentCapability) and
the skill must degrade gracefully. Callers use `resolve_or_unresolved` to
append a `_unresolved[]` entry with a diagnostic reason and get back
`("unknown", "skip")` so the wave orchestrator can keep parsing.

Invariants:
  * Only the 3-char prefix is consulted for Id-based routing — 15-char
    and 18-char Ids both map the same way.
  * `standard_action` kind is selected by caller context (bundle's
    `invocationTargetType == "standardInvocableAction"`), not by prefix —
    standard actions have no Id. Its presence in the Kind union is
    scaffolding for call-site type-checking.
  * `REGISTERED_PREFIXES` exposes the known prefix set as a frozenset for
    tests and probe-channel validation.
"""
from __future__ import annotations

import re
from typing import Literal

Kind = Literal[
    "apex",
    "flow_definition",
    "flow_version",
    "prompt_template",
    "standard_action",
    "unknown",
]
Channel = Literal[
    "tooling_soql",
    "retrieve_required",
    "skip",
]

_PREFIX_MAP: dict[str, tuple[Kind, Channel]] = {
    "01p": ("apex", "tooling_soql"),
    "300": ("flow_definition", "tooling_soql"),
    "301": ("flow_version", "tooling_soql"),
    "0hf": ("prompt_template", "retrieve_required"),
}

# public reverse-lookup set. `frozenset` (not set) so callers can't
# mutate the authoritative table by accident.
REGISTERED_PREFIXES: frozenset[str] = frozenset(_PREFIX_MAP.keys())

# Salesforce Ids are 15 or 18 chars, alphanumeric only. This is the gate
# between "could be a real Id with an unknown prefix" (treat as an NGA
# addition we don't know about yet) and "garbage input" (empty, wrong
# length, bad characters — treat as invalid format).
_SF_ID_RE = re.compile(r"^[A-Za-z0-9]+$")
_SF_ID_LENGTHS = frozenset({15, 18})


def looks_like_sf_id(id_str: object) -> bool:
    """True iff `id_str` is a 15- or 18-char alphanumeric string.

    promoted from module-private `_looks_like_sf_id`
    so `main._route` can gate calls to `resolve_or_unresolved` on the
    Id shape without reaching into a leading-underscore symbol (same
    surface). Underscore form retained as a deprecated alias.
    """
    if not isinstance(id_str, str):
        return False
    if len(id_str) not in _SF_ID_LENGTHS:
        return False
    return bool(_SF_ID_RE.match(id_str))


# backcompat alias — deprecated; use `looks_like_sf_id`.
_looks_like_sf_id = looks_like_sf_id


def resolve_target_id(id_str: str) -> tuple[Kind, Channel]:
    """Return (kind, resolvable_via) for a Salesforce Id.

    unknown prefixes NEVER raise — callers observing ("unknown", "skip")
    are expected to route through `resolve_or_unresolved` (or equivalent)
    to append an `_unresolved[]` entry. This function stays pure — it does
    not mutate any caller state, does not log.
    """
    if not id_str or not isinstance(id_str, str) or len(id_str) < 3:
        return ("unknown", "skip")
    prefix = id_str[:3]
    return _PREFIX_MAP.get(prefix, ("unknown", "skip"))


def resolve_or_unresolved(
    id_str: object,
    unresolved: list[dict],
) -> tuple[Kind, Channel]:
    """Like `resolve_target_id` but records failures into `unresolved`.

    semantics:
      * Valid Salesforce Id (15 or 18 alphanumeric chars) with known prefix:
        route as usual. `unresolved` untouched.
      * Valid Id shape, unknown prefix: append
        `{"id": <id>, "reason": f"unknown-id-prefix:{id[:3]}"}` and
        return ("unknown", "skip"). This is the "NGA shipped a new type"
        path — the wave orchestrator keeps running.
      * Not an Id shape (empty/None/wrong length/bad chars): append
        `{"id": str(id_str), "reason": "invalid-id-format"}` and return
        ("unknown", "skip"). Distinct reason so triage can tell "NGA
        added something new" apart from "caller passed us garbage."

    `unresolved` is mutated in place — same contract as `_unresolved[]`
    throughout the skill. Caller owns the list.
    """
    if _looks_like_sf_id(id_str):
        kind, channel = resolve_target_id(id_str)  # type: ignore[arg-type]
        if kind == "unknown":
            # Real Id shape, prefix we don't recognize — record the prefix
            # so triage can add it to _PREFIX_MAP.
            unresolved.append({
                "id": id_str,
                "reason": f"unknown-id-prefix:{id_str[:3]}",  # type: ignore[index]
            })
        return (kind, channel)

    # Not a valid Id shape — empty, None, wrong length, or bad chars.
    unresolved.append({
        "id": str(id_str),
        "reason": "invalid-id-format",
    })
    return ("unknown", "skip")
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