> ## Documentation Index > Fetch the complete documentation index at: https://docs.poly.ai/llms.txt > Use this file to discover all available pages before exploring further. # Managed topics > Create curated topics with sample questions, answers, and actions to handle common caller requests. Managed Topics define what your agent knows and how it responds. Each topic has sample questions, an answer, and optional actions (handoffs, SMS, tool calls). Topics cover the questions callers ask most: return policies, store hours, appointment availability, account lookups. Managed Topics are found under **Build > Knowledge > Managed Topics tab**. **Use Managed Topics when** you need precise control over what the agent says, or when the answer should trigger an action (SMS, handoff, tool call). **Use [Connected Knowledge](/connected-knowledge/introduction) instead** when you want to expose large volumes of external content (help articles, PDFs, FAQs) without curating individual topics.
[Agent Builder](/studio-assistant/introduction) pre-populates your Managed Topics from the URL or document you gave it at sign-up. Skim what it built, then ask in plain language to fix anything that's off ("tighten the refund answer", "add a topic for store hours"). You can also edit topics directly in this tab.
If you need to add custom logic to your topics, such as API calls, data lookups, or conditional behavior, see the [Tools](/tools/introduction) section under **Build** in the sidebar.
## The Managed Topics interface Searchable, filterable list of all topics. Click any topic to edit its content, sample questions, or actions. Supports bulk CSV import, activation toggling, and deletion. ## How retrieval works Retrieval-augmented generation flow for Managed Topics The agent **does not** see all MTs at once. Instead, it uses [retrieval-augmented generation (RAG)](/managed-topics/RAG/introduction) to find the best match for the user's message. 1. The retriever compares the message to the topic's **name**, **sample questions**, and **content**, with higher weighting given to the name and sample questions. 2. It returns the top matching topics to the LLM. 3. The [LLM](https://en.wikipedia.org/wiki/Large_language_model) selects the best match and generates a reply (and may trigger an **[action](/managed-topics/how-to-setup-action/introduction)**). [Raven](/agent-settings/raven) is the recommended model. It grounds answers in retrieved topics, says "I don't know" instead of hallucinating, and converts topic content into natural responses without example utterances. ## Types of Managed Topic entries ### Simple FAQ Used when the agent just needs to answer a question with no follow-up or action required. #### Single turn One message in, one message out. * Add a short, helpful reply in `content`. * Leave `actions` empty. #### Multi turn Ask a clarifying question before giving the answer. * Use branching inside `content` to structure the reply. * Leave `actions` empty. multi-pet_policy ### Handoff Used when the agent should offer to connect the user to a human agent. #### Offer Agent replies, then offers to transfer. * `content`: Include the answer and the offer. * `actions`: Trigger `transfer_call` (or another [handoff function](/call-handoff/introduction)) only if the user accepts. handoff_offer-spa #### Direct Immediate transfer with no agent reply. * Leave `content` empty. * Always run `transfer_call` in `actions`. handoff-direct-billing #### Conditional Transfer based on user clarification, for example, group size or request type. * `content`: Ask a disambiguating question. * `actions`: Map each answer to the correct destination. handoff_conditional-room_reservation ### Outbound messaging Used when you want to send a follow-up message via SMS or WhatsApp. #### Offer Offer to send a link via message. * `content`: Include a short message and ask for consent. * `actions`: If accepted, call `start_sms_flow`. See [SMS setup](/sms/introduction) for details. SMS_offer #### Conditional Let the user choose which message to receive. * `content`: Ask a branching question. * `actions`: Map answers to different `sms_id`s. SMS_conditional ### Info only Used for static reference material (like opening hours or prices). No interaction or action required. * Fill `content`. * Leave `actions` empty. misc_info_dump_opening_hours ## Entity extraction and structured data collection Managed Topics do not support entity extraction directly. If you need to collect structured data (names, dates, phone numbers, etc.) when a topic is matched, trigger a flow from the topic's action and configure [entity extraction](/flows/no-code/entities) in that flow's steps. There are two ways to trigger a flow from a topic: ### Using the /Flow shortcut (no code) In the topic's **Actions** field, type `/Flow` to insert a flow action. Select or create the target flow. When the topic matches, the agent enters the flow and can begin collecting entities. ### Using a tool call (code) Alternatively, add a tool call action to the topic that calls `conv.goto_flow()`: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} def start_booking_flow(conv: Conversation): conv.goto_flow("Collect booking details") return ``` This approach is useful when you need additional logic before entering the flow, for example, storing the originating topic name in `conv.state` so the agent can return to it after the flow completes. ### Returning to the topic after a flow If the agent is answering an FAQ and takes a detour through a flow (e.g. to collect a date or verify identity), the agent can pick up where it left off after exiting the flow. To do this: 1. Before entering the flow, store the topic name in state (e.g. `conv.state.original_topic = "how_to_make_claim"`). 2. In the flow's exit function, check the stored topic and return a prompt directing the LLM back to the relevant topic content. This avoids a generic "Is there anything else I can help with?" when the caller's original question has not yet been answered. For the full triggering-flows reference, see [Triggering flows](/flows/triggering-flows). ## Best practices ### Writing good sample questions Include at least **3 sample questions** per topic (maximum 20). This baseline helps the AI generalize intent across typical phrasings. For broad topics, add more to ensure better coverage. * Focus on variety in **language and structure**, don't just make minor rewrites of the same sentence * Think about how real users might describe the same issue, confused, specific, vague, or using non-standard terminology * Additional examples should reflect **distinct phrasings**, not slight rewordings * Vary sentence lengths alongside phrasing variety * Consider including short queries ("billing help") alongside full questions ("Why was I charged twice this month?") If migrating from an intent-based project, you might have more than 10 sample questions. Focus on keeping the most diverse items that preserve the full semantic scope of the original list. ### Topic naming Because the topic **Name** is shown to the retriever, it should be semantically close to the topic content. For instance, a topic about payment disputes named "general\_behavior-payment" will likely trigger on payment queries in general rather than only on disputes. * Make topic names **semantically descriptive**, the name should clearly reflect what the topic is about * Avoid generic names like `Misc`, `Help`, `Info`, or `General` * Use natural language: `Payment dispute resolution` is better than `payment_dispute_v2` ### Writing topic content * Keep replies **brief, helpful, and consistent** with your brand style * Give the agent **one task per turn**, do not mix text responses and tool calls in the same round * Break down multi-step processes into **multiple turns or topics** rather than cramming everything into a single entry * For multi-turn topics, structure the conversation so each turn has a clear purpose (ask a question, provide information, or trigger an action) * After answering a simple FAQ, ensure the agent asks if the user needs more help, either in the topic content or in the [Behavior](/agent-settings/rules) section ### Using actions effectively * Use `actions` **only when necessary**, if the agent just needs to answer a question, leave actions empty * Limit to **one action per turn** for reliability * When an action requires a handoff, include the handoff utterance as a parameter to `transfer_call` rather than mixing a `content` response with the action * For conditional actions (transfer to different destinations based on caller response), use the disambiguating question in `content` and map each answer to its destination in `actions` ### General guidelines **Do this:** * Use specific topic names. * Add **3–20** realistic sample phrasings per topic. * Keep replies short, helpful, and on-brand. * Use `actions` only when necessary. * Split multi-part flows into separate turns or topics. * Give the agent one task per turn, either speak or act, not both. **Avoid this:** * Bundling multiple intents into one topic. * Running more than one action in a single turn. * Using vague topic names like `Misc`, `Help`, or `Info`. * Mixing text and tool calls in the same turn. ### Common anti-patterns **Mixing text and tool calls in one turn:** For best results, split utterances and tool calls into separate turns, give the agent one task per turn. When a topic requires both a spoken response and an action, structure it so the response happens in one turn and the action in the next. Turn 1: Agent answers the question and asks if the user wants to be transferred. Turn 2: If the user says yes, call `transfer_call` with a handoff utterance. Single turn: Answer the question, then immediately call `transfer_call` with utterance, the agent may skip one of these tasks. **Overloading a topic with multiple intents:** If a topic covers "billing questions" but includes return policies, refund processes, and payment methods, it becomes too broad. Split each into its own topic with specific sample questions. **Missing follow-up prompt:** Without a follow-up question like "Is there anything else I can help with?", the agent may hallucinate a next step. Add this to each simple FAQ's content or configure it in the [Behavior](/agent-settings/rules) section. ## Live collaboration Multiple users can edit Managed Topics at the same time. Changes are synced in real time, so you can collaborate on topic content without overwriting each other's work. ## Activating and deactivating topics kb-toggle Not every topic needs to be available all the time. You can temporarily **deactivate** a topic to keep it out of retrieval without deleting it or removing its content. * Inactive topics are **ignored by the [LLM](https://en.wikipedia.org/wiki/Large_language_model)** and marked clearly in the UI. * Activation status is **environment-specific**, so you can test changes safely in Sandbox before going live. Learn more about [environments and versions](/environments-and-versions/introduction). * CSV import/export includes an `Active` column (`Y`/`N`) for bulk updates. This is useful for seasonal articles, phased rollouts, A/B tests, or hiding content that is not ready for production.
## Automate with the Agents API If you already have a knowledge base somewhere else (a help center, CMS, or intents list), you can create and sync topics programmatically instead of clicking through the UI. The [Agents API](/api-reference/agents/introduction) has full CRUD for knowledge base topics. This is especially handy for the initial migration or for scheduled syncs from an external source. ```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}} # Create a knowledge base topic on the main branch curl -X POST https://api.us.poly.ai/v1/agents/AGENT_ID/branches/main/knowledge-base/topics \ -H "x-api-key: $POLYAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Password reset", "sampleQuestions": ["How do I reset my password?", "I forgot my password"], "content": "To reset your password, visit the account portal..." }' ``` ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}} import os, requests BASE = "https://api.us.poly.ai" HEADERS = {"x-api-key": os.environ["POLYAI_API_KEY"]} # Sync all FAQ entries from your CMS into PolyAI topics for faq in cms.list_faqs(): requests.post( f"{BASE}/v1/agents/{AGENT_ID}/branches/main/knowledge-base/topics", headers=HEADERS, json={ "name": faq["title"], "sampleQuestions": faq["variants"], "content": faq["answer"], }, ) ``` See [Knowledge base endpoints](/api-reference/agents/endpoint/knowledge-base/list-knowledge-base-topics) for the full list.
## Resources Add tool calls, handoffs, and SMS triggers to topics. Common issues with topics, rules, and actions. Keep topics accurate and up to date over time. Create and sync topics via the Agents API.