n8n-nodes-agenthub/README.md

n8n nodes for AgentHub integration

# 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:
   ```bash
   git clone https://github.com/agenthub/n8n-agenthub-node.git
   cd n8n-agenthub-node
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

3. Build the package:
   ```bash
   npm run build
   ```

4. Run the installation script:
   ```bash
   ./install.sh
   ```

#### For Windows:

1. Clone this repository:
   ```cmd
   git clone https://github.com/agenthub/n8n-agenthub-node.git
   cd n8n-agenthub-node
   ```

2. Install dependencies:
   ```cmd
   npm install
   ```

3. Build the package:
   ```cmd
   npm run build
   ```

4. Run the Windows installation script:
   ```cmd
   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

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

### Agent Initialization

```json
{
  "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](https://docs.agenthub.com)
- **Issues**: [GitHub Issues](https://github.com/agenthub/n8n-agenthub-node/issues)
- **Community**: [AgentHub Community](https://community.agenthub.com)

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## Changelog

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