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

​
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:
ParameterTypeDescription
agent_idstringThe 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:
FieldTypeDescription
messagestringThe input message for the agent
Optional Fields:
FieldTypeDescription
session_idstringSession ID for conversation continuity
agent_configobjectOverride agent configuration
contextobjectAdditional 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

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

​
Advanced Configuration

{
  "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.
{
  "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.
{
  "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: 
# 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

​
API Key Management

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
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

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

​
Conditional Routing Workflow

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"
    }
  ]
}
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

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"
      }
    ]
  }
}
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;
}
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
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

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

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

​
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

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