LlamaIndex vs. LangGraph: Agentic orchestration (2026)

When an agent needs branches, retries, persistent state, or human approval, plain Python control flow can become difficult to maintain. LlamaIndex vs. LangGraph is a common comparison at that point. LlamaIndex Workflows routes typed events between asynchronous steps, while LangGraph connects nodes and edges over a shared state object.

This comparison examines their programming models, state, persistence, human review, observability, ecosystems, and managed deployment options. It also explains where document parsing belongs in the architecture when an agent processes PDFs or scans.

What LlamaIndex Workflows and LangGraph do

Both are orchestration frameworks for agentic systems. They run multiple steps, retain state across those steps, branch and loop as needed, and call tools or large language models (LLMs). LlamaIndex Workflows(opens in a new tab) uses typed events to connect steps. LangGraph(opens in a new tab), from the LangChain team, uses nodes and edges while its runtime passes state through the graph.

Neither framework is a document parser. LlamaIndex offers retrieval and parsing products elsewhere in its ecosystem, but Workflows itself controls execution. LangGraph similarly coordinates whichever retrievers, parsers, models, and tools an application supplies.

A framework may be unnecessary for a short, linear process with a few function calls. Workflows and LangGraph become more useful when branching, cycles, persistence, and human review make ordinary control flow difficult to inspect or resume.

The frameworks at a glance

Programming model: Events vs. graph

The main difference is how each framework expresses control. LangGraph declares nodes and edges before execution, so the overall state machine can be inspected and rendered. LlamaIndex Workflows determines routing from the event types that steps emit and consume. That model maps naturally to asynchronous fan-out and fan-in, although the complete path is less visible in one place.

Install llama-index-workflows or langgraph before running the matching example. Both snippets implement the same retry rule: Short document text receives additional context once before the workflow returns it. The example is deliberately deterministic so the orchestration difference remains visible.

LlamaIndex Workflows:

import asyncio

from workflows import Workflow, step
from workflows.events import Event, StartEvent, StopEvent


class DraftEvent(Event):
    text: str
    retries: int


class RetryEvent(Event):
    text: str
    retries: int


class ReviewWorkflow(Workflow):
    @step
    async def prepare(self, ev: StartEvent | RetryEvent) -> DraftEvent:
        if isinstance(ev, StartEvent):
            return DraftEvent(text=ev.get("document_text").strip(), retries=0)

        return DraftEvent(
            text=f"{ev.text} Verified against the source document.",
            retries=ev.retries,
        )

    @step
    async def review(self, ev: DraftEvent) -> RetryEvent | StopEvent:
        if len(ev.text) < 50 and ev.retries < 1:
            return RetryEvent(text=ev.text, retries=ev.retries + 1)

        return StopEvent(result=ev.text)


async def main() -> None:
    workflow = ReviewWorkflow(timeout=10)
    result = await workflow.run(document_text="Invoice total: $125")
    print(result)


if __name__ == "__main__":
    asyncio.run(main())

RetryEvent sends execution back to prepare. The runtime infers that route from the step annotations.

LangGraph:

from typing import Literal

from typing_extensions import TypedDict
from langgraph.graph import END, START, StateGraph


class State(TypedDict):
    document_text: str
    retries: int


def prepare(state: State) -> dict:
    text = state["document_text"].strip()
    if state["retries"] > 0:
        text = f"{text} Verified against the source document."
    return {"document_text": text}


def route(state: State) -> Literal["retry", "done"]:
    if len(state["document_text"]) < 50 and state["retries"] < 1:
        return "retry"
    return "done"


def retry(state: State) -> dict:
    return {"retries": state["retries"] + 1}


builder = StateGraph(State)
builder.add_node("prepare", prepare)
builder.add_node("retry", retry)
builder.add_edge(START, "prepare")
builder.add_conditional_edges(
    "prepare",
    route,
    {"retry": "retry", "done": END},
)
builder.add_edge("retry", "prepare")
graph = builder.compile()

result = graph.invoke({"document_text": "Invoice total: $125", "retries": 0})
print(result["document_text"])

LangGraph declares the retry path as a conditional edge and stores the retry count in shared state. The code is longer, but the cycle is visible before the graph runs.

State and persistence

LangGraph makes state explicit. Each node receives the current state and returns updates. Compiling a graph with a checkpointer saves state at step boundaries, enabling resumable execution, memory, human review, fault recovery, and time travel. LangGraph’s persistence documentation(opens in a new tab) explains which features require a checkpointer.

LlamaIndex Workflows carries data on events and stores shared per-run values in Context. Workflows are ephemeral by default. A process can serialize Context, restore it later, and continue the run. For automatic recovery, the framework also supports runtime plugins such as its DBOS integration. See the official guide to durable Workflows(opens in a new tab).

LangGraph therefore provides the more integrated persistence model, while Workflows offers manual snapshots and optional runtime-backed durability.

Control flow and human review

Agentic systems commonly need retries, routing, parallel work, and pauses for approval. Both frameworks support these patterns.

LangGraph represents routes with edges and pauses execution with interrupt(). A checkpointer preserves state so a run can resume after a person responds. LlamaIndex Workflows expresses routes through event types and uses input-required and human-response events to pause and continue execution. LangGraph is the more direct fit when durable approval steps are central to the application. Workflows is attractive when events already match the application’s architecture.

Observability and debugging

LangGraph integrates with LangSmith for step-level tracing and can render the graph. Its checkpointer enables time travel(opens in a new tab), which can replay or fork execution from a previous checkpoint. Nodes after that checkpoint run again, including model and API calls.

LlamaIndex Workflows provides instrumentation hooks and workflow visualization. It can integrate with OpenTelemetry-compatible tools through LlamaIndex instrumentation. Existing observability infrastructure may matter more than small differences between the two frameworks.

Ecosystem and integrations

Workflows is available through the standalone llama-index-workflows package and is also reexported by llama-index-core. That makes it convenient for applications already using LlamaIndex retrieval or indexing, without requiring the rest of the framework for standalone use.

LangGraph can also run without LangChain, although it integrates closely with LangChain models, tools, and LangSmith. The better ecosystem fit usually depends on which retrievers, model clients, tracing tools, and deployment services the application already uses.

Pricing and managed deployment

Both open source libraries use the MIT license and can be self-hosted without a framework license fee. Infrastructure, model calls, vector storage, and external tools still carry their own costs.

LangSmith has a free Developer plan for observability, but that plan doesn’t include Deployment. The paid Plus plan includes one small serverless deployment, with additional usage billed separately. See LangSmith pricing(opens in a new tab) for current details.

Using LlamaIndex and LangGraph together

The frameworks can be combined. For example, a LangGraph node can call a LlamaIndex query engine as a tool. LlamaIndex then handles retrieval while LangGraph controls the broader workflow. This arrangement is useful when an application needs LlamaIndex retrieval and LangGraph’s explicit state machine.

The document parsing layer

Document parsing is separate from orchestration. If a parser drops a table column or returns text in the wrong reading order, the error can affect retrieval, tool calls, and the final answer. A workflow can retry a failed operation, but it can’t reconstruct source content it never received.

For document agents, evaluate parsing quality independently before deciding that the orchestrator caused an inaccurate result. The parsing guide explains how structured spatial output preserves tables, coordinates, confidence, and page context.

When to choose each

Choose LangGraph when:

• The application needs an explicit, inspectable graph for a multistep or multiagent process.
• Durable execution, checkpointing, and fault recovery are central requirements.
• Human approval must pause a run and resume it from saved state.
• The stack already uses LangChain or LangSmith.

Choose LlamaIndex Workflows when:

• The application benefits from event-driven, asynchronous orchestration.
• Retrieval and indexing already use LlamaIndex.
• Manual context snapshots or an optional durability plugin meet persistence requirements.
• The team prefers ordinary Python branching inside typed workflow steps.

Consider both when:

• LlamaIndex retrieval should run inside a broader LangGraph state machine.

Is LlamaIndex better than LangGraph?

Neither framework is universally better. LangGraph provides an explicit state machine and an integrated checkpointing model. LlamaIndex Workflows provides event-driven orchestration with straightforward access to the LlamaIndex ecosystem. Choose based on the control model, persistence requirements, and tools the application already uses.

Where Nutrient fits

Nutrient Data Extraction API is a document processing service, not an orchestration framework. It parses PDFs, scans, images, and Office files before their content enters a LlamaIndex Workflows or LangGraph application.

Spatial parsing returns typed document elements with page references, coordinates, and detection confidence. Understanding-mode extraction uses AI and is probabilistic. Those source details let an application validate uncertain results and route them for review instead of treating every output as deterministic.

The following request returns spatial document elements:

import requests

with open("document.pdf", "rb") as document:
    response = requests.post(
        "https://api.nutrient.io/extraction/parse",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        files={"file": document},
        data={
            "instructions": '{"mode":"understand","output":{"format":"spatial"}}'
        },
        timeout=60,
    )

response.raise_for_status()
print(response.json())

The RAG ingestion guide shows how to pass parsed output into a retrieval pipeline. For schema-based fields rather than whole-document elements, use the Data Extraction API’s extract endpoint.

Conclusion

Choose LangGraph when the workflow needs an explicit graph, integrated checkpointing, and durable human review. Choose LlamaIndex Workflows when typed events and asynchronous steps fit the application better, particularly alongside LlamaIndex retrieval. If both models are useful, LlamaIndex retrieval can run as a tool inside a LangGraph node.

FAQ