Teach the AI assistant

Guide Overview

Target audience: System administrators who decide what the assistant knows and how it behaves.

Reading time: ~15 minutes.

Outcome: A document is indexed and Ready for the assistant, you know who can find it and how close a passage must be, a website is set to be crawled, you know where the skills live, and you can adjust the assistant’s mission and behaviour.

The assistant answers from the data a person may read. You extend what it can draw on with knowledge sources (documents, pages, recordings and typed text), keep websites up to date with website crawls, and shape how it works through skills and the assistant’s own settings.

Before You Start

You need	Why
The Settings access right (system administrator)	Knowledge Sources is a system administrator menu, and only a system administrator can edit an assistant, a skill or a skill pack. An AI Administrator sees the skill and skill pack lists but cannot change them.
An embedding connection	Indexing turns the text into searchable passages through the Embedding Vendor of AI ‣ Configuration ‣ Settings. The ready-made Viindoo connection covers this (see Connect AI vendors and choose data location).

Add a Knowledge Source

A knowledge source is a document, page or recording the assistant may use to answer.

1. Go to AI ‣ Configuration ‣ Knowledge Sources. Each line shows the Source Name, the Source Type, the Status and the Company.

2. Click New and type the Source Name.

3. Choose the Source Type: PDF File, Web Page, Typed Text, Image (OCR), PDF (OCR) or Audio (Transcript). Then give the content: the file, the web page address or the Text Content.

4. Choose Text Cleaning: None (keep original) or Basic (clean). Set Restricted to User Groups when only some people may see answers drawn from the source.

5. Click Save. The status bar starts at Draft (not yet indexed). A scheduled job named AI: Process Pending Sources picks the source up in the background (it runs every five minutes), moves it to Processing (chunking + embedding in progress) and then to Ready (available for search). Chunk Count shows how many passages were indexed.

6. When a source stops at Error, read the reason in the Error section and fix the cause, for example a corrected address or a readable file. Then open the assistant in AI ‣ Agents, go to the Knowledge Sources tab and click Retry failed sources.

Choose Who Can Find a Knowledge Source

The assistant searches your knowledge by meaning with the tool Find Knowledge. It searches every knowledge source the person who asks may read, of any type, and gives back the closest passage of each record. It can also narrow the search to one kind of record, for example the pages of one space.

A source a person may read is searchable by every assistant that answers that person, including a source you attached to one assistant in its Knowledge Sources tab. Attaching a source does not make it private to that assistant. To keep a source private, set Restricted to User Groups on the source: only the members of those groups find it, whichever assistant they ask.

The tool belongs to the topic Data Questions of the Viindoo AI Assistant.

1. Go to AI ‣ Agents, open the assistant and go to the Topics tab.

2. Click the topic Data Questions. In the dialog, scroll to Actions This Topic Is About: Find Knowledge is listed beside the other tools of the topic.

Every internal user can read a topic; a system administrator changes it. Removing Find Knowledge from the list stops the assistants that carry this topic from searching knowledge by meaning, and Add a line puts it back.

Set How Close a Passage Must Be

Two settings decide which passages of your knowledge may answer a question. The Relevance Floor, set on the embedding model, is the score below which a passage means nothing; every knowledge search ignores such passages, whichever assistant asks (see Relevance Floor of an Embedding Model). The Minimum Relevance, set on each assistant, says how much more relevant than that floor a passage must be.

Minimum Relevance is counted above the floor: 0 keeps every passage above the floor, and 1 keeps only identical text. A value below 0 or above 1 is refused when you save. To admit more passages than 0 does, lower the floor on the embedding model. Searching by words is never limited by it.

1. Go to AI ‣ Agents and open the assistant.

2. In the Behaviour section, set Minimum Relevance and click Save. Point at the question mark beside the field to read its help.

Because each person may read different documents, two people can legitimately get different answers, or one a grounded answer and the other a refusal. That is expected.

After an Update of Viindoo AI

When Viindoo AI is updated on a database that already uses it, the update adjusts these settings so that answers stay as they were:

• The Relevance Floor of the shipped Viindoo embedding model is set to 0.35.

• The Minimum Relevance of every assistant is converted to the scale counted above the floor, so the same passages stay hidden. A value at or below the floor becomes 0; for example 0.6 becomes 0.38. Nothing is converted a second time.

• Find Knowledge is added to the topic Data Questions when the topic still holds the tools it was released with. A topic whose tools you changed is left as you set it: add the tool with Add a line as described above.

• The translations of the module are reloaded from the catalogue that ships with it. A translation of a Viindoo AI term that an administrator edited by hand is replaced by the shipped one: edit it again after the update if you want your own wording.

Keep a Website Up to Date

1. Go to AI ‣ Operations ‣ Website Crawls and click New.

2. Type a Crawl Name and the URL Patterns, one per line. A * matches any text, so one pattern covers a whole site; a plain address is fetched alone.

3. Set Re-crawl Every (days) (7 by default), and Restricted to User Groups if needed. Leave Active on.

4. Click Save. Last Crawl and Last Crawl Status fill in once a crawl has run, and the pages found are listed under Crawled Pages.

The web crawler itself is set in AI ‣ Configuration ‣ Settings, section Knowledge: Firecrawl URL (leave it empty for the default) and Firecrawl API Key.

Note

Every internal user can open Website Crawls and read the rules. A system administrator or a user with the AI Content Manager right can edit them.

See and Manage Skills

A skill is a set of instructions the assistant loads when a task calls for it, such as a marketing brief or a month-end checklist. Skills come in packs.

1. Go to AI ‣ Configuration ‣ AI Skill Packs. Each pack shows its Technical Code, Pack Name, Version and Vendor.

2. Open a pack to see the skills it carries under Skills.

3. Go to AI ‣ Configuration ‣ AI Skills to search every skill, with its Technical Code, Skill Name, Version, Skill Pack and Company. Use the Global and Archived filters and the grouping by pack to narrow the list.

4. Open a skill to read its instructions. Untick Active to retire a skill without deleting it.

Set Up an Assistant

1. Go to AI ‣ Agents and open the assistant.

2. Write what it is for in Role and Mission, in a sentence or two. Other assistants read it to decide whether to hand work to this one. The system prompt further down the form says how it behaves.

3. Pick the Preferred Model Line or Preferred AI Model, the Reasoning Level, and untick Collect User Feedback if people should not see the thumbs up, thumbs down and flag buttons under its answers.

4. In Behaviour, tick Answer Only From Attached Sources for an assistant that must not mix in its general knowledge, then attach sources on the Knowledge Sources tab. Passages Per Answer and Minimum Relevance tune how many passages are pulled in and how closely related they must be (see Set How Close a Passage Must Be). Per-Run Cost Cap (USD) stops one run when it reaches the limit.

5. Use the tabs Topics, Knowledge Sources, External Tools and Skills for the rest, then click Save. The Traces button lists the runs of this assistant.

Note

Everyone can read the list of assistants, but only a system administrator can change one. Leave the Temperature and Max Tokens settings at their defaults unless your AI vendor’s documentation tells you otherwise.

Success Checkpoint

• A typed-text source shows Ready (available for search) and a Chunk Count above zero.

• The topic Data Questions lists Find Knowledge, and Minimum Relevance holds a value from 0 to 1.

• The website crawl rule is saved, active, and shows its schedule.

• You can find the pack and skills you expect, and the assistant keeps its new mission after you save.

Common Problems

Problem	What to do
A source stays in Draft (not yet indexed) for a few minutes.	The scheduled job runs every five minutes. Wait for the next run.
A source stops at Error.	Read the Error section, fix the cause, then click Retry failed sources on the assistant.
A question your documents cover is answered with the card Nothing matched.	Lower Minimum Relevance to 0, then lower the Relevance Floor of the embedding model (see Advanced configuration). Check that the person asking may read the source: a source restricted to user groups stays hidden from everyone else.
Find Knowledge is missing from the topic Data Questions.	A topic whose tools were changed is left as set. Add the tool with Add a line in the topic dialog.
You cannot see Knowledge Sources in the menu.	It is reserved for system administrators.
You cannot edit a skill or an assistant.	Only a system administrator can. An AI Administrator can read these lists.

Next Steps

• External tools and feedback - connect external tool servers and review how people rate the answers.

• Advanced configuration - the technical lists, and when to leave them alone.