Every Agentforce Builder agent that still runs on GPT-4.1 as its reasoning engine now has a deadline. OpenAI is retiring the model near March 2027, and the Winter '27 release note asks you to move those agents to GPT-5.6 Luna before then and test them thoroughly. Switching the model takes one button. Most of the effort goes into finding every agent and subagent pinned to 4.1 and proving that the new model routes, calls actions and answers the way the old one did before you activate it.
The upgrade applies to Lightning Experience in Enterprise, Performance and Unlimited editions with Foundations or Agentforce 1. You can change the reasoning engine at any time, so nothing stops you starting this week.
Which retirement date to plan against
Three Salesforce pages cover this change, and they disagree. The Builder release note says GPT-4.1 retires "near March 2027". A separate note on the GPT-4o and GPT-4.1 family says requests will be rerouted to GPT-5.6 Luna on April 14, 2027, and the release note change log shows the note first gave January 14, 2027, with the date pushed to April 14 the week of October 19, 2026. Meanwhile the Agentforce Developer Guide page on configuring models still lists GPT 4.1 as a recommended model.
| Builder retirement note | GPT-4o / GPT-4.1 reroute note | Agent Script developer guide | |
|---|---|---|---|
| Position on GPT-4.1 | Retiring; upgrade the reasoning engine first | Rerouted along with GPT-4o, GPT-4o mini and GPT-4.1 Mini | One of three "recommended", thoroughly tested models |
| Date given | Near March 2027 | April 14, 2027 (was January 14, 2027) | None |
| Model it points you to | GPT-5.6 Luna | GPT-5.6 Luna | GPT 4.1, Claude Haiku 4.5, Gemini 3.5 Flash |
| Who it addresses | Agentforce Builder agents | Orgs with Einstein for Sales, Platform or Service add-ons | Anyone writing Agent Script |
I am treating the end of February 2027 as the deadline. "Near March" is vague, and the only date with a specific day belongs to a different product surface. Whether the April reroute also catches Builder agents left on GPT-4.1 is not yet confirmed. Even if it does, I wouldn't rely on it: a reroute swaps the model under a live agent with no testing, which is the exact outcome this plan exists to avoid.
The developer guide's recommended list is out of step with the retirement note. Follow the retirement note, and don't start a new agent on GPT-4.1 because a guide page calls it tested.
One more date: the Builder note's upgrade instructions were revised the week of November 16, 2026. If you read it before then, read it again.
Find every agent and subagent still on GPT-4.1
The Builder banner only tells you about the agent you have open. With more than a handful of agents, or a release programme spanning several orgs, check the metadata instead. Agent Script is stored in the agent's AiAuthoringBundle metadata component, which retrieves as a .agent file. A wildcard on the bundle name retrieves every version, and you want them all because old versions are your rollback path.
# Retrieve all versions of each agent bundle (use your own API names)
sf project retrieve start --metadata "AiAuthoringBundle:Claims_Triage_Agent*"
sf project retrieve start --metadata "AiAuthoringBundle:Dealer_Support_Agent*"
# 1. Anything explicitly pinned to GPT-4.1, at agent or subagent level
grep -rn "sfdc_ai__DefaultGPT41" --include="*.agent" force-app/
# 2. Agent files with no model_config at all: these inherit the org default
grep -rL "model_config" --include="*.agent" force-app/
The output sorts your agents into three groups:
- Files matching
sfdc_ai__DefaultGPT41. These need changing; open each match and check its indentation and enclosing block to see whether the pin is at the agent level or inside a subagent. - Files without a
model_config. These use the org-level model set in Setup. Check what that model is before deciding whether these agents are exposed. - Files with a
model_configpointing at another model. Lower risk, though if anything else in the agent changes during the upgrade, retest them too. A file whose onlymodel_configsits inside a subagent still inherits the org default at the agent level, so check where eachmodel_configsits before putting the file in this group.
What Upgrade Now writes, and how model settings stack
In Builder, open the agent, click New Version, then click Upgrade Now in the banner, save, and test. The release note only tells you to click New Version first when the banner or button is missing. I click it every time anyway, because Upgrade Now changes the version you are editing, and I want the active GPT-4.1 version serving traffic until the new one has passed testing.
Upgrade Now adds a model_config block for you. The release note shows the result as:
model_config:
model: "model://sfdc_ai__DefaultGPT56Luna"
After that, Settings > Default Model in Builder lets you change the selection.
model_config accepts model, temperature (0 to 1), max_tokens and top_p (0 to 1), at the agent level or the subagent level. Precedence runs one way:
- A subagent-level model overrides the agent-level model.
- An agent-level model overrides the org default.
- An agent with no
model_configuses the org default from Setup.
Subagent pins are where these upgrades go wrong. If a subagent still says sfdc_ai__DefaultGPT41, upgrading at the agent level does nothing for it. The failure mode is easy to miss: the agent-level change goes in, the test transcripts look clean because no test utterance routes to the one subagent still pinned, and the first real request that reaches that subagent runs on GPT-4.1.
To clear a subagent pin, delete its model_config so it inherits the agent-level Luna setting, or point it at Luna explicitly. I couldn't confirm the guide's exact nesting example for a subagent-level block, so copy the structure Builder generates in your org rather than writing it from memory.
Some templates, including the Agentforce Service agent, use the Salesforce-built EinsteinHyperClassifier model for subagent classification in the Agent Router. That classifier can't use before_reasoning or after_reasoning, and its only tool is @utils.transition. Whether Upgrade Now touches the router's model is not confirmed. If your router uses the classifier, leave it alone unless you have a specific reason to change it.
Run both models side by side before you switch
Comparing the active version with the Luna version tests two things at once: the model, and whatever sampling settings each version happens to inherit. Hold everything except the model constant. I create two new versions from the active one, a control pinned to GPT-4.1 with an explicit temperature and a candidate on Luna with the same temperature.
Control version (GPT-4.1):
model_config:
model: "model://sfdc_ai__DefaultGPT41"
temperature: 0.2
Candidate version (Luna):
model_config:
model: "model://sfdc_ai__DefaultGPT56Luna"
temperature: 0.2
The cost is one extra version to manage and delete afterwards. In return, any difference you see comes from the model.
Next, build an utterance set that covers every subagent, including the ones that rarely see traffic. For each case, record the expected subagent, action and action inputs, plus anything the answer has to mention:
{
"agent": "Claims_Triage_Agent",
"runsPerUtterance": 3,
"cases": [
{
"id": "CT-014",
"utterance": "My windscreen cracked on the motorway yesterday, can I claim?",
"expectSubagent": "New_Claim_Intake",
"expectAction": "Create_Claim_Draft",
"expectInputs": { "lossType": "Glass", "incidentDate": "relative:yesterday" },
"answerMustMention": ["claim reference", "excess"]
},
{
"id": "CT-031",
"utterance": "Cancel the claim I opened this morning",
"expectSubagent": "Claim_Changes",
"expectAction": "Withdraw_Claim",
"expectInputs": { "claimSelector": "most_recent_open" },
"answerMustMention": ["withdrawn"]
}
]
}
Run every case against both versions at least three times, because a low temperature reduces variation without removing it. Use whatever harness you already have; the Builder test panel and a spreadsheet will do. For each case, compare:
- Which subagent it routed to.
- Which action it selected.
- The inputs it passed to that action.
- The final answer.
The first three should match exactly, and a mismatch blocks activation until you understand it. A newer model often fills action inputs differently, normalising a date or skipping an optional field it used to populate, and the Flow or Apex behind the action may not cope. Judge the final answer on meaning and required content. Its wording will change, and that is fine.
When the candidate passes, activate it and keep the old production version for rollback. Delete the control version once you're done.
What to watch for
- Your rollback window closes when GPT-4.1 retires. Until then, rolling back means reactivating the previous version. After retirement that version has nothing to run on, so you either fix forward on Luna or move to another supported model and run the full test set again. The developer guide warns that some supported models may not suit particular agents or tools, so switching to Claude Haiku 4.5 or Gemini 3.5 Flash carries its own risk.
- Upgrade Now changes one version. If several people are editing different versions of the same agent, each version has to be upgraded or rebuilt from the upgraded one.
- Subagent pins beat the agent level. Rerun the grep after the upgrade and confirm it returns nothing.
- Agents without a
model_configfollow whatever Setup says, so if someone changes the org default later, all of those agents change with it. Pinning the model at the agent level costs one line and removes that dependency. - If your router uses EinsteinHyperClassifier, check what Builder generated after the upgrade instead of assuming.
- The reroute note also asks orgs with Einstein add-ons to test their prompts in Prompt Builder and AI Models. If that's you, run that as a separate track.
- Expect the documentation to move again. The upgrade instructions changed in mid-November and the reroute date has already shifted once, so check the release note change log monthly until your last agent is on Luna.
Leave a Comment