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.

graph LR
    subgraph "n8n → PraisonAI API Flow"
        A[🌐 n8n Workflow] --> B[📤 HTTP Request Node]
        B --> C[🔗 /agents/{id}/invoke]
        C --> D[🤖 PraisonAI Agent]
        D --> E[📊 Agent Response]
        E --> F[🔙 HTTP Response]
        F --> G[📋 n8n Processing]
    end

    classDef n8n fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef api fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef agent fill:#10B981,stroke:#7C90A0,color:#fff

    class A,G n8n
    class B,C,F api
    class D,E agent

How It Works

Quick Start

1. Start PraisonAI API Server

   # Start the API server with your agents (localhost default)
   praisonai serve agents.yaml --port 8005

   For a containerised n8n, the API must be reachable from another container — bind to 0.0.0.0 and set an API key:

   # Public bind — REQUIRES an api key (or SystemExit at startup)
   export PRAISONAI_SERVE_API_KEY="$(openssl rand -hex 32)"
   praisonai serve agents.yaml --port 8005 --host 0.0.0.0

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/{agent_id}/invoke

Invoke a specific PraisonAI agent with input data.

URL Parameters:

Request Body:

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

Required Fields:

Optional Fields:

Supported agent_config keys

agent_config overrides only the whitelisted attributes below on the request’s isolated clone. Any other key returns a 400.

Rejected requests return a FastAPI error with a 400 status:

{
  "detail": "Unsupported agent_config override(s): ['temperature']. Allowed: ['backstory', 'goal', 'instructions', 'llm', 'markdown', 'max_iter', 'role', 'verbose']"
}

Session semantics

session_id isolates conversations per id, resumes history within an id, and runs ephemerally when omitted.

# Serve the agent
# agents.yaml is loaded and mounted on http://localhost:8005

praisonai serve agents.yaml --port 8005

# Same session_id → continuous conversation for one user
curl -s http://localhost:8005/api/v1/agents/researcher/invoke \
  -X POST -H "content-type: application/json" \
  -d '{"message": "my name is Sam", "session_id": "user-42"}'

curl -s http://localhost:8005/api/v1/agents/researcher/invoke \
  -X POST -H "content-type: application/json" \
  -d '{"message": "what is my name?", "session_id": "user-42"}'
# → "Sam"

# Different session_id → isolated; never sees user-42's history
curl -s http://localhost:8005/api/v1/agents/researcher/invoke \
  -X POST -H "content-type: application/json" \
  -d '{"message": "what is my name?", "session_id": "user-99"}'
# → no idea

# No session_id at all → ephemeral; nothing is persisted
curl -s http://localhost:8005/api/v1/agents/researcher/invoke \
  -X POST -H "content-type: application/json" \
  -d '{"message": "hello"}'

Per-request cleanup

/invoke releases the per-request clone deterministically. After every response — success or error — the wrapper calls await agent.aclose() (or agent.close() in a worker thread when the clone only exposes the sync form). Only clones are closed; when the resolved agent is the shared registry template (plain mocks / non-isolatable agents) it is left untouched, so subsequent requests don’t hit a torn-down instance.

This means:

• MCP stdio subprocesses started by a clone’s tools are terminated before the response returns — no node.exe / uvx … accumulation in long-lived n8n polling loops.
• LLM HTTP client pools and tool-executor threads owned by the clone are released.
• Cleanup failures never mask the response — they are caught and logged (logger.exception("Agent cleanup failed")).

No API change: AgentInvokeRequest / AgentInvokeResponse are unchanged. This is a wrapper-internal fix delivered in PR #5083.

Safe Retries (Idempotency-Key)

Send the same Idempotency-Key header on a retry and the invoke endpoint returns 409 instead of starting a second agent run — no duplicate tool actions, no doubled LLM spend.

Opt-in, backward-compatible: no header → unchanged behaviour (every POST runs the agent). The request body is unchanged.

import os
import uvicorn
from fastapi import FastAPI
from praisonaiagents import Agent
from praisonai.api.agent_invoke import register_agent, router

os.environ.setdefault("CALL_SERVER_TOKEN", "my-secret-token")

agent = Agent(name="support", instructions="Handle refund requests.")
register_agent("support", agent)

app = FastAPI()
app.include_router(router)
uvicorn.run(app, host="127.0.0.1", port=8005)

curl -X POST http://127.0.0.1:8005/api/v1/agents/support/invoke \
  -H "Authorization: Bearer my-secret-token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-123" \
  -d '{"message": "refund order 123"}'

1. Retry with the same key

   Your client times out after the agent already fired the refund. Retry with the same key — the retry gets 409, so the refund is not issued twice.

   import requests
   
   url = "http://127.0.0.1:8005/api/v1/agents/support/invoke"
   headers = {"Authorization": "Bearer my-secret-token", "Idempotency-Key": "order-123"}
   body = {"message": "refund order 123"}
   
   first = requests.post(url, json=body, headers=headers)   # 200 — agent runs
   retry = requests.post(url, json=body, headers=headers)   # 409 — no second run
   print(first.status_code, retry.status_code)

2. Set the header in n8n

   Add the header to the HTTP Request node. Use a value that stays the same across n8n’s retries of one item but differs between items.

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

   With Retry On Fail enabled, a timed-out attempt that already reached the agent now returns 409 on the retry instead of running the agent again.

3. Retry after a failure

   If the first run fails (tool error, LLM timeout → 500), just retry with the same key. A failed run frees its key, so the retry runs the agent normally.

What happens in each case:

Scoping and limits:

Which endpoint for safe retries?

See Gateway API → Safe Retries and Async Jobs → Submit Run.

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

// Persistent conversation — pass the real per-user session id
{
  "method": "POST",
  "url": "http://localhost:8005/api/v1/agents/researcher/invoke",
  "sendBody": true,
  "specifyBody": "json",
  "jsonBody": "{\"message\": \"{{ $json.query }}\", \"session_id\": \"{{ $json.user_id }}\"}"
}

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

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

{
  "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) }}}"
}

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

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

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

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

# 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

# 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

# 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

// 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 }}\"}"
}

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

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

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

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

// Set Node for validation — pass a stable id, or omit session_id
{
  "values": {
    "message": "{{ $json.input || 'Default message' }}",
    "session_id": "{{ $json.user_id }}",
    "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;
}

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

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

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

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