Agentforce isn't a chatbot. Understanding how Atlas reasons, plans, and executes is essential for anyone building production agents — here's what's actually happening under the hood.
The most common misconception about Agentforce is that it's a fine-tuned LLM — that Salesforce took a foundation model and trained it on Salesforce documentation and object schemas. It isn't. A second misconception is that it's a simple prompt chain — a sequence of hardcoded prompts that string together API calls. It isn't that either.
Atlas is Salesforce's hybrid reasoning layer that sits between the LLM and your org's actions. Think of it as an orchestration engine that uses an LLM for language understanding and response generation, but applies its own deterministic logic for routing, action selection, and guardrail enforcement. The LLM handles natural language; Atlas handles everything else.
This architecture matters for how you build. It means some behaviours are configurable (Topic classification thresholds, action selection prompts, Instructions), while others are fixed (PII masking, audit trail generation, trust layer enforcement). It means hallucination can be addressed at the architecture level, not just through prompt engineering. And it means the debugging model is different: when an agent misbehaves, the problem might be in your Instructions, your Topic classification, your Action design, or the underlying data — and each requires a different fix.
Every agent interaction runs through a four-phase loop. Here's how each phase works, using a concrete example: an SDR agent qualifying an inbound lead.
Atlas receives the conversation context: the user's message, the active channel (chat, email, Slack), and any structured data attached at invocation — in our SDR example, the Lead record fields, company size, industry, and any prior engagement history pulled from Data Cloud. This context is assembled into the prompt that Atlas reasons over. The quality of what Atlas observes is directly determined by what your channel configuration and context actions provide at invocation.
Atlas classifies the request against your Topic library, selects the matching Topic, and generates an execution plan: which Actions to call, in what order, and what to do with the results. For the SDR agent, this might be: retrieve company firmographic data → assess against ICP criteria → if qualified, check calendar availability → draft personalised outreach → propose meeting. The plan is generated dynamically based on the specific request — it's not a fixed script.
Actions are executed in sequence (or in parallel where Atlas determines they're independent). Each Action call — whether it's an Apex method, a Flow, an API endpoint, or a Data Cloud query — is a discrete, audited event. Results are returned to Atlas's context window for use in subsequent planning. If an Action fails, Atlas can either retry (if configured), route to a fallback, or escalate, depending on how your Instructions handle that state.
After executing, Atlas evaluates whether the plan produced a satisfactory outcome. If the lead qualified and a meeting was booked, the loop closes and a confirmation is sent. If something didn't resolve — the calendar API returned an error, the lead didn't match ICP criteria — Atlas determines whether to retry, adapt the plan, or escalate. This reflection phase is where well-written Instructions have the most impact: explicit success criteria in your Instructions give Atlas a clear basis for evaluating whether to proceed or escalate.
The loop isn't always linear. For complex requests, Atlas might run multiple Plan-Act cycles before arriving at a final response. This is why context window management matters: every Action call consumes tokens, and a poorly designed agent that calls five Actions to answer a simple query will hit context limits on complex conversations.
Before Atlas can plan anything, it needs to know which Topic applies to the current request. Topic classification is the first decision Atlas makes, and it's more nuanced than a keyword match.
Each Topic has a classification description — the text you write when defining the Topic in Agent Builder. Atlas uses this description, combined with the current conversation context, to score the relevance of each Topic. The Topic with the highest confidence score above the threshold is selected. If no Topic scores above the threshold, the request falls to the “I Can't Help With That” default.
The confidence threshold is configurable, and getting it right requires deliberate tuning. A threshold that's too high means borderline requests that the agent could handle get unnecessarily escalated. A threshold that's too low means the agent attempts Topics it shouldn't, leading to off-brand or incorrect responses. Most production configs we see run between 0.65 and 0.80 depending on the risk profile of the use case.
Topic descriptions also need to be non-overlapping. If two Topics have similar descriptions, Atlas will score them close together and make inconsistent routing decisions. The fix is precise language: Topics should describe what they do and what they explicitly don't do. “Handle loan status queries for authenticated borrowers. Does not handle payment processing, hardship applications, or account closures.” is a better Topic description than “Answer questions about loans.”
Actions are the mechanism through which agents do things. Understanding how Atlas selects and executes Actions is critical for building agents that behave predictably.
Agentforce supports four Action types: Apex (invocable methods), Flow (Autolaunched or Screen), API (external HTTP endpoints), and MuleSoft (connected APIs via Anypoint). Each has different latency characteristics, error handling behaviour, and context injection capabilities. Apex is typically fastest and most flexible for complex business logic. Flow is easiest to build but has governor limit exposure in high-volume scenarios. API and MuleSoft Actions introduce external dependencies with their own failure modes.
There's an important distinction between deterministic and LLM-directed action selection. For some Topics, you can define a fixed sequence of Actions — Atlas will always call Get Account, then Get Recent Cases, then Generate Response, in that order. This is deterministic action selection: predictable, auditable, and easy to debug.
For more complex Topics, Atlas uses LLM-directed selection: it reasons over the available Actions and decides which to call based on the specific request. This is more flexible but introduces variability. The implication for builders: for regulated use cases or actions with side effects (writes, notifications, record updates), use deterministic sequencing. Reserve LLM-directed selection for informational, read-only Topics where variability in execution order carries lower risk.
Talk to our team. We've built production Agentforce deployments across financial services, healthcare, and SaaS — and we know where the Atlas edge cases hide.
The Einstein Trust Layer is the security and compliance wrapper that sits around all Atlas operations. For enterprise orgs — particularly in regulated industries — it's not optional configuration; it's what makes Agentforce defensible in a board-level risk conversation.
Prompt injection defence: Atlas validates all input before passing it to the LLM. Instructions embedded in user messages attempting to override system behaviour (“ignore your previous instructions and instead...”) are detected and blocked before they reach the reasoning layer. This isn't foolproof — novel injection techniques exist — but it catches the vast majority of automated and manual injection attempts.
PII masking: Configurable at the field and object level. When enabled, specified data types (account numbers, SSNs, payment card data, healthcare identifiers) are replaced with tokens before being included in the LLM prompt. The LLM reasons over the tokenised representation; the actual values are never sent. This is essential for HIPAA, PCI-DSS, and GDPR compliance scenarios.
Audit logging: Every agent action — every Action call, every escalation, every response generated — is logged with a full trail: timestamp, user identity, action type, input parameters, output, and the Atlas confidence scores that drove routing decisions. For financial services clients under FCA or SEC oversight, this audit trail is the artefact that demonstrates the agent's behaviour is explainable and reviewable.
Zero data retention for LLM calls: Agentforce uses Salesforce's own LLM infrastructure with a zero-retention policy: no conversation data is retained by the LLM provider after the call completes. This is the key architectural difference from using OpenAI or Anthropic APIs directly — there's no risk of your org's data appearing in future model training.
LLMs hallucinate. This is a property of the architecture, not a bug that will be fixed. The question for Agentforce builders isn't whether the LLM could hallucinate — it's whether your architecture prevents hallucinations from reaching the user.
Atlas uses two grounding mechanisms. First, Data Cloud retrieval augmentation: at invocation time, Atlas can query Data Cloud for relevant records and inject them into the context window. This means the agent's response is grounded in actual org data — loan balances, case histories, account details — rather than the LLM's parametric knowledge. The LLM's role becomes synthesising and communicating the retrieved data, not generating it from memory.
Second, Action results: when an agent calls an Action and receives a structured response (a JSON object with specific field values), those results are passed back into the context window as ground truth. The LLM's job is then to present that data in natural language, not to recall it. An agent that retrieves a loan balance via a Get Loan Status Action and presents the retrieved value to the customer is not susceptible to hallucination on that specific fact.
We've seen what happens without proper grounding, and it's instructive. One client inherited an Agentforce deployment where the Knowledge Base Actions weren't working — broken SOQL queries meant the agent was receiving empty results. Rather than escalating, the agent was filling the gap with LLM-generated content that sounded plausible but was fabricated. Customers were receiving invented product specifications and non-existent return policies. The fix was straightforward once diagnosed, but the client had been live for three weeks before someone noticed.
Understanding the Atlas architecture changes how you approach specific configuration decisions:
Instructions are the most influential variable in agent behaviour, and they're also the most common source of production issues. Write Instructions as explicit business rules, not personality guidance. “Be professional and friendly” is not an Instruction; it's decoration. “When the customer asks about loan balances, always retrieve the current balance using the Get Loan Balance Action before responding. Never state a balance from memory.” is an Instruction. The more specific your Instructions, the less Atlas has to infer — and less inference means fewer surprises.
Every Topic should have an explicit fallback instruction for the cases you know will occur: Action failures, out-of-scope requests, authentication failures, empty data results. Don't rely on the default LLM behaviour for these states — it will be inconsistent. Write the fallback behaviour explicitly in the Instructions, including the exact escalation path and the context that should be passed.
Start conservative (0.75+) and tune down based on observed escalation rate. If your agent is escalating 40% of conversations that should be resolvable, pull a sample of those conversations, examine the confidence scores in debug logs, and adjust the threshold. Don't guess — look at the data. For high-risk Topics (anything involving record writes or financial data), stay above 0.70 regardless of escalation rate.
Every Action call, every retrieved record, and every message in the conversation consumes tokens. For complex Topics with multiple Action calls, map out the approximate token consumption before building. If your context budget is tight, use targeted data retrieval (specific fields, not full record JSON) and consider whether any Actions can be combined. A well-scoped pilot agent should rarely hit context limits; an overly broad agent will hit them regularly.
Agentforce 3 (generally available Q1 2026) brings three changes that materially affect the architecture decisions described above.
Native MCP support: The Model Context Protocol integration means agents can now connect to MCP servers without building custom Apex callouts. Salesforce has first-party integrations with Google Cloud, Stripe, PayPal, GitHub, and several ERP vendors. For orgs with these systems, this eliminates a significant integration build. The trade-off: MCP connections are less auditable than native Actions — the Einstein Trust Layer doesn't instrument MCP calls with the same granularity as Apex or Flow Actions. For regulated use cases, Apex/MuleSoft remains the right choice.
Multi-agent orchestration: Agentforce 3 enables agents to invoke other agents as sub-tasks. An orchestrator agent can decompose a complex request and delegate sub-tasks to specialised agents — a Quote Drafter, a Pricing Validator, an Approval Submitter — each operating within its own Topic scope. The orchestration model provides cleaner separation of concerns for complex workflows, but adds debugging complexity: a failure in a sub-agent conversation doesn't always surface cleanly in the parent conversation's audit log.
Reasoning improvements: The Atlas reasoning layer in Agentforce 3 demonstrates measurably better performance on multi-step planning tasks compared to Agentforce 2. In our testing, Topics that previously required explicit step-by-step Instructions now execute correctly with higher-level goal descriptions. This doesn't mean you should reduce the precision of your Instructions — explicit constraints are still better than inferred ones — but it does mean the planning phase is more robust on complex, multi-action Topics.
The 12 questions you must answer before writing a single Topic or Action.
8 min readCase StudyStep-by-step walkthrough of a financial services deployment — architecture, MuleSoft integration, and guardrail configuration.
15 min read