langflow Documentation

Technical Documentation: langflow-ai/langflow

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (README.md) Copy Section

Langflow is a powerful platform for building and deploying AI-powered agents and workflows. It provides developers with both a visual authoring experience and built-in API and MCP servers that turn every workflow into a tool that can be integrated into applications built on any framework or stack. Langflow comes with batteries included and supports all major LLMs, vector databases and a growing library of AI tools.

✨ Highlight features Copy Chapter

• Visual builder interface to quickly get started and iterate.
• Source code access lets you customize any component using Python.
• Interactive playground to immediately test and refine your flows with step-by-step control.
• Multi-agent orchestration with conversation management and retrieval.
• Deploy as an API or export as JSON for Python apps.
• Deploy as an MCP server and turn your flows into tools for MCP clients.
• Observability with LangSmith, LangFuse and other integrations.
• Enterprise-ready security and scalability.

🖥️ Langflow Desktop Copy Chapter

Langflow Desktop is the easiest way to get started with Langflow. All dependencies are included, so you don't need to manage Python environments or install packages manually.
Available for Windows and macOS.

📥 Download Langflow Desktop

⚡️ Quickstart Copy Chapter

Install locally (recommended) Copy Section

Requires Python 3.10–3.14 and uv (recommended package manager).

Install

From a fresh directory, run:

uv pip install langflow -U

The latest Langflow package is installed.
For more information, see Install and run the Langflow OSS Python package.

Run

Official release packages and tagged source archives disable automatic login by default. Set LANGFLOW_SUPERUSER_PASSWORD before starting Langflow, then sign in with the username langflow (or your configured LANGFLOW_SUPERUSER). Development branches retain automatic login by default. See authentication configuration.

To start Langflow, run:

uv run langflow run

Langflow starts at http://127.0.0.1:7860.

That's it! You're ready to build with Langflow! 🎉

📦 Other install options Copy Chapter

Run from source Copy Section

If you've cloned this repository and want to contribute, run this command from the repository root:

make run_cli

For more information, see DEVELOPMENT.md.

Docker Copy Section

Set and export a strong password before starting the container (Bash):

read -rsp "Langflow administrator password: " LANGFLOW_SUPERUSER_PASSWORD; echo
export LANGFLOW_SUPERUSER_PASSWORD
docker run -p 7860:7860 -e LANGFLOW_SUPERUSER_PASSWORD langflowai/langflow:latest

Langflow is available at http://localhost:7860/. Sign in as langflow with the password you entered. Official Docker images require authentication by default.
If you already have an auto-login installation, follow the upgrade instructions before switching defaults.
For configuration options, see the Docker deployment guide.

🛡️ Security Copy Chapter

For security information, see our Security Policy.

🚀 Deployment Copy Chapter

Langflow is completely open source and you can deploy it to all major deployment clouds. To learn how to deploy Langflow, see our Langflow deployment guides.

⭐ Stay up-to-date Copy Chapter

Star Langflow on GitHub to be instantly notified of new releases.

👋 Contribute Copy Chapter

We welcome contributions from developers of all levels. If you'd like to contribute, please check our contributing guidelines and help make Langflow more accessible.

❤️ Contributors Copy Chapter

README (`docs/README.md`) Copy Section

Website

This website is built using Docusaurus 3, a modern static website generator.

Installation Copy Section

$ npm install

Local Development Copy Section

$ npm run start

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

Build Copy Section

$ npm run build

This command generates static content into the build directory and can be served using any static contents hosting service, including npm run serve.

Import code snippets from the repo Copy Section

To embed source files directly in the docs, use raw-loader to import the file as a string and pass it to the native CodeBlock component.

import CodeBlock from "@theme/CodeBlock";
import customComponent from "!!raw-loader!@langflow/src/lfx/src/lfx/custom/custom_component/custom_component.py";

<CodeBlock language="python" title="CustomComponent metadata (from codebase)">
  {customComponent}
</CodeBlock>

Docusaurus Versioning Copy Chapter

The versioning configuration is found in docusaurus.config.js.

Versioning example for release version 1.9.x on top of 1.8.x:

1. Before release, the docs in the active release branch should already be set to 1.8.x, the current version.
2. When ready to release 1.9.x, create a branch and run npm run docs:version -- 1.9.0 to snapshot the current docs.
3. After creating a new version, update docusaurus.config.js to include the 1.9.0 release:

docs: {
  lastVersion: '1.9.0',
  versions: {
    '1.9.0': {
      label: '1.9.x',
      path: '1.9.0',
    },
    '1.8.0': {
      label: '1.8.x',
      path: '1.8.0',
    },
  },
},

4. Test the deployment locally:

npm run build
npm run serve

5. Create a pull request to main, and merge to create your new release.
6. To create version 2.0.x, repeat the process: update the active release branch docs to 2.0.x when you begin working on it, then when ready to release, run npm run docs:version -- 2.0.0, update docusaurus.config.js with labels using .x notation, and merge to main.

• lastVersion = the most recent released version (shown as "latest" in the UI).

See the Docusaurus docs for more info.

Disable versioning Copy Section

1. Remove the versions configuration from docusaurus.config.js.
2. Delete the docs/versioned_docs/ and docs/versioned_sidebars/ directories.
3. Delete docs/versions.json.

References Copy Section

• Official Docusaurus Versioning Documentation
• Docusaurus Versioning Best Practices

Deployment Copy Section

Using SSH:

$ USE_SSH=true npm run deploy

Not using SSH:

$ GIT_USER=<Your GitHub username> npm run deploy

If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the gh-pages branch.

Docs API Reference README (`docs/docs/API-Reference/README.md`) Copy Section

API Examples (Local Test Harness)

Run all API example suites against a local Langflow server:

make api_examples_local

Run one test suite:

make api_examples_local suites=python
make api_examples_local suites=javascript
make api_examples_local suites=curl

The following examples are not executed in this harness:

• api-build/build-flow-and-stream-events-2.py
• api-build/build-flow-and-stream-events-3.py
• api-flows-run/stream-llm-token-responses.py
• api-openai-responses/example-streaming-request.py
• api-logs/stream-logs.py
• api-logs/retrieve-logs-with-optional-parameters.py
• api-users/reset-password.py
• workflows-api/example-quickstart-sync.py (and matching .js / .sh; sync mode, read output.text)
• workflows-api/example-quickstart-stream-tokens.py (and matching .js / .sh; stream mode, print token events)
• workflows-api/example-quickstart-background-poll.py (and matching .js / .sh; background queue and poll until completed)
• workflows-api/example-stream-agui-parse.py (and matching .js / .sh; parses AG-UI events and chains two runs)

Docs API Reference Workflow Api Quickstart (`docs/docs/API-Reference/workflow-api-quickstart.mdx`) Copy Section

title: Workflow API quickstart slug: /workflow-api-quickstart Copy Chapter

import CodeBlock from '@theme/CodeBlock';
import exampleQuickstartSync from '!!raw-loader!@site/docs/API-Reference/curl-examples/workflows-api/example-quickstart-sync.sh';
import examplePythonQuickstartSync from '!!raw-loader!@site/docs/API-Reference/python-examples/workflows-api/example-quickstart-sync.py';
import exampleJavascriptQuickstartSync from '!!raw-loader!@site/docs/API-Reference/javascript-examples/workflows-api/example-quickstart-sync.js';
import exampleQuickstartStreamTokens from '!!raw-loader!@site/docs/API-Reference/curl-examples/workflows-api/example-quickstart-stream-tokens.sh';
import examplePythonQuickstartStreamTokens from '!!raw-loader!@site/docs/API-Reference/python-examples/workflows-api/example-quickstart-stream-tokens.py';
import exampleJavascriptQuickstartStreamTokens from '!!raw-loader!@site/docs/API-Reference/javascript-examples/workflows-api/example-quickstart-stream-tokens.js';
import exampleStreamAguiParse from '!!raw-loader!@site/docs/API-Reference/curl-examples/workflows-api/example-stream-agui-parse.sh';
import examplePythonStreamAguiParse from '!!raw-loader!@site/docs/API-Reference/python-examples/workflows-api/example-stream-agui-parse.py';
import exampleJavascriptStreamAguiParse from '!!raw-loader!@site/docs/API-Reference/javascript-examples/workflows-api/example-stream-agui-parse.js';
import exampleQuickstartBackgroundPoll from '!!raw-loader!@site/docs/API-Reference/curl-examples/workflows-api/example-quickstart-background-poll.sh';
import examplePythonQuickstartBackgroundPoll from '!!raw-loader!@site/docs/API-Reference/python-examples/workflows-api/example-quickstart-background-poll.py';
import exampleJavascriptQuickstartBackgroundPoll from '!!raw-loader!@site/docs/API-Reference/javascript-examples/workflows-api/example-quickstart-background-poll.js';

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import PartialAPISetup from '@site/docs/_partial-api-setup.mdx';

The Workflow API executes Langflow flows over POST /api/v2/workflows in three modes.

Use the default sync mode when you want to wait for the full JSON result in one response. Use stream when you need live Server-Sent Events (SSE) emitted as the flow runs. Use background when you want to queue a job and then poll or re-attach to its event stream.

This quickstart runs the same flow with each mode, so you can use the mode that fits your application.

The examples on this page also expect FLOW_ID to be set to your flow's UUID. Use a chat-style flow (for example Basic Prompting) so output.text contains the assistant reply.

Run a flow synchronously Copy Chapter

Omit mode or set "mode": "sync" to run inline. When the flow finishes, the response includes a top-level output.text field with the primary answer.

Example sync response

{
  "flow_id": "67ccd2be-17f0-8190-81ff-3bb2cf6508e6",
  "session_id": "session-123",
  "object": "response",
  "status": "completed",
  "output": {
    "reason": "single",
    "text": "2 + 2 equals 4.",
    "source": "ChatOutput-xyz"
  },
  "has_errors": false
}

Pass the same session_id on the next request to continue chat history for that conversation.

Stream LLM tokens Copy Chapter

Set "mode": "stream" to open an SSE stream. Choose the wire format with stream_protocol:

• langflow (default): Langflow EventManager frames for existing Langflow clients.
• agui: AG-UI lifecycle events for compatible clients.

For request examples, event types, and protocol details, see Execute flow with selected stream mode in the Workflow API reference.

Langflow EventManager (default) Copy Section

Each data: line is JSON shaped like {"event": "<type>", "data": {...}}. The example below prints only token events (data.chunk) as they arrive.

AG-UI {#ag-ui} Copy Section

Send "stream_protocol": "agui". Each data: line contains one AG-UI event as JSON. The example below handles TEXT_MESSAGE_CONTENT, TOOL_CALL_RESULT, and RUN_FINISHED, extracts a number from the first reply, then chains a follow-up prompt in the same session_id.

Run in the background Copy Chapter

Set "mode": "background" to queue a job and receive a job_id immediately. Poll GET /api/v2/workflows?job_id=… until status is completed, then read output.text from the result.

While a job is still queued or in_progress, the poll endpoint returns a job object (object: "job") with links for status, events, and stop. When the job completes, the same endpoint returns the full execution response.

To connect to a background run, see Re-attach to a background run.

Next steps Copy Chapter

• Workflow API reference — request body fields, response schemas, status polling, stop endpoint, tweaks, globals, and error codes.
• Flow trigger endpoints — v1 /run and /webhook endpoints if you are migrating from or comparing with the v1 API.

Docs Deployment Deployment Overview (`docs/docs/Deployment/deployment-overview.mdx`) Copy Section

title: Langflow deployment overview slug: /deployment-overview Copy Chapter

This section includes the different ways to bring your locally-built flows to the world.

• To self-host your local server through an ngrok gateway, see Deploy a public Langflow server.
  This approach uses ngrok to forward traffic and share your local Langflow server over the internet, without deploying to a cloud provider or exposing your network directly.

• To build and deploy a Langflow container that includes your flow files, see Containerize a Langflow application.
  This approach bundles your flows and dependencies into a portable, reproducible Docker image for easy deployment across different environments.

• To deploy a Langflow server on a remote server with Docker and Caddy, see Deploy Langflow on a remote server.
  This approach is good for hosting your own Langflow instance on a remote server with secure web access, using Docker containers and Caddy as a reverse proxy for HTTPS support.

• To deploy Langflow with Nginx and automatic SSL certificates, see Deploy Langflow with Nginx and Let's Encrypt.
  This approach uses Nginx as a reverse proxy with Let's Encrypt for automatic HTTPS certificate management to provide a secure deployment without Docker.

• To deploy Langflow on Kubernetes, see Langflow Kubernetes architecture and best practices
  This approach creates production-grade deployments with high availability, scalability, and robust orchestration.

• For cloud provider-specific deployment guides, see your cloud provider's documentation.
  The Langflow documentation provides a few examples, such as Google Cloud Platform and Hugging Face Spaces, to help you get started.

Docs Develop Authentication Overview (`docs/docs/Develop/authentication-overview.mdx`) Copy Section

title: Authentication and authorization overview slug: /authentication-overview Copy Chapter

Langflow uses authentication to verify who a user is before granting access, and authorization to control what an authenticated user is allowed to do.

Authentication and authorization are configured independently. Most deployments only require authentication. Authorization is an optional plugin that adds role-based access control (RBAC) to your server.

To configure authentication and authorization for your Langflow server, pick your authentication path below and follow the corresponding documentation.

• To secure a Langflow server with user accounts and API keys using Langflow's built-in authentication, see API keys and authentication.
  Built-in authentication is always available and is the default setting. Users log in with a username and password, and Langflow issues a short-lived JWT session token and validates Langflow API keys against its own database.

• To connect Langflow to your company's SSO, OIDC, or identity provider, see External authentication.
  External authentication lets an upstream identity provider, OIDC proxy, or corporate SSO gateway handle login. Langflow accepts the token the proxy forwards, validates it against the identity provider's JWKS endpoint, and provisions a local user automatically.

• To configure RBAC on your Langflow server, see Authorization.
  After a user is authenticated by any of the authentication paths, the authorization layer decides what the user can do.
  RBAC enforcement requires a registered authorization plugin.

When multiple credentials are present, Langflow tries each credential in the order of built-in JWT, external token, and then Langflow API key.

See also Copy Chapter

• Environment variables
• Security

Docs Flows Concepts Overview (`docs/docs/Flows/concepts-overview.mdx`) Copy Section

title: Use the visual editor slug: /concepts-overview Copy Chapter

import Icon from "@site/src/components/icon";

You use Langflow's visual editor to create, test, and share flows, which are functional representations of application workflows.
Flows consist of components that represent individual steps in your application's workflow.

Langflow's drag-and-drop interface allows you to create complex AI workflows without writing extensive code.
You can connect different resources, including prompts, large language models (LLMs), data sources, agents, MCP servers, and other tools and integrations.

:::tip
To try building and running a flow in a few minutes, see the Langflow quickstart.
:::

Workspace Copy Chapter

When building a flow, you primarily interact with the workspace.
This is where you add components, configure them, and attach them together.

From the workspace, you can also access the Playground, Share menu, and Logs.

Workspace gestures and interactions Copy Section

Use these shortcuts, gestures, and functionality to navigate the workspace:

• Pan horizontally and vertically: Click and drag an empty area of the workspace.

• Rearrange components: Click and drag the components anywhere on the workspace.

  To change the programmatic relationship between components, you must manipulate the component edges or ports. For more information, see Components overview.

  To enable guide lines, click Help, and then toggle Enable smart guides.

  If you can't edit any components, make sure the flow is unlocked.

• Zoom: Scroll on the mouse or trackpad, or click Canvas controls next to the zoom percentage more zoom options: Zoom In, Zoom Out, Zoom To 100%, and Zoom To Fit.

• Add notes and comments: Click Add Note.

• Keyboard shortcuts: To view available shortcuts, click Help, and then select Shortcuts.

Playground Copy Chapter

If your flow has a Chat Input component, you can use the Playground to run your flow, chat with your flow, view inputs and outputs, and modify the LLM's memories to tune the flow's responses in real time.

To try this for yourself, create a flow based on the Simple Agent template, and then click Playground when editing the flow in the workspace.

If you have an Agent component in your flow, the Playground displays its tool calls and outputs so you can monitor the agent's tool use and understand the reasoning behind its responses.

For more information, see Test flows in the Playground.

Share {#share-menu} Copy Chapter

The Share menu provides the following options for integrating your flow into external applications:

• API access: Integrate your flow into your applications with automatically-generated Python, JavaScript, and curl code snippets.

• Export: Export your flow to your local machine as a JSON file.

• MCP Server: Expose your flow as a tool for MCP-compatible clients.

• Embed into site: Embed your flow in HTML, React, or Angular applications.

• Shareable Playground: Share your Playground interface with another user.

  This is specifically for sharing the Playground experience; it isn't for running a flow in a production application.

  The Sharable Playground isn't available for Langflow Desktop.

See also Copy Chapter

• Manage files in Langflow
• Global variables
• API keys and authentication

Docs Get Started Get Started Quickstart (`docs/docs/Get-Started/get-started-quickstart.mdx`) Copy Section

title: Quickstart slug: /get-started-quickstart Copy Chapter

import Icon from "@site/src/components/icon";
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import PartialGlobalModelProviders from '@site/docs/_partial-global-model-providers.mdx';

Get started with Langflow by loading a template flow, running it, and then serving it at the /run API endpoint.

Prerequisites Copy Chapter

• Install and start Langflow

• Create an OpenAI API key

• Create a Langflow API key

  Create a Langflow API key

  A Langflow API key is a user-specific token you can use with Langflow.

  To create a Langflow API key, do the following:

  1. In Langflow, click your user icon, and then select Settings.

  2. Click Langflow API Keys, and then click Add New.

  3. Name your key, and then click Create API Key.

  4. Copy the API key and store it securely.

  5. To use your Langflow API key in a request, set a LANGFLOW_API_KEY environment variable in your terminal, and then include an x-api-key header or query parameter with your request.
     For example:

     bash Copy

     # Set variable
     export LANGFLOW_API_KEY="sk..."
     
     # Send request
     curl --request POST \
     --url "http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID" \
     --header "Content-Type: application/json" \
     --header "x-api-key: $LANGFLOW_API_KEY" \
     --data '{
       "output_type": "chat",
       "input_type": "chat",
       "input_value": "Hello"
     }'

:::tip
If you encounter the error "An API key must be passed as query or header" when attempting to sign up, see Troubleshooting.
:::

Run the Simple Agent template flow Copy Chapter

1. In Langflow, click New Flow, and then select the Simple Agent template.

The Simple Agent template consists of an Agent component connected to Chat Input and Chat Output components, a Calculator component, and a URL component. When you run this flow, you submit a query to the agent through the Chat Input component, the agent uses the Calculator and URL tools to generate a response, and then returns the response through the Chat Output component.

Many components can be tools for agents, including Model Context Protocol (MCP) servers. The agent decides which tools to call based on the context of a given query.

2. In the Agent component, click Setup Provider to select your language model provider.

3. In the Agent component, select your configured model from the Language Model dropdown.

   Access more models and providers

   There are two ways to access more models and providers:

   • Edit Langflow's global Models configuration. These providers and models are part of Langflow's core functionality. Use the Ollama provider to connect to any model hosted on a local or remote Ollama instance.
   • Connect any additional language model component to the Agent component's Language Model port.

4. To run the flow, click Playground.

5. To test the Calculator tool, ask the agent a simple math question, such as I want to add 4 and 4.
   To help you test and evaluate your flows, the Playground shows the agent's reasoning process as it analyzes the prompt, selects a tool, and then uses the tool to generate a response.
   In this case, a math question causes the agent to select the Calculator tool and use an action like evaluate_expression.

6. To test the URL tool, ask the agent about current events.
   For this request, the agent selects the URL tool's fetch_content action, and then returns a summary of current news headlines.

7. When you are done testing the flow, click Close.

:::tip Next steps
Now that you've run your first flow, try these next steps:

• Edit your Simple Agent flow by attaching different tools or adding more components to the flow.
• Build your own flows from scratch or by modifying other template flows.
• Integrate flows into your applications, as explained in Run your flows from external applications.
  :::

Run your flows from external applications Copy Chapter

Langflow is an IDE, but it's also a runtime you can call through the Langflow API with Python, JavaScript, or HTTP.

When you start Langflow locally, you can send requests to the local Langflow server.
For production applications, you need to deploy a stable Langflow instance to handle API calls.

For example, you can use the /run endpoint to run a flow and get the result.

Langflow provides code snippets to help you get started with the Langflow API.

1. When editing a flow, click Share, and then click API access.

   The default code in the API access pane constructs a request with the Langflow server url, headers, and a payload of request data.
   The code snippets automatically include the LANGFLOW_SERVER_ADDRESS and FLOW_ID values for the flow, and a script to include your LANGFLOW_API_KEY if you've set it as an environment variable in your terminal session.
   Replace these values if you're using the code for a different server or flow.
   The default Langflow server address is http://localhost:7860.

   python Copy

   import requests
   
   url = "http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID"  # The complete API endpoint URL for this flow
   
   # Request payload configuration
   payload = {
       "output_type": "chat",
       "input_type": "chat",
       "input_value": "hello world!"
   }
   
   # Request headers
   headers = {
       "Content-Type": "application/json",
       "x-api-key": "$LANGFLOW_API_KEY"
   }
   
   try:
       # Send API request
       response = requests.request("POST", url, json=payload, headers=headers)
       response.raise_for_status()  # Raise exception for bad status codes
   
       # Print response
       print(response.text)
   
   except requests.exceptions.RequestException as e:
       print(f"Error making API request: {e}")
   except ValueError as e:
       print(f"Error parsing response: {e}")

   js Copy

   const payload = {
       "output_type": "chat",
       "input_type": "chat",
       "input_value": "hello world!",
       "session_id": "user_1"
   };
   
   const options = {
       method: 'POST',
       headers: {
           'Content-Type': 'application/json',
           'x-api-key': 'LANGFLOW_API_KEY'
       },
       body: JSON.stringify(payload)
   };
   
   fetch('http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID', options)
       .then(response => response.json())
       .then(response => console.log(response))
       .catch(err => console.error(err));

   bash Copy

   curl --request POST \
        --url 'http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID?stream=false' \
        --header 'Content-Type: application/json' \
        --header "x-api-key: LANGFLOW_API_KEY" \
        --data '{
         "output_type": "chat",
         "input_type": "chat",
         "input_value": "hello world!"
         }'
   
   # A 200 response confirms the call succeeded.

2. Copy the snippet, paste it in a script file, and then run the script to send the request.
   If you are using the curl snippet, you can run the command directly in your terminal.

If the request is successful, the response includes many details about the flow run, including the session ID, inputs, outputs, components, durations, and more.
The following is an example of a response from running the Simple Agent template flow:

Result

/* Detailed source-code truncated for AI context efficiency. */

In a production application, you probably want to select parts of this response to return to the user, store in logs, and so on. The next steps demonstrate how you can extract data from a Langflow API response to use in your application.

Extract data from the response Copy Section

The following example builds on the API pane's example code to create a question-and-answer chat in your terminal that stores the agent's previous answer.

1. Incorporate your Simple Agent flow's /run snippet into the following script.
   This script runs a question-and-answer chat in your terminal and stores the agent's previous answer so you can compare them.

   text Copy

/* Detailed source-code truncated for AI context efficiency. */

</TabItem>
    <TabItem value="JavaScript" label="JavaScript">

    ```
/* Detailed source-code truncated for AI context efficiency. */

</TabItem>
</Tabs>

2. To view the agent's previous answer, type compare. To close the terminal chat, type exit.

Use tweaks to apply temporary overrides to a flow run Copy Section

You can include tweaks with your requests to temporarily modify flow parameters.
Tweaks are added to the API request, and temporarily change component parameters within your flow.
Tweaks override the flow's components' settings for a single run only.
They don't modify the underlying flow configuration or persist between runs.

Tweaks are added to the /run endpoint's payload.
To assist with formatting, expose the fields you want to override before copying the code snippet.

1. On the canvas, select the component whose parameter you want to override.
2. Click Parameters, and then click API on the field you want to include in the snippet.
3. Click Share > API access.
   Enabling API on a field doesn't permanently change the parameter value. It only adds the field to the sample code snippets.
4. For example, to change the agent's LLM model from OpenAI to Anthropic and include your Anthropic API key with the request, select the Agent component, open Parameters, and enable API on the Language Model field.

Langflow updates the tweaks object in the code snippets based on your exposed parameters, and includes default values to guide you.
Use the updated code snippets in your script to run your flow with your overrides.

payload = {
    "output_type": "chat",
    "input_type": "chat",
    "input_value": "hello world!",
    "tweaks": {
        "Agent-ZOknz": {
            "agent_llm": "Anthropic",
            "api_key": "ANTHROPIC_API_KEY",
            "model_name": "claude-opus-4-5-20251101"
        }
    }
}

Next steps Copy Chapter

• Trigger flows with the Langflow API
• Use Langflow as a Model Context Protocol (MCP) server
• Containerize a Langflow application
• File management

Docs Lfx Extensions Overview (`docs/docs/Lfx/extensions-overview.mdx`) Copy Section

title: Langflow Extensions overview slug: /extensions-overview Copy Chapter

Langflow ships third-party provider integrations as extensions.
An extension is a pip-installable package that registers components when Langflow starts.

Each extension exposes one or more bundles.
A bundle is a named provider such as openai, qdrant, or duckduckgo.
This bundle is the same group that related components are listed under in the visual editor.

Instead of every integration being built into langflow, you install the extensions you need. Saved flows reference bundles by stable IDs (ext::<Class>@official), not by pip package name, so a provider can move between packages without breaking your flows.

Starting in Langflow 1.12, the default uv pip install langflow installation includes only a curated list of providers. For more information, see Additional bundles.

To install extensions and bundle components, see Install LFX with bundle components.

To build your own extension, see Build your first extension.

See also Copy Chapter

• About LFX
• Install LFX
• Bundle list
• Build your first extension
• Manifest reference
• Run flows with LFX
• Serve flows with LFX

Docs Lfx Extensions Quickstart (`docs/docs/Lfx/extensions-quickstart.mdx`) Copy Section

title: Build your first extension slug: /extensions-quickstart Copy Chapter

Build, validate, and run a Langflow extension that ships a single bundle.
A bundle is a pip-installable package you can publish or load with lfx extension dev.

Prerequisites Copy Chapter

• Python 3.10 or greater
• langflow installed with uv pip install langflow. The lfx CLI provides every command in this guide. For more information, see Install the Langflow OSS package.

Create an extension Copy Chapter

1. Scaffold a new extension:

   bash Copy

   lfx extension init my-extension
   cd my-extension

   This creates the canonical layout the loader expects:

   text Copy

   my-extension/
   ├── extension.json           # the v0 manifest
   ├── pyproject.toml           # so the bundle is pip-installable
   └── src/
       └── lfx_my_extension/
           ├── __init__.py
           ├── extension.json   # symlink/copy used by importlib at runtime
           └── components/
               └── my_bundle/
                   ├── __init__.py
                   └── my_component.py

   For more information, see Manifest reference.

2. To edit the component, open src/lfx_my_extension/components/my_bundle/my_component.py.
   The scaffold ships a working Component subclass that prints "Hello, {name}!"

   python Copy

   from lfx.custom.custom_component.component import Component
   from lfx.io import MessageTextInput, Output
   from lfx.schema.message import Message
   
   class HelloComponent(Component):
       display_name = "Hello"
       description = "Greets the caller."
   
       inputs = [MessageTextInput(name="who", display_name="Who?", value="world")]
       outputs = [Output(display_name="Greeting", name="greeting", method="build_message")]
   
       def build_message(self) -> Message:
           return Message(text=f"Hello, {self.who}!")

   The full surface available to bundle code is enumerated in BUNDLE_API.md.
   Anything outside of BUNDLE_API.md is not part of the API contract, and may move or break between releases.

3. Before launching Langflow, run the static extension checker.

   bash Copy

   lfx extension validate .

   The validator parses the manifest and reports typed errors.
   It does not execute imports by default, so it is safe to run against an extension you just downloaded. Use --execute-imports only when you trust the source — it runs the import probe in a subprocess.

4. Run Langflow with the extension loaded.

   bash Copy

   lfx extension dev .

   This launches a Langflow dev server with my-extension registered at the @official slot. The Hello component appears in the Langflow UI component list under the bundle name in extension.json.

   To see what the loader picked up:

   bash Copy

   lfx extension list --format json

5. Iterate with reload.
   Edit the component, save, then click the Reload action in the palette's bundle header (or run lfx extension reload --bundle my_bundle). The atomic-swap reload pipeline replaces the component in place; in-flight flows keep the pre-swap class so a running execution is never interrupted.

   Reload only works in Mode A (local dev). Production deployments rebuild the Docker image.

6. Ship the extension.

   Once the extension works locally, publish the package to PyPI:

   bash Copy

   python -m build         # builds the wheel + sdist
   twine upload dist/*     # publish to PyPI

   To install the extension into a Langflow environment with a regular pip install:

   bash Copy

   pip install lfx-my-extension
   langflow run

   Discovery happens at server startup.
   The bundle appears in the palette without further configuration.

See also Copy Chapter

• Extensions overview
• Manifest reference
• About LFX
• Run flows with LFX
• Serve flows with LFX

Docs Lfx Lfx Overview (`docs/docs/Lfx/lfx-overview.mdx`) Copy Section

title: About LFX slug: /lfx-overview Copy Chapter

import Icon from "@site/src/components/icon";

LFX (Langflow Executor) is a lightweight CLI and Python library for running Langflow flows without the full Langflow application.

Flows are built in the Langflow visual builder, and then the flow JSON files are run with LFX.
LFX executes flows statelessly from JSON files with minimal dependencies, no database, and no UI.

LFX is similar to running Langflow with --backend-only, but even more lightweight because the full Langflow package and its dependencies do not need to be installed.

If you're building flows in Langflow with a uv pip install langflow installation, you likely don't need to explore LFX, but if you're deploying and running flows from JSON files using other applications or environments, you'll find LFX is a powerful tool for executing flows.

If you have installed Langflow OSS version 1.6 or later, lfx is already included in your environment.

How LFX differs from Langflow Copy Chapter

In Langflow, you build and test flows in the visual builder, and the full application stores flows, messages, and users in a database.
The same Langflow server already uses LFX as its flow runtime.
Installing LFX on its own decouples the runtime from the Langflow UI and database.
lfx run executes a flow once from the command line and prints the result, and lfx serve exposes one or more flows as persistent HTTP endpoints.
You still author flows in the Langflow visual builder, and export the flows as JSON files.
Standalone LFX is for executing flow JSON files without starting the Langflow server or opening the visual editor.

Under the hood, LFX uses a no-op database interface (NoopSession) instead of a real database. There is no langflow.db file, and stateful operations such as saving flows, storing messages, and managing users do not persist. Operations that depend on langflow.db will not work as they do in the full Langflow application.

LFX commands Copy Chapter

LFX provides two sets of commands:

Runtime commands, to run and serve flows locally:

For the LFX runtime commands, see Run flows with LFX and Serve flows with LFX.

Flow DevOps SDK commands, to version, test, and deploy flows:

For the Flow DevOps SDK commands, see Flow DevOps Toolkit SDK.

See also Copy Chapter

• Install LFX
• Run flows with LFX
• Serve flows with LFX
• Pre-warm LFX
• Build flows with the LFX MCP server
• Flow DevOps Toolkit SDK
• LFX and Langflow version compatibility
• Extensions overview

Versioned Docs Version 1.10.0 API Reference README (`docs/versioned_docs/version-1.10.0/API-Reference/README.md`) Copy Section

API Examples (Local Test Harness)

Run all API example suites against a local Langflow server:

make api_examples_local

Run one test suite:

make api_examples_local suites=python
make api_examples_local suites=javascript
make api_examples_local suites=curl

The following examples are not executed in this harness:

• api-build/build-flow-and-stream-events-2.py
• api-build/build-flow-and-stream-events-3.py
• api-flows-run/stream-llm-token-responses.py
• api-openai-responses/example-streaming-request.py
• api-logs/stream-logs.py
• api-logs/retrieve-logs-with-optional-parameters.py
• api-users/reset-password.py

Versioned Docs Version 1.10.0 Deployment Deployment Overview (`docs/versioned_docs/version-1.10.0/Deployment/deployment-overview.mdx`) Copy Section

title: Langflow deployment overview slug: /deployment-overview Copy Chapter

This section includes the different ways to bring your locally-built flows to the world.

• To self-host your local server through an ngrok gateway, see Deploy a public Langflow server.
  This approach uses ngrok to forward traffic and share your local Langflow server over the internet, without deploying to a cloud provider or exposing your network directly.

• To build and deploy a Langflow container that includes your flow files, see Containerize a Langflow application.
  This approach bundles your flows and dependencies into a portable, reproducible Docker image for easy deployment across different environments.

• To deploy a Langflow server on a remote server with Docker and Caddy, see Deploy Langflow on a remote server.
  This approach is good for hosting your own Langflow instance on a remote server with secure web access, using Docker containers and Caddy as a reverse proxy for HTTPS support.

• To deploy Langflow with Nginx and automatic SSL certificates, see Deploy Langflow with Nginx and Let's Encrypt.
  This approach uses Nginx as a reverse proxy with Let's Encrypt for automatic HTTPS certificate management to provide a secure deployment without Docker.

• To deploy Langflow on Kubernetes, see Langflow Kubernetes architecture and best practices
  This approach creates production-grade deployments with high availability, scalability, and robust orchestration.

• For cloud provider-specific deployment guides, see your cloud provider's documentation.
  The Langflow documentation provides a few examples, such as Google Cloud Platform and Hugging Face Spaces, to help you get started.

Versioned Docs Version 1.10.0 Develop Extensions Overview (`docs/versioned_docs/version-1.10.0/Develop/extensions-overview.mdx`) Copy Section

title: Langflow Extensions overview slug: /extensions-overview Copy Chapter

import Icon from "@site/src/components/icon";

Langflow ships component bundles that are maintained and released separately from the core Langflow server as Extensions.
Instead of every integration being built into langflow, each bundle is its own pip-installable package, such as lfx-duckduckgo or lfx-arxiv.

When you run uv pip install langflow, you install:

• All Langflow core components
• All bundles that ship as dependencies of the langflow metapackage

Some bundles that were previously included in langflow are moved into standalone packages.
The langflow metapackage adds them as regular pip dependencies, so pip install langflow continues to include them.

Current Extension bundles Copy Chapter

The following Extension bundles are included with uv pip install langflow:

The internal identifier for each component changes.
For example, a DuckDuckGo component previously referenced as a DuckDuckGoSearchComponent class is now ext:duckduckgo:DuckDuckGoSearchComponent@official.
Langflow rewrites these references automatically when you open a saved flow, so in most cases the migration is invisible.

If a component is missing after an upgrade Copy Chapter

If you open a flow and a node shows an error like component-not-found, it means the automatic migration couldn't resolve the component reference.
This can happen when:

• The bundle the component came from was not installed in the upgraded environment.
• The component was referenced by a name that appears in more than one bundle (component-name-ambiguous).

In both cases the error message includes a hint that names the expected canonical ID. For example:

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

Use the bundle name from the hint, such as duckduckgo in this example, to find and install the correct extension package, and then reload the flow.

Install a bundle extension Copy Chapter

If a bundle you need is not included in your Langflow environment, install it with pip:

uv pip install lfx-duckduckgo
uv run langflow run

Langflow discovers the package at server startup and loads the components into the palette automatically.
No additional configuration is required.

To see what extensions are currently loaded, run:

lfx extension list

Build your own extension Copy Chapter

If you have custom components that you want to distribute and version independently of your Langflow install, you can package them as an extension.

For more information, see Build your first Langflow Extension.

See also Copy Chapter

• Build your first extension
• Manifest reference

Versioned Docs Version 1.10.0 Develop Extensions Quickstart (`docs/versioned_docs/version-1.10.0/Develop/extensions-quickstart.mdx`) Copy Section

title: Langflow Extension quickstart slug: /extensions-quickstart Copy Chapter

Build, validate, and run a Langflow Extension bundle to create a single-component extension you can pip-install or load using lfx extension dev.

Prerequisites Copy Chapter

• Python 3.11 or greater
• langflow installed with uv pip install langflow. The lfx CLI provides every command in this guide. For more information, see Install the Langflow OSS package.

Create an extension Copy Chapter

1. Scaffold a new extension:

   bash Copy

   lfx extension init my-extension
   cd my-extension

   This creates the canonical layout the loader expects:

   text Copy

   my-extension/
   ├── extension.json           # the v0 manifest
   ├── pyproject.toml           # so the bundle is pip-installable
   └── src/
       └── lfx_my_extension/
           ├── __init__.py
           ├── extension.json   # symlink/copy used by importlib at runtime
           └── components/
               └── my_bundle/
                   ├── __init__.py
                   └── my_component.py

   For more information, see Manifest reference.

2. To edit the component, open src/lfx_my_extension/components/my_bundle/my_component.py.
   The scaffold ships a working Component subclass that prints "Hello, {name}!"

   python Copy

   from lfx.custom.custom_component.component import Component
   from lfx.io import MessageTextInput, Output
   from lfx.schema.message import Message
   
   class HelloComponent(Component):
       display_name = "Hello"
       description = "Greets the caller."
   
       inputs = [MessageTextInput(name="who", display_name="Who?", value="world")]
       outputs = [Output(display_name="Greeting", name="greeting", method="build_message")]
   
       def build_message(self) -> Message:
           return Message(text=f"Hello, {self.who}!")

   The full surface available to bundle code is enumerated in BUNDLE_API.md.
   Anything outside of BUNDLE_API.md is not part of the API contract, and may move or break between releases.

3. Before launching Langflow, run the static extension checker.

   bash Copy

   lfx extension validate .

   The validator parses the manifest and reports typed errors.
   It does not execute imports by default, so it is safe to run against an extension you just downloaded. Use --execute-imports only when you trust the source — it runs the import probe in a subprocess.

4. Run Langflow with the extension loaded.

   bash Copy

   lfx extension dev .

   This launches a Langflow dev server with my-extension registered at the @official slot. The Hello component appears in the Langflow UI component list under the bundle name in extension.json.

   To see what the loader picked up:

   bash Copy

   lfx extension list --format json

5. Iterate with reload.
   Edit the component, save, then click the Reload action in the palette's bundle header (or run lfx extension reload --bundle my_bundle). The atomic-swap reload pipeline replaces the component in place; in-flight flows keep the pre-swap class so a running execution is never interrupted.

   Reload only works in Mode A (local dev). Production deployments rebuild the Docker image.

6. Ship the extension.

   Once the extension works locally, publish the package to PyPI:

   bash Copy

   python -m build         # builds the wheel + sdist
   twine upload dist/*     # publish to PyPI

   To install the extension into a Langflow environment with a regular pip install:

   bash Copy

   pip install lfx-my-extension
   langflow run

   Discovery happens at server startup.
   The bundle appears in the palette without further configuration.

See also Copy Chapter

• Bundle extensions overview
• Manifest reference

Versioned Docs Version 1.10.0 Flows Concepts Overview (`docs/versioned_docs/version-1.10.0/Flows/concepts-overview.mdx`) Copy Section

title: Use the visual editor slug: /concepts-overview Copy Chapter

import Icon from "@site/src/components/icon";

You use Langflow's visual editor to create, test, and share flows, which are functional representations of application workflows.
Flows consist of components that represent individual steps in your application's workflow.

Langflow's drag-and-drop interface allows you to create complex AI workflows without writing extensive code.
You can connect different resources, including prompts, large language models (LLMs), data sources, agents, MCP servers, and other tools and integrations.

:::tip
To try building and running a flow in a few minutes, see the Langflow quickstart.
:::

Workspace Copy Chapter

When building a flow, you primarily interact with the workspace.
This is where you add components, configure them, and attach them together.

From the workspace, you can also access the Playground, Share menu, and Logs.

Workspace gestures and interactions Copy Section

Use these shortcuts, gestures, and functionality to navigate the workspace:

• Pan horizontally and vertically: Click and drag an empty area of the workspace.

• Rearrange components: Click and drag the components anywhere on the workspace.

  To change the programmatic relationship between components, you must manipulate the component edges or ports. For more information, see Components overview.

  To enable guide lines, click Help, and then toggle Enable smart guides.

  If you can't edit any components, make sure the flow is unlocked.

• Zoom: Scroll on the mouse or trackpad, or click Canvas controls next to the zoom percentage more zoom options: Zoom In, Zoom Out, Zoom To 100%, and Zoom To Fit.

• Add notes and comments: Click Add Note.

• Keyboard shortcuts: To view available shortcuts, click Help, and then select Shortcuts.

Playground Copy Chapter

If your flow has a Chat Input component, you can use the Playground to run your flow, chat with your flow, view inputs and outputs, and modify the LLM's memories to tune the flow's responses in real time.

To try this for yourself, create a flow based on the Simple Agent template, and then click Playground when editing the flow in the workspace.

If you have an Agent component in your flow, the Playground displays its tool calls and outputs so you can monitor the agent's tool use and understand the reasoning behind its responses.

For more information, see Test flows in the Playground.

Share {#share-menu} Copy Chapter

The Share menu provides the following options for integrating your flow into external applications:

• API access: Integrate your flow into your applications with automatically-generated Python, JavaScript, and curl code snippets.

• Export: Export your flow to your local machine as a JSON file.

• MCP Server: Expose your flow as a tool for MCP-compatible clients.

• Embed into site: Embed your flow in HTML, React, or Angular applications.

• Shareable Playground: Share your Playground interface with another user.

  This is specifically for sharing the Playground experience; it isn't for running a flow in a production application.

  The Sharable Playground isn't available for Langflow Desktop.

See also Copy Chapter

• Manage files in Langflow
• Global variables
• API keys and authentication

Versioned Docs Version 1.10.0 Get Started Get Started Quickstart (`docs/versioned_docs/version-1.10.0/Get-Started/get-started-quickstart.mdx`) Copy Section

title: Quickstart slug: /get-started-quickstart Copy Chapter

import Icon from "@site/src/components/icon";
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import PartialGlobalModelProviders from '@site/docs/_partial-global-model-providers.mdx';

Get started with Langflow by loading a template flow, running it, and then serving it at the /run API endpoint.

Prerequisites Copy Chapter

• Install and start Langflow

• Create an OpenAI API key

• Create a Langflow API key

  Create a Langflow API key

  A Langflow API key is a user-specific token you can use with Langflow.

  To create a Langflow API key, do the following:

  1. In Langflow, click your user icon, and then select Settings.

  2. Click Langflow API Keys, and then click Add New.

  3. Name your key, and then click Create API Key.

  4. Copy the API key and store it securely.

  5. To use your Langflow API key in a request, set a LANGFLOW_API_KEY environment variable in your terminal, and then include an x-api-key header or query parameter with your request.
     For example:

     bash Copy

     # Set variable
     export LANGFLOW_API_KEY="sk..."
     
     # Send request
     curl --request POST \
     --url "http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID" \
     --header "Content-Type: application/json" \
     --header "x-api-key: $LANGFLOW_API_KEY" \
     --data '{
       "output_type": "chat",
       "input_type": "chat",
       "input_value": "Hello"
     }'

:::tip
If you encounter the error "An API key must be passed as query or header" when attempting to sign up, see Troubleshooting.
:::

Run the Simple Agent template flow Copy Chapter

1. In Langflow, click New Flow, and then select the Simple Agent template.

The Simple Agent template consists of an Agent component connected to Chat Input and Chat Output components, a Calculator component, and a URL component. When you run this flow, you submit a query to the agent through the Chat Input component, the agent uses the Calculator and URL tools to generate a response, and then returns the response through the Chat Output component.

Many components can be tools for agents, including Model Context Protocol (MCP) servers. The agent decides which tools to call based on the context of a given query.

2. In the Agent component, click Setup Provider to select your language model provider.

3. In the Agent component, select your configured model from the Language Model dropdown.

   Access more models and providers

   There are two ways to access more models and providers:

   • Edit Langflow's global Models configuration. These providers and models are part of Langflow's core functionality. Use the Ollama provider to connect to any model hosted on a local or remote Ollama instance.
   • Connect any additional language model component to the Agent component's Language Model port.

4. To run the flow, click Playground.

5. To test the Calculator tool, ask the agent a simple math question, such as I want to add 4 and 4.
   To help you test and evaluate your flows, the Playground shows the agent's reasoning process as it analyzes the prompt, selects a tool, and then uses the tool to generate a response.
   In this case, a math question causes the agent to select the Calculator tool and use an action like evaluate_expression.

6. To test the URL tool, ask the agent about current events.
   For this request, the agent selects the URL tool's fetch_content action, and then returns a summary of current news headlines.

7. When you are done testing the flow, click Close.

:::tip Next steps
Now that you've run your first flow, try these next steps:

• Edit your Simple Agent flow by attaching different tools or adding more components to the flow.
• Build your own flows from scratch or by modifying other template flows.
• Integrate flows into your applications, as explained in Run your flows from external applications.
  :::

Run your flows from external applications Copy Chapter

Langflow is an IDE, but it's also a runtime you can call through the Langflow API with Python, JavaScript, or HTTP.

When you start Langflow locally, you can send requests to the local Langflow server.
For production applications, you need to deploy a stable Langflow instance to handle API calls.

For example, you can use the /run endpoint to run a flow and get the result.

Langflow provides code snippets to help you get started with the Langflow API.

1. When editing a flow, click Share, and then click API access.

   The default code in the API access pane constructs a request with the Langflow server url, headers, and a payload of request data.
   The code snippets automatically include the LANGFLOW_SERVER_ADDRESS and FLOW_ID values for the flow, and a script to include your LANGFLOW_API_KEY if you've set it as an environment variable in your terminal session.
   Replace these values if you're using the code for a different server or flow.
   The default Langflow server address is http://localhost:7860.

   python Copy

   import requests
   
   url = "http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID"  # The complete API endpoint URL for this flow
   
   # Request payload configuration
   payload = {
       "output_type": "chat",
       "input_type": "chat",
       "input_value": "hello world!"
   }
   
   # Request headers
   headers = {
       "Content-Type": "application/json",
       "x-api-key": "$LANGFLOW_API_KEY"
   }
   
   try:
       # Send API request
       response = requests.request("POST", url, json=payload, headers=headers)
       response.raise_for_status()  # Raise exception for bad status codes
   
       # Print response
       print(response.text)
   
   except requests.exceptions.RequestException as e:
       print(f"Error making API request: {e}")
   except ValueError as e:
       print(f"Error parsing response: {e}")

   js Copy

   const payload = {
       "output_type": "chat",
       "input_type": "chat",
       "input_value": "hello world!",
       "session_id": "user_1"
   };
   
   const options = {
       method: 'POST',
       headers: {
           'Content-Type': 'application/json',
           'x-api-key': 'LANGFLOW_API_KEY'
       },
       body: JSON.stringify(payload)
   };
   
   fetch('http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID', options)
       .then(response => response.json())
       .then(response => console.log(response))
       .catch(err => console.error(err));

   bash Copy

   curl --request POST \
        --url 'http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID?stream=false' \
        --header 'Content-Type: application/json' \
        --header "x-api-key: LANGFLOW_API_KEY" \
        --data '{
         "output_type": "chat",
         "input_type": "chat",
         "input_value": "hello world!"
         }'
   
   # A 200 response confirms the call succeeded.

2. Copy the snippet, paste it in a script file, and then run the script to send the request.
   If you are using the curl snippet, you can run the command directly in your terminal.

If the request is successful, the response includes many details about the flow run, including the session ID, inputs, outputs, components, durations, and more.
The following is an example of a response from running the Simple Agent template flow:

Result

/* Detailed source-code truncated for AI context efficiency. */

In a production application, you probably want to select parts of this response to return to the user, store in logs, and so on. The next steps demonstrate how you can extract data from a Langflow API response to use in your application.

Extract data from the response Copy Section

The following example builds on the API pane's example code to create a question-and-answer chat in your terminal that stores the agent's previous answer.

1. Incorporate your Simple Agent flow's /run snippet into the following script.
   This script runs a question-and-answer chat in your terminal and stores the agent's previous answer so you can compare them.

   text Copy

/* Detailed source-code truncated for AI context efficiency. */

</TabItem>
    <TabItem value="JavaScript" label="JavaScript">

    ```
/* Detailed source-code truncated for AI context efficiency. */

</TabItem>
</Tabs>

2. To view the agent's previous answer, type compare. To close the terminal chat, type exit.

Use tweaks to apply temporary overrides to a flow run Copy Section

You can include tweaks with your requests to temporarily modify flow parameters.
Tweaks are added to the API request, and temporarily change component parameters within your flow.
Tweaks override the flow's components' settings for a single run only.
They don't modify the underlying flow configuration or persist between runs.

Tweaks are added to the /run endpoint's payload.
To assist with formatting, you can define tweaks in Langflow's Input Schema pane before copying the code snippet.

1. To open the Input Schema pane, from the API access pane, click Input Schema.
2. In the Input Schema pane, select the parameter you want to modify in your next request.
   Enabling parameters in the Input Schema pane doesn't permanently change the listed parameters. It only adds them to the sample code snippets.
3. For example, to change the agent's LLM model from OpenAI to Anthropic and include your Anthropic API key with the request, select the Agent component in the Input Schema pane and enable the Language Model field.

Langflow updates the tweaks object in the code snippets based on your input parameters, and includes default values to guide you.
Use the updated code snippets in your script to run your flow with your overrides.

payload = {
    "output_type": "chat",
    "input_type": "chat",
    "input_value": "hello world!",
    "tweaks": {
        "Agent-ZOknz": {
            "agent_llm": "Anthropic",
            "api_key": "ANTHROPIC_API_KEY",
            "model_name": "claude-opus-4-5-20251101"
        }
    }
}

Next steps Copy Chapter

• Trigger flows with the Langflow API
• Use Langflow as a Model Context Protocol (MCP) server
• Containerize a Langflow application
• File management

Versioned Docs Version 1.11.0 API Reference README (`docs/versioned_docs/version-1.11.0/API-Reference/README.md`) Copy Section

API Examples (Local Test Harness)

Run all API example suites against a local Langflow server:

make api_examples_local

Run one test suite:

make api_examples_local suites=python
make api_examples_local suites=javascript
make api_examples_local suites=curl

The following examples are not executed in this harness:

• api-build/build-flow-and-stream-events-2.py
• api-build/build-flow-and-stream-events-3.py
• api-flows-run/stream-llm-token-responses.py
• api-openai-responses/example-streaming-request.py
• api-logs/stream-logs.py
• api-logs/retrieve-logs-with-optional-parameters.py
• api-users/reset-password.py
• workflows-api/example-quickstart-sync.py (and matching .js / .sh; sync mode, read output.text)
• workflows-api/example-quickstart-stream-tokens.py (and matching .js / .sh; stream mode, print token events)
• workflows-api/example-quickstart-background-poll.py (and matching .js / .sh; background queue and poll until completed)
• workflows-api/example-stream-agui-parse.py (and matching .js / .sh; parses AG-UI events and chains two runs)

Versioned Docs Version 1.11.0 API Reference Workflow Api Quickstart (`docs/versioned_docs/version-1.11.0/API-Reference/workflow-api-quickstart.mdx`) Copy Section

title: Workflow API quickstart slug: /workflow-api-quickstart Copy Chapter

import CodeBlock from '@theme/CodeBlock';
import exampleQuickstartSync from '!!raw-loader!@site/docs/API-Reference/curl-examples/workflows-api/example-quickstart-sync.sh';
import examplePythonQuickstartSync from '!!raw-loader!@site/docs/API-Reference/python-examples/workflows-api/example-quickstart-sync.py';
import exampleJavascriptQuickstartSync from '!!raw-loader!@site/docs/API-Reference/javascript-examples/workflows-api/example-quickstart-sync.js';
import exampleQuickstartStreamTokens from '!!raw-loader!@site/docs/API-Reference/curl-examples/workflows-api/example-quickstart-stream-tokens.sh';
import examplePythonQuickstartStreamTokens from '!!raw-loader!@site/docs/API-Reference/python-examples/workflows-api/example-quickstart-stream-tokens.py';
import exampleJavascriptQuickstartStreamTokens from '!!raw-loader!@site/docs/API-Reference/javascript-examples/workflows-api/example-quickstart-stream-tokens.js';
import exampleStreamAguiParse from '!!raw-loader!@site/docs/API-Reference/curl-examples/workflows-api/example-stream-agui-parse.sh';
import examplePythonStreamAguiParse from '!!raw-loader!@site/docs/API-Reference/python-examples/workflows-api/example-stream-agui-parse.py';
import exampleJavascriptStreamAguiParse from '!!raw-loader!@site/docs/API-Reference/javascript-examples/workflows-api/example-stream-agui-parse.js';
import exampleQuickstartBackgroundPoll from '!!raw-loader!@site/docs/API-Reference/curl-examples/workflows-api/example-quickstart-background-poll.sh';
import examplePythonQuickstartBackgroundPoll from '!!raw-loader!@site/docs/API-Reference/python-examples/workflows-api/example-quickstart-background-poll.py';
import exampleJavascriptQuickstartBackgroundPoll from '!!raw-loader!@site/docs/API-Reference/javascript-examples/workflows-api/example-quickstart-background-poll.js';

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import PartialAPISetup from '@site/docs/_partial-api-setup.mdx';

The Workflow API executes Langflow flows over POST /api/v2/workflows in three modes.

Use the default sync mode when you want to wait for the full JSON result in one response. Use stream when you need live Server-Sent Events (SSE) emitted as the flow runs. Use background when you want to queue a job and then poll or re-attach to its event stream.

This quickstart runs the same flow with each mode, so you can use the mode that fits your application.

The examples on this page also expect FLOW_ID to be set to your flow's UUID. Use a chat-style flow (for example Basic Prompting) so output.text contains the assistant reply.

Run a flow synchronously Copy Chapter

Omit mode or set "mode": "sync" to run inline. When the flow finishes, the response includes a top-level output.text field with the primary answer.

Example sync response

{
  "flow_id": "67ccd2be-17f0-8190-81ff-3bb2cf6508e6",
  "session_id": "session-123",
  "object": "response",
  "status": "completed",
  "output": {
    "reason": "single",
    "text": "2 + 2 equals 4.",
    "source": "ChatOutput-xyz"
  },
  "has_errors": false
}

Pass the same session_id on the next request to continue chat history for that conversation.

Stream LLM tokens Copy Chapter

Set "mode": "stream" to open an SSE stream. Choose the wire format with stream_protocol:

• langflow (default): Langflow EventManager frames for existing Langflow clients.
• agui: AG-UI lifecycle events for compatible clients.

For request examples, event types, and protocol details, see Execute flow with selected stream mode in the Workflow API reference.

Langflow EventManager (default) Copy Section

Each data: line is JSON shaped like {"event": "<type>", "data": {...}}. The example below prints only token events (data.chunk) as they arrive.

AG-UI {#ag-ui} Copy Section

Send "stream_protocol": "agui". Each data: line contains one AG-UI event as JSON. The example below handles TEXT_MESSAGE_CONTENT, TOOL_CALL_RESULT, and RUN_FINISHED, extracts a number from the first reply, then chains a follow-up prompt in the same session_id.

Run in the background Copy Chapter

Set "mode": "background" to queue a job and receive a job_id immediately. Poll GET /api/v2/workflows?job_id=… until status is completed, then read output.text from the result.

While a job is still queued or in_progress, the poll endpoint returns a job object (object: "job") with links for status, events, and stop. When the job completes, the same endpoint returns the full execution response.

To connect to a background run, see Re-attach to a background run.

Next steps Copy Chapter

• Workflow API reference — request body fields, response schemas, status polling, stop endpoint, tweaks, globals, and error codes.
• Flow trigger endpoints — v1 /run and /webhook endpoints if you are migrating from or comparing with the v1 API.

Versioned Docs Version 1.11.0 Deployment Deployment Overview (`docs/versioned_docs/version-1.11.0/Deployment/deployment-overview.mdx`) Copy Section

title: Langflow deployment overview slug: /deployment-overview Copy Chapter

This section includes the different ways to bring your locally-built flows to the world.

• To self-host your local server through an ngrok gateway, see Deploy a public Langflow server.
  This approach uses ngrok to forward traffic and share your local Langflow server over the internet, without deploying to a cloud provider or exposing your network directly.

• To build and deploy a Langflow container that includes your flow files, see Containerize a Langflow application.
  This approach bundles your flows and dependencies into a portable, reproducible Docker image for easy deployment across different environments.

• To deploy a Langflow server on a remote server with Docker and Caddy, see Deploy Langflow on a remote server.
  This approach is good for hosting your own Langflow instance on a remote server with secure web access, using Docker containers and Caddy as a reverse proxy for HTTPS support.

• To deploy Langflow with Nginx and automatic SSL certificates, see Deploy Langflow with Nginx and Let's Encrypt.
  This approach uses Nginx as a reverse proxy with Let's Encrypt for automatic HTTPS certificate management to provide a secure deployment without Docker.

• To deploy Langflow on Kubernetes, see Langflow Kubernetes architecture and best practices
  This approach creates production-grade deployments with high availability, scalability, and robust orchestration.

• For cloud provider-specific deployment guides, see your cloud provider's documentation.
  The Langflow documentation provides a few examples, such as Google Cloud Platform and Hugging Face Spaces, to help you get started.

Versioned Docs Version 1.11.0 Develop Authentication Overview (`docs/versioned_docs/version-1.11.0/Develop/authentication-overview.mdx`) Copy Section

title: Authentication and authorization overview slug: /authentication-overview Copy Chapter

Langflow uses authentication to verify who a user is before granting access, and authorization to control what an authenticated user is allowed to do.

Authentication and authorization are configured independently. Most deployments only require authentication. Authorization is an optional plugin that adds role-based access control (RBAC) to your server.

To configure authentication and authorization for your Langflow server, pick your authentication path below and follow the corresponding documentation.

• To secure a Langflow server with user accounts and API keys using Langflow's built-in authentication, see API keys and authentication.
  Built-in authentication is always available and is the default setting. Users log in with a username and password, and Langflow issues a short-lived JWT session token and validates Langflow API keys against its own database.

• To connect Langflow to your company's SSO, OIDC, or identity provider, see External authentication.
  External authentication lets an upstream identity provider, OIDC proxy, or corporate SSO gateway handle login. Langflow accepts the token the proxy forwards, validates it against the identity provider's JWKS endpoint, and provisions a local user automatically.

• To configure RBAC on your Langflow server, see Authorization.
  After a user is authenticated by any of the authentication paths, the authorization layer decides what the user can do.
  RBAC enforcement requires a registered authorization plugin.

When multiple credentials are present, Langflow tries each credential in the order of built-in JWT, external token, and then Langflow API key.

See also Copy Chapter

• Environment variables
• Security

Versioned Docs Version 1.11.0 Flows Concepts Overview (`docs/versioned_docs/version-1.11.0/Flows/concepts-overview.mdx`) Copy Section

title: Use the visual editor slug: /concepts-overview Copy Chapter

import Icon from "@site/src/components/icon";

You use Langflow's visual editor to create, test, and share flows, which are functional representations of application workflows.
Flows consist of components that represent individual steps in your application's workflow.

Langflow's drag-and-drop interface allows you to create complex AI workflows without writing extensive code.
You can connect different resources, including prompts, large language models (LLMs), data sources, agents, MCP servers, and other tools and integrations.

:::tip
To try building and running a flow in a few minutes, see the Langflow quickstart.
:::

Workspace Copy Chapter

When building a flow, you primarily interact with the workspace.
This is where you add components, configure them, and attach them together.

From the workspace, you can also access the Playground, Share menu, and Logs.

Workspace gestures and interactions Copy Section

Use these shortcuts, gestures, and functionality to navigate the workspace:

• Pan horizontally and vertically: Click and drag an empty area of the workspace.

• Rearrange components: Click and drag the components anywhere on the workspace.

  To change the programmatic relationship between components, you must manipulate the component edges or ports. For more information, see Components overview.

  To enable guide lines, click Help, and then toggle Enable smart guides.

  If you can't edit any components, make sure the flow is unlocked.

• Zoom: Scroll on the mouse or trackpad, or click Canvas controls next to the zoom percentage more zoom options: Zoom In, Zoom Out, Zoom To 100%, and Zoom To Fit.

• Add notes and comments: Click Add Note.

• Keyboard shortcuts: To view available shortcuts, click Help, and then select Shortcuts.

Playground Copy Chapter

If your flow has a Chat Input component, you can use the Playground to run your flow, chat with your flow, view inputs and outputs, and modify the LLM's memories to tune the flow's responses in real time.

To try this for yourself, create a flow based on the Simple Agent template, and then click Playground when editing the flow in the workspace.

If you have an Agent component in your flow, the Playground displays its tool calls and outputs so you can monitor the agent's tool use and understand the reasoning behind its responses.

For more information, see Test flows in the Playground.

Share {#share-menu} Copy Chapter

The Share menu provides the following options for integrating your flow into external applications:

• API access: Integrate your flow into your applications with automatically-generated Python, JavaScript, and curl code snippets.

• Export: Export your flow to your local machine as a JSON file.

• MCP Server: Expose your flow as a tool for MCP-compatible clients.

• Embed into site: Embed your flow in HTML, React, or Angular applications.

• Shareable Playground: Share your Playground interface with another user.

  This is specifically for sharing the Playground experience; it isn't for running a flow in a production application.

  The Sharable Playground isn't available for Langflow Desktop.

See also Copy Chapter

• Manage files in Langflow
• Global variables
• API keys and authentication

Versioned Docs Version 1.11.0 Get Started Get Started Quickstart (`docs/versioned_docs/version-1.11.0/Get-Started/get-started-quickstart.mdx`) Copy Section

title: Quickstart slug: /get-started-quickstart Copy Chapter

import Icon from "@site/src/components/icon";
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import PartialGlobalModelProviders from '@site/docs/_partial-global-model-providers.mdx';

Get started with Langflow by loading a template flow, running it, and then serving it at the /run API endpoint.

Prerequisites Copy Chapter

• Install and start Langflow

• Create an OpenAI API key

• Create a Langflow API key

  Create a Langflow API key

  A Langflow API key is a user-specific token you can use with Langflow.

  To create a Langflow API key, do the following:

  1. In Langflow, click your user icon, and then select Settings.

  2. Click Langflow API Keys, and then click Add New.

  3. Name your key, and then click Create API Key.

  4. Copy the API key and store it securely.

  5. To use your Langflow API key in a request, set a LANGFLOW_API_KEY environment variable in your terminal, and then include an x-api-key header or query parameter with your request.
     For example:

     bash Copy

     # Set variable
     export LANGFLOW_API_KEY="sk..."
     
     # Send request
     curl --request POST \
     --url "http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID" \
     --header "Content-Type: application/json" \
     --header "x-api-key: $LANGFLOW_API_KEY" \
     --data '{
       "output_type": "chat",
       "input_type": "chat",
       "input_value": "Hello"
     }'

:::tip
If you encounter the error "An API key must be passed as query or header" when attempting to sign up, see Troubleshooting.
:::

Run the Simple Agent template flow Copy Chapter

1. In Langflow, click New Flow, and then select the Simple Agent template.

The Simple Agent template consists of an Agent component connected to Chat Input and Chat Output components, a Calculator component, and a URL component. When you run this flow, you submit a query to the agent through the Chat Input component, the agent uses the Calculator and URL tools to generate a response, and then returns the response through the Chat Output component.

Many components can be tools for agents, including Model Context Protocol (MCP) servers. The agent decides which tools to call based on the context of a given query.

2. In the Agent component, click Setup Provider to select your language model provider.

3. In the Agent component, select your configured model from the Language Model dropdown.

   Access more models and providers

   There are two ways to access more models and providers:

   • Edit Langflow's global Models configuration. These providers and models are part of Langflow's core functionality. Use the Ollama provider to connect to any model hosted on a local or remote Ollama instance.
   • Connect any additional language model component to the Agent component's Language Model port.

4. To run the flow, click Playground.

5. To test the Calculator tool, ask the agent a simple math question, such as I want to add 4 and 4.
   To help you test and evaluate your flows, the Playground shows the agent's reasoning process as it analyzes the prompt, selects a tool, and then uses the tool to generate a response.
   In this case, a math question causes the agent to select the Calculator tool and use an action like evaluate_expression.

6. To test the URL tool, ask the agent about current events.
   For this request, the agent selects the URL tool's fetch_content action, and then returns a summary of current news headlines.

7. When you are done testing the flow, click Close.

:::tip Next steps
Now that you've run your first flow, try these next steps:

• Edit your Simple Agent flow by attaching different tools or adding more components to the flow.
• Build your own flows from scratch or by modifying other template flows.
• Integrate flows into your applications, as explained in Run your flows from external applications.
  :::

Run your flows from external applications Copy Chapter

Langflow is an IDE, but it's also a runtime you can call through the Langflow API with Python, JavaScript, or HTTP.

When you start Langflow locally, you can send requests to the local Langflow server.
For production applications, you need to deploy a stable Langflow instance to handle API calls.

For example, you can use the /run endpoint to run a flow and get the result.

Langflow provides code snippets to help you get started with the Langflow API.

1. When editing a flow, click Share, and then click API access.

   The default code in the API access pane constructs a request with the Langflow server url, headers, and a payload of request data.
   The code snippets automatically include the LANGFLOW_SERVER_ADDRESS and FLOW_ID values for the flow, and a script to include your LANGFLOW_API_KEY if you've set it as an environment variable in your terminal session.
   Replace these values if you're using the code for a different server or flow.
   The default Langflow server address is http://localhost:7860.

   python Copy

   import requests
   
   url = "http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID"  # The complete API endpoint URL for this flow
   
   # Request payload configuration
   payload = {
       "output_type": "chat",
       "input_type": "chat",
       "input_value": "hello world!"
   }
   
   # Request headers
   headers = {
       "Content-Type": "application/json",
       "x-api-key": "$LANGFLOW_API_KEY"
   }
   
   try:
       # Send API request
       response = requests.request("POST", url, json=payload, headers=headers)
       response.raise_for_status()  # Raise exception for bad status codes
   
       # Print response
       print(response.text)
   
   except requests.exceptions.RequestException as e:
       print(f"Error making API request: {e}")
   except ValueError as e:
       print(f"Error parsing response: {e}")

   js Copy

   const payload = {
       "output_type": "chat",
       "input_type": "chat",
       "input_value": "hello world!",
       "session_id": "user_1"
   };
   
   const options = {
       method: 'POST',
       headers: {
           'Content-Type': 'application/json',
           'x-api-key': 'LANGFLOW_API_KEY'
       },
       body: JSON.stringify(payload)
   };
   
   fetch('http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID', options)
       .then(response => response.json())
       .then(response => console.log(response))
       .catch(err => console.error(err));

   bash Copy

   curl --request POST \
        --url 'http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID?stream=false' \
        --header 'Content-Type: application/json' \
        --header "x-api-key: LANGFLOW_API_KEY" \
        --data '{
         "output_type": "chat",
         "input_type": "chat",
         "input_value": "hello world!"
         }'
   
   # A 200 response confirms the call succeeded.

2. Copy the snippet, paste it in a script file, and then run the script to send the request.
   If you are using the curl snippet, you can run the command directly in your terminal.

If the request is successful, the response includes many details about the flow run, including the session ID, inputs, outputs, components, durations, and more.
The following is an example of a response from running the Simple Agent template flow:

Result

/* Detailed source-code truncated for AI context efficiency. */

In a production application, you probably want to select parts of this response to return to the user, store in logs, and so on. The next steps demonstrate how you can extract data from a Langflow API response to use in your application.

Extract data from the response Copy Section

The following example builds on the API pane's example code to create a question-and-answer chat in your terminal that stores the agent's previous answer.

1. Incorporate your Simple Agent flow's /run snippet into the following script.
   This script runs a question-and-answer chat in your terminal and stores the agent's previous answer so you can compare them.

   text Copy

/* Detailed source-code truncated for AI context efficiency. */

</TabItem>
    <TabItem value="JavaScript" label="JavaScript">

    ```
/* Detailed source-code truncated for AI context efficiency. */

</TabItem>
</Tabs>

2. To view the agent's previous answer, type compare. To close the terminal chat, type exit.

Use tweaks to apply temporary overrides to a flow run Copy Section

You can include tweaks with your requests to temporarily modify flow parameters.
Tweaks are added to the API request, and temporarily change component parameters within your flow.
Tweaks override the flow's components' settings for a single run only.
They don't modify the underlying flow configuration or persist between runs.

Tweaks are added to the /run endpoint's payload.
To assist with formatting, expose the fields you want to override before copying the code snippet.

1. On the canvas, select the component whose parameter you want to override.
2. Click Parameters, and then click API on the field you want to include in the snippet.
3. Click Share > API access.
   Enabling API on a field doesn't permanently change the parameter value. It only adds the field to the sample code snippets.
4. For example, to change the agent's LLM model from OpenAI to Anthropic and include your Anthropic API key with the request, select the Agent component, open Parameters, and enable API on the Language Model field.

Langflow updates the tweaks object in the code snippets based on your exposed parameters, and includes default values to guide you.
Use the updated code snippets in your script to run your flow with your overrides.

payload = {
    "output_type": "chat",
    "input_type": "chat",
    "input_value": "hello world!",
    "tweaks": {
        "Agent-ZOknz": {
            "agent_llm": "Anthropic",
            "api_key": "ANTHROPIC_API_KEY",
            "model_name": "claude-opus-4-5-20251101"
        }
    }
}

Next steps Copy Chapter

• Trigger flows with the Langflow API
• Use Langflow as a Model Context Protocol (MCP) server
• Containerize a Langflow application
• File management

Versioned Docs Version 1.11.0 Lfx Extensions Overview (`docs/versioned_docs/version-1.11.0/Lfx/extensions-overview.mdx`) Copy Section

title: Langflow Extensions overview slug: /extensions-overview Copy Chapter

Langflow ships third-party provider integrations as extensions.
An extension is a pip-installable package that registers components when Langflow starts.

Each extension exposes one or more bundles.
A bundle is a named provider such as openai, qdrant, or duckduckgo.
This bundle is the same group that related components are listed under in the visual editor.

Instead of every integration being built into langflow, you install the extensions you need. Saved flows reference bundles by stable IDs (ext::<Class>@official), not by pip package name, so a provider can move between packages without breaking your flows.

To install extensions and bundle components, see Install LFX with bundle components.

To build your own extension, see Build your first extension.

See also Copy Chapter

• About LFX
• Install LFX
• Bundle list
• Build your first extension
• Manifest reference
• Run flows with LFX
• Serve flows with LFX

Versioned Docs Version 1.11.0 Lfx Extensions Quickstart (`docs/versioned_docs/version-1.11.0/Lfx/extensions-quickstart.mdx`) Copy Section

title: Build your first extension slug: /extensions-quickstart Copy Chapter

Build, validate, and run a Langflow extension that ships a single bundle.
A bundle is a pip-installable package you can publish or load with lfx extension dev.

Prerequisites Copy Chapter

• Python 3.10 or greater
• langflow installed with uv pip install langflow. The lfx CLI provides every command in this guide. For more information, see Install the Langflow OSS package.

Create an extension Copy Chapter

1. Scaffold a new extension:

   bash Copy

   lfx extension init my-extension
   cd my-extension

   This creates the canonical layout the loader expects:

   text Copy

   my-extension/
   ├── extension.json           # the v0 manifest
   ├── pyproject.toml           # so the bundle is pip-installable
   └── src/
       └── lfx_my_extension/
           ├── __init__.py
           ├── extension.json   # symlink/copy used by importlib at runtime
           └── components/
               └── my_bundle/
                   ├── __init__.py
                   └── my_component.py

   For more information, see Manifest reference.

2. To edit the component, open src/lfx_my_extension/components/my_bundle/my_component.py.
   The scaffold ships a working Component subclass that prints "Hello, {name}!"

   python Copy

   from lfx.custom.custom_component.component import Component
   from lfx.io import MessageTextInput, Output
   from lfx.schema.message import Message
   
   class HelloComponent(Component):
       display_name = "Hello"
       description = "Greets the caller."
   
       inputs = [MessageTextInput(name="who", display_name="Who?", value="world")]
       outputs = [Output(display_name="Greeting", name="greeting", method="build_message")]
   
       def build_message(self) -> Message:
           return Message(text=f"Hello, {self.who}!")

   The full surface available to bundle code is enumerated in BUNDLE_API.md.
   Anything outside of BUNDLE_API.md is not part of the API contract, and may move or break between releases.

3. Before launching Langflow, run the static extension checker.

   bash Copy

   lfx extension validate .

   The validator parses the manifest and reports typed errors.
   It does not execute imports by default, so it is safe to run against an extension you just downloaded. Use --execute-imports only when you trust the source — it runs the import probe in a subprocess.

4. Run Langflow with the extension loaded.

   bash Copy

   lfx extension dev .

   This launches a Langflow dev server with my-extension registered at the @official slot. The Hello component appears in the Langflow UI component list under the bundle name in extension.json.

   To see what the loader picked up:

   bash Copy

   lfx extension list --format json

5. Iterate with reload.
   Edit the component, save, then click the Reload action in the palette's bundle header (or run lfx extension reload --bundle my_bundle). The atomic-swap reload pipeline replaces the component in place; in-flight flows keep the pre-swap class so a running execution is never interrupted.

   Reload only works in Mode A (local dev). Production deployments rebuild the Docker image.

6. Ship the extension.

   Once the extension works locally, publish the package to PyPI:

   bash Copy

   python -m build         # builds the wheel + sdist
   twine upload dist/*     # publish to PyPI

   To install the extension into a Langflow environment with a regular pip install:

   bash Copy

   pip install lfx-my-extension
   langflow run

   Discovery happens at server startup.
   The bundle appears in the palette without further configuration.

See also Copy Chapter

• Extensions overview
• Manifest reference
• About LFX
• Run flows with LFX
• Serve flows with LFX

Versioned Docs Version 1.11.0 Lfx Lfx Overview (`docs/versioned_docs/version-1.11.0/Lfx/lfx-overview.mdx`) Copy Section

title: About LFX slug: /lfx-overview Copy Chapter

import Icon from "@site/src/components/icon";

LFX (Langflow Executor) is a lightweight CLI and Python library for running Langflow flows without the full Langflow application.

Flows are built in the Langflow visual builder, and then the flow JSON files are run with LFX.
LFX executes flows statelessly from JSON files with minimal dependencies, no database, and no UI.

LFX is similar to running Langflow with --backend-only, but even more lightweight because the full Langflow package and its dependencies do not need to be installed.

If you're building flows in Langflow with a uv pip install langflow installation, you likely don't need to explore LFX, but if you're deploying and running flows from JSON files using other applications or environments, you'll find LFX is a powerful tool for executing flows.

If you have installed Langflow OSS version 1.6 or later, lfx is already included in your environment.

How LFX differs from Langflow Copy Chapter

In Langflow, you build and test flows in the visual builder, and the full application stores flows, messages, and users in a database.
The same Langflow server already uses LFX as its flow runtime.
Installing LFX on its own decouples the runtime from the Langflow UI and database.
lfx run executes a flow once from the command line and prints the result, and lfx serve exposes one or more flows as persistent HTTP endpoints.
You still author flows in the Langflow visual builder, and export the flows as JSON files.
Standalone LFX is for executing flow JSON files without starting the Langflow server or opening the visual editor.

Under the hood, LFX uses a no-op database interface (NoopSession) instead of a real database. There is no langflow.db file, and stateful operations such as saving flows, storing messages, and managing users do not persist. Operations that depend on langflow.db will not work as they do in the full Langflow application.

LFX commands Copy Chapter

LFX provides two sets of commands:

Runtime commands, to run and serve flows locally:

For the LFX runtime commands, see Run flows with LFX and Serve flows with LFX.

Flow DevOps SDK commands, to version, test, and deploy flows:

For the Flow DevOps SDK commands, see Flow DevOps Toolkit SDK.

See also Copy Chapter

• Install LFX
• Run flows with LFX
• Serve flows with LFX
• Pre-warm LFX
• Build flows with the LFX MCP server
• Flow DevOps Toolkit SDK
• LFX and Langflow version compatibility
• Extensions overview

Versioned Docs Version 1.12.0 API Reference README (`docs/versioned_docs/version-1.12.0/API-Reference/README.md`) Copy Section

API Examples (Local Test Harness)

Run all API example suites against a local Langflow server:

make api_examples_local

Run one test suite:

make api_examples_local suites=python
make api_examples_local suites=javascript
make api_examples_local suites=curl

The following examples are not executed in this harness:

• api-build/build-flow-and-stream-events-2.py
• api-build/build-flow-and-stream-events-3.py
• api-flows-run/stream-llm-token-responses.py
• api-openai-responses/example-streaming-request.py
• api-logs/stream-logs.py
• api-logs/retrieve-logs-with-optional-parameters.py
• api-users/reset-password.py
• workflows-api/example-quickstart-sync.py (and matching .js / .sh; sync mode, read output.text)
• workflows-api/example-quickstart-stream-tokens.py (and matching .js / .sh; stream mode, print token events)
• workflows-api/example-quickstart-background-poll.py (and matching .js / .sh; background queue and poll until completed)
• workflows-api/example-stream-agui-parse.py (and matching .js / .sh; parses AG-UI events and chains two runs)

Versioned Docs Version 1.12.0 API Reference Workflow Api Quickstart (`docs/versioned_docs/version-1.12.0/API-Reference/workflow-api-quickstart.mdx`) Copy Section

title: Workflow API quickstart slug: /workflow-api-quickstart Copy Chapter

import CodeBlock from '@theme/CodeBlock';
import exampleQuickstartSync from '!!raw-loader!@site/docs/API-Reference/curl-examples/workflows-api/example-quickstart-sync.sh';
import examplePythonQuickstartSync from '!!raw-loader!@site/docs/API-Reference/python-examples/workflows-api/example-quickstart-sync.py';
import exampleJavascriptQuickstartSync from '!!raw-loader!@site/docs/API-Reference/javascript-examples/workflows-api/example-quickstart-sync.js';
import exampleQuickstartStreamTokens from '!!raw-loader!@site/docs/API-Reference/curl-examples/workflows-api/example-quickstart-stream-tokens.sh';
import examplePythonQuickstartStreamTokens from '!!raw-loader!@site/docs/API-Reference/python-examples/workflows-api/example-quickstart-stream-tokens.py';
import exampleJavascriptQuickstartStreamTokens from '!!raw-loader!@site/docs/API-Reference/javascript-examples/workflows-api/example-quickstart-stream-tokens.js';
import exampleStreamAguiParse from '!!raw-loader!@site/docs/API-Reference/curl-examples/workflows-api/example-stream-agui-parse.sh';
import examplePythonStreamAguiParse from '!!raw-loader!@site/docs/API-Reference/python-examples/workflows-api/example-stream-agui-parse.py';
import exampleJavascriptStreamAguiParse from '!!raw-loader!@site/docs/API-Reference/javascript-examples/workflows-api/example-stream-agui-parse.js';
import exampleQuickstartBackgroundPoll from '!!raw-loader!@site/docs/API-Reference/curl-examples/workflows-api/example-quickstart-background-poll.sh';
import examplePythonQuickstartBackgroundPoll from '!!raw-loader!@site/docs/API-Reference/python-examples/workflows-api/example-quickstart-background-poll.py';
import exampleJavascriptQuickstartBackgroundPoll from '!!raw-loader!@site/docs/API-Reference/javascript-examples/workflows-api/example-quickstart-background-poll.js';

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import PartialAPISetup from '@site/docs/_partial-api-setup.mdx';

The Workflow API executes Langflow flows over POST /api/v2/workflows in three modes.

Use the default sync mode when you want to wait for the full JSON result in one response. Use stream when you need live Server-Sent Events (SSE) emitted as the flow runs. Use background when you want to queue a job and then poll or re-attach to its event stream.

This quickstart runs the same flow with each mode, so you can use the mode that fits your application.

The examples on this page also expect FLOW_ID to be set to your flow's UUID. Use a chat-style flow (for example Basic Prompting) so output.text contains the assistant reply.

Run a flow synchronously Copy Chapter

Omit mode or set "mode": "sync" to run inline. When the flow finishes, the response includes a top-level output.text field with the primary answer.

Example sync response

{
  "flow_id": "67ccd2be-17f0-8190-81ff-3bb2cf6508e6",
  "session_id": "session-123",
  "object": "response",
  "status": "completed",
  "output": {
    "reason": "single",
    "text": "2 + 2 equals 4.",
    "source": "ChatOutput-xyz"
  },
  "has_errors": false
}

Pass the same session_id on the next request to continue chat history for that conversation.

Stream LLM tokens Copy Chapter

Set "mode": "stream" to open an SSE stream. Choose the wire format with stream_protocol:

• langflow (default): Langflow EventManager frames for existing Langflow clients.
• agui: AG-UI lifecycle events for compatible clients.

For request examples, event types, and protocol details, see Execute flow with selected stream mode in the Workflow API reference.

Langflow EventManager (default) Copy Section

Each data: line is JSON shaped like {"event": "<type>", "data": {...}}. The example below prints only token events (data.chunk) as they arrive.

AG-UI {#ag-ui} Copy Section

Send "stream_protocol": "agui". Each data: line contains one AG-UI event as JSON. The example below handles TEXT_MESSAGE_CONTENT, TOOL_CALL_RESULT, and RUN_FINISHED, extracts a number from the first reply, then chains a follow-up prompt in the same session_id.

Run in the background Copy Chapter

Set "mode": "background" to queue a job and receive a job_id immediately. Poll GET /api/v2/workflows?job_id=… until status is completed, then read output.text from the result.

While a job is still queued or in_progress, the poll endpoint returns a job object (object: "job") with links for status, events, and stop. When the job completes, the same endpoint returns the full execution response.

To connect to a background run, see Re-attach to a background run.

Next steps Copy Chapter

• Workflow API reference — request body fields, response schemas, status polling, stop endpoint, tweaks, globals, and error codes.
• Flow trigger endpoints — v1 /run and /webhook endpoints if you are migrating from or comparing with the v1 API.

Versioned Docs Version 1.12.0 Deployment Deployment Overview (`docs/versioned_docs/version-1.12.0/Deployment/deployment-overview.mdx`) Copy Section

title: Langflow deployment overview slug: /deployment-overview Copy Chapter

This section includes the different ways to bring your locally-built flows to the world.

• To self-host your local server through an ngrok gateway, see Deploy a public Langflow server.
  This approach uses ngrok to forward traffic and share your local Langflow server over the internet, without deploying to a cloud provider or exposing your network directly.

• To build and deploy a Langflow container that includes your flow files, see Containerize a Langflow application.
  This approach bundles your flows and dependencies into a portable, reproducible Docker image for easy deployment across different environments.

• To deploy a Langflow server on a remote server with Docker and Caddy, see Deploy Langflow on a remote server.
  This approach is good for hosting your own Langflow instance on a remote server with secure web access, using Docker containers and Caddy as a reverse proxy for HTTPS support.

• To deploy Langflow with Nginx and automatic SSL certificates, see Deploy Langflow with Nginx and Let's Encrypt.
  This approach uses Nginx as a reverse proxy with Let's Encrypt for automatic HTTPS certificate management to provide a secure deployment without Docker.

• To deploy Langflow on Kubernetes, see Langflow Kubernetes architecture and best practices
  This approach creates production-grade deployments with high availability, scalability, and robust orchestration.

• For cloud provider-specific deployment guides, see your cloud provider's documentation.
  The Langflow documentation provides a few examples, such as Google Cloud Platform and Hugging Face Spaces, to help you get started.

Versioned Docs Version 1.12.0 Develop Authentication Overview (`docs/versioned_docs/version-1.12.0/Develop/authentication-overview.mdx`) Copy Section

title: Authentication and authorization overview slug: /authentication-overview Copy Chapter

Langflow uses authentication to verify who a user is before granting access, and authorization to control what an authenticated user is allowed to do.

Authentication and authorization are configured independently. Most deployments only require authentication. Authorization is an optional plugin that adds role-based access control (RBAC) to your server.

To configure authentication and authorization for your Langflow server, pick your authentication path below and follow the corresponding documentation.

• To secure a Langflow server with user accounts and API keys using Langflow's built-in authentication, see API keys and authentication.
  Built-in authentication is always available and is the default setting. Users log in with a username and password, and Langflow issues a short-lived JWT session token and validates Langflow API keys against its own database.

• To connect Langflow to your company's SSO, OIDC, or identity provider, see External authentication.
  External authentication lets an upstream identity provider, OIDC proxy, or corporate SSO gateway handle login. Langflow accepts the token the proxy forwards, validates it against the identity provider's JWKS endpoint, and provisions a local user automatically.

• To configure RBAC on your Langflow server, see Authorization.
  After a user is authenticated by any of the authentication paths, the authorization layer decides what the user can do.
  RBAC enforcement requires a registered authorization plugin.

When multiple credentials are present, Langflow tries each credential in the order of built-in JWT, external token, and then Langflow API key.

See also Copy Chapter

• Environment variables
• Security

Versioned Docs Version 1.12.0 Flows Concepts Overview (`docs/versioned_docs/version-1.12.0/Flows/concepts-overview.mdx`) Copy Section

title: Use the visual editor slug: /concepts-overview Copy Chapter

import Icon from "@site/src/components/icon";

You use Langflow's visual editor to create, test, and share flows, which are functional representations of application workflows.
Flows consist of components that represent individual steps in your application's workflow.

Langflow's drag-and-drop interface allows you to create complex AI workflows without writing extensive code.
You can connect different resources, including prompts, large language models (LLMs), data sources, agents, MCP servers, and other tools and integrations.

:::tip
To try building and running a flow in a few minutes, see the Langflow quickstart.
:::

Workspace Copy Chapter

When building a flow, you primarily interact with the workspace.
This is where you add components, configure them, and attach them together.

From the workspace, you can also access the Playground, Share menu, and Logs.

Workspace gestures and interactions Copy Section

Use these shortcuts, gestures, and functionality to navigate the workspace:

• Pan horizontally and vertically: Click and drag an empty area of the workspace.

• Rearrange components: Click and drag the components anywhere on the workspace.

  To change the programmatic relationship between components, you must manipulate the component edges or ports. For more information, see Components overview.

  To enable guide lines, click Help, and then toggle Enable smart guides.

  If you can't edit any components, make sure the flow is unlocked.

• Zoom: Scroll on the mouse or trackpad, or click Canvas controls next to the zoom percentage more zoom options: Zoom In, Zoom Out, Zoom To 100%, and Zoom To Fit.

• Add notes and comments: Click Add Note.

• Keyboard shortcuts: To view available shortcuts, click Help, and then select Shortcuts.

Playground Copy Chapter

If your flow has a Chat Input component, you can use the Playground to run your flow, chat with your flow, view inputs and outputs, and modify the LLM's memories to tune the flow's responses in real time.

To try this for yourself, create a flow based on the Simple Agent template, and then click Playground when editing the flow in the workspace.

If you have an Agent component in your flow, the Playground displays its tool calls and outputs so you can monitor the agent's tool use and understand the reasoning behind its responses.

For more information, see Test flows in the Playground.

Share {#share-menu} Copy Chapter

The Share menu provides the following options for integrating your flow into external applications:

• API access: Integrate your flow into your applications with automatically-generated Python, JavaScript, and curl code snippets.

• Export: Export your flow to your local machine as a JSON file.

• MCP Server: Expose your flow as a tool for MCP-compatible clients.

• Embed into site: Embed your flow in HTML, React, or Angular applications.

• Shareable Playground: Share your Playground interface with another user.

  This is specifically for sharing the Playground experience; it isn't for running a flow in a production application.

  The Sharable Playground isn't available for Langflow Desktop.

See also Copy Chapter

• Manage files in Langflow
• Global variables
• API keys and authentication

Versioned Docs Version 1.12.0 Get Started Get Started Quickstart (`docs/versioned_docs/version-1.12.0/Get-Started/get-started-quickstart.mdx`) Copy Section

title: Quickstart slug: /get-started-quickstart Copy Chapter

import Icon from "@site/src/components/icon";
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import PartialGlobalModelProviders from '@site/docs/_partial-global-model-providers.mdx';

Get started with Langflow by loading a template flow, running it, and then serving it at the /run API endpoint.

Prerequisites Copy Chapter

• Install and start Langflow

• Create an OpenAI API key

• Create a Langflow API key

  Create a Langflow API key

  A Langflow API key is a user-specific token you can use with Langflow.

  To create a Langflow API key, do the following:

  1. In Langflow, click your user icon, and then select Settings.

  2. Click Langflow API Keys, and then click Add New.

  3. Name your key, and then click Create API Key.

  4. Copy the API key and store it securely.

  5. To use your Langflow API key in a request, set a LANGFLOW_API_KEY environment variable in your terminal, and then include an x-api-key header or query parameter with your request.
     For example:

     bash Copy

     # Set variable
     export LANGFLOW_API_KEY="sk..."
     
     # Send request
     curl --request POST \
     --url "http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID" \
     --header "Content-Type: application/json" \
     --header "x-api-key: $LANGFLOW_API_KEY" \
     --data '{
       "output_type": "chat",
       "input_type": "chat",
       "input_value": "Hello"
     }'

:::tip
If you encounter the error "An API key must be passed as query or header" when attempting to sign up, see Troubleshooting.
:::

Run the Simple Agent template flow Copy Chapter

1. In Langflow, click New Flow, and then select the Simple Agent template.

The Simple Agent template consists of an Agent component connected to Chat Input and Chat Output components, a Calculator component, and a URL component. When you run this flow, you submit a query to the agent through the Chat Input component, the agent uses the Calculator and URL tools to generate a response, and then returns the response through the Chat Output component.

Many components can be tools for agents, including Model Context Protocol (MCP) servers. The agent decides which tools to call based on the context of a given query.

2. In the Agent component, click Setup Provider to select your language model provider.

3. In the Agent component, select your configured model from the Language Model dropdown.

   Access more models and providers

   There are two ways to access more models and providers:

   • Edit Langflow's global Models configuration. These providers and models are part of Langflow's core functionality. Use the Ollama provider to connect to any model hosted on a local or remote Ollama instance.
   • Connect any additional language model component to the Agent component's Language Model port.

4. To run the flow, click Playground.

5. To test the Calculator tool, ask the agent a simple math question, such as I want to add 4 and 4.
   To help you test and evaluate your flows, the Playground shows the agent's reasoning process as it analyzes the prompt, selects a tool, and then uses the tool to generate a response.
   In this case, a math question causes the agent to select the Calculator tool and use an action like evaluate_expression.

6. To test the URL tool, ask the agent about current events.
   For this request, the agent selects the URL tool's fetch_content action, and then returns a summary of current news headlines.

7. When you are done testing the flow, click Close.

:::tip Next steps
Now that you've run your first flow, try these next steps:

• Edit your Simple Agent flow by attaching different tools or adding more components to the flow.
• Build your own flows from scratch or by modifying other template flows.
• Integrate flows into your applications, as explained in Run your flows from external applications.
  :::

Run your flows from external applications Copy Chapter

Langflow is an IDE, but it's also a runtime you can call through the Langflow API with Python, JavaScript, or HTTP.

When you start Langflow locally, you can send requests to the local Langflow server.
For production applications, you need to deploy a stable Langflow instance to handle API calls.

For example, you can use the /run endpoint to run a flow and get the result.

Langflow provides code snippets to help you get started with the Langflow API.

1. When editing a flow, click Share, and then click API access.

   The default code in the API access pane constructs a request with the Langflow server url, headers, and a payload of request data.
   The code snippets automatically include the LANGFLOW_SERVER_ADDRESS and FLOW_ID values for the flow, and a script to include your LANGFLOW_API_KEY if you've set it as an environment variable in your terminal session.
   Replace these values if you're using the code for a different server or flow.
   The default Langflow server address is http://localhost:7860.

   python Copy

   import requests
   
   url = "http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID"  # The complete API endpoint URL for this flow
   
   # Request payload configuration
   payload = {
       "output_type": "chat",
       "input_type": "chat",
       "input_value": "hello world!"
   }
   
   # Request headers
   headers = {
       "Content-Type": "application/json",
       "x-api-key": "$LANGFLOW_API_KEY"
   }
   
   try:
       # Send API request
       response = requests.request("POST", url, json=payload, headers=headers)
       response.raise_for_status()  # Raise exception for bad status codes
   
       # Print response
       print(response.text)
   
   except requests.exceptions.RequestException as e:
       print(f"Error making API request: {e}")
   except ValueError as e:
       print(f"Error parsing response: {e}")

   js Copy

   const payload = {
       "output_type": "chat",
       "input_type": "chat",
       "input_value": "hello world!",
       "session_id": "user_1"
   };
   
   const options = {
       method: 'POST',
       headers: {
           'Content-Type': 'application/json',
           'x-api-key': 'LANGFLOW_API_KEY'
       },
       body: JSON.stringify(payload)
   };
   
   fetch('http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID', options)
       .then(response => response.json())
       .then(response => console.log(response))
       .catch(err => console.error(err));

   bash Copy

   curl --request POST \
        --url 'http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID?stream=false' \
        --header 'Content-Type: application/json' \
        --header "x-api-key: LANGFLOW_API_KEY" \
        --data '{
         "output_type": "chat",
         "input_type": "chat",
         "input_value": "hello world!"
         }'
   
   # A 200 response confirms the call succeeded.

2. Copy the snippet, paste it in a script file, and then run the script to send the request.
   If you are using the curl snippet, you can run the command directly in your terminal.

If the request is successful, the response includes many details about the flow run, including the session ID, inputs, outputs, components, durations, and more.
The following is an example of a response from running the Simple Agent template flow:

Result

/* Detailed source-code truncated for AI context efficiency. */

In a production application, you probably want to select parts of this response to return to the user, store in logs, and so on. The next steps demonstrate how you can extract data from a Langflow API response to use in your application.

Extract data from the response Copy Section

The following example builds on the API pane's example code to create a question-and-answer chat in your terminal that stores the agent's previous answer.

1. Incorporate your Simple Agent flow's /run snippet into the following script.
   This script runs a question-and-answer chat in your terminal and stores the agent's previous answer so you can compare them.

   text Copy

/* Detailed source-code truncated for AI context efficiency. */

</TabItem>
    <TabItem value="JavaScript" label="JavaScript">

    ```
/* Detailed source-code truncated for AI context efficiency. */

</TabItem>
</Tabs>

2. To view the agent's previous answer, type compare. To close the terminal chat, type exit.

Use tweaks to apply temporary overrides to a flow run Copy Section

You can include tweaks with your requests to temporarily modify flow parameters.
Tweaks are added to the API request, and temporarily change component parameters within your flow.
Tweaks override the flow's components' settings for a single run only.
They don't modify the underlying flow configuration or persist between runs.

Tweaks are added to the /run endpoint's payload.
To assist with formatting, expose the fields you want to override before copying the code snippet.

1. On the canvas, select the component whose parameter you want to override.
2. Click Parameters, and then click API on the field you want to include in the snippet.
3. Click Share > API access.
   Enabling API on a field doesn't permanently change the parameter value. It only adds the field to the sample code snippets.
4. For example, to change the agent's LLM model from OpenAI to Anthropic and include your Anthropic API key with the request, select the Agent component, open Parameters, and enable API on the Language Model field.

Langflow updates the tweaks object in the code snippets based on your exposed parameters, and includes default values to guide you.
Use the updated code snippets in your script to run your flow with your overrides.

payload = {
    "output_type": "chat",
    "input_type": "chat",
    "input_value": "hello world!",
    "tweaks": {
        "Agent-ZOknz": {
            "agent_llm": "Anthropic",
            "api_key": "ANTHROPIC_API_KEY",
            "model_name": "claude-opus-4-5-20251101"
        }
    }
}

Next steps Copy Chapter

• Trigger flows with the Langflow API
• Use Langflow as a Model Context Protocol (MCP) server
• Containerize a Langflow application
• File management

Versioned Docs Version 1.12.0 Lfx Extensions Overview (`docs/versioned_docs/version-1.12.0/Lfx/extensions-overview.mdx`) Copy Section

title: Langflow Extensions overview slug: /extensions-overview Copy Chapter

Langflow ships third-party provider integrations as extensions.
An extension is a pip-installable package that registers components when Langflow starts.

Each extension exposes one or more bundles.
A bundle is a named provider such as openai, qdrant, or duckduckgo.
This bundle is the same group that related components are listed under in the visual editor.

Instead of every integration being built into langflow, you install the extensions you need. Saved flows reference bundles by stable IDs (ext::<Class>@official), not by pip package name, so a provider can move between packages without breaking your flows.

Starting in Langflow 1.12, the default uv pip install langflow installation includes only a curated list of providers. For more information, see Additional bundles.

To install extensions and bundle components, see Install LFX with bundle components.

To build your own extension, see Build your first extension.

See also Copy Chapter

• About LFX
• Install LFX
• Bundle list
• Build your first extension
• Manifest reference
• Run flows with LFX
• Serve flows with LFX

Versioned Docs Version 1.12.0 Lfx Extensions Quickstart (`docs/versioned_docs/version-1.12.0/Lfx/extensions-quickstart.mdx`) Copy Section

title: Build your first extension slug: /extensions-quickstart Copy Chapter

Build, validate, and run a Langflow extension that ships a single bundle.
A bundle is a pip-installable package you can publish or load with lfx extension dev.

Prerequisites Copy Chapter

• Python 3.10 or greater
• langflow installed with uv pip install langflow. The lfx CLI provides every command in this guide. For more information, see Install the Langflow OSS package.

Create an extension Copy Chapter

1. Scaffold a new extension:

   bash Copy

   lfx extension init my-extension
   cd my-extension

   This creates the canonical layout the loader expects:

   text Copy

   my-extension/
   ├── extension.json           # the v0 manifest
   ├── pyproject.toml           # so the bundle is pip-installable
   └── src/
       └── lfx_my_extension/
           ├── __init__.py
           ├── extension.json   # symlink/copy used by importlib at runtime
           └── components/
               └── my_bundle/
                   ├── __init__.py
                   └── my_component.py

   For more information, see Manifest reference.

2. To edit the component, open src/lfx_my_extension/components/my_bundle/my_component.py.
   The scaffold ships a working Component subclass that prints "Hello, {name}!"

   python Copy

   from lfx.custom.custom_component.component import Component
   from lfx.io import MessageTextInput, Output
   from lfx.schema.message import Message
   
   class HelloComponent(Component):
       display_name = "Hello"
       description = "Greets the caller."
   
       inputs = [MessageTextInput(name="who", display_name="Who?", value="world")]
       outputs = [Output(display_name="Greeting", name="greeting", method="build_message")]
   
       def build_message(self) -> Message:
           return Message(text=f"Hello, {self.who}!")

   The full surface available to bundle code is enumerated in BUNDLE_API.md.
   Anything outside of BUNDLE_API.md is not part of the API contract, and may move or break between releases.

3. Before launching Langflow, run the static extension checker.

   bash Copy

   lfx extension validate .

   The validator parses the manifest and reports typed errors.
   It does not execute imports by default, so it is safe to run against an extension you just downloaded. Use --execute-imports only when you trust the source — it runs the import probe in a subprocess.

4. Run Langflow with the extension loaded.

   bash Copy

   lfx extension dev .

   This launches a Langflow dev server with my-extension registered at the @official slot. The Hello component appears in the Langflow UI component list under the bundle name in extension.json.

   To see what the loader picked up:

   bash Copy

   lfx extension list --format json

5. Iterate with reload.
   Edit the component, save, then click the Reload action in the palette's bundle header (or run lfx extension reload --bundle my_bundle). The atomic-swap reload pipeline replaces the component in place; in-flight flows keep the pre-swap class so a running execution is never interrupted.

   Reload only works in Mode A (local dev). Production deployments rebuild the Docker image.

6. Ship the extension.

   Once the extension works locally, publish the package to PyPI:

   bash Copy

   python -m build         # builds the wheel + sdist
   twine upload dist/*     # publish to PyPI

   To install the extension into a Langflow environment with a regular pip install:

   bash Copy

   pip install lfx-my-extension
   langflow run

   Discovery happens at server startup.
   The bundle appears in the palette without further configuration.

See also Copy Chapter

• Extensions overview
• Manifest reference
• About LFX
• Run flows with LFX
• Serve flows with LFX

Versioned Docs Version 1.12.0 Lfx Lfx Overview (`docs/versioned_docs/version-1.12.0/Lfx/lfx-overview.mdx`) Copy Section

title: About LFX slug: /lfx-overview Copy Chapter

import Icon from "@site/src/components/icon";

LFX (Langflow Executor) is a lightweight CLI and Python library for running Langflow flows without the full Langflow application.

Flows are built in the Langflow visual builder, and then the flow JSON files are run with LFX.
LFX executes flows statelessly from JSON files with minimal dependencies, no database, and no UI.

LFX is similar to running Langflow with --backend-only, but even more lightweight because the full Langflow package and its dependencies do not need to be installed.

If you're building flows in Langflow with a uv pip install langflow installation, you likely don't need to explore LFX, but if you're deploying and running flows from JSON files using other applications or environments, you'll find LFX is a powerful tool for executing flows.

If you have installed Langflow OSS version 1.6 or later, lfx is already included in your environment.

How LFX differs from Langflow Copy Chapter

In Langflow, you build and test flows in the visual builder, and the full application stores flows, messages, and users in a database.
The same Langflow server already uses LFX as its flow runtime.
Installing LFX on its own decouples the runtime from the Langflow UI and database.
lfx run executes a flow once from the command line and prints the result, and lfx serve exposes one or more flows as persistent HTTP endpoints.
You still author flows in the Langflow visual builder, and export the flows as JSON files.
Standalone LFX is for executing flow JSON files without starting the Langflow server or opening the visual editor.

Under the hood, LFX uses a no-op database interface (NoopSession) instead of a real database. There is no langflow.db file, and stateful operations such as saving flows, storing messages, and managing users do not persist. Operations that depend on langflow.db will not work as they do in the full Langflow application.

LFX commands Copy Chapter

LFX provides two sets of commands:

Runtime commands, to run and serve flows locally:

For the LFX runtime commands, see Run flows with LFX and Serve flows with LFX.

Flow DevOps SDK commands, to version, test, and deploy flows:

For the Flow DevOps SDK commands, see Flow DevOps Toolkit SDK.

See also Copy Chapter

• Install LFX
• Run flows with LFX
• Serve flows with LFX
• Pre-warm LFX
• Build flows with the LFX MCP server
• Flow DevOps Toolkit SDK
• LFX and Langflow version compatibility
• Extensions overview

Versioned Docs Version 1.8.0 Deployment Deployment Overview (`docs/versioned_docs/version-1.8.0/Deployment/deployment-overview.mdx`) Copy Section

title: Langflow deployment overview slug: /deployment-overview Copy Chapter

This section includes the different ways to bring your locally-built flows to the world.

• To self-host your local server through an ngrok gateway, see Deploy a public Langflow server.
  This approach uses ngrok to forward traffic and share your local Langflow server over the internet, without deploying to a cloud provider or exposing your network directly.

• To build and deploy a Langflow container that includes your flow files, see Containerize a Langflow application.
  This approach bundles your flows and dependencies into a portable, reproducible Docker image for easy deployment across different environments.

• To deploy a Langflow server on a remote server with Docker and Caddy, see Deploy Langflow on a remote server.
  This approach is good for hosting your own Langflow instance on a remote server with secure web access, using Docker containers and Caddy as a reverse proxy for HTTPS support.

• To deploy Langflow with Nginx and automatic SSL certificates, see Deploy Langflow with Nginx and Let's Encrypt.
  This approach uses Nginx as a reverse proxy with Let's Encrypt for automatic HTTPS certificate management to provide a secure deployment without Docker.

• To deploy Langflow on Kubernetes, see Langflow Kubernetes architecture and best practices
  This approach creates production-grade deployments with high availability, scalability, and robust orchestration.

• For cloud provider-specific deployment guides, see your cloud provider's documentation.
  The Langflow documentation provides a few examples, such as Google Cloud Platform and Hugging Face Spaces, to help you get started.

Versioned Docs Version 1.8.0 Flows Concepts Overview (`docs/versioned_docs/version-1.8.0/Flows/concepts-overview.mdx`) Copy Section

title: Use the visual editor slug: /concepts-overview Copy Chapter

import Icon from "@site/src/components/icon";

You use Langflow's visual editor to create, test, and share flows, which are functional representations of application workflows.
Flows consist of components that represent individual steps in your application's workflow.

Langflow's drag-and-drop interface allows you to create complex AI workflows without writing extensive code.
You can connect different resources, including prompts, large language models (LLMs), data sources, agents, MCP servers, and other tools and integrations.

:::tip
To try building and running a flow in a few minutes, see the Langflow quickstart.
:::

Workspace Copy Chapter

When building a flow, you primarily interact with the workspace.
This is where you add components, configure them, and attach them together.

From the workspace, you can also access the Playground, Share menu, and Logs.

Workspace gestures and interactions Copy Section

Use these shortcuts, gestures, and functionality to navigate the workspace:

• Pan horizontally and vertically: Click and drag an empty area of the workspace.

• Rearrange components: Click and drag the components anywhere on the workspace.

  To change the programmatic relationship between components, you must manipulate the component edges or ports. For more information, see Components overview.

  To enable guide lines, click Help, and then toggle Enable smart guides.

  If you can't edit any components, make sure the flow is unlocked.

• Zoom: Scroll on the mouse or trackpad, or click Canvas controls next to the zoom percentage more zoom options: Zoom In, Zoom Out, Zoom To 100%, and Zoom To Fit.

• Add notes and comments: Click Add Note.

• Keyboard shortcuts: To view available shortcuts, click Help, and then select Shortcuts.

Playground Copy Chapter

If your flow has a Chat Input component, you can use the Playground to run your flow, chat with your flow, view inputs and outputs, and modify the LLM's memories to tune the flow's responses in real time.

To try this for yourself, create a flow based on the Simple Agent template, and then click Playground when editing the flow in the workspace.

If you have an Agent component in your flow, the Playground displays its tool calls and outputs so you can monitor the agent's tool use and understand the reasoning behind its responses.

For more information, see Test flows in the Playground.

Share {#share-menu} Copy Chapter

The Share menu provides the following options for integrating your flow into external applications:

• API access: Integrate your flow into your applications with automatically-generated Python, JavaScript, and curl code snippets.

• Export: Export your flow to your local machine as a JSON file.

• MCP Server: Expose your flow as a tool for MCP-compatible clients.

• Embed into site: Embed your flow in HTML, React, or Angular applications.

• Shareable Playground: Share your Playground interface with another user.

  This is specifically for sharing the Playground experience; it isn't for running a flow in a production application.

  The Sharable Playground isn't available for Langflow Desktop.

See also Copy Chapter

• Manage files in Langflow
• Global variables
• API keys and authentication

Versioned Docs Version 1.8.0 Get Started Get Started Quickstart (`docs/versioned_docs/version-1.8.0/Get-Started/get-started-quickstart.mdx`) Copy Section

title: Quickstart slug: /get-started-quickstart Copy Chapter

import Icon from "@site/src/components/icon";
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import PartialGlobalModelProviders from '@site/docs/_partial-global-model-providers.mdx';

Get started with Langflow by loading a template flow, running it, and then serving it at the /run API endpoint.

Prerequisites Copy Chapter

• Install and start Langflow

• Create an OpenAI API key

• Create a Langflow API key

  Create a Langflow API key

  A Langflow API key is a user-specific token you can use with Langflow.

  To create a Langflow API key, do the following:

  1. In Langflow, click your user icon, and then select Settings.

  2. Click Langflow API Keys, and then click Add New.

  3. Name your key, and then click Create API Key.

  4. Copy the API key and store it securely.

  5. To use your Langflow API key in a request, set a LANGFLOW_API_KEY environment variable in your terminal, and then include an x-api-key header or query parameter with your request.
     For example:

     bash Copy

     # Set variable
     export LANGFLOW_API_KEY="sk..."
     
     # Send request
     curl --request POST \
     --url "http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID" \
     --header "Content-Type: application/json" \
     --header "x-api-key: $LANGFLOW_API_KEY" \
     --data '{
       "output_type": "chat",
       "input_type": "chat",
       "input_value": "Hello"
     }'

:::tip
If you encounter the error "An API key must be passed as query or header" when attempting to sign up, see Troubleshooting.
:::

Run the Simple Agent template flow Copy Chapter

1. In Langflow, click New Flow, and then select the Simple Agent template.

The Simple Agent template consists of an Agent component connected to Chat Input and Chat Output components, a Calculator component, and a URL component. When you run this flow, you submit a query to the agent through the Chat Input component, the agent uses the Calculator and URL tools to generate a response, and then returns the response through the Chat Output component.

Many components can be tools for agents, including Model Context Protocol (MCP) servers. The agent decides which tools to call based on the context of a given query.

2. In the Agent component, click Setup Provider to select your language model provider.

3. In the Agent component, select your configured model from the Language Model dropdown.

   Access more models and providers

   There are two ways to access more models and providers:

   • Edit Langflow's global Models configuration. These providers and models are part of Langflow's core functionality. Use the Ollama provider to connect to any model hosted on a local or remote Ollama instance.
   • Connect any additional language model component to the Agent component's Language Model port.

4. To run the flow, click Playground.

5. To test the Calculator tool, ask the agent a simple math question, such as I want to add 4 and 4.
   To help you test and evaluate your flows, the Playground shows the agent's reasoning process as it analyzes the prompt, selects a tool, and then uses the tool to generate a response.
   In this case, a math question causes the agent to select the Calculator tool and use an action like evaluate_expression.

6. To test the URL tool, ask the agent about current events.
   For this request, the agent selects the URL tool's fetch_content action, and then returns a summary of current news headlines.

7. When you are done testing the flow, click Close.

:::tip Next steps
Now that you've run your first flow, try these next steps:

• Edit your Simple Agent flow by attaching different tools or adding more components to the flow.
• Build your own flows from scratch or by modifying other template flows.
• Integrate flows into your applications, as explained in Run your flows from external applications.
  :::

Run your flows from external applications Copy Chapter

Langflow is an IDE, but it's also a runtime you can call through the Langflow API with Python, JavaScript, or HTTP.

When you start Langflow locally, you can send requests to the local Langflow server.
For production applications, you need to deploy a stable Langflow instance to handle API calls.

For example, you can use the /run endpoint to run a flow and get the result.

Langflow provides code snippets to help you get started with the Langflow API.

1. When editing a flow, click Share, and then click API access.

   The default code in the API access pane constructs a request with the Langflow server url, headers, and a payload of request data.
   The code snippets automatically include the LANGFLOW_SERVER_ADDRESS and FLOW_ID values for the flow, and a script to include your LANGFLOW_API_KEY if you've set it as an environment variable in your terminal session.
   Replace these values if you're using the code for a different server or flow.
   The default Langflow server address is http://localhost:7860.

   python Copy

   import requests
   
   url = "http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID"  # The complete API endpoint URL for this flow
   
   # Request payload configuration
   payload = {
       "output_type": "chat",
       "input_type": "chat",
       "input_value": "hello world!"
   }
   
   # Request headers
   headers = {
       "Content-Type": "application/json",
       "x-api-key": "$LANGFLOW_API_KEY"
   }
   
   try:
       # Send API request
       response = requests.request("POST", url, json=payload, headers=headers)
       response.raise_for_status()  # Raise exception for bad status codes
   
       # Print response
       print(response.text)
   
   except requests.exceptions.RequestException as e:
       print(f"Error making API request: {e}")
   except ValueError as e:
       print(f"Error parsing response: {e}")

   js Copy

   const payload = {
       "output_type": "chat",
       "input_type": "chat",
       "input_value": "hello world!",
       "session_id": "user_1"
   };
   
   const options = {
       method: 'POST',
       headers: {
           'Content-Type': 'application/json',
           'x-api-key': 'LANGFLOW_API_KEY'
       },
       body: JSON.stringify(payload)
   };
   
   fetch('http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID', options)
       .then(response => response.json())
       .then(response => console.log(response))
       .catch(err => console.error(err));

   bash Copy

   curl --request POST \
        --url 'http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID?stream=false' \
        --header 'Content-Type: application/json' \
        --header "x-api-key: LANGFLOW_API_KEY" \
        --data '{
         "output_type": "chat",
         "input_type": "chat",
         "input_value": "hello world!"
         }'
   
   # A 200 response confirms the call succeeded.

2. Copy the snippet, paste it in a script file, and then run the script to send the request.
   If you are using the curl snippet, you can run the command directly in your terminal.

If the request is successful, the response includes many details about the flow run, including the session ID, inputs, outputs, components, durations, and more.
The following is an example of a response from running the Simple Agent template flow:

Result

/* Detailed source-code truncated for AI context efficiency. */

In a production application, you probably want to select parts of this response to return to the user, store in logs, and so on. The next steps demonstrate how you can extract data from a Langflow API response to use in your application.

Extract data from the response Copy Section

The following example builds on the API pane's example code to create a question-and-answer chat in your terminal that stores the agent's previous answer.

1. Incorporate your Simple Agent flow's /run snippet into the following script.
   This script runs a question-and-answer chat in your terminal and stores the agent's previous answer so you can compare them.

   text Copy

/* Detailed source-code truncated for AI context efficiency. */

</TabItem>
    <TabItem value="JavaScript" label="JavaScript">

    ```
/* Detailed source-code truncated for AI context efficiency. */

</TabItem>
</Tabs>

2. To view the agent's previous answer, type compare. To close the terminal chat, type exit.

Use tweaks to apply temporary overrides to a flow run Copy Section

You can include tweaks with your requests to temporarily modify flow parameters.
Tweaks are added to the API request, and temporarily change component parameters within your flow.
Tweaks override the flow's components' settings for a single run only.
They don't modify the underlying flow configuration or persist between runs.

Tweaks are added to the /run endpoint's payload.
To assist with formatting, you can define tweaks in Langflow's Input Schema pane before copying the code snippet.

1. To open the Input Schema pane, from the API access pane, click Input Schema.
2. In the Input Schema pane, select the parameter you want to modify in your next request.
   Enabling parameters in the Input Schema pane doesn't permanently change the listed parameters. It only adds them to the sample code snippets.
3. For example, to change the agent's LLM model from OpenAI to Anthropic and include your Anthropic API key with the request, select the Agent component in the Input Schema pane and enable the Language Model field.

Langflow updates the tweaks object in the code snippets based on your input parameters, and includes default values to guide you.
Use the updated code snippets in your script to run your flow with your overrides.

payload = {
    "output_type": "chat",
    "input_type": "chat",
    "input_value": "hello world!",
    "tweaks": {
        "Agent-ZOknz": {
            "agent_llm": "Anthropic",
            "api_key": "ANTHROPIC_API_KEY",
            "model_name": "claude-opus-4-5-20251101"
        }
    }
}

Next steps Copy Chapter

• Trigger flows with the Langflow API
• Use Langflow as a Model Context Protocol (MCP) server
• Containerize a Langflow application
• File management

Versioned Docs Version 1.9.0 API Reference README (`docs/versioned_docs/version-1.9.0/API-Reference/README.md`) Copy Section

API Examples (Local Test Harness)

Run all API example suites against a local Langflow server:

make api_examples_local

Run one test suite:

make api_examples_local suites=python
make api_examples_local suites=javascript
make api_examples_local suites=curl

The following examples are not executed in this harness:

• api-build/build-flow-and-stream-events-2.py
• api-build/build-flow-and-stream-events-3.py
• api-flows-run/stream-llm-token-responses.py
• api-openai-responses/example-streaming-request.py
• api-logs/stream-logs.py
• api-logs/retrieve-logs-with-optional-parameters.py
• api-users/reset-password.py

Versioned Docs Version 1.9.0 Deployment Deployment Overview (`docs/versioned_docs/version-1.9.0/Deployment/deployment-overview.mdx`) Copy Section

title: Langflow deployment overview slug: /deployment-overview Copy Chapter

This section includes the different ways to bring your locally-built flows to the world.

• To self-host your local server through an ngrok gateway, see Deploy a public Langflow server.
  This approach uses ngrok to forward traffic and share your local Langflow server over the internet, without deploying to a cloud provider or exposing your network directly.

• To build and deploy a Langflow container that includes your flow files, see Containerize a Langflow application.
  This approach bundles your flows and dependencies into a portable, reproducible Docker image for easy deployment across different environments.

• To deploy a Langflow server on a remote server with Docker and Caddy, see Deploy Langflow on a remote server.
  This approach is good for hosting your own Langflow instance on a remote server with secure web access, using Docker containers and Caddy as a reverse proxy for HTTPS support.

• To deploy Langflow with Nginx and automatic SSL certificates, see Deploy Langflow with Nginx and Let's Encrypt.
  This approach uses Nginx as a reverse proxy with Let's Encrypt for automatic HTTPS certificate management to provide a secure deployment without Docker.

• To deploy Langflow on Kubernetes, see Langflow Kubernetes architecture and best practices
  This approach creates production-grade deployments with high availability, scalability, and robust orchestration.

• For cloud provider-specific deployment guides, see your cloud provider's documentation.
  The Langflow documentation provides a few examples, such as Google Cloud Platform and Hugging Face Spaces, to help you get started.

Versioned Docs Version 1.9.0 Flows Concepts Overview (`docs/versioned_docs/version-1.9.0/Flows/concepts-overview.mdx`) Copy Section

title: Use the visual editor slug: /concepts-overview Copy Chapter

import Icon from "@site/src/components/icon";

You use Langflow's visual editor to create, test, and share flows, which are functional representations of application workflows.
Flows consist of components that represent individual steps in your application's workflow.

Langflow's drag-and-drop interface allows you to create complex AI workflows without writing extensive code.
You can connect different resources, including prompts, large language models (LLMs), data sources, agents, MCP servers, and other tools and integrations.

:::tip
To try building and running a flow in a few minutes, see the Langflow quickstart.
:::

Workspace Copy Chapter

When building a flow, you primarily interact with the workspace.
This is where you add components, configure them, and attach them together.

From the workspace, you can also access the Playground, Share menu, and Logs.

Workspace gestures and interactions Copy Section

Use these shortcuts, gestures, and functionality to navigate the workspace:

• Pan horizontally and vertically: Click and drag an empty area of the workspace.

• Rearrange components: Click and drag the components anywhere on the workspace.

  To change the programmatic relationship between components, you must manipulate the component edges or ports. For more information, see Components overview.

  To enable guide lines, click Help, and then toggle Enable smart guides.

  If you can't edit any components, make sure the flow is unlocked.

• Zoom: Scroll on the mouse or trackpad, or click Canvas controls next to the zoom percentage more zoom options: Zoom In, Zoom Out, Zoom To 100%, and Zoom To Fit.

• Add notes and comments: Click Add Note.

• Keyboard shortcuts: To view available shortcuts, click Help, and then select Shortcuts.

Playground Copy Chapter

If your flow has a Chat Input component, you can use the Playground to run your flow, chat with your flow, view inputs and outputs, and modify the LLM's memories to tune the flow's responses in real time.

To try this for yourself, create a flow based on the Simple Agent template, and then click Playground when editing the flow in the workspace.

If you have an Agent component in your flow, the Playground displays its tool calls and outputs so you can monitor the agent's tool use and understand the reasoning behind its responses.

For more information, see Test flows in the Playground.

Share {#share-menu} Copy Chapter

The Share menu provides the following options for integrating your flow into external applications:

• API access: Integrate your flow into your applications with automatically-generated Python, JavaScript, and curl code snippets.

• Export: Export your flow to your local machine as a JSON file.

• MCP Server: Expose your flow as a tool for MCP-compatible clients.

• Embed into site: Embed your flow in HTML, React, or Angular applications.

• Shareable Playground: Share your Playground interface with another user.

  This is specifically for sharing the Playground experience; it isn't for running a flow in a production application.

  The Sharable Playground isn't available for Langflow Desktop.

See also Copy Chapter

• Manage files in Langflow
• Global variables
• API keys and authentication

Versioned Docs Version 1.9.0 Get Started Get Started Quickstart (`docs/versioned_docs/version-1.9.0/Get-Started/get-started-quickstart.mdx`) Copy Section

title: Quickstart slug: /get-started-quickstart Copy Chapter

import Icon from "@site/src/components/icon";
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import PartialGlobalModelProviders from '@site/docs/_partial-global-model-providers.mdx';

Get started with Langflow by loading a template flow, running it, and then serving it at the /run API endpoint.

Prerequisites Copy Chapter

• Install and start Langflow

• Create an OpenAI API key

• Create a Langflow API key

  Create a Langflow API key

  A Langflow API key is a user-specific token you can use with Langflow.

  To create a Langflow API key, do the following:

  1. In Langflow, click your user icon, and then select Settings.

  2. Click Langflow API Keys, and then click Add New.

  3. Name your key, and then click Create API Key.

  4. Copy the API key and store it securely.

  5. To use your Langflow API key in a request, set a LANGFLOW_API_KEY environment variable in your terminal, and then include an x-api-key header or query parameter with your request.
     For example:

     bash Copy

     # Set variable
     export LANGFLOW_API_KEY="sk..."
     
     # Send request
     curl --request POST \
     --url "http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID" \
     --header "Content-Type: application/json" \
     --header "x-api-key: $LANGFLOW_API_KEY" \
     --data '{
       "output_type": "chat",
       "input_type": "chat",
       "input_value": "Hello"
     }'

:::tip
If you encounter the error "An API key must be passed as query or header" when attempting to sign up, see Troubleshooting.
:::

Run the Simple Agent template flow Copy Chapter

1. In Langflow, click New Flow, and then select the Simple Agent template.

The Simple Agent template consists of an Agent component connected to Chat Input and Chat Output components, a Calculator component, and a URL component. When you run this flow, you submit a query to the agent through the Chat Input component, the agent uses the Calculator and URL tools to generate a response, and then returns the response through the Chat Output component.

Many components can be tools for agents, including Model Context Protocol (MCP) servers. The agent decides which tools to call based on the context of a given query.

2. In the Agent component, click Setup Provider to select your language model provider.

3. In the Agent component, select your configured model from the Language Model dropdown.

   Access more models and providers

   There are two ways to access more models and providers:

   • Edit Langflow's global Models configuration. These providers and models are part of Langflow's core functionality. Use the Ollama provider to connect to any model hosted on a local or remote Ollama instance.
   • Connect any additional language model component to the Agent component's Language Model port.

4. To run the flow, click Playground.

5. To test the Calculator tool, ask the agent a simple math question, such as I want to add 4 and 4.
   To help you test and evaluate your flows, the Playground shows the agent's reasoning process as it analyzes the prompt, selects a tool, and then uses the tool to generate a response.
   In this case, a math question causes the agent to select the Calculator tool and use an action like evaluate_expression.

6. To test the URL tool, ask the agent about current events.
   For this request, the agent selects the URL tool's fetch_content action, and then returns a summary of current news headlines.

7. When you are done testing the flow, click Close.

:::tip Next steps
Now that you've run your first flow, try these next steps:

• Edit your Simple Agent flow by attaching different tools or adding more components to the flow.
• Build your own flows from scratch or by modifying other template flows.
• Integrate flows into your applications, as explained in Run your flows from external applications.
  :::

Run your flows from external applications Copy Chapter

Langflow is an IDE, but it's also a runtime you can call through the Langflow API with Python, JavaScript, or HTTP.

When you start Langflow locally, you can send requests to the local Langflow server.
For production applications, you need to deploy a stable Langflow instance to handle API calls.

For example, you can use the /run endpoint to run a flow and get the result.

Langflow provides code snippets to help you get started with the Langflow API.

1. When editing a flow, click Share, and then click API access.

   The default code in the API access pane constructs a request with the Langflow server url, headers, and a payload of request data.
   The code snippets automatically include the LANGFLOW_SERVER_ADDRESS and FLOW_ID values for the flow, and a script to include your LANGFLOW_API_KEY if you've set it as an environment variable in your terminal session.
   Replace these values if you're using the code for a different server or flow.
   The default Langflow server address is http://localhost:7860.

   python Copy

   import requests
   
   url = "http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID"  # The complete API endpoint URL for this flow
   
   # Request payload configuration
   payload = {
       "output_type": "chat",
       "input_type": "chat",
       "input_value": "hello world!"
   }
   
   # Request headers
   headers = {
       "Content-Type": "application/json",
       "x-api-key": "$LANGFLOW_API_KEY"
   }
   
   try:
       # Send API request
       response = requests.request("POST", url, json=payload, headers=headers)
       response.raise_for_status()  # Raise exception for bad status codes
   
       # Print response
       print(response.text)
   
   except requests.exceptions.RequestException as e:
       print(f"Error making API request: {e}")
   except ValueError as e:
       print(f"Error parsing response: {e}")

   js Copy

   const payload = {
       "output_type": "chat",
       "input_type": "chat",
       "input_value": "hello world!",
       "session_id": "user_1"
   };
   
   const options = {
       method: 'POST',
       headers: {
           'Content-Type': 'application/json',
           'x-api-key': 'LANGFLOW_API_KEY'
       },
       body: JSON.stringify(payload)
   };
   
   fetch('http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID', options)
       .then(response => response.json())
       .then(response => console.log(response))
       .catch(err => console.error(err));

   bash Copy

   curl --request POST \
        --url 'http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID?stream=false' \
        --header 'Content-Type: application/json' \
        --header "x-api-key: LANGFLOW_API_KEY" \
        --data '{
         "output_type": "chat",
         "input_type": "chat",
         "input_value": "hello world!"
         }'
   
   # A 200 response confirms the call succeeded.

2. Copy the snippet, paste it in a script file, and then run the script to send the request.
   If you are using the curl snippet, you can run the command directly in your terminal.

If the request is successful, the response includes many details about the flow run, including the session ID, inputs, outputs, components, durations, and more.
The following is an example of a response from running the Simple Agent template flow:

Result

/* Detailed source-code truncated for AI context efficiency. */

In a production application, you probably want to select parts of this response to return to the user, store in logs, and so on. The next steps demonstrate how you can extract data from a Langflow API response to use in your application.

Extract data from the response Copy Section

The following example builds on the API pane's example code to create a question-and-answer chat in your terminal that stores the agent's previous answer.

1. Incorporate your Simple Agent flow's /run snippet into the following script.
   This script runs a question-and-answer chat in your terminal and stores the agent's previous answer so you can compare them.

   text Copy

/* Detailed source-code truncated for AI context efficiency. */

</TabItem>
    <TabItem value="JavaScript" label="JavaScript">

    ```
/* Detailed source-code truncated for AI context efficiency. */

</TabItem>
</Tabs>

2. To view the agent's previous answer, type compare. To close the terminal chat, type exit.

Use tweaks to apply temporary overrides to a flow run Copy Section

You can include tweaks with your requests to temporarily modify flow parameters.
Tweaks are added to the API request, and temporarily change component parameters within your flow.
Tweaks override the flow's components' settings for a single run only.
They don't modify the underlying flow configuration or persist between runs.

Tweaks are added to the /run endpoint's payload.
To assist with formatting, you can define tweaks in Langflow's Input Schema pane before copying the code snippet.

1. To open the Input Schema pane, from the API access pane, click Input Schema.
2. In the Input Schema pane, select the parameter you want to modify in your next request.
   Enabling parameters in the Input Schema pane doesn't permanently change the listed parameters. It only adds them to the sample code snippets.
3. For example, to change the agent's LLM model from OpenAI to Anthropic and include your Anthropic API key with the request, select the Agent component in the Input Schema pane and enable the Language Model field.

Langflow updates the tweaks object in the code snippets based on your input parameters, and includes default values to guide you.
Use the updated code snippets in your script to run your flow with your overrides.

payload = {
    "output_type": "chat",
    "input_type": "chat",
    "input_value": "hello world!",
    "tweaks": {
        "Agent-ZOknz": {
            "agent_llm": "Anthropic",
            "api_key": "ANTHROPIC_API_KEY",
            "model_name": "claude-opus-4-5-20251101"
        }
    }
}

Next steps Copy Chapter

• Trigger flows with the Langflow API
• Use Langflow as a Model Context Protocol (MCP) server
• Containerize a Langflow application
• File management

DEPRECATED MACOS SUPPORT INVESTIGATION (`docs/DEPRECATED_MACOS_SUPPORT_INVESTIGATION.md`) Copy Section

Investigation: Deprecated macOS Support — Impact on Langflow

Date: 2026-04-02
Status: Complete
Related: PyTorch macOS x86_64 + Python 3.13 (resolved in PR #12469)

TL;DR Copy Chapter

macOS Intel (x86_64) is in its final phase of deprecation across the entire ecosystem — Apple hardware, operating system, GitHub Actions runners, PyTorch, and the broader ML/AI stack. Langflow already has platform exclusion markers for the most critical torch-dependent extras (PR #12469), but additional deprecations in GitHub Actions runners, macOS versions, and upstream dependencies will require further action over the next 12–18 months.

Key decision required: Set a timeline to officially drop macOS x86_64 from Langflow's support matrix (recommended: Langflow 2.0 or Q4 2026, whichever comes first).

1. Deprecation Landscape Copy Chapter

1.1 Apple Hardware & OS Timeline Copy Section

Key fact: Apple's Rosetta 2 translates x86_64 binaries on Apple Silicon, but native ARM64 builds are preferred. Rosetta support for macOS is expected to continue but individual frameworks (e.g., Metal 3) are ARM-only.

1.2 GitHub Actions Runner Deprecation Copy Section

Key fact: macos-latest-large is the only Intel x86_64 runner available. It is one of the most expensive GitHub Actions runners. GitHub has signaled the shift toward ARM-only macOS runners.

1.3 PyTorch macOS x86_64 Deprecation Copy Section

Result: No PyTorch wheel exists for macOS x86_64 + Python ≥ 3.13. PyTorch 2.2.2 is the last version with Intel Mac support, and it only covers Python 3.10–3.12.

1.4 Broader ML Ecosystem Copy Section

2. Current State of Langflow macOS Support Copy Chapter

2.1 Platform Exclusion Markers in `pyproject.toml` Copy Section

The following extras have platform markers excluding macOS x86_64 (as of PR #12469):

Extras with NO macOS exclusion that still work on Intel:

2.2 macOS-Specific Runtime Workarounds Copy Section

2.3 CI Matrix Coverage Copy Section

3. Impact Assessment Copy Chapter

3.1 What Works on macOS x86_64 Today Copy Section

Langflow core functionality (flow builder, API, database, all non-ML components) works on macOS Intel with Python 3.10–3.13. The following features are unavailable:

• ALTK (Agent Lifecycle Toolkit) components
• HuggingFace/sentence-transformers embeddings
• EasyOCR
• Docling document processing (binary; docling-core metadata still works)
• MLX inference
• Metal GPU acceleration
• CUGA

This is acceptable because Intel Macs lack the GPU capabilities (Metal 3, Neural Engine) that make these ML features performant.

3.2 What Will Break Next Copy Section

3.3 CI Cost Exposure Copy Section

macos-latest-large (Intel x86_64) is the most expensive runner in the matrix:

• GitHub Actions pricing: macOS large runners cost ~$0.12/min (10× Linux)
• Current usage: 4 stable jobs + 1 experimental job = 5 Intel Mac CI jobs per workflow run
• Estimated cost: ~$15–25 per full CI run for Intel Mac jobs alone

4. Recommendations Copy Chapter

4.1 Immediate (No Action Needed) Copy Section

PR #12469 has already addressed the most critical issue:

• ✅ altk and langchain-huggingface excluded on macOS x86_64
• ✅ docling and easyocr already excluded (pre-existing)
• ✅ mlx, cuga are ARM64-only
• ✅ Experimental CI uses continue-on-error: true

4.2 Short-Term (Langflow 1.10 / Q2 2026) Copy Section

~~R1: Add `platform_machine` marker to `metal` extra~~ — NOT NEEDED

metal_sdk is the SDK for getmetal.io (a cloud vector search/embedding service), not Apple's Metal GPU framework. It's a pure Python package (py3-none-any.whl) with no platform-specific dependencies. No marker change needed.

R2: Reduce macOS Intel CI to Python 3.12 only

Remove the Python 3.10 stable test on macOS AMD64. Python 3.12 is the most commonly deployed version and provides sufficient coverage:

# Remove from stable matrix:
# - os: macos
#   arch: amd64
#   runner: macos-latest-large
#   python-version: "3.10"

Saves: ~$5–7 per CI run, reduces alert noise.

R3: Document macOS support matrix in user-facing docs

Add a support matrix page to docs/ clarifying which features require Apple Silicon vs. work on Intel, so users have clear expectations.

4.3 Medium-Term (Langflow 2.0 / Q4 2026) Copy Section

R4: Drop macOS x86_64 from CI entirely

Once GitHub deprecates macos-latest-large or macOS 26 ships:

1. Remove all macos-latest-large entries from cross-platform-test.yml
2. Remove the brew install protobuf step (only needed for Intel runners)
3. Keep macos-latest (ARM64) as the sole macOS test target

Saves: ~$15–25 per CI run. Reduces matrix complexity.

R5: Audit and clean up OBJC fork safety workaround

The OBJC_DISABLE_INITIALIZE_FORK_SAFETY workaround in __main__.py and langflow_launcher.py applies to all macOS, not just Intel. However, once Intel is dropped:

• Verify if the issue persists on Apple Silicon with current gunicorn/uvicorn
• If ARM64-only deployments don't trigger the issue, consider removing the workaround
• If still needed, keep it but document why

R6: Officially deprecate macOS x86_64 in release notes

Add a deprecation notice in the Langflow 2.0 release notes:

macOS Intel (x86_64) support is deprecated. Langflow 2.0 is the last version tested on Intel Macs. Future releases will only be tested on Apple Silicon (ARM64). Core functionality may continue to work, but ML features require Apple Silicon.

4.4 Long-Term (Langflow 2.x+ / 2027) Copy Section

R7: Remove all macOS x86_64 platform markers

Once Intel Mac support is officially dropped, simplify pyproject.toml by removing the platform_machine != 'x86_64' guards — they become unnecessary clutter:

# Before (with Intel exclusion)
altk = ["agent-lifecycle-toolkit>=0.10.1,<1.0; sys_platform != 'darwin' or platform_machine != 'x86_64'"]

# After (Intel dropped from support matrix)
altk = ["agent-lifecycle-toolkit>=0.10.1,<1.0"]

R8: Evaluate ARM64-only macOS features

With Intel out of the picture, lean into Apple Silicon capabilities:

• MLX-based local inference as a first-class feature
• Metal GPU acceleration for embedding generation
• Neural Engine integration for on-device ML
• CoreML model support via ONNX Runtime CoreML EP

5. Risk Matrix Copy Chapter

6. Recommended macOS Support Matrix Copy Chapter

Current (Langflow 1.9.x) Copy Section

Proposed (Langflow 2.0+) Copy Section

7. Summary of Action Items Copy Chapter

Appendix A: Complete Platform Marker Inventory Copy Chapter

All sys_platform and platform_machine markers in src/backend/base/pyproject.toml:

Line  53: jq         → sys_platform != 'win32'
Line  96: ocrmac     → sys_platform == 'darwin'                    (root pyproject.toml)
Line 258: metal      → (no marker — correct; getmetal.io cloud SDK, not Apple Metal)
Line 293: altk       → sys_platform != 'darwin' or platform_machine != 'x86_64'
Line 297: langchain-huggingface → sys_platform != 'darwin' or platform_machine != 'x86_64'
Line 310: docling    → sys_platform != 'darwin' or platform_machine != 'x86_64'
Line 312: easyocr    → sys_platform != 'darwin' or platform_machine != 'x86_64'
Line 327: cuga       → sys_platform != 'darwin' (non-Mac) + sys_platform == 'darwin' and platform_machine == 'arm64' (Mac ARM)
Line 331: mlx        → sys_platform == 'darwin' and platform_machine == 'arm64' and python_version >= '3.12'
Line 345: gassist    → sys_platform == 'win32'

Appendix B: Related Issues & PRs Copy Chapter

TORCH MACOS AMD64 PYTHON313 INVESTIGATION (`docs/TORCH_MACOS_AMD64_PYTHON313_INVESTIGATION.md`) Copy Section

Investigation: PyTorch on macOS AMD64 (x86_64) + Python 3.13

Date: 2026-04-02
Status: Complete

TL;DR Copy Chapter

PyTorch officially dropped macOS x86_64 (Intel) binary support after version 2.2.2 (milestone: PyTorch 2.3, March 2024). Since Python 3.13 was released in October 2024 — after this cutoff — no official PyTorch wheel exists for macOS x86_64 + Python 3.13. This is an upstream, permanent gap — not a bug in Langflow.

The failing CI job is test-installation-experimental on macos-latest-large (AMD64) with Python 3.13. The continue-on-error: true flag means it doesn't block releases, but the failure is persistent and expected.

Root Cause Analysis Copy Chapter

1. PyTorch macOS x86_64 Deprecation Timeline Copy Section

Key fact: PyTorch 2.2.2 has macOS x86_64 wheels for Python 3.10, 3.11, 3.12 — but not 3.13. And PyTorch 2.3+ does not publish macOS x86_64 wheels at all.

2. What the UV Resolver Does Copy Section

When resolving for macOS x86_64 + Python 3.13, the uv lockfile shows:

torch 2.2.2        → Python < 3.13, macOS x86_64  (has wheels: cp310, cp311, cp312)
torch 2.2.2+cpu    → Python >= 3.13, macOS x86_64  (NO WHEELS listed!)
torch 2.10.0       → macOS arm64 (all Python versions)
torch 2.10.0+cpu   → Linux/Windows (all Python versions)

The resolver picks torch 2.2.2+cpu for macOS x86_64 + Python 3.13, but this version has zero available wheels for that platform. Installation fails because there's no compatible binary.

3. How Torch Gets Pulled In Copy Section

The main langflow package depends on langflow-base[complete], which includes multiple extras that transitively require torch:

Dependency Chains to Torch

The ALTK extra is the primary unguarded path that forces torch installation on macOS x86_64. The issue was initially noticed with ALTK but the root cause is PyTorch's platform support.

4. Existing Mitigations Copy Section

The codebase already excludes some torch-dependent packages on macOS x86_64:

# src/backend/base/pyproject.toml
docling = [
    "docling-core>=2.36.1,<3.0.0",
    "docling>=2.36.1,<3.0.0; sys_platform != 'darwin' or platform_machine != 'x86_64'",
]
easyocr = ["easyocr>=1.7.2,<2.0.0; sys_platform != 'darwin' or platform_machine != 'x86_64'"]

However, ALTK and langchain-huggingface (which depends on sentence-transformers → torch) have no such platform exclusion.

5. CI Configuration Copy Section

The experimental job in .github/workflows/cross-platform-test.yml:

• Tests Python 3.13 on all platforms including macOS AMD64
• Uses continue-on-error: true so failures don't block releases
• The test-summary job considers experimental failures "acceptable"

Recommendations Copy Chapter

Option A: Exclude torch-dependent extras on macOS x86_64 (Recommended) Copy Section

Add platform markers to all extras that transitively depend on torch, similar to what's done for easyocr:

# In src/backend/base/pyproject.toml
altk = ["agent-lifecycle-toolkit~=0.4.4; sys_platform != 'darwin' or platform_machine != 'x86_64'"]
langchain-huggingface = ["langchain-huggingface==0.3.1; sys_platform != 'darwin' or platform_machine != 'x86_64'"]

Pros:

• CI will pass on all experimental platforms
• macOS x86_64 users on Python 3.13 can still use Langflow (just without ALTK/HuggingFace features)
• Consistent with existing pattern for docling/easyocr

Cons:

• Reduces feature availability on macOS x86_64
• All Python versions on macOS x86_64 lose these features (not just 3.13)

Option B: Add Python version + platform compound markers Copy Section

More surgical approach — only exclude on the exact broken combination:

altk = ["agent-lifecycle-toolkit~=0.4.4; (sys_platform != 'darwin' or platform_machine != 'x86_64' or python_version < '3.13')"]

Pros:

• Preserves functionality on macOS x86_64 + Python 3.10-3.12
• Only excludes the broken combination

Cons:

• More complex markers
• PEP 508 marker evaluation of compound OR conditions can be tricky across tools

Option C: Remove macOS AMD64 from experimental CI matrix (Simplest) Copy Section

Since macOS x86_64 is a dying platform (Apple stopped selling Intel Macs in 2022), remove it from CI:

# Remove this entry from the experimental matrix:
# - os: macos
#   arch: amd64
#   runner: macos-latest-large
#   python-version: "3.13"

Pros:

• Simplest fix (one line change)
• Saves CI runner costs (macos-latest-large is expensive)
• Reflects reality that macOS Intel is EOL

Cons:

• Loses visibility into macOS x86_64 regressions
• Some users may still be on Intel Macs

Option D: Keep as-is (Status Quo) Copy Section

The experimental job already uses continue-on-error: true and the test-summary job reports it as acceptable. This failure is a known, documented limitation.

Pros:

• No code changes needed
• Maintains CI visibility

Cons:

• Persistent red CI job creates alert fatigue
• Could mask other real failures in the experimental matrix

Recommendation Copy Chapter

Option A + Option C combined is the strongest approach:

1. Add platform exclusion markers to altk and langchain-huggingface extras for macOS x86_64 (Option A). This prevents installation failures for end users on Intel Macs.

2. Optionally remove macOS AMD64 from the Python 3.13 experimental matrix (Option C) to reduce CI costs and noise, since the platform is EOL from both Apple and PyTorch.

The combination ensures both end-user experience and CI health. The feature loss on macOS Intel is acceptable because:

• Apple stopped producing Intel Macs in June 2022
• PyTorch dropped Intel Mac support in March 2024
• The HuggingFace/ML ecosystem is rapidly moving to ARM-only on macOS

Appendix: Affected Lockfile Entries Copy Chapter

torch versions resolved by platform Copy Section

torchvision versions resolved by platform Copy Section

Agents ANTI PATTERNS (`docs/agents/ANTI-PATTERNS.md`) Copy Section

Anti-Patterns and Scar Tissue

These are battle scars. Every rule here cites a real recurring failure: a commit, a revert, or an explicit project lesson. Read this file when you're about to "just" change something — most of the don't/do rules below started as a one-line "small fix" that broke production.

Don't / Do (with why) Copy Chapter

1. Don't add or rename a field on a component without regenerating starter projects AND the component index.
   Why: commits 1a9f4548c, 5987421bd, bbe1dad7c, 69d29a4c6, 67af71450, 4f9beebc0 are all fix: commits cleaning up the same "I added a field and shipped" mistake. CI (9dad1965c) now syncs the index on label addition — that's a backstop, not a substitute.

2. Don't rename a component class, display name, or module path. If unavoidable, add the new component alongside the old one, set legacy = True + replacement = ["<category>.<NewClassName>"] on the old class, and update every supported version's file_names_mapping in tests.
   Why: class names key saved flows. There is no class-rename map in setup.py — the type_migrations map there only handles output type strings (Data → JSON, DataFrame → Table). See 2a7c56e84 (IngestionDescriberComponent → FileDescriptionGeneratorComponent) and f5a0d52197 (starter project rename) for the cleanup churn. See CONTRACTS.md for the full list.

3. Don't mock at a different boundary than production calls. If production uses subprocess.Popen, mock Popen — not run.
   Why: a747135d1, bc433c375 — mocked tests passed; production failed. Better: don't mock at all — project policy is "Avoid mocking in tests." Use real integrations or MockLanguageModel for pure-logic LLM paths.

4. Don't write a Graph test by poking internals.
   Why: the canonical pattern is build → connect via .set() → call async_start → iterate results → validate. Tests that bypass this don't exercise the graph the way users do.

5. Don't add a retry, broaden an except, or widen a type to make a symptom go away.
   Why: "It is not a fix if you didn't have evidence of the change fixing something." See revert chain 9cdbf1b23, 35aad2f2e, e3b90b7351 — fixes that masked rather than solved, then had to be reverted.

6. Don't bump a dependency speculatively. Confirm the conflict reproduces locally and the new version actually resolves it.
   Why: cf659f0d0, ef6a303406, 38d142a72, 9029c4b61 — repeated dep-conflict cleanup.

7. Don't invent model IDs, MCP tool names, or API surface. Read the registry, the batch dispatcher, and models.py first.
   Why: 9f1402ed9 (remove fictional gpt-5.3 ids), cecc4a6c2 (expose layout tool as layout_flow to match batch dispatch).

8. Don't use raw langflow run / python when a uv command exists. Always uv run. For lfx tests specifically: uv sync inside src/lfx (not src/lfx/src/lfx) to avoid pulling in langflow.
   Why: lfx must be testable without langflow installed; mixing them masks dependency leaks.

9. Don't add a database migration without running make alembic-upgrade end to end and uv run pytest src/backend/tests/unit/test_database.py sequentially.
   Why: d8b9cc38f, c30150a2d, 6585fe661. test_database.py may pass in batch and fail individually — agents have stopped running it.

10. Don't claim a race condition is fixed without an integration test that reproduced it. Agent double-execution and queue leaks keep coming back.
    Why: 8a993ac90, 42e84d0fd, 749865b31, f30b291f8.

11. Don't add tool_mode=True to outputs that confuse agents (e.g., dataframe surfaces).
    Why: cbc54108 (remove tool_mode=True for as_dataframe), 35aad2f2e (revert of the original disable). Output tool exposure is a user contract — don't toggle it back and forth.

12. Don't widen the scope of a PR. Closely related follow-ups belong in the existing open PR, not a new stacked PR.

13. Don't ship without running the tests locally. Typing the test command in the chat is not running it.

14. Don't make incremental "wip" commits. One coherent commit per logical change, after everything is done and tested.

15. Don't push or open PRs without explicit user confirmation. Pushing during active CI iteration on an already-open PR is fine; opening a new PR or pushing new branches is not.

Things that look like a fix but aren't Copy Chapter

• Adding try/except Exception: pass around a flaky call.
• Adding a time.sleep to dodge a race instead of awaiting a condition.
• Bumping a dependency version "just in case."
• Marking a failing test @pytest.mark.skip without a linked issue.
• Switching # type: ignore instead of fixing the type.
• Reverting symptoms (a UI flag, a tool flag) instead of finding the root.
• "Fixing" a test by changing its assertion to match wrong output.

Before claiming done Copy Chapter

• make format_backend and make lint clean.
• Tests for the changed surface ran and passed locally — not just typed out.
• If a component field/output changed: starter projects regenerated and component_index.json rebuilt.
• If a class/module renamed: old class kept with legacy=True + replacement=[...]; file_names_mapping updated for every supported version.
• No incremental "wip" commits. One coherent commit per logical change.
• No "Generated with Claude Code" / Co-Authored-By: Claude trailers.
• No --no-verify unless explicitly authorized.
• PR not pushed and PR not opened until the user explicitly asks.
• PR description has no test-plan checklist, no Jira links/IDs.

Where to look for context — don't invent it Copy Chapter

• Starter projects: src/backend/base/langflow/initial_setup/starter_projects/. Any field/output change must regenerate these.
• Component index: src/lfx/src/lfx/_assets/component_index.json (rebuilt via the index sync workflow added in 9dad1965c).
• Output type migrations: src/backend/base/langflow/initial_setup/setup.py type_migrations map — handles renames of output type strings (e.g., Data → JSON). It does NOT remap component class names; for class renames use legacy=True + replacement=[...].
• Version mapping for component tests: src/backend/tests/constants.py::SUPPORTED_VERSIONS and each test's file_names_mapping.
• Release notes / changelog: docs/docs/Support/release-notes/ — check before claiming behavior is "new"; many features predate the current task.
• MCP tool catalog: dispatched via the batch tool — names must match (cecc4a6c2 is the canonical "I guessed the tool name" failure).
• Models / providers: real model IDs come from the provider's listing endpoint or our adapter, never from training-data memory (9f1402ed9).
• Migrations: src/backend/base/langflow/alembic/versions/ — always read the latest two before adding a new one.

Agents ARCHITECTURE (`docs/agents/ARCHITECTURE.md`) Copy Section

Architecture Boundaries

Langflow is a runnable base application, a curated distribution, an executor
SDK, standalone extensions, and one frontend. Dependencies point in one
direction. Most "off-narrative" code is a boundary violation. Read this before
adding a new file.

Package dependency graph (one-way only) Copy Chapter

frontend (TS)  ──HTTP──▶  langflow-base (UI/API, services, graph, db, alembic)
                                   │
                                   ▼ may import
                               lfx (executor, primitives, built-in components)
                                   │
                                   ▼ may import
                               langchain-core, pydantic

langflow (curated distribution) ──depends on──▶ langflow-base
             │
             └──depends on──▶ standalone lfx-* extensions ──depends on──▶ lfx

Dependency rules Copy Section

• lfx MUST NOT import langflow.*. (langflow-base installs the
  langflow import package.) If LFX code needs a service, define an interface
  inside lfx and inject the implementation from the application. Existing
  upward imports are known violations; do not add more.
• langflow-base MAY import lfx. It MUST NOT import vendor-specific component modules from langflow.components.<vendor>.
• Standalone lfx-* extensions MAY import the public LFX bundle API. They
  MUST NOT import application services from langflow-base.
• langflow is dependency metadata, not another application layer. It adds
  the curated extension set to the same langflow-base executable and runtime.
• frontend talks to langflow only via HTTP/WebSocket. No shared filesystem state.

"Where does this code go?" decision tree Copy Chapter

Walk top-down. Stop at the first match.

1. Is it framework-agnostic flow execution, base component classes, or Component primitives?
   → src/lfx/src/lfx/ (base/ for shared primitives, components/ for built-ins shipped with lfx).
2. Is it a FastAPI route, auth, db model, alembic migration, or a lifecycle-managed singleton?
   → src/backend/base/langflow/ (api/, services/X/, alembic/versions/).
3. Is it a vendor integration (OpenAI, Pinecone, Notion, …) — a Component subclass that wraps a third-party SDK?
   → a standalone package under src/bundles//, with an extension.json manifest. Add it to the curated langflow dependencies only when it belongs in the default distribution. Never rename the component class.
4. Is it UI, state, or icons?
   → src/frontend/src/. If it consumes a new API field, also update src/frontend/src/types/.
5. Is it CLI behavior for lfx run / lfx serve?
   → src/lfx/src/lfx/cli/.
6. Is it a SQLAlchemy/SQLModel model change?
   → services/database/models/ AND make alembic-revision message="..." AND apply with make alembic-upgrade.
7. Is it a flow JSON schema change?
   → STOP. Existing saved flows must keep loading. Add a version mapping; do not mutate the existing shape. See CONTRACTS.md.
8. Is it shared by both lfx and langflow-base?
   → src/lfx/src/lfx/base/, never langflow/base/.

Dependency direction — bad/good examples Copy Chapter

• Bad: from langflow.services.deps import session_scope inside src/lfx/....
  Good: Define lfx.interfaces.SessionProvider, accept it as a constructor arg; langflow wires the concrete session_scope at startup.
• Bad: from langflow.components.openai import ... inside langflow-base core (api/, services/, graph/).
  Good: Components are loaded dynamically via the component registry; core code references Component only.
• Bad: A new MyHelperService that's just functions.
  Good: Utility functions go in langflow/helpers/ or lfx/utils/. A service inherits from services/base.Service and is registered via services/factory.py.

API change protocol Copy Chapter

• api/v1/ is the live, stable surface (~25 routers). Existing v1 endpoints MUST stay backwards-compatible: only additive fields, never rename or remove.
• api/v2/ is the active redesign surface (files, mcp, registration, workflow) — both are mounted at runtime in api/router.py. v2 is not "future"; the old cursor rule was wrong.
• Add a new endpoint to v2 only if it (a) replaces a v1 endpoint with a breaking shape change, or (b) belongs to one of the four v2 domains. Otherwise extend v1 additively.
• A breaking change to a v1 endpoint is forbidden. Add a v2 sibling and leave v1 in place.

Cross-cutting change protocol Copy Chapter

A change that touches a request/response shape MUST update three places in the same PR:

1. The pydantic model in langflow/api/v{1,2}/schemas.py (or the route's local schema).
2. The TypeScript type in src/frontend/src/types/ consumed by the affected page/store. There is no OpenAPI generator — the types are hand-maintained, so the frontend silently breaks at runtime if you skip this.
3. If the field is persisted: a new alembic revision (make alembic-revision message=...) AND a flow-JSON version mapping if the shape lives inside saved flows.

If you cannot do all three in one PR, do not start.

Service vs utility vs component Copy Chapter

• Service (services/<name>/): lifecycle-managed singleton, inherits services.base.Service, registered through services/factory.py, accessed via services/deps.py. Use when the thing has state, startup/shutdown, or shared connections (db, cache, queue).
• Utility (helpers/, utils/, or lfx/utils/): pure or near-pure functions. Use when there is no shared state and no lifecycle.
• Component (src/lfx/src/lfx/components/<category>/): user-visible node in the graph, subclass of Component, with display_name, inputs, outputs. Use only when the user must wire it on the canvas. Do not add a Component to expose internal plumbing.

`lfx/base/` vs `langflow/base/` Copy Chapter

Both exist. Both have agents/, data/, models/, prompts/. New shared primitives go in src/lfx/src/lfx/base/. The langflow/base/ tree is legacy; do not add to it.

Agents COMPONENTS (`docs/agents/COMPONENTS.md`) Copy Section

Component Development

Components are the unit of work in Langflow. They render as nodes on the canvas, persist into flow JSON, and become tools for Agents. Get the contract right and the rest of the system follows; get it wrong and you orphan every saved flow that referenced your component.

Components live in src/lfx/src/lfx/components/<category>/. The mirror tree under src/backend/base/langflow/components/ is legacy stubs — do not add files there.

Before you add a component (decision checklist) Copy Chapter

Stop and check, in order. If any answer is "yes," do not create a new component.

1. Does one already exist? Search:
   bash Copy

   rg -l 'display_name = ".*<keyword>.*"' src/lfx/src/lfx/components/

   and check the category folder. The Calculator regret (two of them, see tools/calculator.py legacy = True, replacement = ["utilities.CalculatorComponent"]) is what happens when this step is skipped.
2. Is this a thin wrapper around an existing tool/SDK that an Agent could call directly via tool_mode=True? If yes, add tool_mode=True to the relevant input on the existing component instead of building a new one.
3. Does it belong in a vendor bundle (e.g., openai/, anthropic/, datastax/) rather than in generic tools/ or helpers/? Vendor logic goes in vendor folders so bundles can ship/version independently.
4. Is this an lfx-runtime concern (graph execution, schema, IO primitives) or a Langflow-app concern (auth, DB, tracing)? Components are lfx; never import langflow.services.* from a component.
5. Does an existing base class cover this category? Use it:
   • LLMs → LCModelComponent (see openai/openai_chat_model.py)
   • Tools → LCToolComponent (see tools/calculator.py)
   • Vector stores → LCVectorStoreComponent + @check_cached_vector_store (see vectorstores/local_db.py)
   • Chat IO → ChatComponent (see input_output/chat.py)

Scope rules (one component, one job) Copy Chapter

• One job per component. If the description has " and " in it, split it.
• Inputs budget: aim for ≤8 visible inputs; push the rest behind advanced=True. If you need a mode switch (Ingest/Retrieve etc.), use TabInput + update_build_config to hide irrelevant fields — see vectorstores/local_db.py.
• Outputs: one primary Output(method=...) is the default. Add more only if downstream nodes genuinely need different shapes (Message vs DataFrame vs Data). Don't add an output you don't use.
• Mark inputs an Agent should be able to fill with tool_mode=True (e.g., local_db.py) — this is how a component becomes an agent tool.

Breaking-change list (locked once shipped) Copy Chapter

Saved flows reference components by string identifiers. Once a component is merged, the following are frozen — change them and existing user flows break silently:

• The class name (already in our rules).
• The name = "..." class attribute. This is the flow-JSON identifier, not the class name. See openai_chat_model.py, chat.py.
• Each input name=.... Renaming input_value → prompt orphans every edge pointing at it.
• Each output name=... and its declared return type. Downstream nodes match on both.
• Default values and default behavior of existing inputs (a flow saved with the default re-loads with the new default).

To remove or rework a component, do not edit it in place. Add the replacement under the right category, then on the old one set:

legacy = True
replacement = ["<category>.<NewClassName>"]

(see tools/calculator.py, flow_controls/sub_flow.py). The UI shows "Updates Available" and migrates users; the old class stays importable.

See CONTRACTS.md for the full user-facing surface this protects.

Conventions agents miss Copy Chapter

These appear all over the codebase but rarely in old docs.

• name (class attr): flow-JSON identifier. Always set it explicitly; do not rely on __class__.__name__. Example: chat.py name = "ChatInput".
• legacy = True + replacement = [...]: deprecation pair. Always together. Example: tools/calculator.py.
• tool_mode=True on an input: exposes the component as an Agent tool with that input as the tool argument. Example: vectorstores/local_db.py.
• real_time_refresh=True + update_build_config(self, build_config, value, name): dynamic form. Use for mode switches and dependent-field hide/show. Examples: openai/openai_chat_model.py, vectorstores/local_db.py.
• metadata = {"keywords": [...]}: extra search terms for the component picker. Example: data_source/sql_executor.py.
• minimized = True: render collapsed by default. Example: input_output/chat.py.
• documentation = "https://docs.langflow.org/...": deep-link from the node UI. Example: input_output/chat.py.

Placement rules Copy Chapter

• Vendor-specific code → vendor folder (openai/, anthropic/, datastax/, cohere/, …). Not tools/, not models/.
• Generic, vendor-agnostic helpers → helpers/, processing/, logic/, flow_controls/.
• IO primitives → input_output/.
• Add the import to the category __init__.py in alphabetical order.
• Do not invent a new top-level category. If you think you need one, that is a signal to discuss with the team first — categories are visible in the UI sidebar and are part of the product surface.

Icons Copy Chapter

Every component needs an icon. Use a Lucide icon when one fits; create a custom SVG only for vendor logos.

Lucide icon (default) Copy Section

icon = "calculator"  # any Lucide icon name, lowercase

See https://lucide.dev/icons for the catalog.

Custom vendor icon Copy Section

For brand logos you need a frontend SVG component. The Python icon string and the frontend mapping key must match exactly (case-sensitive).

1. Python: set icon = "AstraDB" on the component.
2. Frontend SVG component at src/frontend/src/icons/AstraDB/AstraDB.jsx:
   jsx Copy

   const AstraSVG = (props) => (
     <svg {...props}>
       <path fill={props.isDark ? "#ffffff" : "#0A0A0A"} d="..." />
     </svg>
   );

3. Wrapper at src/frontend/src/icons/AstraDB/index.tsx:
   tsx Copy

   import React, { forwardRef } from "react";
   import AstraSVG from "./AstraDB";
   
   export const AstraDBIcon = forwardRef<SVGSVGElement, React.PropsWithChildren<{}>>(
     (props, ref) => <AstraSVG ref={ref} isDark={isDark} {...props} />
   );

4. Lazy import in src/frontend/src/icons/lazyIconImports.ts:
   ts Copy

   AstraDB: () =>
     import("@/icons/AstraDB").then((mod) => ({ default: mod.AstraDBIcon })),

5. Verify in the UI in both light and dark mode.

Icon checklist Copy Section

• Python icon = "..." set.
• If custom: SVG component with isDark prop, wrapper with forwardRef, entry in lazyIconImports.ts.
• Light and dark mode both verified.

Component testing Copy Chapter

See TESTING.md for the full testing contract. Quick reference:

• Inherit from ComponentTestBaseWithClient (needs API) or ComponentTestBaseWithoutClient (pure logic).
• Provide three fixtures: component_class, default_kwargs, file_names_mapping. The inherited test_latest_version runs every output offline with default_kwargs; list outputs that need the network in the optional skipped_outputs fixture, with the reason.
• Use MockLanguageModel for pure-logic LLM paths; use @pytest.mark.api_key_required for real-API tests.
• For graph behavior, use the Graph test pattern: build, .set(), async_start, validate. Do not poke graph internals.

Canonical examples Copy Chapter

When in doubt, read these files before starting:

• LLM with dynamic provider switching: src/lfx/src/lfx/components/openai/openai_chat_model.py
• Tool with tool_mode and legacy/replacement: src/lfx/src/lfx/components/tools/calculator.py
• Vector store with cache + tab inputs: src/lfx/src/lfx/components/vectorstores/local_db.py
• Chat input with minimized: src/lfx/src/lfx/components/input_output/chat.py
• Component with searchable metadata: src/lfx/src/lfx/components/data_source/sql_executor.py
• Legacy + replacement pattern: src/lfx/src/lfx/components/flow_controls/sub_flow.py

Agents CONTRACTS (`docs/agents/CONTRACTS.md`) Copy Section

User-Facing Contracts

These are the surfaces users depend on. Breaking them silently is the most common way an agent ships work that "doesn't connect to the story." Read this before changing anything below.

The contract surface Copy Chapter

Before-you-change matrix Copy Chapter

Breaking changes that look harmless Copy Chapter

These all look like cleanup. They are user-visible regressions.

• Renaming input_value → text on a component: 100% of saved flows referencing that input lose their wiring.
• Reordering outputs = [a, b] to [b, a]: old flows with the default selection now route from the wrong output.
• Tightening Output(types=["Message", "Data"]) → ["Message"]: edges that resolved as Data go invalid on load.
• Changing a default="gpt-4o-mini" to default="gpt-5": silently re-bills users.
• Moving langflow/components/foo/bar.py → langflow/components/foo2/bar.py: custom components stored in user DBs that from langflow.components.foo.bar import ... fail on next load. file_names_mapping test passes because it only validates listed historical versions, not user code.
• Dropping tool_mode=True from a vector store's as_dataframe: every Agent that called it as a tool now sees the tool disappear.
• Adding a required field to Message: every queued message in a running deployment fails to deserialize on next read.
• Renaming a starter project file: deep links from docs and tutorials 404.

Why this matters Copy Chapter

Langflow flows are persisted user artifacts running in production. The system that loads them is forgiving by design: it tolerates new fields, falls back on missing ones, applies type migrations on load. That tolerance is paid for by every contract in the table above. Break one and the system can no longer route around it — the flow stops working.

Treat this file as a checklist. If your change touches any row, the corresponding rule applies; no exceptions without an explicit deprecation plan.

Agents PHILOSOPHY (`docs/agents/PHILOSOPHY.md`) Copy Section

Project Philosophy

Read this file before scoping any non-trivial work. Most off-narrative work comes from skipping it.

Langflow is a visual flow builder first. Every change should make sense to someone whose only interface is dragging nodes onto a canvas. Use these principles to scope work; if a proposed change fails one of them, stop and reconsider.

Tenets Copy Chapter

1. Flows are user artifacts, not implementation details. Flow JSON lives in users' databases and runs in production. Backwards compatibility for components is non-negotiable: never rename a class name, name attribute, input name, or output name; never remove an input or output; never tighten an output type; never remove methods from base classes like LCModelComponent. To change a component, add the new one alongside, set legacy=True + replacement=[...] on the old, and update file_names_mapping in tests so saved flows still load. See CONTRACTS.md for the full surface.

2. Every backend feature must land on the canvas. If a capability cannot be expressed as a component (or a property of one) that a non-Python user can wire up, it is an SDK feature and belongs in lfx, not langflow-base. Backend changes that have no visual surface are almost always off-narrative.

3. Components are the unit of work, not endpoints or services. Before adding a route, store, or service, ask: which component does this serve? If the answer is "none yet," the route is premature. New REST endpoints without a component or UI consumer are off-narrative.

4. lfx is the runtime, langflow-base is the platform, langflow is the distribution. Components and the graph engine live in lfx (src/lfx/src/lfx/components/). API, auth, persistence, and multi-user concerns live in langflow-base. The langflow package is the integration that ships everything together. New code goes in the lowest layer that can host it. Boundaries are enforced one-way: langflow → langflow-base → lfx. See ARCHITECTURE.md.

5. Don't add a config flag for something a builder-user would set on a node. If a setting affects flow behavior, it's a component input. If it affects deployment, it's an env var. Hidden global flags that change component semantics break the visible-data-flow contract.

6. Visible data flow beats clever magic. Implicit context, hidden globals, and side-channel state make flows unreadable on the canvas. Pass data through inputs and outputs. If you find yourself reaching for a global, you're probably building something that doesn't belong in a node.

7. Composition over capability. Prefer adding small, single-purpose components users can wire together over one large component with many modes. The If-Else / Current Date style (one job, clear name, obvious icon) is the target shape.

8. Every component needs display_name, description, icon, and a sensible category. A component that doesn't render legibly in the sidebar shouldn't ship. The icon is part of the API, not decoration — pick a Lucide icon that matches the verb.

9. The Playground is the test harness builder-users see. A component is "done" when it works end-to-end in a flow on the canvas, not when its unit test passes. Use the Graph test pattern (build, .set(), async_start, validate) before claiming a feature works.

10. Two audiences, one product: visual builders and Python devs. When their needs conflict, the visual builder wins for langflow-base features and the Python dev wins for lfx SDK features. Don't compromise the canvas to make the SDK prettier, and don't compromise the SDK to make the canvas easier.

11. It is not a fix if you didn't have evidence of the change fixing something. Adding error handling, retries, type widening, or skipping a flaky test does not constitute a fix. Reproduce the failure, demonstrate the fix removes it, then ship. See ANTI-PATTERNS.md.

How to apply Copy Chapter

When scoping a task, walk through the tenets and name the ones the work serves. If a change fails tenet 1, 2, or 3, stop and surface the conflict before writing code. If you can't tell which tenet a change serves, it's probably off-narrative — ask.

Agents TESTING (`docs/agents/TESTING.md`) Copy Section

Testing

Conventions for backend tests. Frontend testing follows the standard Jest/Playwright patterns documented in src/frontend/.

Project policy: avoid mocking Copy Chapter

Prefer real integrations. The pattern of "mocked test passes, production fails" has cost us multiple release cycles — see ANTI-PATTERNS.md for the relevant commit history. Use mocks only when:

• The dependency is an LLM and the test exercises pure logic → use MockLanguageModel from tests/unit/mock_language_model.py.
• The dependency is genuinely unreliable and orthogonal to what's being tested.

Otherwise: hit the real thing, mark the test with @pytest.mark.api_key_required if it needs credentials, and let CI gate it.

Built-in fixtures Copy Chapter

`client` (FastAPI test client) Copy Section

Defined in src/backend/tests/conftest.py. Async httpx.AsyncClient connected to the full app via ASGITransport + LifespanManager. Auto-configured with in-memory SQLite and mocked env vars. Skip with @pytest.mark.noclient.

async def test_login_endpoint(client):
    response = await client.post("api/v1/login", data={"username": "foo", "password": "bar"})
    assert response.status_code == 200

For authenticated routes, also use the logged_in_headers fixture.

Component test base classes Copy Chapter

Located in src/backend/tests/base.py.

Required fixtures Copy Section

Every subclass provides three fixtures:

1. component_class — the component class under test.
2. default_kwargs — dict of kwargs to instantiate the component (can be empty).
3. file_names_mapping — list of VersionComponentMapping entries mapping each historical Langflow version (from src/backend/tests/constants.py::SUPPORTED_VERSIONS) to module/file names. Use DID_NOT_EXIST for versions before the component was added.

from tests.base import ComponentTestBaseWithClient, VersionComponentMapping, DID_NOT_EXIST
from langflow.components.my_namespace import MyComponent

class TestMyComponent(ComponentTestBaseWithClient):
    @pytest.fixture
    def component_class(self):
        return MyComponent

    @pytest.fixture
    def default_kwargs(self):
        return {"foo": "bar"}

    @pytest.fixture
    def file_names_mapping(self):
        return [
            VersionComponentMapping(version="1.1.1", module="my_module", file_name="my_component.py"),
            VersionComponentMapping(version="1.0.19", module="my_module", file_name=DID_NOT_EXIST),
        ]

The base class auto-provides:

• test_latest_version — builds the component from source and calls run() as an unconnected vertex, so every output method runs. It fails if any output returns None or if the component exposes no outputs. It runs offline: a non-loopback socket connect is refused and fails the test, even when the component catches the error and returns a fallback.
• test_all_versions_have_a_file_name_defined — ensures mapping completeness vs SUPPORTED_VERSIONS.
• test_component_versions (parameterized) — builds the component from source for each supported version and asserts execution.

If an output cannot run offline with default_kwargs (it calls a live provider or service, needs real credentials, or needs state the unit suite does not set up), prefer mocking the external call. If that is impractical, override the optional skipped_outputs fixture to name the output and the reason. The harness rejects names the component does not have, and a component whose outputs are all skipped reports as skipped, not passed.

@pytest.fixture
    def skipped_outputs(self):
        return {"text_output": "sends the prompt to a live LLM"}

For components that build outputs dynamically with update_outputs, override component_setup and call await self.map_frontend_outputs(component, field_name, value).

If you rename or move a component file, you must update file_names_mapping for every supported version, or saved flows on those versions will fail to load. See CONTRACTS.md row 3.

Graph testing pattern Copy Chapter

The canonical pattern for tests that exercise the graph engine:

1. Build the graph with connected components.
2. Connect them via .set() calls.
3. Call async_start and iterate over the results.
4. Validate the results.

Don't poke graph internals. If a test needs to reach into private state, the test is wrong or the API is wrong — fix the right one.

Async patterns Copy Chapter

@pytest.mark.asyncio
async def test_async_component():
    result = await component.async_method()
    assert result is not None

Awaiting conditions, not sleeping: never use time.sleep or asyncio.sleep to mask a race. Wait on a condition (asyncio.wait_for, an event, a queue read with timeout). Sleep-based tests are flaky by construction.

Pytest markers Copy Chapter

• @pytest.mark.api_key_required — needs an external API key; CI skips when absent.
• @pytest.mark.no_blockbuster — skip blockbuster plugin.
• @pytest.mark.noclient — skip the client fixture.
• @pytest.mark.asyncio — async test (also pytest-asyncio auto-mode in some configs).

Database tests Copy Chapter

test_database.py may fail in batch and pass individually. If you touch DB models or migrations, run it sequentially as part of your verification:

uv run pytest src/backend/tests/unit/test_database.py

Never edit a past alembic migration. Run make alembic-upgrade end-to-end before claiming a migration works.

API endpoint tests Copy Chapter

async def test_flows_endpoint(client, logged_in_headers):
    flow_data = {"name": "Test", "data": {"nodes": [], "edges": []}}
    response = await client.post("api/v1/flows/", json=flow_data, headers=logged_in_headers)
    assert response.status_code == 201

For event-stream endpoints, consume the NDJSON stream and validate event order:

async for line in response.aiter_lines():
    if not line:
        continue
    parsed = json.loads(line)
    # First event should be vertices_sorted; last should be end.

Flow testing with starter JSON Copy Chapter

Use tests/unit/build_utils.py helpers:

from tests.unit.build_utils import create_flow, build_flow, get_build_events

flow_id = await create_flow(client, json_flow, logged_in_headers)
build_response = await build_flow(client, flow_id, logged_in_headers)
events_response = await get_build_events(client, job_id, logged_in_headers)

Running tests Copy Chapter

make unit_tests                              # All backend unit tests, parallel
make unit_tests async=false                  # Sequential
uv run pytest path/to/test.py                # Single file
uv run pytest path/to/test.py::test_name     # Single test

# lfx tests specifically — must be run after `uv sync` inside src/lfx
cd src/lfx && uv sync && uv run pytest

Verification checklist before claiming "tests pass" Copy Chapter

• You actually ran the command, not just composed it.
• You ran test_database.py sequentially if you touched DB code.
• You ran the specific test file for any component you changed.
• No skipped tests without a linked issue.
• No mocks added at the wrong boundary.

Development Sqlite Kb Controller (`docs/development/sqlite-kb-controller.md`) Copy Section

Managed SQLite upgrade controller

The 1.13 controller stops the selected old worker family, verifies a metadata
backup and maintenance receipt, starts the new application, and waits for its migration-aware readiness endpoint. Existing
vectors are migrated automatically by the application's storage coordinator
using the bundled reader. Docker, cosign and a separate helper release are not
required. The controller uses the same supported formats and resource limits as
the automatic upgrade.

This controller supports one host, local storage and a SQLite application
metadata database. Run it as the non-root application account, from outside
the old supervisor's session. The old application must have a foreground
supervisor that is the leader of its own dedicated POSIX session. All API,
background and Memory workers must remain in that session. Windows services,
container orchestrators, distributed workers, PostgreSQL metadata and workers
that detach into other sessions require their deployment-specific controller.
The controller fails closed when it cannot inspect a worker or listener.

Disable the service manager's external restart policy before invoking this
command and keep it disabled throughout migration. --external-restarts-disabled
records this explicit operator contract. The controller cannot prove that an
external manager will not recreate a terminated service. Do not point it at a
shared login shell, a machine-wide service manager or an unrelated process.

Install 1.13 into a clean environment, retaining the original data paths and
application configuration. Root-owned private files must be transferred to the
application account through the deployment manager rather than made public.

Obtain the old foreground supervisor PID from its deployment manager, then get
its exact creation time using the new environment's installed psutil:

/path/to/1.13/bin/python -c 'import psutil, sys; print(psutil.Process(int(sys.argv[1])).create_time())' 12345

Copy the full printed value into --supervisor-created. Do not use ps -o lstart,
which rounds away the required precision. Linux journal identities additionally
retain kernel start ticks and boot ID so clock adjustments cannot invalidate a
paused family. Run the controller from the new environment:

/path/to/1.13/bin/python -m langflow.services.knowledge_base_storage.controller \
  --root /absolute/knowledge-bases \
  --database /absolute/langflow.db \
  --state /private/upgrade-1.13 \
  --supervisor-pid 12345 \
  --supervisor-created 1234567890.0 \
  --cwd /absolute/application-directory \
  --port 7860 \
  --external-restarts-disabled \
  -- /path/to/1.13/bin/python -m langflow run --host 127.0.0.1 --port 7860

The PID and creation time in this example are placeholders. Never guess them.
The command after -- is an argument vector, executed directly without a shell.
It must remain in the foreground and honor the existing instance configuration.
Pass credentials through the application's normal private environment or secret
configuration, not command arguments, because the private journal records argv.
The controller explicitly sets the knowledge-base root, SQLite metadata URL and
maintenance receipt in the new process's environment.
Do not override those paths with CLI arguments or a different configuration file.

Before shutdown, the controller suspends the exact supervisor, inventories and
suspends its entire session, and durably records every PID and creation time.
Only then does it terminate those recorded identities. After the graceful stop
period (30 seconds by default), it kills remaining matching workers and verifies
that the family exited. PID reuse, escaped sessions and unexpected workers stop
the upgrade. Failure before the stop is committed resumes workers suspended by
the controller. After the stop is committed, it leaves the old service stopped
and preserves the journal for forward recovery.

The maintenance verifier creates and checks a consistent SQLite metadata backup,
fingerprints every legacy source, and writes a private receipt. The new process
is launched only after this barrier. It records its own identity atomically
before executing the application, so resuming after a parent-controller crash
cannot launch a second instance. The controller command uses an IPv4 loopback listener. Readiness requires both a successful
/healthz?require_storage_ready=true
response and a listening socket owned by that exact new supervisor's session.
An unrelated healthy service on the port cannot satisfy the gate.

A private application.log captures the new process output. Backup and source
files remain retained.

Resume and forward repair Copy Chapter

Re-run the same command with the same state directory after interruption.
The journal binds the host, old supervisor identity, data paths and command.
Completed shutdown and backup steps are reused. A running new application is observed instead of launched again. A readiness timeout leaves
it available for the authenticated administration and migration retry APIs.
Fix the reported issue and re-run the controller to observe readiness.

If the new process has exited, inspect the private application log first.
Re-run the same command with --restart-new to explicitly restart the selected
new application. The old source is never automatically restarted, and the
pre-upgrade metadata backup is never restored automatically. Once new writes
have happened, recovery must continue forward. Keep external old-version
restarts disabled and hand the recorded new supervisor PID back to the service
manager only after readiness succeeds.

If the controller is killed while workers are suspended, resume using the same
state directory. It recovers the dedicated session and its shutdown journal.
Do not delete the journal or substitute a new state directory. Preserve failed
backup attempts for diagnosis. A different deployment topology needs its own
shutdown proof rather than bypassing the maintenance receipt checks.

Recent MCP stdio tools can leave subprocesses in separate sessions for several
minutes. The controller refuses these escaped sessions before stopping the app.
Stop using stdio tools and let their cached subprocesses expire before preparing
the upgrade, or stop the complete deployment through its deployment manager.

Development Sqlite Kb Qualification (`docs/development/sqlite-kb-qualification.md`) Copy Section

SQLite upgrade qualification evidence

This ledger records the local qualification of the 1.13.0 transition on
2026-10-01. It supports review of the implementation and does not assert that a
application release or security closure already exists. The separate container
helper described in the original qualification has since been retired. Both
automatic and managed upgrades now use the bundled reader.
See the upgrade design and
managed controller instructions for supported scope.

Completed local checks Copy Chapter

The original combined storage, controller, cleanup, helper and application suite
passed all 320 tests before helper retirement. Those counts are historical.
The affected bundle/component retirement suite passed 16 tests, and bundle structural discovery passed for 72 providers in the local
test environment. The universal dependency export contains none of the three
retired SDKs.

The process-death and capacity tests use disposable databases and exact child
processes. SQLITE_FULL is induced with SQLite's max_page_count, not by filling
the host disk. It exposed and verified a fix for an error-handling bug: an
implicit SQLite rollback must not be followed by a second rollback that masks
the original error. These checks establish transaction/replay behavior, not
power-loss durability of every supported filesystem or storage device.

Controller and native failure checks ran on macOS ARM64, Python 3.14.3. The
controller requires a non-root POSIX application account, a dedicated foreground
supervisor session, disabled external restarters, local storage and SQLite
application metadata. A native wheel matrix does not extend controller support
to Windows services, distributed deployments or PostgreSQL metadata.

Measured local search workloads Copy Chapter

Measurements use scripts/benchmark/sqlite_kb.py, deterministic precomputed
float32 vectors and five searches per filter. The exact self-match was checked
on every query. Document embedding and network time are excluded.

Host: macOS 27.0.1 ARM64, Python 3.14.3. Other qualification work ran concurrently
on this host. These are observed measurements, not an SLO, capacity limit or
isolated performance comparison. The first query is not a cold OS-cache probe.
Storage sizes below use decimal MB.

Reproduce in the Chroma-free application environment:

uv run --no-sync python scripts/benchmark/sqlite_kb.py --rows 100000 --dimensions 384 --runs 5
uv run --no-sync python scripts/benchmark/sqlite_kb.py --rows 10000 --dimensions 1536 3072 --runs 5

These workloads do not qualify near-limit 8 GiB source migrations, sustained
multi-user load, every metadata-filter distribution or network filesystems.

Remaining release gates Copy Chapter

The release workflow enforces application artifact and inventory prerequisites.
A separate helper build, signing approval and publication are no longer required.
Local unit-test success does not substitute for final artifact scans or
deployment-specific acceptance.

Development Sqlite Kb Upgrade (`docs/development/sqlite-kb-upgrade.md`) Copy Section

SQLite Knowledge Base transition for 1.13.0

The local default is SQLite with sqlite-vec. Explicit pgVector configuration
continues to take precedence. Existing pgVector and OpenSearch stores retain
their routing. This change targets 1.13.0 only, with no 1.12.5 backport.

See the qualification evidence for measured tests,
workloads and remaining application release gates.

The application workspace, universal lock and all-packages/all-extras/all-groups
export no longer require chromadb, langchain-chroma or
agent-lifecycle-toolkit. langflow-base installs lfx[sqlite], including APSW
3.53.4.0 and sqlite-vec 0.1.9. The default automatic reader is bundled, uses SQLite and bounded inert HNSW
data parsing, and imports no Chroma SDK or native HNSW library. The optional
managed controller uses this same bundled reader after stopping the old workers
and preserving a metadata backup. No separate migration helper is published.

Runtime and storage Copy Chapter

Each store is located at
<knowledge_bases_root>/sqlite/<owner UUID>/<KB UUID>/<generation>/vectors.sqlite3.
The factory obtains identities from the authoritative application record, not
request paths, display names or the accessing user's identity. Configuration
cannot override the database or extension path. Shared resources use the owner.
Normal reads open an existing generation and fail if its database is missing.
Only explicit new-store creation or unpublished migration creates files.

The backend uses a private APSW runtime, WAL, full synchronous durability,
foreign keys, bounded busy waits and short transactions. It loads only the
installed sqlite-vec extension and disables further extension loading. Connections
are scoped to bounded worker operations. Cancellation drains active workers
before releasing their lifecycle guard. Pools are recreated after fork.

Canonical tables retain native IDs, original JSON metadata, text and float32
vectors. Native IDs are distinct from user metadata _id. Exact filtered search
supports squared L2, cosine and inner product. Extreme finite vectors use stable
double-precision distance calculation before ranking. Equal distances use native
ID ordering. Exact search can differ from Chroma's approximate search.

The public local score remains negative distance. User source filters are applied
before top-k selection, with AND across keys, OR across values and the historical
Python string-conversion behavior. Internal job/session equality filters remain
separate. Cosine zero vectors are rejected explicitly, including during migration,
rather than silently removed or assigned a different metric.

Application factories wrap complete backend methods and iterators in a
cross-process guard. A fresh routing/state check follows lock acquisition.
Generation and identity checks also occur inside SQLite transactions. Local
stores require one host and local disk. Remote stores use application-database
coordination without requiring a local vector directory. PostgreSQL advisory
locks use a separate configurable pool, avoiding exhaustion of the application pool.
LANGFLOW_KNOWLEDGE_BASE_STORAGE_POOL_SIZE defaults to 20 connections per process.
Nested operations spanning several remote KBs share one coordination transaction.
Memory capture revalidates routing, message contents, session identity and cursor
under its write lease after provider calls. Embedding calls and retry back-off do
not hold that lease. Tracking commits revalidate the same snapshot. Session purges and regeneration acquire the
same guards before changing messages, cursors or history.

Deletion persists a fence, drains active operations and tombstones the generation
before removing application records. Failures retain the identity needed for a
retry. A new KB with the same display name receives a new UUID and cannot reuse
a tombstoned generation. Storage and metadata cleanup retain the original UUID,
so a delayed request cannot delete its replacement. Remote destructive requests
propagate transport and partial-completion errors. OpenSearch worker requests
drain before cancellation releases their guard.
Cleanup never manually unlinks active WAL/SHM files or
truncates live databases.

Automatic upgrade Copy Chapter