Skip to main content
Find answers to frequently asked questions about Knowledge (Managed Topics and Connected), rules, actions, and agent configuration. Start here if your agent isn’t answering correctly, changes aren’t live, or you need guidance on structuring topics and rules.

​
Common issues

This is usually a retrieval issue – the agent has the right topic, but the retriever didn’t match it to the user’s message.How to debug:
  1. Open conversation diagnosis for the affected conversation.
  2. Check the sources panel – does the relevant topic appear in the retrieved results?
  3. If the topic is not retrieved: improve the topic name and sample questions to better match how real users phrase the question.
  4. If the topic is retrieved but the agent still gives a wrong answer: review the topic content for ambiguity, or check whether a conflicting topic is also being retrieved.
The retriever weights topic name and sample questions more heavily than content. If a topic isn’t being found, rewriting these is the most effective fix.
Saving a change does not make it live. Changes go through a promotion pipeline (Draft → Sandbox → Pre-release → Live) before reaching production. Until you publish and promote, your changes stay in draft.See the deployment pipeline for full details, or the environments FAQ for common questions.
Tone and phrasing problems are best fixed through specific, example-driven global rules – not single-sentence personality instructions. Identify the problematic response in conversation review, add a rule with a concrete example of the correct behavior, and test in sandbox before promoting.See the rules FAQ and personality FAQ for detailed guidance.

​
Topic-specific FAQs

Managed topics

Topic structure, retrieval, sizing, and organization.

Connected knowledge

Differences from Managed Topics, when to use, and troubleshooting retrieval.

Rules

Global rules, examples, channel filtering, and edge case handling.

Actions

Action types, combining actions, variables, and debugging failures.

Personality and role

Setting tone, personality, and role configuration.

Environments and testing

Safe testing, deployment pipeline, and multi-site agents.

Technical considerations

ASR/TTS independence, token limits, and context management.

Support guide

Contact PolyAI support for further assistance.

Community

Join the PolyAI community on Slack.
Last modified on April 16, 2026