SfSkills Domains Docs GitHub

Home / agentforce / agent-topic-design

agent-topic-design

Use when designing or reviewing Agentforce topic (renamed subagent in April 2026) structure, including topic boundaries, instruction quality, handoff rules, out-of-scope behavior, and topic-selector strategy.

Open the skill folder on GitHub

Agent Topic Design

Use this skill when the agent's real problem is scope design, not model tuning. Subagents — called topics before April 2026, and still labelled that way in older documentation, in metadata API names, and in many orgs — are how Agentforce understands which job it is doing at a given moment. The rename changed nothing about behaviour. A weak subagent design creates overlapping instructions, confused routing, and actions appearing available in the wrong conversational context. A strong subagent design keeps the agent focused, predictable, and honest about what it cannot do.

The core job is to draw clean domain boundaries. A subagent should represent a coherent business capability with clear entry signals, clear exclusions, and a clear exit or handoff path. If the subagent description reads like a backlog label or a vague department name, the agent will not have enough structure to choose well. Agentforce guidance emphasizes small, explicit subagent sets and deliberate use of topic selectors when the domain becomes too broad.

Current official guidance emphasizes keeping subagent sets tight and using clear boundaries ("Limit subagents: Start with essential subagents and add more gradually as needed", Agentforce Developer Guide, Agent Router pattern). The number fifteen that circulates in this space is the Generative AI guide's recommendation of no more than 15 actions per topic; no source read for this revision gives a topic-count threshold for adding a router. The agent classifies each utterance into the single most relevant topic by comparing it to every topic's name and classification description, which means the subagent boundary must be specific enough to drive the right instructions and action set.

Terminology. This skill leads with subagent because that is the current product term. It deliberately keeps topic in metadata and API names, in the "topic selector" pattern name, and in search keywords — those did not change, and readers arriving with the older vocabulary still need to find this skill.

Before Starting

Check for salesforce-context.md in the project root. If present, read it first.

Gather if not available:

Questions to Ask Before Configuring

QuestionWhy it mattersWhat a good answer addsWhat proper configuration adds over just doing it
What jobs must the agent do, stated as one sentence each?The agent picks a topic by comparing the utterance to topic names and classification descriptions (Generative AI guide, What are Agents?).A capability list that becomes topic names and 1–3 sentence classification descriptions.Routing has distinct signals to work with instead of department labels.
Which requests must the agent refuse or hand to a person, and under what conditions?Escalation is designed per topic: GenAiPlugin.canEscalate, Agentforce Service Agent topic instructions, or @utils.escalate with an Omni-Channel connection.A handoff rule list per topic with the context to collect first.Users reach a person with context instead of looping.
Which business rules must always hold, regardless of wording?Instructions are nondeterministic; the guide says deterministic rules belong in the action's logic, not in topic instructions.A list of hard rules mapped to actions or deterministic transitions.Refund limits and eligibility checks hold every time.
Which actions does each topic need, and which are shared?An action can be added to multiple topics, and the guide recommends no more than 15 actions per topic.An action-to-topic matrix with counts.Topics stay small without duplicating actions.
Are topics built in Agentforce Builder per agent, in the asset library, or in Agent Script?In Winter '26 and later, topics created inside an agent are retrieved through GenAiPlannerBundle, while asset-library topics are GenAiPlugin; Agent Script agents live in AiAuthoringBundle.The metadata type the team will version and deploy.Retrieves and deployments pick up the topics that are actually live.
How will routing be tested after each change?Adding a topic can pull intents away from existing ones; AiEvaluationDefinition test cases can assert topic_sequence_match.A routing test set with expected topics per utterance.Regressions show up in a test run, not in production transcripts.

Core Concepts

A Subagent Is A Capability Boundary

Subagents are not team names, project codes, or loose labels. A subagent should map to a real capability such as case deflection, order status, or appointment rescheduling.

What makes a good subagent name:

Subagent Instructions Need Both Inclusion And Exclusion

A subagent that only says what it does is incomplete. It should also say what it does not do and when to hand off or refuse.

Subagent instruction template:

## What this subagent does
[Specific capability. One or two sentences.]

## When to activate
[Concrete user-intent signals that should route to this subagent.]

## What this subagent does NOT do
[Explicit exclusions. Important for avoiding over-selection.]

## Handoff rules
[Conditions that cause the subagent to escalate, refuse, or route elsewhere.]

## Actions available
[The narrow action set this subagent can use.]

The "does NOT do" section is where most subagent designs fall apart. Without it, the LLM will use the subagent for anything that's plausibly related.

Smaller Subagent Sets Produce Better Routing

When too many subagents compete for similar intents, the agent becomes less reliable. Keep the direct subagent set small and use a topic selector when the business domain is too large for one flat list.

UNVERIFIED (2026-10-03): the table below is a heuristic. No source read for this revision ties routing quality to these subagent counts; the documented numeric guidance is no more than 15 actions per topic.

Subagent countRouting qualityManagement cost
1-5ExcellentLow
6-10GoodLow-medium
11-15OK; requires disciplineMedium
16-25Degraded; need selectorMedium-high
25+Poor; selector mandatoryHigh

Handoff Rules Are Part Of Subagent Design

A subagent should define when it stays in control, when it escalates, and what information should be collected before that handoff occurs.

Handoff trigger types:

Each handoff type has different UX — escalation to a human is different from routing to another subagent.

Single Active Subagent Semantics

Only one subagent is active at a time in the Agentforce runtime. That means:

Design implication: an action needed by several subagents is added to each of them; the Generative AI guide says an action can be added to multiple topics. Earlier versions of this skill said such actions should not exist and must be duplicated per subagent OR moved to a shared "utility" subagent that has broader action access but narrower scope.

Common Patterns

Pattern 1: Narrow Capability Subagent

When to use: The agent handles one well-defined business job with its own signals and boundaries.

Structure: Write the subagent around the specific job. Include clear out-of-scope statements. Attach only the actions relevant to that job. The subagent's name, description, and instructions should all reinforce the one capability.

Example: Appointment_Reschedule only handles rescheduling existing appointments. It does NOT create new appointments (different subagent). It does NOT cancel (different subagent). Overlap is explicit and intentional.

Pattern 2: Topic Selector

When to use: The overall agent domain contains many potential subagents and one flat list would become noisy.

Structure: A higher-level "selector" (itself a subagent) whose only job is to classify user intent and route to the specific subagent. In Agent Script this is the agent router, the start_agent block; its tools are transitions such as go_to_orders: @utils.transition to @subagent.Order_Management, named with a go_to_ prefix (Agentforce Developer Guide, Agent Router pattern). The selector is minimal: no business actions, just routing.

Selector pattern:

User: "I need help"
Selector: identifies intent → routes to `Appointment_Issues` → specific subagent takes over

Pattern 3: Handoff-Ready Subagent

When to use: A subagent is useful up to a point, but certain cases need a person, queue, or alternate workflow.

Structure: Subagent instructions explicitly list:

Pattern 4: Persona-Scoped Subagent Family

When to use: Different personas need fundamentally different subagent sets (e.g. customer-facing vs employee-facing vs partner-facing agents).

Structure: Build separate AGENTS per persona. Each has its own subagent set. Don't try to use conditional instructions within subagents to handle persona differences — too easy to leak. Persona-scoped agents also have different Trust Layer posture (what data each can access).

Pattern 5: Utility Subagent

When to use: A narrow set of cross-cutting capabilities (greeting, farewell, small-talk redirect) that ANY subagent might need.

Structure: A lightweight subagent with a very narrow action set (maybe just "greet" and "farewell"). NOT a dumping ground for "everything else" — that becomes a general-help anti-pattern.

Decision Guidance

SituationRecommended ApproachReason
One coherent business job with clear signalsSingle narrow subagent (Pattern 1)Easier routing, safer instructions
Many overlapping candidate subagentsRefine boundaries OR add selector (Pattern 2)Reduces competition
Agent should stop after policy / risk conditionsExplicit handoff rule (Pattern 3)Prevents false confidence
Subagent sounds like a team/dept instead of a jobRewrite around the capabilityBetter activation signals
Subagent needs many unrelated actionsSplit it OR narrow action setKeep behavior predictable
Multiple personasSeparate agents per persona (Pattern 4)Avoids leaking context across personas
Cross-cutting concerns (greeting, small talk)Utility subagent (Pattern 5) with strict scopeAvoid "general help" anti-pattern
Domain has many candidate subagents with overlapping intentsAgent router (Pattern 2) with available when filtersFlat lists get harder to route; the threshold is a judgment call (UNVERIFIED count)

Review Checklist

Step-by-step instructions for an AI agent or practitioner activating this skill:

  1. Gather context — confirm business capabilities, persona set, handoff expectations, and the answers to the Questions table above
  2. Draft each subagent as the GenAiPlugin fields it will become: name, 1–3 sentence classification description, scope, instructions, actions (≤ 15), and canEscalate; a complete example is in references/metadata-examples.md
  3. Move every hard business rule out of instructions and into action logic or a deterministic transition
  4. Validate — run scripts/check_agent_topic_design.py against the retrieved metadata, then run an AiEvaluationDefinition routing test with topic_sequence_match expectations, and verify against the Review Checklist above
  5. Document — record any deviations from standard patterns and update the template if needed

Salesforce-Specific Gotchas

  1. A subagent with vague boundaries degrades both routing and action safety — the agent may activate the wrong capability for the right user question.
  2. Too many subagents are an architecture problem, not just a UX problem — competition between them lowers reliability.
  3. Handoff behavior is not a separate cleanup task — it belongs inside the subagent design from the start.
  4. One active subagent at a time means its wording must be sharp — fuzzy capability boundaries cannot be rescued later by prompt tuning alone.
  5. Subagent instructions are prompt context — they count against the model's token budget; extremely verbose instructions degrade other areas.
  6. Managed-package subagents may have opaque instructions — you see the subagent exists but can't see why it activates; coordinate with the vendor.
  7. Subagent names affect classification: The agent compares the utterance to each topic's name and classification description, so names are part of the routing signal. The detailed traps, with sources, are in references/gotchas.md.
  8. Adding a subagent changes routing behavior for existing ones — a new subagent can poach intents from established ones. Test regression paths.
  9. Instructions written for internal audiences don't generalize — if the instruction uses jargon only your team understands, the LLM often misroutes.
  10. Trust Layer settings are org-level, not per subagent: The Generative AI guide says Einstein Trust Layer settings "are applied to your Salesforce org", and Agent Script's citation and groundedness switches sit in the agent's config.runtime block. Earlier versions of this skill said masking and citation can differ per subagent.
  11. The April 2026 rename is cosmetic, but the vocabulary split is real — the UI says subagent while metadata, evaluation assertions, and older Help articles still say topic. Expect to read both in the same investigation.

Proactive Triggers

Surface these WITHOUT being asked:

Output Artifacts

ArtifactDescription
Subagent architecture reviewFindings on overlap, boundary clarity, selector need
Subagent rewrite guidanceBetter scope, exclusions, handoff wording
Selector recommendationWhether the agent needs scope narrowing before execution
Persona-scoping planAgent-per-persona decomposition when one agent can't serve all
Handoff rule catalogPer-subagent escalation triggers + destination + context-to-collect

Package files