Tutorial · Architecture guide
Designing LlamaIndex Workflows with Human Approval
This guide explains how to reason about state, approval, and recovery in a LlamaIndex document workflow. It distinguishes a workflow’s in-process execution from durable application records, and highlights an important limitation in the supplied persistence evaluation: LlamaIndex serialized Context did not resume in a fresh process in the tested setup. Treat that result as a finding about the tested configuration, not a universal statement about every LlamaIndex deployment.
What this guide covers
LlamaIndex is often associated with retrieval-augmented generation, but the verified context describes a broader direction: Agent Document Workflows, or ADW. In the reported description, a workflow can treat a document as part of a larger business process, maintain state across steps, apply business rules, coordinate components, and take actions based on document content. Contract review is one example: a process may extract information, compare it with regulatory requirements, identify potential risks, and prepare recommendations.
This guide focuses on the architecture questions that follow from that kind of multi-step work. What does it mean for a process to retain state? Which information should an application keep independently of the workflow runtime? Where should a human review or approve a consequential result? And what evidence is needed before claiming that a process can recover after a service restart?
It does not provide an executable LlamaIndex or SQLite implementation. The supplied verified sources do not establish the exact APIs, dependency versions, or code needed to build one. Presenting unverified code as a tested tutorial would create a false impression of support. Instead, the steps below give a practical design and verification method that can be applied when implementing a workflow against the documentation for the specific versions in use.
Step 1: Model the work as a document-centered process
Begin with the business task, not with a model call. Write down the document or case being processed, the information that must be extracted, the reference material that must be consulted, the decisions that are allowed, and the outcome that a reviewer or downstream system needs. For a contract-review scenario, the process might include extracting relevant clauses, comparing them with applicable requirements, identifying potential concerns, and preparing a recommendation for an analyst.
This framing reflects the ADW description in the verified context. The document is not merely a prompt supplied to a model. It is part of a broader process in which context and decisions evolve across steps. The workflow may need to preserve which material was examined, what rule was applied, and which result should be reviewed next. Do not assume, however, that the source establishes a specific component layout, API contract, or storage mechanism. Those details need to be confirmed in the documentation for the implementation you choose.
Separate the process into named stages. A useful conceptual outline is intake, extraction, reference review, decision preparation, human review, and completion. Each stage should have an explicit input and expected result. For example, “reference review” should identify the reference material consulted and the questions it is intended to answer. “Decision preparation” should create a reviewable recommendation rather than silently treating a model-generated statement as an approved action.
Finally, define what happens when information is missing or ambiguous. A workflow should be able to stop for clarification or review rather than inventing missing contract terms or treating uncertainty as a positive finding. This is a design requirement for the application; it is not a claim that any particular LlamaIndex workflow enforces it automatically.
Step 2: Separate workflow context from durable business records
Use precise language when describing persistence. A workflow may carry context between steps while it is executing. An application may separately store a case record, document identifier, review status, approval decision, or final recommendation. Those are different things. Saving a business record does not, by itself, prove that an interrupted workflow can be restored at the exact step where it stopped.
The distinction matters because the title “resumable workflow” can mean several different guarantees. It might mean that a user can reopen a case and inspect its last saved result. It might mean that the application can rerun unfinished work from its beginning. Or it might mean that the runtime can restore the complete in-progress execution, including the state needed to continue from a particular step. These guarantees are not interchangeable. State which one your system actually supports.
The supplied persistence study compares several agent frameworks and their persistence mechanisms. Its summary reports that LlamaIndex used serialized Context in the evaluation, and that this tested configuration did not resume in a fresh process. The result is a reason to test the precise recovery behavior you need, not a basis for claiming that every LlamaIndex workflow is incapable of recovery. Equally, it is not evidence that storing application data in SQLite automatically enables runtime restoration.
When designing an application-level record, consider what a person needs to understand and review: the case identifier, the current business status, the relevant input or a secure reference to...
Continue Reading
Log in for free to read the rest of this article and access exclusive AI tools.
Log in / Register