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/tests/fixtures/genai_payloads.py

View on GitHub
"""Synthetic GenAi query payloads for main pipeline integration tests.

Phase 2 Batch 1: these fixtures model the shapes live Salesforce returns
for each of the 7 Wave A + 3 Wave B SOQL calls. Field names come from
`references/soql_fields.md` (live-describe verified on my-org-alias +
my-perf-org-alias, 2026-05-02).

Two shapes covered:
  * CLASSIC_*  — MyAgent v5-shaped payloads (AiCopilot__* planner,
    InvocationTarget is DeveloperName strings, PlannerId set on bundle-
    scope functions).
  * NGA_*      — MyAgent2 v3-shaped payloads (Atlas__* planner,
    InvocationTarget is Salesforce Ids, PluginId set on every function).

SEQUENTIAL_* is a third variant: classic PlannerType but 0 plugins, 1
bundle-scope function — reproduces the SequentialPlannerIntentClassifier
bot shape which tests often miss.
"""
from __future__ import annotations


# ===========================================================================
# Classic shape (MyAgent v5-style)
# ===========================================================================

CLASSIC_PLANNER = {
    "Id": "1VxVF0000000001",
    "DeveloperName": "MyAgent",
    "MasterLabel": "Service Agent",
    "Description": "Classic ReAct MyAgent",
    "PlannerType": "AiCopilot__ReActAiPlannerV1",
    "Capabilities": None,
    "AgentGraph": None,
}

CLASSIC_PLUGINS = [
    {
        # Distinct Ids per plugin; the plugin→function join table keys on
        # this Id, so collapsing them would fan actions across every topic.
        "Id": f"1VyVF000000TOP{i}",
        "DeveloperName": f"Topic{i}",
        "MasterLabel": f"Topic {i}",
        "Description": f"Topic {i} desc",
        "PluginType": "Custom",
        "Scope": f"Topic {i} scope",
        "IsLocal": True,
        "CanEscalate": False,
        "Source": "Declarative",
        "ParentId": "1VxVF0000000001",
        "LocalDeveloperName": f"Topic{i}",
    }
    for i in range(1, 7)  # 6 topics → matches the "6 topics" assertion
]

# Classic functions: 2 bundle-scope (PlannerId set, PluginId null) +
# 2 topic-scope (PluginId set under Topic1). Invocation targets are
# DeveloperName strings (classic).
CLASSIC_FUNCTIONS = [
    # Bundle-scope
    {
        "Id": "1VuVF0000000B01",
        "DeveloperName": "LookupOrderFlow",
        "MasterLabel": "Lookup Order",
        "Description": None,
        "InvocationTargetType": "flow",
        "InvocationTarget": "LookupOrder",
        "IsLocal": False,
        "IsConfirmationRequired": False,
        "IsIncludeInProgressIndicator": False,
        "ProgressIndicatorMessage": None,
        "Source": "Declarative",
        "PluginId": None,
        "PlannerId": "1VxVF0000000001",
        "ParentId": None,
        "LocalDeveloperName": "LookupOrderFlow",
    },
    {
        "Id": "1VuVF0000000B02",
        "DeveloperName": "EscalateCase",
        "MasterLabel": "Escalate Case",
        "Description": None,
        "InvocationTargetType": "apex",
        "InvocationTarget": "CaseEscalationHandler",
        "IsLocal": False,
        "IsConfirmationRequired": True,
        "IsIncludeInProgressIndicator": False,
        "ProgressIndicatorMessage": None,
        "Source": "Declarative",
        "PluginId": None,
        "PlannerId": "1VxVF0000000001",
        "ParentId": None,
        "LocalDeveloperName": "EscalateCase",
    },
    # Topic-scope (Topic1)
    {
        "Id": "1VuVF0000000T01",
        "DeveloperName": "GetOrderDetails",
        "MasterLabel": "Get Order Details",
        "Description": None,
        "InvocationTargetType": "flow",
        "InvocationTarget": "GetOrderDetails",
        "IsLocal": True,
        "IsConfirmationRequired": False,
        "IsIncludeInProgressIndicator": True,
        "ProgressIndicatorMessage": "Looking up...",
        "Source": "Declarative",
        "PluginId": "1VyVF000000TOP1",
        "PlannerId": None,
        "ParentId": None,
        "LocalDeveloperName": "GetOrderDetails",
    },
    {
        "Id": "1VuVF0000000T02",
        "DeveloperName": "ApplyDiscount",
        "MasterLabel": "Apply Discount",
        "Description": None,
        "InvocationTargetType": "apex",
        "InvocationTarget": "DiscountApplicator",
        "IsLocal": True,
        "IsConfirmationRequired": False,
        "IsIncludeInProgressIndicator": False,
        "ProgressIndicatorMessage": None,
        "Source": "Declarative",
        "PluginId": "1VyVF000000TOP1",
        "PlannerId": None,
        "ParentId": None,
        "LocalDeveloperName": "ApplyDiscount",
    },
]

CLASSIC_PLUGIN_FUNCTIONS = [
    {"Id": "1VqVF000001", "PluginId": "1VyVF000000TOP1", "Function": "1VuVF0000000T01"},
    {"Id": "1VqVF000002", "PluginId": "1VyVF000000TOP1", "Function": "1VuVF0000000T02"},
]

CLASSIC_BUNDLE_FN_JOIN = [
    {"Id": "1VrVF000001", "PlannerId": "1VxVF0000000001", "Plugin": "LookupOrderFlow"},
    {"Id": "1VrVF000002", "PlannerId": "1VxVF0000000001", "Plugin": "EscalateCase"},
]

CLASSIC_INSTRUCTIONS = [
    {
        "Id": "1VwVF000001",
        "GenAiPluginDefinitionId": "1VyVF000000TOP1",
        "DeveloperName": "Instruction1",
        "MasterLabel": "Use polite tone",
        "Description": "Always greet the user first.",
        "SortOrder": 1,
    }
]

CLASSIC_ATTRS = [
    {
        "Id": "1VvVF000001",
        "ParentId": "1VuVF0000000T01",
        "DeveloperName": "OrderId",
        "MasterLabel": "Order Id",
        "Description": None,
        "MappingType": "input",
        "ParameterName": "orderId",
    }
]

# Wave B classic: 2 flows (LookupOrder, GetOrderDetails), 2 apex
# (CaseEscalationHandler, DiscountApplicator).
CLASSIC_FLOW_DEFS = [
    {"Id": "300VF001", "DeveloperName": "LookupOrder", "ActiveVersionId": "301VF001"},
    {"Id": "300VF002", "DeveloperName": "GetOrderDetails", "ActiveVersionId": "301VF002"},
]

CLASSIC_APEX_ROWS = [
    {
        "Id": "01pVF001",
        "Name": "CaseEscalationHandler",
        "Body": "public class CaseEscalationHandler {}",
        "SymbolTable": None,
        "ApiVersion": 60.0,
        "IsValid": True,
    },
    {
        "Id": "01pVF002",
        "Name": "DiscountApplicator",
        "Body": "public class DiscountApplicator {}",
        "SymbolTable": None,
        "ApiVersion": 60.0,
        "IsValid": True,
    },
]

CLASSIC_FLOW_METADATA = {
    "301VF001": {"Id": "301VF001", "FullName": "LookupOrder-1", "Metadata": {}},
    "301VF002": {"Id": "301VF002", "FullName": "GetOrderDetails-1", "Metadata": {}},
}


# ===========================================================================
# NGA shape (MyAgent2 v3-style) — InvocationTarget is Ids, PluginId-only
# ===========================================================================

NGA_PLANNER = {
    "Id": "1VxVF0000000N01",
    "DeveloperName": "MyAgent2",
    "MasterLabel": "NGA Service Agent",
    "Description": "Atlas MyAgent",
    "PlannerType": "Atlas__ConcurrentMultiAgentOrchestration",
    "Capabilities": None,
    "AgentGraph": None,
}

NGA_PLUGINS = [
    {
        "Id": "1VyVF0000000N01",
        "DeveloperName": "NGATopic1",
        "MasterLabel": "NGA Topic 1",
        "Description": None,
        "PluginType": "Custom",
        "Scope": "NGA scope",
        "IsLocal": True,
        "CanEscalate": False,
        "Source": "Declarative",
        "ParentId": "1VxVF0000000N01",
        "LocalDeveloperName": "NGATopic1",
    },
]

# NGA functions store InvocationTarget as Salesforce Ids — `01p...` for
# Apex, `300...` for FlowDefinition. PluginId is always set; PlannerId
# is null.
NGA_FUNCTIONS = [
    {
        "Id": "1VuVF0000000N01",
        "DeveloperName": "NGAFlowAction",
        "MasterLabel": "NGA Flow Action",
        "Description": None,
        "InvocationTargetType": "flow",
        "InvocationTarget": "300VF999NGAFLOW",
        "IsLocal": True,
        "IsConfirmationRequired": False,
        "IsIncludeInProgressIndicator": False,
        "ProgressIndicatorMessage": None,
        "Source": "Declarative",
        "PluginId": "1VyVF0000000N01",
        "PlannerId": None,
        "ParentId": None,
        "LocalDeveloperName": "NGAFlowAction",
    },
    {
        "Id": "1VuVF0000000N02",
        "DeveloperName": "NGAApexAction",
        "MasterLabel": "NGA Apex Action",
        "Description": None,
        "InvocationTargetType": "apex",
        "InvocationTarget": "01pVF999NGAAPEX",
        "IsLocal": True,
        "IsConfirmationRequired": False,
        "IsIncludeInProgressIndicator": False,
        "ProgressIndicatorMessage": None,
        "Source": "Declarative",
        "PluginId": "1VyVF0000000N01",
        "PlannerId": None,
        "ParentId": None,
        "LocalDeveloperName": "NGAApexAction",
    },
]

NGA_PLUGIN_FUNCTIONS = [
    {"Id": "1VqVF00N01", "PluginId": "1VyVF0000000N01", "Function": "1VuVF0000000N01"},
    {"Id": "1VqVF00N02", "PluginId": "1VyVF0000000N01", "Function": "1VuVF0000000N02"},
]

# NGA reverse-lookup rows (B1 NGA variant + B3 NGA variant)
NGA_FLOW_DEF_BY_ID = [
    {
        "Id": "300VF999NGAFLOW",
        "DeveloperName": "NGAResolvedFlow",
        "ActiveVersionId": "301VF999NGAVER",
        "LatestVersionId": "301VF999NGAVER",
    },
]

NGA_APEX_BY_ID = [
    {
        "Id": "01pVF999NGAAPEX",
        "Name": "NGAResolvedApex",
        "Body": "public class NGAResolvedApex {}",
        "SymbolTable": None,
        "ApiVersion": 60.0,
        "IsValid": True,
    },
]


# ===========================================================================
# SequentialPlannerIntentClassifier shape
# ===========================================================================
# Classic family (AiCopilot__SequentialPlannerIntentClassifier), ZERO
# plugins, exactly ONE bundle-scope function. Tests the
# "empty plugin_ids short-circuits" path.

SEQ_PLANNER = {
    "Id": "1VxVF0000000SEQ",
    "DeveloperName": "SequentialAgent",
    "MasterLabel": "Sequential Agent",
    "Description": None,
    "PlannerType": "AiCopilot__SequentialPlannerIntentClassifier",
    "Capabilities": None,
    "AgentGraph": None,
}

SEQ_FUNCTIONS = [
    {
        "Id": "1VuVF0000000S01",
        "DeveloperName": "StandardReply",
        "MasterLabel": "Standard Reply",
        "Description": None,
        "InvocationTargetType": "standardInvocableAction",
        "InvocationTarget": "reply",
        "IsLocal": False,
        "IsConfirmationRequired": False,
        "IsIncludeInProgressIndicator": False,
        "ProgressIndicatorMessage": None,
        "Source": "Declarative",
        "PluginId": None,
        "PlannerId": "1VxVF0000000SEQ",
        "ParentId": None,
        "LocalDeveloperName": "StandardReply",
    },
]


# ===========================================================================
# Bot version / definition rows (Data API shape)
# ===========================================================================

def make_bot_versions(agent_api_name: str, versions=("v5",), active: str = "v5") -> list[dict]:
    """Build BotVersion records list in the Data API shape."""
    return [
        {
            "Id": f"0Xx{i:012d}",
            "DeveloperName": v,
            "Status": "Active" if v == active else "Inactive",
            "BotDefinitionId": "0Xa000000000ABC",
            "BotDefinition": {
                "DeveloperName": agent_api_name,
                "MasterLabel": f"{agent_api_name} bot",
            },
        }
        for i, v in enumerate(versions)
    ]


BOT_DEFINITION_DETAIL_CLASSIC = {
    "DeveloperName": "MyAgent",
    "MasterLabel": "Service Agent",
    "Description": "Classic bot",
    "AgentType": "ExternalCopilot",
    "Type": "Copilot",
    "AgentTemplate": "EinsteinCopilotForServiceTmpl",
    "BotSource": "EinsteinCopilot",
}

BOT_DEFINITION_DETAIL_NGA = {
    "DeveloperName": "MyAgent2",
    "MasterLabel": "NGA Service Agent",
    "Description": "NGA bot",
    "AgentType": "EinsteinAgentKind",
    "Type": "Agentforce",
    "AgentTemplate": "SvcCopilotTmpl__EinsteinAgentKind",
    "BotSource": "AgentforceService",
}


# ===========================================================================
# Probe-channels "all OK" + "PROBE_FAILED" payloads
# ===========================================================================


def probe_ok_payload() -> dict:
    return {
        "_schema": "channels/1",
        "_built_at_utc": 0.0,
        "status": "OK",
        "channels": {},
    }


def probe_failed_payload(sobject: str = "GenAiPlannerDefinition",
                        missing: list[str] | None = None) -> dict:
    return {
        "_schema": "channels/1",
        "_built_at_utc": 0.0,
        "status": "PROBE_FAILED",
        "channels": {
            sobject: {
                "queryable_fields": [],
                "mandatory_missing": missing or ["DeveloperName"],
                "describe_error": None,
            }
        },
    }
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