From Doomprompting to Agent Script-A Translation Guide for Existing Agents
You've got an Agentforce agent in production. It mostly works. "Mostly" is the problem.
Every time it fails, you write more instructions. The instructions get longer. The failures get subtler. That cycle has a name: doomprompting.
Agent Script exists to break that cycle. This is what an agentforce agent script migration actually looks like: what to translate, what to leave alone, and what breaks in the process.
Two prerequisites apply before this translation makes sense. Use the decision map to confirm the agent needs L6 deterministic routing. Use the org audit to confirm your org is ready.
The term has a precise definition. Start there.
What Doomprompting Actually Is (And Why Salesforce Coined It)
Doomprompting in Agentforce is the pattern that forms when you rely on natural language instructions to force an LLM into specific, repeatable behavior. It produces the right output most of the time. The failure cases are unpredictable.
What it looks like
Here is a typical doomprompting example. One instruction, trying to handle an order routing decision:
When a customer contacts about an order, first check the order value by querying the Order object. If the order value is greater than $10,000, treat this as high-value: be thorough, take extra time, and escalate to the senior support team. If the order value is under $10,000, be efficient and friendly. Always maintain an empathetic tone regardless of order value.
That instruction works ~85% of the time. The escalation step, the one that matters most for high-value customers, gets skipped unpredictably.
Why it happens
LLMs are pattern-completers, not instruction-followers. They predict the most probable next token given context. They do not execute a checklist.
Salesforce's own research shows LLMs begin omitting instructions after eight directives. Stack more than that in a single instruction block and you will lose some of them. Not sometimes. Reliably. (salesforce.com/blog/doomprompting/)
The "always", "never", "you must" qualifiers you add to compensate do not fix this. They add more directives. They push the count higher.
The signal you're doomprompting
Your instructions are 3+ sentences trying to force specific behavior.
You've added "always", "never", "you must" to compensate for unreliable output.
You've rewritten the same instruction more than twice.
If any of those apply, you have instructions that belong in Agent Script, not in a natural language prompt.
The Instruction Audit: What to Translate and What to Leave Alone
Not every instruction is a doomprompt. The audit determines which ones cross the line and what the right translation target is.
Step 1 : Export with Agentforce DX
Run sf agent retrieve. This exports your agent as .agent files: readable, diffable, and version-controllable from the start.
Mohith Shrivastava, from the Salesforce Developers team, described the DX workflow: "use the very familiar org browser in VS Code to pull it into your Salesforce DX project." That is your baseline. (developer.salesforce.com/docs/ai/agentforce/guide/agent-dx.html)
Step 2 : Categorize every instruction by type
The core question in any agentforce instruction audit methodology is simple: does this instruction need deterministic execution or LLM judgment? The table below maps each type to its correct translation target.
| Instruction type | Characteristic | Translate to |
|---|---|---|
| Must happen identically every time | Deterministic routing needed | if/else block in Agent Script |
| Interpret tone, context, or ambiguity | LLM judgment is the right tool | | pipe prompt instruction |
| Calls a Flow or Apex class | Data or computation needed | action with target: "flow://..." |
Step 3 : Identify the doomprompts
Flag any instruction that is 3+ sentences AND tries to control behavior probabilistically. Those are your migration candidates.
Not everything moves. An instruction that interprets tone or handles ambiguity belongs in a | pipe prompt line. Moving it to an if block removes the LLM reasoning that makes it useful.
To speed this up, paste your exported .agent file contents into any LLM with this prompt:
Review the output: Example 3 is the one most teams miss. Any instruction that says "always", "never", or "must" around account data, entitlements, or approvals is a MIGRATE regardless of sentence count. The LLM will honor it 85% of the time. The other 15% is a compliance gap.
Step 4 : Check Levels of Determinism first
Before scripting at L6, ask: is this a data retrieval problem (L3)? A context-loss problem (L4)? An action availability problem (L5)?
Only the instructions that genuinely need identical execution every turn belong in Agent Script. Use the decision map to confirm which level applies before writing a single line of script.
Before and After: Three Translations
No other guide in this SERP provides complete before/after migrations with real Agent Script syntax. Three patterns architects encounter most often in production.
Example 1: Order value routing
The before: natural language
When a customer contacts about an order, check the order value using the Order object. If the value exceeds $10,000, this is a high-value order: be thorough, take extra time to investigate, and escalate to the senior support team. For standard orders under $10,000, be efficient and friendly. Always maintain an empathetic tone.
This works 85-90% of the time. The escalation step gets skipped unpredictably, usually when the LLM pattern-matches to a "satisfied customer" context and skips the conditional check.
The after: Agent Script
(developer.salesforce.com/sample-apps/agent-script-recipes)
What changed
Routing is deterministic: the if block runs identically every turn, regardless of LLM prediction.
Tone stays with the LLM: | pipe lines are prompt instructions. The LLM still decides how to express "thorough and empathetic."
The Flow does the data work. Agent Script directs traffic between outcome paths.
Example 2: Identity verification gate
Security gates are the doomprompting failure architects lose sleep over. "Always verify identity before discussing account details" is followed ~85% of the time. The other 15% is a compliance gap.
The before: natural language
Always confirm the customer's identity before discussing any account details. If there's any doubt, ask for additional verification. Never share account information with an unverified caller.
This is the edge case from the audit prompt (Example 3 in the migration classifier above): the one most teams miss. "Always" and "never" around account data are security requirements, not style preferences. The LLM honors them probabilistically.
The after: Agent Script
What changed
available when @variables.identity_verified == True makes get_account_details invisible to the agent until verification passes. The agent cannot skip what it cannot see.
identity_verified is a mutable variable declared with a default of False, not a chat memory. It survives re-execution every turn. State that a doomprompt asks the LLM to "remember from earlier in the conversation" is now an explicit boolean the platform tracks.
Three overlapping constraints ("always", "if there's any doubt", "never") are replaced by one gate.
Example 3: Refund eligibility gate
Multi-condition checks are the most common within-turn failure in production agents. LLMs reliably follow a two-step check. Add a third condition and they begin short-circuiting: proceeding on the first True without evaluating the rest.
The before: natural language
When processing a return, check if the customer has an active warranty AND the item was purchased within 90 days AND the refund amount is under the auto-approve threshold. If all three conditions are met, process the refund automatically. If any condition fails, route to manager approval.
In production: LLMs frequently approve refunds for in-warranty items without verifying the time window or the threshold. The compound AND is treated as "check one, infer the rest."
The after: Agent Script
What changed
check_entitlement returns three values in a single Flow call: has_warranty, days_since_purchase, refund_amount. One action, multiple outputs, all used in downstream branching. This is how real Salesforce Flows work.
Nested if blocks enforce evaluation of all three conditions. No else if exists in Agent Script: separate if blocks prevent the LLM from jumping to a conclusion after the first check passes.
available when @variables.has_warranty == True on auto_approve_refund adds a platform-level gate before the reasoning block runs.
What you gain
Guaranteed execution for every path. Order escalation fires for every order over $10,000. Account details are gated on verified identity, every time. Refund approval runs all three conditions, not just the first.
Before Agent Script, each of these had a 10-15% failure rate. Now they are guarantees, not probabilities.
Datasite saw a comparable shift: case deflection jumped from the low 60s to 82% after migrating to Agent Script. The 17-point gain came from determinism, not new functionality. (salesforce.com/blog/datasite-agentforce/)
What you lose
For each example: the LLM can no longer apply contextual judgment to override the gate. It cannot escalate a $5,000 order because the customer sounds urgent. It cannot share account details even when context makes identity "obvious." It cannot approve a refund it intuitively senses is valid.
Here's the thing: that flexibility was never reliable. It was a guess. The question is whether those guesses were ever defensible for compliance, security, or financial thresholds.
Decide that for your specific use case. Do not default to keeping the flexibility because it feels safer.
Syntax notes
These apply across all three examples. Agent Script is whitespace-sensitive and case-sensitive. Wrong syntax fails silently in some cases.
3-space indentation. Not tabs. Not 2 spaces. Tabs break the parser with no error message.
True / False capitalized. Python-style booleans, not JavaScript.
No else if. The construct does not exist in Agent Script. Use separate if blocks for multi-branch logic. The nested if pattern in Example 3 is the correct idiom.
instructions:-> on one line. The arrow goes with instructions:, not on the line below it.
Declare mutable variables before use. The identity_verified: mutable boolean = False in Example 2 is required. Undeclared variables fail at runtime.
Migration Tools and Surfaces
Three tools handle different parts of this migration. They are not interchangeable.
Agentforce DX (recommended for production migrations)
sf agent retrieve pulls the agent into your local project as .agent files. Edit in VS Code. sf agent deploy pushes the updated script back to the org.
This is the serious migration workflow: full source control, peer review, and diff-based iteration. The org browser approach Mohith Shrivastava describes makes it familiar territory for experienced Salesforce developers. (developer.salesforce.com/docs/ai/agentforce/guide/agent-dx.html)
SF Explorer AgentScript Migration Tool
SF Explorer automates ~85% of structural conversion: config mapping, variable extraction, and topic routing. The remaining 15% covers business rules, reasoning logic, and error handling. That part is still manual.
Good for large agents where converting the structure by hand would take too long. (info.sf-explorer.com/blog/agentscript-migration-tool/)
AI Assistant in the new Agentforce builder
The Salesforce new Agentforce builder includes an AI assistant that accepts natural language descriptions and suggests Agent Script syntax. Useful for prototyping individual topics and exploring unfamiliar constructs. Not designed for full migrations.
Use DX for production. Use SF Explorer for structural scaffolding. Use the AI assistant for syntax exploration.
Common Issues and What You Cannot Do Yet
Most migration failures fall into four categories. Know them before you start.
What breaks during migration
Indentation errors: Agent Script is whitespace-sensitive. 3-space indent, enforced strictly. Tabs break the parser silently: no error message, just wrong behavior.
else if usage: The construct does not exist in Agent Script. Teams migrating conditional logic hit this immediately. Use separate if blocks.
Variable naming: Classic agent variables do not map directly. Declare all variables in the variables: block before use. Undeclared variables fail at runtime.
Turn re-execution: Instructions re-execute every turn with fresh context. Behavior that passed one-shot testing can break in multi-turn conversations. This is the subtlest failure mode.
What the language cannot do yet
Only + and - arithmetic. Move complex calculations to Flow or Apex.
60-second action timeout. Plan your action chains accordingly.
No else if roadmap as of TDX April 2026.
The Bottom Line
This is not a rewrite. It is a translation. Your existing instructions already encode real business logic. Agent Script gives that logic guarantees.
Start with one topic. The one where "mostly works" keeps you up at night.
Translate its highest-risk instruction. Test in sandbox. Compare reliability against the natural language version. The difference will be visible in the logs.
Before migrating, check the pitfalls guide for what goes wrong after the script works: deployment issues, governance gaps, and edge cases that testing does not catch.
Next in the series: Agent Script Has No Try/Catch. Here's Why That's the Point.
Which instruction in your current agent is the biggest source of unpredictability? Drop it below.
Thoughts?
Explore Related Blogs
Let’s Talk
Drop us a note, we’re happy to take the conversation forward 👇🏻
