Skip to content
be-human.ai
← Back to the journal

Personalized AI infrastructure

Connecting Legacy Software to AI Agents: A Thin-Layer API Gap Test

A step-by-step test to find which legacy systems lack an API, export or safe write path, and how to add a thin layer for AI agents without a rewrite.

Be Human typographic cover with the title: Connecting Legacy Software to AI Agents: A Thin-Layer API Gap Test
Conceptual illustration created with AI · Be Human

To connect legacy software to AI agents, first test each system for three paths: a way to read current records, a way to export them on a schedule, and a narrow way to write changes with validation and a record of who made them. Where a path is missing, add a thin integration layer that exposes a few named operations, enforces the same permissions a staff member has, and logs every call. The old system keeps running as it does today, and the agent never touches its internals.

Key takeaways

  • Test every legacy system for read, export, write and audit paths before choosing any technology.
  • Write down the specific tasks an agent should perform, then check which systems those tasks depend on.
  • Build a thin layer with a small set of named operations, input validation and logs, not a copy of the old system.
  • Keep every write behind a permission check and an approval step until the layer has a record of reliable behavior.
  • Test the connection against known correct answers from the system of record before any agent goes live.

Why legacy systems block agents

Most older business systems were built for people sitting at a screen. They may have a web form, a nightly batch file, a shared spreadsheet, or a vendor-hosted tool with no public interface at all. An agent needs something different: it must look up the current state of a record, perform a bounded action, and leave evidence of what it did. When a system offers none of this, teams often reach for shortcuts such as pasting data into prompts or driving the user interface with automated clicks. Those shortcuts work until a screen changes, and then they fail quietly, which is the worst outcome for a business process.

The first useful question is therefore not which AI tool to adopt. It is which of your systems hold the facts the agent needs, and how each one can be read and changed by a program. A one-page architecture map helps here because it shows where each system sits and which ones feed others. For the full method, see Draw Your AI Stack: A One-Page Architecture Map for Leaders.

The API gap test, step by step

Run this test once per system, using the tasks you have already listed. Keep the answers in one shared document that operations and the system owner both review, so that disagreements about a system's capabilities surface early.

  • Step 1: List the tasks the agent would perform in this system, written as plain verbs such as looking up an order status, drafting a shipping change, or updating a customer address.
  • Step 2: Check the read path. Look for a documented API endpoint, a scheduled export, a report, or a database view that a read-only account can query. Record how fresh the data is.
  • Step 3: Check the write path. Look for an API call, an import file with validation, or a supported form that the vendor maintains. Ask whether repeating the same request creates a duplicate. Stripe's documentation on idempotent requests shows how a provider can define this behavior explicitly, and many older tools offer nothing comparable.
  • Step 4: Check the audit path. Confirm that the system records who changed what and when. If it does not, the layer must keep that record itself.
  • Step 5: Check identity. Confirm that a dedicated service account can be created and limited to specific actions, separate from any person's login.
  • Step 6: Score each task. Green means read, write and audit paths exist. Amber means only a read or export path exists. Red means the only write path is a manual screen or the system leaves no reliable record.

A task is ready for an agent when its read path is green and its write path is green or protected by an approval step. Red tasks stay with people until someone builds a proper path. Amber tasks can often start as read-only assistance, where the agent answers questions and drafts changes that a person then submits.

Illustrative scenario: a small distributor runs an order system with no API. It has a nightly export of orders and a web form for shipping changes. The agent answers status questions from the export and states the export time in every answer, so staff know the data may be a day old. Shipping changes are drafted by the agent and submitted by an employee, because the only write path is the form. The team scores status lookup as amber and shipping changes as red for now, and both decisions are written down with a date for review.

Building a thin layer that leaves the core alone

A thin layer is a small service that sits between the agent and the legacy system. It exposes a short list of named operations, such as an order status lookup or a shipping change draft, each with a clear purpose, typed inputs and a fixed set of returned fields. It does not expose raw database access, whole tables, or a general-purpose query. Tool descriptions matter as well. Anthropic's engineering guidance on writing tools for agents favors narrow, clearly described tools over broad ones, because the agent chooses which tool to call based on those descriptions.

Choose the read pattern deliberately. Transactional facts such as stock counts or open invoices should be queried live where the system allows it, or clearly marked as stale when they come from an export. Policies, manuals and long documents are a different case, suited to retrieval from an indexed set of documents. Mixing the two is a common mistake, and the Google Cloud reference architecture for retrieval-augmented generation and the AWS comparison of retrieval and fine-tuning both explain when each approach fits.

Operational habits keep the layer replaceable. Use timeouts and rate limits, return errors in plain language rather than silent empty results, and attach a trace identifier to each call so a single request can be followed from the agent to the legacy system and back. The OpenTelemetry observability primer describes these concepts in general terms. A layer built around your own operations and documented in your own terms can be changed or replaced later, which matters for the reasons explained in How to Avoid AI Vendor Lock-In With Business Agents.

Protecting writes, permissions and inputs

Permission checks belong on the server side of the layer, on every call. Do not rely on the agent's instructions to keep it within bounds. OWASP's authorization guidance is clear that access decisions should be enforced by the system receiving the request, checked for each call, and based on the identity making it. The agent's service account should hold only the operations listed in its role, and nothing else.

Inputs need equal care. Emails, tickets and web pages that the agent reads can contain text written to manipulate it. The OWASP cheat sheet on prompt injection prevention describes the general defenses: limit which tools are available for a given task, validate every value the agent passes to a write operation, and keep a person in the loop for actions with financial or customer-facing effects. A practical default is that every write needs approval at first, and approval limits are raised only after the record shows the layer behaves as expected. The review routine is covered in How to Run a Permission Review for Your AI Agents, Step by Step.

Testing the connection before it reaches production

Before an agent uses the layer on real work, build a small test set from requests your team has already handled. For each request, record the correct answer and the system of record where it lives. Then check whether the agent retrieves the right record, refuses requests outside its scope, shows the stale-data warning when it should, and avoids duplicate writes when a request is retried. The retry check is easy to skip and expensive to miss.

Anthropic's guidance on evals for agents and the OpenAI evals guide both describe how to structure such tests, with graders that check outcomes rather than wording. Keep the test set under version control and rerun it after every change to the layer or the vendor system. Define stop rules in advance: if a write test fails, writes are disabled while reads continue until the cause is found.

Operating the layer after launch

A connection works only while the systems on either side stay stable, and they often change. Vendors update forms, rename fields, or move exports to a new schedule. Monitoring should therefore cover error rates, latency, data timestamps and unexpected empty results, not only outages. Set an alert when an export is older than the team expects, because a quiet failure is harder to detect than a loud one.

Each quarter, review which service accounts exist, which operations they can call, and which approvals were granted. The checklist in Quarterly AI Agent Permission Review: Steps and Evidence gives a practical structure for that review. Keep a kill switch that disables write operations separately from read operations, so an incident can be contained without stopping the whole service.

Where to start with a managed approach

Be Human designs, implements and operates this kind of layer for companies as part of managed operations. A first engagement defines one useful role, the memory and tools that role needs, the approval boundaries, and a success criterion the business can observe. Be Human runs the gap test with your team, builds the adapter with named operations and logs under your control, keeps permissions reviewable, and handles monitoring, integration maintenance and controlled changes afterward. The work is remote and available in English and Portuguese.

If you are not yet sure which of your systems should be connected first, the free Be Human AI diagnostic can help you find the first task worth handing to an agent.

Frequently asked questions

Can an agent work with a system that has no API at all? Yes, but only in a limited way. Start with reads from an export or a read-only database view, and treat any write as a draft that a person submits until a reliable write path exists. Automating a user interface is possible but fragile, so it should be a last resort.

Do we need to rewrite our legacy software before connecting it? No. The thin layer described here sits beside the system and uses the access it already offers. A rewrite may become worth considering later for its own reasons, but it is not a prerequisite for a first useful agent.

How do we know the layer is safe enough to allow writes? Safety here rests on a record, not on a claim. Writes should pass the test set, be protected by server-side permission checks and approvals, and produce logs that show which identity made each change. Raise approval limits slowly, and only when the record supports it.

Who should own the layer after it is built? The business should own its definitions: the operations, the permissions and the approval rules. Operations or the system owner should review changes, and whoever maintains the layer should be named in writing, so that vendor changes and incidents have a clear path to resolution.

Your next step

See where an AI agent fits in your company first.

Take the free Be Human AI diagnostic. A few questions about your work show which task to hand to an agent first, what it needs to know and where a person approves.

Be Human editorial guidance. Examples are illustrative unless explicitly attributed. Sources provide background; implementation choices depend on your workflow.

Less busywork. More room for you.

Bring us the work you wish you had time for.

Book a call to try a personalized AI agent free for 7 days ↗Or take the free AI diagnostic →