Not verified hands-on. This article was written from primary documentation rather than reproduced in an org, so it carries no tested-release badge. If you run it and something differs, say so in the comments and it gets tested and corrected.

The short version: the agent definition, its topics and its actions are metadata and move through a normal deployment. Almost everything that makes the agent work in the source org is not, or is metadata that points at something with a different ID in the target. Expect to rebuild connections, reassign permissions, re-point channel configuration and re-verify grounding by hand, and expect the agent to deploy successfully while doing nothing useful until you do.

What moves

Broadly, the definitional parts. The agent and its versions, topic definitions with their instructions and classification descriptions, the action definitions that wire an agent to a flow, an Apex class or a prompt template, and the prompt templates themselves.

The supporting metadata moves as normal too: flows, Apex classes, custom objects and fields, permission sets. If your actions are backed by flows and Apex you already know how to deploy, that part is ordinary.

Exact metadata type names and what each one carries have changed across releases, and the authoring format for agents has itself moved. Check the current metadata coverage documentation for your release rather than trusting a component list from an older article, including this one.

What does not move, or moves broken

This list is where the deployment day goes.

  • Activation state. A deployed agent generally arrives inactive. Activating in production is a deliberate act, and that is correct behaviour rather than a bug.
  • Channel configuration. Messaging channels, deployments, embedded service configuration and the connection between a channel and the agent. Per-environment by nature, since the endpoints and keys differ.
  • Anything with an environment-specific ID. Queues, users, record types, knowledge data categories, external credentials. A reference that resolves in the source org may not exist in the target under the same identity.
  • Grounding content. Knowledge articles are data. So are the records your agent reads in testing. A perfect metadata deployment into an org with an empty knowledge base produces an agent that answers nothing.
  • Data Cloud configuration, where used. Its own deployment story with its own constraints.
  • Permission set assignments. The sets deploy. Who has them does not.
  • Testing artefacts. Whether test definitions and results move depends on the tooling version. Verify rather than assume your evaluation set travels with the agent.

The sequence that works

Deploy the supporting layer first, then the agent, then reconnect by hand.

  1. Objects, fields, permission sets, flows, Apex classes. Verify the flows run in the target org before anything else, because an action failing at runtime in production looks like an agent problem and is not.
  2. Prompt templates, and check each one resolves against a real record in the target. Merge fields referencing something absent fail quietly.
  3. The agent, its topics and its actions.
  4. Manual reconnection: channel wiring, queue references, credentials, data categories.
  5. Assign permission sets to real users.
  6. Load or verify grounding content.
  7. Run the full test set against the target org. Not a smoke test.
  8. Activate.

Step seven is the one people skip because the deployment reported success. Deployment success means the metadata was accepted. It says nothing about whether the agent behaves the same, and it will not behave identically, because the data underneath is different.

Source control and drift

Agent configuration is edited in a builder, which means it drifts in whatever org people are editing. Treat the agent the same as any other metadata: retrieve it, commit it, and make changes in a way you can review.

Instruction text deserves particular attention in review. A one-word change to a topic description alters classification behaviour across the whole agent, and it is invisible in a diff summary that only lists changed files. Read the instruction diffs properly.

# Retrieve the agent's metadata into source
sf project retrieve start --metadata Bot:MyServiceAgent

# Deploy to the target org
sf project deploy start --source-dir force-app --target-org uat

Metadata type names vary by release and authoring format, so confirm the right type against the metadata coverage report before scripting a pipeline around a name you half remember.

Frequently asked

Can I deploy an active agent straight to production? Technically the metadata arrives, and activation should still be a separate, deliberate step with a named owner. Treat it like enabling a trigger.

Will it behave the same in production? No. Different data, different volumes, different users. Behaviour is data-dependent and the data is not the same.

Do I need a full sandbox? For realistic testing, something with representative data and real knowledge content. A developer sandbox tells you the configuration deploys, not that the agent works.

How do we handle hotfixes to instructions? Same as any production change: through the pipeline, with the regression set rerun. Editing instructions directly in production is tempting because it is easy, and it is how the tested version stops matching the running one.