Once you’ve built an agent, given it a topic, and wired up a couple of actions, a very natural question appears: when a customer types something, how does the agent know which action to run? You didn’t write an if statement. You didn’t draw a flowchart. Yet somehow the agent reads “I want to return my order” and reaches for the right tool. The thing doing that choosing has a name — the planner — and understanding it is the moment Agentforce stops feeling like magic and starts feeling like something you can reason about.
Let me walk you through it the way I’d explain it to someone on their first day.
The four parts, and where the planner sits
By now you’ve met the building blocks: the agent (the assistant itself), its topics (the jobs it’s allowed to help with), its actions (the concrete things it can do), and grounding (the real data that keeps its answers honest). The planner is the piece that ties them together at runtime.
Think of it as the agent’s reasoning step. When a message arrives, the planner looks at what the user wants, looks at the topics and actions available, and decides on a course: which topic this falls under, which action (or sequence of actions) to run, and what information it still needs to ask for.
The planner is the agent’s decision-maker. Topics and actions are what’s possible; the planner is what actually happens for this particular message.
What the planner is really reading
Here’s the part that surprises beginners most: the planner chooses an action largely by reading its description in plain language. When you create an action, you give it a name and a description of what it does and when to use it. The planner uses that description — not hidden code — to match a user’s request to the right action.
This is why I tell people the most important field on an action isn’t the logic; it’s the description. “Use this to look up the status of a customer’s existing order by order number” is a sentence the planner can match against “where’s my order?”. A vague description like “order action” gives the planner almost nothing to reason with, and it’ll either pick the wrong tool or none at all.
In other words: you’re not programming the planner with rules. You’re describing your tools clearly enough that a good reasoner picks the right one. It’s much closer to writing instructions for a capable new colleague than writing traditional code.
A request, step by step
Say a customer types: “I bought some boots last week and they don’t fit — can I send them back?” Roughly, the planner:
- Reads intent. It interprets this as a return request, not an order-status check or a product question.
- Selects a topic. It maps the request to the topic that covers returns, which narrows the available actions to the relevant ones.
- Chooses an action. Among that topic’s actions, it matches the request to, say, “Start a return for a delivered order.”
- Spots missing information. That action needs an order number. The customer didn’t give one, so the planner asks for it rather than guessing.
- Runs and responds. With the order number, it runs the action, grounds the result in real order data, and replies.
You didn’t script that sequence. You provided clear topics, well-described actions, and good grounding — and the planner assembled the path.
Why your agent sometimes does the “wrong” thing
Once you see the planner as a reasoner reading descriptions, the common beginner frustrations make sense:
- It picks the wrong action. Usually two actions have overlapping or vague descriptions, and the planner can’t tell them apart. Sharpen the descriptions so each clearly owns its job.
- It ignores an action entirely. Often the action’s description doesn’t sound like anything a real user would say, so the planner never matches it. (There’s also a metadata gotcha where a deployed action simply doesn’t register — I wrote about that hard-to-spot case in Fixing Agentforce ‘Actions: 0’.)
- It makes something up. That’s a grounding problem, not a planning one — see Grounding Explained.
The fix is rarely “more code.” It’s clearer scope and clearer descriptions, which is exactly the craft of Topics and Instructions.
The mindset that makes this click
Twenty years of teaching left me with one stubborn habit: before I explain anything, I ask what the listener already knows and what they’re actually trying to do. The planner does a smaller version of that on every message — interpret the goal, check what’s available, choose a path. Your job isn’t to control its every move; it’s to give it a well-organised, clearly-labelled set of tools and trust the reasoning. Build for that, and the agent feels less like a black box and more like a colleague who reads instructions well.
Your next step
You now have the missing piece: topics define scope, actions define what’s possible, grounding keeps it honest — and the planner is the reasoning that turns a message into the right action. The best way to build intuition for it is to watch it choose in practice, which is exactly what Testing Your Agentforce Agent is about. If you’re still placing the pieces, start at What Is Agentforce? and keep exploring the Agentforce category.