Skip to content

Module 2: Semantic Router

Block off topic queries before they reach the LLM. This guardrail saves tokens and keeps your agent focused on its domain.

How it works

The Semantic Router classifies every incoming query into one of two routes:

Route Effect
Allow list Query passes through to the agent
Deny list Query is redirected or blocked
Why both lists?

Without a deny list, an off topic query like "help me write code" could weakly match an allow example like "Can you help me?" and slip through. The deny list gives the router explicit off topic examples to match against first. Notice the deny list uses a stricter threshold (0.5 vs 0.7) — it needs a closer match to trigger, avoiding false blocks.

Setup

Enable the Semantic Router by updating your .env:

GUARDRAIL_ENABLED=true

Exercise

Open exercises/telco/semantic_router.py.

define_routes()

Two routes are already started for you, the allow list has common wireless support queries and the deny list has off topic examples.

Each Route has three fields:

  • name — "allow_list" lets queries through, "deny_list" blocks them
  • references — example queries that represent this category
  • distance_threshold — how close a match must be (lower = stricter)

Your job: add 2-3 more references to each route to improve classification accuracy.

Route(
    name="allow_list",
    references=[
        "Why is my bill so high this month?",
        "How do I upgrade my phone?",
        "What plans do you offer?",
        "Set up autopay",
        "Do I have device insurance?",
        "I have no signal at home",
        "Can you help me?",
        "What do you know about my preferences?",
        # Add 2-3 more wireless support queries...
    ],
    distance_threshold=0.7,
),
Route(
    name="deny_list",
    references=[
        "What's the weather like today?",
        "Tell me a joke",
        "Help me with my homework",
        # Add 2-3 more off-topic queries...
    ],
    distance_threshold=0.5,
),
Click for a hint

For the allow list, think about billing disputes, plan changes, international roaming, device trade-ins, or greetings like "Hello". For the deny list, think about cooking, trivia, coding help, or creative writing.

Verify

Restart with make dev, then open localhost:3040.

  • Ask: "Why is my bill higher than last month?" — Notice on the right in "Semantic Router" it passes through, returns a normal answer
  • Ask: "Tell me a joke" — blocked with a redirect message