Agent vs. Builder vs. Script
Which primitive for your Agentforce build — Agentforce Builder, Agent Script, or Prompt Builder?
Every customer call asks it: Builder, Script, or Prompt Builder? Short answer below, reasoning after.
Terminology update (April 2026)
"Topics" are now subagents in Agentforce Builder and Agent Script. Same concept, new name — a subagent is a scoped bundle of instructions + actions the parent agent can route to. Existing .genAiPlugin metadata is unchanged under the hood.
The short answer
Agentforce Builder
Declarative agent with subagents, actions, and guardrails. Admin-maintainable in Setup. Canvas + Script views.
Agent Script
Source-controlled .agent files. Deterministic FSM with slots, transitions, and unit tests. Developer-owned.
Prompt Builder
One-shot reusable prompt template with structured output. Callable from Flow, Apex, LWC. Not an agent.
All three mix in the same org. A Builder agent can route to an Agent Script subagent; either can invoke a Prompt Builder template.
Three-question decision
Conversation or one-shot?
One-shot LLM call → Prompt Builder, stop. Multi-turn → continue.
Does behavior need to be deterministic at the step level?
Yes (slot filling, validation, retries) → Agent Script. No → continue.
Who owns it post-handoff?
Salesforce admin in Setup → Agentforce Builder. Engineering team with PR reviews → Agent Script.
Agentforce Builder
The declarative, point-and-click experience. You build subagents (scoped situations the agent should recognize), actions (what it can do), and instructions in Setup. Metadata is .genAiPlugin, .genAiFunction, .bot.
Builder now ships two authoring surfaces side-by-side:
Visual blocks for subagents, instructions, actions, and transitions. Best for admins and for quick scaffolding when you're still shaping the flow.
Edit the same agent as Agent Script code inside Builder. Same file you'd pull via DX — round-trip edits work. Best once the agent has shape and you want determinism on specific paths.
Pull the .agent bundle locally, edit in VS Code / Cursor with the sf-ai-agentscript skill, deploy back. Best when source control is non-negotiable.
Skill: sf-ai-agentforce for metadata authoring, review, deployment.
Agent Script
A DSL in .agent files — agent as a finite state machine with states, slots, transitions, explicit per-state instructions. Source-controlled, deployable, testable. Subagents are modular units you can transition to deterministically or expose to the LLM as a routing decision.
CLI: sf agent generate authoring-bundle, sf agent validate authoring-bundle, sf agent preview, sf agent publish authoring-bundle, sf agent activate.
Skills: sf-ai-agentscript for authoring, sf-ai-agentforce-testing for tests.
Prompt Builder
A reusable prompt template with input parameters, templated body, defined output shape. Callable from Flow, Apex, LWC, or another agent. Not an agent — no conversation, no tools.
Mix-and-match pattern
Real POCs use all three:
- A Builder agent
Customer Service Triagehandles top-level conversation, classifies intent, routes. - On a warranty claim, Triage hands off to an Agent Script subagent
Warranty Claim Intakethat deterministically collects serial number, purchase date, defect description. - Warranty Claim Intake calls a Prompt Builder template
Summarize Claimthat writes a one-paragraph case summary to the Case record.
Admin owns the shell and the summarization prompt. Developer owns the critical intake path. Everyone edits what they're qualified to edit.
What it looks like on disk
| Tool | Path in force-app/main/default/ |
|---|---|
| Agentforce Builder (subagents, actions, guardrails) | genAiPlugins/, genAiFunctions/, bots/ |
| Agent Script | agents/*.agent (+ bundle files) |
| Prompt Builder | genAiPromptTemplates/*.genAiPromptTemplate |
A .agent file = Agent Script. A .genAiPlugin-meta.xml = Builder-managed subagent. A .genAiPromptTemplate = Prompt Builder.
Testing, briefly
| Primitive | How you test |
|---|---|
| Builder agent | sf agent test run against .aiEvaluationDefinition specs |
| Agent Script | sf agent validate authoring-bundle + sf agent preview pre-deploy; same test runner post-deploy |
| Prompt template | Prompt Builder UI, or programmatic via Models API |
The sf-ai-agentforce-testing skill covers all three with one rubric.
Common mistakes
Before you commit to a primitive
- Reaching for Agent Script when Builder would do. If the admin owns it post-handoff, Builder saves pain. Script is a commitment.
- Reaching for Builder when Script would do. A three-state warranty intake will frustrate you in Builder's planner.
- Using Prompt Builder to fake an agent. Multi-turn needs Builder or Script.
- Mixing without naming. When a Builder agent calls a Script subagent, name them clearly so the customer can tell them apart in Setup.
Next
- Agentforce DX — local authoring flow.
- Session Tracing & Agent Testing — test what you just built.
sf-ai-agentforce-persona— voice and tone before you ship.
CI Reviews & Handoff Automation
Run Claude Code in GitHub Actions to review POC PRs, summarize metadata deltas between demos, and generate handoff docs on every tag. Zero-click artifacts for the customer.
Session Tracing & Agent Testing
Run agent tests from Cursor and read session traces to understand what your Agentforce agent actually did.