Before we write a line of code for any agent, we produce a workflow document. It is not a technical spec — it is a description of what the agent does in plain language, with explicit decisions about every meaningful branch and every situation where a human needs to be involved. We have found that this step prevents more production problems than any amount of post-build testing.
Here is what it contains and why each part matters.
Section 1: The happy path narrative
The workflow document starts with a two-paragraph description of the happy path — the most common, least complicated version of the process. Written in plain language, not pseudocode. The point is that anyone involved in the project, including people who will not write any code, can read it and confirm that it accurately describes what they want to happen.
This sounds obvious but is frequently skipped. Teams go directly from "the agent should handle X" to technical design. The happy path narrative forces everyone to agree on what success looks like before any design decisions are made.
Section 2: The input inventory
Every piece of information the agent needs to do its job gets listed here, along with its source (which system, which field, which format), and what happens if it is missing or malformed. This is where a lot of edge cases surface: people discover that the field they assumed was always populated is sometimes empty, or that the same information comes in different formats from different sources.
We do not move forward until every input is accounted for and every missing-or-malformed case has an explicit handling decision.
Section 3: The decision inventory
Every place where the agent makes a judgment — not just follows a rule, but actually decides between options based on context — gets documented here. For each decision:
- What information does the agent use to make it?
- What are the possible outcomes?
- What is the consequence if the agent gets it wrong?
- Does this decision require a human review step?
The last question is the most important. Most agents try to do too much autonomously. Our experience is that routing decisions, classification, and information extraction can usually be done autonomously. Actions with significant downstream consequences — sending external communications, modifying financial records, triggering commitments to third parties — almost always warrant a human review step, at least until the agent has a demonstrated track record on that specific decision type.
Section 4: The escalation design
This section specifies exactly what happens when the agent encounters something it cannot or should not handle autonomously. Three things get defined for each escalation scenario:
- What triggers the escalation (the condition)
- What the agent surfaces to the human (the briefing format)
- Who receives the escalation and through what channel
A common mistake is to design escalation as an error state — the agent stops and produces an alert. Escalation should feel more like the agent has done as much of the prep as it can and is handing off a ready-to-review package. The human should not have to dig around to understand the situation — the briefing should give them everything they need to make a decision quickly.
Section 5: The audit requirements
Every agent we deploy produces a log of its actions — what it decided, why (in terms of the inputs it used), and what it did. The workflow document specifies what that log needs to contain. This matters both for debugging when something goes wrong and for compliance in environments where the provenance of automated decisions is regulated.
We have found that thinking through audit requirements during workflow design often changes the design itself. Sometimes you realise that a decision you planned to make autonomous needs a structured record that the current tool set cannot easily produce — and it is much cheaper to solve that in design than in code.
How long this takes
For a well-scoped single-workflow agent, this document takes one to two working sessions to produce — maybe four to six hours total including review and agreement from the client side. For more complex agents, longer. It is paid time within the engagement scope, not a free pre-sales exercise.
The question we sometimes hear is whether this is really necessary for a small scope. Our answer: the smaller the scope, the faster the document. The value is not proportional to the length — it is the act of forcing explicit decisions that matters. A short workflow document for a small-scope agent can prevent weeks of rework after deployment.