Skip to main content
Common questions about Knowledge (Managed Topics and Connected), rules, actions, and agent configuration.

​
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 before reaching production:
  1. Draft — you make edits in the editor. These are only visible to you.
  2. Publish to Sandbox — click Publish to create a version. Test it using agent chat or a sandbox phone number.
  3. Promote to Pre-release — move the version to a staging environment for user acceptance testing (UAT).
  4. Promote to Live — push to production where real users interact with the agent.
Until you publish and promote, your changes stay in draft. See the deployment pipeline for full details.
If your agent isn’t reflecting recent changes, check which environment you’re testing in. Draft changes are not visible in Sandbox, Pre-release, or Live until promoted.
Tone and phrasing problems are best fixed through specific, example-driven rules — not single-sentence personality instructions.Instead of: “Be polite and professional.”Use: “When a customer expresses frustration, acknowledge their concern before offering a solution. Example: ‘I understand that’s frustrating. Let me look into this for you.’”Steps to fix:
  1. Identify the problematic response in conversation review.
  2. Add or update a rule in global rules with a concrete example of the correct response.
  3. Test with adversarial inputs in sandbox — try edge cases where tone is most likely to go wrong (frustrated users, repeated questions, off-topic requests).
  4. Promote only after confirming the fix works consistently.

​
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 March 27, 2026