Tutorial: Add a simple topic
Lesson 3 of 6 – Time to teach your agent something useful. You’ll create a simple topic that answers one question – like “what time do you close?” – in both Chat and Call.
A Managed Topic is how your agent learns to answer questions. In this lesson, you’ll create the simplest kind: one question, one answer, no follow-ups.
What “simple” means
Simple topics
Not simple
- Completes in one turn
- Requires no clarification
- Triggers no actions
- Works the same way in Chat and Call
If a topic needs any of those features, it should be implemented as a complex topic instead. These will be covered in more detail in Level 2: Advanced of the PolyAcademy.
Is your idea a simple or complex topic?
Use this decision tree before writing anything:
Check your understanding
What defines a simple Managed Topic?
- It uses at least one action like SMS or handoff
- It asks the user a follow-up question to clarify intent
- It completes in one turn, needs no actions, and requires no clarification
- It combines multiple related questions into a single response
Answer: It completes in one turn, needs no actions, and requires no clarification
A simple Managed Topic completes in one turn, triggers no actions (no SMS, handoff, or routing), and requires no clarification from the user.
Before you start: define your intent
Answer these questions before creating the topic:
- What is the exact question being answered?
- Can a human answer it in one short response?
- Can users reasonably phrase this question in several different ways?
If the topic answers more than one question, split it.
Example: single intent
- “What time do you close?”
Example: multiple intents
- “What time do you close and do you have holiday hours?”
These should be two separate topics.
Step 1: Choose a precise topic name
The topic name is the strongest signal for retrieval.
Good topic names:
- Describe one intent
- Are specific, not general
- Use
snake_case
Examples
closing_timeparking_costpet_policy
Avoid names that are broad or vague.
Avoid
infogeneralshop_questionsmisc
Step 2: Write sample questions
Sample questions teach the retriever how users phrase requests. As a baseline, aim for at least 3 sample questions per topic. If the topic is broad or users phrase it in many different ways, include more – up to 20.
Add variations that reflect real speech. Include:
- Short questions
- Polite phrasing
- Informal or incomplete phrasing
- Call-style filler words
- Different sentence lengths
Example: closing_time sample questions
- what time is closing
- closing time
- when do we have to leave
- when do you shut
- what time do we need to be out by
- uh what’s the closing time
Focus on variety in language and structure, not slight rewordings. Think about the different ways real users might describe the same issue – whether they are confused, specific, vague, or using non-standard terminology.
Avoid:
- Repeating the same sentence with small wording changes
- Writing marketing-style language
- Including answers
How retrieval works
The retriever compares the user’s utterance to the topic Name, Sample questions, and Content to find the closest semantic matches. The top matches are then sent to the LLM, which makes the final decision on which topic to use.
These signals are not weighted equally. The topic name is the strongest retrieval signal, followed by sample questions, then content. This means a precise topic name has more impact on retrieval than a large number of sample questions.
Because the Name is shown to the retriever, it should be semantically close to the intent. A vague name like general_behavior-payment may trigger on any payment-related utterance instead of only the specific payment issue you intended.
Step 3: Write the Content response
The Content field is the agent’s full response.
It should be:
- Short
- Direct
- Easy to understand when spoken
- Complete on its own
Use this structure:
- State the answer clearly
- Optionally mention one next step
- Stop
Example: closing_time content
This works because:
- The answer comes first
- The response ends cleanly
- No action is triggered
Avoid:
- Explanations or justification
- Policy language
- Multiple offers or options
Avoid
This reads well on a page but performs poorly.
Step 4: For now, leave Actions empty
For a simple Managed Topic:
- Do not add Actions
- Do not reference functions
- Do not trigger handoff or SMS
If an action is required, the topic is no longer simple and should be rewritten as a complex topic.
Common simple Managed Topic patterns
Static information
Topic name: opening_hours
Content:
Policy statement
Topic name: pet_policy
Content:
Location information
Topic name: parking_location
Content:
Price reference
Topic name: parking_cost
Content:
Check your understanding
What is the strongest signal for Managed Topic retrieval?
- The sample questions list
- The topic content or answer text
- The topic name
- The topic description field
Answer: The topic name
The topic name is the strongest signal – it should describe exactly one intent, be specific rather than generic, and use snake_case. Sample questions come second, then content.
Verification
Test in Chat
Ask the question using:
- Exact phrasing
- Informal phrasing
- Polite phrasing
- Abrupt phrasing
Confirm:
- The same topic triggers every time
- The response does not change
- No follow-up question is asked
Live, in the test panel, look for the topic citations to confirm which topic was recalled by the agent.
Test in Call
Ask the same question out loud, including hesitation or filler words.
Confirm:
- Speech is transcribed correctly
- The response sounds natural when spoken
- The agent does not over-explain
In conversation review, make sure topic citations are enabled:
Final checklist
Before moving on, confirm:
- The topic answers exactly one question
- Sample questions reflect real user phrasing
- Content is short and speakable
- Actions are empty
- The topic behaves the same in Chat and Call
Try it yourself
Challenge: Write a pet_policy topic
Write a complete simple topic for a store that allows only service animals.
Include:
- Topic name (snake_case)
- Five sample questions
- Content (one to two sentences)
Hint
The topic name should describe exactly one intent. Sample questions should reflect how real users speak – including informal and spoken phrasing. Content should be speakable and complete in one or two sentences.
Example solution
Topic name: pet_policy
Sample questions:
- are pets allowed
- can I bring my dog
- do you allow animals
- is my cat allowed inside
- what’s your policy on pets
Content:
Check your understanding
Should a simple Managed Topic include Actions?
- Yes – always add at least one action as a fallback
- Only if the user explicitly requests it
- Yes – SMS and handoff actions are always safe to include
- No – if an action is needed, the topic is no longer simple
Answer: No – if an action is needed, the topic is no longer simple
If an action is required (SMS, handoff, routing), the topic is no longer simple and should be rewritten as a complex topic.
A Managed Topic that answers one question in one turn, requires no clarification, and triggers no actions is called a _____ topic.
Answer: simple, Simple
Go deeper
Want the full reference for FAQs? These pages cover everything – including the more complex topics you’ll learn in Level 2: