An agentic workflow combines a task, decisions about what to do next, tools and a stopping rule. A useful example should show more than the happy path. It should explain what happens when information is missing, an operation fails or the workflow reaches its allowed budget.
This guide designs one document-organizing task through four paths. You get a state table, an original input fixture and explicit expected outcomes. The traces are authored walkthroughs, not logs from an executed agent or claims about a particular framework's performance.
Choose one job with a visible end
Our fictional neighborhood club has three meeting notes and wants an index of decisions, owners and unresolved questions. The output is a draft index for the coordinator. The workflow may read the supplied notes and write its draft artifact; it may not assign people new commitments, contact members or rewrite the originals.
A finished result contains a row for each supported decision, a source reference and an uncertainty flag where needed. “All notes processed” is not sufficient if the index converts discussion into approval. Completion depends on the output meeting its contract, not merely on exhausting the input list.
The building effective agents article is useful background for distinguishing predefined task paths from more flexible agent decisions. This example deliberately limits flexibility: the workflow may choose which missing item to request, but cannot expand the purpose of the task.
Define states before drawing arrows
Use seven states: received, checking input, reading notes, drafting index, reviewing evidence, waiting for input and finished. Add two explicit endings: stopped after failure and stopped at budget. A waiting state is not a success state; a stopped run is not necessarily a failed business outcome if it returns an honest handoff.
Download the original state table and four traces. Keep the transition reasons beside the state names so that another person can repeat the walkthrough.
| Current state | Condition | Next state | Artifact preserved |
|---|---|---|---|
| Checking input | All required notes present | Reading notes | Source manifest |
| Checking input | Note referenced but missing | Waiting for input | Missing-source request |
| Reading notes | Read operation fails once | Bounded retry | Failure description |
| Reading notes | Retry still fails | Stopped after failure | Partial index and unresolved sources |
| Reviewing evidence | Claims supported | Finished | Draft index plus review status |
| Any active state | Exercise budget reached | Stopped at budget | Checkpoint and next required step |
Do not use “error” as a single node for every exception. A missing note needs a person to supply it; a temporary read failure might justify one retry; a budget stop requires a checkpoint. Combining those outcomes makes the recovery path ambiguous.
Path one: produce the draft index
The input contains N1, N2 and N3. N1 approves a Saturday cleanup. N2 records discussion of a tool loan but no approval. N3 confirms that the cleanup time remains unresolved. The index should include the approved cleanup, preserve its unresolved time and keep the tool-loan proposal distinct from a decision.
An authored draft row reads: “Cleanup approved; time unconfirmed; owner not assigned in the supplied notes; sources N1 and N3.” That is less satisfying than inventing an owner, but it faithfully represents the evidence. The coordinator can now answer the missing questions.
Before finishing, check whether every decision row has a source and whether every unresolved item is still visible. A clean table with empty cells silently filled by inference should fail the review. A useful workflow can produce an incomplete but accurate artifact.
If the task is repeated after new notes arrive, assign a new input version. Do not overwrite the earlier index without preserving the evidence it used. A reviewer should be able to distinguish a corrected extraction from a newly approved decision.
Path two: request the missing note
Now remove N3 while N1 still refers to a later time decision. The workflow knows that the pack is incomplete. It should stop before claiming the schedule is settled and return a request naming N3 and the question it would answer.
A useful request is: “Please provide the follow-up note referenced by N1, or confirm that the event time remains undecided.” It gives the coordinator two ways to resolve the dependency. “Need more context” is too vague to act on.
Draw this path separately from tool failure. Nothing has crashed; the information is simply absent. A retry of the same three file locations cannot create a note nobody supplied. The next useful action belongs to the source owner.
Put your own task on the canvas
Open the agentic workflow architecture template. Replace its generic task with your input manifest, draft artifact and review condition. Add three clearly labeled exits: missing input, read failed after retry, and budget reached. Write the handoff artifact beside each exit.
Author-created example: inspect the relationships before adapting the template.
The template already illustrates common architecture patterns. Use this exercise to add a single end-to-end task and its failure behavior instead of making another list of patterns. The canvas should help a colleague answer “what happens next?” at every branch.
For repository-specific events and outputs, see GitHub Agentic Workflows issue triage. A repository label or comment introduces effects that this document-index exercise does not have.
Path three: handle a failed read
Assume the input manifest names N2, but reading it returns a temporary error. The exercise allows one retry of that read. Record which source failed, the observed error and the retry count. Do not retry every completed step, because that can duplicate work and obscure which operation actually failed.
If the second attempt fails, preserve the rows supported by N1 and N3 and mark N2 unresolved. The resulting artifact must say that the index is partial. It should not infer N2's content from its filename or from a previous unrelated run.
This retry limit is an exercise design choice, not a universal recommendation. A real system may need different handling for temporary failures, invalid files, permission errors and unavailable services. Classify the failure first. Repeating a request with unchanged permissions will not normally resolve an access decision.
When a real operation can write state, retry design becomes more demanding. You need to know whether the first attempt took effect before it failed to return a response. A duplicate-safe operation or a state check may be required. The document exercise avoids external writes, but your production map must not hide them behind the same “retry” arrow.
Path four: stop at the exercise budget
Define the budget in observable terms. For this paper exercise, allow at most three source-read attempts and two drafting passes. These numbers create a testable boundary; they are not measured optimal settings or a promise about API cost.
If a repeated revision reaches the second drafting pass without resolving a source contradiction, stop and save the current index, the unresolved claim and the reason another revision would require new evidence. Do not relabel the partial artifact as final just because no more work is allowed.
A checkpoint should contain the input version, completed steps, unresolved items, artifact location and the next permitted action. It should not rely on a vague internal memory of what happened. If another person resumes the task tomorrow, the checkpoint should be sufficient to understand why it stopped.
Use separate counters for different operations when they have different meanings. Three reads and two revisions are not interchangeable units. In a live system, token usage, elapsed time and paid operations may need their own measurement and limits.
Review the four traces with a simple rubric
Check four properties in each path: evidence meaning is preserved, the next action is appropriate, the output status is honest and the boundary is respected. The success path must not invent an owner. The missing-input path must request the named dependency. The failed-read path must retain a partial status. The budget path must return a checkpoint.
A human walkthrough verifies the design logic, not the runtime. If you implement the process in software, replay the fixtures and save actual outputs separately. Observe which tools ran, which files changed and whether stopping occurred where the design predicted.
Use a disagreement log. When two reviewers classify the same note differently, write down whether the ambiguity is in the source, the task contract or the extraction rule. Not every disagreement should be solved by adding another instruction; sometimes the source needs a clearer approval statement.
The context engineering example helps with source versions, while the Claude Skills review exercise shows how to package a recurring evidence-checking method. They support different responsibilities inside the same workflow.
Common workflow design mistakes
A loop with no new evidence. Revising the same uncertain claim repeatedly does not resolve it. Return to the source owner when the missing information is outside the workflow.
A success label on every ending. “Stopped at budget” can be an acceptable controlled outcome, but it is not the same as a complete index. Keep status names meaningful for the person receiving the artifact.
A checkpoint without an input version. Resuming against changed files can invalidate earlier rows. Identify the source set used by the saved artifact before continuing.
A tool choice presented as the architecture. Naming a model, a framework and a database does not specify decisions, stopping conditions or ownership. The state table should remain understandable if those implementation choices change.
Finish with one inspectable workflow
Replace the club notes with your own approved input set and walk all four paths before implementing anything. Keep the state table beside the diagram. A design is ready for implementation when someone else can follow its branches and explain both the output and the reason it stops.
