Why architecture matters before you build
Most Agentforce implementations that struggle in production share a common root cause: the team didn't understand the architecture before they started building. They treated Agentforce like a chatbot builder — define some flows, add some buttons — and were surprised when the agent behaved unpredictably at scale.
Agentforce is a reasoning system, not a scripted workflow tool. Understanding how each layer works makes every configuration decision clearer and every performance problem easier to diagnose.
The Agentforce architecture stack
Agentforce is composed of six layers that work together to produce autonomous agent behavior:
┌─────────────────────────────────────────────┐ │ CHANNELS │ │ Web Chat │ Email │ SMS │ Voice │ Slack │ ├─────────────────────────────────────────────┤ │ AGENT DEFINITION │ │ Role │ Scope │ Guardrails │ ├─────────────────────────────────────────────┤ │ TOPICS │ │ Classification │ Instructions │ Actions │ ├─────────────────────────────────────────────┤ │ ATLAS REASONING ENGINE │ │ LLM Reasoning │ Planning │ Execution │ ├─────────────────────────────────────────────┤ │ DATA GROUNDING │ │ CRM Records │ Knowledge Base │ Data Cloud │ ├─────────────────────────────────────────────┤ │ SALESFORCE PLATFORM │ │ Objects │ Flows │ Apex │ APIs │ Permissions │ └─────────────────────────────────────────────┘
Layer 1: Channels
Channels are the interfaces through which an agent interacts with users. Agentforce supports:
- Messaging channels: Web chat (Embedded Service), SMS, WhatsApp, Facebook Messenger, Apple Messages for Business
- Email: Inbound email processed as agent conversations via Einstein for Service
- Voice: Agentforce for Voice (GA in 2025) handles inbound call transcription and real-time agent assist or full autonomous handling
- Internal channels: Slack (via Slack AI integration), Salesforce internal pages via Einstein Copilot
Each channel has its own configuration in Setup → Messaging Settings or Einstein Copilot Settings. The same agent can be deployed across multiple channels simultaneously — but the agent's behavior should be tuned for each channel's interaction patterns. Voice conversations require shorter, clearer responses than web chat. Email allows more structured formatting.
Layer 2: Agent definition
The agent definition is the top-level configuration that governs an agent's overall behavior. It contains three elements:
Role description
A natural language description of what the agent is, what it does, and what it's responsible for. This is the most important configuration in the entire system. The Atlas reasoning engine reads this at the start of every conversation to orient its behavior. Vague role descriptions produce inconsistent agents.
Scope definition
What the agent is and isn't allowed to handle. Define the explicit boundaries: what topics are in scope, what requests should be immediately escalated, what information the agent cannot access or share.
Guardrails
Specific prohibitions that override the agent's reasoning. Common guardrails include: never discuss competitors, never quote specific pricing, never make promises about timelines, always escalate legal or compliance questions. Guardrails are enforced at the reasoning layer — the agent cannot reason its way around them.
Layer 3: Topics
Topics are the categories of tasks an agent can handle. They are the most architecturally significant component of an Agentforce deployment, and the most commonly misconfigured.
Each topic contains:
- Classification description: Natural language text the LLM uses to decide if an incoming message belongs to this topic. Write this with extreme precision — overlapping or vague topic descriptions cause misclassification.
- Topic-level instructions: Additional guidance that applies only when this topic is active. Can include specific tone, required information to gather, or decision criteria.
- Action library: The set of actions the agent can invoke while this topic is active. An agent cannot call an action that isn't assigned to the active topic.
Topic design principles
Topics should be mutually exclusive and collectively exhaustive — every possible user request should map cleanly to exactly one topic. If you have overlapping topics, the agent will misclassify requests. If you have gaps, the agent will fall back to its base role description, which often produces unhelpful responses.
For a first deployment, 3–5 topics is optimal. We've seen agents with 20+ topics perform worse than agents with 5 well-defined ones.
Layer 4: Atlas reasoning engine
Atlas is the name Salesforce gives to the reasoning layer that powers Agentforce. It's a large language model (based on a combination of Salesforce-tuned models and, in some configurations, third-party LLMs via Model Builder) combined with a planning and execution system.
How Atlas processes a request
- Context assembly: Atlas gathers the conversation history, the agent's role description, the active topic's instructions, available actions, and any grounded data retrieved so far
- Topic classification: If no topic is active, Atlas reads the incoming message and selects the best matching topic
- Plan generation: Atlas generates a plan for how to respond — what information it needs, which actions to invoke, what order to execute them in
- Action execution: Atlas invokes the necessary actions, processes their outputs, and updates its plan if needed
- Response generation: Atlas generates a natural language response based on the gathered information and its instructions
- Guardrail check: The response is checked against the agent's guardrails before being sent
This loop repeats for each turn in the conversation. The entire process — from receiving a message to sending a response — typically completes in 2–5 seconds for standard requests.
Model Builder
Salesforce's Model Builder allows you to connect external LLMs (OpenAI, Anthropic, Azure OpenAI, Google Vertex AI) as the reasoning engine for your agents. This is used when the default Salesforce LLM doesn't meet performance requirements for specific domains, or when enterprise data residency requirements mandate a specific cloud provider.
Layer 5: Data grounding
Grounding is how Agentforce connects to real data to produce accurate, context-aware responses. Without grounding, the agent can only reason about what's in the conversation — it cannot look up records, check status, or verify facts.
CRM record grounding
The most important grounding source. Actions that query Salesforce objects (Get Record, SOQL queries) retrieve live CRM data during the conversation. The agent's responses are as accurate as your CRM data — which is why data quality is the foundation of every successful Agentforce deployment.
Knowledge base grounding
Salesforce Knowledge articles serve as the agent's reference library for product information, policies, and procedures. Articles are retrieved via vector search when the agent determines they're relevant to a request. Keep articles accurate, unambiguous, and well-tagged — conflicting articles are a leading cause of agent hallucinations.
Data Cloud grounding
For enterprises with Salesforce Data Cloud, agents can be grounded on unified customer profiles that combine CRM data with external sources — web behaviour, product usage, firmographic enrichment. This enables personalization that goes far beyond what's available in standard CRM records.
Layer 6: Salesforce platform
Agentforce runs on top of the standard Salesforce platform. Agents execute as a named credential with a specific permission set — they can only access the objects and fields that the running user is permitted to see. Actions invoke standard Salesforce automations: Flows, Apex classes, and REST API callouts.
This is Agentforce's biggest architectural advantage over standalone AI tools: it doesn't need a separate integration layer. The agent's actions are native Salesforce operations, with all the platform's built-in governance, audit logging, and security controls applied automatically.
Common architecture mistakes
- Too many topics: Every topic you add increases classification complexity. Start with fewer, broader topics and split them only when you see misclassification in production.
- Actions with vague descriptions: The LLM decides which action to invoke by reading its description. Write action descriptions like API documentation — precise, with clear invocation conditions.
- Over-permissioned agents: Give agents the minimum permissions needed to do their job. An agent with write access to objects it shouldn't touch will eventually write to them.
- No fallback topic: Every agent should have a catch-all topic for requests outside its defined scope. Without one, out-of-scope requests produce unpredictable behavior.
- Stale knowledge articles: Articles that contradict each other or contain outdated information are the most common cause of agent hallucinations. Audit your knowledge base before building.