AGENTS.md

AGENTS.md

This file provides guidance to AI coding agents when working with code in this repository.

Project Overview

Langflow is a visual workflow builder for AI-powered agents. It has a Python/FastAPI backend, React/TypeScript frontend, and a lightweight executor CLI (lfx).

Prerequisites

• Python: 3.10-3.13
• uv: >=0.4 (Python package manager)
• Node.js: >=20.19.0 (v22.12 LTS recommended)
• npm: v10.9+
• make: For build coordination

Common Commands

Development Setup

make init              # Install all dependencies + pre-commit hooks
make run_cli           # Build and run Langflow (http://localhost:7860)
make run_clic          # Clean build and run (use when frontend issues occur)

Development Mode (Hot Reload)

make backend           # FastAPI on port 7860 (terminal 1)
make frontend          # Vite dev server on port 3000 (terminal 2)

For component development, enable dynamic loading:

LFX_DEV=1 make backend                    # Load all components dynamically
LFX_DEV=mistral,openai make backend       # Load only specific modules

Code Quality

make format_backend    # Format Python (ruff) - run FIRST before lint
make format_frontend   # Format TypeScript (biome)
make format            # Both
make lint              # mypy type checking

Testing

make unit_tests                    # Backend unit tests (pytest, parallel)
make unit_tests async=false        # Sequential tests
uv run pytest path/to/test.py      # Single test file
uv run pytest path/to/test.py::test_name  # Single test

make test_frontend                 # Jest unit tests
make tests_frontend                # Playwright e2e tests

Database Migrations

make alembic-revision message="Description"  # Create migration
make alembic-upgrade                         # Apply migrations
make alembic-downgrade                       # Rollback one version

Architecture

Monorepo Structure

src/
├── backend/
│   ├── base/langflow/     # Core backend package (langflow-base)
│   │   ├── api/           # FastAPI routes (v1/, v2/)
│   │   ├── components/    # Built-in Langflow components
│   │   ├── services/      # Service layer (auth, database, cache, etc.)
│   │   ├── graph/         # Flow graph execution engine
│   │   └── custom/        # Custom component framework
│   └── tests/             # Backend tests
├── frontend/              # React/TypeScript UI
│   └── src/
│       ├── components/    # UI components
│       ├── stores/        # Zustand state management
│       └── icons/         # Component icons
└── lfx/                   # Lightweight executor CLI

Key Packages

• langflow: Main package with all integrations
• langflow-base: Core framework (api, services, graph engine)
• lfx: Standalone CLI for running flows (lfx serve, lfx run)

Service Layer

Backend services in src/backend/base/langflow/services/:

• auth/ - Authentication
• database/ - SQLAlchemy models and migrations
• cache/ - Caching layer
• storage/ - File storage
• tracing/ - Observability integrations

Component Development

Components live in src/backend/base/langflow/components/. To add a new component:

1. Create component class inheriting from Component
2. Define display_name, description, icon, inputs, outputs
3. Add to __init__.py (alphabetical order)
4. Run with LFX_DEV=1 make backend for hot reload

IMPORTANT: Changing a component's class name is a breaking change and should never be done. The class name serves as an identifier used to match components in saved flows and to flag them for updates in the UI. Renaming it will break existing flows that use that component.

Component Structure

from langflow.custom import Component
from langflow.io import MessageTextInput, Output

class MyComponent(Component):
    display_name = "My Component"
    description = "What it does"
    icon = "component-icon"  # Lucide icon name or custom

    inputs = [
        MessageTextInput(name="input_value", display_name="Input"),
    ]
    outputs = [
        Output(display_name="Output", name="output", method="process"),
    ]

    def process(self) -> Message:
        # Component logic
        return Message(text=self.input_value)

Component Testing

Tests go in src/backend/tests/unit/components/. Use base classes:

• ComponentTestBaseWithClient - Components needing API access
• ComponentTestBaseWithoutClient - Pure logic components

Required fixtures: component_class, default_kwargs, file_names_mapping

Frontend Development

• React 19 + TypeScript + Vite
• Zustand for state management
• @xyflow/react for graph visualization
• Tailwind CSS for styling

Custom Icons

1. Create SVG component in src/frontend/src/icons/YourIcon/
2. Export with forwardRef and isDark prop support
3. Add to lazyIconImports.ts
4. Set icon = "YourIcon" in Python component

Testing Notes

• @pytest.mark.api_key_required - Tests requiring external API keys
• @pytest.mark.no_blockbuster - Skip blockbuster plugin
• Database tests may fail in batch but pass individually
• Pre-commit hooks require uv run git commit
• Always use uv run when running Python commands

Graph Testing Pattern

Proper Graph tests follow this pattern:

1. Build graph with connected components
2. Connect them via .set() calls
3. Call async_start and iterate over the results
4. Validate the results

Testing Best Practices

• Avoid mocking in tests when possible
• Prefer real integrations for more reliable tests

Version Management

make patch v=1.5.0  # Update version across all packages

This updates: pyproject.toml, src/backend/base/pyproject.toml, src/frontend/package.json

Pre-commit Workflow

1. Run make format_backend (FIRST - saves time on lint fixes)
2. Run make format_frontend
3. Run make lint
4. Run make unit_tests
5. Commit changes (use uv run git commit if pre-commit hooks are enabled)

Pull Request Guidelines

• Follow semantic commit conventions
• Reference any issues fixed (e.g., Fixes #1234)
• Ensure all tests pass before submitting

Documentation

Documentation uses Docusaurus and lives in docs/:

cd docs
yarn install
yarn start        # Dev server on port 3000 (prompts for 3001 if 3000 is in use)