Otogent Nodes Reference

Summary

Otogent Nodes are the individual processing units within a Workflow DAG. Each Node has a type (one of 33 NodeType enum values), a configuration schema, input/output ports, optional credential bindings, and an execute function. This document provides the complete reference for every Node type, organized by category: Trigger, Action, Logic, and Transformation.

Purpose

This reference enables AI agents and developers to select the correct Node type for a given task, understand its configuration requirements, and predict its behavior within a Workflow Execution.

Concepts

See 00-glossary.md. Key terms: Node, Node Type, Port, Credential, Node Execution, Node Definition, Workflow Context.

Node Definition System

Every Node type is defined by a NodeDefinition interface:

interface NodeDefinition {
  type: NodeType;             // Enum value (e.g., "OPENAI", "HTTP_REQUEST")
  version: number;            // Schema version (default: 1)
  label: string;              // Display name in editor
  category: "trigger" | "action" | "logic" | "transformation";
  description?: string;       // Purpose description

  fields: NodeFieldDefinition[];      // UI configuration fields
  configSchema: ZodObject;            // Zod validation schema
  ports: PortDefinition[];            // Input/output connection points
  credentials: CredentialRequirement[]; // Required credential bindings

  execute?(ctx: NodeExecutionContext): Promise<NodeExecutionResult>;
  getSummary?(data: Config): string;
  migrate?(oldData: unknown, fromVersion: number): unknown;
}

Port System

Each Node has named input and output Ports:

interface PortDefinition {
  id: string;        // Handle name (e.g., "main", "true", "false", "error")
  label: string;     // Display label
  direction: "in" | "out";
  isDefault?: boolean;
}

Default port: { id: "main", direction: "out", isDefault: true }

Credential System

Nodes declare credential requirements:

interface CredentialRequirement {
  key: string;            // Access key in ctx.credentials[key]
  type: CredentialType;   // OPENAI | ANTHROPIC | GEMINI | GEMMA | HUGGINGFACE | COMPOSIO | GENERIC
  required: boolean;
}

At execution time, the engine:

1. Reads the credential ID from node.data[key]
2. Loads the Credential record from the database (scoped to Organization)
3. Decrypts valueEncrypted using the ENCRYPTION_KEY
4. Injects plaintext into ctx.credentials[key]

Execution Contract

Every Node executor returns:

interface NodeExecutionResult {
  status: "SUCCESS" | "FAILURE" | "RETRY";
  data: unknown;          // Output data merged into Workflow Context
  routeId: string;        // Output port handle (e.g., "main", "true", "error")
  error?: {
    message: string;
    code: string;
    stack?: string;
    isRetriable: boolean;
  };
}

Field Types

Configuration fields for the visual editor:

Trigger Nodes

Trigger Nodes initiate Workflow Execution. A Workflow may have one or more Trigger Nodes. When multiple Trigger Nodes exist, the engine uses resolveWorkflowStartNodeIds to determine which one activated the current Execution.

INITIAL

MANUAL_TRIGGER

WEBHOOK_TRIGGER

GOOGLE_FORM_TRIGGER

STRIPE_TRIGGER

SCHEDULE

Action Nodes — AI Models

OPENAI

ANTHROPIC

GEMINI

GEMMA

HUGGINGFACE

Action Nodes — Messaging

DISCORD

SLACK

TELEGRAM

EMAIL_SEND

EMAIL_PARSER

TWILIO_SMS

Action Nodes — Social Media

X

LINKEDIN

INSTAGRAM

Action Nodes — Data & Services

HTTP_REQUEST

GOOGLE_SHEETS

DB_QUERY

FILE_STORAGE

HUBSPOT

SHOPIFY

COMPOSIO

Logic Nodes

ROUTER

CONDITION

HUMAN_APPROVAL

MERGE

Transformation Nodes

SET_VARIABLE

TEXT_TEMPLATE

JSON_TRANSFORM

DELAY

LOGGER

Agent Instructions

When selecting a Node type for a Workflow step, use this reference to match the task to the correct Node type. Each Node type has a specific purpose — do not use generic Nodes when a specialized Node exists.

Node Selection Guide

IF task is "call an LLM"
  → Use OPENAI, ANTHROPIC, GEMINI, GEMMA, or HUGGINGFACE based on provider

IF task is "send a message"
  → Use DISCORD, SLACK, TELEGRAM, EMAIL_SEND, or TWILIO_SMS based on channel

IF task is "make an HTTP API call"
  → Use HTTP_REQUEST for arbitrary APIs, or a specific integration Node if available

IF task is "connect to a SaaS tool"
  → Use COMPOSIO for 250+ tools, or HUBSPOT/SHOPIFY for native integrations

IF task is "route based on a condition"
  → Use CONDITION for expression-based routing, ROUTER for state-based routing

IF task is "wait for human review"
  → Use HUMAN_APPROVAL

IF task is "transform data"
  → Use SET_VARIABLE, TEXT_TEMPLATE, or JSON_TRANSFORM

IF task is "add a delay"
  → Use DELAY

IF task is "log for debugging"
  → Use LOGGER

Decision Tree

IF you need an LLM call:
  IF you want OpenAI → OPENAI Node
  IF you want Claude → ANTHROPIC Node
  IF you want Gemini → GEMINI Node
  IF you want an open-source model → HUGGINGFACE Node
  IF you want Gemma → GEMMA Node

IF you need to send a notification:
  IF via Slack → SLACK Node
  IF via Discord → DISCORD Node
  IF via email → EMAIL_SEND Node
  IF via SMS → TWILIO_SMS Node
  IF via Telegram → TELEGRAM Node

IF you need conditional logic:
  IF evaluating an expression → CONDITION Node
  IF reading a state variable for routing → ROUTER Node
  IF requiring human decision → HUMAN_APPROVAL Node
  IF joining parallel paths → MERGE Node

Common Errors

Related Pages

• 00-glossary.md — Term definitions
• 02-workflows.md — Workflow structure
• 03-execution-engine.md — How Nodes execute
• 05-integrations.md — Integration details
• 06-security.md — Credential management