> ## Documentation Index > Fetch the complete documentation index at: https://docs.praison.ai/llms.txt > Use this file to discover all available pages before exploring further. # n8n Integration > Export and run PraisonAI workflows in n8n Use n8n as the **visual UI layer** for your PraisonAI workflows. Two ways: 1. `praisonai n8n open agents.yaml` — one-step command (recommended) 2. `praisonai agents.yaml --n8n` — exports + auto-imports via the run flag ## Quick Start ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Start n8n (one-time) docker run -d -p 5678:5678 docker.n8n.io/n8nio/n8n # Set API key (get one from n8n UI → Settings → API) export N8N_API_KEY="your-api-key" # Open your workflow in n8n praisonai n8n open agents.yaml ``` ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai agents.yaml --n8n ``` Every agent in your YAML becomes a node in n8n. Sequential steps are connected automatically. The visual editor opens in your browser. ## `praisonai n8n open` — The Simplest UX ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} name: My Research Workflow agents: researcher: name: Researcher role: Research Specialist llm: gpt-4o-mini writer: name: Writer role: Content Writer llm: gpt-4o-mini ``` ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai n8n open my-workflow.yaml ``` The n8n editor opens automatically with your workflow visualized as connected HTTP Request nodes — one per agent. ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} %%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#8B0000','primaryTextColor':'#fff','primaryBorderColor':'#8B0000','lineColor':'#189AB4','secondaryColor':'#189AB4','tertiaryColor':'#fff'}}}%% graph LR A[agents.yaml]:::agent --> B[praisonai n8n open]:::tool B --> C[YAMLToN8nConverter]:::tool C --> D[n8n Public API]:::tool D --> E[Visual Editor]:::agent classDef agent fill:#8B0000,stroke:#8B0000,color:#fff classDef tool fill:#189AB4,stroke:#189AB4,color:#fff ``` n8n Integration Exports Workflows ## Usage ### Basic Export ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Export workflow to n8n JSON and open in browser praisonai agents.yaml --n8n ``` **Expected Output:** ``` ✅ Workflow converted successfully! 📄 JSON saved to: agents_n8n.json 🌐 Opening: http://localhost:5678/workflow/new ``` ### Auto-Import with API Key ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Set n8n API key for automatic import export N8N_API_KEY="your-api-key" # Export and auto-import praisonai agents.yaml --n8n ``` **Expected Output:** ``` ✅ Workflow converted successfully! 📄 JSON saved to: agents_n8n.json 🚀 Workflow created in n8n! ✅ Workflow activated! 🔗 Webhook URL (to trigger workflow): POST http://localhost:5678/webhook/your-workflow-name 🌐 Opening: http://localhost:5678/workflow/abc123 ``` ### Custom n8n URL ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Use custom n8n instance praisonai agents.yaml --n8n --n8n-url http://n8n.example.com:5678 ``` ### Custom API URL (Cloud/Tunnel) When n8n is in the cloud and PraisonAI runs locally, use `--api-url` to specify a tunnel or cloud URL: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # With Cloudflare Tunnel praisonai agents.yaml --n8n --api-url https://praisonai.yourdomain.com # With ngrok praisonai agents.yaml --n8n --api-url https://abc123.ngrok-free.app # With cloud deployment praisonai agents.yaml --n8n --api-url https://praisonai-api.railway.app ``` ## Generated Workflow Structure The n8n workflow includes: ``` ┌─────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ Webhook │────▶│ Researcher │────▶│ Writer │────▶│ Editor │ │ Trigger │ │ │ │ │ │ │ └─────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │ │ ▼ ▼ ▼ /agents/researcher /agents/writer /agents/editor ``` Each agent becomes an HTTP Request node that calls the corresponding PraisonAI API endpoint. ## Complete Workflow ### Step 1: Start the API Server ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Terminal 1 praisonai serve agents.yaml --port 8005 ``` ### Step 2: Create n8n Workflow ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Terminal 2 export N8N_API_KEY="your-api-key" praisonai agents.yaml --n8n ``` ### Step 3: Trigger the Workflow ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Via webhook curl -X POST "http://localhost:5678/webhook/your-workflow-name" \ -H "Content-Type: application/json" \ -d '{"query": "Research AI trends and write a blog post"}' ``` ## Getting n8n API Key 1. Open n8n UI ([http://localhost:5678](http://localhost:5678)) 2. Go to **Settings** → **API** 3. Click **Create API Key** 4. Copy the key and set it: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} export N8N_API_KEY="your-api-key" ``` ## Example agents.yaml ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} name: Create Movie Script About Cat in Mars description: Research, design narrative, and write script agents: researcher: name: Researcher role: Research Specialist goal: Research about cats and Mars for the movie backstory: Expert researcher with knowledge of space and animals llm: gpt-4o-mini narrative_designer: name: Narrative Designer role: Story Designer goal: Design the narrative structure backstory: Creative storyteller who crafts compelling narratives llm: gpt-4o-mini scriptwriter: name: Scriptwriter role: Script Writer goal: Write the final movie script backstory: Professional screenwriter with Hollywood experience llm: gpt-4o-mini ``` ## n8n Workflow Features ### Webhook Trigger The workflow uses a webhook trigger for programmatic execution: * **Path**: Auto-generated from workflow name * **Method**: POST * **Response Mode**: Returns final agent output ### Per-Agent HTTP Nodes Each agent gets its own HTTP Request node: | Node | Endpoint | Purpose | | ------------------ | ---------------------------- | --------------------------------------- | | Researcher | `/agents/researcher` | First agent, receives webhook input | | Narrative Designer | `/agents/narrative_designer` | Receives researcher output | | Scriptwriter | `/agents/scriptwriter` | Receives designer output, returns final | ### Data Flow ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} // Webhook input {"query": "Create a movie about a cat on Mars"} // Passed to Researcher {"query": "Create a movie about a cat on Mars"} // Researcher output → Narrative Designer input {"query": "Research findings about cats and Mars..."} // Narrative Designer output → Scriptwriter input {"query": "Narrative structure: Act 1..."} // Final output returned to webhook caller {"response": "FADE IN: EXT. MARS SURFACE..."} ``` ## Use Cases See agent execution flow in n8n's visual editor Add IF nodes between agents for branching Connect to other n8n nodes (Slack, Email, etc.) Use n8n's scheduler to run workflows periodically ## Advanced: Manual Import If auto-import fails, manually import the generated JSON: 1. Run `praisonai agents.yaml --n8n` 2. Open n8n UI 3. Click **Add Workflow** → **Import from File** 4. Select `agents_n8n.json` 5. Click **Import** ## Troubleshooting ### Connection Refused ``` Error: ECONNREFUSED 127.0.0.1:8005 ``` **Solution**: Start the PraisonAI server first: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai serve agents.yaml --port 8005 ``` ### API Key Invalid ``` Error: 401 Unauthorized ``` **Solution**: Verify your n8n API key: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} curl -H "X-N8N-API-KEY: $N8N_API_KEY" http://localhost:5678/api/v1/workflows ``` ### Workflow Not Activating **Solution**: Manually activate in n8n UI or check webhook settings. ## Command Options | Option | Default | Description | | ----------- | ---------------------------------------------- | ------------------------------------ | | `--n8n` | - | Enable n8n export | | `--n8n-url` | [http://localhost:5678](http://localhost:5678) | n8n instance URL | | `--api-url` | [http://127.0.0.1:8005](http://127.0.0.1:8005) | PraisonAI API URL (for tunnel/cloud) | ## Environment Variables | Variable | Description | | ------------- | --------------------------- | | `N8N_API_KEY` | n8n API key for auto-import | ## Cloud/Tunnel Setup When n8n runs in the cloud but PraisonAI runs locally, you need to expose your local API. ### Option 1: Cloudflare Tunnel (Recommended) Free, stable URLs, unlimited bandwidth. ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Install cloudflared brew install cloudflared # macOS # or: https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/ # Authenticate cloudflared tunnel login # Create tunnel cloudflared tunnel create praisonai # Create config (~/.cloudflared/config.yml) cat > ~/.cloudflared/config.yml << EOF tunnel: credentials-file: ~/.cloudflared/.json ingress: - hostname: praisonai.yourdomain.com service: http://localhost:8005 - service: http_status:404 EOF # Run tunnel cloudflared tunnel run praisonai ``` Then use: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai agents.yaml --n8n --api-url https://praisonai.yourdomain.com ``` ### Option 2: ngrok (Quick Testing) Easy setup, URL changes on restart (free tier). ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Install brew install ngrok # Auth (one-time) ngrok config add-authtoken # Start tunnel ngrok http 8005 # Output: https://abc123.ngrok-free.app ``` Then use: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai agents.yaml --n8n --api-url https://abc123.ngrok-free.app ``` ### Option 3: Deploy to Cloud Deploy PraisonAI API to Railway, Render, or Fly.io. **Dockerfile:** ```dockerfile theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} FROM python:3.11-slim WORKDIR /app COPY agents.yaml . RUN pip install praisonai praisonaiagents EXPOSE 8005 CMD ["praisonai", "serve", "agents.yaml", "--host", "0.0.0.0", "--port", "8005"] ``` **Deploy to Railway:** ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} railway up ``` Then use: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai agents.yaml --n8n --api-url https://your-app.railway.app ``` ## Related * [Serve Command](/docs/cli/serve) * [Workflows](/features/workflows) * [YAML Configuration](/docs/concepts/yaml)