> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://poly-ai.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://poly-ai.ferndocs.com/_mcp/server.

# Frequently asked questions

> Common questions and troubleshooting solutions for agent configuration, knowledge, rules, and actions.

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

#### Why isn't my agent answering a question it should know?

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](/agent-studio/conversations/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.

> **Tip**
>
> 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.

#### I changed something – why isn't it live?

**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](/agent-studio/deployments/overview) for full details, or the [environments FAQ](/academy/fa-qs/environments-and-testing) for common questions.

#### How do I make my agent stop saying the wrong thing?

Tone and phrasing problems are best fixed through **specific, example-driven [global rules](/agent-studio/behavior/general/behavior)** – not single-sentence personality instructions. Identify the problematic response in [conversation review](/agent-studio/conversations/review), add a rule with a concrete example of the correct behavior, and test in sandbox before promoting.

See the [rules FAQ](/academy/fa-qs/behavior) and [personality FAQ](/academy/fa-qs/personality-and-role) for detailed guidance.

## Topic-specific FAQs

#### [Managed topics](/academy/fa-qs/managed-topics)

Topic structure, retrieval, sizing, and organization.

#### [Connected knowledge](/academy/fa-qs/connected-knowledge)

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

#### [Behavior](/academy/fa-qs/behavior)

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

#### [Actions](/academy/fa-qs/actions)

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

#### [Personality and role](/academy/fa-qs/personality-and-role)

Setting tone, personality, and role configuration.

#### [Environments and testing](/academy/fa-qs/environments-and-testing)

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

#### [Technical considerations](/academy/fa-qs/technical)

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

---

#### [Community](https://polyaijupiter-uki8686.slack.com/archives/C075ST5UK7Y)

Join the PolyAI community on Slack.