AI Agent Integration With Legacy Systems: A Playbook
AI agent integration with legacy systems rarely needs a rewrite. Five integration patterns, how to design agent-safe tools, and the order to build them in.
Your Agent Doesn't Need a New ERP
AI agent integration with legacy systems always arrives in the same shape. Someone has an agent that works beautifully against a sandbox, and the only thing standing between it and real value is a nineteen-year-old order management system that nobody fully understands, has no API worth the name, and cannot be taken offline for longer than a Sunday night.
The instinct at that point is to scope a modernization programme. That instinct is usually premature. This is an interface problem before it is a modernization problem, and the two have very different price tags and very different failure modes.
At Kuaray we spend a lot of time on this exact boundary, and the pattern repeats: the legacy system is not the obstacle. The obstacle is that teams hand an agent the same raw surface a human operator uses — a hundred CRUD endpoints, a database login, a screen with forty fields — and then wonder why it improvises. The work is designing a deliberate, narrow, verifiable surface between the two. This piece is about how to build it, and which of the five integration patterns to reach for.
Why AI Agent Integration With Legacy Systems Breaks at the Tool Boundary
A traditional integration is written once by someone who read the docs. It calls the same three endpoints, in the same order, forever. When the contract changes, it throws.
An agent is not that. It decides at runtime which tool to call, with which arguments, how many times, and what to do when the response is confusing. Give it a surface designed for a human with institutional knowledge and you have handed a non-deterministic process the keys to a system whose rules live in people's heads.
So the integration layer has to carry what the legacy system never wrote down:
- Which operations exist at all. Not "every endpoint", but the handful the agent's job actually requires.
- What the preconditions are. Humans know you don't post an adjustment before the period closes. The agent does not, unless the tool enforces it.
- What "done" looks like. A 200 response is not evidence that the business operation succeeded.
- What is reversible. The tool layer is the only honest place to mark that distinction.
None of that is AI work. It is ordinary API and integration engineering, applied with more discipline than usual because the consumer will improvise rather than crash.
Five Ways to Put a Legacy System in Front of an Agent
1. Read-only replica or reporting view
The cheapest useful thing you can do. Point the agent at a read replica, materialized view or nightly extract, and let it answer questions without touching anything.
This covers far more demand than people expect — "which orders are stuck", "summarize this customer's history", "find the mismatches between these two systems". It is also the only pattern where you can relax about agent behaviour, because the blast radius is bounded by physics rather than policy.
Do not let the agent write SQL freehand against production. Expose parameterized queries as named tools, or a semantic layer, and cap result sizes.
2. A service facade over the legacy core
The workhorse. You write a thin service — typically a few hundred lines — that sits in front of the legacy system and exposes business operations rather than table rows: hold_order, issue_credit, reschedule_delivery.
The facade is where you put everything the legacy system lacks: input validation, idempotency keys, authorization scoped to the agent's role, structured errors, and an audit record of every call with the run that made it. Crucially, it is testable without the agent and usable by humans and other services afterwards. Most of our clients keep it long after the agent project ends, which is a reasonable way to judge whether a piece of work was real.
3. An MCP server over the facade
Once the facade exists, exposing it over the Model Context Protocol is largely mechanical, and worth doing rather than hard-wiring tool definitions into one application. MCP gives you a single place to version tool schemas and the ability to point a second agent — or a different vendor's model — at the same surface next quarter without rewriting the integration.
The mistake is skipping step 2 and building the MCP server directly against the legacy database. You end up with protocol plumbing wrapped around an unsafe surface, and no layer enforcing business rules.
4. Event bridge for anything long-running
Legacy systems are frequently batch-shaped. Agent tool calls are request-shaped, with a timeout. When the underlying operation takes four minutes or runs overnight, do not hold the call open and hope.
Publish the request to a queue, return a ticket, and give the agent a check_status tool and a resumable run. That is the difference between an agent that fails every Thursday during the nightly job and one that simply waits. A queue is also back-pressure you can enforce; a loop of direct calls is not.
5. UI automation, as a last resort with an expiry date
Sometimes there is no API, no database access, and no vendor cooperation. Browser or terminal automation works, and modern agents drive a UI better than the RPA generation did.
Treat it as a liability accepted on purpose. It breaks on cosmetic changes, it is hard to make idempotent, and it usually runs with a human's credentials rather than a service identity. Isolate it behind the same facade interface as everything else, so the day a real API appears you swap the implementation rather than the agent.
Choosing Between Them
| Pattern | Build effort | Blast radius | Breaks when | Reach for it when |
|---|---|---|---|---|
| Read replica / view | Low | None (read-only) | Schema drifts | The job is analysis, triage or reporting |
| Service facade | Medium | Controlled by design | Business rules change | The agent must write, and correctness matters |
| MCP server over facade | Low on top of #2 | Same as the facade | Tool schemas go unversioned | More than one agent or client will use it |
| Event bridge | Medium | Deferred, observable | The queue has no dead-letter path | Operations are slow, batch or bursty |
| UI automation | Low to start, high to keep | Whatever the user account can do | The UI changes at all | Nothing else is available, and you have an exit plan |
The honest reading of that table: patterns 1 and 2 cover most real work, and projects that went badly usually started at 5 because it looked faster in week one.
Note what is not in the table: rewriting the legacy system. That is a separate decision with separate economics, and we've written about how to decide between rebuilding and refactoring legacy software. AI agent integration with legacy systems is reversible; a rewrite is not. Do the reversible one first and let it tell you what the system actually does.
Designing Tools an Agent Can't Misuse
The facade is only as good as the tool contracts on top of it. Four rules we apply without exception when connecting AI agents to ERP, CRM or other systems of record:
Expose verbs, not endpoints. cancel_shipment(shipment_id, reason) is a tool. PATCH /shipments/{id} is an invitation to construct a body nobody anticipated. One tool should correspond to one business decision, with a small, typed, enumerated argument set.
Make every write idempotent. The agent will retry — on a timeout, on an ambiguous response, on a reread of its own transcript. Require a client-supplied idempotency key and deduplicate server-side. This one control removes an entire class of duplicate-record incidents that are otherwise hard to diagnose after the fact.
Return structured, actionable errors. {"error": "period_closed", "retryable": false, "period": "2026-10"} tells the agent to stop and escalate. A 500 with an HTML error page tells it to try something creative. Fail closed, and say why in a field the model can branch on.
Gate the irreversible. Payments, external communications, deletions and anything regulatory belongs behind an explicit approval step, with the proposed call rendered for a human in business terms rather than as a JSON blob.
Underneath all four sits identity. The agent gets its own service principal scoped to the tools it actually has — not a copy of an administrator's account, and not a shared integration user three other systems also use. Agents read untrusted content (tickets, emails, documents), which makes credential scope a live security concern rather than a hygiene checkbox.
The Order We Build It In
- Pick one workflow and trace it end to end. Not a capability — a workflow, with a named owner and a number attached. "Resolve a delivery exception", not "AI for logistics".
- Write the read tools first and ship them. A read-only agent in production this month teaches you more about your data quality than another quarter of discovery.
- Build the facade for exactly the writes that workflow needs. Three or four operations. Resist generalizing before anything is live.
- Add idempotency, structured errors and audit before the first write ships. Far cheaper built in than retrofitted after incidents.
- Put approval gates on the irreversible subset, then narrow them. Start conservative, measure how often reviewers actually intervene, remove gates where the record justifies it.
- Instrument every tool call as a span tied to a run id. When something goes wrong at 3am you want to replay the run, not theorize about it.
Steps 1 to 3 usually take weeks, not quarters, which is the point. The legacy system gets a clean, documented, authenticated edge it never had, and the agent becomes a consumer of that edge rather than a privileged guest inside your core.
What This Actually Buys You
Teams who do this well end up with something more durable than an agent: a described, enforced, audited interface to a system that previously had none. That is the first genuinely useful artifact most legacy modernization efforts produce, and it makes every later decision cheaper.
Teams who skip it get a demo that works until the first retry storm, and then a rollback.
If you are staring at a system of record and an agent that needs to touch it, the question this week is not "can the model handle it". It is: what are the five operations this agent needs, and who can state the preconditions for each one?
Talk to Kuaray about connecting agents to your systems of record — we design and build the integration layer, the tool contracts and the controls around them. See how we approach AI and agent engineering.