In one sentence: Prompt Builder is a place to write a prompt, attach real record data to it with merge fields, see the resolved text before it goes anywhere, and activate it so other things can call it. The interface is simple enough that people skip the two steps that matter, which are reading the resolved prompt and testing against records that are messy rather than tidy.
Creating a template
You pick a type first, and the type decides where the output can go and what inputs are available. Then you name it, choose the object or objects the template works against, and write the instructions.
The template is mostly prose with merge fields embedded. A rough shape that works:
You are summarising a support case for an agent
picking it up mid-conversation.
Case subject: {!Case.Subject}
Status: {!Case.Status}
Opened: {!Case.CreatedDate}
Description: {!Case.Description}
Write three sentences: what the customer wants,
what has been done, what is outstanding.
If the description is empty, say so and stop.
Three things there do real work. The role statement sets the audience. The output shape is specific, so you get three sentences rather than an essay. And the empty case is handled explicitly, which is the most useful line you can add.
Grounding with merge fields
A merge field pulls a value from a record into the prompt before it is sent. This is the difference between a prompt that knows about your data and one that invents something plausible.
Practical rules:
- Name the fields you want. Pulling a wide set of fields fills the prompt with things the model has to sift, and puts data in front of it you might not have chosen to expose.
- Related records need a path. What relationships are traversable, and how deep, is constrained. Where the template cannot reach the data, get it from a flow instead.
- Labels matter. The model reads the surrounding text. “Status: Escalated” is understood. A bare value on its own line is not.
- Empty fields arrive as nothing. The prompt just has a gap, and the model fills it. Say what to do when a field is blank.
Where record fields cannot supply what you need, a flow can return computed or queried values into the template. That is the route for anything involving arithmetic or conditions.
Testing it properly
The preview lets you pick a record and see both the resolved prompt and the response.
Read the resolved prompt first, before you read the output. Most template problems are visible there: a merge field that did not resolve, a field that was empty, a description forty thousand characters long that has pushed your instructions into the background. If the input is wrong, the output tells you nothing.
Then test against records chosen for being awkward rather than representative:
- A record with the key fields empty.
- One with an enormous text field.
- One in a language other than English, if that happens in your org.
- One where a customer has typed something instruction-shaped into a free text field.
- The same record three times, to see how much the output varies.
That last one surprises people. Run it repeatedly and you get a sense of the variance you are shipping, which a single clean preview hides entirely.
Activating and calling it
A template does nothing until it is activated. Activation makes it callable from wherever its type allows, which may be a Lightning page component, a Flow, Apex, an agent action, or the API depending on the type you chose.
Treat activation as a release step. It is the moment the template starts running against real records for real people. Understand how your org handles changes to an active template before editing one in production.
What it is not for
Prompt Builder is not a place to implement business rules. If the correct output depends on conditions, thresholds or calculations, those belong in a flow or Apex that supplies the finished value. A prompt that says “if the amount is over 10,000 mention the enterprise team” will follow that rule most of the time, and most of the time is not a rule.
Frequently asked
Why does the output differ between previews? Because the model is not deterministic. Variation is normal. If the variation changes the meaning, tighten the instruction or move the decision out of the prompt.
How long should a template be? Long enough to be specific about the output, short enough that the instructions do not get lost behind merged data. If the data section dwarfs the instruction section, cut fields.
Do templates deploy? Yes, as metadata, and they will resolve differently in the target org because the data differs. Retest after every deployment.
