Configuration and administration
Business documents
Add business rules and metric definitions for agents to retrieve and reference in their answers.
Business documents explain rules beyond table structures, such as what counts as a valid order, when the fiscal year starts, and how metrics are defined. Agents retrieve and reference this content when answering.
Documents differ from skills: skills describe how to perform analysis, while documents provide background knowledge about how your business works.
Before you start
| Item | Requirement |
|---|---|
| Permissions | Members can manage their own agents; project owners and administrators can manage all project agents. Sharing grants recipients use without configuration changes |
| Entry point | Main navigation on the left → “Agents” → open an agent you own or can manage → “Documents” tab |
The page is titled “Business documents”, with a description explaining that captured business knowledge is retrieved during data Q&A to make answers more relevant to your business. The document list is on the left and the selected document's details are on the right.
Create and edit
Click New document
On the Documents tab, click “New document” to open the creation dialog.
Enter a title and description
- Title: required, up to 255 characters.
- Description: required; one sentence explaining what the document covers.
- Body: can be empty and filled in later.
Write the body
Write the body in the right-hand detail panel, clearly stating rules, definitions, and exceptions. Title, description, and body all save on blur; there is no need to find a save button.
Add keywords
Add keywords in the detail panel: enter a term and press Enter or comma to add it. Click × to the right of a keyword to remove it.
Keywords guide retrieval. When the user's phrasing does not match the title, keywords can bring the document into the candidate set.
Check the list
List items show title and description, plus a keyword-count badge when keywords are present.
How documents are used
Your documents do not just wait for people to read them. They enter the agent's retrieval scope:
- After receiving a question, the agent performs hybrid retrieval in the semantic layer, with business documents as one content type;
- Matching documents enter context with their paths and summary excerpts; the full text is read if the excerpt is insufficient;
- From the agent's perspective, documents live in a virtual
/documents/directory, with one/documents/<title>.mdpath per document.
That is why specificity matters more than length. A focused document with one clear definition, an accurate title, and useful keywords is easier to retrieve than a large all-purpose manual.
Key constraints
| Item | Value or behavior |
|---|---|
| Title | Required, maximum 255 characters |
| Description | Required |
| Body | Can be empty |
| Keywords | Separated by Enter or comma; can be added or removed |
| Saving | Saves on blur |
| Deletion | Delete from the detail panel; irreversible after confirmation |
| Ownership | Attached to a specific agent and effective only within that agent's retrieval scope |
| Difference from skills | Documents provide background knowledge; skills provide analysis methods |
Troubleshooting
| Symptom | How to identify it | What to do |
|---|---|---|
| Answer does not use a document | A definition is documented, but the answer uses a different calculation | Check that the title and keywords cover the user's phrasing; make the definition more specific |
| Title cannot be saved | Submission reports an excessive title length | Shorten to no more than 255 characters |
| Empty description fails to save | Description is required | Add a one-sentence description |
| Changes do not take effect | The old value returns after leaving the field | Check that you own the agent or are a project owner or administrator; receiving a shared agent does not grant configuration management |
| Need to remove an incorrect document | Delete in the detail panel, then confirm | Confirmation is irreversible; back up important content elsewhere first |
Next steps
- Make analysis methods reusable too: Analysis skills
- Align document definitions with table structures: Table and field descriptions
- See whether a document was actually referenced: Logs and user feedback