Skip to main content
This page requires Python familiarity. It covers disabling FAQs from Python functions so they are excluded from retrieval for the rest of the conversation.
Use conv.disable_kb_topics() when you need to deterministically prevent the agent from matching certain topics – for example, when an upstream IVR has already handled a flow, the caller is in a context where some answers are not applicable, or a client request requires hiding a topic from the agent without editing the knowledge base. Previously this could only be approximated through prompting. Disabling topics from a function gives you a reliable, deterministic way to scope the agent’s knowledge mid-conversation. Set and clear disabled topics using:
  • conv.disable_kb_topics() – hide one or more topics from retrieval
  • conv.clear_disabled_kb_topics() – re-enable topics that were previously disabled

​
How it behaves

​
Persists across turns

Topics disabled with conv.disable_kb_topics() stay disabled for the rest of the conversation. They continue to be excluded until you:
  • call conv.clear_disabled_kb_topics(), or
  • call conv.disable_kb_topics() again with a new list (the new list replaces the previous one).
You do not need to re-disable topics on every turn.

​
Excluded everywhere RAG runs

Disabled topics are removed from:
  • The list of topics shown to the LLM in the system prompt.
  • Retrieval results used to ground the response.
  • The function/tool list exposed to real-time (speech-to-speech) agents.

​
Combines with channel exclusions

Disabled topics are merged with any topics already excluded for the current channel (configured under Channels). A topic is hidden if it is excluded by either mechanism.

​
When to use this

Use conv.disable_kb_topics() when:
  • An external IVR has already handled an intent and you do not want the agent to repeat it.
  • The caller’s account or segment should not see certain topics (for example, a “cancellations” topic for a non-cancellable plan).
  • A client requests temporary suppression of a topic without changing the knowledge base.
  • You want to scope retrieval to a subset of topics for a specific part of the conversation.

​
conv.disable_kb_topics()

Disables one or more FAQs for the current conversation.

​
Parameters

​
topics (list of strings)

A list of Managed Topic names to disable. Names must match the topic names configured under Knowledge > FAQs. Calling conv.disable_kb_topics() replaces any previously disabled list. To add to the existing list, include the previous names alongside the new ones.

​
Examples

​
Disable a single topic based on IVR context

def on_start(conv):
    if conv.state.get("ivr_intent") == "billing_handled":
        conv.disable_kb_topics(["refund_policy", "billing_dispute"])

​
Disable topics based on account data

def setup_account(conv):
    account = conv.api.crm.get_account()

    if not account["supports_cancellation"]:
        conv.disable_kb_topics(["cancellation_policy"])

​
Replace the disabled list

def update_scope(conv):
    # Only "store_hours" is disabled after this call;
    # any previously disabled topics are re-enabled.
    conv.disable_kb_topics(["store_hours"])

​
conv.clear_disabled_kb_topics()

Re-enables any topics that were previously disabled for the conversation. Use this when the reason for disabling no longer applies – for example, after the caller switches to a different intent or completes a verification step.

​
Example: disable, then clear

def handle_self_service(conv):
    conv.disable_kb_topics(["human_handoff"])
    conv.say("Let's try to sort this out together.")

    # Later, if self-service fails:
    if conv.state.get("self_service_failed"):
        conv.clear_disabled_kb_topics()
Last modified on June 18, 2026