Documentation Agents: 2. Design the Architecture
Once the need, audience, service, and expected benefits have been defined (see Agentic AI: 1 Define the Strategy), the next challenge is architectural:
How do you design the right agent for the right knowledge environment?
A technical writer does not operate in a vacuum.
Before designing an agent, they already need to understand the documentation ecosystem: what knowledge is available, how it is organized, who produces and uses it, and which parts can or should be exploited.
This knowledge directly shapes the agent's behavior.
Its design depends on:
- knowledge it can access;
- structure and hierarchy of that knowledge;
- audiences and ownership of the content;
- types and formats of information it must understand;
- metadata available — or missing — and what it describes;
- lifecycle and status of the content;
- skills it needs;
- actions it is allowed to perform;
- guidance provided by its prompt: instructions, priorities, and guardrails.
Configuring the agent is therefore not merely a technical setup phase.
It is an extension of documentation strategy, drawing on the technical writer's knowledge of the corpus, users, information architecture, terminology, governance, and documentation practices.
Understand the Content Before Configuring the Agent
Technical documentation is rarely made of prose only.
Across the documentation ecosystems I have worked with in recent years, the content could include:
- text;
- screenshots and illustrations;
- diagrams, including Mermaid diagrams;
- PNG and SVG visuals;
- command-line snippets;
- REST API endpoints;
- Python library examples;
- other code examples and technical instructions;
- mathematical formulas.
This matters because the agent must be designed around the real form of the documentation it will process.
In technical environments, meaning is often distributed across several content types. A procedure may combine explanatory text, command-line instructions, code snippets, diagrams, and API examples.
The agent therefore needs to interpret these elements together rather than treating the documentation as a purely textual corpus.
This led me to clearly define behaviors such as the following in the agent design:
Handle code and documentation together.
The same applies to visual content.
If important knowledge is carried by diagrams, screenshots, or other visual assets, the agent needs the appropriate capabilities to access and interpret them.
The architectural question is therefore not only:
What knowledge should the agent access?
It is also:
What forms does that knowledge take, and which of them must the agent be able to understand?
Prompt Design is Architecture
Designing the prompt starts before writing the prompt itself.
It brings together the decisions and information collected during the previous steps: the agent's role, the service it should provide, the expected benefits, the knowledge it can access, the types of content it must understand, the risks to avoid, and the policies or constraints that apply within the organization.
Translate Design Inputs into Instructions
The prompt turns all these elements into a formal, structured set of instructions.
| Design input | How it translates into the prompt |
|---|---|
| Agent role | Role description and mission |
| User need and expected service | Objectives and typical use cases |
| Target audience | Tone, level of detail, response style |
| Expected benefits | Success criteria and expected outcomes |
| Knowledge surface | Scope and allowed sources |
| Content to exclude | Out-of-scope rules and restrictions |
| Content types and formats | Instructions for handling text, code, visuals, or other technical content |
| Documentation structure | Retrieval and navigation rules |
| Metadata and lifecycle information | Source prioritization and reliability rules |
| Terminology and vocabulary | Normalization rules and glossary references |
| Company policies and constraints | Guardrails and mandatory behaviors |
| Known documentation weaknesses | Conflict handling, ambiguity management, fallback rules |
| Expected user interaction | Response format, guidance, escalation, or next actions |
The more precisely these elements are defined, the more predictable and useful the agent becomes.
An Iterative Design Process
In practice, building these prompts was an iterative and collaborative process with AI. I used Copilot, the AI assistant available in the company environment, as a working partner to structure the prompts, challenge formulations, identify missing cases, refine instructions, and improve the organization of the expected responses.
As the technical writer and documentation expert, I remained at the initiative of the project and acted as the conductor of the process: defining the direction, supervising the work, providing the instructions, and making the design decisions based on the documentation context, my domain knowledge, and my understanding of the users and their needs.
I also acted as an editor throughout the process. The prompts were progressively refined through review, correction, post-editing, and repeated iterations until the agent behavior matched the intended service as closely as possible.
Make Priorities Visible in the Prompt
Critical instructions should be clearly identified so that the agent can distinguish them from more general guidance. Labels such as IMPORTANT, Critical Rule, or Critical Behavior can act as markers that establish a hierarchy among instructions and make rule precedence clearer.
The principle is similar to precedence in CSS: some rules are intended to override more general ones. For example, an instruction to exclude client-specific information should take precedence over a broader instruction to retrieve as much relevant context as possible.
This is especially important when structuring a prompt that combines task instructions, expected behaviors, scope restrictions, and fallback rules.
Define Scope for Operational Boundaries
The knowledge surface defines where the agent can retrieve information. The scope and out-of-scope rules define how the agent is allowed to behave within that environment.
These rules translate the documentation strategy into operational boundaries.
Depending on the service the agent is expected to provide, they may define:
- which types of requests the agent should handle;
- which topics, audiences, or information it must exclude;
- how it should treat mixed or ambiguous content;
- which actions it is allowed to suggest or perform;
- when it should redirect, escalate, or refuse to answer.
This creates a direct link with the services defined earlier (see Agentic AI: 1. Strategy).
An onboarding agent may explain concepts and guide users, but should avoid answering unrelated corporate questions. A support agent may provide step-by-step guidance and suggest escalation, but should not invent undocumented troubleshooting steps. A documentation analysis agent may identify duplicates or inconsistencies, but should not automatically delete or rewrite content without validation.
Define Out-of-scope Behavior
A useful agent therefore also needs to know when not to answer.
If the available knowledge is incomplete, contradictory, outside the defined scope, or not reliable enough, the safest response may be to state that limitation clearly rather than generate a plausible answer.
Depending on the use case, the agent can then:
- ask for clarification;
- break a broad request into smaller subtopics;
- ignore out-of-scope content and continue searching;
- limit the answer to verified information;
- point to the available source;
- recommend validation;
- redirect the user to another service or agent;
- trigger an escalation path;
- or simply say no when no reliable or relevant information is available.
This ability to step back is not a weakness of the agent. It is part of its reliability.
Failure behavior must be designed as deliberately as successful behavior. It is not an edge case to add later.
Leverage Metadata for Source Qualification
Metadata is part of the knowledge architecture the agent relies on.
Retrieving relevant information is not enough. The agent also needs signals that help it qualify the sources it finds and distinguish between content that is merely available and content that is more likely to be current, authoritative, or reliable.
These source-qualification rules can rely on metadata such as:
- authorship and ownership;
- creation and update dates;
- page history and version information;
- lifecycle status;
- labels and categories;
- source type;
- indicators such as
archived,deprecated,WIP, or equivalent statuses.
The native proximity between Rovo and Confluence make it possible to base these rules on Confluence metadata, such as authorship and page history, as well as on user-defined metadata such as statuses or labels.
In a documentation website (like the one you are reading right now), structured metadata can play the same role through front matter, taxonomy, publication and modification dates, content status, canonical information, or other machine-readable fields.
These metadata provide additional context that helps the agent qualify retrieved information and distinguish between what is merely available and what is more likely to be current, authoritative, or relevant.
If these signals are missing, inconsistent, or poorly maintained, that absence is itself useful information: it can reveal weaknesses in documentation governance, lifecycle management, or metadata quality.
From SEO to GEO — How structured metadata can improve both discoverability and AI readability in documentation websites.
Define the Knowledge Surface
A documentation agent should not necessarily have access to everything.
A knowledge base gathers content with very different purposes, maturity levels, audiences, ownership rules, and confidentiality requirements.
Defining the knowledge surface therefore means deciding exactly which part of the corpus the agent is allowed — and needs — to use.
This decision serves two purposes:
- protect information that should remain outside the agent's scope;
- improve relevance by focusing the agent on the knowledge required for its intended service.
A surface that is too narrow can provide too little context and produce poor or incomplete answers. The agent may ultimately bring little additional value.
A surface that is too broad — for example, “the entire knowledge base” or “all R&D content” — can create the opposite problem: too much noise, irrelevant or contradictory information, or content with very different lifecycle statuses treated as equally authoritative.
The right surface is therefore neither the largest nor the smallest possible.
It is the one that provides enough context for the agent to perform its service reliably, without introducing unnecessary noise.
In my case, I deliberately restricted the surface to the technical documentation included in my audit. I excluded marketing and communication areas, personal spaces, project-specific content, and client-specific information.
Some exclusions were defined directly in the prompts; others were applied through the Knowledge configuration in Rovo Studio.
Choosing the knowledge surface is part of documentation strategy.
Choose the Right Skills
Skills are part of the architecture.
Once the agent's role, scope, priorities, and expected behavior have been defined, it needs the capabilities required to perform that role.
The question is not:
Which skills are available?
It is:
Which capabilities does the agent need to deliver the service it was designed for?
For documentation agents, two capabilities are particularly important.
Navigating the Hierarchy
A documentation agent must be able to navigate the structure of the knowledge base, not just retrieve isolated pages.
Relevant knowledge may be distributed across parent and child pages, several levels of hierarchy, or related documentation sets. The agent therefore needs to move from one page to another and preserve enough context to understand how the information fits together.
This is especially important for large technical documentation ecosystems, where the answer rarely lives on a single page.
Finding the Source of Truth
Retrieving information is not enough. The agent also needs to identify which information deserves the most trust.
This is particularly important in long-lived knowledge bases where several versions may coexist, older pages remain accessible, or content is marked as draft, WIP, archived, legacy, or deprecated.
This assessment can rely on metadata (see above) such as update dates, version information, lifecycle status, ownership, or other indicators of authority and freshness.
The same principle applies to a knowledge base such as Confluence and to a documentation website whose metadata is sufficiently structured and maintained.
The agent therefore needs capabilities that help it distinguish between information that is merely available and information that is likely to be authoritative, current, and reliable.
Skills and Tools are Different
A skill and a tool do not play the same role in an agent architecture, especially in Rovo Studio.
- A skill defines a reusable way for the agent to approach or perform a task.
- A tool exposes an executable capability that the agent can invoke, generally with defined inputs and outputs.
Depending on the AI platform, these tools may be provided by the platform itself or exposed through integrations, connectors, MCP servers, or other external systems.
The distinction becomes especially important when moving beyond a standalone agent: tools can allow an agent to interact with other systems, trigger actions, exchange structured information, or participate in a broader multi-agent architecture.
From Specialization to Orchestration
Specialization remains an important architectural principle.
Each agent should have a clearly defined role, scope, and expected behavior. Some overlap can nevertheless be useful when agents are also designed to operate independently.
For example, an information-retrieval agent may need basic terminology-normalization capabilities even when a dedicated glossary agent exists. The objective is not to eliminate every overlap, but to keep responsibilities sufficiently distinct for each agent to remain understandable and useful.
When several specialized agents coexist, an orchestrator can provide a single entry point for the user.
The user should not need to know which agent is responsible for retrieval, support, terminology, or documentation quality — or even decide in advance why the question belongs to one category rather than another.
The orchestrator can interpret the request, involve the relevant expertise, combine the findings, and return a single coherent response.
This creates a useful separation between:
- internal specialization: several agents, each designed around a specific documentation service ;
- and external simplicity: one interaction and one consolidated answer for the user.
A simplified architecture can be represented as:
This diagram represents the architectural principle rather than the detailed execution workflow. A real orchestrator may use conditional routing, sequential processing, parallel calls, or other decision paths depending on the request.
Unfortunately, although I designed the orchestration workflow for my four agents, I could not implement it because I did not have access to the required Tools configuration in Rovo Studio.
The Expert Technical Writer as Agent Architect
Designing a documentation agent — and even more so a system of agents — requires more than knowing how to write a prompt.
It requires expertise in domain knowledge, information architecture, users and usages, terminology, governance and metadata, technical content.
This is why I would describe this role as one for the expert technical writer.
The technical writer already works at the intersection of knowledge, users, products, and documentation systems. Agent design extends this responsibility to a new way of consuming and interacting with that knowledge.
The output is no longer only a page, a guide, or a documentation portal.
In a docs-as-data approach, the technical writer also designs how documented knowledge can be retrieved, interpreted, combined, and reused by AI systems.
The objective is not to replace traditional documentation consumption, but to make knowledge easier to access and use through complementary modes of interaction.
-
Users can still browse, search, and read the documentation directly.
-
Agents can add another layer: questioning the corpus in natural language, consolidating distributed information, guiding users, or turning documented knowledge into an actionable service.
AI platforms provide models, skills, tools, and integrations.
But designing a reliable documentation agent still depends on human expertise to determine what knowledge should be exposed, how it should be interpreted, which rules should govern the agent, and what service it should ultimately provide.
Building the right agent starts with understanding the knowledge before configuring the AI.
Continue with Step 3: Test and Evaluate.
© Author: Florence Venisse, Technical Documentation & AI Expert – First version dated September 12, 2026