LlamaAgents Documentation

LlamaAgents is an open-source Python framework designed for building and shipping document-centric agents. It is built on Agent Workflows, an event-driven orchestration library where workflow steps are asynchronous Python functions that emit and consume events. This allows for branching, looping, parallelization, state persistence, and failure recovery using plain Python without a Domain Specific Language (DSL).

Key capabilities include:

• Orchestration: Manage complex document pipelines (OCR, LLMs, extraction, validation, human review).
• Flexibility: Use it as a library in notebooks/scripts, mount it as a REST API in existing apps, or deploy it as a standalone agent.
• Integration: Works seamlessly with LlamaParse for heavy document primitives like OCR and structured extraction.

The examples/dbos/ directory contains several patterns for using DBOS for durable workflows:

• server_quickstart.py: The simplest WorkflowServer setup using SQLite. Recommended starting point.
• durable_workflow.py: Demonstrates checkpointing without a server. It features a looping counter that can be interrupted (Ctrl+C) and resumed using the --resume flag.
• server_replicas.py: Demonstrates two WorkflowServer replicas sharing a Postgres event store. Requires Docker.
• idle_release_demo.py: Demonstrates how long-idle workflows are released from memory and automatically resumed upon receiving a new event.
• _replica.py: An internal single-replica server process used by the multi-replica example.

LlamaAgents provides multiple ways to trace and inspect workflow runs. You can use the built-in context logger for structured logging tied to specific runs, or integrate with third-party observability platforms to visualize traces.

For beginners, it is recommended to start with the basic instrumentation and event stream reading patterns before moving to advanced patterns like custom spans or nested workflow timing.

The llama-agents-control-plane provides the API surface required to manage LlamaAgents deployments and projects. It serves as the central management layer for orchestrating agentic workflows and infrastructure.

For a complete end-to-end introduction on how to use LlamaAgents, refer to the Getting started with LlamaAgents guide.

The llama-agents-client provides the following capabilities:

• Execution Modes: Run workflows both synchronously and asynchronously.
• Real-time Streaming: Stream events in real-time as a workflow executes.
• Human-in-the-loop: Support for injecting events into running workflows via the send_event method.
• Custom Transport: Ability to provide your own httpx.AsyncClient to configure custom authentication, headers, or transport layers.

The LlamaAgents Server provides the following capabilities:

• REST API: For running, streaming, and managing workflows.
• Debugger UI: Automatically mounted at / for visualizing and debugging workflows.
• Event Streaming: Supports newline-delimited JSON or Server-Sent Events (SSE).
• Human-in-the-loop: Support for interactive workflows.
• Persistence: Built-in SQLite store is provided by default, but you can implement your own storage using AbstractWorkflowStore.

Runtimes in LlamaAgents are composed using a decoration pattern. A WorkflowServer assembles a default chain of decorators on top of a provided base runtime. Each decorator wraps the inner runtime and its adapters, overriding only the specific methods required to implement a concern.

Customizing the Base Runtime

You can swap the base runtime by passing the runtime= argument to WorkflowServer. Supported base runtimes include BasicRuntime, DBOSRuntime, or your own custom implementation.

Writing a Custom Decorator

To create a new decorator, extend BaseRuntimeDecorator. You can also optionally extend BaseInternalRunAdapterDecorator or BaseExternalRunAdapterDecorator. These base classes forward all methods to the inner runtime/adapter, allowing you to focus only on the logic you wish to intercept or add.

LlamaAgents uses the WorkflowStore as a write-ahead log and subscription source to provide resumable event streaming to clients via Server-Sent Events (SSE).

How Resumption Works

1. Sequence Numbers: The store assigns a monotonic sequence number to every event.
2. Client Tracking: Clients receive events with an id field containing the sequence number.
3. Reconnection: If a client disconnects, it should reconnect using the Last-Event-ID HTTP header containing the last seen sequence number.
4. Replay: The _WorkflowAPI calls subscribe_events(after_sequence=cursor) to replay all missed events from the store before continuing with live updates.

The "now" Cursor

To skip all historical events and only receive new events upon connection, use the special "now" cursor.

DBOS operates as a local runtime with database coordination. Unlike distributed step workers, a DBOS workflow and all its constituent steps execute within the same process. Coordination between different replicas is achieved through a shared Postgres database using tables and pg_notify.

Key architectural components include:

• WorkflowServer: The top-level container.
• DBOSRuntime: Manages the execution, containing an InternalAdapter (for the workflow control loop) and an ExternalAdapter (for receiving external HTTP/service calls).
• Shared Postgres: The source of truth for coordination, event delivery, and state.