> Give your AI agent a knowledge base of Markdown entries you write, try every change on preview, publish it with the agent and restore any version. # A knowledge base for your AI agent A knowledge base is what an AI agent answers from when a question needs facts: return policies, delivery zones, how a service works. In Vatio it is a set of Markdown entries you write, from the CLI or the inbox, that the agent searches with the built-in `knowledge_lookup` tool; Vatio does not read websites. You plug it into the agent in your `vatio.yml`, try every change on preview, and publish it together with the agent, which answers from it on WhatsApp, Instagram and the web. ## What it is, and why it matters Without a knowledge base, an agent asked about your return policy can only say it does not know, or guess. Pasting every policy into the instructions does not scale either: the prompt grows, rules get buried, and only a developer can fix a stale fact. A knowledge base keeps long facts out of the prompt. The agent searches it when a question calls for it and reads only the sections that match, and supervisors can correct an entry the moment a fact changes. It is one of three places an answer can come from, and choosing the right one avoids a whole class of wrong replies: | Put it in | When | Example | |---|---|---| | `instructions` | Rules, the order of steps, what never to say, which tool does which job | "Never quote a shipping cost that is not in the knowledge" | | Knowledge | Facts that change slowly and take paragraphs to explain | Return policy, delivery zones, brewing guides | | A tool | Data that can change by the hour, or belongs to one person | Stock, today's price, free slots, an order's status | The test: if the answer could be wrong by this afternoon, it comes from a tool that calls your API. Knowledge is not a cache of your catalog. ## How it works 1. **A base holds entries.** Create one base per set of entries you want kept apart, and list on the agent the bases it reads. 2. **An entry is Markdown you write.** Its title comes from its own `# heading`, and each `##` heading starts a section that is searched on its own. 3. **The agent searches with `knowledge_lookup`**, a built-in tool you enable in `agent.tools`. When nothing matches, the tool says so, and your instructions decide what the agent does next. 4. **Indexing is asynchronous.** An entry can be searched once its sections are embedded; `vatio kb show` says which entries are ready. 5. **Live answers from published entries.** Preview keeps its own changes on top of live and reads everything else from it. ## Step by step ### 1. Create the base and write entries ```bash vatio kb create shop vatio kb write shop shipping shipping.md vatio kb write shop returns returns.md vatio kb write shop brewing brewing.md vatio kb show shop ``` `vatio kb write BASE ENTRY FILE` creates the entry, or replaces what is there. With no file it reads stdin, so editing in place is one line: `vatio kb cat shop returns | edit | vatio kb write shop returns`. `vatio kb cat` prints exactly what Vatio holds. ### 2. Plug it into the agent ```yaml agent: instructions: | Shipping, returns and brewing: search knowledge_lookup first. If the results do not answer the question, say so and offer to pass it to the team. tools: [knowledge_lookup] knowledge: [shop] ``` A referenced base must already exist: a misspelled name fails the push instead of quietly becoming an empty base. Removing a reference later does not delete the base's content. ### 3. Push and test retrieval ```bash vatio push vatio chat "How long does shipping take to Denver?" vatio chat show ``` `chat show` lists the knowledge lookup the agent made and what came back. If the answer is missing, check `vatio kb show shop`: an entry still indexing cannot be found yet. ## Write entries that answer on their own The agent receives the sections that match a question, not the whole entry in order. A section that leans on another one answers badly. This entry reads fine top to bottom and fails as search results: ```markdown # Shipping We ship nationwide. Details below. ## More info Same as above, but longer for Alaska and Hawaii. Free over the amount we mentioned. ``` This one answers from any section: ```markdown # Shipping ## Delivery times Orders ship from Portland. Delivery takes 2–4 business days to the contiguous US and 5–8 business days to Alaska and Hawaii. ## Shipping cost Free on orders over $60. Below that, $6.50 to the contiguous US and $14 to Alaska and Hawaii. ## Order cut-off Orders paid before 1 p.m. Pacific on a business day leave the same day. ``` - **One entry per topic**, and every `##` heading a question a customer actually asks, with the whole answer under it. - **No "see above", "as mentioned" or "details below".** - **Numbers, conditions and exceptions**, written out. - **The customer's words.** "Delivery times", not "Fulfillment SLA". - **Never a credential.** Keys and passwords do not belong in knowledge. ## Supervisors edit in the inbox Supervisors, invited from **Team** in the inbox, open the knowledge in the inbox, edit entries and fill one from a file. Saving there takes the change live right away, with no deploy. Every change, from the inbox or the CLI, becomes a numbered version of its entry, recording who made it and from where. That is what keeps the base current: the person who learns that pickup hours changed can fix the entry in a minute. When a wrong reply has a deeper cause, they flag it instead, and the fix goes through preview and evals; see [Improve your agent](/guides/improve-your-ai-agent). ## Try changes on preview Once the agent is live, change knowledge the way you change the prompt. `kb write`, `cat`, `rm-entry`, `show` and `status` work in preview, so only preview answers from what you wrote: ```bash vatio kb write shop shipping shipping.md vatio chat "How much is shipping to Hawaii?" vatio kb status shop # what live does not have yet vatio eval # with flags, publish wants preview tested first vatio publish # the agent and these entries, together ``` `vatio kb publish shop` takes one base's changes live on their own, without the agent, and `--env live` reads and writes live directly. ### Conflicts If live changes an entry after preview changed it too, because a supervisor fixed it in the inbox, publishing would overwrite a change nobody working on preview has read. So it is refused, and `vatio kb status` names the entry. Two ways out: - **From the terminal:** read the entry from live, write your change on top, and the conflict clears. ```bash vatio kb cat shop shipping --env live > shipping.md $EDITOR shipping.md vatio kb write shop shipping shipping.md ``` - **In the inbox:** the knowledge changes page under **Test** has the diff of every entry preview changed (`vatio env` prints the link). For a conflict it shows both sides and offers three options: keep preview's version on top of live, take live's, or combine both by hand. ## History and going back ```bash vatio kb history shop # every version that reached live vatio kb cat shop shipping --version 3 > shipping.md vatio kb write shop shipping shipping.md --env live # version 3 becomes the newest ``` Going back is writing an old version again. In the inbox it is one button, **Restore this version**, on the entry's history. `vatio rollback` goes further. A live deployment is a snapshot of the configuration and the version of every entry it answered from, so a rollback restores the previous live configuration and knowledge together. An inbox edit leaves a snapshot too, which means the first rollback after a supervisor's fix undoes that fix. Read `vatio kb history` before rolling back. ## A worked example Lupine Tea sells loose-leaf tea online and answers on WhatsApp and its website: ```yaml workspace: lupine-tea agent: name: Lupine Tea personality: Warm and brief. Plain words. instructions: | You help customers of Lupine Tea choose teas and answer questions about shipping, returns, brewing and storage. Shipping, returns, brewing and storage: search knowledge_lookup first. If it does not answer, say so and offer to pass the question to the team. Never quote a shipping cost or time that is not in the knowledge. Stock and prices: call check_stock. Never state a stock level or a price that check_stock did not return. tools: [check_stock, knowledge_lookup] knowledge: [shop] ``` The `shop` base holds four entries: `shipping`, `returns`, `brewing` and `storage`. Prices and stock are not in it, because they change every day; `check_stock` reads them from the store's API. In December the carrier announces new rates for January. A developer rewrites the cost section of `shipping` and tries it in a chat on preview. Meanwhile a supervisor fixes the order cut-off time in the same entry from the inbox, and live answers with that fix immediately. When the developer runs `vatio kb status shop`, `shipping` is listed as a conflict. They read it from live, apply the new rates on top of the supervisor's fix, write it again and publish. Live gets the new rates and keeps the corrected cut-off. ## Pitfalls - **Live data in knowledge.** Stock or prices that change hourly go stale the moment you write them. Use a tool. - **"See our website."** The agent cannot follow a link to read a page. Write the answer into an entry. - **A base the agent cannot reach.** It needs both `knowledge: [shop]` and `knowledge_lookup` in `agent.tools`. - **Testing too early.** Indexing is asynchronous; check `vatio kb show` before deciding retrieval is broken. - **No instruction for "not found".** Without "if it does not answer, say so", a model is tempted to fill the gap. - **Rolling back blind.** An inbox edit is a snapshot, so check the history first. ## What next When a wrong reply has a deeper cause than a stale entry, see [Improve your agent](/guides/improve-your-ai-agent). Every command is in the [knowledge docs](https://vatio.ai/docs/knowledge). ## Frequently asked questions ### How do I give an AI agent a knowledge base? Create a base with vatio kb create, write each topic as a Markdown entry with vatio kb write, list the base under agent.knowledge and add knowledge_lookup to agent.tools. Push, then ask the agent a question the entries answer and read the lookup with vatio chat show. ### Can the agent learn from my website? No. Vatio does not read websites. If the answer lives on a page, write what the agent needs into an entry. That also means nothing changes behind your back when someone edits the site. ### What belongs in the knowledge base and what belongs in a tool? Knowledge is for facts that change slowly: policies, delivery zones, how a service works. Anything that can change by the hour, such as stock, today's price or free slots, comes from a tool that calls your API. Rules and the order of steps go in the instructions. ### Can non-developers edit the knowledge base? Yes. Supervisors edit entries in the inbox, and saving there takes the change live right away. Every change is kept as a numbered version with who made it and from where, and any version can be restored with one button in the entry's history. ### What happens if a supervisor edits an entry I also changed on preview? Publishing preview is refused, so their fix is not overwritten unread. vatio kb status names the entry. Read it from live and write your change on top, or resolve it on the knowledge changes page under Test in the inbox, where you keep preview's version, take live's or combine both by hand. ### Does vatio rollback undo knowledge changes? Yes. A live deployment is a snapshot of the configuration and the version of every entry it answered from, and vatio rollback restores the previous one, both together. It does not restore secret values or undo anything a tool already did.