Skip to content

forcedotcom/sf-skills / plugins/builder/agentforce-adlc/skills/agentforce-generate

agentforce-generate

Flagged

Build, modify, audit, repair, optimize, debug, and deploy agents with Agentforce Agent Script. TRIGGER when: user creates, reviews, or changes .agent files or aiAuthoringBundle metadata; asks to fix AgentScript, audit an existing agent, run an AgentScript health check, common-pitfall review, or baseline-versus-candidate repair loop; changes a response, action, subagent, route, state flow, or Agent Spec; migrates or upgrades a legacy GenAiPlannerBundle Agentforce agent (NOT an Einstein Bot) to an aiAuthoringBundle (Agent Script) agent; previews, debugs, deploys, publishes, or tests agents; uses sf agent generate/preview/publish/test; or manages Agentforce MCP servers, tools, assets, or authentication. DO NOT TRIGGER when: Apex, Flow, Prompt Template, Experience Cloud, or general Salesforce CLI work is unrelated to Agent Script; the source is an Einstein Bot (BotDefinition/BotVersion) — use agentforce-bot-upgrade; or the primary input is a production session or trace ID rather than an agent artifact.

FileKindSize
README.mdmarkdown5.4 KB
SKILL.mdskill md31.7 KB
assets/agent-spec-template.mdmarkdown6.4 KB
assets/agents/README.mdmarkdown2.6 KB
assets/agents/hello-world.agentother1.9 KB
assets/agents/knowledge-grounded.agentother5.6 KB
assets/agents/local-info-agent-annotated.agentother17.0 KB
assets/agents/order-service.agentother11.7 KB
assets/agents/production-faq.agentother3.9 KB
assets/agents/production-faq.bundle-meta.xmlconfig161 B
assets/agents/router-first.agentother5.6 KB
assets/agents/simple-qa.agentother1.9 KB
assets/agents/template-multi-subagent.agentother5.4 KB
assets/agents/template-single-subagent.agentother2.6 KB
assets/agents/verification-gate.agentother10.7 KB
assets/agents/voice-knowledge-grounded.agentother8.2 KB
assets/agents/voice-service-agent.agentother4.6 KB
assets/bundle-meta.xmlconfig808 B
assets/invocable-apex-template.clsother6.9 KB
assets/patterns/README.mdmarkdown10.8 KB
assets/patterns/action-callbacks.agentother4.7 KB
assets/patterns/advanced-input-bindings.agentother6.9 KB
assets/patterns/bidirectional-routing.agentother5.6 KB
assets/patterns/critical-input-collection.agentother12.2 KB
assets/patterns/delegation-routing.agentother6.4 KB
assets/patterns/lifecycle-events.agentother4.7 KB
assets/patterns/llm-controlled-actions.agentother5.1 KB
assets/patterns/multi-step-workflow.agentother10.1 KB
assets/patterns/open-gate-routing.agentother11.6 KB
assets/patterns/procedural-instructions.agentother4.8 KB
assets/patterns/prompt-template-action.agentother6.6 KB
assets/patterns/system-instruction-overrides.agentother10.6 KB
references/action-prompt-templates.mdmarkdown5.7 KB
references/actions-reference.mdmarkdown30.2 KB
references/agent-access-guide.mdmarkdown2.9 KB
references/agent-audit-and-repair.mdmarkdown7.9 KB
references/agent-audit-candidate-verification.mdmarkdown5.2 KB
references/agent-audit-diagnostic-catalog.mdmarkdown7.6 KB
references/agent-audit-diagnostics-actions-state.mdmarkdown6.9 KB
references/agent-audit-diagnostics-architecture-evaluation.mdmarkdown2.5 KB
references/agent-audit-diagnostics-instructions-routing.mdmarkdown11.8 KB
references/agent-audit-evaluation-loop.mdmarkdown6.0 KB
references/agent-audit-repair-report.mdmarkdown6.9 KB
references/agent-audit-scope-path-review.mdmarkdown8.5 KB
references/agent-design-and-spec-creation.mdmarkdown54.5 KB
references/agent-metadata-and-lifecycle.mdmarkdown30.2 KB
references/agent-script-core-language.mdmarkdown49.3 KB
references/agent-subagent-map-diagrams.mdmarkdown10.8 KB
references/agent-user-setup.mdmarkdown27.8 KB
references/agent-validation-and-debugging.mdmarkdown44.6 KB
references/agentscript-toolchain.mdmarkdown4.6 KB
references/architecture-patterns.mdmarkdown13.5 KB
references/common-control-flow-pitfalls.mdmarkdown9.4 KB
references/complex-data-types.mdmarkdown3.9 KB
references/control-flow-actions-sequencing.mdmarkdown6.9 KB
references/control-flow-lifecycle-side-effects.mdmarkdown3.3 KB
references/data-library-reference.mdmarkdown40.8 KB
references/deploy-reference.mdmarkdown6.7 KB
references/discover-reference.mdmarkdown4.3 KB
references/examples.mdmarkdown12.6 KB
references/feature-validity.mdmarkdown2.1 KB
references/instruction-resolution.mdmarkdown23.4 KB
references/known-issues.mdmarkdown27.6 KB
references/legacy-nga-regression-eval.mdmarkdown30.2 KB
references/mcp-management-reference.mdmarkdown37.6 KB
references/optimization-pattern-1-data-flow.mdmarkdown4.6 KB
references/optimization-pattern-2-deterministic-logic.mdmarkdown5.4 KB
references/optimization-pattern-3-reference-syntax.mdmarkdown4.1 KB
references/optimization-pattern-4-escalation.mdmarkdown2.2 KB
references/org-setup-for-adl.mdmarkdown23.7 KB
references/patterns-by-requirement.mdmarkdown5.4 KB
references/posture-and-determinism.mdmarkdown9.3 KB
references/production-gotchas.mdmarkdown12.6 KB
references/reference-map.mdmarkdown5.3 KB
references/safety-review-reference.mdmarkdown6.3 KB
references/salesforce-cli-for-agents.mdmarkdown16.7 KB
references/scaffold-reference.mdmarkdown6.7 KB
references/scoring-rubric.mdmarkdown3.3 KB
references/upgrade-legacy-agent-to-agentscript.mdmarkdown26.2 KB
references/version-history.mdmarkdown4.4 KB
references/voice-latency-heuristics.mdmarkdown9.7 KB
references/voice-modality-reference.mdmarkdown19.0 KB
references/voice-telephony-cli.mdmarkdown10.3 KB
references/zen-of-agentscript.mdmarkdown13.1 KB
scripts/__init__.pyscript0 B
scripts/agentscript-sdk-loader.mjsscript4.0 KB
scripts/discover.pyexecutablescript20.2 KB
scripts/generators/__init__.pyscript0 B
scripts/generators/apex_stub.pyscript13.4 KB
scripts/generators/apex_test_stub.pyscript3.8 KB
scripts/generators/flow_xml.pyscript7.6 KB
scripts/generators/permission_set_xml.pyscript1014 B
scripts/generators/remote_site_xml.pyscript1.4 KB
scripts/index-agent.mjsexecutablescript3.8 KB
scripts/org_describe.pyexecutablescript5.8 KB
scripts/scaffold.pyexecutablescript15.1 KB
scripts/setup-agentscript-sdk.mjsexecutablescript9.7 KB
scripts/upgrade-legacy-nga-analyze.pyexecutablescript20.0 KB
scripts/upgrade-legacy-nga-run-trials.shexecutablescript3.4 KB

scripts/setup-agentscript-sdk.mjs

View on GitHub
#!/usr/bin/env node

import fs from "node:fs"
import path from "node:path"
import process from "node:process"
import { spawnSync } from "node:child_process"
import { pathToFileURL } from "node:url"
import {
  PUBLIC_PACKAGE,
  PUBLIC_VERSION,
  SOURCE_REF,
  SOURCE_REPOSITORY,
  sdkCacheDirectory,
  sdkManifestPath,
} from "./agentscript-sdk-loader.mjs"

function usage() {
  console.error(
    "Usage: node scripts/setup-agentscript-sdk.mjs [--npm | --source] [--version <version>] [--source-ref <ref>] [--cache-dir <path>] [--force] [--json]",
  )
}

function parseArguments(argv) {
  const options = {
    provider: "npm",
    version: PUBLIC_VERSION,
    sourceRef: SOURCE_REF,
    force: false,
    json: false,
  }

  for (let index = 0; index < argv.length; index += 1) {
    const argument = argv[index]
    if (argument === "--npm") options.provider = "npm"
    else if (argument === "--source") options.provider = "source"
    else if (argument === "--force") options.force = true
    else if (argument === "--json") options.json = true
    else if (argument === "--version") options.version = argv[++index]
    else if (argument === "--source-ref") options.sourceRef = argv[++index]
    else if (argument === "--cache-dir") options.cacheDirectory = argv[++index]
    else throw new Error(`Unknown argument: ${argument}`)
  }

  if (!options.version || !options.sourceRef) {
    throw new Error("--version and --source-ref require non-empty values")
  }
  if (
    options.version !== "latest" &&
    !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(options.version)
  ) {
    throw new Error("--version must be an exact semantic version or latest")
  }
  if (
    !/^[0-9A-Za-z][0-9A-Za-z._/-]{0,200}$/.test(options.sourceRef) ||
    options.sourceRef.includes("..")
  ) {
    throw new Error("--source-ref must be a branch, tag, or commit name")
  }
  return options
}

function run(command, args, options = {}) {
  const result = spawnSync(command, args, {
    cwd: options.cwd,
    encoding: "utf8",
    env: process.env,
    stdio: options.progress
      ? ["ignore", process.stderr, process.stderr]
      : "pipe",
  })
  if (result.error) throw result.error
  if (result.status !== 0) {
    const detail = (result.stderr || result.stdout || "").trim()
    throw new Error(`${command} failed (${result.status}): ${detail}`)
  }
  return (result.stdout || "").trim()
}

function assertManagedPath(target, cacheDirectory) {
  const relative = path.relative(cacheDirectory, target)
  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
    throw new Error(`Refusing to modify path outside SDK cache: ${target}`)
  }
}

function replaceDirectory(target, replacement, cacheDirectory) {
  assertManagedPath(target, cacheDirectory)
  if (fs.existsSync(target)) fs.rmSync(target, { recursive: true, force: true })
  fs.mkdirSync(path.dirname(target), { recursive: true })
  fs.renameSync(replacement, target)
}

async function verifyCompiler(entry) {
  const sdk = await import(`${pathToFileURL(entry).href}?smoke=${Date.now()}`)
  if (typeof sdk.compileSource !== "function") {
    throw new Error(`SDK entry does not export compileSource(): ${entry}`)
  }

  const result = sdk.compileSource(`
system:
    instructions: "Answer questions about store hours."

config:
    developer_name: "Compiler_Smoke_Test"
    agent_label: "Compiler Smoke Test"
    description: "Validates the installed AgentScript SDK."

start_agent store_hours:
    label: "Store Hours"
    description: "Answers store-hours questions."
    reasoning:
        instructions: ->
            | Answer the latest store-hours question.
`)
  const errors = (result.diagnostics || []).filter((item) => item.severity <= 2)
  if (errors.length > 0 || !result.output?.global_configuration) {
    throw new Error("Installed SDK failed its AgentScript compiler smoke test")
  }
}

function writeManifest(cacheDirectory, manifest) {
  const manifestPath = sdkManifestPath(cacheDirectory)
  fs.mkdirSync(path.dirname(manifestPath), { recursive: true })
  const temporary = `${manifestPath}.${process.pid}.tmp`
  fs.writeFileSync(temporary, `${JSON.stringify(manifest, null, 2)}\n`)
  fs.renameSync(temporary, manifestPath)
  return manifestPath
}

async function installFromNpm(options, cacheDirectory) {
  const installRoot = path.join(
    cacheDirectory,
    "agentscript-sdk",
    "npm",
    `${PUBLIC_PACKAGE.replaceAll("/", "-").replaceAll("@", "")}-${options.version}`,
  )
  const packageFile = path.join(installRoot, "package.json")

  if (options.force && fs.existsSync(installRoot)) {
    assertManagedPath(installRoot, cacheDirectory)
    fs.rmSync(installRoot, { recursive: true, force: true })
  }
  fs.mkdirSync(installRoot, { recursive: true })
  if (!fs.existsSync(packageFile)) {
    fs.writeFileSync(
      packageFile,
      `${JSON.stringify({ private: true, type: "module" }, null, 2)}\n`,
    )
  }

  const packageSpec = `${PUBLIC_PACKAGE}@${options.version}`
  if (options.force || !fs.existsSync(path.join(installRoot, "node_modules"))) {
    console.error(`Installing ${packageSpec} in the AgentScript SDK cache...`)
    run(
      "npm",
      [
        "install",
        "--ignore-scripts",
        "--no-audit",
        "--no-fund",
        "--save-exact",
        packageSpec,
      ],
      { cwd: installRoot, progress: true },
    )
  }

  const installedRoot = path.join(
    installRoot,
    "node_modules",
    "@sf-agentscript",
    "agentforce",
  )
  const installedPackage = JSON.parse(
    fs.readFileSync(path.join(installedRoot, "package.json"), "utf8"),
  )
  const entry = path.join(installedRoot, installedPackage.exports["."].import)
  await verifyCompiler(entry)
  return {
    provider: "npm",
    package: PUBLIC_PACKAGE,
    requestedVersion: options.version,
    version: installedPackage.version,
    entry,
  }
}

function pnpmCommand() {
  const direct = spawnSync("pnpm", ["--version"], { encoding: "utf8" })
  if (direct.status === 0) return ["pnpm", []]

  const corepack = spawnSync("corepack", ["pnpm", "--version"], {
    encoding: "utf8",
  })
  if (corepack.status === 0) return ["corepack", ["pnpm"]]
  throw new Error("Source builds require pnpm or Corepack with pnpm enabled")
}

async function installFromSource(options, cacheDirectory) {
  const sourceRoot = path.join(
    cacheDirectory,
    "agentscript-sdk",
    "source",
    "checkout",
  )
  const temporary = path.join(
    cacheDirectory,
    "agentscript-sdk",
    "source",
    `checkout-${process.pid}.tmp`,
  )
  assertManagedPath(temporary, cacheDirectory)

  if (fs.existsSync(sourceRoot) && !options.force) {
    const entry = path.join(
      sourceRoot,
      "packages",
      "agentforce",
      "dist",
      "index.js",
    )
    if (!fs.existsSync(entry)) {
      throw new Error(
        "Cached source checkout is incomplete; rerun with --source --force",
      )
    }
    await verifyCompiler(entry)
    return {
      provider: "source",
      repository: SOURCE_REPOSITORY,
      requestedRef: options.sourceRef,
      sourceRevision: run("git", ["rev-parse", "HEAD"], { cwd: sourceRoot }),
      entry,
    }
  }

  if (fs.existsSync(temporary))
    fs.rmSync(temporary, { recursive: true, force: true })
  fs.mkdirSync(temporary, { recursive: true })
  try {
    console.error(`Fetching ${SOURCE_REPOSITORY} at ${options.sourceRef}...`)
    run("git", ["init", "--quiet"], { cwd: temporary })
    run("git", ["remote", "add", "origin", SOURCE_REPOSITORY], {
      cwd: temporary,
    })
    run(
      "git",
      ["fetch", "--quiet", "--depth", "1", "origin", options.sourceRef],
      {
        cwd: temporary,
        progress: true,
      },
    )
    run("git", ["checkout", "--quiet", "--detach", "FETCH_HEAD"], {
      cwd: temporary,
    })

    const [pnpm, prefix] = pnpmCommand()
    console.error(
      "Installing the public source checkout's pinned dependencies...",
    )
    run(pnpm, [...prefix, "install", "--frozen-lockfile"], {
      cwd: temporary,
      progress: true,
    })
    console.error(
      "Building the AgentScript Agentforce SDK and its dependencies...",
    )
    run(pnpm, [...prefix, "--filter", "@agentscript/agentforce...", "build"], {
      cwd: temporary,
      progress: true,
    })

    const temporaryEntry = path.join(
      temporary,
      "packages",
      "agentforce",
      "dist",
      "index.js",
    )
    await verifyCompiler(temporaryEntry)
    const sourceRevision = run("git", ["rev-parse", "HEAD"], {
      cwd: temporary,
    })
    replaceDirectory(sourceRoot, temporary, cacheDirectory)
    return {
      provider: "source",
      repository: SOURCE_REPOSITORY,
      requestedRef: options.sourceRef,
      sourceRevision,
      entry: path.join(
        sourceRoot,
        "packages",
        "agentforce",
        "dist",
        "index.js",
      ),
    }
  } catch (error) {
    if (fs.existsSync(temporary))
      fs.rmSync(temporary, { recursive: true, force: true })
    throw error
  }
}

async function main() {
  let options
  try {
    options = parseArguments(process.argv.slice(2))
  } catch (error) {
    usage()
    throw error
  }

  const cacheDirectory = sdkCacheDirectory(options.cacheDirectory)
  const installed =
    options.provider === "source"
      ? await installFromSource(options, cacheDirectory)
      : await installFromNpm(options, cacheDirectory)
  const manifest = {
    ...installed,
    installedAt: new Date().toISOString(),
  }
  const manifestPath = writeManifest(cacheDirectory, manifest)
  const result = { status: "ok", cacheDirectory, manifestPath, ...manifest }

  if (options.json) console.log(JSON.stringify(result, null, 2))
  else
    console.log(
      `AgentScript SDK ready: ${installed.provider} (${installed.entry})`,
    )
}

main().catch((error) => {
  console.error(error instanceof Error ? error.message : String(error))
  process.exit(1)
})
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