npm package: @original-land/n8n-nodes-original-agent
Description: Custom original.land agent node for n8n
Author: info@original.land
Latest version: 0.3.30

# n8n-nodes-original-agent

Custom Original.land AI Agent integration for [n8n](https://n8n.io). This node allows you to interact with Original.land AI Agents directly from your n8n workflows.

## Features

- 🤖 **Direct AI Agent Integration**: Connect with Original.land AI Agents
- 🔄 **Streaming Support**: Choose between streaming and non-streaming responses
- 🔑 **Secure Authentication**: API key and Bot ID based authentication
- 🌐 **Flexible Endpoints**: Configurable bot endpoints
- ⚡ **Error Handling**: Comprehensive error handling including payment scenarios
- 🛠️ **TypeScript**: Built with TypeScript for better development experience

## Installation

Install the node directly in n8n:

1. Go to **Settings** > **Community Nodes**
2. Select **Install**  
3. Enter `@original-land/n8n-nodes-original-agent`
4. Agree to the risks of using community nodes

Or install globally:

```bash
pnpm add -g @original-land/n8n-nodes-original-agent
```

## Usage

1. Add the "Original Agent" node to your workflow
2. Configure the following parameters:
   - **Bot ID**: Your Original.land bot identifier
   - **API Key**: Your Original.land API authentication key  
   - **Message**: The message/query to send to the AI agent
   - **Bot Endpoint** (optional): Custom API endpoint (defaults to https://ai-api.original.land)
   - **Streaming** (optional): Enable streaming responses for real-time output

## Configuration

### Required Parameters

- **Bot ID**: Available in your Original.land dashboard
- **API Key**: Generate from your Original.land account settings  
- **Message**: The text query or instruction for the AI agent

### Optional Parameters

- **Bot Endpoint**: Override default API endpoint if using custom deployment
- **Streaming**: Toggle between streaming and batch responses

## Development

### Prerequisites

* [git](https://git-scm.com/downloads)
* Node.js and pnpm. Minimum version Node 20
* Install n8n with: `pnpm add -g n8n`

### Getting Started

1. Clone the repository:
   ```bash
   git clone https://github.com/noku-team/n8n-original-agent.git
   cd n8n-original-agent
   ```

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

3. Build the project:
   ```bash
   pnpm run build
   ```

4. Run linting:
   ```bash
   pnpm run lint
   ```

## Release Process

This project uses automated versioning and publishing through GitHub Actions. The release process follows semantic versioning.

### Automated Release

1. Go to the **Actions** tab in the GitHub repository
2. Select **"Release and Publish to NPM"** workflow
3. Click **"Run workflow"**
4. Choose version type:
   - **patch**: Bug fixes and small updates (0.0.1 → 0.0.2)
   - **minor**: New features (0.0.1 → 0.1.0) 
   - **major**: Breaking changes (0.0.1 → 1.0.0)
5. Click **"Run workflow"**

The automation will:
- ✅ Update the version in `package.json`
- ✅ Generate an updated `CHANGELOG.md` 
- ✅ Build and test the project
- ✅ Publish to NPM with public access
- ✅ Create a GitHub release with release notes
- ✅ Create and push a git tag

### Manual Release (Alternative)

For local releases, you can use the pnpm scripts:

```bash
# For patch release (0.0.1 → 0.0.2)
pnpm run version:patch && pnpm run release

# For minor release (0.0.1 → 0.1.0)  
pnpm run version:minor && pnpm run release

# For major release (0.0.1 → 1.0.0)
pnpm run version:major && pnpm run release
```

### Changelog Generation

The changelog is automatically generated based on [Conventional Commits](https://conventionalcommits.org/). Use these commit message prefixes:

- `feat:` - New features
- `fix:` - Bug fixes
- `docs:` - Documentation updates
- `style:` - Code style changes
- `refactor:` - Code refactoring
- `perf:` - Performance improvements
- `test:` - Testing changes
- `chore:` - Maintenance tasks

### GitHub Secrets Configuration

For the automated release to work, you need to configure these secrets in your GitHub repository:

1. Go to **Settings** > **Secrets and variables** > **Actions**
2. Add the following secrets:

| Secret Name | Description | How to Get |
|------------|-------------|------------|
| `NPM_TOKEN` | NPM authentication token | 1. Login to [npmjs.com](https://npmjs.com)<br/>2. Go to Access Tokens<br/>3. Generate a Classic Token with "Automation" type |
| `GITHUB_TOKEN` | GitHub Actions token | Automatically provided by GitHub Actions |

### First Time Setup

Before running the automated release:

1. **NPM Account**: Ensure you have an NPM account and are logged in
2. **Package Scope**: The package name `@original-land/n8n-nodes-original-agent` should be available or owned by you  
3. **Repository Access**: You need write access to the repository to push tags and create releases

### Test Installation

After release, verify the package works:

```bash
pnpm add @original-land/n8n-nodes-original-agent@latest
```

## Output Format

The node returns structured data in the following format:

```json
{
  "originalAgent": {
    "response": "AI Agent response text or parsed JSON",
    "streaming": true/false,
    "conversationId": "unique-conversation-identifier"
  },
  "botId": "configured-bot-id",
  "message": "processed-input-message"
}
```

## Error Handling

The node handles various error scenarios:

- **402 Payment Required**: When API credits are insufficient
- **API Failures**: Network or service unavailability
- **Authentication Errors**: Invalid API key or Bot ID
- **Parsing Errors**: Malformed API responses

## License

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

## Support

- **Issues**: [GitHub Issues](https://github.com/noku-team/n8n-original-agent/issues)
- **Original.land**: [Official Documentation](https://original.land)
- **n8n Community**: [n8n Community Forum](https://community.n8n.io/)