Skip to content

Module 2: Semantic Router

What you're building

Your agent currently answers everything, even off-topic questions like "Tell me a joke." In this module you'll add a semantic router that filters queries before they reach the AI.

You'll define two lists of example queries: an allow list for questions your agent should handle, and a deny list for ones it should block.

Setup

Enable the Semantic Router in your .env file:

GUARDRAIL_ENABLED=true

Exercise

  1. Open exercises/telco/semantic_router.py in your IDE.
  2. Add 2-3 more references to each route to improve classification. Each Route has:
Field What it does
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) 
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

Stop the running server (Ctrl+C) and restart:

make dev

.\workshop.ps1 dev

Open localhost:3040.

  • Ask: "Why is my bill higher than last month?" and click Semantic-router in the right activity panel to see it pass through
  • Ask: "Tell me a joke" and see it get blocked with a redirect message