Tool Agent with Knowledge Base

The most powerful out-of-the-box capability in Virbe is the Tool Agent node with Knowledge Base retrieval (RAG). The Tool Agent reasons about user questions, searches your Knowledge Base for relevant content, and generates a natural language response – all in a single node. This tutorial walks through setting it up from scratch.

What you'll build: A virtual being that answers questions about your organisation, product, or topic area using content you add to the Knowledge Base.

Time: approximately 60 minutes (including content setup)

Prerequisites:

• A Virbe account with a Web Widget or Kiosk profile
• An AI model configured in Configure → AI Models (OpenAI or Azure OpenAI recommended)
• Content to add to the Knowledge Base (website URL, documents, or structured data)

Step 1 – Add Content to the Knowledge BaseCopy Anchor Link

1. Go to Configure → Knowledge Base
2. Click + Add collection to create a new collection (e.g., "Product Information")
3. Add your content:

Option A – Crawl a websiteCopy Anchor Link

Click + Add document → Website. Enter the URL of the page or section you want to crawl (e.g., https://yourcompany.com/products). Click Save, then click Crawl manually to start the crawl. The crawl may take a few minutes depending on the number of pages.

Option B – Add a text documentCopy Anchor Link

Click + Add document → Text. Give the document a name and paste or type your content into the rich editor. This is useful for FAQs, policies, or content that isn't publicly accessible.

Option C – Add a tableCopy Anchor Link

Click + Add document → Table. Create columns appropriate to your data (e.g., Product Name, Description, Price, Category). Use this for structured data that you want to query precisely.

4. After adding content, verify it has been embedded – the storage panel in the sidebar should show embeddings % above 0 once processing is complete.

Step 2 – Configure a Tool Agent NodeCopy Anchor Link

1. Open the Conversation Editor
2. Open the On User Input handler
3. Add a Tool Agent node
4. Configure the node:
   • Select model – choose your AI model configuration
   • Enable Knowledge Base retrieval – toggle this on to give the Tool Agent access to your Knowledge Base
   • Knowledge Base – select the collection(s) you want the agent to search
   • System instruction – write the persona and behavioural instructions for the agent. Example:

You are a helpful assistant for Acme Corp. You help customers find product information, answer questions about shipping, and assist with account queries. Be concise and friendly. If you don't know the answer, say so rather than guessing.

5. Leave History message count at the default (6–10 turns is usually sufficient for context)

Step 3 – Set Up the Flow StructureCopy Anchor Link

A minimal but complete On User Input flow:

Flow Entrypoint
    │
    └── On User Input
              │
              └── Tool Agent (with KB retrieval)

The Tool Agent handles the full turn – retrieving context from the KB and generating a response. For most use cases, no additional nodes are needed in this flow.

Step 4 – Add Fallback HandlingCopy Anchor Link

Add a Greet flow to welcome users at the start of a conversation:

1. Create a Flow named "Greet"
2. Add a Text node: "Hi! I'm here to help. What would you like to know?"
3. In the On conversation-start handler, add a Go to Flow node pointing to the Greet flow

Your pipeline now:

• Greets users when they start a conversation
• Answers all subsequent questions via the Tool Agent with KB retrieval

Step 5 – Test Retrieval QualityCopy Anchor Link

1. Open the Test conversation panel
2. Enable Show system messages to see which Knowledge Base chunks were retrieved
3. Ask several representative questions:
   • Questions with clear answers in your content – verify the correct answer is returned
   • Questions with vague or no answer in your content – verify the assistant says it doesn't know rather than hallucinating
   • Questions with multiple relevant sections – verify the agent synthesises a coherent response

If retrieval is poor:

• Check that embeddings have completed processing (storage panel)
• Review your content for clarity and density – short, focused documents retrieve better than large, unfocused ones
• Consider adjusting chunk size in Knowledge Base Configuration
• See Knowledge Base Best Practices for detailed guidance

Step 6 – Publish and DeployCopy Anchor Link

1. Use Assign draft to profile to link the pipeline to your profile
2. Click Publish to activate the pipeline
3. Test on the live profile using the web widget embed or kiosk configuration

Extending This PatternCopy Anchor Link

Multiple collections, targeted retrieval: If you have separate collections for products, policies, and FAQs, you can use different Tool Agent nodes in different flows – each with its own Knowledge Base collection filter – so the agent only searches relevant content for each topic.

Combining RAG with deterministic data: For precise data lookups (pricing, inventory, locations), use a Find Records node to query a Table document directly, and pass the result to the Tool Agent as additional context in the system instruction using variable interpolation ({{var.productPrice}}).

Escaping to human handover: Add a signal-based trigger in the Tool Agent's flow that routes to a human handover flow if the agent cannot answer (e.g., user says "I want to speak to a person"). See the use-cases section for a complete human handover tutorial.

Cookie settings