Agentforce and Data Cloud Architecture: The Reference Design

Most Agentforce demonstrations work. Most Agentforce deployments stall. The difference is almost never the model or the prompt. It is architecture: whether the data underneath the agent is unified, whether the actions it needs already exist and are trustworthy, and whether anyone decided what the agent is not allowed to do. This is the reference design we use, the run time flow behind it, and the decisions you need to make before anybody opens Agentforce Builder.

Why agent projects stall

Across assessments, the same four causes come up. None of them is an AI problem.

• The data is in pieces. The agent is asked about a customer who exists as four records across three systems. It answers confidently from one of them.
• The actions do not exist. An agent can only do what you give it. If there is no reliable, tested way to issue a refund, the agent cannot issue refunds, no matter how well it understands the request.
• Nobody defined the boundary. Without explicit limits, the agent attempts things it should escalate, and everyone loses confidence after the first bad transcript.
• Nobody defined success. No deflection target, no measurement, so the project cannot be shown to have worked and quietly loses its sponsor.

The five layers of a working agent

Every agent that survives production has these five layers. Build them bottom up, because each one depends on the one below.

The temptation is to start at layer 4, because that is the layer that looks like AI. Starting there is how you get a demonstration that cannot be deployed.

What actually happens at run time

Understanding the request path makes the design decisions obvious. When a user asks an agent something:

1. The utterance arrives with session context: who is asking, from which channel, and which record they are on.
2. The planner classifies the request against the subagents available to it. Each subagent is a category of related work with its own instructions and its own set of actions.
3. The planner selects actions from that subagent, using each action's description to decide what fits. This is why action descriptions are functional design, not documentation.
4. Grounding happens. Retrievers query indexed content, prompt templates merge in record data, and the results are assembled into the prompt.
5. The prompt passes through the trust layer, where policy checks apply before it reaches the model.
6. The model responds, either with an answer or with a decision to call another action.
7. Actions execute as the running user, subject to that user's permissions and sharing.
8. The loop repeats until the goal is met or the agent escalates.
9. Everything is logged for review.

Two consequences worth internalising. First, permissions are enforced at execution, so the agent's running user is a security design decision, not an afterthought. Second, the planner only knows what your descriptions tell it, so vague action and subagent descriptions produce an agent that picks the wrong tool and looks stupid.

Layer 1: The data foundation

This is where most of the real work is, and it is unglamorous.

Decide what Data 360 is for

Salesforce Data Cloud is now branded Data 360. You do not need it for every agent. Be honest about which case you are in:

• You do not need it if everything the agent reasons over already lives in your Salesforce org as clean CRM data. Ground on the records directly.
• You need it when the truth is spread across systems, when you need to unify a person across channels, when you want to ground on unstructured documents, or when you want to query a warehouse without copying the data.

The pipeline, in order

1. Data streams bring data in from a source.
2. Data Lake Objects hold it as ingested, close to its original shape.
3. Mapping to Data Model Objects harmonises it into a shared model, so "customer" from three systems becomes one shape.
4. Identity resolution matches and reconciles records into a unified profile. This is the step that decides whether your agent talks to one person or three fragments of one person.
5. Calculated insights compute the metrics you want available, such as lifetime value or engagement recency.
6. Data spaces partition all of it by brand, region, or business unit, which is also a security boundary.

Zero copy federation deserves a specific mention. If your analytics already live in Snowflake, BigQuery, Databricks, or Redshift, you can query them without physically moving the data. That changes the economics of grounding on warehouse data, and it removes a synchronisation problem you would otherwise own forever.

Identity resolution is the highest leverage and most misunderstood step, so we cover the tuning in Data Cloud identity resolution.

Layer 2: Grounding, and choosing between three routes

Grounding is how facts reach the prompt. There are three routes, and picking the wrong one is a common and expensive mistake.

The practical rule: start with a data library if your content is one tidy source and you want to prove value in days. Move to custom retrievers when you need more than one source, when freshness matters, or when the answers need to reflect a unified profile rather than a document.

Note also that ensemble retrievers let you combine sources, and data graphs pre-join related structured data so the agent gets a whole picture in one retrieval instead of several. With Data Cloud One connections, retrievers created in a home org can be used from companion orgs, which matters for multi-org estates.

The full setup walkthrough is in grounding Agentforce in your own documents.

Layer 3: Actions

Actions are the agent's hands. This layer is ordinary Salesforce engineering, which is good news, because you already know how to do it well.

• Flow for most record work: create, update, look up, orchestrate a few steps. Start here.
• Apex for logic Flow cannot express cleanly, complex callouts, or heavy data work.
• Prompt templates when the output is generated text: a summary, a draft reply, an explanation.
• External services and APIs when the system of record is elsewhere.

Three rules that matter more than the choice of type:

1. Actions must be idempotent or guarded. A planner can retry. If a retry issues a second refund, that is your bug, not the model's.
2. Actions must fail informatively. "Something went wrong" leaves the agent unable to decide what to do next. Return a reason it can act on.
3. Inputs and outputs must be tightly typed and described. The planner maps conversation to parameters using your descriptions.

Detail on building them, including how to write descriptions the planner can actually use, is in Agentforce custom actions with Flow, Apex, and prompt templates.

Layer 4: Reasoning and orchestration

This layer used to be described as topics and actions. The current model is more explicit, and understanding the metadata makes it concrete:

• AiAuthoringBundle holds the agent blueprint, including its Agent Script. This is what you edit, in Agentforce Builder or in VS Code.
• GenAiPlannerBundle is the reasoning engine. One per agent. It holds the subagent map, the orchestration graph, instructions, and the actions available.
• GenAiPlugin represents a subagent, meaning a category of actions related to one job to be done.
• GenAiFunction represents a single action.
• Bot and BotVersion appear once an agent version is committed. A draft is the authoring bundle alone.

Design guidance for this layer:

• Scope subagents narrowly. One job each. A subagent that covers billing, returns, and technical support will misroute, because the planner has no basis to choose.
• Write instructions as policy, not as prose. "Always verify identity before discussing account balances" is usable. "Be helpful and professional" is decoration.
• State what the agent must not do, explicitly. Negative instructions do more for reliability than positive ones.
• Give each subagent an escalation path, and make escalation an acceptable outcome rather than a failure. Agents that cannot escalate improvise.

On deployment, agents are metadata and move between orgs like anything else. There is a convenient Agent pseudo type in the CLI that gathers the related components, for example sf project deploy start --metadata Agent:My_Agent. One thing to know before you plan a release pipeline: deploying agent metadata does not deploy the Apex classes and Flows behind its actions, so those must be in the same deployment. Avoid wildcards on Apex, Flow, and prompt template types, because pulling everything in the org leads to very long deployments and timeouts.

Layer 5: Trust, guardrails, and observability

The Einstein Trust Layer sits between your prompt and the model, providing toxicity detection on generated output, an audit trail of prompts and responses, and zero data retention agreements with the model providers. It is infrastructure, and it is not a substitute for your own design.

What you still own:

• The running user's permissions. Actions execute with real access. Create a dedicated user with the minimum object, field, and record access the agent needs. Never reuse an administrator.
• Human in the loop, deliberately placed. Decide which actions require confirmation. Anything that moves money, changes entitlement, or sends external communication is a candidate.
• Testing. Agentforce Testing Center lets you run utterance sets against an agent and check the outcome. Build your test set from real transcripts, including the awkward ones, and re-run it on every change. This is the closest thing to regression testing for an agent and it is routinely skipped.
• Observability. Review transcripts weekly at first. Watch for wrong subagent selection, actions failing silently, and the questions the agent cannot handle. That last list is your roadmap.
• Measurement. Pick the metric before launch: deflection rate, resolution time, conversion. An agent without a number is an agent nobody can defend at budget time.

Seven architecture decisions to make up front

1. Do you need Data 360 at all? If the answer is unclear, you probably do not yet. Prove value grounding on CRM data first.
2. Who is the running user, and what can it touch? Write the permission set before the agent.
3. Which grounding route per use case? Data library, custom retriever, or direct record access. Mixing them is fine; choosing by accident is not.
4. What are the subagent boundaries? List the jobs to be done, then draw one subagent per job.
5. What is explicitly out of scope? Write the list down and put it in the instructions. This is the most valuable document in the project.
6. Where does a human confirm? Decide per action, not per agent.
7. What is the success metric and its baseline? Measure the baseline before go-live or you can never prove improvement.

Anti-patterns we keep seeing

• The everything agent. One agent, twenty subagents, launched at once. It misroutes, nobody can debug it, and confidence collapses. Ship one narrow agent, prove it, expand.
• Grounding on a mess. Pointing a retriever at an unmaintained document library. The agent faithfully repeats a policy that was superseded in 2023.
• Admin as running user. Convenient in a sandbox, indefensible in production.
• No escalation path. The agent has no legitimate exit, so it invents an answer.
• Actions built for the agent only. Build them as reusable Flows and Apex that humans and the agent both use. You get one tested path instead of two.
• Testing by conversation. Three people chatting with the agent is not a test suite. Build the utterance set.
• Data 360 as the first purchase. Buying a data platform before you have a scoped use case usually produces an unused data platform.

Almost every one of these is a decision that could have been made in a design workshop and was instead discovered in production.

Frequently asked questions