chore: add AGENTS.md for AI coding agents (#11411)
* feat: add AGENTS.md for AI coding agents This adds a general AGENTS.md file (see https://agents.md) for use by AI coding agents. This also adds an explicit CLAUDE.md file that simply references AGENTS.md, since Claude Code has not yet adopted the emerging standard of AGENTS.md (see https://github.com/anthropics/claude-code/issues/6235). * Update AGENTS.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
This commit is contained in:
Gabriel Luiz Freitas Almeida
committed by
GitHub
GitHub
parent
a5dce3a015
commit
922f86411b
1
.gitignore
vendored
1
.gitignore
vendored
@@ -280,7 +280,6 @@ src/frontend/temp
|
||||
*.mcp.json
|
||||
|
||||
news-aggregated.json
|
||||
CLAUDE.md
|
||||
.claude
|
||||
|
||||
member_servers.json
|
||||
|
||||
200
AGENTS.md
Normal file
200
AGENTS.md
Normal file
@@ -0,0 +1,200 @@
|
||||
# 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
|
||||
```bash
|
||||
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)
|
||||
```bash
|
||||
make backend # FastAPI on port 7860 (terminal 1)
|
||||
make frontend # Vite dev server on port 3000 (terminal 2)
|
||||
```
|
||||
|
||||
For component development, enable dynamic loading:
|
||||
```bash
|
||||
LFX_DEV=1 make backend # Load all components dynamically
|
||||
LFX_DEV=mistral,openai make backend # Load only specific modules
|
||||
```
|
||||
|
||||
### Code Quality
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
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
|
||||
```python
|
||||
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
|
||||
```bash
|
||||
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](https://www.conventionalcommits.org/)
|
||||
- Reference any issues fixed (e.g., `Fixes #1234`)
|
||||
- Ensure all tests pass before submitting
|
||||
|
||||
## Documentation
|
||||
|
||||
Documentation uses Docusaurus and lives in `docs/`:
|
||||
```bash
|
||||
cd docs
|
||||
yarn install
|
||||
yarn start # Dev server on port 3000 (prompts for 3001 if 3000 is in use)
|
||||
```
|
||||
5
CLAUDE.md
Normal file
5
CLAUDE.md
Normal file
@@ -0,0 +1,5 @@
|
||||
# CLAUDE.md
|
||||
|
||||
See [AGENTS.md](./AGENTS.md) for project instructions.
|
||||
|
||||
This project uses [AGENTS.md](https://agents.md/) as the standard for providing context to AI coding agents. The AGENTS.md file contains all the information needed to understand and contribute to this codebase.
|
||||
Reference in New Issue
Block a user