Why Your Agentforce Agent Keeps Picking the Wrong Topic — and How to Fix It Permanently

Topic misrouting is the most common runtime complaint in Agentforce deployments — and the most dangerous, because it fails silently. No error message. No alert in Studio. Just the wrong action executing on a live user's record.

One case documented in the Trailblazer Community involved 340 leads routed to the wrong follow-up flow before anyone noticed. The agent had been working correctly for weeks. Then a new topic was added that shared vocabulary with an existing one, and the Atlas classification engine started splitting between them on every other qualifying message.

This is a solvable problem — but only if you understand why it happens and work through the complete fix.

How Atlas topic classification actually works

The Atlas reasoning engine does not pattern-match keywords against your topic names. It uses semantic similarity: it reads the full classification description you write for each topic, embeds it, embeds the incoming user message, and scores the message against every topic simultaneously. The highest-scoring topic wins.

The implication: if two topics share similar meaning in their descriptions — even if the wording is different — Atlas will consistently produce near-tied scores for messages that activate that shared meaning. The agent is not broken. It is making a mathematically reasonable choice given the descriptions it has. The descriptions are the problem.

The score itself is invisible in Agentforce Builder. You cannot see why one topic beat another. This is why misrouting is so hard to diagnose without Agent Platform Tracing — the only place classification scores appear.

The anatomy of a bad classification description

These two descriptions will cause misrouting on any message that mentions "account":

Topic A — Account Billing:
"Handles questions and requests related to customer accounts,
 billing issues, invoices, and payment history."

Topic B — Account Management:
"Handles requests related to customer accounts, including
 upgrades, renewals, and changes to account details."

Both descriptions contain "customer accounts." Both will score similarly for the message "I have a question about my account." Atlas will pick one based on what else the user said — and if the message is short or ambiguous, it may flip between them across separate sessions.

The fix is not to add more detail. The fix is to make each description contrast with the others from the first sentence.

The contrast-first technique

Open every classification description by naming what this topic handles that no other topic handles. Then name what it explicitly does not handle. This forces Atlas to differentiate the topics by their semantic boundaries rather than their shared vocabulary:

Topic A — Account Billing (revised):
"Handles invoices, payment failures, billing cycle questions,
 and refund requests. Does NOT handle account upgrades,
 contract changes, or user access requests."

Topic B — Account Management (revised):
"Handles subscription upgrades, contract renewals, account
 tier changes, and adding or removing users. Does NOT handle
 billing disputes, invoices, or payment issues."

The explicit exclusions in each description give Atlas strong negative signal — if the message is about an invoice, it now scores very poorly against Topic B's description, not just slightly lower. The classification gap widens.

The 8–13 topic rule

Salesforce's own guidance is to keep each agent between 8 and 13 topics. The reasoning is mathematical:

• Below 8: Topics become too broad and catch too many different user intents under one umbrella, forcing the agent to handle genuinely different scenarios with a single action set.
• Above 13: The classification space becomes crowded. With 15+ topics, there will almost always be at least two whose descriptions share meaningful semantic overlap — the long tail of "remaining" use cases tends to create vague, overlapping descriptions.

If your agent genuinely needs more than 13 topics to cover its scope, the right architecture is a multi-agent setup: an orchestrator agent with a small number of high-level routing topics, each delegating to a specialist sub-agent. The orchestrator routes coarsely (billing, account management, technical support); each sub-agent handles its domain with 5–10 focused topics. This is the pattern behind Agentforce multi-agent orchestration.

Out-of-scope guardrails

Contrast-first descriptions handle most misrouting. Out-of-scope guardrails handle the edge cases that survive even well-written descriptions.

A guardrail is an instruction in a topic's configuration telling the agent which user intents this topic should decline regardless of classification score. You add them in Agentforce Builder on the topic detail page under Instructions:

Do not handle requests about contract renewals or account
upgrades. If the user asks about these, let them know you
can help with billing questions only, and suggest they
contact the Account Management team.

Guardrails are a second filter after classification. They catch cases where the user's phrasing genuinely matches the description but the intent is out of scope — for example, a user asking "I need to change my billing address for my renewal" landing on the Billing topic when the renewal part should go to Account Management.

Verifying the fix with Agent Platform Tracing

Do not assume revised descriptions fixed the problem. Verify:

1. Enable Agent Platform Tracing if not already active
2. Run 10–15 Simulate Mode conversations using the exact messages that were misrouting
3. Query the trace data and confirm the classification scores — the correct topic should now score at least 0.08–0.10 higher than its nearest competitor on previously ambiguous inputs
4. Run an additional 10 conversations using messages that should route to other topics, confirming you did not accidentally pull those messages into the revised topic

If the gap is still under 0.05 after revisions, the descriptions still share too much semantic vocabulary. Read them aloud to a colleague unfamiliar with your topic structure — if they cannot tell in one sentence what each topic does and doesn't handle, Atlas cannot either.