How to calculate your agent integration debt

Your agent project is stalled. You know the problem is somewhere in the gap between what your APIs expose and what your agents need to do. But "the APIs aren't good enough" is not a case you can take to leadership. You need a number.

This guide walks through how to calculate your agent integration debt: the engineering work required to close the gap between your current API surface and a surface that agents can actually act on. It's not a precise science, but it's precise enough to make decisions with.

What agent integration debt is

Agent integration debt is the accumulated gap between what your product can do and what an agent can reach. It exists because SaaS products were built for the UI. APIs kept up with some of it. The rest — form logic in controllers, workflows that span screens, permission checks that live outside the API layer — is invisible to agents.

Unlike technical debt in the traditional sense, agent integration debt isn't caused by shortcuts taken in the past. It's caused by a new consumer — the agent — arriving with requirements that no one designed for. The debt isn't your fault. But it's your problem.

Step 1: Map what your agents need to do

Start with the agent's task list, not your API docs. What are the five to ten business tasks your agent project is trying to automate? Write them in user terms, not API terms.

Examples:

• Enrol a new student in a course with prerequisite checks
• Process an insurance claim through first review
• Close a deal and trigger the handoff to onboarding
• Update a patient record with visit notes and billing codes

For each task, break it into the atomic actions it requires. In our experience, a single business task typically requires between three and fifteen atomic actions. List them all.

Step 2: Map those actions to your API surface

For each atomic action, check whether your current API supports it. There are three outcomes:

Covered. The API endpoint exists, is documented, and works reliably. No work needed.

Partially covered. An endpoint exists but doesn't expose the full behaviour — missing fields, missing logic, missing permission handling. Some work needed.

Not covered. The capability exists in the product but there's no API surface for it at all. Significant work needed.

Build a simple table. Task, atomic actions, coverage status. Don't spend more than a day on this — you're estimating, not auditing.

Step 3: Estimate the engineering effort per gap

For each uncovered or partially covered action, estimate the engineering work to close the gap. Use three bands:

Small (1–3 days). Exposing an existing internal method through a new endpoint. The logic exists; it just needs a surface.

Medium (1–2 weeks). Refactoring controller logic to make it callable externally without breaking existing consumers. Requires care but not a rewrite.

Large (4+ weeks). The capability exists only in UI logic, not in any backend layer. Closing the gap requires pulling business logic out of the frontend and into a callable service. Often involves auth, validation, and state management work.

Be honest about which band each gap falls into. The temptation is to underestimate; resist it. Leadership making investment decisions based on underestimates is worse than leadership making decisions based on honest ones.

Step 4: Multiply across your product portfolio

If your company has multiple products — through acquisition, organic growth, or parallel lines — repeat steps 1–3 for each product the agent project touches.

This is where the debt compounds. A gap that takes two weeks to close in one product often takes two weeks per product, not two weeks total. The tech stacks are different. The teams are different. The auth models are different. There is no economy of scale in bespoke connector work.

Add up the total across all products. That's your integration debt figure.

Step 5: Add the maintenance multiplier

One-time engineering cost is only part of the picture. APIs change. When they do, any agent tooling built against the old shape needs updating — and that work falls on whoever owns the tooling.

A rough maintenance multiplier: industry benchmarks put general software maintenance at 15–25% of initial build cost per year, with integration-heavy and business-critical systems trending toward the upper end of that range or beyond. For agent connector work — which is integration-heavy by definition, spans multiple systems, and breaks whenever upstream APIs change — assume 20–30% per year. If your integration debt figure is 40 engineer-weeks to close, expect 8–12 engineer-weeks per year in ongoing maintenance, compounding as the product changes.

This is the number that often surprises leadership. The build cost is a one-time hit. The maintenance cost is a recurring charge on a system that wasn't designed to be maintained this way.

What to do with the number

You now have two figures: total build cost, and annual maintenance cost.

These serve three purposes:

Making the internal case. A concrete number changes the conversation from "the APIs aren't good enough" to "closing this gap in-house would take X engineer-weeks and Y per year in maintenance." That's a fundable or unfundable decision, not a vague complaint.

Sizing the alternatives. Whatever alternative you're evaluating — a vendor, a platform, a different architecture — you now have a baseline to compare against. The comparison isn't "does this cost money" but "does this cost less than X, and what does it buy us in maintenance savings."

Prioritising which products to start with. If you have five products and three of them account for 80% of the debt, that tells you where to start. Integration debt isn't evenly distributed. The calculation usually reveals the right sequence.

A note on what the calculation doesn't capture

This method estimates build and maintenance cost. It doesn't capture:

• Opportunity cost — the agent project outcomes delayed while the gap stays open
• Drift risk — what happens when a product change breaks agent tooling silently
• Prioritisation cost — the internal political cost of pulling engineering teams away from their roadmap to build connector work

Those are real costs. They're just harder to quantify. Acknowledge them in the presentation, but don't let them substitute for the concrete number.

The concrete number is what gets the conversation out of vague and into actionable.