I recently shipped an internal knowledge agent for an engineering consultancy — the "Atlas" case study is here. Most of what I believed going in turned out to be half-right. Here's what survived contact with real users.
1. A narrow job description beats a smart assistant
The agents that work are the ones with a boring, checkable job: answer questions from company documents, with citations, or say you don't know. Every time we were tempted to widen the brief ("could it also draft proposals?"), the answer quality of the core job dropped. Ship the narrow thing first. Widen later, deliberately.
2. Citations are a feature, not a garnish
The single biggest driver of trust wasn't answer quality — it was that every answer linked to its sources. People stopped asking "can I trust this?" because they could check in one click. As a bonus, the questions that produced bad citations became a map of stale documentation.
3. Permissions are the actual hard part
Wiring a model to a search index is a weekend. Making sure the agent never shows an HR document to someone who couldn't open it themselves is the real engineering. Index documents with their access lists, trim every query by the signed-in user's groups, and test it adversarially. If you skip this, your pilot ends the first time someone screenshots a salary file.
4. Build the evaluation set before the agent
We collected 120 real questions from staff and wrote expected answers before tuning anything. Every prompt tweak and retrieval change ran against that set. Without it you're steering by anecdote — the loudest tester's last experience becomes your roadmap.
5. The UI should be the most boring part
A plain chat surface in the tools people already use (web + Teams) beat every clever interface idea we sketched. Novelty budget belongs in retrieval quality and permissions, not in the front end.
Thinking about an agent for your own company's knowledge? Tell me what you're working with — I'll give you an honest read on whether it's worth building.