Architecture documentation workbook guide

Complete reference for the agent architecture documentation workbook. Each sheet's purpose, column descriptions, and dropdown values are documented below.

Quick start: Download the blank workbook or sample filled workbook. Fill sheets in order: Overview → Agent Topology → Components → Tool Registry → Data Flows → Trust Boundaries → Memory Architecture → Guardrails → Autonomy → Observability.

Agentic-specific sheets

The workbook adds four agentic-specific sheets — Agent Topology, Tool Registry, Memory Architecture, and Guardrails — alongside the standard cloud architecture sheets (Overview, Components, Data Flows, Trust Boundaries, Autonomy, Observability). This structure models the cognitive control loop, multi-agent topologies, tool registries, and tiered memory systems rather than treating the agent as a monolithic black box.

Agent Topology

Map the cognitive control loop: nodes, edges, conditions, and state payloads. A directed graph structure that visual tools can ingest directly.

Column	Description	Values	Example
`node_id`	Unique node identifier	required	`NODE_CLASSIFIER`
`node_type`	Node category (dropdown)	required	`LLM_Agent`
`parent_cluster`	Logical grouping or layer	free text	`Control Plane`
`target_node_id`	Edge destination node	required	`NODE_EVALUATOR`
`edge_type`	Edge type (dropdown)	required	`conditional`
`edge_condition`	Trigger logic for the edge	free text	`confidence < 0.85`
`state_payload`	Key state variables passed across the edge	free text	`claim_id, uncertainty_reason`
`state_read_keys`	State channels read by the node	comma-separated	`validated_claim, context_chunks`
`state_write_keys`	State channels written or appended by the node	comma-separated	`approval_decision`
`input_token_budget`	Maximum input tokens allocated to the node	integer	`2000`
`output_token_budget`	Maximum output tokens allocated to the node	integer	`1000`
`mermaid_flow_code`	Excel-generated Mermaid edge; copy the populated column into a flowchart	formula	`NODE_A -->\|conditional\| NODE_B`

Node types: LLM_Agent, Deterministic_Function, Router, HITL_Gate, Tool_Node, End

Edge types: sync, async, conditional, fallback, human_interrupt

Sample topology (from 7-node claims triage):

Ingestion Plane Control Plane Knowledge Plane Governance Plane NODE_INGEST ──sync──▶ NODE_CLASSIFIER ──conditional──▶ NODE_RAG_LOOKUP ──sync──▶ NODE_EVALUATOR (DF) (LLM) │ (Tool) (LLM) │ │ │ │ │ conditional ├──conditional──▶ NODE_PAYMENT_EXEC │ ▼ (confidence<0.85) │ │ NODE_HITL_GATE ──human_interrupt──▶ NODE_PAYMENT_EXEC └─────────────────────────────────────────────────────────┘ (amt>500)

Tool Registry

Document every tool or action the agent can invoke. Separate passive data ingestion from active external side effects.

Column	Description	Values	Example
`tool_id`	Unique tool identifier	required	`TOOL-003`
`tool_name`	Schema function name	required	`submit_approval`
`description_prompt`	Semantic description the LLM uses for selection	required	`Submit claim approval to payment gateway`
`execution_type`	How the tool executes (dropdown)	required	`API`
`side_effect_level`	Impact on external state (dropdown)	required	`Irreversible_Action`
`is_idempotent`	Whether retrying produces the same safe result	Yes / No	`No`
`schema_format`	Tool-interface contract format	dropdown	`JSON_Schema`
`auth_sandbox`	Execution boundary	free text	`Payment API Gateway`
`timeout_retry_policy`	Timeout and fallback behavior	free text	`10s, no retry — requires idempotency key`
`mermaid_sequence_code`	Excel-generated Mermaid participant declaration	formula	`participant TOOL-003 as submit_approval`

Execution types: API, SQL_Query, Sandboxed_Python, CLI_Command, Function_Call

Side effects: Read_Only, Idempotent_Write, Irreversible_Action

Memory Architecture

Define how context windows and persistent storage interact across conversational turns.

Column	Description	Values	Example
`tier`	Memory tier (dropdown)	required	`Working_Context`
`storage_engine`	Storage backend	free text	`In-Memory State`
`retrieval_strategy`	How data is fetched (dropdown)	free text	`Full_Context`
`context_eviction_strategy`	How context is reduced during long execution loops	dropdown	`Summarize_Window`
`token_budget_limit`	Allocated context size	free text	`4,000 tokens`
`notes`	Additional context	free text	`Current turn context window`

Memory tiers: Working_Context, Short_Term_Session, Episodic_History, Semantic_Knowledge

Retrieval strategies: Dense_Vector, Hybrid_BM25_Dense, GraphRAG, Sliding_Window, Full_Context

Eviction policies: TTL, LRU, Summarize_on_Overflow, Selective_Pruning, None

Guardrails

Map defensive filters applied across the agent lifecycle.

Column	Description	Values	Example
`interception_point`	Where the guardrail fires (dropdown)	required	`Pre_Model_Input`
`guardrail_type`	Type of guard (dropdown)	required	`PII_Redaction`
`action_on_breach`	Response on violation (dropdown)	required	`Sanitize`
`mitre_atlas_technique`	Mapped adversarial-ML technique	dropdown	`AML.T0003_Execution`
`latency_impact`	Expected overhead	free text	`~20ms`
`notes`	Additional context	free text	`Redact SSN, DOB, bank account before LLM call`

Interception points: Pre_Model_Input, In_Reasoning_Execution, Post_Model_Output, Pre_Tool_Execution

Guardrail types: Prompt_Injection_Detection, PII_Redaction, Regex_Schema_Validator, Hallucination_Eval, Tool_Output_Validator

Breach actions: Block_and_Alert, Reprompt_Self_Correction, Fallback_to_Human, Sanitize, Log_Only

Standard architecture sheets

Overview

System metadata: name, version, owner, purpose, autonomy level, data sensitivity.

10 key-value pairs with guidance notes in the third column. Autonomy level: none / assistive / supervised / autonomous.

Components

Inventory of deployed components with exact versions and deployment mode. Dropdowns for category, deployment, state owner.

Data Flows

How data moves between components and external systems. Captures synchronous versus asynchronous transport, frequency, protocol, and an Excel-generated mermaid_flow_code edge.

Trust Boundaries

Security and authorization boundaries, including authentication, authorization, encryption, and an OWASP LLM threat mapping such as prompt injection, sensitive-information disclosure, or excessive agency.

Autonomy

What the system can do without human approval, safety controls, rollback methods.

Observability

Telemetry: traces, logs, metrics, evals. Dropdown for coverage level.

Need help? Send the filled workbook to madhavraop@dhristhi.com with context about your system.