n8n AgentHub Node

A custom n8n node for seamless integration with AgentHub AI agents. This node allows you to hire, execute, and manage AI agents directly from your n8n workflows.

Features

• Agent Management: Search, list, and get details about available AI agents
• Hiring Operations: Hire agents, manage hiring status, and view hiring details
• Agent Execution: Execute hired agents with custom input data
• Deployment Management: Create, monitor, and control agent deployments
• Persistent Agents: Initialize and manage persistent agent instances

Installation

Option 1: Install as a Community Node Package

1. In your n8n instance, go to Settings → Community Nodes
2. Click Install and search for n8n-nodes-agenthub
3. Install the package and restart n8n

Option 2: Manual Installation

For macOS/Linux:

1. Clone this repository:

   git clone https://github.com/agenthub/n8n-agenthub-node.git
   cd n8n-agenthub-node

2. Install dependencies:

   npm install

3. Build the package:

   npm run build

4. Run the installation script:

   ./install.sh

For Windows:

1. Clone this repository:

   git clone https://github.com/agenthub/n8n-agenthub-node.git
   cd n8n-agenthub-node

2. Install dependencies:

   npm install

3. Build the package:

   npm run build

4. Run the Windows installation script:

   install-windows.bat

Manual Windows Installation:

If you prefer to install manually on Windows:

1. Build the package: npm run build
2. Copy the dist folder contents to your n8n custom directory:
   • Default: C:\Users\{YourUsername}\.n8n\custom\
   • Alternative: C:\Users\{YourUsername}\AppData\Roaming\n8n\custom\
3. Restart n8n

Option 3: Direct Copy Installation

1. Build the package: npm run build
2. Copy the dist folder contents to your n8n custom nodes directory:
   • macOS/Linux: ~/.n8n/custom/
   • Windows: C:\Users\{YourUsername}\.n8n\custom\
3. Restart n8n

Configuration

1. Create AgentHub Credentials

1. In your n8n workflow, add an AgentHub node
2. Click on the credentials field and select Create New
3. Fill in the following details:
   • Base URL: Your AgentHub server URL (e.g., http://localhost:8002)
   • API Key: Your AgentHub API key
   • User ID: Your AgentHub user ID (optional)

2. Get Your API Key

1. Log into your AgentHub instance
2. Go to Profile → API Keys
3. Create a new API key or copy an existing one

Usage Examples

Example 1: Execute an AI Agent

This workflow demonstrates how to execute a hired AI agent:

1. AgentHub Node (Hiring → List Hirings)

   • Lists your active hirings
   • Outputs hiring IDs and agent details

2. AgentHub Node (Execution → Execute Agent)

   • Uses the hiring ID from the previous node
   • Sends input data to the agent
   • Waits for completion and returns results

3. Process Results

   • Parse the agent's response
   • Continue with your workflow logic

Example 2: Hire and Deploy a New Agent

1. AgentHub Node (Agent → Search Agents)

   • Search for agents by category or query
   • Find the perfect agent for your needs

2. AgentHub Node (Hiring → Hire Agent)

   • Hire the selected agent
   • Specify requirements and billing cycle

3. AgentHub Node (Deployment → Create Deployment)

   • Create deployment for the hiring
   • Wait for deployment to be ready

4. AgentHub Node (Execution → Execute Agent)

   • Execute the newly deployed agent

Example 3: Persistent Agent Management

1. AgentHub Node (Execution → Initialize Agent)

   • Initialize a persistent agent with configuration
   • Set up the agent's state and context

2. AgentHub Node (Execution → Execute Agent)

   • Execute the initialized agent multiple times
   • Maintain state between executions

3. AgentHub Node (Execution → Get Status)

   • Monitor execution progress
   • Handle long-running operations

Node Operations

Agent Operations

• List Agents: Browse available agents with optional filtering
• Get Agent: Retrieve detailed information about a specific agent
• Search Agents: Find agents by query, category, or other criteria

Hiring Operations

• Hire Agent: Hire an agent for your use
• List Hirings: View all your active and past hirings
• Get Hiring Details: Get comprehensive information about a hiring
• Cancel Hiring: Terminate an active hiring
• Suspend Hiring: Pause a hiring temporarily
• Activate Hiring: Resume a suspended hiring

Execution Operations

• Execute Agent: Run a hired agent with input data
• Get Execution Status: Check the status of an execution
• Initialize Agent: Set up a persistent agent instance

Deployment Operations

• Create Deployment: Deploy a hired agent
• Get Deployment Status: Monitor deployment progress
• Stop Deployment: Terminate a running deployment
• List Deployments: View all your deployments

Input Data Format

Agent Execution Input

{
  "query": "What is the weather in New York?",
  "context": "I need this for a business meeting",
  "format": "json"
}

Agent Initialization

{
  "model": "gpt-4",
  "temperature": 0.7,
  "max_tokens": 1000,
  "system_prompt": "You are a helpful AI assistant"
}

Output Format

The node returns structured data that includes:

• Execution ID: Unique identifier for the execution
• Status: Current execution status (pending, running, completed, failed)
• Output Data: The agent's response
• Metadata: Execution details, timing, and resource usage

Error Handling

The node includes comprehensive error handling:

• Validation Errors: Invalid input data or parameters
• Authentication Errors: Invalid API key or permissions
• Execution Errors: Agent execution failures
• Network Errors: Connection issues with AgentHub

Best Practices

1. Use Wait for Completion: Enable this option for synchronous workflows
2. Handle Errors Gracefully: Use n8n's error handling nodes
3. Monitor Resource Usage: Track API calls and execution costs
4. Cache Results: Store frequently used agent responses
5. Rate Limiting: Respect API rate limits in high-volume workflows

Troubleshooting

Common Issues

1. Authentication Failed

   • Verify your API key is correct
   • Check that your user account is active

2. Agent Not Found

   • Ensure the agent ID is correct
   • Verify the agent is approved and available

3. Execution Timeout

   • Increase the timeout value for long-running agents
   • Check if the agent requires initialization

4. Deployment Failed

   • Verify the hiring is active
   • Check server resources and logs

Node Not Appearing in n8n?

macOS/Linux:

• Check ~/.n8n/custom/ directory exists
• Verify files were copied correctly
• Restart n8n completely

Windows:

• Check C:\Users\{YourUsername}\.n8n\custom\ directory
• Alternative: C:\Users\{YourUsername}\AppData\Roaming\n8n\custom\
• Verify files were copied correctly
• Restart n8n completely

Debug Mode

Enable debug logging in n8n to see detailed API requests and responses.

Support

• Documentation: AgentHub Docs
• Issues: GitHub Issues
• Community: AgentHub Community

License

MIT License - see LICENSE file for details.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Changelog

v1.0.0

• Initial release
• Support for agent hiring, execution, and deployment
• Comprehensive error handling
• TypeScript implementation
• Cross-platform installation scripts