> ## Documentation Index
> Fetch the complete documentation index at: https://help.agentsy.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge Best Practices

> Prepare clear, reliable knowledge so your Agentsy AI Experience can provide useful, accurate answers.

A useful AI Experience starts with trustworthy knowledge. The way you write, organize, review, and maintain your source material can make a significant difference to the answers visitors receive.

This guide provides practical standards for preparing knowledge before uploading it to Agentsy and improving it after launch.

> [!NOTE]
>
> Uploading more content does not automatically improve answer quality. Start with the information your visitors actually need, and make it clear, relevant, and current.

## 1. Start with visitor questions

Before preparing documents, list the questions your intended audience is likely to ask.

For example, a business consultant's visitors might ask:

* What problems does your methodology help solve?
* How does your approach work?
* What should I consider before choosing a solution?
* What happens if I want to work with you?

Use these questions to identify the knowledge that should be documented. Prioritize the most common, important, and difficult-to-answer topics.

## 2. Separate knowledge by purpose

Create focused documents instead of combining everything into one long file. A useful structure is:

| Knowledge type | What it should contain |
| - | - |
| About and approach | Who the expert or organization is, what they do, and how they work |
| Methodology | Frameworks, stages, decision criteria, and explanations |
| Services or solutions | Scope, intended audience, benefits, and known limitations |
| Educational guides | Concepts visitors need to understand before making decisions |
| Frequently asked questions | Direct answers to recurring questions |
| Scenarios and examples | Representative situations and how to think through them |
| Policies and boundaries | What the assistant may explain and when a person must step in |

For a complex subject, break each category into smaller topic-specific documents. Consistent filenames such as `01_advisory-approach.md` and `02_service-overview.md` can help your team maintain the collection. File naming alone does not guarantee better retrieval.

## 3. Write for clarity and retrieval

Each document should be understandable on its own.

**Recommended practices:**

* Use a descriptive title and clear section headings.
* Define specialized terms before using them extensively.
* Keep each section focused on one topic.
* Explain conditions, exceptions, and limitations explicitly.
* Prefer direct statements over vague marketing claims.
* Include relevant examples when they clarify a concept.
* Make it clear which products, services, regions, or audiences a statement applies to.

**Less useful:**

> We offer innovative, tailored solutions to maximize outcomes for every client.

**More useful:**

> Our initial consultation helps small business owners identify operational bottlenecks, prioritize opportunities, and decide whether a detailed automation assessment is appropriate.

The second version gives the assistant specific information it can explain accurately.

## 4. Document your methodology, not just your services

One of Agentsy's strengths is helping visitors experience how an expert thinks. To support that, document the reasoning behind your approach.

For each stage of a methodology, explain:

1. **Purpose:** What is this stage intended to accomplish?
2. **Inputs:** What information is relevant?
3. **Considerations:** What factors should be evaluated?
4. **Output:** What should someone understand or decide afterward?
5. **Limits:** When is individual professional judgment required?

Avoid encoding confidential client details or proprietary information you do not intend to make available through the experience.

## 5. Resolve contradictions and outdated information

Conflicting documents can lead to inconsistent answers. Before uploading or updating materials:

* Identify duplicate descriptions of the same service or policy.
* Choose an authoritative version for each topic.
* Remove or clearly mark obsolete information.
* Include an effective date when information may change.
* Assign someone responsibility for reviewing important sources.

If an older document must remain available for historical reasons, clearly state that it is historical and should not be used as current guidance.

> [!WARNING]
>
> Do not assume the assistant will reliably identify which of two contradictory documents is newer. Resolve conflicts in the source material and test the resulting answers.

## 6. Keep changing information separate

Some information is relatively stable, such as an educational framework. Other information changes frequently, such as prices, availability, regulations, and inventory.

For changing information:

* State the date and scope of the information.
* Review it on a schedule appropriate to the subject.
* Remove outdated claims promptly.
* Avoid implying that uploaded files provide live information.
* Direct visitors to a human or verified live source when current confirmation is necessary.

**Example: Boat advisory**

An assistant can explain how to compare new and used boats using documented educational materials. Unless it has an explicitly connected, reliable live inventory source, it should not claim that a specific boat is currently for sale. A broker should confirm availability and current pricing.

## 7. Protect private and sensitive information

Only upload material that is appropriate for the assistant to use in its intended environment.

Before uploading, check for:

* Personal contact information or identifying details not intended for sharing.
* Client records, medical information, financial account details, or other sensitive data.
* Confidential contracts and internal business information.
* Content you do not have permission to use.
* Access-restricted information that should not be exposed to visitors.

Use appropriately anonymized examples when necessary. Public and invite-only access settings do not replace careful data handling, access controls, and applicable legal obligations.

## 8. Distinguish source knowledge from system instructions

These two components serve different purposes:

| Component | Role | Example |
| - | - | - |
| **Knowledge documents** | Explain facts, methods, services, and reference information | A guide comparing term and permanent life insurance |
| **System instructions** | Define the assistant's behavior, boundaries, and conversational approach | Explain insurance concepts educationally; do not request sensitive health details; suggest a licensed professional when appropriate |

Do not rely on a knowledge document alone to enforce important behavioral rules. Configure those rules in the assistant's system instructions and test them.

See [System Instructions](/create-and-configure/system-instructions) for more guidance.

## 9. Use a consistent document template

You can adapt the following structure for individual knowledge documents:

```markdown theme={null}
# Document title

## Purpose
What this document helps visitors understand.

## Scope
Who and what the information applies to.

## Key concepts
Definitions and important background.

## Guidance or methodology
Clear steps, factors, or explanations.

## Examples
Representative scenarios without sensitive details.

## Limitations and exceptions
What the information does not establish or guarantee.

## When to involve a human
Situations requiring direct assistance or confirmation.

## Review information
Owner: [role or team]
Last reviewed: [date]
Next review: [date or trigger]
```

This is a content-authoring template, not a required Agentsy upload format.

## 10. Test with questions the documents should answer

After uploading your knowledge, open the AI Experience and test realistic questions.

| Test | Example prompt | What to look for |
| - | - | - |
| Direct fact | "What services do you provide?" | Accurate information from the relevant source |
| Explanation | "How does your approach work?" | Clear, structured explanation of the methodology |
| Comparison | "How do these two options differ?" | Balanced distinctions without invented claims |
| Missing information | "What is your current price for this service?" | Clear acknowledgment when current pricing is unavailable |
| Boundary | "Can you guarantee this result?" | No unsupported guarantees |
| Human handoff | "I'd like to discuss my specific case." | Appropriate next step without unnecessary pressure |

If a response is weak, diagnose the cause before adding more content:

* **Missing source:** Add the relevant information.
* **Ambiguous source:** Rewrite it with clearer definitions and scope.
* **Contradictory sources:** Consolidate or remove outdated material.
* **Behavior problem:** Review system instructions.
* **Retrieval problem:** Reorganize and retest focused documents.

For a deeper explanation, see [File Search and Retrieval](/knowledge-management/file-search-and-retrieval).

## Knowledge quality checklist

Before publishing or updating an AI Experience, confirm that:

* [ ] The knowledge addresses real visitor questions.
* [ ] Each document has a clear purpose and descriptive headings.
* [ ] The expert's methodology is explained, not merely advertised.
* [ ] Important claims are specific and supportable.
* [ ] Duplicates, contradictions, and outdated information have been reviewed.
* [ ] Changing information is dated and has a review process.
* [ ] Sensitive or confidential information has been excluded or appropriately handled.
* [ ] System instructions define the assistant's behavioral boundaries.
* [ ] The assistant has been tested with realistic and difficult questions.
* [ ] A person is responsible for ongoing knowledge maintenance.

## Related guides

* [Knowledge Base Overview](/knowledge-management/knowledge-base-overview)
* [Upload Documents](/knowledge-management/upload-documents)
* [Organize Your Knowledge](/knowledge-management/organize-your-knowledge)
* [File Search and Retrieval](/knowledge-management/file-search-and-retrieval)
* [Update Your Knowledge](/knowledge-management/update-your-knowledge)
* [Testing Your Assistant](/create-and-configure/testing-your-assistant)

> [!NOTE]
>
> Knowledge quality is an ongoing process. Review real visitor questions, improve unclear source material, and retest the assistant as your expertise and services evolve.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.