---
title: "AI agent architecture: patterns and governance"
description: "Design AI agents with explicit tool permissions, human approval, evaluation gates, and cost limits. Use eight architecture patterns, a GOVERNANCE.md template, and implementation case studies."
canonical: "https://architecture.reopt.ai/"
language: "en"
alternate-markdown: "https://architecture.reopt.ai/ko.md"
site-index: "https://architecture.reopt.ai/llms.txt"
source: "reopt architecture"
---

# AI agent architecture: patterns and governance

> Design AI agents with explicit tool permissions, human approval, evaluation gates, and cost limits. Use eight architecture patterns, a GOVERNANCE.md template, and implementation case studies.

An AI agent architecture defines which decisions an agent can make, which tools it can call, what context it can access, and how execution stops or recovers. reopt architecture is a practical reference for teams turning a working agent into an accountable production system.

Define the boundary. Implement the control. Test the failure.

Written and maintained by [Eric Han](https://architecture.reopt.ai/about.md) · Co-founder / CTO, Reopt AI

## Start with the failure you need to prevent

Choose one workflow and its most costly failure. Follow a pattern, produce the artifact below, and test the boundary before expanding the agent’s authority.

### An agent can change data without approval

Separate proposing an action from executing it. Bind approval to the exact action and arguments, then verify authorization again at execution time.

Deliverable: an approval record and a test that rejects changed or expired requests.

[Design human approval](https://architecture.reopt.ai/patterns/human-approval.md)

### Retries and tool calls run beyond budget

Give each run a budget and a stop condition. Include nested model calls and retries in the same accounting boundary.

Deliverable: a run budget and a test proving execution stops when it is exhausted.

[Bound agent cost](https://architecture.reopt.ai/patterns/cost-control.md)

### Nobody can explain a failed agent run

Connect the user request, agent version, tool calls, approval, and outcome with one trace identifier. Decide which data must be redacted.

Deliverable: a trace that reconstructs a failed action without exposing secrets.

[Make decisions traceable](https://architecture.reopt.ai/patterns/decision-traceability.md)

## Worked example: a support agent that drafts refunds

Illustrative design, not a production benchmark. The agent may read an authorized order and propose a refund. A separate executor owns the payment operation; a support lead owns the outcome.

| Boundary | Implementation decision | Failure to test |
| --- | --- | --- |
| Authority | Expose read_order and propose_refund to the agent. Keep execute_refund behind server-side authorization. | A prompt or tool argument attempts to invoke the payment operation directly. |
| Approval | Store the order, amount, currency, requester, approver, and expiry with the proposal. Recheck them before execution. | The amount changes after approval, approval expires, or the order belongs to another tenant. |
| Recovery | Use an idempotency key for the approved operation. Reconcile an uncertain payment result before retrying. | The provider accepts the refund but the response times out. |
| Evaluation | Run denied, expired, cross-tenant, and duplicate-request cases before granting write access. Keep the resulting trace. | A plausible model response passes review while the underlying action violates a rule. |

Write these decisions in GOVERNANCE.md, then enforce them in tool handlers and tests. A policy document or an instruction in a prompt cannot enforce a payment boundary by itself.

[Write the governance contract](https://architecture.reopt.ai/governance.md)

[Review the implementation](https://architecture.reopt.ai/checklist.md)

## The Five-Phase Methodology

1. **Assess** — Make the current state objective

   Scan the product's requirements and structural risks across 17 engineering and business attributes. The first phase is the team seeing the same picture and agreeing on priorities.

   → [Product Assessment](https://architecture.reopt.ai/assessment.md)

2. **Define** — Document the structural commitments

   Lock the assessment results into GOVERNANCE.md. Declaring the four — ownership, judgment contracts, collaboration rules, improvement criteria — gives the loop and the execution a direction.

   → [GOVERNANCE.md guide](https://architecture.reopt.ai/governance.md)

3. **Loop** — Sharpen the structure through the four OCLS phases

   - **OWN** — Name the owner of the outcome — governance changes with whether the owner is human or AI.
   - **CONTRACT** — Declare judgment conditions and boundaries — the more an AI owns it, the stricter the contract.
   - **LAYER** — Layer the product structure and scale.
   - **SHARPEN** — Refine the structure from operational outcomes.

   → [Checklist](https://architecture.reopt.ai/checklist.md)

4. **Execute** — Make design decisions with patterns

   Pick the right pattern for the situation and make the design decision. Responsibility Partitioning, Module Contract, Context Routing — when the team answers the judgment questions of the eight patterns, GOVERNANCE.md's commitments turn into real design.

   → [Pattern catalog](https://architecture.reopt.ai/patterns.md)

5. **Evaluate** — Measure outcomes and iterate

   Evaluate execution outcomes through the agentic-debt lens. Update GOVERNANCE.md, return to the assessment (phase 1). Each pass sharpens the structure.

   → [Re-assess](https://architecture.reopt.ai/assessment.md)

## Implementation notes and field experience

Inspect the code examples, design decisions, and limits behind the methodology. These are author-reported experiences; their outcomes do not establish results for other systems.

### [Implementing Reopt Agentic Governance: from assessment to system](https://architecture.reopt.ai/articles/reopt-agentic-patterns-in-production.md)

2026-04-15 · Eric Han

How a production SaaS running eight AI agents used reopt architecture's principles to diagnose its governance gaps and close them — universal audit logging, persistent approval records, MCP tracing and rate limiting, agent constraints, and an admin dashboard.

### [Projects as design experiments: learning architecture with AI](https://architecture.reopt.ai/articles/cross-project-design-review.md)

2026-10-26 · Eric Han

Across 25 pilot projects, comparing projects with different development principles proved especially useful. This guide turns that experience into cross-project design review: make policies explicit, derive improvement hypotheses from reference projects, and verify them in the receiving project.

### [Running the reopt architecture five-phase loop in Claude Code](https://architecture.reopt.ai/articles/claude-code-with-reopt-architecture.md)

2026-04-17 · Eric Han

A practical guide that maps the Assess→Define→Loop→Execute→Evaluate methodology onto Claude Code's CLAUDE.md auto-load, slash commands, sub-agents, and skills — applied to a real repository.

[Browse all articles](https://architecture.reopt.ai/articles.md)

## Use the parts your system needs

A deterministic workflow may only need a module contract, an owner, and failure tests. Add agent delegation when a task requires open-ended decisions; add approval where actions cross a meaningful authority boundary. The reference is independent of an agent framework and is not a compliance certification.

## Related

- [AI agent architecture patterns](https://architecture.reopt.ai/patterns.md)
- [Architecture](https://architecture.reopt.ai/architecture.md)
- [GOVERNANCE.md](https://architecture.reopt.ai/governance.md)
- [Product Assessment](https://architecture.reopt.ai/assessment.md)
- [Checklist](https://architecture.reopt.ai/checklist.md)
- [Articles](https://architecture.reopt.ai/articles.md)
- [Skills](https://architecture.reopt.ai/skills.md)
- [Glossary](https://architecture.reopt.ai/glossary.md)

---

_Markdown representation of https://architecture.reopt.ai/. Full index: https://architecture.reopt.ai/llms.txt HTML original: https://architecture.reopt.ai/ · 한국어: https://architecture.reopt.ai/ko.md_