Skip to main content

Operator Configuration Specification

This document provides a detailed introduction to the configuration structure and specifications of GeniSpace operators, including input/output schema definitions, configuration parameter management, and other core concepts.

Configuration Structure Overview​

Each operator contains the following main configuration sections:

{
  "name": "Operator Name",
  "identifier": "operator-id",
  "description": "Operator Description",
  "type": "operator",  // or "agent"
  "inputPorts": [ /* input port definitions */ ],
  "outputPorts": [ /* output port definitions */ ],
  "inputSchema": { /* input data structure definition */ },
  "outputSchema": { /* output data structure definition */ },
  "configuration": {
    "schema": { /* user configuration item definitions */ },
    "values": { /* default configuration values */ }
  },
  "systemConfiguration": {
    "schema": { /* system configuration item definitions */ },
    "values": { /* system configuration values */ }
  },
  "metadata": {
    "origin": "built-in" | "custom",
    "runtime": {
      "type": "worker" | "rest-api" | "container" | "mcp",
      "config": {}
    }
  }
}

Operator Type Configuration​

Agent Operator Configuration​

Agent operators have a special configuration structure that includes AI model-related settings:

{
  "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}}, target audience: {{target}}, usage scenario: {{scenario}}. Highlight {{key_benefit}} and address the {{pain_point}} issue",
  "systemPrompt": "You are an expert in medical aesthetics marketing on Xiaohongshu, following these guidelines:\n1. Content complies with Xiaohongshu community standards, using language styles preferred by young women\n2. Use scenario-based descriptions with emoji symbols\n3. Include relevant hashtags (#MedicalAestheticsTrends #SkincareBlackTech)\n4. Highlight product ingredients/technology advantages related to user pain points\n5. Avoid prohibited advertising terms, using an experience-sharing format\n6. Provide customized recommendations based on user segments (age/skin type/spending capacity)",
  "inputPorts": [
    {
      "name": "memory",
      "type": "boolean",
      "label": "Enable Conversation History Memory",
      "required": false
    },
    {
      "name": "product",
      "type": "string",
      "label": "Product Name",
      "required": false
    },
    {
      "name": "features",
      "type": "string",
      "label": "Product Features",
      "required": false
    }
  ],
  "outputPorts": [
    {
      "name": "answer",
      "type": "string",
      "label": "Generated Content"
    }
  ],
  "model": {
    "id": "3638ac90-902e-424c-84fd-a100d9e97b43",
    "identifier": "deepseek-v3",
    "name": "DeepSeek-V3",
    "apiType": "openai",
    "modelType": "text",
    "systemConfiguration": {
      "model": "deepseek-v3",
      "apiKey": "sk-xxx",
      "apiUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "provider": "alibaba"
    }
  }
}

Worker Operator Configuration​

Configuration structure for Worker operators:

{
  "type": "operator",
  "name": "Email Sender",
  "identifier": "email",
  "method": "default",
  "inputPorts": [
    {
      "name": "to",
      "type": "string",
      "label": "Recipient",
      "required": true
    },
    {
      "name": "content",
      "type": "string",
      "label": "Email Content",
      "required": true
    },
    {
      "name": "subject",
      "type": "string",
      "label": "Email Subject",
      "required": true
    },
    {
      "name": "attachments",
      "type": "array",
      "label": "Attachments",
      "required": false
    }
  ],
  "outputPorts": [
    {
      "name": "success",
      "type": "boolean",
      "label": "Send Status"
    },
    {
      "name": "messageId",
      "type": "string",
      "label": "Message ID"
    }
  ],
  "metadata": {
    "origin": "built-in",
    "runtime": {
      "type": "worker",
      "config": {}
    }
  }
}

API Operator Configuration​

Configuration structure for API operators:

{
  "type": "operator",
  "name": "Email Sender Plus",
  "identifier": "email-operator",
  "method": "default",
  "inputPorts": [
    {
      "name": "to",
      "type": "string",
      "label": "Recipient",
      "required": true
    },
    {
      "name": "cc",
      "type": "array",
      "label": "CC",
      "required": false
    },
    {
      "name": "bcc",
      "type": "array",
      "label": "BCC",
      "required": false
    },
    {
      "name": "subject",
      "type": "string",
      "label": "Subject",
      "required": true
    },
    {
      "name": "text",
      "type": "string",
      "label": "Text Content",
      "required": false
    },
    {
      "name": "html",
      "type": "string",
      "label": "HTML Content",
      "required": false
    },
    {
      "name": "attachment_files",
      "type": "array",
      "label": "Attachment Files",
      "required": false
    }
  ],
  "outputPorts": [
    {
      "name": "success",
      "type": "boolean",
      "label": "Send Status"
    },
    {
      "name": "data",
      "type": "object",
      "label": "Response Data"
    }
  ],
  "metadata": {
    "origin": "custom",
    "runtime": {
      "type": "rest-api",
      "config": {
        "serverUrl": "https://api.genispace.cn",
        "method": "POST",
        "endpoint": "https://api.genispace.cn/njs-operators/message/email_operator",
        "timeout": 30000,
        "retryPolicy": {
          "maxAttempts": 3,
          "intervalMs": 1000
        },
        "caching": {
          "enabled": false,
          "ttlSeconds": 3600
        },
        "headers": []
      }
    }
  }
}

Input Schema​

The Input Schema defines the input data structure accepted by an operator, based on the JSON Schema standard.

Agent Input Schema​

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "memory": {
        "type": "boolean",
        "default": false,
        "description": "Enable conversation history memory"
      },
      "target": {
        "type": "string",
        "description": "Target audience"
      },
      "context": {
        "type": "boolean",
        "default": false,
        "description": "Enable knowledge base content"
      },
      "product": {
        "type": "string",
        "description": "Product name"
      },
      "features": {
        "type": "string",
        "description": "Product features"
      },
      "internet": {
        "type": "boolean",
        "default": false,
        "description": "Enable internet search"
      },
      "scenario": {
        "type": "string",
        "description": "Usage scenario"
      },
      "pain_point": {
        "type": "string",
        "description": "User pain point"
      },
      "key_benefit": {
        "type": "string",
        "description": "Key benefit"
      }
    }
  }
}

Basic Structure​

{
  "type": "object",
  "required": ["param1"],
  "properties": {
    "param1": {
      "type": "string",
      "title": "Parameter 1",
      "description": "Description of Parameter 1",
      "isPort": true
    },
    "param2": {
      "type": "number",
      "title": "Parameter 2",
      "description": "Description of Parameter 2",
      "default": 100,
      "minimum": 0,
      "maximum": 1000
    }
  }
}

Supported Data Types​

1. String Type (string)​

{
  "type": "string",
  "title": "Text Input",
  "description": "Please enter text content",
  "minLength": 1,
  "maxLength": 1000,
  "pattern": "^[a-zA-Z0-9]+$",
  "default": "default value"
}

2. Number Type (number/integer)​

{
  "type": "number",
  "title": "Numeric Input",
  "description": "Please enter a number",
  "minimum": 0,
  "maximum": 100,
  "multipleOf": 0.1,
  "default": 50
}

3. Boolean Type (boolean)​

{
  "type": "boolean",
  "title": "Toggle Option",
  "description": "Whether to enable this feature",
  "default": false
}

4. Array Type (array)​

{
  "type": "array",
  "title": "List Data",
  "description": "Data list",
  "items": {
    "type": "string"
  },
  "minItems": 1,
  "maxItems": 10,
  "uniqueItems": true
}

5. Object Type (object)​

{
  "type": "object",
  "title": "Configuration Object",
  "description": "Complex configuration object",
  "properties": {
    "name": {
      "type": "string",
      "title": "Name"
    },
    "value": {
      "type": "number",
      "title": "Value"
    }
  },
  "required": ["name"]
}

Port Identification​

Use the isPort attribute to indicate whether a field is a workflow connection port:

{
  "param1": {
    "type": "string",
    "title": "Input Data",
    "isPort": true,  // Identified as a port, connectable in workflows
    "description": "Data from upstream nodes"
  },
  "config1": {
    "type": "string",
    "title": "Configuration Parameter",
    "isPort": false, // Not a port, used only as a configuration parameter
    "description": "Operator configuration parameter"
  }
}

Default Value Settings​

Default values can be set for input parameters:

{
  "properties": {
    "timeout": {
      "type": "number",
      "title": "Timeout",
      "description": "Request timeout in seconds",
      "default": 30,
      "minimum": 1,
      "maximum": 300
    },
    "retryCount": {
      "type": "integer",
      "title": "Retry Count",
      "description": "Number of retries on failure",
      "default": 3,
      "minimum": 0,
      "maximum": 10
    }
  }
}

Output Schema​

The Output Schema defines the output data structure produced by an operator.

Agent Output Schema​

{
  "outputSchema": {
    "type": "object",
    "properties": {
      "answer": {
        "type": "string",
        "label": "Generated Content",
        "description": "AI-generated response content"
      }
    }
  }
}

Basic Structure​

{
  "type": "object",
  "properties": {
    "result": {
      "type": "object",
      "title": "Processing Result",
      "description": "Result data from operator execution",
      "properties": {
        "status": {
          "type": "string",
          "title": "Status",
          "enum": ["success", "error"]
        },
        "data": {
          "type": "object",
          "title": "Data",
          "description": "Actual result data"
        },
        "message": {
          "type": "string",
          "title": "Message",
          "description": "Execution message or error information"
        }
      }
    },
    "metadata": {
      "type": "object",
      "title": "Metadata",
      "description": "Metadata about the execution process",
      "properties": {
        "executionTime": {
          "type": "number",
          "title": "Execution Time",
          "description": "Operator execution duration in milliseconds"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "format": "date-time"
        }
      }
    }
  }
}

Conditional Output​

For operators with conditional branches, multiple output ports can be defined:

{
  "type": "object",
  "properties": {
    "success": {
      "type": "object",
      "title": "Success Output",
      "description": "Output when processing succeeds",
      "isPort": true
    },
    "error": {
      "type": "object",
      "title": "Error Output",
      "description": "Output when processing fails",
      "isPort": true
    }
  }
}

Configuration Management​

Operator configuration is divided into two levels: operator-level configuration and method-level configuration.

Operator-Level Configuration​

Operator-level configuration is global configuration that affects the entire operator's behavior:

{
  "configuration": {
    "schema": {
      "type": "object",
      "properties": {
        "serverUrl": {
          "type": "string",
          "title": "Server URL",
          "description": "Base URL of the API server",
          "required": true,
          "format": "uri"
        },
        "timeout": {
          "type": "number",
          "title": "Global Timeout",
          "description": "Request timeout in milliseconds",
          "default": 30000,
          "minimum": 1000,
          "maximum": 300000
        },
        "headers": {
          "type": "array",
          "title": "Global Headers",
          "description": "Global headers applied to all requests",
          "items": {
            "type": "object",
            "properties": {
              "key": {
                "type": "string",
                "title": "Header Name"
              },
              "value": {
                "type": "string",
                "title": "Header Value"
              }
            },
            "required": ["key", "value"]
          }
        },
        "retryPolicy": {
          "type": "object",
          "title": "Global Retry Policy",
          "properties": {
            "maxAttempts": {
              "type": "number",
              "title": "Max Retry Attempts",
              "default": 3,
              "minimum": 0,
              "maximum": 10
            },
            "intervalMs": {
              "type": "number",
              "title": "Retry Interval",
              "description": "Retry interval in milliseconds",
              "default": 1000,
              "minimum": 100
            }
          }
        }
      }
    },
    "values": {
      "serverUrl": "",
      "timeout": 30000,
      "headers": [
        {"key": "Content-Type", "value": "application/json"}
      ],
      "retryPolicy": {
        "maxAttempts": 3,
        "intervalMs": 1000
      }
    }
  }
}

Method-Level Configuration​

Each operator method can have its own specific configuration:

{
  "methods": [
    {
      "name": "Get User Info",
      "identifier": "get-user",
      "configuration": {
        "schema": {
          "type": "object",
          "properties": {
            "method": {
              "type": "string",
              "title": "Request Method",
              "enum": ["GET", "POST", "PUT", "DELETE"],
              "default": "GET",
              "required": true
            },
            "endpoint": {
              "type": "string",
              "title": "Endpoint Path",
              "description": "Endpoint path relative to the server URL",
              "required": true,
              "pattern": "^/"
            },
            "caching": {
              "type": "object",
              "title": "Caching Configuration",
              "properties": {
                "enabled": {
                  "type": "boolean",
                  "title": "Enable Caching",
                  "default": false
                },
                "ttlSeconds": {
                  "type": "number",
                  "title": "Cache Duration",
                  "description": "Cache validity period in seconds",
                  "default": 3600,
                  "minimum": 60
                }
              }
            },
            "headers": {
              "type": "array",
              "title": "Method-Specific Headers",
              "description": "Headers applied only to this method",
              "items": {
                "type": "object",
                "properties": {
                  "key": {"type": "string"},
                  "value": {"type": "string"}
                }
              }
            }
          }
        },
        "values": {
          "method": "GET",
          "endpoint": "/api/users/{id}",
          "caching": {
            "enabled": true,
            "ttlSeconds": 1800
          },
          "headers": []
        }
      }
    }
  ]
}

System Configuration​

System configuration consists of internal settings invisible to users, used for storing sensitive information and system-level parameters.

Operator-Level System Configuration​

{
  "systemConfiguration": {
    "schema": {
      "type": "api",
      "properties": {
        "internalServerUrl": {
          "type": "string",
          "title": "Internal Server URL",
          "description": "Internal API server address",
          "required": true
        },
        "apiKey": {
          "type": "string",
          "title": "API Key",
          "description": "System-level API key",
          "format": "password",
          "required": true
        },
        "rateLimiting": {
          "type": "object",
          "title": "Rate Limiting Configuration",
          "properties": {
            "requestsPerSecond": {
              "type": "number",
              "title": "Requests Per Second",
              "default": 10
            },
            "burstSize": {
              "type": "number",
              "title": "Burst Size",
              "default": 20
            }
          }
        }
      }
    },
    "values": {
      "internalServerUrl": "https://internal-api.example.com",
      "apiKey": "system-secret-key",
      "rateLimiting": {
        "requestsPerSecond": 10,
        "burstSize": 20
      }
    }
  }
}

Method-Level System Configuration​

{
  "methods": [
    {
      "systemConfiguration": {
        "schema": {
          "type": "api",
          "properties": {
            "internalEndpoint": {
              "type": "string",
              "title": "Internal Endpoint Path",
              "required": true
            },
            "authToken": {
              "type": "string",
              "title": "Authentication Token",
              "format": "password"
            }
          }
        },
        "values": {
          "internalEndpoint": "/internal/users",
          "authToken": "method-specific-token"
        }
      }
    }
  ]
}

Configuration Type Details​

Configuration Differences by Execution Type​

API Type Operators​

{
  "metadata": {
    "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
        },
        "caching": {
          "enabled": false,
          "ttlSeconds": 3600
        },
        "headers": []
      }
    }
  }
}

Worker Type Operators​

{
  "metadata": {
    "runtime": {
      "type": "worker",
      "config": {}
    }
  }
}

MCP Type Operators​

{
  "systemConfiguration": {
    "schema": {
      "type": "mcp",
      "properties": {
        "serverUrl": {"type": "string", "required": true},
        "model": {"type": "string", "required": true},
        "apiKey": {"type": "string", "format": "password"},
        "timeout": {"type": "number", "default": 60000}
      }
    }
  }
}

Container Type Operators​

{
  "systemConfiguration": {
    "schema": {
      "type": "container",
      "properties": {
        "image": {"type": "string", "required": true},
        "registry": {
          "type": "object",
          "properties": {
            "url": {"type": "string"},
            "username": {"type": "string"},
            "password": {"type": "string", "format": "password"}
          }
        },
        "resources": {
          "type": "object",
          "properties": {
            "memory": {"type": "string", "default": "512Mi"},
            "cpu": {"type": "string", "default": "0.5"}
          }
        }
      }
    }
  }
}

Configuration Validation​

Schema Validation Rules​

  1. Required Field Validation: Use the required array to specify required fields
  2. Data Type Validation: Strictly validate field data types
  3. Format Validation: Use the format attribute to validate specific formats (e.g., email, uri, date-time)
  4. Range Validation: Use minimum, maximum, minLength, maxLength, etc.
  5. Enumeration Validation: Use enum to restrict allowed values
  6. Regex Validation: Use pattern for regular expression validation

Example Validation Configuration​

{
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "title": "Email Address"
    },
    "url": {
      "type": "string",
      "format": "uri",
      "pattern": "^https?://",
      "title": "URL"
    },
    "port": {
      "type": "integer",
      "minimum": 1,
      "maximum": 65535,
      "title": "Port Number"
    },
    "status": {
      "type": "string",
      "enum": ["active", "inactive", "pending"],
      "title": "Status"
    }
  },
  "required": ["email", "url"]
}

Best Practices​

1. Schema Design Principles​

  • Clear Naming: Use meaningful field names and titles
  • Detailed Descriptions: Provide clear descriptions for each field
  • Reasonable Defaults: Provide sensible default values for optional fields
  • Appropriate Validation: Add necessary validation rules without being overly restrictive

2. Configuration Layering​

  • Operator-Level Configuration: Global, common configuration
  • Method-Level Configuration: Configuration specific to a particular method
  • User Configuration: Parameters visible and configurable by users
  • System Configuration: Sensitive internal configurations used by the system

3. Backward Compatibility​

  • Adding Fields: Always provide default values
  • Modifying Fields: Maintain backward compatibility; consider using new field names
  • Removing Fields: Mark as deprecated rather than deleting directly

4. Security Considerations​

  • Sensitive Information: Use format: "password" to mark sensitive fields
  • Input Validation: Strictly validate all input data
  • Access Control: Differentiate access permissions between user and system configurations