Llama Agents: event-driven workflows for document-heavy agent pipelines

The problem Llama Agents targets: heavy document steps that do not want to be microservices

The README is unusually direct about the workload it was written for. Document pipelines stitch together OCR, LLM calls, structured extraction, classification, custom validation and human review. The steps are slow, the payloads are heavy, and much of the work is in-process Python: embedding models, image analysis, vision calls, heuristics that nobody wants to expose as a separate service. The stated consequence is that teams end up with a side process that other systems cannot integrate with.

That framing matters because it rules out a large part of the agent-framework market. If your steps are thin API calls, the cost of a distributed orchestrator is low and the benefit is high. If your steps load a model into memory, move that step across a network boundary and you have made the system slower and harder to debug. Llama Agents takes the second case as the default and keeps the step in process.

The audience is therefore Python engineers building document agents, not teams assembling chat assistants from third-party tools. The README says the framework is for building and shipping document-centric agents in Python, and the examples directory backs this up with document_agents and document_processing notebooks alongside server, client, dbos, docker, observability and k8s-otel folders.

How Agent Workflows executes steps: events in, events out, no DSL

The mechanism is stated plainly: steps are async Python functions that emit and consume events. Branching, looping, parallel execution, state persistence and failure recovery are expressed in Python rather than in a separate graph language. A workflow class subclasses Workflow, each unit of work is decorated with @step, and the type annotations on the function signature determine which events it receives and which it returns.

The README example makes the data flow concrete: a step takes a StartEvent and returns a StopEvent, and the return value of StopEvent becomes the workflow result. Between those two ends, intermediate event classes carry data from one step to the next, which is how branching and fan-out are expressed without a scheduler configuration file.

This is a real design commitment, not a marketing line. Because the graph is the Python call graph, you get type checking and editor navigation for free, and you can unit test a step by constructing its input event. The cost is that there is no serialized workflow definition to inspect or diff, so tooling that expects a declarative graph has nothing to read. The repository does include a visualization example, but the README does not describe a visual authoring format.

Durability is described as pluggable. The README says runs can be saved and resumed from a file or connected to a database, and the examples directory contains durable_workflows.ipynb and a dbos folder, which points at persistence being an integration rather than a fixed backend.

Installing llama-index-workflows and running a first workflow

The README gives the library path as the simplest one: install the package with pip and await the workflow's run method. The README does not state a minimum Python version for the package itself, though the monorepo pyproject.toml sets requires-python to >=3.10 for the workspace.

pip install llama-index-workflows

The README's own example defines a workflow with a single step that transforms a StartEvent into a StopEvent. Note that the step reads ev.name, so the start event has to be constructed with a name field.

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

class HelloWorkflow(Workflow):
    @step
    async def greet(self, ev: StartEvent) -> StopEvent:
        return StopEvent(result=f"Hello, {ev.name}")

Running it is an await on workflow.run, passing the start event. What you should see is the StopEvent's result string, in this case the greeting built from the name you passed in. The import path in the README is workflows, not llama_index.workflows, which is worth noting because the PyPI distribution name and the import name differ.

The README points at the packages/llama-index-workflows directory for more detail, and the examples directory for further patterns. It does not document a CLI for the library path; the CLI arrives with llamactl.

Wrapping a workflow as a REST service with llama-agents-server

The second path in the README is mounting a workflow inside an app you already have. The llama-agents-server package wraps a workflow as a REST API with streaming, persistence and human-in-the-loop support, and the README says it can be dropped into an existing Starlette or FastAPI app or run standalone. The matching llama-agents-client package is described as an async client for calling workflows from other services.

The README's example is three lines: construct a WorkflowServer, then register a workflow instance under a name.

from llama_agents.server import WorkflowServer

server = WorkflowServer()
server.add_workflow("greet", HelloWorkflow())

What this buys you is the boundary between the in-process step and everything else. The heavy Python stays where it is; the HTTP surface, streaming and persistence come from the server package. The README does not spell out the route paths, port or environment variables in the excerpt available here, so check the packages/llama-agents-server directory and the deployment documentation before wiring a client to it.

One thing the README does not address is authentication or multi-tenancy. For a server that exposes workflow execution over HTTP, that is a gap worth investigating directly in the package source rather than assuming it is handled.

llamactl, deployment targets and the CLI path

The third path is the CLI. The README says llamactl is for building and deploying agent apps end to end: initialize from a starter, develop locally with hot reload, then deploy to LlamaParse, AWS Bedrock AgentCore or your own infrastructure. Agents can be headless workflow services, MCP servers, or full-stack apps with a UI.

The README gives four commands in sequence, and they are the ones to copy exactly.

uv tool install llamactl
llamactl init
llamactl serve
llamactl deployments create

llamactl init scaffolds from a starter, llamactl serve runs the app locally with hot reload, and llamactl deployments create pushes it to a target. The README does not document rollback, versioning of deployed agents, or how a deployment is torn down, so treat those as open questions until the llamactl package documentation answers them.

The deployable-agent path is also where the LlamaParse relationship becomes explicit. The README positions LlamaParse as the home for OCR, structured extraction, classification and splitting, with those plugged into a workflow as steps. That is a commercial dependency in the middle of an otherwise MIT-licensed stack, and it is the clearest example of where the open source boundary sits.

Where Llama Agents is the wrong choice

The README's own framing is the first limitation. It is a library at its core, and the server and CLI are layers on top. If your team wants a declarative graph definition that a platform team can review, diff and deploy independently of application code, this design works against you: the workflow is Python, so the graph only exists at runtime.

Second, the document-heavy assumption cuts both ways. The framework is optimized for slow steps with large payloads that stay in process. For a pipeline of fifteen fast API calls, the event-driven step model adds ceremony without removing a bottleneck, and a simpler async function or a task queue would be easier to operate.

Third, the deployment story is multi-target and therefore multi-surface. The README names LlamaParse, AWS Bedrock AgentCore and your own infrastructure as destinations. Each has its own operational model, and the README excerpt does not describe a common abstraction over them. Teams that need one well-trodden deployment path should verify how much of the llamactl path is provider-specific before standardizing on it.

Finally, the repository is a monorepo with many packages. The top-level pyproject.toml lists basedpyright environments for llama-index-workflows, llama-agents-client, llama-agents-server, llama-index-utils-workflow, llama-agents-core, llama-agents-control-plane, llama-agents-appserver, llamactl and llama-agents-agentcore. The README only walks through three of those surfaces, so the dependency graph is wider than the front page suggests.

Llama Agents compared with LangGraph

The comparison people search for is against LangGraph, and the difference is structural rather than cosmetic. LangGraph's model is a graph of nodes and edges that you construct explicitly, which gives you a serializable topology you can render, checkpoint against and reason about as a diagram. Llama Agents inverts this: the topology is the Python call graph, and control flow is expressed through which events a step emits and which events it declares it consumes.

The practical consequences run in both directions. With Llama Agents, a step is a normal async function, so existing type checkers, test runners and debuggers apply without a framework-specific layer, and the README's claim that there is no DSL is accurate in the sense that you never leave Python. With LangGraph, the graph is data, which makes it easier to build generic tooling on top, including the kind of visual inspection that a runtime-only topology cannot offer.

Durability is where the two converge more than they differ. The README describes persistence as pluggable for Llama Agents, with runs saved and resumed from a file or a database. LangGraph likewise treats checkpointing as a backend concern. The choice is therefore less about durability and more about whether you want the control flow to be inspectable outside the process.

Maintenance, licensing and the cost of keeping up

The repository is not archived, and the last push was on 2026-09-14. Releases are frequent and independently versioned: llama-agents-client@0.3.13 on 2026-09-10, llama-index-workflows@2.23.3 on 2026-08-22, and llama-agents-server@v0.7.1 on 2026-08-22. The client, the workflow library and the server move on separate version cadences, which is the main upgrade cost to plan for. Pinning each package separately and reading the release notes per package is the realistic approach; a single version number for the whole stack does not exist.

The repository uses Changesets for versioning, visible in package.json with a version script that runs a dev CLI and a publish script that takes a tag, plus a .changeset directory at the top level. That is a signal that releases are generated from recorded changes rather than hand-edited, which tends to produce readable changelogs.

Licensing is MIT, stated in both the README and the workspace pyproject.toml. MIT is permissive and imposes no source-disclosure obligation on your own code. The caveat is not legal but architectural: the README recommends LlamaParse for OCR, structured extraction, classification and splitting, and LlamaParse is a commercial cloud service. Nothing forces you to use it, since those are just steps in a workflow, but the recommended path for document understanding leads to a paid dependency. Confirm your own compliance obligations with counsel; this is not legal advice.

Editorial conclusion

Adopt Llama Agents if your document pipeline is already async Python and you want durability, a REST surface and deployment without rewriting the steps. Do not adopt it if you expect a declarative graph DSL, a visual editor or a hosted control plane out of the box: the README describes a library first, with server and CLI layered on top. Before committing, verify which of the packages you actually need, because the README names several (llama-index-workflows, llama-agents-server, llama-agents-client, llamactl) and the top-level pyproject.toml lists more package directories than the README documents.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. run-llama/llama-agents on GitHub