Picture an admin at a software company’s support team who gets 2 tickets in the same week. The first asks her to “put AI on the case page” so reps see a summary and a suggested reply. The second, from an architect, asks her to “build it as an agent action” so the service agent can do the same thing in chat. She has a sandbox, a week and a vague sense that the 2 requests are the same job described in different words. This scenario is invented for illustration and doesn’t describe a real company or person.
This post sorts jobs between prompt templates built in Prompt Builder and actions that an Agentforce agent calls. It draws on Salesforce’s Agent Script reference, 3 developer blog posts (2 from April 2024 and the other from July 2025), several Trailhead units, the Prompt Builder product page and the Agentforce pricing page. All of it’s vendor material. I found no independent benchmark, I couldn’t test anything in an org, and I found no Salesforce statement of the credit rate for a prompt template run. Confirm prices, limits and behavior with Salesforce before you commit.
TL;DR
- Prompt templates generate text, and actions do work. A template turns record data into a summary, a draft or a field value. An action reads or changes data, calls a system or runs logic. Choosing between them starts with the verb in the job description rather than with the product names.
- They combine more often than they compete. Salesforce’s Agent Script reference lists prompt templates as an action target next to Flow and Apex, so a template can sit behind an action. The real choice is usually between a template, a Flow and Apex for the work behind the action.
- Pricing for the combination is unclear. Salesforce’s pricing examples imply 20 Flex Credits, about $0.10, per action, and the page says credits work across actions and prompts without a separate prompt rate. My invented volumes of 5,000 to 100,000 actions a month cost $500 to $10,000 a month at that implied rate.
What each tool is for
Prompt Builder is where you write, test and refine reusable prompt templates, according to Salesforce’s Trailhead overview. A template is a prompt with placeholders that Salesforce fills with record data, sends through the Einstein Trust Layer to a language model and returns as text. Salesforce lists 4 template types: Sales Email, Field Generation, Record Summary and Flex, which covers purposes the other types don’t. An agent action is something an agent can do. The Agent Script reference describes an action as a task a subagent performs, with 3 target types: Apex, Flow and prompt template. The tools therefore sit at different levels. A template produces content, and an action is the unit an agent calls, which can have a template behind it.
The practical consequence is that “Prompt Builder or actions” is usually the wrong question. A rep-facing summary on a record page needs only a template. A chat agent that updates a case and then explains what it did needs an action, and that action may call Flow for the update and a template for the explanation. Sorting the job into its verbs, such as generate, look up, update and calculate, tells you which pieces you need, and only then do you decide how an agent fits.
A side-by-side view of both tools
The table compares a prompt template with an agent action on the dimensions that tend to decide a build. Entries come from Salesforce’s documentation and blog posts as of this writing, and the 2024 posts are old enough that you should check them against current documentation. When a cell says “my judgment,” I’m describing a pattern I’d expect rather than quoting a Salesforce statement, so treat those cells as hypotheses to test in your sandbox before you design around them.
| Question | Prompt template | Agent action |
| What it produces | Generated text from a resolved prompt: an email, a summary, a field value | Whatever the target does: updates, lookups, calculations, calls or generated text |
| Who builds it | Admin or prompt author in Prompt Builder | Admin in Flow Builder, or a developer in Apex, then wired into the agent |
| Where it runs | Record pages, Flow, Apex, REST and agents, per Salesforce’s product page and developer blog | Inside a subagent of an agent |
| Data access | Merge fields, related lists, Flow, Apex and Data 360 | Whatever the Flow or Apex reads; Salesforce recommends user mode for Apex |
| Who decides to run it | A user, a flow or code calls it | The model decides, or Agent Script runs it every time |
| Typical failure | Wrong or ungrounded wording (my judgment) | Wrong action chosen, wrong inputs or a partial update (my judgment) |
| First test | Preview in the builder; the invocation API has an isPreview option | Agent Builder, then Testing Center for bulk cases |
Read the table by rows that matter to your job. If the “who decides” row is your main worry, an action with deterministic invocation is the answer. If the “typical failure” row worries you, plan your test cases around it before you plan your prompts. Whichever row you start from, write the answer down before you open the builder, because a decision made late costs more to reverse than a decision made at the whiteboard.
Jobs that fit a prompt template
- Summaries of a record. The Record Summary type creates a rich-text summary of a record from its data, per Salesforce’s Trailhead overview, and Salesforce’s developer blog says it takes a single object as input. A case summary for a rep or a handoff note for an agent escalation fits well, because the source is a single record and the output is text a person reads. Keep the summary short and give it a fixed structure so reps learn where to look.
- Drafted messages. Sales Email templates draft personalized emails from record data. The 2024 developer blog says the template takes a Contact or Lead, plus optionally a second object. That suits follow-ups, meeting recaps and renewal reminders. A rep should review the draft before it goes out, and Salesforce itself recommends a human check of model responses for most use cases, which makes drafts a natural fit. Keep the tone instructions short, and test them on real records.
- Generated field values. Field Generation templates add generated values to custom fields on a record, such as a short description or a category. The 2024 blog says the type takes a single object. Use it where a field today relies on reps typing free text, and decide up front whether the generated value overwrites rep edits. Test with real records, because messy source text produces messy values. Review a sample every week for the first month.
- Classification and translation. Salesforce’s Trailhead grounding unit says prompt templates handle queries such as knowledge search, summarization, translation, classification and content creation. Classification is a good small job: label an inbound message by topic or urgency and return a value another step can use. Ask the template for structured output such as JSON, as Salesforce’s own examples do, so Flow or Apex can parse the result. Measure accuracy on a labeled sample before you trust the labels.
- Flexible single-use content. Flex templates generate content for purposes the other types don’t cover and let you define your own inputs, with up to 5 objects according to the 2024 blog. Use Flex when the job needs more than a single record, such as a brief that combines an account, an opportunity and a recent case. Check the current limit in Salesforce’s documentation, because the post is over 2 years old.
Jobs that fit an action
Flow actions. Flow is the declarative route. Salesforce’s Trailhead grounding unit points teams that prefer low-code or no-code approaches to Flows for agent actions. Use a Flow action for work with clear steps and data changes: update a case, assign an owner, create a task, look up an order record. The logic is visible to admins, version history exists and the result is the same every time the Flow runs. The model decides only whether to call it and with what inputs.
Apex actions. Developers expose an Apex method with the @InvocableMethod annotation, and Agentforce Builder then offers it as an action. Salesforce’s July 29, 2025 best-practices post, by a Salesforce developer advocate, recommends wrapper classes with @InvocableVariable for inputs and outputs, running with sharing in user mode and returning only necessary fields. Choose Apex when the logic is too complex for Flow, such as a calculation with many branches, or when you need tight control of errors and bulk behavior.
External systems. Salesforce’s Trailhead unit recommends MuleSoft APIs for grounding an agent on data outside Salesforce, and recommends Salesforce Connect for real-time access to external objects. A prompt template can’t reach external data through merge fields, according to the 2024 blog, so an action is the usual route for order status, billing balances or inventory held elsewhere. Return only the fields the agent needs, and decide what the agent says when the system is down.
Prompt template actions. The Trailhead unit “Bring Your Prompt to Life with Agent Actions” says prompts are available as actions just like Flows or Apex. You create a new action on the subagent, choose Prompt Template as the reference action type, pick an activated template and describe its inputs and outputs. This is how a Record Summary or Flex template reaches the agent. If the template isn’t listed, the unit says to check that it’s activated in Prompt Builder.
Why the question is rarely either-or
Most real jobs need both text and work. Consider an agent that handles a late-delivery complaint. It needs to find the order (a Flow or Apex lookup), decide whether the customer qualifies for a credit (a rule that belongs in Flow or Apex rather than in a prompt), apply the credit (an update) and write a message that explains the outcome (a template). These steps need 3 or 4 building blocks, and only the last is Prompt Builder work. An agent coordinates them, but each block is built with the tool that suits its verb.
The reverse also happens. A template can call into Flow or Apex for grounding, which Salesforce’s 2024 blog describes as a template-triggered prompt flow or an invocable method assigned to a template capability. In that case Flow or Apex supplies data to the prompt and the agent never sees it. Keeping those layers straight matters for testing. When a summary is wrong, you need to know whether the grounding returned bad data, the prompt misread it or the agent passed the wrong input, because each fix lives in a different place.
How a prompt template gets its data
- Merge fields and related lists. These are the simplest route. They reference record properties directly in the template and cover CRM data, with Data Cloud enrichment for Contacts and Leads in 2024, according to Salesforce’s developer blog. The same post says merge fields can’t reference external data. Start here, because a template that uses only merge fields is easy to read, easy to preview and easy to hand to another admin.
- Flow. Salesforce’s blog describes a template-triggered prompt flow that receives the template’s inputs, computes grounding text and adds it through an “Add Prompt Instructions” element, which the author calls additive. Flow can reference CRM, Data Cloud and external data. Use it when the template needs related records, a filter or a calculation that merge fields can’t express, and keep the grounding logic small so it stays readable. Test it with a record that has no related data.
- Apex. For more control, write an invocable method assigned to a capability type, such as the Sales Email type or a Flex template. The method takes a list of requests with a variable per template input and returns a list of responses whose Prompt variable holds the text added to the prompt. Choose Apex when you need custom queries, error handling or calls to services that Flow handles awkwardly. Keep the method small and covered by unit tests.
- Data 360 and retrieval. Salesforce’s product page says prompts can be grounded in unstructured data from Data 360 and external data through MuleSoft, with retrieval or Flow Builder logic. The Trailhead grounding unit says Agentforce Data Libraries suit unstructured datasets and automate steps such as creating a search index and retriever. I haven’t tested retrieval quality, so evaluate it on your own documents. Compare retrieved passages with the source before you let a template quote them.
How actions get chosen and run
Chosen by the model. When you expose an action as a tool in the reasoning block, the model decides whether to call it, according to Salesforce’s Agent Script reference. It reads the action’s description to decide, so the description has to say what the action does and when to use it. The reference also says the model fills only inputs that are both required and unbound. Weak descriptions lead to missed calls or wrong calls, and no setting compensates for that.
Run every time. The same reference describes a deterministic option: call an action with run @actions.<name> in a subagent’s reasoning logic or in its after-reasoning block, and it runs every time the subagent runs. Use this for steps that must happen, such as logging an interaction or verifying a customer before anything else. The reference also shows chaining, where an action triggers another immediately afterward, which removes the model from the sequence.
Sequencing and composite actions. Salesforce’s July 2025 post says topic instructions can sequence actions but calls that non-deterministic, and says that for fully deterministic sequencing you should build a composite action in Apex or Flow. If a refund must follow an eligibility check every time, put both in a single Flow so the order isn’t left to the model. Pass data between actions with variables when you do rely on instructions.
Outputs and confirmation. By default the agent keeps action outputs for the whole session, per the Agent Script reference, and the filter_from_agent property hides an output from the agent’s context. The reference also lists require_user_confirmation for actions that should ask the customer first. Hide bulky or sensitive outputs, and require confirmation for anything that changes money, contact details or entitlements. Treat each output as something the customer could eventually see, and ask whether the conversation needs it.
Matching common jobs to a tool
The table below maps typical jobs to a likely fit. It’s my judgment, built from the documentation above, and your constraints may change the answer. Where I say “Flow or Apex,” the deciding factor is usually who will maintain it: an admin team points toward Flow, and a developer team with test coverage points toward Apex. Treat the “reason” column as the thing to argue with in your design review.
| Job | Likely fit | Reason |
| Summarize a case for a handoff | Record Summary template, wrapped as an action for the agent | Text from a single record, and a person reads it |
| Draft a reply email | Sales Email or Flex template | Personalized text from record data, reviewed before sending |
| Update case status or owner | Flow action | Declarative, repeatable and visible to admins |
| Calculate a refund with business rules | Apex action, or Flow if the rules are simple | Logic belongs in code or Flow, with tests, rather than in a prompt |
| Fetch order status from an outside system | Apex or Flow action, or a MuleSoft API | Merge fields can’t reach external data |
| Fill a custom field from rep notes | Field Generation template | Generated text for a single object |
| Run a fixed sequence of steps | Composite Flow or Apex action | Salesforce says instruction sequencing is non-deterministic |
| Answer a policy question from documents | Retrieval grounding with a template or knowledge action | Data Libraries suit unstructured data; I haven’t verified quality |
Testing and failure modes
Salesforce’s July 2025 post lists 4 ways to test an Apex action: Agent Builder for planning and reasoning in real time, Agentforce Testing Center for bulk responses to varied inputs, Agentforce DX tools to automate tests in CI/CD, and Apex unit tests for the code. Prompt templates have their own check, the preview. Salesforce’s invocation post shows an isPreview option that resolves the template without sending it to the model, which lets you see exactly what the prompt contains. When a template misbehaves, read the resolved prompt first, because empty or wrong grounding is a common cause.
Expect different failures from each tool. Templates fail by producing fluent but wrong text, by ignoring format instructions or by running long. Actions fail by being chosen when they shouldn’t be, by being skipped when they should run, by receiving bad inputs and by half-completing a bulk update. The Apex post notes that agent actions don’t bulkify by default and that each action runs in its own transaction. Build a test set for each failure type, include requests that shouldn’t trigger an action, and rerun it after every change to a description, instruction or prompt.
Controls that apply to both
- Trust Layer masking and retention. Salesforce’s Trailhead overview says the Trust Layer masks sensitive data before a prompt reaches the model, and its product page cites data masking and no-retention terms. Neither page lists every masked data type or says what the retention commitments cover. Ask Salesforce for those details in writing, and test masking with realistic sample records in a sandbox rather than relying on the description. Keep the test records and results as evidence.
- Permissions and user mode. Salesforce’s Apex post recommends sharing, running queries and updates in user mode and returning only necessary fields for public actions. For private actions, it says to verify the user before executing. The prompt template articles I read don’t say which user context template invocations run as, so test that explicitly with a low-privilege user before launch. A low-privilege test user will show quickly whether a field or record leaks into an output.
- Human review. Salesforce’s Trust Layer documentation recommends that a person check each model response before it reaches end users in most use cases. Drafts reviewed by reps meet that easily. A chat agent talking directly to customers doesn’t, so decide which responses need review, which can go out directly and how you’ll sample the rest. Record the decision for each use case, with an owner, so an auditor can see that review was chosen deliberately rather than assumed.
What it costs, as far as anyone publishes
The meter. Salesforce’s Agentforce pricing page lists Flex Credits at $500 per 100,000 credits, which is 0.005percredit.Thepageshowsnodate.Itsexamplesgivecreditsperaction:a”WhereisMyOrder”agentwith2actionsuses40credits(0.20), case management with 3 actions uses 60 (0.30),appointmentschedulingwith5actionsuses100(0.50) and onboarding with 1 action uses 20 ($0.10). Each works out to 20 credits, or $0.10, per action, an inference from examples rather than a stated rate.
A mismatch in the examples. A voice reservation example lists 4 actions and 120 credits, which is 30 credits per action, and shows $0.15. At $0.005 a credit, 120 credits would be $0.60 in total, so the $0.15 appears to be a per-action figure while the other rows show totals. The page also says usage types and multipliers differ for voice actions without giving a multiplier. Treat the page’s examples as illustrations, and get a written rate card from Salesforce.
Prompts and actions share a pool. The page says Flex Credits are fungible across actions, prompts, translations and voice actions. It gives no separate rate for a prompt template run and doesn’t say whether a template called inside an action counts once or twice. This is the main gap for this comparison. I found no Salesforce statement that settles it, so ask your account team and put the answer in the order form.
Other terms. The pricing page says unused credits don’t roll over, overage is billed at your contracted rate monthly in arrears, and Flex Credits and Conversations can’t be used in the same org. It lists a $2 per conversation option, 125peruserpermonthadd-ons(150 for industries) and Agentforce 1 Editions from $550 per user per month with 2.5 million Flex Credits per org per year. Its examples exclude Data 360 credits and other consumption services.
A usage cost model with invented inputs
The table prices 3 invented monthly volumes at the implied 20 credits per action and $0.005 per credit, then compares annual credits with the 2.5 million per year that the pricing page lists for Agentforce 1 Editions. The volumes are invented, the 20-credit rate is inferred from Salesforce’s examples, and the model ignores prompt template charges because I found no separate rate. Replace the inputs with your own usage forecast and the rate on your order form.
| Actions a month | Credits a month | Cost a month at $0.005 | Credits a year | Against 2.5 million included |
| 5,000 | 100,000 | $500 | 1,200,000 | 48% of the allowance |
| 25,000 | 500,000 | $2,500 | 6,000,000 | 2.4 times the allowance |
| 100,000 | 2,000,000 | $10,000 | 24,000,000 | 9.6 times the allowance |
The included 2.5 million credits cover 125,000 actions at 20 credits each, or $12,500 at list-equivalent pricing. At 25,000 actions a month, annual use exceeds the allowance by 3.5 million credits, which would cost $17,500 at $0.005 each, and at 100,000 actions the excess is 21.5 million credits, or $107,500. Those overage figures assume the list-equivalent rate, which may not match your contract. The $2 conversation price breaks even with Flex Credits at 20 actions per conversation, so a conversation averaging 3 actions costs about $0.30 on credits.
Mistakes that waste a sprint
- Building an action when a template would do. A rep-facing summary on a record page doesn’t need an agent. Salesforce’s product page says prompts can be used on record pages and in Flow, so a template alone can deliver it. Adding an action, a subagent and agent testing multiplies the work for a job that needed none of it. Start with the simplest surface that reaches the user. Add the agent later, if the job turns out to need it.
- Writing vague action descriptions. Salesforce’s reference says the model reads the description when deciding whether to call an action, and the July 2025 post says labels and descriptions should match between Apex and the action configuration. A description such as “updates a record” invites misuse. Say what the action does, what it needs and what it must not be used for. Reread every description as if you’d never seen the system, and fix anything a stranger could misread.
Naming churn and documentation drift
Salesforce’s names and prerequisites have moved while these tools matured, and sources of different ages disagree. The Trailhead unit says subagents are being rebranded from topics, so your org may show either term. The 2024 developer blogs say Prompt Builder requires an Einstein 1 Edition license or a paid add-on, while the pricing page now lists Agentforce 1 Editions and Flex Credits. The Apex post refers to Agent Builder and the Trailhead unit to Agentforce Builder. The 2024 grounding and invocation posts are 930 and 921 days old, and the grounding post says some features were still in development.
Sources also differ in age. The Prompt Builder product page was published Mar 1, 2024 and modified Sept 3, 2026, according to its metadata, and the pricing page shows no date. The Agent Script reference page showed no date in what I read. For decisions that depend on a limit, a license or a price, treat blog posts as background and confirm in the current documentation or with your Salesforce account team. When sources conflict, trust the newer source and ask Salesforce to confirm in writing.
A practical order of operations
Start with the job. Write the job as a sentence with a verb, for example “summarize an open case and update its priority.” Split it into verbs and sort each into generate, look up, update or calculate. Verbs that generate text go to templates, and the others go to Flow, Apex or an API. This takes an hour and prevents building the wrong tool. Share that sentence with the business owner before you build, and fix the wording together.
Build the smallest version. Build the template or Flow alone and run it from a record page or a screen flow. Preview the template to see the resolved prompt. For an invented sprint starting Monday, Nov 2, 2026, this fits in week 1, with a review on Fri, Nov 13, 2026. A working piece you can test beats a diagram of an agent. Keep the first build small enough to throw away.
Test in a sandbox. Run realistic records, including messy ones, with a user whose permissions match production. Check masking, confirm which user context the template runs under, and record failures. Set exit criteria, such as a maximum error rate on a sample and no unauthorized data in any output, before you look at results. Keep the failures in a log with the input, the output and the fix, because that log becomes the regression set you rerun after every later change.
Add the agent last. Once the pieces work, expose them as actions, write precise descriptions, decide which must run every time and which the model may choose, and build a test set for the agent. Week 4 of the invented sprint includes the Nov 26 US holiday, so plan test coverage. Measure credits per conversation early, and compare them with your forecast. Rerun the earlier template and Flow tests as well, since the agent changes the inputs they receive.
FAQs
What’s the difference between Prompt Builder and an Agentforce action?
Prompt Builder is the tool where you write, test and refine prompt templates that turn record data into generated text. An Agentforce action is a task an agent can perform, and its target can be a Flow, an Apex method or a prompt template. So a template produces content, while an action is the unit an agent calls. Many builds use both, with a template behind an action. The distinction matters most when you plan testing.
Can a prompt template be used as an agent action?
Yes. Salesforce’s Agent Script reference lists prompt templates as an action target next to Flow and Apex, and a Trailhead unit shows creating a new action with Prompt Template as the reference action type. The template must be activated in Prompt Builder first. Write clear descriptions for the action’s inputs and outputs, because the model uses them to decide when to call it and what to pass. Test the action with a few inputs that are missing.
When should I use Flow rather than Apex for an action?
Use Flow when the steps are clear, admins will maintain them and the logic fits declarative tools. Use Apex when the logic is complex, when you need precise error handling and bulk behavior, or when developers own testing. Salesforce’s Trailhead unit points low-code teams to Flow, and its July 2025 post gives detailed Apex guidance. Both can be wrapped in composite actions for fixed sequences. When in doubt, build the first version in Flow and move to Apex if limits appear.
Which costs more, a prompt template or an action?
I can’t say. Salesforce’s pricing examples imply 20 Flex Credits, or about $0.10, per action, and the page says credits are fungible across actions and prompts. It lists no separate rate for a prompt template run and doesn’t say how a template called inside an action is counted. Ask Salesforce for a written rate card and for the treatment of nested calls before you forecast. Until then, treat any forecast as a range rather than a number.
Can prompt templates use data from outside Salesforce?
Yes, through Flow or Apex grounding, though not through merge fields. Salesforce’s 2024 developer blog says merge fields can’t reference external data, while Flow and Apex can reference CRM, Data Cloud and external data. Its product page also mentions external data through MuleSoft. For live lookups the agent needs at conversation time, an action that calls the system is often the clearer design. Confirm in your sandbox that the external call respects the permissions of the user who triggered it.
How do I make an action run every time?
Call it deterministically in Agent Script with run @actions.<name> in the subagent’s reasoning logic or after-reasoning block, per Salesforce’s reference. Instruction-based sequencing is described as non-deterministic in Salesforce’s July 2025 post, which recommends a composite action in Apex or Flow when order matters. Test the sequence with cases that try to skip a step, and confirm the behavior in your current release. Then check the log to confirm the action ran in the right place.
Do I need Prompt Builder to build an agent?
I found no Salesforce document that says so. The Trailhead grounding unit lists Apex, Flows, prompt templates and MuleSoft APIs as ways to connect agents to data, so a template is an option among several. An agent that only looks up and updates records can use Flow and Apex actions alone. Prompt Builder becomes useful when the agent needs generated summaries, drafts or classifications. Confirm with Salesforce whether your edition requires a separate license for it.
What’s the best way to test both?
Test each piece alone before the agent. Preview templates to read the resolved prompt, run Flows and Apex with unit and sandbox tests, then test the agent in Agent Builder and in Testing Center with bulk cases. Salesforce’s July 2025 post lists those 4 test approaches for Apex actions. Include requests that shouldn’t trigger an action, low-privilege users and messy records. Keep a regression set of these cases, and rerun it after every change.
