The Atlas reasoning engine

A customer types “I want to return the shoes I ordered last week.” The agent cheerfully reports that the order was delivered on Tuesday. Correct, grounded, and completely beside the point — the customer asked about a return, and the agent answered about order status. When this happens, most teams blame the model. Almost always, the model is fine. The two topics had overlapping classification descriptions, and the router picked the wrong one before any real reasoning began.

That router is part of the Atlas reasoning engine, the decision-making layer inside Agentforce. Salesforce has published enough about how it works — an engineering deep-dive, a step-by-step workflow article, a Trailhead module — that you don’t have to treat it as a black box. And you shouldn’t, because every stage of the Atlas loop reads a specific field you wrote: a topic name, a classification description, an instruction, an action description. Those fields are not documentation. They are the program.

This post walks the mechanics first — classification, planning, action selection, the evaluate-and-refine loop, grounding, and the hybrid-reasoning direction Salesforce is now taking — then turns each stage into concrete rules for writing the fields it depends on, and the failure modes you get when you don’t.

What the Atlas reasoning engine actually is

Atlas is not a large language model. It’s the orchestration system around one — the layer that takes a user utterance, decides which job it belongs to, plans a response, calls tools, checks the results, and only then replies. Salesforce’s engineering team, which incubated Atlas within Salesforce AI Research, describes it as implementing inference-time “System 2” reasoning: deliberate, multi-step deliberation at runtime, as opposed to the single-shot pattern-matching of a plain prompt-and-response call. Under the hood, the same post describes asynchronous, event-driven, graph-based workflows with loosely coupled components — architecture that matters to you mainly because it explains why the loop can branch, retry, and run steps concurrently rather than marching through a fixed script.

The operating pattern is a reason-act-observe cycle. Salesforce’s Trailhead module puts it plainly: the engine “thinks through a step, uses an action, checks the outcome, and loops until it completes the user’s goal” — the ReAct pattern from the agent-research literature, productised. Salesforce has claimed real gains from this design; in early pilots it reported a 2x increase in response relevance and a 33% increase in end-to-end accuracy for customer-service use cases versus single-shot and DIY alternatives. Vendor-reported numbers, so weigh them accordingly, but the architectural argument behind them is sound: checking your work catches errors that one-pass generation cannot.

If you want the broader platform picture — what agents, topics, and actions are and how the whole product fits together — we’ve covered that in our plain-English Agentforce explainer. Here we stay inside the engine.

One terminology note before we go further. Just this month, Salesforce’s documentation began renaming “topics” to “subagents”, with no change in functionality. As of this writing, “topics” is still the term you’ll see in most orgs, builders, and guidance, so it’s the one we use below. Expect mixed vocabulary for a while.

From utterance to answer: the six steps Atlas takes

Salesforce’s workflow documentation lays out what happens between a message arriving and a reply going out. Condensed, the loop looks like this:

Topic classification. Atlas reads the incoming message against each topic’s name and classification description and picks the best match. If nothing fits, it falls back to an off-topic response. This is a routing decision, made before any plan exists — and it’s where our shoe-return conversation above went wrong.
Context assembly. The winning topic’s scope, instructions, and available actions are injected into the prompt, alongside the user’s message and the conversation history. Whatever isn’t in that assembled context does not exist as far as this turn of reasoning is concerned.
Plan and decide. The LLM evaluates the combined context and chooses: run an action to get information or perform a task, or respond to the user directly — either because it has enough to answer or because it needs to ask a clarifying question.
Action execution. If an action is chosen, Atlas invokes it — a Flow, an Apex invocable, a prompt template, an API call — and captures the output.
Evaluate and refine. The action’s output is fed back into the loop with the original context. Atlas re-plans: is the goal met, is another action needed, has something failed? It repeats steps 3–5 until it’s ready to answer.
Check and respond. Before the reply goes out, it’s validated for grounding in the retrieved information and adherence to the topic’s instructions and scope, then delivered.

Two properties of this pipeline are worth sitting with. First, it’s prompts all the way down: at each turn, the “program” Atlas executes is assembled at runtime from text fields you wrote in Agentforce Builder. Second, it’s observable. Each planning step, action call, and evaluation is captured in the agent’s reasoning trace — visible through the plan tracer in the builder’s testing panel — which is how you debug an agent: not by guessing, but by reading what the engine believed at each step.

Grounding and retrieval: what Atlas knows when it decides

Reasoning quality is bounded by what the loop can see, and most of what it sees arrives through retrieval. In Agentforce, knowledge grounding runs through retrieval-augmented generation: content is chunked and indexed ahead of time, and at runtime a retriever pulls the passages relevant to the current question into the prompt. Salesforce’s engineering team has written about the machinery behind this — Agentforce Data Library’s retrieval pipeline ingests knowledge articles, uploaded files, and web content into structured indexes, and uses confidence-weighted retriever selection, scoring retrievers on past accuracy, document credibility, and contextual relevance rather than treating all sources equally.

The part that matters for this post: retrieval is not a preprocessing step that happens once before reasoning. It participates in the loop. Search-style actions are tools like any other, which means Atlas decides whether and when to retrieve as part of planning — the “agentic RAG” pattern. A well-configured agent retrieves before answering a policy question and skips retrieval when confirming a date it already has.

The practical consequence cuts two ways. Good: you can shape retrieval behaviour with instructions (“always search the knowledge base before answering warranty questions”). Bad: grounding failures masquerade as reasoning failures. An agent that answers from stale or duplicated content isn’t reasoning badly — it evaluated exactly what your index gave it. In our experience, when an agent’s answers are confidently wrong, the index is the first place to look and the instructions are the second.

Hybrid reasoning: where Atlas is heading

Everything above describes the probabilistic core: an LLM choosing, at every turn, what to do next. That flexibility is the point, and also the problem — some business steps must happen in a fixed order, every time, and asking a language model nicely is a strange way to guarantee that.

Salesforce’s answer, announced with Agentforce 360 in October 2025, is hybrid reasoning: making the Atlas engine configurable so deterministic business logic and LLM judgment can be mixed deliberately. The developer-facing expression of this is Agent Script, a human-readable domain-specific language for defining agent behaviour — conditional logic, guardrails, explicit action sequences — that compiles into a graph specification the engine executes. Under the hood sits what the engineering team calls Agent Graph, and a design goal of “guided determinism”: workflows modelled as explicit nodes and edges, with state machines handling transitions while the LLM handles language and judgment inside each node. The motivating failure they cite is familiar to anyone who has watched an agent wander — losing the primary objective during a tangential conversation and never returning to it.

A status check, since this area moves fast: Agent Script entered pilot at Dreamforce 2025 and moved to public beta in November 2025. As of this writing in early April 2026, it remains in beta, so treat specifics as subject to change before general availability. The direction, though, is unambiguous — and it reinforces rather than replaces the argument of this post. Hybrid reasoning gives you rails for the steps that must be deterministic. Everything on either side of those rails is still steered by natural language you write.

Your words are the program: writing for each stage Atlas reads

Here is the payoff of knowing the mechanics. Each configuration field is consumed by a specific stage of the loop, does one job there, and fails in a characteristic way when it’s badly written:

What you write	When Atlas reads it	Its job	Classic failure when badly written
Topic name + classification description	Step 1, routing	Match the utterance to a job	Misrouting; off-topic fallbacks
Scope	Steps 2–3, planning	Draw the boundary of the job	Scope creep; dead-end refusals
Topic instructions	Every reasoning turn	Guide judgment within the job	Looping; rigid or contradictory behaviour
Action name + description	Steps 3–4, tool selection	Advertise what each tool does	Wrong tool chosen; tools never chosen
Input/output descriptions	Steps 4–5, invocation and evaluation	Explain parameters and results	Malformed calls; ignored or misread outputs

Salesforce’s own instruction-writing guidance backs most of the rules below; the rest is pattern recognition from building these things.

Classification descriptions: write for the router, not the reader

The classification description is read at step 1, in competition with every other topic’s description, before any instructions load. So write it as a routing rule: what the user says when this topic applies, not what the topic does internally. “Manages customer inquiries about order status and return requests” routes; “This topic uses the OrderAPI flow to query fulfilment status” does not. Keep descriptions mutually exclusive — if two topics both mention “orders,” you have built a coin flip. And split combined topics along the lines customers actually draw: our shoe-return failure disappears the moment “order status” and “returns and exchanges” are separate topics with disjoint vocabulary.

Scope: state the boundary in both directions

Scope is the fence Atlas consults when planning. The pattern that works is explicit inclusion and exclusion, in one line — Salesforce’s example is the right shape: “Handle resending reservation confirmations, but do not create new reservations.” The exclusions matter more than the inclusions, because they’re what stands between a helpful agent and one that improvises a capability you never gave it.

Topic instructions: guidance for judgment, not business rules

Instructions are re-read on every turn of the loop, so they should read like a good standard operating procedure: conditional, situational, positively framed. Pair specific situations with specific actions (“if the customer provides an order number, run Look Up Order before answering”). Prefer telling the agent what to do over what not to do. And keep hard business rules out of them entirely — a discount cap or an eligibility check belongs inside the Flow or Apex behind the action, where it executes identically every time, not in prose an LLM interprets probabilistically. Salesforce’s guidance is blunt about the sharpest edge here: the agent closely follows “must,” “never,” and “always,” and may get “stuck” trying to fulfil a “must” or “always” instruction, or interpret a “never” too broadly. Use absolutes sparingly, and when an agent misbehaves, suspect them first.

Action names and descriptions: label the tools honestly

At step 3, the LLM chooses among actions mostly by their names and descriptions. Similar names invite confusion — the official guidance recommends distinct verbs, e.g. “Locate Project Details” alongside “Retrieve Task Information” rather than two near-identical “Get…” actions. Give each action a one-to-three-sentence description covering what it does, when to use it, and any dependency (“run Identify Customer Account first to obtain the Account ID”). Then describe inputs and outputs with the precision you’d want in an API doc — “accountId: the 18-digit Account record ID” tells the model exactly what to pass; “the ID” does not. A useful side effect, noted in the same guidance: pushing detail into action configuration keeps topic instructions short, which keeps the assembled prompt lean and the reasoning sharper.

Misrouting, looping, and how to debug them

When agents go wrong in production, the failures cluster into a few shapes, and the pipeline explains each one.

Misrouting is a step-1 failure: overlapping classification descriptions, vocabulary shared across topics, or simply too many topics competing. Practitioner write-ups consistently report classification reliability degrading once topic counts climb past roughly a dozen, with overlap — not volume — as the underlying cause. The fix is editorial: make descriptions disjoint, merge genuine duplicates, split false unions.
Looping is usually a step-5 failure with a step-2 cause. An absolute instruction the agent can’t satisfy (“always confirm the order number” when the channel doesn’t provide one) sends the evaluate-refine cycle around in circles. So does an action that fails silently — a Flow returning null gives the evaluator nothing to conclude, so it retries. Make actions return explicit success and failure messages the LLM can read, and give the agent an exit (“if the order can’t be found after one attempt, apologise and offer escalation”).
Wrong-action selection points at names and descriptions: two lookups that sound alike, or a description that oversells what the action accepts.
Confident nonsense is typically grounding, not reasoning — stale articles, duplicates, or missing content the agent papered over.

Debugging all of these starts in the same place: the reasoning trace. Read what topic was chosen and why, what plan was formed, what each action returned, and where the loop went sideways — then fix the specific field that stage was reading. Test the way an adversary would, not the way a demo script does; we’ve written separately about what separates production agents from demos, and adversarial utterance testing is most of it.

Configuration is code now — treat it that way

Step back far enough and the Atlas reasoning engine does something quietly radical: it turns plain English into the runtime behaviour of a production system. The topic descriptions, scopes, instructions, and action descriptions in your org are executed — assembled into prompts, interpreted, and acted on, thousands of times a day. That’s a definition of source code, whether or not it lives in a file.

Which suggests the discipline. Write these fields deliberately, with the stage that consumes them in mind. Review changes to them the way you’d review an Apex diff, because a one-word edit to a classification description can reroute a whole category of conversations. Version them, test them against a fixed utterance set, and read reasoning traces after every change. The teams that get consistent behaviour out of Agentforce aren’t the ones with the cleverest prompts — they’re the ones who treat agent language as a maintained artifact with an owner, and who put deterministic logic in deterministic places while reserving natural language for genuine judgment.

The hybrid-reasoning direction makes this split explicit rather than optional: rails where you need certainty, reasoning where you need flexibility. But you don’t need to wait for any of it to get better agents this quarter. You now know what Atlas reads at every step. Go read your own topics with the router’s eyes, your instructions with the loop’s eyes — and rewrite the ones that were written for humans instead of for the engine.

Understanding the basics

What is the Atlas reasoning engine?

The Atlas reasoning engine is the decision-making layer inside Salesforce Agentforce. It takes each user message, classifies it into a topic, assembles that topic’s instructions and actions into a prompt, plans a response, invokes actions such as Flows or Apex, evaluates the results, and loops until it can answer. Salesforce describes it as inference-time “System 2” reasoning — deliberate multi-step deliberation rather than single-shot text generation.

How does Agentforce decide which topic handles a request?

Before any planning happens, Atlas compares the incoming message against every topic’s name and classification description and routes to the best match; if none fits, it gives an off-topic response. Because this is a competitive matching step, classification descriptions must be written as mutually exclusive routing rules in the customer’s own vocabulary. Overlapping descriptions are the leading cause of misrouted conversations.

Why does an Agentforce agent loop or get stuck?

Looping usually traces to one of two things: an absolute instruction (“must,” “always,” “never”) the agent cannot satisfy in the current conversation, or an action that fails silently, giving the evaluate-and-refine loop nothing to conclude so it retries. The fixes are to use absolutes sparingly, return explicit success and failure messages from every action, and give the agent a stated exit path such as escalation.

Rewriting topics and instructions for an agent that keeps misrouting — or building one properly from the start? Talk to us — reasoning-engine-shaped agents are what we do.

The Atlas reasoning engine: a practical guide to how Agentforce decides