The Freshservice Virtual Agent answers employee IT questions by retrieving from your Solutions knowledge base. Mediocre articles produce mediocre answers. Here is how to write knowledge for retrieval, not just human reading.
One question per article
The virtual agent retrieves whole articles, not paragraphs. Articles answering five questions confuse the retriever. Split them. A 200-word article answering one question outperforms a 2000-word omnibus.
Title with the question
Title articles as the question users ask. “How do I reset my VPN MFA token” beats “VPN MFA Procedures.” The retriever ranks title matches highly.
Front-load the answer
The first paragraph must contain the answer. Background, screenshots, and edge cases come after. The agent surfaces the first 150 characters as a preview.
Title: How do I reset my VPN MFA token
First paragraph: To reset your VPN MFA token, open the
Self-Service portal at /mfa-reset and click "Send reset
link." A verification email arrives within 2 minutes.Tag for routing
Use article tags that match common intents (vpn, password, printer, onboarding). The Virtual Agent uses tags to filter the retrieval candidate set, lowering latency.
Track no-answer events
The Freshservice analytics dashboard surfaces queries that returned no article above the threshold. Export these weekly. Each becomes a candidate new article.
// Export endpoint
GET /api/v2/virtual_agent/sessions?status=no_answer&since=...Feedback loop
Each agent response shows a thumbs up/down. Down-voted answers get logged with the original query. Triage these in the same weekly cadence as no-answer events.
Versioning expired procedures
When IT processes change, archive (not edit) the old article and publish a new one. The retriever may have indexed the old version, and partial edits produce stale answers.
What to do this week
Audit your top 20 viewed articles, split any covering multiple questions, retitle as the question users ask, and schedule a weekly 30-minute triage of no-answer and down-voted events.
