Before You Build an AI Agent, Understand the Workflow

A company can have a clear AI ambition and still be unable to name the first workflow it should change.

That is not a technology problem. It is a visibility problem.

When a legacy product contains several web applications, mobile clients, backend generations, data synchronisation services, reporting jobs, and shared infrastructure, a request such as “add an agent” is too vague to guide safe engineering. The same business action may pass through several interfaces, services, databases, scheduled jobs, and human workarounds.

Before choosing a model, map the work.

A legacy product is a workflow, not a codebase

A code repository shows an important part of a system. It does not show the whole operating reality.

The real workflow may also include:

• a person receiving a request through one interface;
• a web or mobile client collecting information;
• an older service applying business rules;
• a newer service handling a newer version of the same capability;
• a database whose meaning is only partly documented;
• a scheduled synchronisation or reporting process;
• an operator correcting an exception manually;
• an infrastructure component routing traffic between services;
• a person who knows how to recover when the normal path fails.

This is why a modern interface or an AI assistant can create disappointing results. It may improve one visible step while leaving the difficult parts untouched: unclear ownership, contradictory data, undocumented rules, and fragile handoffs.

The useful unit of transformation is therefore not the repository. It is the workflow that creates an outcome for someone.

What we learned from mapping a complex legacy environment

In one legacy-project environment, the system had accumulated multiple application generations and supporting services over time. It included web frontends, mobile applications, backend APIs, data-sync services, reporting automation, dashboards, and edge infrastructure.

The first useful deliverable was not an agent. It was a shared map for humans and agents.

The map recorded:

• which components existed and what each one appeared to do;
• the dependencies between services and clients;
• local and deployment requirements;
• environment variables and configuration expectations;
• validation commands and quality gates;
• operational runbooks and startup order;
• ownership and risk-sensitive areas;
• known gaps, such as missing migrations or uncertain service boundaries.

The repository evidence for this case is an internal coordination workspace and its documentation. The names, URLs, and domain details are intentionally omitted here. The point is that agents and engineers needed a reliable orientation layer before they could change any part of it safely.

That map changed the question from:

Where could we add AI?

to:

Which part of an existing workflow is understood well enough to improve, and what evidence would show that the improvement is safe?

That is a much better starting point.

Map the path from intent to outcome

A useful workflow map follows work through the system, not just requests through an API.

For one recurring process, document the following:

1. Trigger: What starts the work? A user action, a message, a scheduled job, an external event, or an internal decision?
2. Intent: What outcome is the person or business trying to achieve?
3. Interfaces: Which web, mobile, administrative, or external interfaces are involved?
4. Data: What information is required, where does it come from, and which source is authoritative?
5. Decisions: Which rules are deterministic? Which decisions depend on judgement, policy, or incomplete information?
6. Handoffs: Where does work move between people, teams, services, or generations of the product?
7. Exceptions: What happens when data is missing, contradictory, late, or invalid?
8. Completion: How does someone know the work is finished, correct, and safe to close?
9. Recovery: Who can intervene, reverse an action, or continue after a failure?

This map exposes the places where AI might help. It also exposes the places where AI would only make uncertainty move faster.

For example, a summarisation step may be a good candidate for assistance when the inputs are known and the result is reviewed. A payment approval, production change, or legally significant communication needs a different design. The important question is not whether a model can perform the action. It is whether the surrounding workflow can support the action with clear authority, evidence, and recovery.

The map should include people and operations

A technical architecture diagram is useful, but it is not enough.

A workflow map should show who owns each meaningful step and what they do when the normal path breaks. In legacy environments, this knowledge often lives in people rather than documentation. A support specialist may know which record is trustworthy. An operator may know that a “successful” status still requires a manual check. A developer may know which service is actually authoritative despite the names suggesting otherwise.

Those details are not incidental friction. They are part of the system.

The same applies to operations. A workflow that appears simple in a product demonstration may depend on:

• a specific environment configuration;
• a scheduled process;
• an integration credential;
• a database migration;
• a monitoring dashboard;
• a manual recovery procedure;
• an approval that is not represented in the software.

If those dependencies are not visible, an agent may produce a locally correct change with a globally incorrect effect.

Give agents a context they can inspect

Agents need more than access to source code. They need enough context to understand the boundary of the change.

In the environment, the coordination layer combined human-readable documentation with machine-readable context. It catalogued repositories, scripts, runtime requirements, validation commands, risk areas, and operational dependencies. It also defined how context should be refreshed and how stale or sensitive information should be handled.

That design reflects a simple principle:

An agent should be able to discover what it is allowed to change, what it must verify, and who remains responsible for the result.

This does not mean creating documentation for its own sake. It means creating the smallest reliable orientation layer that prevents repeated rediscovery and unsafe assumptions.

The context must also be treated as an operational asset. It can become stale. Configuration changes. Services move. Ownership changes. A map without freshness expectations is another source of false confidence.

For that reason, useful context has:

• a canonical location;
• an owner;
• a refresh rule;
• validation checks;
• explicit gaps;
• redaction rules for sensitive information.

The goal is not perfect documentation. The goal is enough trustworthy context to make the next decision inspectable.

Start with one workflow and a reversible slice

Mapping the entire company before doing anything may be unnecessary. Start with one recurring workflow that matters to the business and is narrow enough to inspect.

A practical sequence is:

1. Choose a workflow with visible cost, delay, error, or coordination burden.
2. Observe how it actually runs, including exceptions and manual workarounds.
3. Trace the workflow across interfaces, services, data, and people.
4. Mark what is known, uncertain, authoritative, duplicated, or missing.
5. Classify each step as deterministic automation, agent assistance, human decision, or out of scope.
6. Build a small slice with limited data and reversible actions.
7. Evaluate it against real examples, failure cases, permissions, cost, and recovery.
8. Expand the boundary only when the evidence supports it.

The first slice should answer a decision question, not merely demonstrate that a model can generate an output.

For example:

Can this workflow reduce manual coordination while preserving approval, traceability, and the operator’s ability to recover from an error?

That question gives the team something to measure. “Does the agent work?” does not.

Mapping is not a reason to postpone change

There is a legitimate risk that discovery becomes a large documentation exercise with no delivery.

The answer is not to skip discovery. It is to keep the first map small and connected to a decision.

A useful first map can fit on one page. It should identify the current path, the people and systems involved, the main exception, the authority for important data, and the smallest safe improvement. It can then be expanded as the team learns.

Nor does every workflow need an agent. Some should be simplified. Some need a reliable integration or validation rule. Some require better monitoring or clearer ownership. Some are not worth automating because the judgement involved is the value of the work.

This is where humility matters. The map is a working model of reality, not reality itself. Validate it with the people who operate the workflow, compare it with the code and data, and update it when evidence changes.

Earn autonomy from understanding

AI transformation should begin with existing workflows because transformation changes a system that already has users, dependencies, responsibilities, and failure modes.

A map makes those elements visible. It helps a team distinguish between:

• an opportunity for genuine leverage;
• a broken or duplicated process;
• a data-quality problem;
• a missing integration;
• a governance decision;
• a workflow that should remain human-led.

Only then can the team decide where an agent belongs.

The practical next step is simple: select one recurring workflow and write down its path from trigger to outcome. Include the systems, people, data, decisions, exceptions, approvals, and recovery steps. Then ask which part is sufficiently understood to improve first.

If the workflow is still unclear, a discovery session can help turn scattered knowledge into a decision-ready map. If the existing platform is too risky to change confidently, an engineering audit can establish the technical and operational evidence needed for the next step.