Agent Topic
An Agent Topic is the skill group inside Agentforce that organizes related Agent Actions and tells the Atlas Reasoning Engine when to consider them.
Definition
An Agent Topic is the skill group inside Agentforce that organizes related Agent Actions and tells the Atlas Reasoning Engine when to consider them. Each topic has a name, a classification description that defines which user messages fall under this skill, an agent instruction that shapes response style, and an attached set of actions that can be invoked when the topic is active.
Topics let the reasoning engine narrow the search space. Without topics, the engine would have to evaluate every action against every message, which destroys latency and accuracy. With topics, the engine first classifies the message into one topic (or rejects it as out of scope), then only considers that topic's actions. The result is predictable behavior even as the action library grows past a hundred entries.
Why topics are the difference between a usable agent and a confused one
Where topics live in Agent Builder
Open Setup, Agent Builder, pick the agent, and the left rail shows a Topics panel. Each row is one topic. Click into a topic to see its classification description, agent instruction, and attached actions. The topic order in the list does not affect routing. The classification description is what the engine reads. Topics can be reordered for editor convenience without changing runtime behavior. Topics created here are scoped to this agent. There is no org-level topic library the way there is for actions. If two agents need the same topic, you build the same topic twice. This is a deliberate design choice so each agent's topic phrasing can adapt to its audience.
The classification description is the field that matters
The classification description is the single highest-leverage field on the topic. The engine reads it on every user message to decide whether this topic is in play. A weak description like "Handles order-related questions" matches almost anything that mentions an order. A strong description names the user phrases that should match and calls out negative cases: "Use this topic when the user asks about order status, delivery date, tracking number, or where their package is. Do not use it for refund requests, return labels, or pricing questions; those belong to the Returns topic." Negative cases bind hard, so spend the same effort on them as on positives.
Topic instructions shape response style
The topic instruction is a separate field from the classification description. It runs after a topic has been picked and tells the agent how to behave inside that topic. This is where you put tone rules ("respond in two sentences or fewer"), confirmation rules ("always confirm the order number before quoting a delivery date"), and escalation rules ("if the user asks for a human three times, hand off"). The instruction does not influence whether the topic is picked. It only influences the response the user sees once an action inside the topic has run.
Actions attached to a topic
Actions inside a topic are the only actions the reasoning engine can call while that topic is active. Most topics need three to seven actions: one or two for read (Get Order, Search Orders), one or two for write (Update Address, Cancel Order), and one or two for adjacent help (Search Knowledge, Transfer to Human). A topic with twenty actions is almost always two topics that should be split. The engine picks one or more actions per message; multiple actions in sequence are common (Identify Order, then Get Order Status). The Plan Trace in the Conversation Preview shows the chain.
Topic versioning and safe rollout
Editing a classification description changes runtime behavior the moment you save. There is no draft mode at the topic level. The agent itself has a version history at the agent level, so the rollback path is to revert the agent version. The practical approach is to clone the agent to a sandbox-like draft agent, edit topics there, validate in the Conversation Preview and Agentforce Testing Center, then promote the topic changes to the live agent. Treat the classification description with the same rigor as a production prompt change.
Standard topics shipped with each agent type
Agentforce for Service ships with topics like Case Triage, Knowledge Search, and Escalation. Agentforce for Sales ships with Account Research, Opportunity Update, and Meeting Prep. Industry agents (Health Cloud, Financial Services Cloud) ship with industry-specific topics. The standard topics are a starting template, not a final state. Most teams keep one or two standard topics unchanged, customize a couple more, and delete the rest. The instruction field on standard topics is editable. The classification description is also editable but worth a careful read first; the Salesforce-provided phrasing has usually been validated against real conversations.
Multi-topic conversations and topic handoff
A single conversation can switch topics turn by turn. The user asks about an order (Order Status topic), then asks to return it (Returns topic), then asks for a refund (Refunds topic). The reasoning engine classifies each turn independently, so the agent picks the right topic without explicit handoff logic. However, state does not automatically carry across topics. If the Returns topic needs the order number established in the Order Status topic, write an action that reads conversation history or persist the order number in a session variable. Otherwise the agent re-asks for it.
How to build an Agent Topic the reasoning engine actually picks correctly
Building a topic is two-thirds writing the classification description, one-third wiring actions. Start with three to five sample user messages you want the topic to handle and three to five sample messages it should reject. Write the classification description against those samples, then validate in the Conversation Preview before adding actions.
- Collect sample user messages
Write three to five messages this topic should handle and three to five messages it should reject. Pull from real chat logs or support tickets if you have them. Make sure the rejected messages are close in phrasing to accepted ones, not obviously different.
- Open Agent Builder and create the topic
Setup, Agent Builder, pick the agent, Topics panel, New Topic. Give the topic a name agents and admins recognize without context, like "Returns and Refunds" rather than "RR-2026-v3".
- Write the classification description with positives and negatives
Name the user phrases the topic should match. Then call out two or three phrases it should reject and where those belong. Negative cases bind hard, so they matter as much as positives.
- Write the topic instruction for response style
Set tone, length, confirmation requirements, and escalation rules. Keep this short. A two-sentence instruction is usually plenty; verbosity here makes the agent verbose.
- Attach the three to seven actions this topic needs
Click Add Action and pick from the Agent Action library or build new actions inline. Keep the list short. Twenty actions on one topic is a signal the topic needs to be split.
- Test in Conversation Preview and read the Plan Trace
Send each sample message. The Plan Trace shows which topic the engine picked. Iterate on the classification description until accepted messages map to this topic and rejected ones map elsewhere or to no topic.
- Save the test set to Agentforce Testing Center
Capture the sample messages and expected topic classifications. Testing Center runs the set on every change and flags regressions before they reach users.
The label that appears in Agent Builder and in the Plan Trace. Use a phrase admins and supervisors will recognize without explanation.
Natural-language description the reasoning engine uses to decide if this topic applies to the current message. The single most important field on the record.
Response-style guidance that runs after the topic is picked. Tone, length, confirmations, escalations.
The set of Agent Actions the engine can invoke while this topic is active. Typically three to seven actions.
Toggles the topic on or off without deleting it. Useful for staged rollout and emergency rollback.
- A weak classification description is the single most common cause of wrong topic routing. Vague descriptions match almost anything and trigger the wrong actions.
- Topic edits go live the moment you save. There is no draft mode at the topic level. Clone the agent to a draft for safe editing.
- State does not carry across topics automatically. If Topic B needs values from Topic A, write an action that reads conversation history or use session variables.
- Two topics with overlapping classification descriptions confuse the engine. Run a confusion check by sending the same message and seeing which topic wins; revise descriptions until each message has one clear home.
- Removing an action from a topic does not delete the action itself. The action stays in the Agent Action library. This is by design so other topics or agents can still use it.
Trust & references
Cross-checked against the following references.
- Agentforce product overviewSalesforce
- Agent topics referenceSalesforce
Straight from the source - Salesforce's reference material on Agent Topic.
- Agentforce TopicsSalesforce Help
- Write a Topic Classification DescriptionSalesforce Help
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is an Agent Topic in Agentforce?
Q2. Which component uses a topic's classification description to decide which topic applies?
Q3. Which of the following does a topic NOT typically include?
Discussion
Loading discussion…