AgentFlow

Workflow validation, compilation, and repair API for n8n.

Send broken workflows, get fixed ones back. Generate workflows from plain English.

The Problem

n8n is UI-first. When AI agents or scripts generate workflow JSON, things break:

• Corrupted connections
• Missing node parameters
• Invalid port mappings
• Orphaned nodes

Hours wasted debugging JSON. AgentFlow fixes this.

API Endpoints

Endpoint	Method	What it does
/health	GET	Health check
/registry	GET	List 53 supported node types
/validate	POST	Validate a DSL workflow
/compile	POST	Compile DSL → n8n JSON
/import	POST	Import n8n JSON → DSL (with repair)
/repair	POST	The money endpoint. Broken JSON in → fixed JSON out
/generate	POST	Plain English → working n8n workflow

Quick Examples

Repair a broken workflow

curl -X POST http://localhost:8787/repair \
  -H "Content-Type: application/json" \
  -d '{"workflow": <your n8n JSON>}'

Generate from description

curl -X POST http://localhost:8787/generate \
  -H "Content-Type: application/json" \
  -d '{"description": "When I receive a webhook, send a Telegram notification"}'

Validate DSL

curl -X POST http://localhost:8787/validate \
  -H "Content-Type: application/json" \
  -d '{"dsl": "workflow: test\nnodes:\n  - id: t\n    type: trigger.webhook\n    config: {method: POST, path: /x}\nedges: []"}'

CLI (also available)

python3 engineering/cli/flow.py validate workflows/basic_webhook.dsl.yml
python3 engineering/cli/flow.py compile workflows/basic_webhook.dsl.yml --out workflow.json
python3 engineering/cli/flow.py import some_n8n_workflow.json

Architecture

DSL → Parser → IR → Validator → Compiler → n8n JSON → (Deploy)
           ↘ Importer (round-trip) ↙
                    ↑
              API Server (FastAPI)

• 53 node types mapped (triggers, logic, data, actions, integrations)
• Deterministic compilation — same input always produces same output
• Round-trip safe — import from n8n, modify, compile back
• Validation — schema, port contracts, required config checks

Run Locally

pip install fastapi uvicorn pyyaml
cd projects/agentflow
PYTHONPATH=engineering python3 -m uvicorn api.server:app --host 0.0.0.0 --port 8787

Run Tests

pip install pytest httpx
python3 -m pytest tests/test_api.py -v

Project Structure

agentflow/
├── api/              # FastAPI server
│   └── server.py     # All endpoints
├── engineering/      # Core compiler pipeline
│   ├── parser_v0.py
│   ├── ir_builder_v0.py
│   ├── validator_v0.py
│   ├── compiler_v0.py
│   ├── importer_v0.py
│   └── cli/flow.py
├── specs/            # DSL spec + node registry
├── tests/            # API tests (19 passing)
├── workflows/        # Example DSL workflows
├── product/          # Product docs
└── docs/             # Technical docs

Roadmap

• Core compiler pipeline (DSL → IR → n8n JSON)
• Importer with repair (n8n JSON → DSL)
• Validator (schema + port + config checks)
• API server (FastAPI)
• 53 node type registry
• Template-based generation
• AI-powered generation (LLM → DSL)
• Multi-platform support (Make, Pipedream)
• Hosted API with auth + rate limiting
• Sync layer (push/pull to running n8n instance)

License

MIT