Build an FAQ agent with knowledge base filtering

This tutorial walks you through building a support agent for GoRoute, a fictional ride-sharing and delivery platform. GoRoute has two user types — drivers and couriers — each with different policies, FAQs, and workflows. You’ll import content from two separate help sites, tag each with metadata, and build playbooks that filter the knowledge base so drivers only see driver content and couriers only see courier content. Before you start, visit demo-goroute.vercel.app to explore the GoRoute website and see the content you’ll be importing into the knowledge base.

Create a new project

From the Dashboard, go to Projects → New project. Name your project “GoRoute Support”, keep the default chat settings, and select Start from scratch.

Import driver help content

Click Knowledge Base in the left sidebar, then Add data sources. Select Sitemap and paste the URL for the driver help center:

https://demo-goroute.vercel.app/driver

Voiceflow will crawl the sitemap and import all pages under this URL.Under LLM chunking strategies, enable the following three options:

Smart chunking — splits content into logical, topic-based sections, which works well for help articles that cover multiple topics on a single page.
FAQ optimization — generates sample questions each section could answer, improving retrieval when users phrase things differently than the source content.
Remove HTML and noise — cleans up messy formatting from web pages so the agent processes clean text.

Different types of content benefit from different chunking strategies. The combination above works well for help center sites, but when you import your own data, experiment with different strategies to find what gets the best results for your content.

Before importing, click + in the Metadata section and add the following tag:

Key	Value
`user_type`	`driver`

This metadata tag is what allows you to filter queries later so the agent only retrieves driver-specific content when helping a driver.

Import courier help content

Click Add data sources again. Select Sitemap and paste the courier help center URL:

https://demo-goroute.vercel.app/courier

Select the same three LLM chunking strategies as before: Smart chunking, FAQ optimization, and Remove HTML and noise. Then add the metadata tag:

Key	Value
`user_type`	`courier`

After both imports finish, your knowledge base will contain content from both help centers — distinguished only by their metadata tags. You can verify this by clicking each data source and checking its metadata in the right panel.

Set up the global prompt

Click the Agent tab. Write a global prompt that establishes the GoRoute support agent’s identity. Notice how the prompt emphasizes identifying the user type early — this is critical for routing to the correct playbook.

# Personality
You are a support agent for GoRoute, a ride-sharing and
delivery platform. You help both drivers and couriers with
questions about the platform, policies, earnings, and
troubleshooting.

# Goal
Resolve questions quickly by finding the right information
for the user. Always determine whether the user is a driver
or a courier early in the conversation so you can provide
the correct information.

# Tone
Friendly, clear, and efficient. Keep answers concise. Use
simple language — many users are checking between rides or
deliveries.

# Guardrails
Never provide information meant for drivers to couriers,
or vice versa. The policies are different and mixing them
up causes real problems. If you're unsure which user type
someone is, ask before answering. Never guess at pay rates,
bonuses, or policy details.

Create the driver support playbook

In the Agent tab, click + in the Skills panel to create a new playbook. Name it “Driver Support”.Set the LLM description:

Answers questions about GoRoute driver topics including ride
policies, earnings, vehicle requirements, and driver app
issues.

Then write the playbook instructions:

# Goal
Help the driver find accurate answers to their questions
about driving on the GoRoute platform.

# Steps
1. Search the knowledge base for information related to
   the driver's question.
2. Provide a clear, concise answer based on what you find.
3. If the answer involves multiple steps (like a setup
   process or troubleshooting flow), walk through them
   one at a time.
4. If no relevant information is found, let the driver
   know and offer to connect them with the GoRoute driver
   support team.

# Important
Only use information retrieved from the knowledge base.
Do not answer driver questions from general knowledge —
GoRoute policies are specific to the platform.

Add knowledge base filtering to the driver playbook

This is the key step. In the driver playbook, scroll to the System tools section on the right and click on the Knowledge base tool to expand its settings.Under Metadata filtering, add a filter:

Key	Value
`user_type`	`driver`

This ensures that when the agent runs the Driver Support playbook, it only retrieves content tagged with user_type: driver. Courier content will never appear in the results.

Create the courier support playbook

Create another playbook called “Courier Support”.Set the LLM description:

Answers questions about GoRoute courier topics including
delivery policies, earnings, bag requirements, and courier
app issues.

Then write the playbook instructions:

# Goal
Help the courier find accurate answers to their questions
about delivering on the GoRoute platform.

# Steps
1. Search the knowledge base for information related to
   the courier's question.
2. Provide a clear, concise answer based on what you find.
3. If the answer involves multiple steps, walk through
   them one at a time.
4. If no relevant information is found, let the courier
   know and offer to connect them with the GoRoute courier
   support team.

# Important
Only use information retrieved from the knowledge base.
Do not answer courier questions from general knowledge —
GoRoute policies are specific to the platform.

Then configure Metadata filtering on this playbook’s Knowledge base tool — same as the previous step, but this time set the value to courier:

Key	Value
`user_type`	`courier`

Add agent instructions for routing

Go back to the Agent tab. In the Instructions field, add routing logic so the agent identifies the user type and directs them to the correct playbook:

# Identify the user
At the start of the conversation, determine whether the user
is a driver or a courier. If it's not clear from their first
message, ask: "Are you a GoRoute driver or a courier?"

# Skills
Route to the Driver Support playbook when the user is a
driver and asks about ride policies, earnings, vehicle
requirements, driver app issues, or any driver-specific topic.

Route to the Courier Support playbook when the user is a
courier and asks about delivery policies, earnings, bag
requirements, courier app issues, or any courier-specific
topic.

If the user asks about something that applies to both (like
account settings or payment methods), route to whichever
playbook matches the user type they identified as.

Test with both user types

Click Run in the top-right corner to test your agent. Try these prompts to verify routing and filtering are working correctly:

Driver test: "I'm a driver. What are the vehicle requirements
to drive for GoRoute?"

Courier test: "Hey, I do deliveries for GoRoute. What kind
of bag do I need?"

Ambiguous test: "How do I update my payment info?"

Check the conversation logs to confirm:

The correct playbook was triggered for each user type
The knowledge base query results only contain content matching the right user_type metadata tag
The ambiguous test prompts the agent to ask which user type they are

Tips for building filtered knowledge bases

Verify your filtering. Open the logs panel while testing and look at the knowledge base query results. You should only see chunks tagged with the correct user_type. If you see mixed results, double-check your metadata tags on the data sources and the filter configuration in each playbook.
Combine chunking strategies for web content. Smart chunking splits pages into logical sections, FAQ optimization helps match varied user phrasing, and Remove HTML and noise cleans up web formatting. Together, they significantly improve retrieval quality for help center content.
Scale this pattern. You can add more user types (e.g., user_type: restaurant_partner) by importing more content with new metadata values and creating additional playbooks with the corresponding filters.
Combine with runtime filtering. For even more dynamic control, you can use conversation variables in the metadata filter value field — so the filter updates automatically based on what the user says.

What’s next?

You’ve built an agent that serves different content to different user types using metadata filtering. Explore these resources to go deeper.

Querying the knowledge base

Advanced configuration for knowledge base queries, including custom queries and query re-writing.

Playbooks

Learn more about playbook tools, exit conditions, and model settings.

​Tips for building filtered knowledge bases

​What’s next?

Querying the knowledge base

Playbooks

Tips for building filtered knowledge bases

What’s next?