🚀 Technical Briefing: This tutorial is part of our deep-dive series on Agentic Workflows at Gate of AI. For the full technical breakdown, interactive code sandbox, and the native Arabic translation, visit the original article here.
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 it, the current result, and the decision history. Select a storage design only after checking the operational and security requirements of your environment. The provided sources do not specify a SQLite schema, transaction strategy, or suitable data-retention policy, so those choices must be independently designed and tested.
Step 3: Make approval a business decision
Human approval is most useful when it is attached to a defined decision, not added as a vague final checkbox. Identify which results require review, who is permitted to review them, what information the reviewer sees, and what the system is allowed to do before approval. A contract recommendation, for instance, can be presented as a proposal for an analyst rather than treated as a final legal determination.
Keep the distinction between recommendation and authorization explicit in the interface and stored business record. The model may prepare a summary or identify a potential issue; the designated reviewer makes the approval decision under the organization's process. Record enough information to explain the decision later, subject to the organization's privacy and retention requirements. This is an application-design recommendation, not a verified built-in LlamaIndex approval feature.
Define the possible outcomes before implementing the review step. A reviewer might approve the proposed next step, reject it, or request additional information. Make each outcome unambiguous to the rest of the process. Avoid language that suggests an external action has happened merely because a recommendation was generated or approved. If a downstream action is part of the product, verify separately how it is authorized, executed, and reported.
Approval policies should be based on business rules that the organization can explain. The verified ADW report specifically mentions applying business rules as part of a broader document process. It does not provide a policy engine or prescribe particular approval thresholds. Define thresholds and reviewer responsibilities with the relevant domain owners instead of presenting arbitrary example rules as universal guidance.
Step 4: Design and test recovery honestly
Before describing a service as resumable, write a recovery specification. State what information survives a process exit, what work can be continued, what work must be repeated, and how the service avoids confusing a partial result with a completed result. Then test those claims by interrupting the service at relevant points and starting it again in a fresh process.
At a minimum, distinguish three recovery outcomes. First, the application may be able to display the last saved business status. Second, it may be able to restart processing from an earlier safe boundary. Third, it may be able to restore the workflow runtime's in-progress state and continue from the interrupted step. A system can provide one outcome without providing the others. Document which outcome you have tested; do not use “checkpoint” as a synonym for all of them.
Include cases where interruption happens before any result is stored, after an intermediate result is recorded, and after a reviewer has made a decision. Check that a restart does not silently mark incomplete work as complete, discard a review decision, or repeat a consequential operation without an explicit policy. The exact test harness and persistence API depend on the LlamaIndex version and application architecture, which the supplied sources do not specify.
The persistence evaluation is useful background, but it is not a substitute for your own verification. Its summary describes a cross-framework study and gives a specific fresh-process result for the tested LlamaIndex configuration. Your system may use a different design, but you should be able to demonstrate its behavior with a reproducible test and describe the boundary of that evidence.
Step 5: Treat document handling as a sequence of accountable stages
The ADW example in the verified context describes documents as part of broader business processes. In the contract-review illustration, a process may extract information from documents, cross-reference regulatory requirements, identify risks, and prepare recommendations. This is a useful model for designing stages, but it is not a guarantee that a particular workflow will make accurate legal or regulatory judgments.
For each stage, specify what information it receives and what it is expected to produce. Keep claims grounded in the supplied document and reference material. If the output is a recommendation, label it as one. If a required source was not consulted, do not imply that the process completed a comprehensive comparison. Reviewers need to know not only the conclusion but also what the process actually examined.
Where business rules apply, make them visible in the process design and test them independently. The source describes ADW as able to apply business rules and coordinate components, but does not enumerate specific rules or establish a particular enforcement mechanism. Do not infer that a model-generated answer is itself a rule check. Define the rule, determine how the application verifies it, and record the outcome in a way that is meaningful to the human reviewer.
Keep the first implementation narrow. Select one document type and one well-defined review outcome. Validate that the workflow can preserve the context required by later stages and that a reviewer can understand the result. Expand to more document types or decisions only after the behavior and recovery boundary are clear.
Step 6: Evaluate the system before describing it as reliable
Evaluation should cover both the content produced and the lifecycle around it. For content, assemble representative examples and have qualified reviewers assess whether the extracted information and recommendations are useful for the intended task. For lifecycle behavior, test that the application represents incomplete work accurately, preserves review decisions as intended, and behaves predictably after an interruption.
Do not reduce the evaluation to a single accuracy percentage unless the measurement has a clear definition and a suitable test set. The verified persistence study reports several storage-related measures, including retained storage, composition, duplication, growth behavior, compressibility, and whether retained bytes reconstruct the history behind a step. Those measures illustrate that persistence has more than one dimension. They are not a performance guarantee for a particular application or a claim about the quality of its recommendations.
Track what your own tests actually establish. For example, a successful test that reloads a saved case record establishes that the record was available after the test restart. It does not establish that the framework restored an in-flight workflow. A test that reruns a process from its beginning establishes retry behavior under that test, not exact step-by-step continuation. Use precise descriptions in technical documentation and product claims.
Include reviewers who understand the relevant domain when evaluating consequential recommendations. A technically valid workflow can still produce an unsuitable business result. For contract review, qualified analysts should assess whether the output is useful and whether uncertainty is communicated appropriately. The sources provide an illustrative use case, not a benchmark proving that ADW replaces expert review.
Common mistakes to avoid
- Calling application records workflow checkpoints. A saved case or audit record may be valuable, but it does not prove restoration of the workflow runtime.
- Overgeneralizing one evaluation result. The cited fresh-process result applies to the tested LlamaIndex configuration described by the study; do not treat it as a verdict on every possible implementation.
- Equating a recommendation with an authorized action. Keep proposal, review, approval, and completion distinct in the business process.
- Claiming unsupported API behavior. Confirm exact APIs and version compatibility against authoritative documentation before publishing executable code.
- Promising production readiness without evidence. State what has been tested, what recovery behavior is available, and what remains a design assumption.
Key takeaways
LlamaIndex Agent Document Workflows are described in the verified context as a way to handle document-centered processes beyond simple extraction or matching, including maintaining state across steps, applying business rules, coordinating components, and taking actions based on document content. That description supports discussing broader workflow design; it does not verify a particular SQLite checkpoint implementation.
Keep application-level business state separate from framework-level workflow restoration. The persistence study reports that LlamaIndex serialized Context did not resume in a fresh process in its tested setup, so recovery claims need a clearly defined scope and direct testing. Design human review around explicit business decisions, and describe recommendations, approvals, and completed work accurately.
This article is an architecture guide rather than a copy-and-run tutorial. Before publishing an implementation, validate its APIs, dependencies, recovery behavior, and tests against authoritative documentation for the exact versions deployed. Editorial attribution: Gate of AI Editorial & Engineering Teams, GateOfAI, LLC, a Delaware, USA company.
Sources and scope
- VentureBeat: LlamaIndex goes beyond RAG so agents can make complex decisions — reporting on Agent Document Workflows and the contract-review example.
- The Hidden Footprint: Making Storage a First-Class Metric for LLM Agent Evaluation — persistence evaluation summary, including the tested fresh-process result for LlamaIndex serialized Context.
Top comments (0)