Your Agent Pilot Isn’t Testing AI. It’s Exposing Architecture Debt.

Six forms of architecture debt a stalled pilot makes visible, the replay test that separates them from agent failures, and the smallest backlog that unblocks the agent.
Header-AI-Agent-Implementation-Challenges.webp

Executive Summary

An action-taking agent pilot tests more than AI.

It exposes weaknesses in the underlying architecture, from unclear rules and brittle interfaces to incomplete data and hidden exceptions. When a pilot stalls, the problem may not be the model but the systems around it. This article explains how to tell the difference, identify the six types of architecture debt, and decide where to fix them.

Key Takeaways

  • Users often compensate for unclear rules and missing information. Agents expose these gaps because they cannot rely on human judgment or workarounds.
  • Reproduce a failure outside the model before diagnosing it. Only problems that persist should go on the modernization backlog.
  • Six types of architecture debt commonly emerge: logic, contract, authority, data, state and transaction, and evidence debt.
  • Adapters are useful when they translate between systems. They become debt when they take on business rules, access decisions, or workflow state.
  • Three gaps should block production: unclear permissions, unrecoverable progress, and unverifiable outcomes.
  • A stalled pilot should produce a focused modernization backlog for one workflow, not trigger a complete rewrite.

The usual response to a stalled agent pilot is to blame the model and rewrite the prompts. This article tests that reflex against one fictional but familiar case: an embedded offboarding agent in a B2B work-management product. It shows how to separate an agent failure from an architecture failure, reads a single trace that does exactly that, names the six debts such traces reveal, and ends with the smallest backlog that gets the workflow moving again. Start with what the debt actually is.

What Is Architecture Debt?

Architecture debt is the gap between what a product’s structure can express and what its workflows need. It builds up from decisions that worked while a person was in the loop: a rule enforced only by a screen, a permission model with no narrow roles, two systems that both own the same record, a multistep job tracked in someone’s head, and an operation whose success nobody verifies.

It differs from code-level technical debt in where it lives. The team that owns a service can refactor messy code inside it. Architecture debt sits between services, data sources, and permission models, so paying it down usually takes decisions across teams.

While people do the work, the debt costs little, because people route around it. It starts charging interest when software has to act on its own, which is why an action-taking agent pilot exposes it.

Understanding Architecture Debt with an Example

Picture the pilot in use in an HRMS platform. An authorized administrator asks the offboarding agent to offboard a departing employee, a job with seven steps:

  1. Confirm the person and the effective date.
  2. Revoke active sessions.
  3. Disable application access.
  4. Transfer owned projects and files.
  5. Reassign open approvals.
  6. Preserve required records.
  7. Log completion, with any unresolved exceptions.

The model understands the request on the first try. The pilot stalls anyway.

The team reads that as a model-quality problem and starts tuning prompts. The blockers can sit lower. Some rules exist only in the interface. Permissions are too broad to delegate. HR, the directory, and the product itself disagree about who owns what. APIs cannot say whether a job finished, and nothing reliably proves that any step completed. Each is a form of architecture debt, and each stays invisible while someone does the work.

Experienced Users Can Innately Navigate to Find Workarounds

Experienced users know which screen shows the real status, which validation message is safe to ignore, which operations must run in order, and which exceptions get handled outside the product entirely. None of that lives anywhere an agent can reach.

The point is not that people are dependable and agents are fragile. People compensate for missing rules, inconsistent states, and ambiguous errors without noticing. That compensation is the debt’s camouflage. Take the person out of one workflow, and the camouflage goes with them. So when the pilot stalls, the first job is to establish whether the agent failed or the product did.

How Do You Test Whether a Failure Belongs to the Architecture Instead of the Pilot?

Repetition localizes a problem. It does not prove the cause. A pilot can break at the same handoff on every run because of tool schemas, prompt design, or the model itself. Before a failure earns a place on the modernization backlog, isolate it in four steps:

  1. Confirm the action. Check that the model interpreted the request and selected the intended operation.
  2. Replay without the model. Run the same operation with fixed inputs through a deterministic client: a scripted caller that sends identical inputs every time, with no model in the loop.
  3. Inspect the operation. Review its contract, the authorization it ran under, the operational state, and the trace.
  4. Classify the result. If the operation still fails, classify the architecture debt. If it succeeds, investigate the agent, the prompts, or the tool design instead.

Replay is strong evidence, but it has limits. A passing replay clears the operation under the inputs you used, not under every condition. When a failure depends on timing, concurrency, or the state the system was in when the agent called it, replay against that state before you clear the product. A failing replay can also reflect a different environment or credential, so confirm that the replay matches the conditions the agent ran under.

A repeated failure at one handoff is a clue, not proof. In the modernization assessments I run, the recurring version of this is a team two weeks into prompt tuning when the blocker was a permission model all along. Here is what the method looks like on one step of the offboarding job.

Exposing Contract Debt and Evidence Debt

Take step 2 of the offboarding job, a revocation that reported success while two sessions stayed active, and read its trace field by field.

Trace: offboarding step 2, session revocation

Expected action
Revoke all active sessions for the departing employee.
Actual result
The agent calls the revocation operation and gets a success response.
Manual check
Two sessions remain active on an older single sign-on system.
Replay
Repeating the operation outside the agent produces the same result, confirming a product defect.
Diagnosis
  • Contract debt: The operation covers only the primary identity provider.
  • Evidence debt: The platform cannot check sessions across both providers.
Disposition
Add session inventory and verification to the core platform. Use an adapter to revoke sessions across both providers until the core fix is ready.

One trace, and the pilot has produced a diagnosis, an owner, and two backlog items. The rest of this article generalizes that reading, starting with the six debts a replay can surface.

A success response proves what the endpoint promised. It doesn’t prove the business outcome happened.

Six Architecture Debts an Action-Taking Agent Exposes

We use six categories to read recurring failures in action-taking agent pilots. Each one below starts with how the offboarding agent meets it, then points to the smallest lasting fix.

Logic Debt: Rules That Exist Only in the Interface

The offboarding agent has to decide which accounts a departing contractor keeps. If that rule must be reverse-engineered from screens, or duplicated into the agent’s prompt, the rule does not exist as far as the product is concerned.

Business logic and interface behavior are different things, and the difference becomes expensive the day software has to act. The fix is extraction: stable rules move into deterministic services or policy that the product itself enforces.

Contract Debt: Operations That Cannot Say Whether the Job Finished

The offboarding agent calls an operation and gets back an answer that cannot tell it whether the job finished, why it failed, or whether a retry is safe. The debt is what the contract leaves out:

  • Declared preconditions.
  • Stable schemas.
  • Errors that state a cause.
  • An answer to whether the job finished.
  • Defined retry and recovery behavior.

Contract debt is not shorthand for bad APIs. Resource-oriented interfaces, which expose data objects such as users and files rather than whole business tasks, are not the villain. Well-specified resource operations compose into workflows.

Goal-shaped operations, which perform one complete business task such as “offboard this user,” make an agent’s tooling simpler and are worth having. The requirement, though, is the dependable contract.

Authority Debt: Permissions Too Broad to Delegate

A powerful backend credential plus prompt instructions saying “only touch this tenant” is not least privilege; it is trust in a sentence. The agent needs authority bounded to the tenant, the user, the workflow, the action, and the resources involved.

Where the permission model cannot express that boundary, the pilot has found a security backlog item that predates the agent.

Data Debt: Systems That Disagree About Who Owns What

Missing data is the easy version. The harder version is conflict: HR says the employee left Friday, the directory says active, and two systems both claim to own project assignments. An agent cannot arbitrate ownership that the system landscape never settled. The remedy is authoritative sources and reconciliation rules, decided once and encoded.

State and Transaction Debt: Workflows That Cannot Survive Partial Completion

Offboarding is not one atomic write. It is a sequence in which partial completion is normal. The workflow must represent what completed, what failed, what can be retried, and what needs a person. It must also survive a mid-workflow restart.

Agent memory and conversation history are not workflow state. Durable progress and recovery state belong in the business workflow or the system of record.

Patterns for long-running sequences already exist. The saga pattern, for example, breaks a long transaction into steps and pairs each step with a compensating action that undoes it if a later step fails. The debt is that the workflow was never modeled as a single unit.

Evidence Debt: Outcomes Nobody Can Prove

When security asks which sessions were revoked and when, the product needs an answer stronger than a log line showing that a call returned 200, the HTTP status code for success. Evidence debt is the gap between what happened and what you can prove.

A successful response proves what that endpoint’s contract promises. In a workflow that spans systems, it does not prove the business outcome. Two mechanisms close the gap, and they do different jobs:

  • Durable event history provides attribution and sequence: who did what, and in what order.
  • An end-state check confirms the outcome: the sessions are actually gone.

The product needs both. Evidence debt is the quietest of the six, and the first one compliance will find.

How to Tell Neighboring Debts Apart

Three pairs are easy to confuse, and confusing them sends the fix to the wrong place.

Contract versus evidence. Contract debt concerns what an operation promises. Evidence debt concerns whether anyone can independently check the outcome. The session-revocation trace showed both at one operation.

Logic versus authority. Logic debt means the product does not encode the rule. Authority debt means the product cannot restrict who may carry out an operation, even when the rule is clear.

Data versus state and transaction. Data debt means systems disagree about the facts. State and transaction debt means the workflow cannot track or recover its own progress.

Symptom-to-Debt Reading Key

The table maps symptoms to hypotheses, not verdicts. Every row assumes the replay has already cleared the agent.

Pilot symptomWhat to investigateFirst remediation direction
Every exception spawns a new prompt ruleLogic debtMove stable rules into deterministic services or policy.
The agent chooses between overlapping operations inconsistentlyContract debtConsolidate around distinct, goal-shaped capabilities.
The pilot only works with a highly privileged credentialAuthority debtIntroduce resource- and transaction-specific permissions.
The agent keeps asking for information it should haveData debt, or a retrieval gap rather than architecture debtDefine authoritative sources and retrieval contracts.
A retry creates duplicates or inconsistent stateState and transaction debtAdd operation records, idempotency (a retried call produces the same result, not a duplicate), and recovery semantics.
The agent reports done, and nobody can confirm itEvidence debtDefine end-state checks and completion evidence.
Symptom-to-debt reading key

Naming the debt is half the diagnosis. The other half decides what the fix will cost.

How Do You Decide Whether a Fix Belongs in an Adapter or the Product?

Once you have a diagnosis, one decision drives cost and honesty: where the fix lives.

When an Adapter Is Permanent Architecture and When It Becomes Debt

An adapter earns its keep when the underlying behavior is stable and correct, and the gap is naming, schema translation, or aggregating a few calls into one operation. An adapter that only translates stable behavior may be the permanent answer. Governed façades (controlled interfaces placed in front of existing systems) and anti-corruption layers (translation layers that stop one system’s model from leaking into another) are recognized architecture, not scaffolding.

An adapter becomes debt when it quietly acquires duplicated rules, authorization decisions, or workflow state without clear ownership. Every further adapter will rebuild them, and the copies will disagree. When the gap is rules, authority, or workflow state, the adapter defers the modernization invoice. It does not cancel it.

When the Product Itself Must Change

Change the product itself when any of these conditions hold:

  • The same problem blocks several workflows.
  • Business rules exist only in the UI or the prompt.
  • Permissions cannot be narrowed safely.
  • Multiple systems claim the same state.
  • Partial completion cannot be represented.
  • Compliance and support need authoritative evidence.

Three Gaps That Should Block Production

Three kinds of gaps should block production: authority that cannot be narrowed to the workflow, state that cannot be represented or recovered after partial completion, and outcomes that cannot be verified independently. Ship past those and the agent operates with too much power, unknown progress, and unprovable results. Naming gaps, schema translation, and tool ergonomics are fixable behind an adapter and should not block.

That sorting tells you what is urgent. The backlog tells you what order to do it in.

How Do You Build the Minimum Viable Modernization Backlog?

Modernizing the whole product before continuing the pilot is the wrong conclusion in the other direction. Prioritize what the specific workflow requires, in the order the workflow needs it.

Remediate in Workflow Order

Each step closes one of the six debts:

  1. Establish the authoritative state and the success condition (data debt). This step also defines what “done” means, which the final step proves.
  2. Define the narrow authority the workflow requires (authority debt).
  3. Extract the business rules the workflow depends on (logic debt).
  4. Repair or wrap the product contracts involved (contract debt).
  5. Add persistent workflow and recovery state (state and transaction debt).
  6. Capture verification and audit evidence (evidence debt).

Missing event history belongs on the backlog with special urgency. Without it, the team can confirm the end state but cannot attribute how the system got there.

Classify Every Fix by Where It Lives

Then give each remediation one of five dispositions:

DispositionWhat it means
Pilot-specific adapterA translation or aggregation layer that serves this pilot, such as the interim revocation adapter.
Shared platform capabilityA fix that several workflows or agents will reuse.
Core product changeA gap in rules, authority, state, or evidence that the product itself must own.
Deferred limitationA known gap the workflow operates around for now, documented rather than hidden.
Unexposed capabilityAn operation the agent should not reach until its debt is resolved.
Five dispositions for a modernization fix

The final disposition also feeds the ‘Agent Access Matrix’, the framework that separately determines whether and how each capability should be exposed to agents (see our upcoming article for more).

Why Is a Stalled Pilot a Diagnostic Report on the Product?

A failure that survives a deterministic replay is the pilot returning results. It shows where the product and the systems around it cannot yet express rules, authority, state, and outcomes clearly enough for software to act on them.

The pilot failed as a demonstration and succeeded as a diagnostic. Teams that treat it that way come out with a focused backlog and a stronger product. Teams that keep tuning the prompt end up with a better-worded version of the same stall.

FAQs

1. How can a team tell agent-design failure from architecture debt?

Reproduce the failing operation outside the model. Replay it with fixed inputs through a deterministic client, then inspect the contract, authorization, operational state, and trace. If the operation still fails, the debt is most likely architectural. If it passes, investigate the agent, the prompts, or the tool design, unless the failure depends on timing or system state.

2. Can MCP or better tool schemas fix architecture debt?

No. MCP (Model Context Protocol) standardizes how tools and systems are exposed to agents, and good schemas remove one source of confusion. Neither can create business rules, authorization boundaries, workflow state, or outcome semantics the product does not have. A standard interface to a product that cannot express its own rules is a cleaner view of the same debt.

3. Which pilot failures should block production?

Three kinds: authority that cannot be narrowed, progress that cannot be recovered after partial completion, and outcomes that cannot be verified. In the session-revocation trace, the evidence gap blocks, because nobody can prove the sessions are gone. The contract gap does not, because an adapter can aggregate the two revocation calls while the core fix ships.

Application Modernization

Did your agent pilot expose more than an AI problem?

We help product teams turn pilot findings into a focused modernization backlog across APIs, permissions, workflow state, data ownership, and operational evidence.

Table of Contents

Related Services

Latest Insights

Stay ahead of the curve with our expert analysis, industry trends, and actionable advice. Our blog offers fresh perspectives on the challenges and opportunities in the tech landscape, helping you make informed decisions and drive innovation within your organization.

Net Solutions

Ask Sol

Powered by Net Solutions

Skip the search. Start the conversation.

Ask Sol anything about digital products, AI, engineering, or growth, and get answers drawn from years of Net Solutions thinking and experience.

Our assistant helps you find content on our website. By asking a question, you acknowledge that we will process your data in accordance with our Privacy Policy, and consent to anonymous tracking of your conversation to help us improve the experience. Please avoid sharing personal or sensitive information, and close this page if you do not agree to these terms. While we strive for accuracy, AI responses may be inaccurate.By chatting you accept our Privacy Policy and anonymous analytics. Do not share sensitive information. AI answers may be inaccurate.