In my last post, Egeria Advisor: The Live Gateway and the Feedback Loop, we explored how the Egeria Advisor transitioned from a passive reference guide into an active operational tool by integrating the Model Context Protocol (MCP) and running live, context-driven report specifications. We gave our multi-agent framework a way to look into and interact with a live metadata estate.
But as we began using the system to execute individual commands against our environment, we hit a fundamental user experience barrier. Data governance is rarely a series of isolated, transactional clicks.
True governance work consists of thoughtful acts of authoring and design. Defining a new Digital Product, grouping resources into Digital Product Families, organizing a Digital Product Catalog, or mapping an Information Supply Chain are all creative and structural design exercises. They require human explanation, rationale, and context just as much as they require backend schema definitions.
To support these authoring activities, we had to move past the traditional, single-pane chatbot paradigm. We needed an environment where human narrative and structured representation live side by side. This realization gave rise to the approach for Literate Governance with Context Intelligence — and the introduction of our split-screen, collaborative design canvas.
What is Literate Governance?
The concept borrows heavily from Donald Knuth’s philosophy of Literate Programming. Instead of writing disconnected code or filling out rigid forms, data stewards and engineers can author an integrated document that explains why a structure exists in plain natural language, right alongside the precise commands that create it.
Dr.Egeria’s markdown-based architecture is natively built for this. A single Dr.Egeria file is essentially a structural narrative document. It can contain blocks of descriptive text explaining what a system does, separated by native markdown commands that define governance definitions, asset schemas, or module relationships.
The benefit of this approach is its lifecycle simplicity. A user can author a multi-step document that lays out a new Project or Information Supply Chain. The final command of that exact same Dr.Egeria file can automatically trigger a live report execution, immediately generating dynamic Mermaid diagrams and definitions of the newly executed commands.
This compiled report can be shared with team members for peer review. When feedback comes back, the user doesn’t jump through different software applications; they simply update the text in the markdown document, re-execute it, and save the finalized version as a repeatable template. Alternatively, since the Dr.Egeria document is completely human-readable, others can review and edit the document by itself, sending the updated file around for discussion. When everyone is happy, the document can be validated and reprocessed by Dr.Egeria.
The Split-Screen Experience: Chat and Canvas
The core engineering challenge of Literate Governance is catering to different user perspectives: the expert who already knows the Dr.Egeria markdown commands by heart, and the novice who understands their business goals but has no idea where to start or how to format the underlying configuration syntax (and of course, an individual can do a mixture of both).
To solve this, the Egeria Advisor UI evolves into a split-screen workspace where the conversational Chat Interface and the interactive Command Canvas collaborate in real time.
🖥️ The Egeria Advisor Workspace Layout
- Folders Pane (Plan Folders): Dedicated navigation space organizing plans into their different operational lifecycle stages.
- Left Pane (Dialog Window): The conversational guide powered by our multi-agent backend. It translates business intent, fetches template code, and answers context questions.
- Right Pane (Interactive Canvas): A full-featured markdown and script editor where the actual Dr.Egeria playbook is constructed, refined, and executed against the platform.
This split UI creates three distinct on-ramps for our community:
1. The Expert Path (Direct Authoring on the Canvas)
Power users can completely bypass the chat interface if they choose. They can click directly into the canvas pane and author their Dr.Egeria markdown by manually selecting from Dr.Egeria templates, filling in what they want, and adding narrative text around them. When ready, they can hit “Validate” and “Execute”. The canvas acts as an intelligent, template-driven text editor hooked directly to our backend validation and execution code in Dr.Egeria (which runs as part of pyegeria).
2. The Novice Path (Conversational Generation)
Users unfamiliar with Dr.Egeria commands can treat the chat interface as an expert pairing partner. The user simply types their goal in plain language:
“Create a plan to create a Solution Blueprint called Coco Pharmaceuticals Sales Forecast Consolidation and solution components for UK Sales Forecast, US Sales Forecast and EU Sales forecast. Each component is part of the solution blueprint. The final step is to View Report on the solution blueprint as a mermaid graph.”
Our backend DrEgeriaActionAgent catches this request, identifies the underlying intent, pulls the appropriate layout from the high-priority egeria_templates vector pool, and stream-populates the code canvas right before the user’s eyes. The user never types a single snippet of syntax; they watch their verbal thoughts take shape as a structured Dr.Egeria plan which they can then validate and execute.
3. The Hybrid Path (Collaborative Tweak and Tune)
The most powerful mode of operation is a mixture of both. The user can lean on the chat interface to generate the massive, complex skeleton of a 15-stage Information Supply Chain onto the canvas. Then, instead of typing back-and-forth prompts to fix tiny typos, they can click into the canvas editor and manually refine names, add customized markdown descriptions between the blocks, or delete unnecessary components on the fly. They can also update the plan through the chat interface concurrently. This is incredibly useful, although managing this inter-mixed lifecycle has required a few architectural redesigns behind the scenes!
Closing the Loop: Templates from Proven Plans
Once the human narrative and the structural components are locked down on the canvas, the user fires the execution sequence. The Advisor pushes the script through the MCP gateway, registers the assets, links the products, and invokes the reporting script to stream an interactive Mermaid visualization straight to the dashboard screen.
But the lifecycle doesn’t end at compilation. Once a user has successfully authored, verified, and executed a multi-step plan, they might want to reuse this same structure for similar tasks. In other words, we can use this working plan to seed future plans.
To capture that value, we introduced a template extraction feature. With a single click, the Advisor can strip out the specific text, entity IDs, and localized names from the canvas script, instantly converting it into a clean, reusable boilerplate file. This boilerplate is then automatically fed back into our backend vector index, and the new template instantly shows up in the user’s Plan Templates folder.
The next time a teammate approaches the chat interface asking to build a similar asset, the system uncovers this template, closing the circle of collective governance intelligence.
The new template shows up in the Plan Templates folder.
Key Takeaways from the Journey
Looking back across the narrative of these five blogs, the process of building the Egeria Advisor has left us with a few core insights into how intelligent assistants can fit into complex enterprise spaces:
- A single source is rarely a single thing. It is easy to treat a documentation folder or a repository as a uniform block of text, but they almost always contain multiple types of information with unique characteristics. We found that by taking the time to profile these differences and tune our ingestion and query strategies accordingly, we could unlock far more utility and meaning from the underlying context.
- Asking rather than guessing is a valuable design principle. Expecting a local LLM to consistently deduce a user’s role or exact intent from a brief, open-ended prompt is asking too much. By building explicit mechanisms into the interface to elicit perspective and intent, we take the guesswork out of the equation and can much more reliably give users exactly what they need.
- Determinism builds trust. Because language models are inherently probabilistic, their unpredictable nature can quickly erode user confidence in a production environment. While chasing perfection is an ongoing effort, introducing structured multi-agent boundaries gave us the predictable, repeatable routing consistency needed to make the system truly dependable.
- Interacting with the real world matters. An advisory tool can become isolated if it only answers static questions. Because enterprise data estates are constantly changing, grounding the assistant in reality meant giving it a secure gateway via the Model Context Protocol to query live reports and interact directly with the active environment.
- Governance requires design and collaboration. Literate Governance provides creative flexibility based on a user’s unique understanding, convenience, and intent. Rather than forcing compliance through fixed forms, Dr.Egeria plans allow users to author shareable, auditable, and transparent living documents. These documents explain the what and why in natural language right alongside the how, allowing governance models to incrementally evolve over time as users add more details, map new relationships, and view their data landscapes in entirely new ways. Execution of the documents can, when it makes sense, be automated.
The Journey Continues: Introducing Egeria Resource Explorer
Over the course of this five-part series, the Egeria Advisor transformed from a simple, unprofiled local RAG prototype with high hallucination rates into a useful, multi-agent assistant operating inside strict deterministic guardrails.
While this brings our initial five-part development series to a close, innovation on the Egeria Advisor platform hasn’t stopped. As the community uses the Advisor to support daily work, the system will continue to organically evolve, refine its metrics, and improve its coordination logic. Keep an eye out for upcoming video walkthroughs, in-depth tutorials, and standalone feature deep-dives.
In the meantime, I’ve been spending more development focus on a brand-new tool that borrows heavily from the architecture we’ve built here.
While the Advisor was built to handle interactive understanding, active administration, and authoring, the Egeria Resource Explorer is focused on discovering, surveying, and understanding information resources that can be reached across an enterprise. I’ll be sharing more details on those architectural developments in a forthcoming blog.
Thank you for following along on this development journey! The code, configuration frameworks, and agent routing logic are all open source on our GitHub, Egeria-Advisor—I welcome your reviews, PRs, and community feedback as we continue to push the boundaries of what open-source ML Ops and metadata governance can achieve.
As always, feedback is welcome!