Beyond Chat-With-Your-Docs: A Reference Agentic AI Architecture for Auditable Systems

Almost every organisation with a document corpus has now seen the same demo. Someone connects an LLM to a folder, asks a question, gets a fluent paragraph back, and the room nods. Two weeks later the project is quietly parked.

The demo is not the hard part. The hard part starts when the output has to survive scrutiny: when a score assigned by the system determines whether a grant is funded, a claim is paid, a supplier is approved, or a report is filed with a regulator. At that point the question stops being "can the model answer" and becomes "can we defend this answer six months from now, to someone who was not in the room."

That second question changes agentic AI architecture completely. This article is a container-level blueprint for systems that have to answer it. We’ve recently designed one for a public-sector programme with a hard audit requirement, and the interesting thing about the design is how little of it was a matter of taste — nearly every decision was forced by a constraint. What follows is agentic architecture, abstracted from the specific domain, along with the reasoning that produced it.

Where this agentic AI architecture fits: domains and use cases

The architecture described in this article is not tied to a single domain. It is relevant wherever AI produces a score, synthesis, or recommendation that must later be explained and supported with evidence:

• ESG and sustainability reporting — scoring initiatives against frameworks, with per-criterion evidence and a defensible methodology trail.
• Grant and funding assessment — screening applications against published criteria, where every rejection needs an evidenced rationale.
• Commercial insurance underwriting — evaluating submissions against underwriting guidelines, with the guideline version recorded per decision.
• Contract and vendor review — assessing agreements against an internal playbook, flagging deviations with citations to the clause and the policy.
• Legal document review — analysing legal documents against defined requirements or internal guidance, with findings linked to the relevant clauses and supporting source material.
• Standards and certification assessment — evaluating applicant submissions against a published standard, where the assessor has to show which clause each finding rests on.
• Safety case and incident review — in rail, aviation, energy and heavy industry, assessing reports against standards and prior findings, with a full evidence chain.
• Corporate credit and investment memos — drafting grounded in policy documents and internal research rather than model recall.
• Bid and RFP response — scoring incoming bids against evaluation criteria, or drafting responses grounded in an approved content library.

One qualifier on that list. Several of these agentic AI systems sit inside regulated high-risk categories. Creditworthiness assessment for individuals and life or health insurance pricing are named explicitly in the EU AI Act's high-risk annex, and anything touching clinical decisions may fall under medical device rules. The architecture described here gives you the traceability, human oversight points and audit trail those regimes ask for, but it does not on its own make a system compliant. 

Conformity assessment, technical documentation obligations, post-market monitoring and the question of whether the system is a device at all are separate work, and they belong in scope from the start rather than discovered at launch. Where we have built in these directions, it has been for internal assessment and drafting workflows with a human decision-maker in the loop by design — not autonomous decisioning about individuals.

Across these domains, the architectural requirement is similar: the system must be able to show how an output was produced and what evidence it relied on. That requirement determines the types of tasks the platform needs to support. 

The class of agentic AI system: four jobs beyond question answering

The system considered here supports four related types of work over a curated corpus. Each places different demands on retrieval, provenance, orchestration, and evaluation, so they need to be considered together at the architecture level.

Grounded synthesis. A user asks a question in natural language and gets a synthesis assembled only from verified internal documents, with every claim traceable to a source fragment. The model is explicitly restricted from supplementing the answer with general knowledge.

Rubric scoring. The system evaluates a submitted artefact — a proposal, a claim, a design, a contract — against a structured rubric derived from reference documents, and returns a numeric score with per-criterion justification. The score has to be reproducible: the same input and the same rubric version must produce the same result within a stated tolerance.

Constrained generation. The system proposes new options while deliberately running at a higher creative temperature. Generated content is kept in a separate namespace so it cannot enter the verified corpus or later be retrieved as ground truth.

Iterative optimisation. Given a score, the system identifies which changes to the artifact would most improve it, tests variants, and keeps only the ones that measurably help.

All four agentic AI workflows also need to support human intervention at defined points. In practice, that intervention may happen hours or days after the system pauses.

This makes durable workflow state a core architectural requirement. This agentic AI system must be able to stop mid-task, persist the relevant state, and resume later, including cases where a different user continues the workflow.

These requirements also shape the roles around the system: who consumes the output, who approves intermediate decisions, and who controls the knowledge base that ultimately determines what the system can retrieve and score against. 

System context: an agentic AI system and the three roles around it

Three roles shape how the system is used and governed.

The Domain Analyst works with the outputs. They ask questions, review evidence, and assess the scores or recommendations produced by the system.

The Facilitator manages collaborative workflows. They guide group sessions in which the system presents results stage by stage and pauses when a decision or approval is required.

The Knowledge Owner controls the corpus that grounds the system. This is a subject-matter role rather than a technical administration role. The Knowledge Owner can adjust document weights, retire outdated sources, and resolve contradictions between documents.

That distinction matters because changes to the corpus can directly affect later scores and assessments. The Knowledge Owner therefore needs a non-technical interface for managing those inputs, while every change to document status, weighting, or version is recorded for auditability and reproducibility.

The system also depends on several external components. A document store acts as the source of truth for the verified corpus. LLM inference may be provided through managed services, self-hosted models, or a combination of both. Where external research is permitted, retrieval is restricted to an allow-listed set of public sources.

The platform then exposes its functionality through a REST API to the host portal or API bus that consumes the results and integrates them into the wider application environment.

Seven agentic AI architecture decisions that are expensive to reverse

Once these roles, data sources, and external dependencies are defined, the architecture has to answer a second set of questions: how retrieval is controlled, how evidence is preserved, how model access is constrained, and how the system remains auditable. 

These are not implementation details that can be postponed until later. Several of them affect the shape of the data model, orchestration layer, and deployment topology from the beginning.

1. Retrieval is two-tiered, and the first tier is not vectors

The reflex is to chunk everything, embed it, and search the vector space. For a corpus in the range of tens to a few hundred documents, that is often the wrong first move.

Instead, build a lightweight index table: one row per document holding a generated summary, an extracted table of contents, topical tags, provenance metadata, and a curator-assigned weight. A query hits that table first and narrows the corpus to a handful of candidate documents. Only then does full-text retrieval run against those documents' fragments.

This costs less, is dramatically easier to debug (you can read the index table), and gives the Knowledge Owner a surface to control retrieval without touching code. Vector search with a reranker then becomes an upgrade to the second tier, switched on where it demonstrably helps — typically where a single criterion is described at different levels of detail across several documents and you need ranking within an already-correct document set.

Commercially, the ordering matters as much as the technique: retrieval quality can be improved without first taking on another infrastructure dependency — and therefore without another line item to procure, deploy and keep running.

2. Citations are a data contract, not a prompt instruction

"Always cite your sources" in a system prompt produces citations that look right and sometimes point at nothing.

Make the model return structured output where every claim carries a chunk_id. Then run a deterministic validator that resolves each one against the store. Unresolvable claim, the response is repaired or rejected — programmatically, before the user ever sees it. The acceptance target for this is not 95%. It is 100%, because it is a lookup, not a judgement.

This single component is what separates a system that can be audited from one that merely produces footnotes. It also shortens every review cycle downstream: a reviewer inspects the evidence behind a claim directly, instead of reconstructing where the model might have found it — which is where reviewer hours actually go.

3. Hard grounding is enforced by tool absence, not by instruction

For the scoring path, the requirement was that the model must not draw on general knowledge or external sources, and that this behaviour must not be modifiable by the end user.

You cannot deliver that with a prompt. You deliver it by giving the scoring agent a tool catalog that contains only the rubric corpus. There is no web search tool to call, so there is no web search. 

4. Human-in-the-loop is a durable state problem

If a reviewer has to approve the criteria set before scoring begins, and that approval might arrive tomorrow, then your orchestration layer needs first-class interrupt and resume. In-memory agent state does not survive a deployment, let alone a weekend.

Use an orchestration framework with a persistent checkpointer — the entire graph state serialises to the database at each pause. The practical payoff goes beyond durability: a paused run becomes a shareable, inspectable object. A reviewer can hand it to a colleague, and an auditor can reconstruct exactly what the system knew at the moment a human said yes.

It also changes what approval costs to operate. Approval becomes a normal workflow state rather than a bottleneck, because nobody has to be online at the moment the model finishes: the run waits for the reviewer, not the reviewer for the run.

5. One gateway is the swap seam for models, and the meter for cost

Technology neutrality — the ability to change LLM provider without rebuilding application logic — is a common procurement requirement and a sound engineering instinct regardless.

Route every inference call through a single gateway (LiteLLM in our stack) exposing an OpenAI-compatible interface. Provider changes become configuration. The same component gives you per-key budgets, spend tracking, fallback chains, and semantic caching for free — which means one container satisfies both the neutrality requirement and the "we need to monitor LLM cost" requirement that usually arrives as a separate line item.

Wrap it in a thin internal adapter layer so no skill imports the gateway SDK directly. That is the difference between swapping a dependency and rewriting your agents.

For a buyer, one container answers two separate anxieties: lock-in and cost uncertainty. Model spend becomes measurable per workflow, and changing provider becomes a procurement decision rather than a reason to reopen the application architecture.

6. Skills are data, with progressive disclosure

Define each capability as a manifest — name, one-line description, required knowledge catalog, input and output schema — stored in a registry that an administrator can edit without a deployment.

At runtime, the orchestrator sees only names and descriptions (discovery), loads the full instruction set for the one skill it selects (activation), executes, then releases that context (execution). This keeps the context window small regardless of how many skills exist, and it is what makes a large capability library viable instead of a source of degradation.

Give each skill a stateless, schema-defined interface from day one, expose knowledge catalogs as separate MCP servers, and extracting a skill into its own service later becomes a deployment change rather than a rewrite.

7. Generated content never touches the verified corpus

The generative agent runs hot on purpose. Its output must land in a separate schema — a proposals namespace, plus a "negative knowledge base" of rejected variants with their scores, which turns out to be genuinely useful analytical material about where the systemic barriers are.

Nothing the model invents becomes retrievable ground truth. This is a deliberate isolation boundary, and it should be visible in the schema. 

Containers: the nineteen-container deployment architecture

Two things about this AI agent architecture diagram are worth calling out.

The colour encodes commercial scope, not architectural layer. Base scope, optional modules, external systems. Layer is legible from position; scope is not, and scope is what a client actually has to make decisions about. When your container diagram maps directly onto the line items in a proposal, conversations about trade-offs get much shorter. Which module can we defer? Point at the diagram.

Every container has at least one edge. That sounds trivial. It is the most common defect in architecture diagrams we review, including drafts of this one. A cache or an observability stack drawn floating and unconnected is a signal that nobody worked out how it is actually used. The fix is to write the dependency list first — source, target, purpose, scope — and derive the diagram from it. Forty edges in a table, then a picture. Not the other way around.

The left column is the request path. The middle column holds retrieval and inference concerns. The right column holds ingestion, platform, and the optional modules. Both chains converge on a single PostgreSQL instance carrying the index table, chunks, optional vectors, document weights, versions, and orchestration checkpoints.

That single-store choice deserves a note. For a corpus of this size, a dedicated vector database means a second backup story, a second HA story, a second monitoring surface, and a second thing to keep in sync — in exchange for performance headroom you will not use. pgvector alongside full-text search in the same Postgres gives you hybrid retrieval with one operational contract. The saving is not the database licence; it is the on-call rota, the failover drill and the restore test that never have to exist.

With that foundation in place, the architecture can be understood through the two flows that exercise most of its components: a grounded research query and a rubric evaluation.

Two core flows: grounded research query and rubric evaluation

A grounded research query. Request arrives at the API service with a validated token. The orchestrator runs discovery against the skill registry, activates the research skill, and calls the relevant catalog's MCP server. The retrieval service queries the index table to shortlist documents, then pulls fragments — full-text, plus vector search and reranking if that option is enabled. If the user has enabled the allow-list toggle, web retrieval adds external results, clearly marked as external and rendered separately. The skill produces structured output with citation spans. The citation validator resolves every chunk_id and repairs or flags anything that fails. The answer streams back over SSE with a source drawer and, where the retrieved context was thin or self-contradictory, a low-confidence flag. In parallel: an LLM trace, a token and cost record, and an audit entry that includes the weight-configuration version in force.

A rubric evaluation. The submitted artefact is classified by depth — short concept or full proposal — which determines the breadth of the rubric applied. The user confirms the classification, the active criteria, and their weights. This is a hard gate: no score is produced without explicit human approval, and the graph interrupts here. The research skill runs as a sub-call to expand context. The artefact is decomposed into features, actions, and impact areas, and that decomposition goes back to the user for a second confirmation. Each criterion is then marked active, unverifiable, or not applicable. Only active criteria are scored, each with a citation and written justification. A validator loop checks every score against the source corpus and the document weight hierarchy before anything is displayed. Unverifiable criteria are surfaced as an explicit gap list, and if the user declines to fill them, the report ships flagged as incomplete with the omissions named.

Note what the second flow implies: the score is a function of the corpus, the weights, and the rubric version — all three of which are mutable by a human. If you do not version and log all three per evaluation, you have no reproducibility, and an auditor asking "why did this score 68 in March" has no answer.

These flows show how agentic AI architecture preserves evidence and state during execution. The next question is whether those guarantees can be measured consistently enough to support acceptance, regression testing, and audit.

How you prove the architecture works: the evaluation framework

This is the part that determines whether a project like this gets accepted, and it is almost always underspecified in the statement of work. "The system must produce high-quality answers" is not a criterion; it is an invitation to unbounded iteration.

Build the evaluation harness as a product component, not a QA activity. But be careful about what you write into a contract, because the metrics that matter here fall into two classes with completely different epistemic status, and putting them in one table with one column of numbers is a mistake we have made ourselves.

Class 1: invariants

These are properties of the system, not of a corpus. They are testable on day one with synthetic data, they do not have a distribution, and there is no version of "mostly" that is acceptable. Commit these immediately.

Invariant	How it is verified	Target
Citation resolvability	Deterministic lookup of every chunk_id	100%
No external reach on the scoring path	Assertion on the agent's tool catalog	no such tool exists
Provenance stamping	Rubric, weight-config and corpus versions recorded per evaluation	100% of records
Structural reproducibility	Same inputs + same versions → identical structured record	exact match
Regression gate	promptfoo or deepeval in CI	no degradation per merge

Note the second row. "Zero ungrounded scores" is often written as one metric, but it is two things wearing one name. Cannot reach outside the corpus is an architectural assertion — you test the tool catalog, and it either contains a search tool or it does not. Makes no unsupported claim about the documents it did receive is a judgement call requiring an LLM judge and a sample. The first belongs above. The second belongs below.

Class 2: statistical quality

These are properties of a model-plus-corpus-plus-query-distribution. You cannot know them before you have measured them, and a number written into a contract before the first ingestion run is a guess wearing a suit.

Metric	Method	How to commit it
Faithfulness / groundedness	Ragas against the golden set	baseline → MVP → production ladder
Context precision / recall	Ragas	ladder, and see the caveat below
Unsupported claims within retrieved context	LLM judge, fixed model and prompt	ladder
Score stability	5 runs, fixed temperature and seed	relative to human variance
Agreement with human experts	Spearman ρ, dual-scored sample	relative to human agreement

Three things make these harder than they look.

Context precision can penalise correct behaviour. If your corpus deliberately contains superseded document versions so the system can flag contradictions — a feature, not a bug, in any auditable design — then retrieving both versions is right, and a precision metric that treats near-duplicates as noise will mark it wrong. Do not contract a number that fights one of your own requirements.

Faithfulness is itself scored by a model. Ragas faithfulness uses an LLM judge. Change the judge, its version, its prompt, or the granularity at which you decompose a paragraph into claims, and the number moves without the system changing at all. If you commit to a faithfulness figure, commit to the judge alongside it — model, version, prompt, decomposition rule — pinned like any other dependency. Otherwise you have contracted a moving target.

Anchor stability and agreement to human baseline, not to absolute numbers. This is the correction we would most want to pass on. In rubric-based assessment, two qualified experts scoring the same artefact typically correlate somewhere in the 0.6–0.8 range. If you demand ρ ≥ 0.7 between machine and expert A, and expert B only manages 0.65 with expert A, you have demanded that the system agree with one human better than another human does. That is not a high standard, it is an undefined one.

So: measure human–human agreement and human–human score variance on the same sample first, then set the machine target relative to it. "Machine–expert correlation within 0.05 of expert–expert correlation" and "machine σ no greater than inter-rater σ" are defensible with evidence. They also protect you from a client demanding more consistency than their own reviewers deliver.

Watch your sample size. With n = 30, an observed ρ of 0.7 carries a 95% confidence interval of roughly [0.45, 0.85]. A single measurement can pass or fail acceptance on sampling noise alone. Either raise n to 50–80, or contract the lower confidence bound rather than the point estimate, or state explicitly that the figure is indicative. "ρ ≥ 0.7 on 30 artefacts" as a pass/fail gate is fragile in both directions.

Which quality targets to commit to, and when

The right answer depends on the commercial shape of the engagement, and the difference is larger than most teams account for.

Direct engagement — the common case, and the good one. Sell a paid discovery phase: two to three weeks of pilot ingestion on twenty to thirty representative documents, golden set built jointly with the client's subject-matter experts, baseline measured and signed off by both sides. Then price and commit the build against a known baseline. Everyone is better off, and it is a well-understood shape — nobody is surprised by an inception phase. The reason it is better for both sides is timing: the uncertainty gets priced while it is still cheap to negotiate, rather than at acceptance, when it has already become a delivery dispute.

The trap to avoid here is committing nothing up front. Without any anchor, the quality conversation gets deferred to the end of the project, which is precisely when your leverage is lowest and the client's frustration is highest. So even with a pilot ahead of you, commit the invariants, and commit the measurement protocol: what gets measured, by whom, on what sample, with which judge, and — critically — what happens if the baseline comes in low. Name the responses in advance: corpus remediation as separately scoped work, a narrower supported query scope, or an adjusted target. Three named options at kickoff prevent one unnamed argument at delivery.

Competitive tender or fixed-price bid. Here you often cannot wait. Procurement wants numbers before anyone has seen the corpus, and "we will determine thresholds after a pilot" reads as this vendor is guaranteeing nothing — which loses to whoever confidently wrote 0.95.

The move is not to defer the number. It is to contract the mechanism: a pilot gate in the first two weeks on N representative documents, baseline measured jointly and signed, production target defined as baseline plus a stated delta with an absolute floor below which the engagement is re-scoped. That is a real commitment, it is auditable, and it survives procurement review — while a bare 0.90 with no corpus behind it is a promise you may not be able to keep.

Internal build, no contract. Different failure mode entirely: nobody enforces the numbers and they quietly rot. The only mechanism that survives organisational entropy is the CI gate. Wire the regression check into the merge pipeline on day one and let the rest be OKRs.

Whatever the engagement model, these targets need a shared evaluation dataset behind them. Without that dataset, neither the baseline nor the production target can be measured consistently.

The golden set is the real deliverable: 100–150 expert-built question-source pairs

100 to 150 question-and-expected-source pairs, built with the client's subject-matter experts. This is the single highest-leverage risk reduction available on a project of this shape, and it has to appear in the contract as a shared responsibility with named people and allocated hours — not as an assumption.

Without it, every number above is unmeasurable, acceptance becomes a matter of opinion, and opinion has no schedule.

The golden set reduces uncertainty around quality, but it does not remove the other delivery risks. Several architectural and process decisions can still change cost substantially or make acceptance difficult later.

What actually drives cost and risk

Ranked by what we have seen bite hardest:

1. Undefined quality acceptance criteria — or worse, prematurely defined ones. Highest risk on any project of this shape, and it cuts both ways. No criteria means unbounded iteration; a hard statistical figure signed before anyone has seen the corpus means a delivery risk you took on for free. Commit the invariants in week one, commit the measurement protocol in week one, and put the statistical figures behind a pilot gate.
2. Evaluation judge drift. If your quality figure is produced by an LLM judge, that judge is a contractual dependency. Pin the model, version, prompt and claim-decomposition rule, and treat a judge change as a change to the acceptance baseline requiring a re-measure — not as a silent upgrade.
3. A rubric that is "derived automatically from the documents." This sounds elegant and produces high score variance. Extract the operational criteria — the actual verification questions — into a versioned, expert-approved artefact. Do not leave the rubric as an emergent property of retrieval.
4. Source-of-truth migration mid-project. Repositories get consolidated during delivery more often than anyone plans for. Put the document store behind a swappable connector interface and price the migration as a separate option.
5. Input document quality. Scans, non-English diacritics, and multi-page tables set a ceiling on faithfulness that no amount of prompt work will raise. Run pilot ingestion on twenty representative files before you commit to a number.
6. PII exposure in the corpus. Interview transcripts and workshop notes usually contain it. A deidentification step ahead of indexing is not optional, and no document should reach the store without passing through it.
7. Rubric and weight changes altering delivered results. Version the weight configuration and stamp it into every audit record, or reproducibility is gone.
8. Open-ended prompt engineering discovered during delivery. Workshops that define agent behaviour mid-project are legitimate but need to be time-boxed: N sessions, M iterations, then change request.

Closing

Building a convincing agentic AI demo is relatively easy. The harder work begins when the system has to operate reliably over real documents, support human review, and explain how it reached a result months after that result was produced.

That is where agentic AI architecture matters. Citations need to resolve to real evidence. Human approvals need to survive pauses and deployments. Rubrics, document weights, and corpus versions need to be recorded so results can be reproduced. Quality also needs to be measured against an agreed evaluation set rather than judged informally at the end of the project.

In practice, these requirements account for much more of the engineering effort than the initial retrieval-and-generation loop. They are also what determine whether an agentic AI system can move from a successful prototype into production.

For companies that do not have the in-house expertise to design and build this kind of system, AI outsourcing can be a practical way to move from prototype to production without assembling a full specialist team internally.

Working with an experienced AI software development company can also help reduce architectural risk early, especially when the project involves retrieval, evaluation, governance, and long-term production support.