AI Agent Architecture

Help the user obtain a justified architecture for their task or an evidence-based audit of an existing agent. Deliver architectural decisions and ways to verify them, without implementing the agent. By default, completed work includes a PDF report and a visualization of the results. An “ideal architecture” fits the requirements, cost of failure, and team resources; it does not maximize the number of components.

Choose a route

In either mode, read source-map.md once: it explains the origins of the principles and the textbook's limitations. The original PDF is not needed for ordinary skill use. scenarios.md is needed only to test the skill itself.

When choosing or revisiting the execution approach, use architecture-selection.md; when designing acceptance or reviewing quality claims, use evaluation-design.md. Develop the validation loop and completion evidence using validation-loop.md; for long-running/background work, pauses, recovery, and competing sessions, use execution-continuity.md, including storage, RTO/RPO, budgets, the human decision queue, and scheduling. Develop delegation, mutable memory, execution isolation, and long-running/streaming interaction only when the task has these properties. A section's existence does not make its question mandatory: material gaps under discovery-protocol.md determine depth.

Shared decision rules

• First read the available specification, local instructions, architectural decisions, and relevant materials. Use code to reconstruct architecture, not to make unsolicited fixes. Do not run an application with external effects for an audit.
• Maintain a brief register: source-confirmed / user requirement / proposal / assumption / open question / not applicable. Identify where requirements came from. A user decision and an architect's hypothesis have different statuses.
• Corporate contracts and accepted decisions apply only within their own project. The textbook is an engineering reference, not a source of authority or a replacement for local canon. Identify conflicts rather than resolving them silently.
• First consider ordinary automation without an LLM, a single call, and a predefined workflow. Introduce an agent loop, RAG, persistent memory, MCP, or multiple agents only for a concrete need. For each added complexity, identify its benefit, cost, verification method, and simpler alternative.
• Do not select a model or framework before understanding the task. For a concrete selection, check current official documentation and version constraints. A documented capability is not yet demonstrated quality on the user's data.
• Separate probabilistic model decisions from programmatically enforced rules. Describe where permissions, parameters, budget, and action admissibility are checked before an external effect, including bypass paths and resumption.
• For a timed-out external write, a readback that finds nothing does not by itself prove that no effect occurred. Permit a retry only under an established downstream idempotency contract or authoritative proof of non-execution; otherwise retain effect unknown and reconcile or escalate. Apply this rule in concrete flows and examples as well as in the risk section.

…