top of page

Managing Agentforce Across Sandbox Refreshes

6 days ago
5 min read

Authored by: Nick Ralston, Sr. Solution Architect, Truffle Consulting


Truffle Consulting poster with robot mascot and steps list: Inventory, Refresh, Reconfigure, Deploy, Reconnect, Validate.

What a refresh does to an Agentforce agent, and the six-step runbook for getting it working again


Does an Agentforce agent survive a Salesforce sandbox refresh?

Partly.


The refresh copies production metadata as it always has, but a working agent also depends on feature enablement, an execution user, Data 360 (Data Cloud) grounding, credentials, channels and other setup tied to the specific org. Those don't reliably come back on their own.


Plan every refresh of a sandbox that hosts an agent as a small deployment. Keep the agent and its dependencies in source control, refresh the sandbox, restore and reconnect what the agent needs, then test it before you hand the sandbox back to developers or UAT testers.


What does a sandbox refresh do to an Agentforce agent?

A refresh replaces the sandbox with a new copy of its source production org. Anything built only in the sandbox, and never deployed to production or saved somewhere else, is gone. For most Salesforce metadata, the copied configuration works as soon as the sandbox is activated.


An Agentforce agent is different because it is a solution made of many parts, not a single configuration item. A working agent can depend on:

  • Agent definitions and topics (or subagents)

  • Actions, flows and Apex

  • Prompt templates

  • Users, profiles, permission sets and licenses

  • Knowledge and Data 360/Data Cloud grounding, including data libraries and search indexes

  • Integrations, named credentials and authentication

  • Messaging, Experience Cloud and other channel configuration, plus Omni-Channel or escalation routing


Some of these behave like ordinary Salesforce metadata. Others are tied to the org they run in. So the sandbox can refresh successfully while the agent inside it still needs configuration and testing before it works.


Why can an agent fail after a refresh even when its metadata is there?

An agent depends on its own configuration and on services in the org where it runs. After a refresh, check these five areas:

  • Feature enablement. Agentforce, Einstein, Bots and Data 360/Data Cloud must be enabled and ready in the refreshed sandbox.

  • Identity and access. The agent execution user, licenses, profiles, permission sets, object access and data-space access must all be valid in the new environment.

  • Connections. External connections, credentials, channels, routing and data libraries may need to be set up again or revalidated.

  • Dependencies. Agent metadata has historically been spread across several metadata types. A missing flow, Apex class, prompt template or action can stop the agent from deploying or activating.

  • Service connection. A newly refreshed sandbox can need Agentforce services to reconnect. Salesforce documents cases where turning Agentforce off and back on fixes Agent Builder connection errors after a refresh.


The post-refresh runbook for Agentforce

The exact steps depend on the agent type and architecture. These six (6) steps, in this order, are the baseline we use on most Agentforce implementations.


Before the refresh: inventory and save the agent

List the agent and everything it depends on: the active agent and version, topics or subagents, actions, flows, Apex, prompt templates, data libraries and grounding, channels, routing, permissions, integrations, credentials, and any environment-specific IDs. Keep the deployable parts in source control, or in DevOps Center where it is supported.

Refresh and activate the sandbox

Run the standard refresh and activation. The refreshed sandbox is a new copy of production, so don't expect sandbox-only work that was never promoted or saved elsewhere to still be there.

Re-establish platform prerequisites

Confirm that Einstein, Bots, Agentforce and the Data 360/Data Cloud capabilities you need are enabled. Check the agent execution user and its licenses and permissions. If Agent Builder fails to load after the refresh, follow Salesforce's guidance for re-establishing the Agentforce service connection.

Restore or deploy the agent configuration

Deploy with supported metadata deployment, Salesforce CLI or DevOps Center, depending on the agent type. Deploy all referenced dependencies together. Some specialized agents have different deployment limits and may need to be configured directly in the target org.

Reconnect environment-specific services

Re-authenticate external systems and named connections. Validate data libraries, search indexes, data-space access, Messaging and Experience Cloud channels, Omni-Channel or escalation routing, and any other configuration specific to the target org.

Validate before returning the sandbox to users

Open the agent in Agentforce Builder and preview representative conversations. Check that the right topic or subagent is selected and that actions run, confirm grounding and permissions, and test escalation and handoff to a human. Run regression tests in Agentforce Testing Center where it applies. Activate the agent only after it behaves as expected.


How long does it take to restore an agent after a refresh?

It depends more on how complex the agent is than on the refresh itself. A simple agent with a few native actions can be ready soon after the prerequisites are back in place.

1

Complex flows or human handoff

2

Data 360/Data Cloud grounding

3

External integrations

4

Experience Cloud or Messaging channels


An agent that uses Data 360/Data Cloud grounding, external integrations, Experience Cloud or Messaging channels, complex flows or human handoff needs its own post-refresh validation window in the environment plan.


Treat agent validation as a gate. The sandbox goes back to development or UAT teams only after the agent passes, the same way you would hold a sandbox until its integrations are confirmed after a refresh.


Does Winter '27 remove the post-refresh work?

It makes deployment easier, but it doesn't remove the post-refresh steps. In Winter '27 (API version 68.0), Salesforce introduced the AiAgentDefinition and AiAgentDefinitionVersion metadata types. Salesforce states that the CLI can retrieve an agent and its dependencies automatically with these types, which cuts much of the manual dependency tracking earlier versions required.


The Salesforce documentation we reviewed does not give a date when a sandbox refresh will need no Agentforce-specific work afterward. Feature enablement, identities, data services and external connections are tied to the environment, so keep them in your refresh plan.


About Truffle Consulting

Truffle Consulting is a Salesforce implementation partner that designs, builds and supports Agentforce agents. If you're planning sandbox refreshes for an org that runs Agentforce, talk to our team.





Frequently asked questions

Does Salesforce support Agentforce in sandboxes?

Yes. Salesforce supports building and testing agents in sandboxes and provides Agentforce Testing Center there. The point to plan for is that a refreshed sandbox may need Agentforce-specific readiness and configuration steps before the agent works again.

Not necessarily. For supported agent types, Salesforce provides metadata-based deployment, and Winter '27 simplifies it further. The right approach depends on the agent type, which builder generation it was built in, the API version and its dependencies.

The agent may depend on things in the target org that copying metadata doesn't provide: feature enablement, execution-user permissions, Data 360/Data Cloud readiness, credentials, connections, channels or referenced components.

You can't count on it. The safer approach is to treat Agentforce validation as a post-refresh gate, similar to validating integrations after a refresh, with additional AI and data dependencies to check.

When Salesforce explicitly documents that your agent type and all of its environment dependencies are preserved or automatically restored by the refresh. Until then, keep the readiness checks, even as metadata deployment gets easier.





Comments


bottom of page