Documentation Agents: 3. Test and Evaluate
Designing and configuring the agent is only the beginning. A documentation agent still has to be prepared for real usage.
Before publication, this means anticipating how users will interact with it, defining what a useful answer should look like, and verifying that its behavior matches the service it was designed to provide.
A documentation agent should not be tested only from the perspective of the person who built it.
It should be tested from the perspective of the people who will use it, with realistic questions, realistic documentation, and realistic expectations.
An expert technical writer is well positioned to do this: understanding audiences, usage contexts, recurring difficulties, and information needs is already part of the job.
This means anticipating how users are likely to interact with the agent, what a useful and reliable answer should look like, and how to verify that the agent behaves correctly — including when it should not answer.
Testing is not a final technical check. It is part of the design of the service.
Design the Output Before Testing the Agent
A documentation agent should not answer in the same way regardless of the service it provides.
A documentation-quality agent may need to return comparisons, detected issues, and recommendations. A support agent may need to provide a direct answer, step-by-step guidance, and an escalation path.
The output format and structure should therefore be defined before testing starts, because they formalize how the response is expected to serve the user and provide a reference against which the agent can be evaluated.
Design the response through the output around the service, not around the model.
Thinking about the output in advance serves two purposes: it helps anticipate how users will interact with the agent, and it makes the testing phase more concrete by defining what a successful response should look like.
Structure Builds Trust
A reliable output should make three things immediately visible: where the information comes from, where uncertainty or limitations exist, and what the user can confidently do next.
References support traceability. Warnings make uncertainty visible. Clear next steps make the answer actionable.
Conversation Starters are Part of the Design
Conversation starters are not just interface suggestions.
They are part of the usage model.
That is why they should be designed early, from the same real use cases already identified when defining the agent's role and prompt.
They help users understand what the agent is for, what kind of questions it can handle, and how those questions can be formulated.
Typical starters might include:
- a request for explanation;
- a request for a detailed or targeted explanation across a large body of documentation;
- a terminology question.
Their purpose is not to showcase everything the agent could theoretically do.
They also provide concrete examples for users who may not immediately know how to start interacting with the agent — a useful way to reduce the “blank page” effect.
If it is difficult to formulate realistic conversation starters, this may indicate that the agent's role, audience, or expected service is still too vague.
Build Test Prompts Before Publication
Now that the prompt is solid and the conversation starters reflect the intended use cases, the process moves outside the prompt and into a dedicated test phase before publication.
Test prompts help the designer verify that the agent behaves as intended.
Rather than testing with a random collection of questions, it is useful to organize test prompts into categories and levels of criticality.
Build a Progression of Test Scenarios
The first level validates the basics.
Higher levels progressively test more demanding situations, from handling conflicting or confidential information to refusing to answer or managing escalation according to the instructions defined in the prompt.
Test the Boundaries, not only the Happy Path
Boundary cases help verify whether the agent can respect its scope, apply its guardrails, recognize insufficient evidence, and avoid generating an answer simply because a question was asked.
In my experience, structuring tests this way was particularly useful during iterative design, including when working with Copilot to identify cases that could expose weaknesses in the prompt or agent behavior.
The purpose of this pre-publication phase is to detect and correct as many issues as possible before the agent is made available to users.
Evaluate Agent Performance
Once the agent has passed its initial test scenarios, evaluation can make this validation more systematic and repeatable.
The objective is to assess the agent against a broader or more targeted set of scenarios and defined success or failure criteria.
Build Evaluation Datasets Around Success and Failure Criteria
Evaluation datasets are close to the test prompts used during design, but they make it easier to evaluate the agent consistently and compare results over time.
They can cover a broad range of representative questions or focus on specific areas: frequent questions, strong or weak indicators of expected behavior, difficult cases, misleading requests, or scenarios that should result in clarification, escalation, or refusal.
What matters is to define what success and failure mean for the service being evaluated.
Depending on the agent, success may mean retrieving the right source, producing a reliable synthesis, respecting terminology, providing an actionable procedure, or correctly refusing an unsupported request.
In Rovo Studio, agent evaluation can be run against CSV datasets containing prompts and, optionally, expected responses.
These datasets make it possible to evaluate published agents repeatedly and review metrics such as resolution rate, while also examining individual responses manually.
When the prompt, knowledge surface, skills, or underlying documentation changes, the same evaluation datasets can be reused to identify regressions or improvements.
Evaluation datasets therefore provide a reusable baseline for validating the agent throughout its evolution.
Evaluate and Iterate Throughout the Agent Lifecycle
Once the agent is in real use, evaluation moves from controlled performance to actual adoption, relevance, and usefulness.
Usage data can provide metrics and KPIs defined by the organization, while platform analytics and direct user feedback show how people actually interact with the service.
In Rovo Studio, for example, Insights can provide usage metrics such as average daily users and total conversations. Reviewing real conversations adds another perspective by revealing recurring questions, unexpected use cases, difficulties, or areas where the agent may still need adjustment.
These quantitative data and qualitative feedback make it possible to keep the agent relevant after publication.
Feed Documentation Improvement
Agent usage can itself produce valuable information about the underlying knowledge base.
Recurring failures, difficult questions, unresolved requests, or unexpected patterns may reveal missing documentation, weak metadata, unclear terminology, conflicting sources, or new user needs.
They can therefore trigger improvements in the documentation itself.
Documentation → Agent usage → Usage data and user feedback → Documentation improvements → New evaluation
Iterate on the Agent
The same information can feed a second loop focused on the agent itself.
Agent usage → Evaluation → Adjustments → Testing → Updated agent
Adjustments may concern the prompt, knowledge surface, skills, output, use cases, or other parts of the agent design.
This creates a continuous improvement process in which the agent evolves alongside the documentation, users, and services it supports.
In my own project, I was able to design, configure, and test the agents before publication, but my mission ended before I could observe their long-term usage, collect significant user feedback, or iterate from real adoption data.
Know When to Stop an Agent
Managing an agent over time also means being prepared to question its continued usefulness.
An agent may need to evolve as the documentation, product, users, or business needs change.
And if the service it was designed to provide is no longer useful, it should be retired rather than allowed to become another obsolete layer in the knowledge ecosystem.
Agent lifecycle management also means knowing when to stop an agent.
An agent should not become another obsolete asset that nobody dares to remove.
Bonus: Experimental Techniques to Support Adoption
Beyond formal testing and evaluation, a few experimental techniques can help improve trust and reveal weaknesses.
Use Confidence Indicators as Guidance
In some of my agents, I experimented with confidence or reliability indicators to help users assess how cautiously they should interpret an answer.
These scores were not scientific metrics. They were designed as signals: to increase transparency for users and to highlight documentation areas that might require attention from authors.
Make Critical Rules Visible
Highlight mandatory behaviors in the prompt.
Using labels such as IMPORTANT or Critical Rule can help distinguish mandatory behaviors from general guidance.
Design the "No" Experience
Plan how the agent should refuse, clarify, or escalate.
A controlled refusal, clarification request, or escalation path can be more useful than a plausible but unsupported answer.
Use the Agent to Probe the Documentation
Carefully chosen questions can reveal missing context, weak metadata, conflicting sources, or terminology issues in the underlying knowledge base.
Explore the full Documentation Agents approach: Strategy → Architecture → Testing and Evaluation.
© Author: Florence Venisse, Technical Documentation & AI Expert – First version dated September 12, 2026