Agentforce Changes Not Taking Effect? Draft vs. Committed

By John Harris · 2026-08-05

You edit your agent's instructions in Agentforce Builder, save, and run a test conversation. The agent behaves exactly as it did before. You check the save went through - it did. You edit again, save again, test again. Still the old behavior.

Nothing is broken. Your edit landed in the draft. The agent runs the committed version. Those are two different sets of metadata, and until you commit, they never touch.

Two metadata states, two metadata types

When you author an agent in the new Agentforce Builder - or write Agent Script directly in a DX project - your work is saved as a draft in the AiAuthoringBundle metadata type. The bundle holds two files: a standard *.bundle-meta.xml descriptor and a *.agent file containing the Agent Script that defines your agent's behavior. If you know how ApexClass pairs a .cls file with its meta XML, this is the same pattern (Agent Metadata, Agentforce Developer Guide).

The draft is a blueprint. It is not the agent.

The agent your users talk to is built from separate runtime metadata: Bot (the top-level agent record), BotVersion (per-version configuration - only one version can be active), and GenAiPlannerBundle (the reasoning engine, holding subagents, instructions, actions, and orchestration logic). That metadata only gets created or updated when you commit a version - the "Commit Version" button in Agentforce Builder. In pro-code, the equivalent is publishing the authoring bundle, which Salesforce's docs describe as exactly the same operation as the Builder button (Publish an Authoring Bundle).

Commit is the translation step. The platform compiles your Agent Script (compilation errors block the commit), then generates the Bot, BotVersion, and GenAi* components the agent actually executes. Salesforce's engineering blog is blunt about this being the crucial moment: only at commit does your script become active runtime metadata (The New Agentforce Metadata and Development Lifecycle).

So the symptom has a one-line diagnosis: saving updates AiAuthoringBundle; only committing regenerates Bot/BotVersion/GenAiPlannerBundle. Edit-save-test without a commit tests yesterday's agent.

A few mechanics worth knowing:

  • After a commit, the bundle's <target> element is populated with the Bot and BotVersion developer names (e.g. My_Agent.v2). That element is the link between an authoring bundle and its agent - a bundle without it is a draft, and only drafts can be published.

  • Committed bundles show up in your DX project with a version suffix on the directory (My_Bundle_1, My_Bundle_2).

  • GenAiPlannerBundle version numbers auto-increment in commit order, so don't expect them to match your AiAuthoringBundle version numbers.

  • The committed planner bundle stores an encoded snapshot of the script, which is how Builder can warn you that your draft has drifted from what's running.

Why it's built this way

The split isn't an oversight - it's the fix for an older problem.

Historically, Agentforce assets were global. Topics (GenAiPlugin) and actions (GenAiFunction) were shared, so editing one used by three agents changed all three, instantly. Salesforce calls this the "global ripple." Its fix is local assets: a local subagent or action clones the global one and anchors it to a single agent version, so you can edit it without breaking anything else. To make that reliable in CI/CD, Salesforce restructured GenAiPlannerBundle so every asset a version depends on deploys together in one folder (The New Agentforce Metadata and Development Lifecycle).

The draft/commit boundary, which arrived with the new Agentforce Builder, applies the same isolation to time: your in-progress edits can't leak into the running agent. You iterate and preview against the draft - Simulation mode exists precisely so you can test without touching live behavior - and the running version stays frozen until you deliberately cut a new one. A side benefit: because versions are isolated, you can roll out a new version without deactivating the agent first.

What this means for deployment and CI/CD

The split changes how agents move between orgs.

Deploying AiAuthoringBundle to a sandbox or production org gives that org a draft - not a runnable agent. Salesforce's recommended pipeline for source-controlled agents is three operations, run with the Agentforce DX CLI:

  1. Deploy the AiAuthoringBundle to the target org.

  2. Publish the bundle, which generates the runtime Bot, BotVersion, and GenAi* metadata (the pro-code equivalent of Commit Version).

  3. Activate the resulting agent version so it's available to users.

The exact command names and flags for these live in Salesforce's Agentforce DX CLI reference - check there for the current syntax, since the agent CLI plugin is still evolving release to release.

If you want to skip the manual publish step entirely, deploy AiAuthoringBundle and GenAiPlannerBundle together - the platform recognizes the script alongside its pre-built runtime metadata and treats the agent as already committed, so it arrives ready to activate (Salesforce developer blog).

Two gotchas. First, API versions: Salesforce's sample manifest for the new metadata uses API version 66.0, which it says is required to support GenAiPlannerBundle and the new agent metadata types, so keep your tooling's API version aligned with the format you're deploying. Second, a quieter win: pull requests can now diff the human-readable .agent script instead of scattered XML, which makes agent changes actually reviewable.

Why this matters for certification

Certification questions on platform behavior tend to be scenario-shaped: "An admin updates an agent's instructions, but users report no change in behavior. What happened?" You can't pattern-match your way through that - you need the model in your head: draft in AiAuthoringBundle, runtime in Bot/BotVersion/GenAiPlannerBundle, commit as the bridge. The same model answers a whole family of questions about versioning, activation, and deployment order, which is the kind of reasoning-over-recall certification exams reward. One caution: every exam guide is pinned to a specific release, so check which version of the builder your exam's guide describes before you study this model for it.

The Platform Administrator exam has its own Agentforce section, worth 8%, on maintaining and testing agent instructions. Our free Platform Administrator practice course covers it, with every option explained.

Sources

More articles