The short version: a topic is a scope boundary. It decides which instructions and which actions exist for the current turn, and everything outside it is invisible while that topic is active. Instructions are behavioural rules inside that boundary, not a prompt written to sound persuasive. Most agents that route badly are not badly instructed. They have too many topics with descriptions that overlap.
What a topic actually does
On each turn the agent classifies the user’s message against the topic descriptions and selects one. From that point the working set is small: that topic’s instructions, that topic’s actions, whatever context is attached. The other topics might as well not exist.
Which is why a topic is a boundary rather than a folder. Putting an action in a topic is a statement that the action is available only when the conversation is about that subject. Putting the same action in five topics is a statement that you have not decided.
Classification is the part that breaks
Topic selection is a classification over short, ambiguous text, and a real user’s opening message is rarely a clean statement of intent. “It’s still not working” has to land somewhere.
Two descriptions that overlap will be confused, and the confusion is not stable. It shifts with phrasing, with conversation history, and with model updates. This is the single biggest source of “it worked last week” reports.
Write each description so it names the cases it owns and excludes its near neighbours. “Billing enquiries about existing invoices and payment status. Not refunds, not contract changes, not new orders.” The exclusions do more work than the inclusions.
Instructions are rules, not persuasion
An instruction should read like a policy line a new employee could follow without interpretation. Short, imperative, checkable.
- Always confirm the account name before calling an action that updates a record.
- If the customer has no active contract, say so and stop. Do not offer alternatives.
- Use the Get Invoice Status action for any question about whether an invoice has been paid.
Weak instructions describe a mood. “Be helpful and empathetic while providing accurate information” is not checkable. Nothing observable follows from it and nothing fails when it is ignored, but it is still read on every turn.
A useful test: could you write a pass or fail assertion for this line? If not, it is decoration.
Why too many topics degrades routing
Each extra topic is another candidate for the classifier and another opportunity for overlap. The degradation is gradual and then sudden. Ten well separated topics usually behave. Forty, added by different people over six months, usually do not.
The failure pattern is consistent. A question that used to reach topic A starts landing in topic B, which lacks the action needed, so the agent apologises or improvises. Nobody touched topic A. Somebody added topic Q, whose description happened to overlap.
Signs you already have too many:
- Two topics you cannot tell apart in one sentence each.
- The same action attached to three or more topics.
- A topic that fires for well under one per cent of conversations.
- Instructions repeated word for word across several topics, which usually means the boundary sits in the wrong place.
A structure that holds
Start with fewer topics than feels natural, each with a wide scope and tight instructions. Split only on evidence: a topic whose instructions have grown contradictory, or one where two genuinely different workflows keep interfering with each other.
Keep a written list of topic names with a one-line scope and a one-line exclusion for each. Read it end to end before adding another. If the new topic cannot be described without referring to an existing one, it is probably an instruction inside that topic instead.
Frequently asked
Can an agent use two topics in one turn? Behaviour here has changed between releases, so check the current documentation rather than a blog post. Design as though it cannot, because an answer needing actions from two topics usually means one boundary is drawn wrongly.
Where do global rules go? In the agent-level instructions, which apply across topics. Keep them short. They are paid for on every turn and they compete with topic instructions rather than cleanly overriding them.
How long should instructions be? Shorter than you want them to be. Long instruction blocks get partially followed, and which part gets dropped is not predictable from one run to the next.
Do instructions guarantee behaviour? No. They shift probabilities. Anything that must always happen belongs inside the Flow or Apex behind an action, where it is code rather than guidance.
