Skip to main content

Operator Usage Examples

This document provides practical usage examples for various types of operators, helping you quickly get started with operator development and usage.

Agent Operator Examples​

Example 1: Medical Aesthetics Marketing Agent​

A real-world agent operator configuration for generating Xiaohongshu marketing copy for medical aesthetics products.

Agent Configuration​

{
  "type": "agent",
  "config": {
    "id": "09dae2fc-6391-4aa9-8936-3636c836deaa",
    "name": "Medical Beauty Marketing Pro",
    "type": "agent",
    "description": "Intelligent marketing expert specializing in the medical aesthetics industry, skilled at writing product promotional posts suited for the Xiaohongshu platform, providing precision marketing strategies and user pain point solutions",
    "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": "target",
        "type": "string",
        "label": "Target Audience",
        "required": false
      },
      {
        "name": "context",
        "type": "boolean",
        "label": "Enable Knowledge Base Content",
        "required": false
      },
      {
        "name": "product",
        "type": "string",
        "label": "Product Name",
        "required": false
      },
      {
        "name": "features",
        "type": "string",
        "label": "Product Features",
        "required": false
      },
      {
        "name": "internet",
        "type": "boolean",
        "label": "Enable Internet Search",
        "required": false
      },
      {
        "name": "scenario",
        "type": "string",
        "label": "Usage Scenario",
        "required": false
      },
      {
        "name": "pain_point",
        "type": "string",
        "label": "User Pain Point",
        "required": false
      },
      {
        "name": "key_benefit",
        "type": "string",
        "label": "Key Benefit",
        "required": false
      }
    ],
    "outputPorts": [
      {
        "name": "answer",
        "type": "string",
        "label": "Generated Content"
      }
    ],
    "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"
        }
      }
    },
    "outputSchema": {
      "type": "object",
      "properties": {
        "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"
      }
    }
  },
  "position": {
    "x": -135,
    "y": 105
  },
  "defaultInputs": {},
  "metadata": {
    "origin": "built-in"
  }
}

Usage Example​

Input Data:

{
  "product": "Hyaluronic Acid Face Mask",
  "features": "Deep hydration, skin firming, anti-aging",
  "target": "Working women aged 25-35",
  "scenario": "Skin recovery after late-night work",
  "pain_point": "Dry, dehydrated skin with visible fine lines",
  "key_benefit": "24-hour continuous hydration"
}

Output Result:

{
  "answer": "🌟 Night owl savior alert! This Hyaluronic Acid Face Mask is absolutely incredible ✨\n\nAs someone who frequently pulls late nights at work, my biggest fear is looking at a dull, dry face in the mirror the next morning 😭 This hyaluronic acid mask is literally my lifeline!\n\n💧 24-hour continuous hydration is no joke:\n✅ Deep Hydration: Hyaluronic acid molecules penetrate straight to the skin's base layer\n✅ Skin Firming: Post-late-night sagging sensation improved instantly\n✅ Anti-Aging: Fine lines are visibly fading\n\nThe next day my skin is so dewy it glows, and my colleagues keep asking if I changed my skincare routine 🤩\n\n#MedicalAestheticsTrends #SkincareBlackTech #NightOwlEssentials #HyaluronicAcidMask\n\nGirls, this one is definitely worth stocking up on!"
}

Worker Operator Examples​

Example 1: Email Sender (Built-in System)​

A real-world Worker operator configuration.

{
  "type": "operator",
  "config": {
    "id": "7eb51af1-1f84-416c-8295-3a03b20391de",
    "name": "Email Sender",
    "type": "operator",
    "method": "default",
    "identifier": "email",
    "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"
      }
    ]
  },
  "position": {
    "x": 330,
    "y": 105
  },
  "defaultInputs": {
    "to": "joshua@magecommerce.com",
    "subject": "Test Email"
  },
  "metadata": {
    "origin": "built-in",
    "runtime": {
      "type": "worker",
      "config": {}
    }
  }
}

Example 2: Document Processing Operator​

Extract content from PDF documents.

{
  "name": "PDF Document Processor",
  "identifier": "pdf-processor",
  "description": "Extract and process PDF document content",
  "executionType": "worker",
  "methods": [
    {
      "name": "Extract Text Content",
      "identifier": "extract-text",
      "inputSchema": {
        "type": "object",
        "required": ["fileUrl"],
        "properties": {
          "fileUrl": {
            "type": "string",
            "title": "PDF File URL",
            "format": "uri",
            "isPort": true
          },
          "pageRange": {
            "type": "object",
            "title": "Page Range",
            "properties": {
              "start": {"type": "number", "title": "Start Page", "minimum": 1},
              "end": {"type": "number", "title": "End Page", "minimum": 1}
            }
          },
          "extractImages": {
            "type": "boolean",
            "title": "Extract Images",
            "default": false
          }
        }
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "title": "Extracted Text Content"
          },
          "images": {
            "type": "array",
            "title": "Extracted Images",
            "items": {
              "type": "object",
              "properties": {
                "url": {"type": "string", "title": "Image URL"},
                "page": {"type": "number", "title": "Page Number"}
              }
            }
          },
          "metadata": {
            "type": "object",
            "title": "Document Metadata",
            "properties": {
              "pageCount": {"type": "number", "title": "Total Pages"},
              "title": {"type": "string", "title": "Document Title"},
              "author": {"type": "string", "title": "Author"}
            }
          }
        }
      }
    }
  ]
}

API Operator Examples​

Example 1: Custom Email Sending API​

A real-world API operator configuration.

{
  "type": "operator",
  "config": {
    "id": "4e269cee-3a80-4049-a9c3-177b9fd6f9b5",
    "name": "Email Sender Plus",
    "type": "operator",
    "method": "default",
    "identifier": "email-operator",
    "inputPorts": [
      {
        "name": "cc",
        "type": "array",
        "label": "CC",
        "required": false
      },
      {
        "name": "to",
        "type": "string",
        "label": "Recipient",
        "required": true
      },
      {
        "name": "bcc",
        "type": "array",
        "label": "BCC",
        "required": false
      },
      {
        "name": "html",
        "type": "string",
        "label": "HTML Content",
        "required": false
      },
      {
        "name": "text",
        "type": "string",
        "label": "Text Content",
        "required": false
      },
      {
        "name": "subject",
        "type": "string",
        "label": "Email Subject",
        "required": true
      },
      {
        "name": "attachment_files",
        "type": "array",
        "label": "Attachment Files",
        "required": false
      }
    ],
    "outputPorts": [
      {
        "name": "data",
        "type": "object",
        "label": "Response Data"
      },
      {
        "name": "success",
        "type": "boolean",
        "label": "Send Status"
      }
    ]
  },
  "position": {
    "x": -90,
    "y": -45
  },
  "defaultInputs": {
    "to": "joshua@magecommerce.com",
    "text": "Test email content",
    "subject": "Test Email"
  },
  "metadata": {
    "runtime": {
      "type": "rest-api",
      "config": {
        "headers": [],
        "timeout": 30000,
        "serverUrl": "https://api.genispace.cn",
        "retryPolicy": {
          "intervalMs": 1000,
          "maxAttempts": 3
        },
        "method": "POST",
        "caching": {
          "enabled": false,
          "ttlSeconds": 3600
        },
        "endpoint": "https://api.genispace.cn/njs-operators/message/email_operator",
        "url": "https://api.genispace.cn/njs-operators/message/email_operator"
      }
    },
    "origin": "custom"
  }
}

Example 2: User Management API​

Create a user management operator providing CRUD operations for users.

Operator Configuration​

{
  "name": "User Management API",
  "identifier": "user-management-api",
  "description": "Provides CRUD operations for user information",
  "category": "api",
  "executionType": "api",
  "configuration": {
    "schema": {
      "type": "api",
      "properties": {
        "serverUrl": {
          "type": "string",
          "title": "Server URL",
          "required": true,
          "description": "User API server address"
        },
        "apiKey": {
          "type": "string",
          "title": "API Key",
          "format": "password",
          "required": true,
          "description": "API access key"
        }
      }
    },
    "values": {
      "serverUrl": "https://api.example.com",
      "apiKey": ""
    }
  }
}

Get User Info Method​

{
  "name": "Get User Info",
  "identifier": "get-user",
  "description": "Get detailed user information by user ID",
  "inputSchema": {
    "type": "object",
    "required": ["userId"],
    "properties": {
      "userId": {
        "type": "string",
        "title": "User ID",
        "description": "The user ID to query",
        "isPort": true
      },
      "includeProfile": {
        "type": "boolean",
        "title": "Include Details",
        "description": "Whether to include detailed user profile",
        "default": false
      }
    }
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "user": {
        "type": "object",
        "title": "User Information",
        "properties": {
          "id": {"type": "string", "title": "User ID"},
          "name": {"type": "string", "title": "Username"},
          "email": {"type": "string", "title": "Email"},
          "createdAt": {"type": "string", "title": "Created At"}
        }
      },
      "success": {
        "type": "boolean",
        "title": "Execution Status"
      }
    }
  },
  "configuration": {
    "schema": {
      "type": "object",
      "properties": {
        "method": {
          "type": "string",
          "title": "Request Method",
          "enum": ["GET"],
          "default": "GET"
        },
        "endpoint": {
          "type": "string",
          "title": "Endpoint Path",
          "required": true
        }
      }
    },
    "values": {
      "method": "GET",
      "endpoint": "/api/users/{userId}"
    }
  }
}

MCP Operator Examples​

Example 1: Intelligent Text Analyzer​

Perform text analysis using AI models.

{
  "name": "Intelligent Text Analyzer",
  "identifier": "ai-text-analyzer",
  "description": "Perform text analysis and processing using AI models",
  "executionType": "mcp",
  "systemConfiguration": {
    "schema": {
      "type": "mcp",
      "properties": {
        "serverUrl": {
          "type": "string",
          "title": "MCP Server URL",
          "required": true
        },
        "model": {
          "type": "string",
          "title": "AI Model",
          "enum": ["gpt-4", "gpt-3.5-turbo", "claude-3"],
          "default": "gpt-4"
        },
        "apiKey": {
          "type": "string",
          "title": "API Key",
          "format": "password",
          "required": true
        }
      }
    }
  },
  "methods": [
    {
      "name": "Sentiment Analysis",
      "identifier": "sentiment-analysis",
      "inputSchema": {
        "type": "object",
        "required": ["text"],
        "properties": {
          "text": {
            "type": "string",
            "title": "Text to Analyze",
            "maxLength": 5000,
            "isPort": true
          },
          "language": {
            "type": "string",
            "title": "Text Language",
            "enum": ["zh", "en", "auto"],
            "default": "auto"
          }
        }
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "sentiment": {
            "type": "string",
            "title": "Sentiment",
            "enum": ["positive", "negative", "neutral"]
          },
          "confidence": {
            "type": "number",
            "title": "Confidence",
            "minimum": 0,
            "maximum": 1
          },
          "keywords": {
            "type": "array",
            "title": "Keywords",
            "items": {"type": "string"}
          }
        }
      }
    }
  ]
}

Container Operator Examples​

Example 1: Python Data Processor​

Perform complex data processing using a Python container.

{
  "name": "Python Data Processor",
  "identifier": "python-data-processor",
  "description": "Perform complex data analysis and processing using Python",
  "executionType": "container",
  "systemConfiguration": {
    "schema": {
      "type": "container",
      "properties": {
        "image": {
          "type": "string",
          "title": "Docker Image",
          "default": "python:3.9-slim"
        },
        "command": {
          "type": "string",
          "title": "Execution Command",
          "default": "python /app/processor.py"
        },
        "environment": {
          "type": "object",
          "title": "Environment Variables",
          "properties": {
            "PYTHONPATH": {
              "type": "string",
              "default": "/app"
            }
          }
        },
        "resources": {
          "type": "object",
          "title": "Resource Limits",
          "properties": {
            "memory": {"type": "string", "default": "1Gi"},
            "cpu": {"type": "string", "default": "1"}
          }
        }
      }
    }
  },
  "methods": [
    {
      "name": "Statistical Analysis",
      "identifier": "statistical-analysis",
      "inputSchema": {
        "type": "object",
        "required": ["dataset"],
        "properties": {
          "dataset": {
            "type": "array",
            "title": "Dataset",
            "description": "Dataset to analyze",
            "isPort": true
          },
          "analysisType": {
            "type": "string",
            "title": "Analysis Type",
            "enum": ["descriptive", "correlation", "regression"],
            "default": "descriptive"
          },
          "outputFormat": {
            "type": "string",
            "title": "Output Format",
            "enum": ["json", "csv", "html"],
            "default": "json"
          }
        }
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "statistics": {
            "type": "object",
            "title": "Statistics Results",
            "properties": {
              "mean": {"type": "number", "title": "Mean"},
              "median": {"type": "number", "title": "Median"},
              "std": {"type": "number", "title": "Standard Deviation"}
            }
          },
          "charts": {
            "type": "array",
            "title": "Chart Data",
            "items": {
              "type": "object",
              "properties": {
                "type": {"type": "string", "title": "Chart Type"},
                "data": {"type": "object", "title": "Chart Data"}
              }
            }
          }
        }
      }
    }
  ]
}

Workflow Integration Examples​

Example: Medical Aesthetics Marketing Content Generation Workflow​

A real-world workflow demonstrating the combined use of Agent and Worker operators.

{
  "workflow": {
    "name": "Medical Aesthetics Product Xiaohongshu Content Publishing",
    "description": "Automated workflow for medical aesthetics product content publishing on Xiaohongshu, including content generation, compliance checking, scheduled publishing, and data feedback",
    "edges": [
      {
        "source": "agent-1747982793576:answer",
        "target": "operator-1747982806154:content"
      }
    ],
    "nodes": {
      "agent-1747982793576": {
        "type": "agent",
        "config": {
          "name": "Medical Beauty Marketing Pro",
          "description": "Intelligent marketing expert specializing in the medical aesthetics industry"
        },
        "position": {"x": -135, "y": 105},
        "defaultInputs": {},
        "metadata": {"origin": "built-in"}
      },
      "operator-1747982806154": {
        "type": "operator",
        "config": {
          "name": "Email Sender",
          "identifier": "email"
        },
        "position": {"x": 330, "y": 105},
        "defaultInputs": {
          "to": "joshua@magecommerce.com",
          "subject": "New Content Generated Notification"
        },
        "metadata": {
          "origin": "built-in",
          "runtime": {"type": "worker", "config": {}}
        }
      }
    }
  }
}

Workflow Execution Process:

  1. Agent Generates Content: Generates Xiaohongshu copy based on product information
  2. Email Notification: Sends the generated content via email to relevant personnel

Connection Description:

  • The agent's answer output connects to the email sender's content input
  • This implements an automated flow from content generation to notification delivery

Example: User Registration Workflow​

Demonstrates how to combine multiple operators in a workflow.

{
  "workflow": {
    "name": "User Registration Flow",
    "description": "Complete user registration and welcome workflow",
    "nodes": [
      {
        "id": "input",
        "type": "input",
        "data": {
          "schema": {
            "type": "object",
            "properties": {
              "email": {"type": "string", "format": "email"},
              "name": {"type": "string"},
              "password": {"type": "string"}
            }
          }
        }
      },
      {
        "id": "validate-user",
        "type": "operator",
        "operatorId": "user-management-api",
        "methodId": "validate-email",
        "configuration": {
          "serverUrl": "https://api.example.com"
        }
      },
      {
        "id": "create-user",
        "type": "operator",
        "operatorId": "user-management-api", 
        "methodId": "create-user",
        "configuration": {
          "serverUrl": "https://api.example.com"
        }
      },
      {
        "id": "send-welcome-email",
        "type": "operator",
        "operatorId": "email",
        "methodId": "default",
        "configuration": {
          "smtpServer": "smtp.example.com"
        }
      },
      {
        "id": "output",
        "type": "output"
      }
    ],
    "connections": [
      {
        "source": "input",
        "sourcePort": "email",
        "target": "validate-user",
        "targetPort": "email"
      },
      {
        "source": "validate-user",
        "sourcePort": "isValid",
        "target": "create-user",
        "targetPort": "proceed"
      },
      {
        "source": "input",
        "sourcePort": "name",
        "target": "create-user",
        "targetPort": "name"
      },
      {
        "source": "create-user",
        "sourcePort": "userId",
        "target": "send-welcome-email",
        "targetPort": "userId"
      },
      {
        "source": "send-welcome-email",
        "sourcePort": "success",
        "target": "output",
        "targetPort": "result"
      }
    ]
  }
}

Testing Examples​

Unit Tests​

{
  "testSuite": {
    "name": "Agent Operator Tests",
    "tests": [
      {
        "name": "Medical Aesthetics Copy Generation Test",
        "operatorId": "medical-beauty-agent",
        "methodId": "generate-content",
        "input": {
          "product": "Hyaluronic Acid Face Mask",
          "features": "Deep hydration, skin firming",
          "target": "Working women aged 25-35",
          "scenario": "Skin recovery after late-night work"
        },
        "expectedOutput": {
          "answer": "Xiaohongshu copy containing product features and target audience"
        }
      },
      {
        "name": "Email Sending Test",
        "operatorId": "email",
        "methodId": "default",
        "input": {
          "to": "test@example.com",
          "subject": "Test Email",
          "content": "This is a test email"
        },
        "expectedOutput": {
          "success": true,
          "messageId": "msg-12345"
        }
      }
    ]
  }
}

Performance Tests​

{
  "performanceTest": {
    "name": "Agent Performance Test",
    "operatorId": "medical-beauty-agent",
    "methodId": "generate-content",
    "scenarios": [
      {
        "name": "Single Content Generation",
        "concurrency": 1,
        "duration": "30s",
        "input": {
          "product": "Hyaluronic Acid Face Mask",
          "features": "Deep hydration"
        },
        "expectations": {
          "averageResponseTime": "< 3s",
          "errorRate": "< 1%"
        }
      },
      {
        "name": "Concurrent Content Generation",
        "concurrency": 10,
        "duration": "60s",
        "input": {
          "product": "Hyaluronic Acid Face Mask",
          "features": "Deep hydration"
        },
        "expectations": {
          "averageResponseTime": "< 5s",
          "errorRate": "< 5%",
          "throughput": "> 2 req/s"
        }
      }
    ]
  }
}

Best Practices Summary​

1. Design Principles​

  • Single Responsibility: Each operator should focus on a specific function
  • Interface Stability: Maintain backward-compatible interface design
  • Error Friendliness: Provide clear error messages and handling

2. Configuration Management​

  • Layered Configuration: Differentiate between operator-level and method-level configuration
  • Sensitive Information: Use system configuration to store sensitive data
  • Default Values: Provide reasonable defaults for all optional parameters

3. Performance Optimization​

  • Caching Strategy: Enable caching for appropriate operations
  • Resource Limits: Set reasonable resource usage limits
  • Timeout Handling: Configure appropriate timeout and retry mechanisms

4. Security Considerations​

  • Input Validation: Strictly validate all input parameters
  • Access Control: Implement appropriate access controls
  • Audit Logging: Record audit information for important operations