Designing Agentforce subagents, instructions and actions that behave predictably

An Agentforce agent is assembled from subagents, instructions and actions, with Agent Script and filters adding deterministic control. Where you draw the line between them decides whether the agent behaves the same way on its hundredth conversation as on its first. This guide covers the rename from topics to subagents, scoping a subagent, which rules belong in natural language and which in script or code, choosing action types, and a worked service example.

Reviewed 10 October 2026 7 min read

On this page

Topics are now called subagents
The building blocks and what each one controls
Scoping a subagent so the router can find it
Where each kind of rule belongs in an Agentforce agent
Choosing an action type: Flow, Apex, prompt template or external call
Grounding answers in records and knowledge without widening access
Guarding sensitive actions with variables and filters
Hypothetical example: a warranty-eligibility service agent
Questions and answers
Sources

Topics are now called subagents

The building blocks and what each one controls

Subagent: A unit of capability with a name, a classification description, a scope, instructions and a set of actions, defining one kind of request the agent can handle².
Classification description: The text the reasoning engine reads, together with the subagent's name, to decide which subagent a message belongs to².
Scope: A job-description style statement of what the agent may and may not do inside the subagent.
Instructions: Natural-language guidance on conversation flow, tone, action choice and business context. They are merged into a prompt, so they are not deterministic².
Actions: What the agent can execute: Flows, Apex and prompt templates, plus MuleSoft APIs, External Services and predictive models with additional licenses².
Agent Script: Salesforce's scripting language for agents, combining configuration, variables, conditions, transitions and reasoning instructions in one readable file; Salesforce's guide calls it Agentforce Script³.
Variables and filters: Variables hold session context or action outputs, and filters use them to remove subagents or actions from consideration deterministically².

Scoping a subagent so the router can find it

Give it one job
Name the subagent after a single customer goal, such as checking warranty eligibility, not after a department. A subagent that covers everything a team does competes with every other subagent.
Write the classification description from real requests
Use phrases customers actually type, taken from case and chat history, and state the boundary. The router reads only the name and description when it classifies².
List what is out of scope
Write exclusions into the scope, for example that the subagent cannot change contract terms or quote prices, so neighboring requests route elsewhere or escalate.
Attach only the actions this job needs
Fewer actions means fewer wrong choices and lower latency. Salesforce's legacy guide advises capping both the subagents per agent and the actions per subagent².
Decide how it ends
Choose the exit for each path: answer and close, move to another subagent, or hand over to a person with a summary.

Where each kind of rule belongs in an Agentforce agent

Salesforce's guidance is consistent: instructions for behavior, script and actions for control³. This table applies that principle to common rule types.

Kind of rule	Put it in	Why
Tone, wording and how to ask for missing details	Instructions	These shape conversation quality and can tolerate some variation
A mandatory order, such as verifying identity before any account change	Agent Script, or a filter on a verification variable	The order must hold every time, so it cannot depend on how the model reads a sentence
Eligibility thresholds, refund limits and date windows	The Flow or Apex action itself	Code gives the same answer for the same inputs and can be unit tested
Moving to another subagent or closing the session	Agent Script transitions	Scripted transitions run with certainty instead of waiting for the router to infer intent³
Which actions exist at all in a given state	Action-level filters	Unavailable actions are removed from consideration rather than discouraged in prose²
Absolute words such as always and never	Avoid them in instructions, or back them with logic	Salesforce warns that absolute terms are read literally and can misfire²

Choosing an action type: Flow, Apex, prompt template or external call

If
The step reads or updates Salesforce records with clear rules, and an admin will maintain it.
Then
Use a Flow action.
Flows are low-code, need no additional license and stay visible to the admins who own the process².
If
The logic is complex, needs callouts or must be unit tested like other code.
Then
Use an Apex action.
Apex suits pro-code rules and record retrieval and fits existing code review and deployment practice².
If
The step drafts text, such as a summary or a reply, from record data.
Then
Use a prompt template action.
Prompt templates generate content but make no decisions and take no actions on their own³.
If
The data lives in an external system with an OpenAPI description or a MuleSoft layer.
Then
Use an External Service or MuleSoft API action, once licensing is confirmed.
Both are built for external calls and need additional licenses².
If
A standard agent action already does the job.
Then
Use it before building a custom one.
Salesforce recommends checking standard actions first, which avoids maintaining duplicate logic³.

Grounding answers in records and knowledge without widening access

Agents ground answers in two ways: actions that read records, and retrieval over knowledge. Record-reading actions run with the agent user's permissions, unless a Flow is set to run in system context, in which case it can read beyond them. Check both before assuming the agent sees only what a service rep would.

Knowledge retrieval runs through Data 360, which indexes and chunks content and creates the retrievers behind actions such as answering questions with knowledge³. Retriever filters narrow what each turn can draw on, for example by product line or region, and citations let reviewers trace an answer back to the article it used³.

Guarding sensitive actions with variables and filters

0 of 6 checked

Require a verified-identity variableHide account and payment subagents until an authentication action sets the variable, as Salesforce's filter guidance describes².
Require the record identifier firstKeep order or case actions unavailable until an order number or case ID is captured and validated.
Validate inputs inside the actionCheck format, ownership and limits in the Flow or Apex, and return a clear error the agent can relay.
Confirm before changing anythingHave the agent restate the change and wait for an explicit yes before calling an action that updates a record.
Use context variables for fixed factsContext variables are set when the session starts and cannot change during it, which suits facts such as channel or verified contact².
Record the decision on the caseWrite the action's inputs, result and reason to the record so people can audit what the agent did.

Hypothetical example: a warranty-eligibility service agent

Hypothetical example

Imagine a consumer electronics company that wants its service agent to answer whether a repair is covered. The team creates one subagent, Warranty eligibility, whose classification description borrows phrases from past chats, such as cracked screen still under warranty, and whose scope excludes refunds and pricing.

Agent Script requires a verified contact and a serial number before anything else happens. A Flow action looks up the asset, purchase date and entitlement and returns covered, not covered or needs review, so date arithmetic never sits in the prompt. Instructions cover tone and how to explain each outcome. When the Flow returns needs review, a transition hands the conversation to the warranty queue with the asset details attached, and the case records the decision either way.

Questions and answers

How many subagents should one Agentforce agent have?

As few as the job allows. Salesforce's legacy guide recommends keeping to between ten and fifteen subagents per agent, because overlapping subagents make routing inconsistent². For a first workflow, start with one or two and add more only when batch tests show the router reliably keeps them apart.

What happens when two subagents overlap?

The router may pick either one, and its choice can change between runs. Sharpen both classification descriptions with explicit exclusions, merge subagents that really serve the same goal, or use filters so only one is available in a given state. Batch tests that assert the expected subagent show whether the fix worked.

Can actions be reused across subagents and agents?

Yes. Salesforce notes that one action can be assigned to more than one subagent², and the same Flow or Apex class can back actions in several agents. Reuse works best when each action carries a short, precise description of what it does and returns, because the reasoning engine reads that description when deciding whether to call it.

Does the rename to subagents affect agents we already built?

Salesforce states that functionality is unchanged: existing topics keep working and are now labeled subagents¹. Expect a period in which documentation, training and screens use both terms. If you automate against metadata or Agent Script, check the current developer documentation for identifier names rather than assuming they changed along with the labels.

Sources

Agent Script Reference — Salesforce Developers · checked 10 October 2026
Legacy Guide: Agentforce Reasoning, Subagents, Instructions, and Actions — Salesforce · checked 10 October 2026
The Agentforce Guide to Context Engineering — Salesforce · checked 10 October 2026

Get a second opinion on your subagent design

Share your draft subagents, their classification descriptions and the actions attached to each. We will point out overlaps, rules that belong in script or code, and the tests that would prove the design.

Review my agent design

Topics are now called subagents

The building blocks and what each one controls

Scoping a subagent so the router can find it

Give it one job

Write the classification description from real requests

List what is out of scope

Attach only the actions this job needs

Decide how it ends