How to train an AI support agent on your own docs
"Upload your docs, get a support agent" is the pitch of every tool in this category, and it is roughly a third of the truth. The other two thirds are the curation the docs cannot do for themselves, and the questions no document can answer at all. Here is the honest version.
Why raw doc-dumping disappoints
Documentation is written for a reader who already knows what they are looking for. Support questions come from people who do not: they describe symptoms ("it says my session expired"), not features ("token refresh"). A retrieval pipeline over raw docs matches the words, not the situation, so it returns the right page to the wrong question, and the agent paraphrases documentation at a person who needed an answer.
There is a second, quieter failure: docs go stale, and a stale doc in a retrieval index is a confident wrong answer with a citation. The agent did nothing wrong; it was grounded in something false.
What actually works: curated Q&A knowledge
The agents that feel good to talk to are trained on knowledge shaped like the conversation: a question the way a customer phrases it, and the answer the way your best support person would give it. Your support history already contains this corpus; curating the recurring questions into direct Q&A pairs takes hours, because support volume follows a steep power law. Twenty good pairs usually cover the bulk of repeat traffic.
Then ship, and read the conversation logs. Every question the agent fumbled is the next knowledge entry. The logs are a better roadmap than the documentation ever was.
The questions docs can never answer
Half of real support traffic is not about the product, it is about the customer: "where is my order", "why was I charged twice", "did my upload finish". No document answers those; they need a live, scoped read of your application's own data at question time. A doc-trained agent meets these questions by apologising. This split, static knowledge for product questions and live data for account questions, is the architectural decision that matters more than which model you run.
The guardrails that keep it honest
- Ground hard. The agent answers from the knowledge it was given, and when the answer is not there it says so and hands off to a human. An agent that sometimes says "I don't know" is trusted; one that is always confident is not.
- Scope the system prompt. What the agent is for, what it must never do (quote unlisted prices, promise refunds, give legal advice), and the voice it answers in.
- Keep keys out of the client. An LLM API key in your website's code is a key anyone can lift from view-source and spend. The provider keys belong behind a backend that also rate limits and moderates.
Doing it with SparkBrain
SparkBrain is this architecture as a managed platform: each
registered app gets its own agent with a custom system prompt, its
own curated FAQ knowledge, and live answers from the app's database
for the account-shaped questions. It deploys as a chat widget with
one <script> tag, zero API keys in client code,
with rate limiting and moderation handled between your app and the
LLM providers. The free tier includes the AI agent, so the test costs
nothing: see the docs or try the
playground.
FAQ
Can I just upload my documentation and get a working support agent?
You will get an agent that answers like documentation, which is the common disappointment. Docs are written for a reader who already knows what they are looking for; support questions are phrased by people who do not. The fix is curating the recurring questions into direct Q&A knowledge, which takes hours, not weeks, because your real support history already tells you what gets asked.
Why does my docs-trained chatbot make things up?
Because a language model fills gaps by default. When retrieval returns half an answer, an ungrounded agent completes it plausibly: inventing prices, flags, and version numbers. The guardrail is instructing the agent to answer only from the knowledge it was given and to say so and hand off when the answer is not there. An agent that sometimes says "I don't know, here's a human" is trusted; one that is always confident is not.
Can an agent trained on docs answer questions about a customer's own account?
No, and this is the half of support traffic doc-training cannot touch. "Where is my order" and "why was I charged twice" have no answer in any document; they need a live, scoped read of your application's data at question time. SparkBrain agents combine FAQ knowledge with live answers from the app's own database for exactly this split.
Do I need to expose an AI API key in my website's code to run a support agent?
No, and you never should: a key in client code is a key anyone can lift from view-source and spend. The agent should run behind a backend that holds the provider keys, enforces rate limits, and moderates input. SparkBrain's widget is one script tag with zero API keys in the client; the platform sits between your app and the LLM providers.
How much documentation do I need before an AI support agent is useful?
Less than you think. Twenty well-chosen Q&As typically cover the majority of repeat support volume, because support questions follow a steep power law. Start with the questions you are tired of answering, ship, read the conversation logs, and add what the agent missed. The logs are a better roadmap than the docs.