Salesforce Agentforce Routing & Subagent Architecture: Best Practices & Limits

⚡ 1-Minute Summary

• The Agent Router selects exactly one subagent per user message by evaluating each subagent's description.
• Overlapping subagent descriptions create unpredictable routing decisions—the single biggest driver of erratic agent behavior.
• Aim for 5 to 8 focused subagents. Remember the hard platform limits: 15 subagents per agent and 15 actions per subagent.

Architecture Overview

root: 'Who handles this message, and how do we know it was right?'
├─ The Agent Router (start_agent)
├─ Subagent design and description overlap
└─ The 15-subagent ceiling

The Agent Router

💬 In plain words: The router acts like a traffic controller. It evaluates the incoming user message and forwards it to a single specialized subagent. It doesn't perform tasks or answer user questions directly—in Agent Script, it is defined by the start_agent block.

📌 Real-World Example: A customer sends a message saying, "The whole street is dark." The router itself doesn't possess outage domain logic. Instead, it scans all registered subagent descriptions, matches the prompt to a subagent handling power outages, and hands off the conversation.

How Routing Works

• The start_agent block is labeled the Agent Router in the Canvas view (previously referred to as the Topic Selector).
• It functions as an entry subagent using the start_agent prefix rather than standard subagent identifiers.
• Every incoming user request processes through this router, including the initial turn of a conversation session.
• Its role is strictly focused on classification, filtering, and delegation.
• It is commonly used to instantiate session-level variables upon start.
• Classification relies entirely on reading each subagent's description attribute rather than inspecting underlying code execution or action logic.
• When a single-turn transition finishes, control returns to the router to process the next incoming message.
• Because of this architecture, routing accuracy serves as your primary health metric for agent performance.

start_agent (Agent Router)
├─ Set initial session variables
├─ Parse incoming utterance
├─ Evaluate against subagent DESCRIPTION values
└─ Delegate to exactly ONE subagent
        ↓
   Subagent executes task (Router execution pauses)

🧠 Single Responsibility: The router evaluates and forwards messages. It does not process task outputs directly.

🧭 360 Card — Agent Router Design

• Rule: Treat routing performance as a measurable metric. Inspect execution logs and traces rather than relying solely on generated output responses.
• Gain: Identify routing mismatches during testing before they affect end users.
• Cost: Creating an extensive evaluation dataset of representative user utterances requires intentional design effort upfront.
• Limits: Routes to exactly 1 subagent per turn. Maximum limit of 15 subagents per parent agent.
• Common Pitfall: Avoid judging routing accuracy by response tone alone. A misrouted subagent may generate a convincing answer using incorrect business logic.
• Production Tip: Track routing accuracy as a core KPI during deployment. A sudden drop in accuracy typically signals overlapping subagent descriptions introduced in recent releases.

⚠ Developer Trap: Do not assume the Agent Router dynamically infers intent without precise metadata. The model matches user input against subagent description text. Vague or ambiguous descriptions degrade routing reliability regardless of the underlying foundation model's capability.

Architectural Interview Q&A

Q: How does Salesforce Agentforce determine which subagent should process a user message?

🎯 Core Point: The Agent Router evaluates the user input against each subagent's written description to assign execution to exactly one subagent.

Every request originates at the start_agent router level. Subagent descriptions act as explicit instruction sets for the routing engine rather than passive documentation. When two subagents share ambiguous boundaries, routing decisions become unpredictable. To maintain execution integrity, always validate routing pathways directly within event execution traces and evaluate updates against a standardized test suite of target utterances.