Agentforce Architecture That Delivers Business Value

Practical guidance for business leaders, architects, and delivery teams designing trusted Agentforce solutions that perform in production.

Explore the guides

Explore featured docs.

Trust Boundaries

Define the agent mandate, execution context, least-privilege permissions, grounding, and knowledge reach.

Architecture Guide

Control Mechanisms

Move hard rules out of prompts and into action filters, permissions, Flow, Apex, and human gates.

Developer Guide

Observability Layers

Prove behavior before launch, trace it after launch, and improve the system from operational evidence.

Implementation Guide

The Monday Checklist

Run nine concrete trust, control, and observability checks before calling an agent production-ready.

Architecture Checklist

Popular Agentforce architecture guides.

Define the Agent Guardrails

Use the People, Business, Technology, and Data framework to document operational boundaries.

Agentforce guardrails framework covering people, business, technology, and data

Agentforce Trust Patterns

Understand platform protections, custom boundaries, and deliberate human handoffs.

Agentforce trust pattern combining agent mandate, topics and instructions, and permitted actions

Variables and Action Filters

Hide actions from the model when deterministic business conditions are not satisfied.

Action filter configuration in Agentforce Builder

Conditional Logic for Agent Context

Route prompts and action paths from explicit variables and evaluated conditions.

Conditional statement configured in the Agentforce canvas

Agentforce Testing Strategy

Move from representative scenarios to evaluation criteria, human validation, and iteration.

Agentforce test suite criteria evaluated at runtime

Session Tracing

Inspect turn-by-turn interactions, actions, inputs, outputs, errors, and final responses.

Pillar 1 · Trust — what it may access

Trust boundaries: trust is an architecture, not a promise.

An agent is autonomous — it acts on real business data, on someone's behalf, inside your org or in customer channels. That autonomy is exactly why trust cannot be a slogan or a well-worded prompt. It has to be an enforceable boundary that answers concrete risks: sensitive-data leakage, loss of human oversight, and automation bias — users over-trusting an answer because it sounds authoritative.

Least privilege, accumulated reach, and the mandate

Start with the oldest rule in security: the agent user begins with a limited set of permissions, and every capability it has was granted on purpose. The failure mode is rarely one bad decision — access accumulates. Each grant is legitimate on its own, until one day the union of many reasonable grants lets the agent reach data nobody meant to expose. Reach is the sum of grants nobody ever reviewed together.

The antidote is the mandate: a written, versioned delegation-of-authority document for a non-human worker. For the board, it reads simply — a job description the agent physically cannot exceed.

The record boundary: enforced by the security model you already run

The boundary is not a new access engine. It is the Salesforce security model — permissions, field-level security, and sharing — and the agent inherits it rather than inventing one. Trust Layer secure retrieval respects those settings end to end, so the agent (and the LLM behind it) never sees data the running user is not authorized to access. The one decision people get wrong is the execution context:

Employee-facing agents run as the logged-in user. Licenses, permissions, field-level security, and sharing already bind the agent, because the person's own context scopes it.
External-facing agents run as one dedicated Agent User. There the permission set is the entire boundary. Pick the wrong context and least privilege silently becomes over-privilege.
The unauthenticated trap: in anonymous sessions, record visibility resolves against internal org-wide defaults. Scope it with filters and variables at the subagent and action level.

Salesforce's own access-control standards complete the picture: strict need-to-know access to AI models and services, a dedicated service-user context with granular permissions for critical actions, and alerting plus regular access audits to catch unauthorized use. One layer up, Data 360 governance extends the same boundary to the whole data estate — attribute-based access control keyed off metadata tags, with row-, field-, and object-level security that propagates along lineage. Treat it as a distinct layer from the agent's runtime permissions, not as the retriever. And one honest operational note: boundary changes ship through your deployment process, so re-verify that permissions and the right flow versions arrived intact before production.

The knowledge boundary: grounding is a trust decision

Models are born generalists — they do not know your current business. Grounding fixes that: verified, domain-specific content is added to the prompt so the agent answers from your sources, not the model's generic training. Accuracy — Salesforce's first trust principle — is really a grounding outcome.

The Agentforce Data Library is the knowledge-supply layer: knowledge articles, uploaded files, websites, and transcripts are ingested, chunked into self-contained passages (LLMs have token limits), indexed for fast retrieval, and served through a retriever — with the underlying Data 360 and Prompt Builder plumbing automated for you. Two properties make this a boundary rather than a content chore:

Each library's retriever decides which data a given tool can reach. Scoping the retriever is scoping the agent's knowledge.
Retrieval respects the user's permissions end to end, so grounding never widens the record boundary — the two boundaries compose instead of fighting.

The trust property that matters most: the agent can only be as accurate as the content it retrieves, so keeping the knowledge base complete, current, and well-chunked is a trust activity. And because data masking is currently disabled for agents, do not ground an agent in raw PII you would not want surfaced — scope the library to what the job needs.

The platform baseline and the auditor

Underneath your configuration, the Agentforce Trust Layer (formerly the Einstein Trust Layer) secures every model interaction: secure data retrieval, dynamic grounding, injection defense on the prompt journey, and zero data retention, toxicity detection, and an audit trail on the response journey. That is the floor you inherit — the architecture on top of it is yours. To make the boundary governable, define an acceptable-use policy (no legal or consequential decision without a human final call), inherit the regulatory floor of your industry and geography, and run adversarial testing — red-teaming for injection, toxicity, bias, and misuse — repeated after every change. Remember that grounding can make a wrong answer sound more authoritative; test for exactly that.

A trust boundary is a scope contract: least privilege granted on purpose, reach reviewed as a whole, and knowledge scoped by retrievers that respect your permission model.

Sources

Trailhead modules and Salesforce documentation behind this guide.

Pillar 2 · Control — what it may do

Control mechanisms: a prompt is not a security control.

Control is deciding in advance — through enforceable mechanisms, not good intentions — what an agent may do, on whose data, and when it must stop and hand off to a human. Instructions steer the model probabilistically; mechanisms enforce deterministically. A mature agent uses both, in layers, and knows which layer carries which responsibility.

The four layers of control

Every rule you write lives on one of four layers, and the layer — not the wording — decides whether the rule is a request or a guarantee:

Behavioral — Subagents (formerly Topics) and Agent Script: natural-language guidance. The model is steered, not constrained.
Deterministic — variables, conditional logic, and action filters: your rules and data drive the agent's path. A condition holds, or it doesn't.
Platform — permissions, sharing, and field-level security on the Agent User: a hard boundary the agent physically cannot cross.
Organizational — risk reviews, escalation policy, documentation, audits: the human process around the technology.

Why the rung is everything: a service agent can look up an order, initiate a return, and authorize a credit — three actions, each fine on its own, never approved as a chain. If the only thing stopping a fifth credit is a sentence in a prompt, that control is one persuasive message away from failure. Your people have approval limits; a non-human worker needs the same, enforced rather than requested.

From instruction to rule — and the gap in between

The first control surface is natural language. Subagents define the range of jobs; Agent Script tells the agent how to decide, and Salesforce recommends explicit rules — "Always…", "Never…", "If x, then y…". Two patterns carry the most weight: scope restriction (what the agent may not do — never use data an action didn't provide, never show record IDs to customers) and escalation triggers (the keywords, sentiment, or requests that hand off to a human, with a summary so the customer never repeats themselves). Powerful — and still soft, because the model interprets it.

The path turns deterministic with variables and conditional logic. Variables hold session-scoped state any subagent can read and set — a customer's lifetime value, a flag for whether a credit was already issued. Conditional logic then sends a different prompt per state, so the platform resolves the branch before the model sees anything, instead of one overloaded prompt engineered for every case. In Salesforce's own loyalty walkthrough, that handles the tiers cleanly: Platinum customers get a $500 credit, Gold get $250. But here is the gap — the credit action stays visible to the model on every branch, so a determined customer simply keeps asking. Deterministic path, still-reachable action. Nothing structural has said no yet.

What hard actually looks like: the enforced write path

Action filtering is the flagship hard control. An availability filter makes an action exist for the model only when a Boolean over your variables is true — for the credit, issued-credit is false AND lifetime value is at least 25,000. When it evaluates false, the action is not greyed out — it is removed from the set the model receives. The model cannot call what it cannot see, so the refund chain becomes impossible, not unlikely. One caveat: base the condition on record data, not a session-scoped flag, or a new session resets it. A follow-up action sets the flag to true after the first credit.
Minimal write permissions form the write boundary. Agents cannot change anything without an action, so the write path is the control point. Before the loyalty agent could issue credits, its Agent User needed Read and Create on the credit object with edit limited to exactly two fields — amount and contact. Nothing more; custom fields stay invisible until granted on purpose.
The action is the only write path. Side effects run through agent-ready flows: only Autolaunched (No Trigger) flows qualify; every flow needs an input and an output, including an error output, so failure is a controlled response rather than improvisation; names and descriptions become instructions the agent reasons over, so write them as directives; never overfeed — choose specific fields; build many small single-task flows.

Be precise about Agent Script: it resolves deterministically, but what a chosen branch produces is still prompt text the model interprets — soft. Only the filter changes whether the action exists at all. And underneath it all sits the platform baseline: secure retrieval, a secure gateway, zero retention, toxicity detection, audit. The platform secures the model; your filters and permissions govern the business.

Where to draw the line is a business call

Building a gate is configuration; deciding where to put it is judgment, and it starts before any config. Salesforce frames agent risk across four categories — People (distrust or manipulation), Business (scope misfit, broken escalation paths), Technology (hallucination, unauditable variability, latency), Data (permissions, privacy, residency, bias). Run that conversation on a whiteboard, not in production; turn each risk into a named guardrail; document it per use case for the audit you will eventually face. Then the sort: gate the irreversible (money, contracts, deletions), escalate the unusual (low confidence, an atypical amount, negative sentiment — and escalation itself can be a filterable action), and let the reversible-and-usual run — that is why you built the agent.

The hard rule — "the agent may grant up to a 10% discount" — belongs in a Flow, in Apex, or a validation rule, not in a prompt: the agent chooses to use the action, the action enforces the value. And the honest trade-off: over-gate and you manufacture rubber-stamping; under-gate and you get the refund. Gate placement is a risk-appetite decision owned by whoever owns the business limits — not by whoever built the agent.

The strongest control is the action the model never sees: availability filters, minimal write permissions, and single-purpose flows turn soft instructions into guarantees.

Sources

Trailhead modules and Salesforce documentation behind this guide.

Pillar 3 · Observability — what it did

Observability layers: "the agent decided" is not a defense.

An agent hides failure better than any system you have run, because it always answers. It does not throw an exception on stale input — it answers fluently and wrongly, for weeks, with no errors and no complaints. And because every run takes a different path, the recorded trace is the only defense you have. What you can defend in a compliance review is the record of what it did — the steps it took and the data it used, not the model's private reasoning.

Evidence in two timeframes: the lab and the field

You need the record in two places, not one. Before the agent ships, you prove it on test cases — in the lab. After it ships, you watch it on real traffic — in the field. Same question both times: what did it actually do. Testing is the pre-deploy verification that your trust boundaries and control mechanisms actually hold; monitoring is the start of the next iteration.

In the lab: Testing Center, three pass rates

Testing Center batch-runs your cases — each an utterance with an expected subagent, expected actions, and an expected response — and reports three separate pass rates. The separation is the point: in Salesforce's own example, routing passed 100% while actions passed only 65%. If you had measured only the final response, the failing action would have been invisible. Generate hundreds of cases from your own subagents and actions, score failures by severity (one critical miss outweighs a hundred cosmetic ones), and remember that testing a non-deterministic system is probabilistic — you set the passing bar, and you set it against how well a good person does the job. Builder preview and Session Tracing let you inspect a single run — variables before and after every step — before it ever reaches production.

In the field: traces and seven dimensions

Sessions and Intents gives you per-session drill-down: the full conversation plus a Trace — an ordered record of every processing step (subagent identification and routing, retrievals, variable updates, action execution, response generation), each with status and timing. Agentforce Session Tracing, which requires Data 360, goes deeper into reasoning-engine executions and prompt and gateway inputs and outputs. This is what the agent did and how long it took — not its chain of thought.

Agent Analytics then measures the fleet across seven dimensions — Effectiveness, Usage, Quality, Health, Trust, User Satisfaction, and Voice — aggregating everything into a unified Data 360 data model under one session ID. The most actionable field is Quality Score Reasoning: an evaluator's explanation of why a response scored the way it did. Classify every session outcome — Deflected, Escalated, Abandoned, Ambiguous — and track it against explicit goals, for example >80% deflection, <25% escalation, <5% abandonment.

Drift, baselines, and the discipline of "good"

The classic failure is drift: an upstream integration goes stale, the pipeline stays green, and the agent keeps grounding on data that no longer reflects reality. There is no automatic drift detector — you baseline the dimensions early and watch for the pattern to move. A rising share of abandons or escalations is a number, not an anecdote, and it is a review trigger the organization owns. Two working rules: watch the steps, not just the answer — subagent, action, and response score separately, so routing can pass while an action silently never runs; and test the reproducible, monitor the probabilistic — Flow and Apex actions are deterministic, so assert them; the reasoning is not, so the scores watch it. Define the KPIs up front, roll out in stages (pilot group → one channel → wider), and treat every monitor alert as the start of the next test cycle: drill, fix, retest, redeploy.

Prove it in the lab, watch it in the field, and turn tracing on from day one — not the day after an incident.

Sources

Trailhead modules and Salesforce documentation behind this guide.