Appendix C — Architecture decision guide and example ADRs

Agentic systems benefit from explicit Architecture Decision Records (ADRs) because many important choices are not visible in source code: why a task is agentic, why a model may call a tool, why a tenant has dedicated storage, or why human approval is required.

C.1 Minimal ADR template

Title
Status: Proposed / Accepted / Superseded / Deprecated
Context: What problem, constraints and assumptions create the decision?
Decision: What will be done?
Alternatives considered: What credible alternatives were rejected and why?
Consequences: Positive, negative and operational consequences.
Security and privacy: Trust boundaries, identities, data and residual risk.
Evaluation: What evidence will show that the decision works?
Revisit triggers: What changes would justify reopening the decision?

C.2 ADR — use an agent or deterministic workflow?

Context. Support engineers investigate integration failures. The relevant diagnostic step varies with message content and system history.

Decision. Use a bounded investigation agent for evidence gathering and hypothesis generation; use a deterministic workflow for ticket state, permission checks, escalation and remediation approval.

Alternative: fully deterministic runbook. Rejected because incidents have too many semantic variants and engineers regularly deviate from fixed diagnostic paths.

Alternative: autonomous remediation agent. Rejected initially because production change authority is high consequence and evidence is not yet sufficient.

Consequences. Higher flexibility during investigation, while remediation remains predictable. Additional model/evaluation/observability cost.

Evaluation. Time to defensible hypothesis, evidence coverage, unnecessary tool calls, escalation accuracy, incident outcomes.

C.3 ADR — RAG versus fine-tuning for enterprise policy knowledge

Context. Policies change monthly and require source attribution.

Decision. Use permission-aware retrieval to supply policy knowledge. Fine-tuning may later be considered for stable output conventions or specialised classification, not for current policy facts.

Why. Retrieval supports freshness, revocation and attribution.

Trade-off. Retrieval quality and indexing lifecycle become operational dependencies.

Revisit. If task-specific behaviour remains inconsistent despite strong prompting/evaluation, consider adaptation methods while retaining RAG for current facts.

C.4 ADR — shared or dedicated vector stores?

Context. A SaaS platform serves multiple enterprise tenants with confidential documents.

Decision. Use pooled compute but dedicated vector indexes and encryption keys for regulated tenants; lower-risk internal tenants may use shared infrastructure with mandatory tenant filtering.

Alternatives. Dedicated full environment for every tenant rejected initially for cost; global shared index rejected for high-sensitivity customers.

Evidence. Cross-tenant security tests, operational recovery tests, cost per tenant.

C.5 ADR — MCP gateway before enterprise APIs

Context. Agents need access to numerous internal APIs, including legacy-backed services.

Decision. Expose only approved task-oriented capabilities through an MCP governance gateway. Existing APIs remain behind domain adapters; raw OpenAPI transformation is permitted only for APIs assessed as already agent-safe.

Reason. MCP standardises capability access but does not make broad enterprise APIs least-privileged.

Revisit. When API estate adopts standard side-effect/security metadata.

C.6 ADR — A2A for cross-domain specialists

Context. Separate business domains operate specialist agents with distinct ownership and deployments.

Decision. Use A2A task delegation for cross-domain work; local specialists within one workflow may continue using internal framework calls.

Reason. A2A adds value at organisational/runtime boundaries where independent identity, capability discovery and versioning matter.

Trade-off. Protocol/federation complexity and context-fragmentation risk.

C.7 ADR — human approval binding

Context. Agent prepares a production configuration change.

Decision. Human approves canonical structured payload; approval stores hash/digest and expires after 20 minutes. Commit service rejects any changed payload.

Rejected alternative. Approve a natural-language summary then regenerate the command afterwards.

Reason. Prevents mismatch between reviewed intent and executed action.

C.8 ADR — historical replay support

Context. Risk recommendations may be challenged months later.

Decision. Store evidence references, source/effective dates, feature/model/policy versions, material tool results and workflow events. Do not store raw chain-of-thought.

Consequence. Additional evidence/telemetry storage and lifecycle controls; improved assurance and regression testing.

C.9 ADR — legacy ERP integration

Context. ERP API uses a privileged technical account and has complex, unstable semantics.

Decision. Place an anti-corruption/capability adapter in front. Agent receives narrow read/prepare operations. Commit requires policy and human approval. Downstream credential stays in adapter.

Alternative. Generic database tool rejected because it bypasses ERP business rules.

C.10 Architecture decision checklist

Before approving an agentic design, answer:

• What business problem requires probabilistic reasoning?
• Which portions can remain deterministic?
• What is the authoritative system of record?
• What knowledge is required and who owns it?
• How is tenant/identity applied before retrieval?
• Which tools are needed and what side-effect class does each have?
• Where is workflow state stored?
• What is the loop termination/progress rule?
• What happens after a timeout or partial commit?
• What human judgement remains material?
• What evidence is stored?
• How will the feature be evaluated before and after production?
• How can it be contained or rolled back?
• What is the cost per resolved outcome?
• What architectural condition would cause this decision to be revisited?