> For the complete documentation index, see [llms.txt](https://docs.helvia.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helvia.ai/knowledge/agent-knowledge.md). # Agent Knowledge Knowledge is what grounds an agent in your own content. Connect a Knowledge Base in the Designer, then retrieve from it in workflows with a Semantic Search node. Observatory shows what was retrieved and where the agent fell short. Go to **Designer > Knowledge** to get started. ```mermaid flowchart LR KB["📚 Knowledge Base"] -->|"Connect"| AG["🤖 Agent"] AG -->|"Retrieve at runtime"| ART["📝 Articles"] ART --> ANS["💬 Answer"] style KB fill:#eeedfc,stroke:#615DEC,color:#1a1a2e style AG fill:#fff4d6,stroke:#F3A702,color:#1a1a2e style ART fill:#eeedfc,stroke:#615DEC,color:#1a1a2e style ANS fill:#f0f4ff,stroke:#94a3b8,color:#1a1a2e ``` ### Connecting a Knowledge Base A Knowledge Base (KB) sits at the Workspace level, where multiple agents can share it. Connect a KB to a specific agent in the Designer and make its articles available for retrieval in the agent's workflows. {% stepper %} {% step %} #### Open the Agent's Knowledge Go to **Designer > Knowledge**. {% endstep %} {% step %} #### Pick the Knowledge Base Select **Connect KB** and choose from the Workspace KBs not already connected. If the KB you need doesn't exist yet, select **Add New Knowledge Base** to create one. {% endstep %} {% step %} #### Sync the Agent Select **Update Agent Knowledge**. New articles only become retrievable [after the sync](#updating-agent-knowledge).
{% endstep %} {% endstepper %} Once connected, the KB appears in the table.
The default reply mode comes in two flavors:

:comment-pen:

AI-Generated Text

The response LLM writes a fresh answer grounded in the retrieved articles. Best when you want answers in a consistent voice or summarized for the user

:quote-right:

Article Body

The agent returns the matching article verbatim. Best for policy text, legal copy, or any content that must not be paraphrased
{% hint style="warning" %} **Modern agents always reply with AI-generated text:** The Article Body reply mode is available for classic agents only {% endhint %} ### Updating Agent Knowledge A connected Knowledge Base doesn't reach the agent automatically. The **Update Agent Knowledge** button runs a sync that brings the agent up to date with every connected KB. You need to sync whenever: * Add, edit, or remove an article in a connected KB * Re-sync a source * Connect or disconnect a KB Syncing is fast but not instant. Until it runs, the agent keeps answering from the previous version of the content. {% columns %} {% column %} #### :circle-check: Synced
The agent retrieves the latest articles from every connected KB. {% endcolumn %} {% column %} #### :arrows-rotate: Needs Sync
Connected KB changes since the last sync are not yet available to the agent. {% endcolumn %} {% endcolumns %} {% hint style="info" %} **No Model Training on Your Data** Updating an agent's knowledge is a sync, not a training run. Your articles are never used to fine-tune the underlying model. {% endhint %} ### Disconnecting a Knowledge Base To stop an agent from retrieving from a Knowledge Base, select the :link-slash: **Unlink** action. To remove several at once, select the rows and choose **Disconnect Selected** from **Bulk Actions**. The KB itself stays in the Workspace and can be reconnected later. After disconnecting, run **Update Agent Knowledge** again so the agent rebuilds its retrieval index without the removed sources. ### Using Knowledge in a Workflow Connecting a KB makes its content available to the agent, however retrieving from it at runtime is the workflow's job. Every question the agent answers from your content passes through a workflow with a Semantic Search node somewhere inside it. Most builders set knowledge retrieval up the same way: 1. Rewrite the question 2. Search the KB 3. Draft the answer Adapt each step to your use case. Add tag filters, branch on the result, or skip steps your agent doesn't need. ```mermaid flowchart LR U["💬 User Message"] --> QR["🪄 LLM
Query Rewrite"] QR --> SS["🔍 Semantic Search"] SS --> RG["✍️ LLM
Response Generation"] RG --> M["📤 Message"] RG --> CA["❌ Cannot Answer"] style U fill:#f0f4ff,stroke:#94a3b8,color:#1a1a2e style QR fill:#eeedfc,stroke:#615DEC,color:#1a1a2e style SS fill:#fff4d6,stroke:#F3A702,color:#1a1a2e style RG fill:#eeedfc,stroke:#615DEC,color:#1a1a2e style M fill:#f0f4ff,stroke:#94a3b8,color:#1a1a2e style CA fill:#f0f4ff,stroke:#94a3b8,color:#1a1a2e ``` #### Rewriting the Query User questions rarely match the wording in your KB. A first-time user might write in a different language, drop product names, or paraphrase a feature in their own words. A follow-up only makes sense in the context of the previous turn. Sending that message straight to the index loses recall. A query-rewrite LLM solves this. Place an LLM node before the Semantic Search node and instruct it to rephrase the user's message into a search-ready query, using the conversation so far as context. What you typically configure on the rewrite LLM:
Terminology mapping Translate everyday phrasing and common misspellings into the company-specific names, product code-names, and terms the KB is written in
Style Turn a sentence into a search query, drop pleasantries, expand abbreviations
Language Translate to the language the KB is written in
Conversation history Include prior turns so a follow-up resolves without the user repeating context
Output variable Store the result in a variable like `userMessageRewritten` for the Semantic Search node to consume
#### Searching with Semantic Search The Semantic Search node retrieves the closest-matching articles from the connected KBs and stores them in a variable that downstream nodes can read. It is the only retrieval primitive that the console exposes inside workflows; everything else (reasoning, drafting, deciding when to fall back) happens in surrounding LLM and Flow Control nodes.

:list-ol:

Max Results

Number of closest-matching articles to return, between 1 and 25. Defaults to 10

:tags:

Filter by Tags

Restrict retrieval to articles with specific tags, or exclude tags from the result set

:magnifying-glass:

Query

The text the node searches with. Almost always a variable set by an upstream rewrite LLM

:box-archive:

Variable Name

Where to store the result for downstream nodes
#### Drafting the Answer The Semantic Search node returns raw articles. Whether that becomes an answer, a follow-up question, or a graceful fallback is the response LLM's job. Place a second LLM node after the Semantic Search node and feed it both the rewritten query and the retrieved sources. A few things builders commonly do at this stage:
Curate the articles Instruct the LLM to use only sources that genuinely answer the question, and ignore loose matches
Cite the sources Ask the LLM to include the article IDs (or URLs) in its output so they surface in Observatory for review
Decide whether to answer Route to a Cannot Answer branch when the sources don't cover the question
Ask a follow-up When the question is ambiguous, request more context before committing to an answer
#### Reporting Missed Questions When the response LLM decides the retrieved sources don't cover the question, route the workflow through a Missed Question node. The node [logs the question](/observatory/sessions.md#missed-questions) so you can review unanswerable topics later and either add the missing content to a KB or build an explicit answer in the workflow. ### Verifying in Observatory Every retrieval that runs in a workflow leaves a trail in Observatory. Open a session and walk through the interaction log to see what the agent actually retrieved and how the surrounding LLMs handled it. Three signals are worth checking:

:database:

Retrieved Sources

The articles a Semantic Search node returned on each turn

:code:

Variable Values

The contents of every workflow variable before and after each turn

:question-circle:

Missed Questions

Topics where the agent couldn't find an answer
#### Retrieved Sources Each Semantic Search node logs an entry in the interaction list with two sections: * **Request:** the `query` sent to the index, `maxResults`, and any tag filters (`filterByTags`, `includedTags`, `excludedTags`) * **Response:** `numResults` plus the full retrieved list in `examinedCorpusStr`, where each article shows its id, title, body, group, language, and tags Use this entry to confirm the rewrite produced a clean query, the expected article came back, and the tag filters did what you intended.
Example interaction log entry ```json { "request": { "query": "Could you please tell me more about ...", "timestamp": "2026-01-13T11:44:01.188Z", "maxResults": 10, "excludedTags": null, "filterByTags": false, "includedTags": null, "variableName": "retrievedSources" }, "response": { "timestamp": "2026-01-13T11:44:01.656Z", "numResults": 7, "examinedCorpusStr": "[{\"id\": \"kb--\", \"title\": \"About - What does do?\", \"body\": \"...\", \"group\": \"Default\", \"language\": \"en\", \"tags\": \"\"}, ...]" } } ```
#### Variable Values The session page lets you follow every [workflow variable](/observatory/inside-a-session.md#the-interaction-log) as the conversation progresses. Inspect the rewritten query, the retrieved sources, and any other variables both before and after each turn to verify the rewrite LLM produced a clean query and the response LLM had the right inputs to draft from. #### Missed Questions When the workflow routes to a Missed Question node, the question is [recorded](/observatory/sessions.md#missed-questions) at **Observatory > Sessions > Missed Questions**. Review the list to spot topics the agent couldn't answer, then add the missing content to a KB. ### Best Practices * **Rewrite the query before searching:** A clean, KB-shaped query lifts recall more than tweaking the maximum allowed results * **Tag from day one:** Include and exclude tag filters are the easiest way to scope retrieval as your KBs grow * **Sync after every KB change:** A connected KB whose content changed but whose agent wasn't updated still returns the old articles * **Always handle Cannot Answer:** Route the response LLM through a Flow Control branch that catches "no good source" and asks a follow-up or hands off. Silent hallucination is worse than a graceful fallback. {% hint style="success" %} You now know how to connect a Knowledge Base to an agent, keep its knowledge in sync, and build a retrieve-and-respond pipeline with Semantic Search, query rewriting, and response generation. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.helvia.ai/knowledge/agent-knowledge.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.