Prompt Engineering for Agentforce: Instructions That Behave in Production

Most prompt engineering advice assumes you are talking to a model. Agent prompt engineering is a different craft, because in Agentforce you are not. You are writing text that a reasoning engine reads at runtime while deciding which of several actions to call, and that changes what good writing looks like.

That difference shows up in the direction of the advice. Chat prompting gets better by adding: more context, more examples, more constraints. Salesforce’s published guidance for agent instructions runs the other way, and that inversion is the most useful thing on this page.

Prompt engineering in Agentforce names four different artifacts

Before any technique matters, the word needs splitting. Four separate things get called prompt engineering in Agentforce conversations, and advice written for one of them actively harms another.

Prompt templates are reusable prompts built in Prompt Builder, with merge fields and grounding, invoked at a point in a process. They are closest to classic prompt engineering, and they are the only one of the four where adding context reliably helps.

Subagent instructions are natural-language guidelines attached to a job the agent can do. They tell the reasoning engine how to behave once a request has been routed there.

Action instructions describe a single action: what it does and when to trigger it. They are read when the agent is deciding whether to call that action.

Agent Script is something larger than the other three, and worth getting right because most commentary treats it as a last resort. Salesforce’s developer guide calls it the language for building agents in Agentforce Builder, reachable by selecting Script from the view picker on an agent, or authored through Agentforce DX in Visual Studio Code. It holds natural-language instructions and programmatic expressions in the same artifact, so if and else conditions, variables and transitions sit alongside the prose rather than replacing it.

Almost everything below concerns the middle two, because those are what people mean when an agent misbehaves in production and someone says the prompt needs work. Mixing them up produces a familiar failure: a team writes a 400-word subagent instruction in the register of a ChatGPT prompt, and the agent gets slower, more expensive and less predictable.

One vocabulary note before the techniques. Salesforce documentation now uses subagent where it previously used topic, so search for both terms when hunting guidance. How subagents get structured and scoped is a separate design question, handled in designing subagents and actions. What follows assumes that structure exists and asks how to write the prose inside it.

Classification description routes the request, scope applies only after routing

Here is the mechanism most instruction-writing gets wrong, and Salesforce states it plainly.

A user’s request is classified to a subagent using the classification description. The scope is only used once the agent is already inside that subagent, to say more about what can be done there.

Read that twice, because it means description and scope are not two chances to say the same thing. They operate at different moments on different decisions.

So routing language belongs in the description and nowhere else. If a subagent exists to handle delivery complaints and your description says “handles customer service inquiries” while the scope says “specifically for late or damaged deliveries”, the specific language is sitting in the field that cannot influence routing. The agent will route delivery complaints somewhere else, and no amount of rewriting the scope will fix it.

A diagnostic follows from that mechanism. When an agent does the wrong job, fix the description. When an agent does the right job badly, fix the instructions. Teams that treat agent misbehavior as one undifferentiated prompt problem rewrite the wrong field and conclude the platform is unpredictable.

Salesforce’s own instruction guidance is mostly subtractive

Read Salesforce’s developer guidance on writing natural language instructions and count the recommendations that tell you to add something. There are few.

Salesforce tells you to start with minimal subagent instructions. To nest action-specific guidance into the action configuration rather than the instructions, explicitly to reduce the complexity of what gets sent to the model. To handle validation inside actions using Flow or Apex instead of relying on instructions for formatting control. To build sensitive or deterministic business rules into the action’s logic rather than the prose. And, when an agent is not working, to try stripping the instructions.

One positive instruction does appear and it is narrow: keep action instructions to one to three straightforward sentences covering the action’s purpose, goal and scope. Salesforce’s own before-and-after is instructive about how little that takes. “Updates a status field” becomes “Updates the Task record’s status to ‘Completed.’ If no Task is found, creates a new one with the specified status.” Longer, but only by one clause that resolves an actual ambiguity.

There is a reason the advice runs this direction. Every word of instruction is read at runtime and competes for the model’s attention with the user’s actual request. A chat prompt is a one-off cost paid by the person typing. An instruction is a standing cost paid on every conversation, in latency, in consumption, and in the chance that the agent follows your aside instead of the customer’s question.

“Must”, “never” and “always” make agents stick or over-generalize

This is the most counterintuitive item in Salesforce’s guidance and the one experienced prompt writers get wrong most reliably, because absolute language is exactly what you reach for when a model misbehaves.

Salesforce’s warning is specific. Agentforce follows instructions specifying that it must, never or always do something very closely, and that can produce unintended results. An agent may get stuck trying to satisfy a “must” or “always” condition. It may interpret a “never” far more broadly than you meant. Its recommendation is to use such language sparingly, and to prioritize removing it when troubleshooting in order to find the root cause.

Picture the failure. An instruction says the agent must always confirm the customer’s identity before discussing an order. A customer who has already authenticated in a logged-in session gets asked for identity anyway, refuses, and the agent will not proceed because the instruction is absolute. Nothing is broken. The instruction is being followed.

So absolutes are worth spending deliberately, like a budget. Reserve them for real compliance boundaries, write them as narrowly as the requirement allows, and record why each one exists. An absolute nobody can justify is the first thing to remove when behavior goes strange.

Validation belongs in the action, not the instruction

A pattern worth naming because it looks like good practice and is not.

Teams discover that an agent passes dates in the wrong format, or occasionally omits a required field, and they respond by adding instruction text: always format dates as YYYY-MM-DD, never submit without an account ID. It works in testing, which is the trap.

Salesforce’s position is that validation, particularly of input format, should be handled within actions using Flow or Apex, because that is more consistent than relying on instructions for formatting control. Its reasoning is structural rather than stylistic. Instructions are non-deterministic, so an instruction about format is a strong suggestion that usually holds. A validation rule in a Flow is a guarantee.

Business rules follow the same logic. Refund eligibility, discount thresholds, entitlement checks: build them into the action and let the action return a result. Writing them as prose means the agent is interpreting your policy rather than applying it, and interpretation varies.

A useful test for any line of instruction text: if this were ignored once in a hundred conversations, would anyone be harmed or out of pocket? If yes, it does not belong in an instruction.

Pushing the rule into a Flow or Apex action is one answer, and until recently it was the only one. Agent Script now offers a closer one. Because it carries programmatic expressions next to the prose, a business rule can be written as a condition in the script itself rather than exported to an action, and Salesforce documents variables that hold agent state reliably instead of depending on the model’s context memory. The design question becomes where determinism lives rather than whether you can have it: an action when the logic is reusable across agents, a script expression when it is specific to this conversation.

Test design for the whole set is a separate discipline, covered in how agent behavior gets tested.

Action names compete with each other, so the verbs have to differ

A small point with outsized production effects, and one almost no published guidance mentions.

Agents read action names and instructions to decide which action to call. Similar names create real ambiguity. Salesforce’s illustration is two actions named “Get Project Details” and “Get Task Details”, and its recommendation is to vary the verb rather than rely on the noun: “Locate Project Details” and “Retrieve Task Details”.

That feels like fussiness until an agent calls the wrong action in front of a customer. That first pair leaves the noun doing all the distinguishing work, and nouns in a long action list are precisely what gets confused. Varying verbs gives the model a second, independent signal.

Salesforce’s checklist for this is short enough to apply in a review. Is the action name unique and descriptive? Are the instructions clear, concise and actionable? Is information about dependent actions included? Are all inputs and outputs precisely defined?

That fourth item earns its place. An action whose output is undefined produces an agent that invents a description of what happened.

A prompt template action absorbs the part prose cannot hold

When instructions grow complicated, Salesforce offers an escape hatch that is easy to miss.

Its guidance suggests that if instructions become too complex and the agent stops working, you can move the complex non-deterministic part into a prompt template action type. That is an architectural move rather than a workaround.

Its effect is to convert sprawling prose into a bounded, callable, versionable unit. A long instruction explaining how to summarize a case history in a particular voice is a liability sitting in a subagent, read on every conversation. That same text as a prompt template is invoked only when needed, lives in Prompt Builder where it can be grounded properly, and can be changed without touching agent behavior anywhere else.

So the sequence when instructions get long is: move deterministic parts into actions, move the generative parts into prompt templates, and keep in the instruction only what remains, which is usually guidance about when to do which. What that invocation pattern costs is worth modeling early, since each call is metered, and the mechanics sit in how agent usage is billed.

GetGenerative.ai separates drafting instructions from deciding them

Everything above describes a writing task with a review requirement, which is an awkward shape for most delivery teams. The person who can write unambiguous prose about a returns policy is rarely the person who built the Apex behind it, and the instruction text tends to get written last by whoever has an hour.

GetGenerative.ai addresses the drafting half. Discovery turns workshop sessions into structured requirements, and Design carries those into stories and acceptance criteria, which means the subagent description and instructions get drafted from a recorded statement of what the business actually said rather than from somebody’s recollection three weeks later. Its Metadata Agent reads the org, so action instructions can name the fields and objects that exist instead of the ones the team assumes.

The deciding half stays human, and the division is sharper here than on most artifacts. Whether an absolute is justified, whether a rule belongs in prose or in a Flow, whether a description will actually route: those are judgments about risk and about how a specific business works. A generated instruction set is a strong first draft that still needs someone to delete two thirds of it. Teams scoping this work can review what an activation package includes.

Debugging instructions means removing them one at a time

Production debugging on agents inverts normal practice. Instinct when an agent behaves oddly says add clarifying text. Salesforce’s guidance says to strip.

A loop that works, built from that guidance and ordered by what it rules out fastest:

Remove the absolutes first. Every must, never and always comes out, and the behavior is retested. If the problem disappears, you have found it, and the absolute goes back in a narrower form.

Then take the instruction set down to the minimum that describes the job, and confirm the agent still routes correctly. Routing failures at this point are description problems, not instruction problems.

Then add back one instruction at a time, testing after each. Tedious, and considerably faster than reasoning about which of eleven interacting sentences caused a behavior.

Finally, for each instruction that survives, ask whether it would be more reliable as action configuration. Many will be.

Two habits make this loop possible. Version the instruction text, because an agent’s behavior is defined by prose and prose with no history cannot be bisected. And change one field at a time, since description, scope and instructions act at different moments and simultaneous edits produce uninterpretable results. Who owns this after go-live is a governance question, set out in who holds the instruction set after launch.

A rewritten instruction set shows where the volume goes

Take a returns subagent, written the way teams usually write them first.

> You are a helpful customer service assistant for our company. You should always be polite and professional. Always check the customer’s order history before responding. You must verify the customer’s identity. Never promise a refund without checking eligibility. Always format dates as DD/MM/YYYY. If the customer is angry, be empathetic. Make sure to explain our returns policy which allows returns within 30 days of delivery for unused items in original packaging, except for personalised goods which cannot be returned. Always offer alternatives before processing a refund.

Now the same subagent after applying the guidance above.

What remains is two or three sentences about when to offer an alternative and when to escalate. Everything else became an action, a validation rule, or grounded content.

That is the shape of an instruction set that behaves in production. Volume did not vanish, it moved to places where it executes deterministically instead of being interpreted. Whether the grounded content is actually reachable by the agent is its own pre-flight question, covered in the twelve pre-activation checks.

Six questions about writing agent instructions

What is prompt engineering in Agentforce?

It covers four distinct artifacts: prompt templates built in Prompt Builder, subagent instructions that guide behavior within a job, action instructions describing what a single action does and when to call it, and Agent Script, which Salesforce documents as the language for building agents in Agentforce Builder and which holds natural-language instructions and programmatic expressions together. Advice written for prompt templates, where adding context helps, misleads when applied to subagent instructions, where Salesforce’s guidance is largely to remove.

Why does Salesforce warn against using “always” and “never” in agent instructions?

Because Agentforce follows such instructions very closely, which produces unintended results. An agent can get stuck trying to satisfy a “must” or “always” condition, or interpret a “never” far more broadly than intended. Salesforce recommends using absolutes sparingly and removing them first when troubleshooting, to identify the root cause.

What is the difference between a subagent’s classification description and its scope?

The classification description is what the request is matched against when the agent decides which subagent handles it. The scope is used only after that routing has happened, to describe what can be done inside. Routing language placed in the scope cannot influence routing, which is why an agent doing the wrong job needs its description fixed rather than its scope.

Should input validation go in agent instructions?

No. Salesforce advises handling validation, particularly input format, inside actions using Flow or Apex, because that is more consistent than relying on instructions. Instructions are non-deterministic, so a formatting rule written as prose is a strong suggestion rather than a guarantee. The same applies to business rules such as refund eligibility.

How do you debug an Agentforce agent that ignores its instructions?

Remove rather than add. Strip the absolutes first and retest, reduce to the minimum instruction set that describes the job, then add instructions back one at a time, testing after each. Version the instruction text so behavior changes can be traced, and change one field at a time, since description, scope and instructions take effect at different points.

How long should an Agentforce instruction be?

Shorter than most teams write. Salesforce specifies one to three straightforward sentences for an action instruction, covering the action’s purpose, goal and scope, and advises starting with minimal subagent instructions. Every word is read at runtime and competes with the user’s actual request, so length carries a cost in latency, consumption and the chance the agent follows an aside instead of the question.