What you'll learn: how to pick an integration style for each system the assistant must read from or write to, how an adapter keeps the customer's model out of your design, and how a write runs exactly once after a person approves it.
At a glance
Figure 1. How the Order and Policy Assistant reaches the customer's systems
How to read this: statuses are read live; policy text arrives as a copy; the only write waits for approval and passes through the adapter.
- Pick a style per system: freshness and failure differ.
- An adapter translates; it holds no business rules.
- A write needs approval and an idempotency key (a unique id that makes a repeat change nothing).
- Your artifact: an integration map.
Scenario
Composite scenario, not a real company. Lumen Industrial Supply, a fictional distributor, has an order management system (OMS) with a REST API behind a gateway owned by the platform team. The policy library (62 documents) is owned by Commercial. The assistant is read-only in the MVP; phase 2 adds an address change. The platform team asks: "What will you call, and what happens when we are down?" Numbers are illustrative.
What you will be able to do
- Choose among five integration styles for a system and defend the choice.
- Design an adapter so tools speak the assistant's model.
- Describe a write that runs once after approval, including a retry.
Prerequisites
- Patterns: act safely and at scale, for the approval pattern.
- AI Architect agents, tools and MCP.
Core ideas
Five ways to reach a system you do not own
Figure 2. Integration styles for the assistant
| Style | Fits when | Freshness | If it fails | Customer changes | Risk |
|---|---|---|---|---|---|
| Live API read | Current facts: order status | Live | Say so, never guess | A read role, if none exists | OMS load |
| Replica or export | Large or slow queries | Age of copy | Show the copy time | A copy job | Old data looks current |
| Event subscription | React to a change | Seconds, if healthy | Reconcile by reading | A publisher, a topic | Duplicates, gaps |
| File drop | Documents with no API | Age of last drop | Keep last good copy | A folder, a schedule | Superseded versions |
| Approved write | Phase 2 actions | Live | Outcome unknown: check | A write role, a key | Wrong or repeated change |
How to read this: lower rows ask more of the customer and cost more when they fail.
Default: live API read, file drop for documents, events only when a use case needs them.
Keep the customer's model out of the assistant
Place an adapter between the assistant and the OMS. The Azure Architecture Center calls this the anti-corruption layer pattern: a facade or adapter between subsystems that do not share semantics, translating requests so one system stays unchanged without compromising the other's design. Tools speak the assistant's model; the adapter maps it.
{
"tool": "get_order_status",
"input": { "order_id": "string" },
"output": { "order_id": "string", "stage": "confirmed", "on_hold": true, "hold_reason": "credit", "as_of": "ISO time" }
}| OMS says | Assistant model |
|---|---|
Status picked, held flag set |
stage: picked, on_hold: true |
| Fields the tool does not need | Dropped |
| Error or empty body | A named error, never an empty order |
The page lists costs: added latency and an extra service to manage. It also advises focusing the layer on translation and avoiding business rules or orchestration in it. So P-ORD-04 (changes after picked need warehouse approval) lives in the policy logic.
Spot the flaw. A tool update_order is exposed straight to the model. On a timeout the orchestrator retries it, using a status cached ten minutes earlier. What breaks?
Answer
The model writes without approval, the retry has no key, and the cache may say confirmed for a picked order. Fix: read-only model tools, propose-approve-execute with a key, as_of on every status.
A write that runs once
Approval is a gate in code the model cannot press: see the approval gate. This page adds what the OMS must support. The key is created with the proposal and bound to the exact arguments the approver sees.
Figure 3. Address change: propose, approve, execute once
How to read this: the model appears only in the first step. Approval covers exactly the arguments shown, once. The second status read is the guard, because the order may have moved to picked since the proposal; it narrows the window, so also ask whether the OMS refuses the change itself.