# Agent-ready SaaS: capability-centred reference architecture

**NR-001** · Reference model · v1.0.0 · Reference / illustrative

Separate AI entry points from the business capabilities that actually own policies, transactions and state.

![Agent-ready SaaS: capability-centred reference architecture](diagram.svg)

## Architecture problem
Teams often expose CRUD endpoints to agents and call the product agent-ready, without delegated identity, semantic contracts or transactional controls.

## Apply when
- Designing agent-accessible B2B product capabilities
- Introducing natural-language or autonomous workflows beside an existing UI
- Defining responsibilities between agent platforms and product engineering

## Not intended for
- Using the model as a complete deployment topology
- Assuming every capability needs an LLM
- Exposing raw database CRUD operations to agents

## Design rules
1. Agents request scoped business outcomes, not arbitrary data mutations.
2. Business capabilities own validation, authorization and commit.
3. Use stable intent/action schemas and versioned domain APIs.
4. Emit domain events only after durable state transitions.
5. Every action needs identity, traceability and a recovery path.

## Trade-offs
- Semantic capability APIs cost more to design than raw CRUD APIs but provide safer evolution.
- An agent gateway centralizes controls but must not become a single all-knowing business service.
- Keeping humans in selected approval loops trades latency for risk reduction.

## Review questions
- Who owns each business capability and its invariants?
- Where is delegated user or service authority checked?
- What is the idempotency and compensation model?
- Can the product execute correctly if the AI service is unavailable?

## Download / adapt
- `diagram.drawio` — primary editable diagrams.net file
- `diagram.dot` — independent Graphviz concept source
- `diagram.mmd` — editable Mermaid interpretation
- `diagram.svg` — scalable figure
- `diagram.png` — high-resolution figure
- `metadata.yaml` — structured pattern description

**Reuse:** CC BY 4.0; credit nishtnr, link the license, and indicate changes. Conceptual reference only.