### Start Local Documentation Server

Source: https://github.com/run-llama/llama-agents/blob/main/docs/api_docs/README.md

Run this command to start a local development server for the documentation. Access it at http://127.0.0.1:8000. Requires uv to be installed.

```bash
uv run mkdocs serve
```

--------------------------------

### Run DBOS durability examples

Source: https://github.com/run-llama/llama-agents/blob/main/examples/dbos/README.md

Commands to execute the quickstart workflow or the multi-replica Postgres-backed workflow.

```bash
# Quickest path — no database required
uv run examples/dbos/server_quickstart.py

# Multi-replica (needs Docker for Postgres)
docker compose -f examples/dbos/docker-compose.yml up -d
uv run examples/dbos/server_replicas.py
```

--------------------------------

### Setup Helm Environment

Source: https://github.com/run-llama/llama-agents/blob/main/charts/AGENTS.md

Commands to prepare the Kubernetes context, install testing tools, and apply required CRDs.

```bash
make -C operator kube-ensure-kind-context
```

```bash
make -C operator helm-unittest-install
```

```bash
make -C operator helm-crds-prom-operator
```

--------------------------------

### Initialize and deploy agents with llamactl

Source: https://github.com/run-llama/llama-agents/blob/main/README.md

Commands to install the CLI, initialize a project, start a local server, and create a deployment.

```bash
uv tool install llamactl
llamactl init
llamactl serve
llamactl deployments create
```

--------------------------------

### Install llama-index-workflows

Source: https://github.com/run-llama/llama-agents/blob/main/examples/eval_driven_prompt_refinement.ipynb

Installs the necessary library for the workflows. Use the `-q` flag for quiet installation.

```bash
!uv pip install llama-index-workflows -q
```

--------------------------------

### Installation

Source: https://github.com/run-llama/llama-agents/blob/main/docs/api_docs/docs/api_reference/index.md

Instructions to install the core Workflows SDK from PyPI.

```APIDOC
## Installation

Install the core Workflows SDK from PyPI:

```bash
pip install llama-index-workflows
```
```

--------------------------------

### Install Dependencies

Source: https://github.com/run-llama/llama-agents/blob/main/examples/server/fastapi_server_example.ipynb

Install the necessary libraries for llama-agents-server and FastAPI.

```bash
%pip install llama-agents-server fastapi
```

--------------------------------

### Install All Dependencies

Source: https://github.com/run-llama/llama-agents/blob/main/architecture-docs/quick-reference.md

Installs all project dependencies, including development extras.

```bash
uv sync --all-packages --all-extras
```

--------------------------------

### Install and Run llamactl

Source: https://github.com/run-llama/llama-agents/blob/main/docs/src/content/docs/llamaagents/llamactl/getting-started.md

Commands to test the CLI without installation or to install it globally using uv.

```bash
uvx llamactl --help
```

```bash
uv tool install -U llamactl
llamactl --help
```

--------------------------------

### Install Dependencies with uv

Source: https://github.com/run-llama/llama-agents/blob/main/docs/api_docs/README.md

Use this command to install project dependencies after cloning the repository. Ensure you have uv installed.

```bash
uv sync
```

--------------------------------

### Install llama-agents-client

Source: https://github.com/run-llama/llama-agents/blob/main/docs/src/content/docs/llamaagents/workflows/client.md

Install the client package via pip.

```bash
pip install llama-agents-client
```

--------------------------------

### Quick Start Commands

Source: https://github.com/run-llama/llama-agents/blob/main/packages/llamactl/README.md

Basic workflow commands to configure, verify, and deploy projects.

```bash
llamactl profile configure
```

```bash
llamactl health
```

```bash
llamactl project create my-project
```

```bash
llamactl deployment create my-deployment --project-name my-project
```

--------------------------------

### Development Setup

Source: https://github.com/run-llama/llama-agents/blob/main/packages/llamactl/README.md

Commands for setting up the development environment for the CLI.

```bash
uv sync
```

```bash
uv run pytest
```

--------------------------------

### Install Llama-Index Workflows

Source: https://github.com/run-llama/llama-agents/blob/main/examples/durable_workflows.ipynb

Install the necessary library for using Llama-Index workflows.

```python
!pip install llama-index-workflows
```

--------------------------------

### Start Development Environment

Source: https://github.com/run-llama/llama-agents/blob/main/architecture-docs/quick-reference.md

Sets up a local Kubernetes cluster (kind) and deploys the necessary resources for development.

```bash
uv run operator/dev.py up
```

--------------------------------

### Install llama-agents-server

Source: https://github.com/run-llama/llama-agents/blob/main/docs/src/content/docs/llamaagents/workflows/deployment.md

Install the workflow server package using pip.

```bash
pip install llama-agents-server
```

--------------------------------

### Install DBOS package

Source: https://github.com/run-llama/llama-agents/blob/main/docs/src/content/docs/llamaagents/workflows/dbos.md

Install the necessary package to enable DBOS-backed durable execution.

```bash
pip install llama-agents-dbos
```

--------------------------------

### Install Workflow Utilities

Source: https://github.com/run-llama/llama-agents/blob/main/docs/src/content/docs/llamaagents/workflows/drawing.md

Install the necessary package to enable workflow visualization features.

```bash
pip install llama-index-utils-workflow
```

--------------------------------

### Install Dependencies

Source: https://github.com/run-llama/llama-agents/blob/main/examples/state_management_with_vector_databases.ipynb

Install the required libraries for workflow management, vector database interaction, and embedding generation.

```bash
%pip install -q llama-index-workflows qdrant-client sentence-transformers openai
```

--------------------------------

### Initialize Llama Agents App Examples

Source: https://github.com/run-llama/llama-agents/blob/main/docs/src/content/docs/llamaagents/llamactl-reference/commands-init.md

Common usage patterns for creating and updating projects via the CLI.

```bash
llamactl init
```

```bash
llamactl init --template basic-ui --dir my-app
```

```bash
llamactl init --template basic-ui --dir ./basic-ui --force
```

```bash
llamactl init --update
```

--------------------------------

### Install llama-agents-server

Source: https://github.com/run-llama/llama-agents/blob/main/examples/server/server_example.ipynb

Install the required package for the WorkflowServer.

```python
%pip install llama-agents-server
```

--------------------------------

### Install llamactl

Source: https://github.com/run-llama/llama-agents/blob/main/packages/llamactl/README.md

Install the CLI tool using standard package managers.

```bash
pip install llamactl
```

```bash
uv add llamactl
```

--------------------------------

### Define and Run a Workflow Server

Source: https://github.com/run-llama/llama-agents/blob/main/packages/llama-agents-server/README.md

Create a server instance, register a workflow, and start the service.

```python
import asyncio
from workflows import Workflow, step
from workflows.context import Context
from workflows.events import Event, StartEvent, StopEvent
from llama_agents.server import WorkflowServer

class StreamEvent(Event):
    sequence: int

class GreetingWorkflow(Workflow):
    @step
    async def greet(self, ctx: Context, ev: StartEvent) -> StopEvent:
        for i in range(3):
            ctx.write_event_to_stream(StreamEvent(sequence=i))
        name = ev.get("name", "World")
        return StopEvent(result=f"Hello, {name}!")

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

if __name__ == "__main__":
    asyncio.run(server.serve("0.0.0.0", 8080))
```

--------------------------------

### Run Workflow Server

Source: https://github.com/run-llama/llama-agents/blob/main/examples/client/README.md

Starts the WorkflowServer using uv. Use this in one terminal.

```bash
uv run examples/client/base/workflow_server.py
```

--------------------------------

### Install Dependencies

Source: https://github.com/run-llama/llama-agents/blob/main/examples/observability/workflows_observablitiy_arize_phoenix.ipynb

Install the necessary packages for Arize Phoenix and LlamaIndex instrumentation.

```python
%pip install arize-phoenix llama-index-workflows llama-index-instrumentation openinference-instrumentation-llama_index
# Optional if using openai or other llama-index packages
%pip install llama-index-llms-openai
```

--------------------------------

### Install required libraries

Source: https://github.com/run-llama/llama-agents/blob/main/examples/document_processing.ipynb

Install the necessary packages for LlamaIndex workflows, LlamaCloud services, and OpenAI.

```bash
%pip install llama-index-workflows llama-cloud-services jsonschema, openai
```

--------------------------------

### Install All Project Dependencies

Source: https://github.com/run-llama/llama-agents/blob/main/CONTRIBUTING.md

Install all dependencies for all packages in the monorepo, including extras, using `uv sync`. This command ensures all necessary packages are available for development.

```bash
uv sync --all-extras --all-packages
```

--------------------------------

### Install Dependencies

Source: https://github.com/run-llama/llama-agents/blob/main/examples/observability/workflow_context_logging.ipynb

Installs the necessary libraries for using Llama Index Dispatcher with workflows and structlog.

```python
%pip install structlog llama-index-workflows
```

--------------------------------

### Workflow Output Example

Source: https://github.com/run-llama/llama-agents/blob/main/examples/document_processing.ipynb

Example output demonstrating the progress and schema proposal steps during a workflow execution, including user interaction for schema approval.

```text
Parsing file: ./qwen3_embed_paper.pdf
Started parsing the file under job_id 9315e44f-6f5e-439f-a088-0e8aeacc1d56
File parsed successfully
Proposing schema
Attempting to parse schema string from:
<schema>
{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "The title of the paper."
    },
    "authors": {
      "type": "array",
      "description": "A list of the authors of the paper.",
      "items": {
        "type": "string"
      }
    },
    "key_takeaways": {
      "type": "array",
      "description": "A list of the main findings or key insights from the paper.",
      "items": {
        "type": "string"
      }
    }
  },
  "required": ["title", "authors", "key_takeaways"]
}
</schema>

Schema proposed successfully
Proposed schema: {'type': 'object', 'properties': {'title': {'type': 'string', 'description': 'The title of the paper.'}, 'authors': {'type': 'array', 'description': 'A list of the authors of the paper.', 'items': {'type': 'string'}}, 'key_takeaways': {'type': 'array', 'description': 'A list of the main findings or key insights from the paper.', 'items': {'type': 'string'}}}, 'required': ['title', 'authors', 'key_takeaways']}
Approved? can you add a section about the datasets used in the paper?
Proposing schema
Attempting to parse schema string from:
<schema>
{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "The title of the paper."
    },
    "authors": {
      "type": "array",
      "description": "A list of the authors of the paper.",
      "items": {
        "type": "string"
      }
    },
    "key_takeaways": {
      "type": "array",
      "description": "A list of the main findings or key insights from the paper.",
      "items": {
        "type": "string"
      }
    },
    "datasets": {
      "type": "array",
      "description": "A list of datasets used in the paper, including synthetic and publicly available datasets.",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "description": "The name of the dataset." },
          "type": { "type": "string", "description": "The type/category of the dataset, e.g. 'synthetic', 'benchmark', 'retrieval', etc." },
          "description": { "type": "string", "description": "A brief description of the dataset and its role in the study." },
          "size": { "type": "string", "description": "Approximate size/count, if available." }
        },
        "required": ["name"]
      }
    }
  },
  "required": ["title", "authors", "key_takeaways", "datasets"]
}
</schema>

Schema proposed successfully
Proposed schema: {'type': 'object', 'properties': {'title': {'type': 'string', 'description': 'The title of the paper.'}, 'authors': {'type': 'array', 'description': 'A list of the authors of the paper.', 'items': {'type': 'string'}}, 'key_takeaways': {'type': 'array', 'description': 'A list of the main findings or key insights from the paper.', 'items': {'type': 'string'}}, 'datasets': {'type': 'array', 'description': 'A list of datasets used in the paper, including synthetic and publicly available datasets.', 'items': {'type': 'object', 'properties': {'name': {'type': 'string', 'description': 'The name of the dataset.'}, 'type': {'type': 'string', 'description': 
```

--------------------------------

### Install Required Packages

Source: https://github.com/run-llama/llama-agents/blob/main/examples/document_agents/finance_triage_agent.ipynb

Installs the necessary libraries for LlamaCloud services, agent workflows, and OpenAI integration. Ensure you have these packages before proceeding.

```python
!pip install llama-cloud-services llama-index-workflows llama-index-llms-openai
```

--------------------------------

### Run Local Development Server

Source: https://github.com/run-llama/llama-agents/blob/main/docs/src/content/docs/llamaagents/llamactl/getting-started.md

Command to start the development server, which manages dependencies, serves workflows, and proxies the frontend.

```bash
llamactl serve
```

--------------------------------

### Configure Project and Workflow

Source: https://github.com/run-llama/llama-agents/blob/main/docs/src/content/docs/llamaagents/llamactl/getting-started.md

Example configuration for pyproject.toml and the corresponding Python workflow definition.

```toml
[project]
name = "my-package"
# ...
[tool.llamaagents.workflows]
my-workflow = "my_package.my_workflow:workflow"

[tool.llamaagents.ui]
directory = "ui"
```

```py
# src/my_package/my_workflow.py
# from workflows import ...
# ...
workflow = MyWorkflow()
```

--------------------------------

### Install Workflow Dependencies

Source: https://github.com/run-llama/llama-agents/blob/main/examples/agent.ipynb

Install the required LlamaIndex workflow and OpenAI LLM packages.

```bash
!pip install llama-index-workflows llama-index-llms-openai
```

--------------------------------

### Install uv

Source: https://github.com/run-llama/llama-agents/blob/main/AGENTS.md

Install the uv package manager required for project dependencies.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

```bash
curl -fsSL https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Install LlamaIndex Workflows SDK

Source: https://github.com/run-llama/llama-agents/blob/main/docs/api_docs/docs/api_reference/index.md

Install the core Workflows SDK from PyPI. This command is used to add the necessary libraries to your Python environment.

```bash
pip install llama-index-workflows
```

--------------------------------

### Initialize Pre-commit Hooks

Source: https://github.com/run-llama/llama-agents/blob/main/CONTRIBUTING.md

Install `pre-commit` hooks to automate linting and formatting. This ensures code quality and consistency across the project.

```bash
uv run pre-commit install
```

--------------------------------

### Install Llama Agents via Helm

Source: https://github.com/run-llama/llama-agents/blob/main/charts/llama-agents/README.md

Perform a fresh installation of the Llama Agents chart with required S3 object storage configuration.

```bash
helm install llama-agents oci://docker.io/llamaindex/llama-agents \
  --set controlPlane.objectStorage.s3.bucket=my-bucket \
  --set controlPlane.objectStorage.s3.region=us-east-1
```

--------------------------------

### Run WorkflowServer and Client Request

Source: https://github.com/run-llama/llama-agents/blob/main/examples/server/README.md

Execute the standalone server example and trigger a workflow via a curl command.

```bash
uv run examples/server/server_example.py
# then in another terminal
curl -X POST http://localhost:8000/workflows/echo/run -d '{"start_event": {"message": "hi"}}'
```

--------------------------------

### Build and Run Docker Container

Source: https://github.com/run-llama/llama-agents/blob/main/examples/docker/README.md

Commands to build the image from the Dockerfile and start the container on port 8000.

```bash
docker build -t workflows-example examples/docker
docker run --rm -p 8000:8000 workflows-example
```

--------------------------------

### Agent Run Output (Response)

Source: https://github.com/run-llama/llama-agents/blob/main/examples/agent.ipynb

Example output displaying the agent's textual response to the user's input.

```text
Output:
assistant: Hello! How can I assist you today?

```

--------------------------------

### Stream Workflow Events Example Request

Source: https://github.com/run-llama/llama-agents/blob/main/docs/src/content/docs/llamaagents/workflows/deployment.md

Example cURL command to stream events from an asynchronously started workflow using the GET /events/{handler_id} endpoint. Customize query parameters like sse, acquire_timeout, include_internal, and include_qualified_name as needed.

```bash
curl http://localhost:80/events/someUniqueId123?sse=false&acquire_timeout=1&include_internal=false&include_qualified_name=true
```

--------------------------------

### Run Agent with Email Input

Source: https://github.com/run-llama/llama-agents/blob/main/examples/document_agents/finance_triage_agent.ipynb

Initializes an EmailReceived object and executes the agent with it as the start event.

```python
email = EmailReceived(
    sender="tuana@runllama.ai",
    subject="Cowork Invoice",
    body="",
    attachment="/content/sb-receipt.png",
)

result = await agent.run(start_event=email)
```

--------------------------------

### Get Deployment Details

Source: https://github.com/run-llama/llama-agents/blob/main/docs/src/content/docs/llamaagents/llamactl-reference/commands-deployments.md

Retrieves details for a specific deployment. By default, it opens a live monitor unless the non-interactive flag is used.

```bash
llamactl deployments get [DEPLOYMENT_ID] [--non-interactive]
```

--------------------------------

### GET /results/{handler_id}

Source: https://github.com/run-llama/llama-agents/blob/main/docs/src/content/docs/llamaagents/workflows/deployment.md

Retrieves the result of a previously started asynchronous workflow run using its handler ID.

```APIDOC
## GET /results/{handler_id}

### Description
Retrieves the result of a previously started asynchronous workflow run. This endpoint only works if the workflow was started with /run-nowait.

### Method
GET

### Endpoint
/results/{handler_id}

### Parameters
#### Path Parameters
- **handler_id** (string) - Required - The unique identifier of the workflow run.

### Response
#### Success Response (200)
- **handler_id** (string) - The handler ID.
- **workflow_name** (string) - Name of the workflow.
- **run_id** (string) - Unique run ID.
- **error** (null|string) - Error message if any.
- **result** (object) - The workflow output.
- **status** (string) - Current status (e.g., completed).
- **started_at** (string) - ISO timestamp.
- **updated_at** (string) - ISO timestamp.
- **completed_at** (string) - ISO timestamp.

#### Accepted Response (202)
Returned when the workflow is still running.

### Response Example
{
  "handler_id": "someUniqueId123",
  "workflow_name": "math_workflow",
  "run_id": "uniqueRunId456",
  "error": null,
  "result": {
    "sum": 15,
    "subtraction": 9,
    "multiplication": 36,
    "division": 4
  },
  "status": "completed",
  "started_at": "2024-10-21T14:32:15.123Z",
  "updated_at": "2024-10-21T14:45:30.456Z",
  "completed_at": "2024-10-21T14:45:30.456Z"
}
```

--------------------------------

### DBOS Runtime Workflow Example

Source: https://github.com/run-llama/llama-agents/blob/main/packages/llama-agents-dbos/README.md

Demonstrates setting up and running a simple workflow with DBOSRuntime and a custom workflow. Ensure DBOS is configured with a system database URL.

```python
import asyncio
from llama_agents.dbos import DBOSRuntime
from dbos import DBOS, DBOSConfig
from workflows import Workflow, step, StartEvent, StopEvent

# Configure DBOS
config: DBOSConfig = {
    "name": "my-app",
    "system_database_url": "postgresql://...",
}
DBOS(config=config)

# Create runtime and workflow
runtime = DBOSRuntime()

class MyWorkflow(Workflow):
    @step
    async def my_step(self, ev: StartEvent) -> StopEvent:
        return StopEvent(result="done")

workflow = MyWorkflow(runtime=runtime)

# launch_sync() works outside async contexts; use await runtime.launch() inside one
runtime.launch_sync()

async def main():
    result = await workflow.run()

asyncio.run(main())
```

--------------------------------

### Initialize and Verify Collection

Source: https://github.com/run-llama/llama-agents/blob/main/examples/state_management_with_vector_databases.ipynb

Instantiate the database client and verify the successful creation of the collection.

```python
qdrant_client = AsyncQdrantClient(":memory:")
model = SentenceTransformer("all-MiniLM-L6-v2")
collection_name = "workflow_collection"
vdb = QdrantVectorDatabase(qdrant_client, model, collection_name)
await vdb.create_collection()
```

```python
await qdrant_client.collection_exists("workflow_collection")
```

--------------------------------

### Run Greeter Workflow (HITL)

Source: https://github.com/run-llama/llama-agents/blob/main/examples/k8s-otel/README.md

Starts the greeter workflow, which requires user input. Send the input using the handler ID obtained from the initial request. Assumes the application is accessible at http://localhost:8080.

```bash
# Start — returns a handler_id
curl -s -X POST http://localhost:8080/workflows/greeter/run-nowait \
  -H 'Content-Type: application/json' -d '{}'
# {"handler_id": "abc123", ...}

# Send user input
curl -s -X POST http://localhost:8080/events/<handler_id> \
  -H 'Content-Type: application/json' \
  -d '{"event": {"type": "UserInput", "value": {"response": "Alice"}}}'

# Get result
curl -s http://localhost:8080/results/<handler_id>
```

--------------------------------

### Download Sample Data with wget

Source: https://github.com/run-llama/llama-agents/blob/main/examples/document_processing.ipynb

Use this command to download a sample PDF file for testing Llama-Agents workflows.

```bash
!wget https://arxiv.org/pdf/2506.05176 -O qwen3_embed_paper.pdf
```

--------------------------------

### Install Workflow Dependencies

Source: https://github.com/run-llama/llama-agents/blob/main/examples/streaming_internal_events.ipynb

Installs the necessary packages for LlamaIndex workflows and cloud services.

```bash
! pip install llama-index-workflows llama-cloud-services llama-index-llms-openai
```

--------------------------------

### Initialize and Start OpenTelemetry Instrumentation

Source: https://github.com/run-llama/llama-agents/blob/main/examples/observability/workflows_observability_pt1.ipynb

Set up a FileSpanExporter to save traces to 'workflow_1.json' and initialize the LlamaIndexOpenTelemetry instrumentor with a service name. Call start_registering() to begin instrumentation.

```python
se_1 = FileSpanExporter(file_path="workflow_1.json")

instrumentor_1 = LlamaIndexOpenTelemetry(
    span_exporter=se_1,
    service_name_or_resource="tracing.a.workflow.1",
)

instrumentor_1.start_registering()
```

--------------------------------

### Install OpenTelemetry Package

Source: https://github.com/run-llama/llama-agents/blob/main/docs/src/content/docs/llamaagents/workflows/observability.md

Install the required package to enable OpenTelemetry support for LlamaIndex workflows.

```bash
pip install llama-index-observability-otel
```

--------------------------------

### Install Observability Dependencies

Source: https://github.com/run-llama/llama-agents/blob/main/examples/feature_walkthrough.ipynb

Installs necessary packages for integrating with observability tools like Arize Phoenix and OpenTelemetry.

```python
%pip install llama-index-instrumentation
%pip install llama-index-core llama-index-llms-openai
%pip install arize-phoenix openinference-instrumentation-llama_index
```

--------------------------------

### Initialize Llama Agents App Usage

Source: https://github.com/run-llama/llama-agents/blob/main/docs/src/content/docs/llamaagents/llamactl-reference/commands-init.md

General syntax for initializing a new project or updating an existing one.

```bash
llamactl init [--template <id>] [--dir <path>] [--force]
llamactl init --update
```

--------------------------------

### Initialize a LlamaAgents Project

Source: https://github.com/run-llama/llama-agents/blob/main/docs/src/content/docs/llamaagents/llamactl/getting-started.md

Command to scaffold a new project using available templates.

```bash
llamactl init
```

--------------------------------

### Install Dependencies for Langfuse and LlamaIndex

Source: https://github.com/run-llama/llama-agents/blob/main/examples/observability/workflows_observablitiy_langfuse.ipynb

Installs necessary packages for Langfuse integration and LlamaIndex workflows. Includes optional packages for LLM integrations.

```python
%pip install langfuse llama-index-workflows openinference-instrumentation-llama_index llama-index-instrumentation

# Optional if using openai or other llama-index packages
%pip install llama-index-llms-openai
```

--------------------------------

### Instantiate and Run a Workflow

Source: https://github.com/run-llama/llama-agents/blob/main/docs/src/content/docs/llamaagents/workflows/index.md

This snippet shows how to instantiate a workflow with optional settings like timeout and verbosity, and then run it asynchronously. Keyword arguments passed to run() become fields of the StartEvent.

```python
w = JokeFlow(timeout=60, verbose=False)
result = await w.run(topic="pirates")
print(str(result))
```

--------------------------------

### Install/Upgrade llama-agents CRDs

Source: https://github.com/run-llama/llama-agents/blob/main/charts/llama-agents-crds/README.md

Use this command to install or upgrade the llama-agents CRD Helm chart. Install this chart before upgrading the main llama-agents chart if CRD schemas have changed.

```bash
helm upgrade --install llama-agents-crds charts/llama-agents-crds
```

--------------------------------

### Install LlamaIndex Instrumentation Dependencies

Source: https://github.com/run-llama/llama-agents/blob/main/examples/observability/workflows_observability_pt1.ipynb

Install the necessary packages for LlamaIndex workflows, instrumentation, OpenAI LLMs, and OpenTelemetry observability. This command ensures all required libraries are available for tracing and instrumentation.

```python
!
```

--------------------------------

### Add an environment

Source: https://github.com/run-llama/llama-agents/blob/main/docs/src/content/docs/llamaagents/llamactl-reference/commands-auth-env.md

Probes the specified server URL and saves the environment configuration.

```bash
llamactl auth env add <API_URL>
```

--------------------------------

### Stream Workflow Events Single Payload Example

Source: https://github.com/run-llama/llama-agents/blob/main/docs/src/content/docs/llamaagents/workflows/deployment.md

A single event payload example received from the /events/{handler_id} endpoint when sse=false. Note that only one reader can stream events per workflow run, and events are not recoverable after streaming.

```json
{
  "value": {"result": 12},
  "qualified_name": "__main__.MathEvent",
  "type": "__main__.MathEvent",
  "types": ["workflows.events.Event", "__main__.MathEvent"]
}
```

--------------------------------

### Manual Deployment with Kubectl

Source: https://github.com/run-llama/llama-agents/blob/main/examples/k8s-otel/README.md

Alternatively, build the Docker image and deploy using kubectl. Port-forwarding is used to access the application and Phoenix UI locally.

```bash
# Build from repo root
docker build -f examples/k8s-otel/Dockerfile -t k8s-otel-app .

# Deploy
kubectl apply -k examples/k8s-otel/k8s/

# Port-forward
kubectl port-forward -n llama-k8s-otel svc/app 8080:8080 &
kubectl port-forward -n llama-k8s-otel svc/phoenix 6006:6006 &
```

--------------------------------

### GET /health

Source: https://github.com/run-llama/llama-agents/blob/main/docs/src/content/docs/llamaagents/workflows/deployment.md

Returns the health status of the WorkflowServer.

```APIDOC
## GET /health

### Description
Returns a health check response.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - The health status of the server.
```

--------------------------------

### Install LlamaIndex and OpenTelemetry Dependencies

Source: https://github.com/run-llama/llama-agents/blob/main/examples/observability/workflows_observability_pt2.ipynb

Install the required libraries for LlamaIndex workflows, instrumentation, OpenAI LLMs, OpenTelemetry observability, Llama Cloud services, managed LlamaIndex indices, and OpenAI embeddings. This command ensures all necessary components are available for tracing and observability.

```python
! pip install -q llama-index-workflows llama-index-instrumentation llama-index-llms-openai llama-index-observability-otel llama-index-cloud-services llama-index-indices-managed-llama-cloud llama-cloud llama-index-embeddings-openai
```

--------------------------------

### GET /events/{handler_id}

Source: https://github.com/run-llama/llama-agents/blob/main/docs/src/content/docs/llamaagents/workflows/deployment.md

Streams events from a running workflow.

```APIDOC
## GET /events/{handler_id}

### Description
Streams all events from a running workflow as newline-delimited JSON or Server-Sent Events.

### Method
GET

### Endpoint
/events/{handler_id}

### Parameters
#### Path Parameters
- **handler_id** (string) - Required - The ID of the workflow handler.

#### Query Parameters
- **sse** (string) - Optional - Set to 'true' for Server-Sent Events, 'false' for NDJSON. Defaults to 'true'.
- **acquire_timeout** (string) - Optional - Timeout for acquiring the lock to iterate over events.
- **include_internal** (string) - Optional - Include internal workflow events if set to 'true'. Defaults to 'false'.
- **include_qualified_name** (string) - Optional - Include the qualified name of the event. Defaults to 'true'.

### Response
#### Success Response (200)
- **value** (object) - The event data.
- **qualified_name** (string) - The qualified name of the event.
- **type** (string) - The type of the event.
- **types** (array) - List of event types.
```

--------------------------------

### Create Kind Cluster and Deploy

Source: https://github.com/run-llama/llama-agents/blob/main/examples/k8s-otel/README.md

Use 'kind' to create a Kubernetes cluster and 'tilt up' to deploy the LlamaIndex Workflows application. Tilt provides a UI for managing resources. Ctrl-C stops Tilt but leaves resources running.

```bash
# Create a kind cluster (one-time setup)
kind create cluster --config examples/k8s-otel/kind-config.yaml

# Deploy
cd examples/k8s-otel
tilt up
```

```bash
tilt down
```

```bash
kind delete cluster --name llama-k8s-otel
```

--------------------------------

### Setup Workflow Class with LLM Instance

Source: https://github.com/run-llama/llama-agents/blob/main/docs/src/content/docs/llamaagents/workflows/index.md

Workflows are implemented by subclassing the `Workflow` class. This snippet shows how to initialize a workflow with a static LLM instance, in this case, an OpenAI model.

```python
class JokeFlow(Workflow):
    llm = OpenAI(model="gpt-4.1")
    ...
```

--------------------------------

### POST /workflows/{name}/run-nowait

Source: https://github.com/run-llama/llama-agents/blob/main/docs/src/content/docs/llamaagents/workflows/deployment.md

Starts the specified workflow asynchronously.

```APIDOC
## POST /workflows/{name}/run-nowait

### Description
Starts the specified workflow asynchronously and returns a handler_id.

### Method
POST

### Endpoint
/workflows/{name}/run-nowait

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the workflow to run.

#### Request Body
- **start_event** (object) - Optional - Serialized representation of a StartEvent.
- **context** (object) - Optional - Serialized representation of the workflow context.
- **handler_id** (string) - Optional - Workflow handler identifier to continue from a previous run.

### Response
#### Success Response (200)
- **handler_id** (string) - Unique identifier for the workflow run.
- **status** (string) - The status of the workflow (e.g., 'started').
```

--------------------------------

### Set Up API Keys

Source: https://github.com/run-llama/llama-agents/blob/main/examples/document_agents/finance_triage_agent.ipynb

Configures the LlamaCloud and OpenAI API keys. It checks if the keys are already set in the environment variables and prompts the user to enter them if they are missing.

```python
import os
from getpass import getpass

if os.getenv("LLAMA_CLOUD_API_KEY") is None:
    os.environ["LLAMA_CLOUD_API_KEY"] = getpass("Enter your LlamaCloud API Key")

if os.getenv("OPENAI_API_KEY") is None:
    os.environ["OPENAI_API_KEY"] = getpass("Enter your OpenAI API Key")
```

--------------------------------

### Run Operator Locally

Source: https://github.com/run-llama/llama-agents/blob/main/operator/AGENTS.md

Start the operator locally; requires a valid kubeconfig.

```bash
make -C operator operator-run
```

--------------------------------

### Workflow Execution Output

Source: https://github.com/run-llama/llama-agents/blob/main/examples/observability/workflows_observablitiy_arize_phoenix.ipynb

Example output generated after running the instrumented workflow.

```text
Output:
This is a custom span
Hello! How can I assist you today?
```

--------------------------------

### Initialize WorkflowClient

Source: https://github.com/run-llama/llama-agents/blob/main/docs/src/content/docs/llamaagents/workflows/client.md

Initialize the client using a base URL or a pre-configured httpx client.

```python
from llama_agents.client import WorkflowClient

client = WorkflowClient(base_url="http://0.0.0.0:8080")
```

```python
import httpx

httpx_client = httpx.AsyncClient(base_url="http://0.0.0.0:8080", headers={"Authorization": "Bearer ..."})
client = WorkflowClient(httpx_client=httpx_client)
```

--------------------------------

### Standard Log Output

Source: https://github.com/run-llama/llama-agents/blob/main/examples/observability/workflow_context_logging.ipynb

Example of standard log output for a processing step.

```text
regular processing step run_id=lBUAX17ywM
```

--------------------------------

### Register events and execute function

Source: https://github.com/run-llama/llama-agents/blob/main/examples/observability/workflows_observability_pt1.ipynb

Starts the registration process and triggers the instrumented function.

```python
instrumentor.start_registering()

example_fn(data="Hello world!")
```

--------------------------------

### Create Deployment CLI Command

Source: https://github.com/run-llama/llama-agents/blob/main/architecture-docs/quick-reference.md

Initiates the creation of a new deployment.

```bash
llamactl deployment create
```

--------------------------------

### Programmatic Workflow Server Setup

Source: https://github.com/run-llama/llama-agents/blob/main/docs/src/content/docs/llamaagents/workflows/deployment.md

Create a WorkflowServer, add workflows, and run it programmatically. This is useful for embedding the server within a larger application. Ensure asyncio is imported and used for running the server.

```python
# my_server.py
import asyncio
from workflows import Workflow, step
from workflows.context import Context
from workflows.events import Event, StartEvent, StopEvent
from llama_agents.server import WorkflowServer


class StreamEvent(Event):
    sequence: int


# Define a simple workflow
class GreetingWorkflow(Workflow):
    @step
    async def greet(self, ctx: Context, ev: StartEvent) -> StopEvent:
        for i in range(3):
            ctx.write_event_to_stream(StreamEvent(sequence=i))
            await asyncio.sleep(0.3)

        name = ev.get("name", "World")
        return StopEvent(result=f"Hello, {name}!")

greet_wf = GreetingWorkflow()


# Create a server instance
server = WorkflowServer()

# Add the workflow to the server
server.add_workflow("greet", greet_wf)

# To run the server programmatically (e.g., from your own script)
# import asyncio
#
# async def main():
#     await server.serve(host="0.0.0.0", port=8080)
#
# if __name__ == "__main__":
#     asyncio.run(main())

```

--------------------------------

### Agent Run Output (ToolCallEvent Loop)

Source: https://github.com/run-llama/llama-agents/blob/main/examples/agent.ipynb

Example output demonstrating the agent's execution flow involving multiple `ToolCallEvent`s, indicating a loop where tools are called and their outputs are processed.

```text
Output:
Running step prepare_chat_history
Step prepare_chat_history produced event InputEvent
Running step handle_llm_input
Step handle_llm_input produced event ToolCallEvent
Running step handle_tool_calls
Step handle_tool_calls produced event InputEvent
Running step handle_llm_input
Step handle_llm_input produced event ToolCallEvent
Running step handle_tool_calls
Step handle_tool_calls produced event InputEvent
Running step handle_llm_input
Step handle_llm_input produced event StopEvent

```

--------------------------------

### Configure OpenTelemetry Integration

Source: https://github.com/run-llama/llama-agents/blob/main/docs/src/content/docs/llamaagents/workflows/observability.md

Initialize the LlamaIndexOpenTelemetry instrumentor to start capturing and exporting traces.

```python
from llama_index.observability.otel import LlamaIndexOpenTelemetry

# Initialize with your span exporter
instrumentor = LlamaIndexOpenTelemetry(
    span_exporter=your_span_exporter,
    service_name_or_resource="your_service_name",
)

# Start registering traces
instrumentor.start_registering()
```

--------------------------------

### File Upload Progress

Source: https://github.com/run-llama/llama-agents/blob/main/examples/document_processing.ipynb

Example output showing the progress of a file upload operation.

```text
Uploading files:   0%|          | 0/1 [00:00<?, ?it/s]
```