n8n API Integration

HTTP endpoints for n8n workflows to invoke PraisonAI agents

from praisonaiagents import Agent

agent = Agent(name="n8n-agent", instructions="Trigger and manage n8n workflows via API.")
agent.start("Trigger the n8n lead-processing workflow for this new contact.")

The n8n API integration enables n8n workflows to invoke PraisonAI agents via HTTP endpoints, allowing bidirectional automation between the platforms.

The user triggers an n8n workflow; HTTP nodes call PraisonAI agents and return structured responses.

How It Works

Quick Start

1. Start PraisonAI API Server

   # Start the API server with your agents
   praisonai serve agents.yaml --port 8005
   
   # With authentication token
   export CALL_SERVER_TOKEN="your-secret-token"
   praisonai serve agents.yaml --port 8005 --auth
   
2. Configure n8n HTTP Request Node

   {
     "method": "POST",
     "url": "http://localhost:8005/api/v1/agents/researcher/invoke",
     "sendBody": true,
     "specifyBody": "json",
     "jsonBody": "{\"message\": \"{{ $json.query }}\"}"
   }
   
3. Test the Integration

   # Trigger n8n workflow via webhook
   curl -X POST "http://localhost:5678/webhook/research-workflow" \
     -H "Content-Type: application/json" \
     -d '{"query": "Research AI trends in 2026"}'
   

---

API Endpoints

POST /api/v1/agents//invoke

Invoke a specific PraisonAI agent with input data.

URL Parameters:

Parameter	Type	Description
agent_id	string	The ID/name of the agent to invoke

Request Body:

{
  "message": "Your message to the agent",
  "session_id": "optional-session-id",
  "agent_config": {
    "llm": "gpt-4o-mini",
    "temperature": 0.7
  },
  "context": {
    "user_id": "user123",
    "timestamp": "2026-04-16T12:00:00Z"
  }
}

Required Fields:

Field	Type	Description
message	string	The input message for the agent

Optional Fields:

Field	Type	Description
session_id	string	Session ID for conversation continuity
agent_config	object	Override agent configuration
context	object	Additional context data

Response:

{
  "result": "The agent's response text",
  "session_id": "session-123",
  "status": "success",
  "metadata": {
    "agent_id": "researcher",
    "execution_time": 2.5,
    "message_length": 50,
    "response_length": 200,
    "llm_calls": 2,
    "tool_calls": 1
  }
}

Error Response:

{
  "error": "Agent 'unknown_agent' not found",
  "status": "error",
  "code": 404
}

GET /api/v1/agents

List all available agents.

Response:

{
  "agents": [
    {
      "id": "researcher",
      "name": "Research Agent",
      "description": "Conducts thorough research on given topics",
      "status": "active"
    },
    {
      "id": "writer",
      "name": "Content Writer",
      "description": "Creates engaging content based on research",
      "status": "active"
    }
  ],
  "count": 2,
  "status": "success"
}

GET /api/v1/health

Check API server health status.

Response:

{
  "status": "healthy",
  "timestamp": "2026-04-16T12:00:00Z",
  "version": "1.0.0",
  "agents_loaded": 3
}

---

n8n HTTP Request Configuration

Basic Configuration

Simple Agent Call

{
  "method": "POST",
  "url": "http://localhost:8005/api/v1/agents/researcher/invoke",
  "sendBody": true,
  "specifyBody": "json",
  "jsonBody": "{\"message\": \"{{ $json.query }}\"}"
}

With Session Management

{
  "method": "POST",
  "url": "http://localhost:8005/api/v1/agents/researcher/invoke",
  "sendBody": true,
  "specifyBody": "json",
  "jsonBody": "{\"message\": \"{{ $json.query }}\", \"session_id\": \"{{ $json.session_id || 'default' }}\"}"
}

With Authentication

{
  "method": "POST",
  "url": "http://localhost:8005/api/v1/agents/researcher/invoke",
  "sendBody": true,
  "specifyBody": "json",
  "jsonBody": "{\"message\": \"{{ $json.query }}\"}",
  "options": {
    "headers": {
      "Authorization": "Bearer {{ $node.parameter.auth_token }}"
    }
  }
}

Advanced Configuration

Dynamic Agent Selection

{
  "method": "POST",
  "url": "http://localhost:8005/api/v1/agents/{{ $json.agent_type }}/invoke",
  "sendBody": true,
  "specifyBody": "json",
  "jsonBody": "{\"message\": \"{{ $json.message }}\", \"context\": {{ JSON.stringify($json.context) }}}"
}

Use this pattern when you want to dynamically select which agent to call based on input data.

Error Handling

{
  "method": "POST",
  "url": "http://localhost:8005/api/v1/agents/researcher/invoke",
  "sendBody": true,
  "specifyBody": "json",
  "jsonBody": "{\"message\": \"{{ $json.query }}\"}",
  "options": {
    "timeout": 30000,
    "retry": {
      "enable": true,
      "maxAttempts": 3
    }
  }
}

Configure timeouts and retry logic for resilient workflows.

Response Processing

{
  "method": "POST",
  "url": "http://localhost:8005/api/v1/agents/researcher/invoke",
  "sendBody": true,
  "specifyBody": "json",
  "jsonBody": "{\"message\": \"{{ $json.query }}\"}",
  "options": {
    "response": {
      "fullResponse": true,
      "neverError": false
    }
  }
}

Control how n8n handles the API response data.

---

Authentication

Token-Based Authentication

Set up authentication for secure API access:

Server Setup

# Set authentication token
export CALL_SERVER_TOKEN="your-secret-token"

# Start server with auth
praisonai serve agents.yaml --port 8005 --auth

# Or in agents.yaml
auth:
  token: "your-secret-token"
  required: true

n8n Configuration

{
  "method": "POST",
  "url": "http://localhost:8005/api/v1/agents/researcher/invoke",
  "sendBody": true,
  "specifyBody": "json",
  "jsonBody": "{\"message\": \"{{ $json.query }}\"}",
  "options": {
    "headers": {
      "Authorization": "Bearer your-secret-token"
    }
  }
}

Environment Variables

# Production setup
export CALL_SERVER_TOKEN="prod-token-123"
export PRAISONAI_API_URL="https://api.yourcompany.com"

# Development setup
export CALL_SERVER_TOKEN="dev-token-456"
export PRAISONAI_API_URL="http://localhost:8005"

API Key Management

Rotation Strategy

Implement token rotation for enhanced security:

# Generate new token
export NEW_TOKEN="$(openssl rand -hex 32)"

# Update server configuration
praisonai config set auth.token "$NEW_TOKEN"

# Update n8n credentials
# Manual step: Update HTTP Request node headers

Multiple Environments

Use different tokens for different environments:

# Production
export CALL_SERVER_TOKEN="prod_$(date +%Y%m%d)_$(openssl rand -hex 16)"

# Staging
export CALL_SERVER_TOKEN="staging_$(date +%Y%m%d)_$(openssl rand -hex 16)"

# Development
export CALL_SERVER_TOKEN="dev_$(openssl rand -hex 16)"

---

Workflow Examples

Sequential Agent Workflow

n8n Workflow

Create a research → write → publish workflow:

1. Webhook Trigger: Receives initial request
2. Researcher HTTP Node: Calls /agents/researcher/invoke
3. Writer HTTP Node: Calls /agents/writer/invoke with research data
4. Publisher HTTP Node: Calls /agents/publisher/invoke with content
5. Response Node: Returns final result

HTTP Node Configuration

// Researcher Node
{
  "url": "http://localhost:8005/api/v1/agents/researcher/invoke",
  "jsonBody": "{\"message\": \"{{ $json.topic }}\"}"
}

// Writer Node
{
  "url": "http://localhost:8005/api/v1/agents/writer/invoke",
  "jsonBody": "{\"message\": \"Write content based on: {{ $node.Researcher.json.result }}\"}"
}

// Publisher Node
{
  "url": "http://localhost:8005/api/v1/agents/publisher/invoke",
  "jsonBody": "{\"message\": \"Publish this content: {{ $node.Writer.json.result }}\"}"
}

Test Webhook

curl -X POST "http://localhost:5678/webhook/research-pipeline" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Future of AI in healthcare",
    "target_audience": "medical professionals",
    "publishing_channels": ["blog", "linkedin"]
  }'

Conditional Routing Workflow

Smart Content Router

Route content to different agents based on type:

// Classification Node
{
  "url": "http://localhost:8005/api/v1/agents/classifier/invoke",
  "jsonBody": "{\"message\": \"Classify this content: {{ $json.content }}\"}"
}

// Switch Node Logic
{
  "rules": [
    {
      "operation": "equal",
      "value1": "{{ $node.Classifier.json.result.type }}",
      "value2": "blog"
    },
    {
      "operation": "equal", 
      "value1": "{{ $node.Classifier.json.result.type }}",
      "value2": "social"
    }
  ]
}

Error Recovery Workflow

Implement fallback logic for failed agent calls:

// Primary Agent Call
{
  "url": "http://localhost:8005/api/v1/agents/primary/invoke",
  "options": {
    "timeout": 10000,
    "neverError": true
  }
}

// IF Node (Check for Errors)
{
  "conditions": {
    "string": [
      {
        "value1": "{{ $json.error }}",
        "operation": "isEmpty"
      }
    ]
  }
}

// Fallback Agent Call
{
  "url": "http://localhost:8005/api/v1/agents/fallback/invoke",
  "jsonBody": "{\"message\": \"{{ $json.original_request }}\"}"
}

---

Best Practices

Error Handling

Implement robust error handling in n8n workflows:

// Configure HTTP Request nodes
{
  "options": {
    "timeout": 30000,
    "retry": {
      "enable": true,
      "maxAttempts": 3,
      "waitBetween": 1000
    },
    "response": {
      "neverError": true
    }
  }
}

// Add IF nodes to check for errors
{
  "conditions": {
    "string": [
      {
        "value1": "{{ $json.status }}",
        "operation": "equal",
        "value2": "error"
      }
    ]
  }
}

Data Validation

Validate data before sending to agents:

// Set Node for validation
{
  "values": {
    "message": "{{ $json.input || 'Default message' }}",
    "session_id": "{{ $json.session_id || $runIndex }}",
    "timestamp": "{{ new Date().toISOString() }}"
  }
}

// Function Node for complex validation
function validateInput() {
  const required = ['message', 'user_id'];
  const missing = required.filter(field => !items[0].json[field]);
  
  if (missing.length > 0) {
    throw new Error(`Missing required fields: ${missing.join(', ')}`);
  }
  
  return items[0].json;
}

Performance Optimization

Optimize API calls for better performance:

• Batch Requests: Group multiple agent calls when possible
• Parallel Execution: Use fan-out patterns for independent calls
• Caching: Store frequently used results in Set nodes
• Connection Pooling: Configure HTTP node connection limits
• Timeouts: Set appropriate timeouts based on agent complexity

Security

Secure your API integration:

• Authentication: Always use CALL_SERVER_TOKEN in production
• HTTPS: Use encrypted connections for remote APIs
• Input Sanitization: Validate and sanitize user inputs
• Rate Limiting: Implement rate limiting on the PraisonAI server
• Logging: Enable request logging for audit trails

---

Troubleshooting

Common Issues

Connection Errors

// Error: ECONNREFUSED
{
  "error": "connect ECONNREFUSED 127.0.0.1:8005"
}

// Solution: Verify PraisonAI server is running
// Check: praisonai serve agents.yaml --port 8005

Authentication Errors

// Error: 401 Unauthorized
{
  "error": "Invalid or missing authentication token",
  "code": 401
}

// Solution: Add Authorization header
{
  "headers": {
    "Authorization": "Bearer your-secret-token"
  }
}

Agent Not Found

// Error: Agent not found
{
  "error": "Agent 'unknown_agent' not found",
  "code": 404
}

// Solution: Check available agents
// GET http://localhost:8005/api/v1/agents

Debugging Steps

1. Check Server Status: Verify PraisonAI API is running
2. Test Endpoints: Use curl to test API endpoints directly
3. Validate Credentials: Confirm authentication tokens are correct
4. Review Logs: Check both n8n and PraisonAI logs for errors
5. Network Connectivity: Ensure n8n can reach PraisonAI server

---

Related

n8n Integration Overview

Complete guide to n8n integration architecture and setup

n8n Tools Reference

PraisonAI tools for executing n8n workflows from agents

Visual Workflow Editor

Export and edit PraisonAI workflows in n8n’s visual interface

CLI n8n Commands

Command-line tools for n8n workflow management