THE PROBLEM
Why this pattern exists
Teams often expose CRUD endpoints to agents and call the product agent-ready, without delegated identity, semantic contracts or transactional controls.
DESIGN GUIDANCE
Principles to preserve
- Agents request scoped business outcomes, not arbitrary data mutations.
- Business capabilities own validation, authorization and commit.
- Use stable intent/action schemas and versioned domain APIs.
- Emit domain events only after durable state transitions.
- Every action needs identity, traceability and a recovery path.
THE REAL DESIGN WORK
Trade-offs, not just boxes
- 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
Before you implement
- 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?