AI Agent Architect

Wrote docs/architecture/agent-architect/00-overview/agent-architect-overview.md. Complete agent runtime architecture specifying authority limits, step and tool budgets, human oversight gates, and anti-pattern verification.

---
skill: agent-architect
---

# AI Agent Architecture: RefundOps Agent [AA-REFUND-001]

## Summary

This specification establishes the bounded autonomous runtime for RefundOps Agent, handling merchant disputes and consumer refund claims. The agent operates under hard programmatic authority limits: maximum $150 per automated transaction, daily user refund limit of $300, and mandatory human escalation for fraud risk scores >= 0.65 or claims above $150. It explicitly rules out autonomous policy overrides, self-adjudication, and direct ledger credit creation outside the guarded `issue_refund` tool interface.

## Detailed Description

RefundOps processes refund requests received via inbound support cases. The agent analyzes transaction ledger data, queries the fraud score oracle, evaluates eligibility against refund policy rules, and either executes a bounded refund or delegates the case to human risk analysts.

Incoming Case
│
▼
[ Runtime Envelope: 30 Tools / 120s ]
│
├─► ledger_read ──► Verify Transaction
├─► fraud_score_lookup ──► Check Risk Metric
│
├── Fraud Score >= 0.65 OR Amount > $150 ──► escalate_to_human
└── Fraud Score < 0.65 AND Amount <= $150 ──► issue_refund

### Alternatives rejected

| Option | Why it was not taken | Under what evidence it would win |
|---|---|---|
| Direct $300 Auto-Approval Ceiling | Fraud chargebacks increased by 18% in the preceding month; raising ceiling doubles exposed financial risk. | Reversal requires 60 consecutive days of fraud chargeback rates dropping below 1.0%. |
| Prompt-Only Guardrails | LLM system instructions cannot guarantee financial ceilings; prompt injection could bypass threshold. | Rejected permanently; financial thresholds must be deterministically enforced by tool wrappers. |
| Fully Manual Review | High ticket volume creates unacceptable resolution backlogs for trivial low-value claims. | Reversal if customer dispute volume drops below 50 tickets/day. |


## Contracts and Invariants

    Financial Authority Ceiling [INV-REFUND-01]
      The agent runtime wrapper strictly enforces that `issue_refund` cannot be invoked with `amount` > 150.00 USD, regardless of LLM reasoning or prompt injection. Violations immediately abort execution with error code ERR_AUTH_CEILING.

    Daily Aggregate Customer Limit [INV-REFUND-02]
      Total cumulative refunds issued to a single `user_id` within a rolling 24-hour window must not exceed 300.00 USD. If cumulative sum + requested amount > 300.00, execution delegates to `escalate_to_human`.

    Mandatory Escalation on Risk Score [INV-REFUND-03]
      Any case returning `fraud_score` >= 0.65 from `fraud_score_lookup` must trigger `escalate_to_human`. The agent is denied authority to call `issue_refund` when risk threshold is breached.

    Execution Resource Bounding [INV-REFUND-04]
      Runtime hard bounds: max 30 model tool iterations, 120 seconds wall-clock timeout. Upon exceeding either limit, the run aborts and falls back to a parked status in the human operator queue.

## Ownership and Handoffs

| Concern | Owner | Handoff payload | Blocked until |
|---|---|---|---|
| Financial Authority & Limits | Risk Operations Guild (Elena Rostova) | Authority ceiling rules & escalation threshold definitions | Approved by Elena Rostova |
| Tool Wrappers & Ledger Integration | Core Payments Engineering | OpenAPI schema for `ledger_read` and `issue_refund` | Wrapper integration test passes |
| Human Review Console | Customer Support Operations | UI case queue format for `escalate_to_human` | Queue webhook receiver deployed |


## Traceability

| Claim | Classification | Source | Freshness |
|---|---|---|---|
| Auto-approval max $150 | provided | Intake specification | Current |
| Daily customer limit $300 | provided | Intake specification | Current |
| 18% fraud chargeback increase | provided | Risk operations report | Stated in request |
| Max 30 tool calls / 120s budget | provided | Intake specification | Current |
| Deterministic wrapper enforcement | decided | Architectural decision AA-REFUND-001 | 2026-09-15 |


## Verification

No validator was supplied, so no command was run.

Reviewer self-check against fitness anti-patterns:
- **Unbounded Autonomy Check**: PASS. Hard limits enforced: 30 tool calls, 120s timeout, $150 per transaction, $300 daily per user.
- **Self-Graded Evaluation Check**: PASS. Agent does not grade its own decisions; risk scores originate from independent `fraud_score_lookup` oracle.
- **Prompt-Only Control Check**: PASS. Ceilings enforced at tool boundary in backend wrapper code, not via LLM system prompt instructions.

## Open Decisions

None. All constraints and boundaries derived directly from intake request.

Next steps

1. Review deterministic tool wrapper enforcement logic with Core Payments Engineering.
2. Verify human review queue ingestion schema with Customer Support Operations lead.
3. Establish weekly audit reconciliation between agent-issued refunds and ledger records.