Skip to main content

Operator Overview

Operators are the core execution units of the GeniSpace workflow system, responsible for handling specific business logic and data operations. Each operator is an independent functional module that can receive input data, perform specific operations, and produce output results.

What Is an Operator​

Operators are the fundamental building blocks of a workflow, similar to functions or methods in programming. They have the following characteristics:

  • Input/Output Definitions: Each operator has clearly defined input and output data structures
  • Configuration Parameters: Supports flexible configuration options to adapt to different use cases
  • Reusability: The same operator can be reused across multiple workflows
  • Independent Execution: Each operator is an independent execution unit, making debugging and maintenance easy

Operator Types​

GeniSpace supports five different types of operators, each suited for different application scenarios:

1. Agent Operators​

Agent operators are intelligent processing units based on AI models, capable of understanding natural language instructions and generating intelligent output.

Features:

  • Intelligent processing based on Large Language Models (LLMs)
  • Support for natural language prompt templates
  • Configurable system prompts and user prompts
  • Support for enhanced capabilities such as memory, knowledge bases, and internet search

Use Cases:

  • Content generation and creation
  • Intelligent analysis and decision-making
  • Natural language processing
  • Intelligent customer service and dialogue

Configuration Example:

{
  "type": "agent",
  "name": "Medical Beauty Marketing Pro",
  "description": "Intelligent marketing expert specializing in the medical aesthetics industry",
  "promptTemplate": "Please write a Xiaohongshu promotional post for [{{product}}], key selling points: {{features}}",
  "systemPrompt": "You are an expert in medical aesthetics marketing on Xiaohongshu...",
  "model": {
    "identifier": "deepseek-v3",
    "name": "DeepSeek-V3",
    "apiType": "openai"
  }
}

2. API Operators​

API operators are used to call external HTTP/HTTPS interfaces and serve as bridges to external services.

Features:

  • Support for RESTful API calls
  • Flexible request configuration (methods, headers, parameters, etc.)
  • Automatic authentication handling and error retry
  • Support for multiple data formats (JSON, XML, form data, etc.)

Use Cases:

  • Calling third-party service APIs
  • Data synchronization and integration
  • External system interaction
  • Inter-microservice communication

Configuration Example:

{
  "runtime": {
    "type": "rest-api",
    "config": {
      "serverUrl": "https://api.genispace.cn",
      "method": "POST",
      "endpoint": "/njs-operators/message/email_operator",
      "timeout": 30000,
      "retryPolicy": {
        "maxAttempts": 3,
        "intervalMs": 1000
      }
    }
  }
}

3. Worker Operators​

Worker operators are built-in system operators that run within the GeniSpace Worker service, providing common data processing and business logic capabilities.

Features:

  • High-performance local execution
  • Rich built-in function library
  • Support for complex data processing logic
  • No external dependencies required

Use Cases:

  • Document processing and conversion
  • Data cleansing and formatting
  • Text analysis and processing
  • Image and media processing
  • Mathematical calculations and statistics

Built-in Operator Categories:

  • Document Processing: PDF parsing, Word conversion, Excel operations
  • Data Conversion: JSON processing, CSV conversion, data mapping
  • Text Processing: Regex matching, string operations, encoding conversion
  • Notification Services: Email sending, SMS notifications, message pushing

Configuration Example:

{
  "runtime": {
    "type": "worker",
    "config": {}
  },
  "identifier": "email",
  "name": "Email Sender"
}

4. MCP Operators​

MCP (Model Context Protocol) operators are used to interact with AI models and services that support the MCP protocol.

Features:

  • Standardized AI model interface
  • Support for multiple AI service providers
  • Unified context management
  • Intelligent dialogue and reasoning capabilities

Use Cases:

  • AI dialogue and Q&A
  • Text generation and summarization
  • Intelligent analysis and decision-making
  • Natural language processing

Configuration Example:

{
  "serverUrl": "https://mcp.ai-service.com",
  "model": "gpt-4",
  "maxTokens": 2048,
  "temperature": 0.7
}

5. Container Operators​

Container operators are based on Docker container technology and can run any containerized application or service.

Features:

  • Fully isolated execution environment
  • Support for any programming language and framework
  • Scalable resource configuration
  • Versioned deployment management

Use Cases:

  • Complex business logic processing
  • Applications in specific languages or frameworks
  • Tasks requiring special runtime environments
  • Third-party tool and service integration

Configuration Example:

{
  "image": "my-app:latest",
  "command": "python app.py",
  "environment": {
    "API_KEY": "secret"
  },
  "resources": {
    "memory": "512Mi",
    "cpu": "0.5"
  }
}

Role of Operators in Workflows​

Data Flow Processing​

Operators are connected through input and output ports, forming a data processing pipeline:

Input Data → Agent A → Intermediate Result → Operator B → Final Output

Real-World Workflow Example​

A workflow structure based on a real-world scenario:

Agent (Content Generation) → Worker Operator (Email Sending)

Connection Method:

{
  "edges": [
    {
      "source": "agent-1747982793576:answer",
      "target": "operator-1747982806154:content"
    }
  ]
}

Parallel Execution​

Multiple operators can process different data branches in parallel:

Input → Dispatch Operator → Operator A → Merge Operator → Output
                          → Operator B →
                          → Operator C →

Operator Configuration Structure​

Actual Operator Configuration Structure​

Based on real-world examples, the operator configuration structure includes:

{
  "type": "operator",  // or "agent"
  "config": {
    "id": "unique operator ID",
    "name": "operator display name",
    "type": "operator",
    "method": "default",  // method to execute
    "identifier": "operator identifier",
    "inputPorts": [
      {
        "name": "parameter name",
        "type": "data type",
        "label": "display label",
        "required": true/false
      }
    ],
    "outputPorts": [
      {
        "name": "output name",
        "type": "data type", 
        "label": "display label"
      }
    ]
  },
  "position": {"x": 100, "y": 200},
  "defaultInputs": {
    "parameter name": "default value"
  },
  "metadata": {
    "origin": "built-in" | "custom",
    "runtime": {
      "type": "worker" | "rest-api" | "container" | "mcp",
      "config": {}
    }
  }
}

Custom Operators vs Built-in System Operators​

Built-in System Operators​

Advantages:

  • Ready to use out of the box, no configuration needed
  • Thoroughly tested, stable and reliable
  • Performance-optimized for high execution efficiency
  • Officially maintained and updated

Limitations:

  • Functionality is relatively fixed
  • Cannot meet specialized business requirements
  • Updates depend on system versions

Custom Operators​

Advantages:

  • Full autonomous control
  • Can implement any business logic
  • Rapid response to business changes
  • Support for private deployment

Creation Methods:

  • Manual Creation: Configure operator inputs, outputs, and business logic from scratch
  • OpenAPI Import: Quickly import multiple API methods as operators from OpenAPI/Swagger documents
  • Docker Container: Create operators based on containerized applications (Enterprise edition feature)
Important Notes
  • Requires self-development and maintenance
  • Security and stability must be considered
  • Detailed documentation should be written

Operator Development Best Practices​

1. Design Principles​

  • Single Responsibility: Each operator should be responsible for only one clear function
  • Idempotency: The same input should always produce the same output
  • Error Handling: Handle exceptions gracefully
  • Performance Considerations: Avoid long-running blocking operations

2. Input/Output Design​

  • Use clear data structure definitions
  • Provide detailed field descriptions
  • Consider backward compatibility
  • Support optional parameters

3. Configuration Management​

  • Separate user configuration from system configuration
  • Provide reasonable default values
  • Support environment variable overrides
  • Encrypt sensitive information in storage

4. Testing and Documentation​

  • Write comprehensive unit tests
  • Provide usage examples
  • Document known limitations and considerations
  • Maintain a version changelog

Next Steps​