Run flows with LFX

lfx run executes a flow once and streams the results to stdout. No API key is required.

To expose flows as HTTP endpoints instead, see Serve flows with LFX.

Both lfx run and lfx serve accept a .json flow file or a .py Python script.

Prerequisites

• Install LFX

• A flow JSON file. Download the Simple Agent starter flow from the repository:

  curl -o simple-agent-flow.json "https://raw.githubusercontent.com/langflow-ai/langflow/main/src/backend/base/langflow/initial_setup/starter_projects/Simple%20Agent.json"

• The flow's required API keys. The Simple Agent flow uses OpenAI, which requires OPENAI_API_KEY.

Install flow dependencies

uv pip install lfx and uvx lfx install the LFX engine only. Before running a flow, install the extensions that provide the flow's components.

If a component is missing, LFX reports component-not-found with a hint naming the bundle to install, for example:

component-not-found-with-hint: DuckDuckGoSearchComponent not found.
Hint: try ext:duckduckgo:DuckDuckGoSearchComponent@official

Use the bundle name from the hint to find the pip package in the Bundle list.

For more information, see Install LFX with bundle components.

Generate requirements.txt

Extension packages cover component code. Some flows still need additional Python packages at runtime (third-party SDKs imported by those components).

To list them from a flow JSON file, use lfx requirements:

lfx requirements simple-agent-flow.json

Install the reported packages in the same environment before running the flow.

Run a flow

To run a flow from a JSON file, run:

uv run lfx run simple-agent-flow.json "Hello world"

Alternatively, use the --input-value flag:

uv run lfx run simple-agent-flow.json --input-value "Hello world"

Other ways to provide a flow

To run a flow JSON from stdin, run:

cat simple-agent-flow.json | uv run lfx run --stdin \
  --input-value "Hello world" \
  --format json | jq '.result'

To fetch and run a flow from a remote API, run:

curl https://api.example.com/flows/my-agent-flow | uv run lfx run --stdin \
  --input-value "Hello world"

To modify a flow before running it, for example, to change the model to gpt-4o, run:

cat simple-agent-flow.json | jq '(.data.nodes[] | select(.data.node.template.model_name.value) | .data.node.template.model_name.value) = "gpt-4o"' | \
  uv run lfx run --stdin \
  --input-value "Hello world" \
  --format json | jq '.result'

To pass a flow JSON directly as a string argument, run:

uv run lfx run --flow-json '{"data": {"nodes": [...], "edges": [...]}}' \
  --input-value "Hello world"

Run a flow from a Python script

In addition to JSON files, lfx run accepts .py Python scripts that define flows programmatically.

Create a file called simple_agent.py:

"""A simple agent flow example.

Usage:
    uv run lfx run simple_agent.py "How are you?"
"""

import os
from pathlib import Path

from lfx import components as cp
from lfx.graph import Graph
from lfx.log.logger import LogConfig


async def get_graph() -> Graph:
    log_config = LogConfig(
        log_level="INFO",
        log_file=Path("langflow.log"),
    )

    chat_input = cp.ChatInput()
    agent = cp.AgentComponent()
    url_component = cp.URLComponent()
    tools = await url_component.to_toolkit()

    agent.set(
        model_name="gpt-4.1-mini",
        agent_llm="OpenAI",
        api_key=os.getenv("OPENAI_API_KEY"),
        input_value=chat_input.message_response,
        tools=tools,
    )
    chat_output = cp.ChatOutput().set(input_value=agent.message_response)

    return Graph(chat_input, chat_output, log_config=log_config)

Run the flow:

uv run lfx run simple_agent.py "How are you?" --verbose

For more examples, see the Complete Agent Example on PyPI.

lfx run options

Option	Description
--check-variables / --no-check-variables	Validate the flow's global variables and connection references before execution. Default: check.
--flow-json	Load inline JSON flow content as a string.
--format, -f	Output format: json, text, message, or result. Default: json.
--input-value	Input value to pass to the graph. Required with --stdin and --flow-json.
--session-id	Session ID for conversation tracking. Auto-generated if not set.
--stdin	Read JSON flow content from stdin.
--timing	Include detailed timing information in output.
--upgrade-flow	Compatibility mode: check reports issues and fails; safe applies safe upgrades in memory before running.
--verbose, -v	Show basic progress and diagnostic output.
-vv	Show detailed progress and debug information.
-vvv	Show full debugging output including component logs.

Run a flow that uses a connection

A flow can store a connection reference, such as google/work, instead of a credential. With the default resolver, lfx run resolves it from the environment under the key LF_CONNECTION__<PROVIDER>__<NAME>. For actions that require scopes, include the scopes actually granted to the token:

export LF_CONNECTION__GOOGLE__WORK='{"access_token":"ya29.a0-example","scopes":["https://www.googleapis.com/auth/drive.readonly"]}'
uv run lfx run connection_flow.json "describe my connection"

Missing connections

With the default --check-variables, lfx run rejects malformed references and checks for injected values when using the built-in environment resolver. A missing value aborts execution:

Connection 'google/work' could not be resolved. Set LF_CONNECTION__GOOGLE__WORK to a token or credential JSON object.

The message names the key and the expected wire format, never a value. With --no-check-variables the flow starts and fails at the point the component asks for the credential instead. Custom resolvers perform their own lookup and do not require environment keys during pre-flight. Credential expiry and scope checks occur when the lease is resolved.

For the credential wire format, the JSON form that carries expiry and scopes, and how to implement a resolver backed by a secret manager, see Resolve connections in headless LFX.

Control which components load

LFX loads all component categories by default. Use environment variables to restrict which categories are available when loading flows.

Variable	Description
LANGFLOW_​COMPONENT_​CATEGORY_​ALLOWLIST	Comma-separated list of category names to include. If empty, all categories are included.
LANGFLOW_​COMPONENT_​CATEGORY_​BLOCKLIST	Comma-separated list of category names to exclude. Applied after the allowlist.

Category names are case-insensitive. The virtual keyword core in the allowlist or blocklist expands to all core component categories.

Component category names don't always match the labels displayed in the Langflow visual editor. To view the component categories, see Bundle list.

To restrict components to specific categories:

export LANGFLOW_COMPONENT_CATEGORY_ALLOWLIST="openai,anthropic,processing,input_output"
uv run lfx serve my_flow.json

To exclude specific categories:

export LANGFLOW_COMPONENT_CATEGORY_BLOCKLIST="prototypes,langchain_utilities"
uv run lfx run my_flow.json "Hello"

To allow only core categories:

export LANGFLOW_COMPONENT_CATEGORY_ALLOWLIST="core"
uv run lfx serve my_flow.json

See also

• Serve flows with LFX
• Resolve connections in headless LFX
• About LFX
• Install LFX
• Flow DevOps Toolkit SDK
• Extensions overview