Agentforce is easy to demo and surprisingly easy to get wrong in production. Most of the problems I've seen come from teams treating it as "a chatbot with a better model." It isn't. It's a reasoning layer that chooses and executes actions on your platform — and that changes how you need to design.
Here's the mental model I use with architects and delivery teams.
The building blocks
| Component | What it is | Think of it as |
|---|---|---|
| Agent | A configured assistant with a role, channel(s), and a set of topics | A job description |
| Topics | Categories of work the agent can handle, each with a classification description, scope and instructions | The responsibilities in that job |
| Instructions | Natural-language guidance for how to behave within a topic | The standard operating procedure |
| Actions | What the agent can actually do: Flows, invocable Apex, prompt templates, API calls (often via MuleSoft) | The tools on the desk |
| Reasoning engine | Interprets the request, selects a topic, plans and executes actions, and evaluates the result | The judgement |
| Trust layer | Grounding, masking, toxicity detection, zero data retention with model providers, and audit | Compliance, built in |
How a request is handled
flowchart TD
U[User message] --> C{Classify into a topic}
C -->|no match / out of scope| ESC[Decline or escalate]
C -->|topic found| P[Plan: which actions, in what order]
P --> A[Execute action · Flow / Apex / API / Prompt]
A --> G[Ground response with retrieved data]
G --> E{Goal met?}
E -->|no| P
E -->|yes| R[Respond · log to audit trail]
The two places this goes wrong are classification (the agent picks the wrong topic) and action design (the right topic, but actions that are too broad, too vague or return too much data).
Design principles that matter in production
Topics: narrow and distinct
Topic descriptions are what the engine uses to route. If two topics overlap — "Order issues" and "Delivery problems" — you'll see inconsistent routing. Write topic descriptions like you're explaining the boundary to a new joiner, and include explicit "this topic does not cover…" statements.
Actions: small, well-named, deterministic
An action called getOrderStatus that takes an order ID and returns four fields is far more reliable than handleOrder that does everything. The engine reads action names, descriptions and input/output definitions — treat those like an API contract, because that's what they are.
Put business rules in the action, not the prompt
If a refund over a threshold needs approval, enforce it in the Flow or Apex — not in an instruction asking the model to "please check". Use the model for language and judgement; use the platform for rules. Newer Agentforce releases give you more ways to make parts of an agent's behaviour deterministic — use them for anything that must always happen the same way.
Grounding beats prompting
Most "hallucination" problems I see are really grounding problems: the agent wasn't given the right data. Retrieval from Knowledge, Data 360 or the records themselves will do more for accuracy than another paragraph of instructions.
- Start with a few high-volume, low-risk topics
- Run the agent as the right user, with least-privilege access
- Build a test conversation library and run it on every change
- Design escalation with a summary for the human
- Create one giant "catch-all" topic
- Encode critical business rules only in instructions
- Return whole records when two fields will do
- Skip the security review because "it's just a pilot"
Where it fits in your architecture
Agentforce is most powerful when it sits on a clean platform: good data, clear processes and well-designed APIs. If your integration layer is brittle or your data model is a mess, an agent will surface those problems very publicly. I often tell leaders that an Agentforce programme is the best excuse they'll get to fix the foundations — and that fixing them is most of the work.
The model decides what to do. Your architecture decides whether it can — safely.
Pranav Sanvatsarkar is a Solution Architect with 14+ years across telecom, healthcare, public sector and non-profit, focused on AI, agentic automation and Salesforce architecture. Say Hello!