Mastering Subagent Architecture in Salesforce Agentforce: Avoiding Description Overlaps and Ceiling Limits

💬 In plain words: A subagent is a focused specialist designed to handle one narrow type of request. The router uses each subagent's description to decide where to send a message. Overlapping descriptions are the single most common reason AI agents exhibit erratic behavior.

📌 Real-World Example: Meridian Utility had two subagents: "questions about power problems" and "questions about service issues." Every customer outage message matched both. As a result, routing accuracy hovered at an unreliable 58% until the subagent descriptions were overhauled to be distinct and mutually exclusive.

🎬 Real-Life Case Study: The Coin Flip Nobody Saw

• The Flawed Approach: A deployment team created three subagents described as "questions about repairs," "questions about service," and "questions about problems." End users complained that agent answers were wildly inconsistent.
• Why It Failed: Customer prompts matched all three descriptions simultaneously. The Agent Router made near-random picks. Because each subagent was smart enough to write a plausible response, the issue remained hidden until follow-up actions failed due to missing tools.
• The Solution:
  1. Read all subagent descriptions aloud sequentially.
  2. Write test sentences—if one sentence fits two subagents, rewrite them.
  3. Ensure each description targets a distinct user intent.
  4. Run an automated utterance test suite and record before-and-after routing scores.
• The Payoff: Routing transformed from an invisible, random guess into a transparent, measurable decision pipeline.

Core Subagent Architecture Concepts

• Subagents were previously called topics in earlier releases. The terminology updated, but the underlying mechanics remain identical.
• Each subagent independently manages its own instruction set, actions, and execution state.
• Salesforce recommended architecture favors 5 to 8 focused, narrow subagents over a single massive generalist agent.
• Because routing relies solely on descriptions, mutually exclusive description boundaries are a strict technical requirement.
• Provide 8 to 10 sample utterances per subagent during testing, including at least two edge or adversarial inputs.
• Subagent API developer names must follow snake_case without spaces or special characters.
• Always assign escalation handling to a dedicated subagent rather than a secondary fallback branch, ensuring seamless agent-to-human handoffs.
• Actions are scoped locally—importing an action into a subagent grants that specific subagent its own isolated execution instance.

Meridian Power — 5-Subagent Architecture Example
├─ outage_report      'reports loss of power at an address'
├─ bill_dispute       'questions a charge or a bill amount'
├─ tariff_change      'wants to switch or compare a tariff plan'
├─ meter_reading      'submits or queries a meter reading'
└─ escalate_to_human  'is unhappy or asks for a person'

GOLDEN RULE: Can one sentence match two descriptions?
If YES → Your descriptions need sharper boundaries.

🧠 Narrow focus creates visibility. Five specialized subagents make routing decisions measurable. One generalist subagent hides routing logic deep inside LLM reasoning.

🧭 360 Card — Subagent Design & Description Overlap

• Rule: Maintain 5 to 8 narrow subagents with mutually exclusive descriptions, verified using a scored utterance test set.
• Gain: Routing decisions become fully observable in execution logs and easily trackable via numeric accuracy KPIs.
• When to Expand: Add a new subagent only when live conversation data demonstrates a distinct user intent—never speculatively.
• Price: Requires managing, naming, and maintaining more granular metadata objects.
• Limits: Hard ceilings of 15 subagents per parent agent and 15 actions per individual subagent.
• The Monolith Risk: Building one broad subagent pushes routing decisions into the LLM context, making debugging impossible.
• Future Impact: Well-defined subagent boundaries later double as security permission zones and isolated testing units.
• At Scale: Descriptions crowd as your agent grows. Re-score your complete utterance test set every time a new subagent is deployed.

⚠ INTERVIEW TRAP: When asked how to fix misrouting, never answer "I would add more detailed instructions inside the subagent." Routing happens before subagent instructions are evaluated. The fix must always be made to the subagent's description field.

Core Q&A

Q: Why design five narrow subagents instead of one comprehensive subagent?

🎯 Say this first: Narrow subagents make routing measurable. Every routing decision is clearly recorded in the trace, allowing you to score and optimize performance metrics precisely.

The primary benefit of narrow subagents is operational observability rather than model intelligence:

• The Agent Router routes purely on descriptions, creating an explicit trace record for every turn.
• You can test user utterances against traces and calculate exact accuracy scores (e.g., 11 out of 12 correct handoffs).
• With a single monolith subagent, routing occurs internally within the LLM's prompt window—hidden from metrics and logs.
• Narrow subagents keep you safely beneath the 15-subagent limit while maintaining clean, lightweight action lists per specialist.
• They establish clear administrative boundaries for security permissions and deployment governance.
• Practical Test: Read descriptions side by side. If a single customer sentence validly triggers two subagents, refine your description boundaries immediately.

Scenario-Based Interview Follow-ups

Q1: Your Agentforce deployment starts giving erratic or unexpected answers. How do you troubleshoot?

Answer: Start with routing evaluation before inspecting instructions or code.

• Execute a benchmark utterance suite and open execution traces to identify which subagent handled each turn.
• In 90% of cases, erratic behavior stems from two subagent descriptions overlapping around shared concepts (e.g., billing vs. account status).
• Rewrite subagent descriptions to establish distinct intent boundaries, then re-test and score routing accuracy.
• Inspect inner instructions or Apex actions only after verifying that routing handoffs are 100% accurate.
• Common Mistake: Modifying internal instructions first. If the wrong subagent was selected initially, updating instructions inside that subagent will not solve the problem.

Q2: Business stakeholders request a 16th subagent on a single agent. What is your architectural plan?

Answer: This scenario hits a hard platform governor limit, requiring an architectural refactoring strategy rather than a workaround.

• Salesforce enforces a strict hard ceiling of 15 subagents per parent agent.
• First, audit existing subagents to identify potential merges where intent boundaries overlap.
• If business requirements genuinely demand more capabilities, split the architecture across multiple dedicated agents grouped by business domain.
• For enterprise scale, adopt an orchestrator pattern where a primary top-level agent routes requests to specialized downstream agents.