Agentforce Topics and Actions Explained: The Building Blocks Every Admin Needs
Agentforce agents are built from Topics and Actions — not code. Here's what each one does, how they fit together, and how to design them so your agent actually works in production.
Most of the confusion about Agentforce comes from not knowing what the agent is actually made of. People see a chat interface, assume it's a large language model talking directly to their data, and wonder why it doesn't just know things. The reality is more structured than that — and once you understand it, building and debugging agents becomes much more straightforward.
An Agentforce agent is not a chatbot with access to your org. It's a reasoning engine that uses Topics and Actions to decide what to do and then do it. Everything else — the conversational interface, the grounding in your data, the escalation to a human — is built on top of those two primitives.
What a Topic Is (and Isn't)
A Topic is a defined area of responsibility. It answers the question: what is this agent supposed to handle?
When a user sends a message, the Atlas Reasoning Engine reads it and decides which Topic it belongs to. It makes that decision based on the Topic's description and scope instructions — plain-English text that you write. The agent doesn't search keyword lists or follow a decision tree. It reads the message, reads your Topic descriptions, and reasons about which one fits.
That last point is worth sitting with. Your Topic descriptions are not labels or categories — they're instructions to a reasoning model. Vague descriptions produce unpredictable routing. "Handle customer questions" is almost useless. "Handle questions about the status of open service cases, including escalation requests and requests for case notes" is something the agent can act on reliably.
A Topic also defines the boundaries of what the agent is allowed to do within it. If your Topic description says the agent handles case status questions, the agent won't go off and start updating records unprompted — it doesn't have Actions for that unless you add them, and even then it will only use them when it decides the situation warrants it.
What Goes Inside a Topic
Each Topic contains:
- Description — what kinds of requests belong here (written for the reasoning engine, not for humans)
- Scope — additional instructions on tone, limits, and behavior within this topic
- Actions — the specific things the agent can do when this Topic is active
The scope field is where you add guardrails: "Do not speculate about case resolution timelines. If the user requests a refund, escalate to a human agent rather than attempting to process it." The agent treats scope instructions as constraints on its behavior within the topic, not suggestions.
What an Action Is
If Topics are about what the agent handles, Actions are about what the agent does.
An Action is a concrete operation the agent can invoke: look up a record, run a Flow, send an email, call an external API, generate text from a prompt template. The agent doesn't write code in the moment. It chooses from the Actions you've made available and calls them in sequence to get to a result.
Actions are typed. In Agentforce Builder, you'll see several categories:
Flow Actions connect to any Salesforce Flow you've built. This is the most common Action type for admins because you likely already have Flows for the processes you want to automate. A Flow that updates a case status, sends a confirmation email, or creates a follow-up task can be dropped into Agentforce as an Action with minimal additional configuration.
Prompt Template Actions generate text using a configured Einstein prompt. Use these when the agent needs to produce something — a case summary, a reply draft, a product recommendation — rather than retrieve or update data.
Apex Actions call Invocable Methods you've written. If you need logic that Flow can't express or API calls that need complex authentication, an Apex action gives you that flexibility without giving up the no-code agent configuration.
Standard Actions cover the out-of-the-box capabilities Salesforce ships: search knowledge articles, transfer to a human, end the conversation. These are the scaffolding most service-oriented agents are built around.
How the Agent Chooses Which Action to Call
This is where most people expect magic and find mechanics instead. The agent reads the active Topic's available Actions and decides which one to invoke based on each Action's description. Again — plain English text you write.
A well-described Action: "Search the knowledge base for articles matching the user's question. Use this when the user asks a how-to question or needs troubleshooting steps."
A poorly described Action: "Knowledge search."
The agent has no intuition about what "Knowledge search" does. It reads the description, matches it to the situation, and decides. If you put three Actions in a Topic and describe them all identically, the agent will pick unpredictably. If you describe them clearly and distinctly, it routes well almost every time.
Designing Topics and Actions That Work in Production
The pattern that causes the most trouble: admins build one giant Topic with twelve Actions, write thin descriptions, and then can't figure out why the agent does unexpected things. The agent isn't broken — it's making guesses because it doesn't have enough signal.
A few principles that hold up in production:
Keep Topics focused. A Topic should handle one coherent area of user intent. If you find yourself writing "or" a lot in a Topic description — "handles billing questions or shipping questions or account changes" — that's probably three Topics, not one. Tight Topics make routing predictable and make it obvious which Actions belong where.
Describe for the reasoning engine, not for documentation. Your Topic and Action descriptions are prompts. Write them the way you'd write instructions to a smart person who has never used your system. Include the when: "Use this when the user is asking about the status of an existing order, not a new one."
Test routing before you test Actions. Before checking whether your Actions do the right thing, verify that user messages land in the right Topic. Agentforce Builder's test console shows you which Topic was selected. If a message routes to the wrong Topic, fix the description — not the Action.
One Action per distinct operation. Resist the temptation to build a single "do everything" Flow and wire it to one Action. If the agent needs to look something up sometimes and update it other times, those are two different Actions. The agent can sequence them, but it can't choose between sub-paths inside a single Action it doesn't know about.
Write scope instructions as constraints, not goals. "Be helpful and professional" is not a useful scope instruction — the agent is already trying to do that. "Do not provide estimated resolution dates. If the user asks for a refund, collect their order number and transfer to a human agent" is actionable.
The Relationship Between Topics and Grounding
Topics and Actions are how the agent acts. Grounding is how the agent knows. They're different systems and they fail independently.
When you add a Standard Knowledge Search Action to a Topic, the agent can retrieve content from your Salesforce Knowledge base. When you connect Data Cloud, the agent can reason across a broader set of unified records. But the Topics and Actions structure doesn't change — the agent still selects a Topic, decides which Actions to run, and reasons about the result. It just has richer data to work with when it does.
This matters for debugging. If your agent gives a wrong answer, the cause is almost always one of two things: it routed to the wrong Topic (a description problem) or it called an Action that returned bad data (a data quality or Action configuration problem). The reasoning engine itself is rarely the issue. Knowing the difference saves a lot of debugging time.
If you haven't dug into the full how to set up an Agentforce agent walkthrough, the Topics and Actions structure you've just read is exactly what you're configuring in those steps.
A Practical Starting Point
If you're building your first agent, this structure works reliably:
- Pick one use case with a clear, narrow scope. Case status lookup, knowledge article surfacing, or account summary are all good first Topics. "General customer support" is not.
- Write three to five Actions maximum. Start with Standard Actions (knowledge search, escalate to human) and one Flow Action that handles your core operation.
- Write descriptions as if you're writing them for someone who will be tested on them. Be explicit about when to use the Action and when not to.
- Test routing first. Before connecting to live data or enabling for users, run thirty test messages through the test console and verify Topic selection is correct on all of them.
- Add scope guardrails for anything you don't want the agent to attempt. Explicit prohibitions in the scope field are more reliable than hoping the agent infers them.
The agents that make it from pilot to production are the ones where someone understood Topics and Actions well enough to design them carefully — not because they used more of them, but because they used fewer, described them precisely, and tested routing before declaring the agent ready.
That's the whole architecture. Topics define responsibility, Actions define capability, descriptions define behavior. Everything else is your data and your Flows, and you probably already have most of those.
Keep reading:
📬 Enjoyed this article?
Subscribe to our free weekly digest — AI tools, Salesforce tips, and prompts every week.