Skip to content

Module 2: Semantic Router

What you're building

Your agent currently answers everything, even off-topic questions like "Write me a Python script." 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/healthcare/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=[
        "Show me my appointment calendar",
        "When is my next appointment?",
        "I need an update on my referral",
        "Who is my primary care provider?",
        "Is telehealth available for my visit?",
        "What's my insurance status?",
        "Can you help me?",
        "What do you know about me?",
        # Add 2-3 more healthcare queries...
    ],
    distance_threshold=0.7,
),
Route(
    name="deny_list",
    references=[
        "Write me a Python script",
        "Tell me a joke",
        "What's the weather like today?",
        # Add 2-3 more off-topic queries...
    ],
    distance_threshold=0.5,
),
Click for a hint

For the allow list, think about scheduling follow ups, rescheduling appointments, or greetings like "Hello". For the deny list, think about homework help, sports scores, or creative writing.

Verify

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

make dev

.\workshop.ps1 dev

Open localhost:3040.

  • Ask: "Do I have any upcoming appointments?" and click Semantic-router in the right activity panel to see it pass through
  • Ask: "Write me a Python script" and see it get blocked with a redirect message