Overview

Handit.AI gives you two powerful ways to define and launch your agents—whether you prefer a visual interface or full programmatic control. Pick the method that best fits your workflow and technical preferences.

1. Interactive Agent Setup

Build your agent using Handit.AI’s intuitive visual interface—no code required.

This method is perfect for users who want a fast, guided setup experience with full visibility into the agent’s behavior. Ideal for testing, prototyping, and cross-functional teams.

Key Features:

• Drag-and-drop node configuration

• Visual builder for defining the agent’s flow

• Real-time validation of connections and inputs

• Instantly generates a configuration behind the scenes

Recommended for: Most users, especially when starting out or collaborating with non-technical team members.

2. Define your Agent with a JSON Configuration

Manually create your agent by writing and uploading a JSON config file.

This option is designed for developers and advanced users who want total control over how their agent is structured and how it integrates into their systems.

Key Advantages:

• Direct, low-level control over agent structure

• Easily stored and tracked in version control systems

• Ideal for programmatic generation or dynamic agents

• Supports complex or highly customized setups

Recommended for: Technical teams, power users, or when integrating with custom pipelines or CI/CD environments.

Choose Your Method

• Use Interactive Agent Setup if you want a simple, visual experience with instant feedback.

• Use Manual JSON Configuration if you need more flexibility, automation, or tight integration with your stack.

Best Practices

Node Configuration

Keep Nodes Focused on a Single Task

• Each node should have one clear responsibility

• Avoid combining multiple operations in a single node

• Example:

  // Good: Single responsibility
  {
    "name": "Text Classification",
    "slug": "text-classifier",
    "description": "Classifies text into predefined categories",
    "type": "model",
    "problem_type": "classification"
  }
  
  // Avoid: Multiple responsibilities
  {
    "name": "Text Processing and Classification",
    "slug": "text-processor-classifier",
    "description": "Processes text, normalizes it, and classifies it",
    "type": "model",
    "problem_type": "text-processing-classification"
  }

Use Clear, Descriptive Names

• Names should be self-explanatory

• Use consistent naming patterns

• Example:

  // Good: Clear and descriptive
  {
    "name": "Sentiment Analyzer",
    "slug": "sentiment-analyzer"
  }
  
  // Avoid: Unclear or generic
  {
    "name": "Text Node 1",
    "slug": "node1"
  }

Include Helpful Descriptions

• Describe the node's purpose and behavior

• Include any important constraints or requirements

• Example:

  // Good: Detailed description
  {
    "name": "Language Detector",
    "slug": "lang-detector",
    "description": "Detects the primary language of input text. Supports 50+ languages. Returns ISO 639-1 language code."
  }
  
  // Avoid: Vague description
  {
    "name": "Language Detector",
    "slug": "lang-detector",
    "description": "Detects language"
  }

Set Appropriate Problem Types

• Choose the most specific problem type

• Match the node's actual functionality

• Example:

  // Good: Specific problem type
  {
    "name": "Question Answering",
    "slug": "qa-system",
    "type": "model",
    "problem_type": "question-answering"
  }
  
  // Avoid: Generic problem type
  {
    "name": "Question Answering",
    "slug": "qa-system",
    "type": "model",
    "problem_type": "text-processing"
  }

Flow Design

Create Logical Node Connections

• Design flows that follow natural data processing steps

• Consider data dependencies between nodes

• Example:

  // Good: Logical flow
  {
    "nodes": [
      {
        "name": "Text Preprocessor",
        "slug": "text-preprocessor",
        "next_nodes": ["sentiment-analyzer"]
      },
      {
        "name": "Sentiment Analyzer",
        "slug": "sentiment-analyzer",
        "next_nodes": ["response-formatter"]
      }
    ]
  }
  
  // Avoid: Unclear flow
  {
    "nodes": [
      {
        "name": "Text Preprocessor",
        "slug": "text-preprocessor",
        "next_nodes": ["response-formatter", "sentiment-analyzer"]
      }
    ]
  }

Avoid Circular Dependencies

• Ensure nodes don't create infinite loops

• Validate flow paths

• Example:

  // Good: Linear flow
  {
    "nodes": [
      {
        "name": "Input Validator",
        "slug": "input-validator",
        "next_nodes": ["processor"]
      },
      {
        "name": "Processor",
        "slug": "processor",
        "next_nodes": ["output-formatter"]
      }
    ]
  }
  
  // Avoid: Circular dependency
  {
    "nodes": [
      {
        "name": "Input Validator",
        "slug": "input-validator",
        "next_nodes": ["processor"]
      },
      {
        "name": "Processor",
        "slug": "processor",
        "next_nodes": ["input-validator"]
      }
    ]
  }

Keep Flows Simple and Maintainable

• Break complex flows into smaller, manageable components

• Use clear naming conventions for flow sections

• Example:

  // Good: Modular flow
  {
    "nodes": [
      {
        "name": "Input Handler",
        "slug": "input-handler",
        "next_nodes": ["data-validator"]
      },
      {
        "name": "Data Validator",
        "slug": "data-validator",
        "next_nodes": ["processor"]
      }
    ]
  }
  
  // Avoid: Complex, monolithic flow
  {
    "nodes": [
      {
        "name": "Main Processor",
        "slug": "main-processor",
        "next_nodes": ["validator", "formatter", "output-handler"]
      }
    ]
  }

Test Flows Before Deployment

• Validate node connections

• Test with sample data

• Verify error handling

• Example:

  // Good: Testable flow
  {
    "nodes": [
      {
        "name": "Input Handler",
        "slug": "input-handler",
        "type": "tool",
        "next_nodes": ["validator"]
      },
      {
        "name": "Validator",
        "slug": "validator",
        "type": "tool",
        "next_nodes": ["processor"]
      }
    ]
  }

Configuration Management

Use Version Control for JSON Files

• Track all configuration changes

• Use meaningful commit messages

• Maintain configuration history

• Example:

  // Good: Version controlled
  {
    "version": "1.0.0",
    "last_updated": "2024-03-21",
    "agent": {
      "name": "Text Processor",
      "slug": "text-processor-v1"
    }
  }

Follow Consistent Naming Conventions

• Use kebab-case for slugs

• Use PascalCase for node names

• Maintain consistent terminology

• Example:

  // Good: Consistent naming
  {
    "agent": {
      "name": "TextProcessor",
      "slug": "text-processor",
      "nodes": [
        {
          "name": "InputValidator",
          "slug": "input-validator"
        },
        {
          "name": "DataProcessor",
          "slug": "data-processor"
        }
      ]
    }
  }

[Image placeholder: Best practices examples]