跳到主要内容

工具使用示例

本文档提供了各种类型工具的实际使用示例，帮助您快速上手工具的开发和使用。

智能体（Agent）工具示例​

示例 1：医美营销智能体​

基于真实案例的智能体工具配置，用于生成医美产品的小红书营销文案。

智能体配置​

{
  "type": "agent",
  "config": {
    "id": "09dae2fc-6391-4aa9-8936-3636c836deaa",
    "name": "医美营销Pro",
    "type": "agent",
    "description": "专注医美行业的智能营销专家，擅长撰写符合小红书平台特性的产品种草文案，提供精准营销策略与用户痛点解决方案",
    "promptTemplate": "请为【{{product}}】撰写小红书种草文案，核心卖点：{{features}}，目标人群：{{target}}，使用场景：{{scenario}}。要求突出{{key_benefit}}并解决{{pain_point}}问题",
    "systemPrompt": "你是一位精通医美行业的小红书运营专家，需遵循以下准则：\n1. 文案符合小红书社区规范，采用年轻女性偏好的语言风格\n2. 使用场景化描述搭配emoji表情符号\n3. 植入相关话题标签（#医美新趋势 #护肤黑科技）\n4. 突出产品成分/技术优势与用户痛点关联\n5. 规避广告法禁用词汇，采用体验分享形式\n6. 结合用户分层（年龄/肤质/消费能力）提供定制化方案",
    "inputPorts": [
      {
        "name": "memory",
        "type": "boolean",
        "label": "启用历史对话记忆",
        "required": false
      },
      {
        "name": "target",
        "type": "string",
        "label": "目标人群",
        "required": false
      },
      {
        "name": "context",
        "type": "boolean",
        "label": "启用知识库内容",
        "required": false
      },
      {
        "name": "product",
        "type": "string",
        "label": "产品名称",
        "required": false
      },
      {
        "name": "features",
        "type": "string",
        "label": "产品特性",
        "required": false
      },
      {
        "name": "internet",
        "type": "boolean",
        "label": "启用互联网搜索",
        "required": false
      },
      {
        "name": "scenario",
        "type": "string",
        "label": "使用场景",
        "required": false
      },
      {
        "name": "pain_point",
        "type": "string",
        "label": "用户痛点",
        "required": false
      },
      {
        "name": "key_benefit",
        "type": "string",
        "label": "核心利益点",
        "required": false
      }
    ],
    "outputPorts": [
      {
        "name": "answer",
        "type": "string",
        "label": "生成内容"
      }
    ],
    "inputSchema": {
      "type": "object",
      "properties": {
        "memory": {
          "type": "boolean",
          "default": false,
          "description": "启用历史对话记忆"
        },
        "target": {
          "type": "string",
          "description": "目标人群"
        },
        "context": {
          "type": "boolean",
          "default": false,
          "description": "启用知识库内容"
        },
        "product": {
          "type": "string",
          "description": "产品名称"
        },
        "features": {
          "type": "string",
          "description": "产品特性"
        },
        "internet": {
          "type": "boolean",
          "default": false,
          "description": "启用互联网搜索"
        },
        "scenario": {
          "type": "string",
          "description": "使用场景"
        },
        "pain_point": {
          "type": "string",
          "description": "用户痛点"
        },
        "key_benefit": {
          "type": "string",
          "description": "核心利益点"
        }
      }
    },
    "outputSchema": {
      "type": "object",
      "properties": {
        "answer": {
          "type": "string",
          "label": "生成内容"
        }
      }
    },
    "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"
  }
}

使用示例​

输入数据：

{
  "product": "玻尿酸面膜",
  "features": "深层补水、紧致肌肤、抗衰老",
  "target": "25-35岁职场女性",
  "scenario": "熬夜加班后的肌肤修复",
  "pain_point": "肌肤干燥缺水、细纹明显",
  "key_benefit": "24小时持续补水"
}

输出结果：

{
  "answer": "🌟熬夜党的救星来了！玻尿酸面膜真的太绝了✨\n\n作为一个经常熬夜加班的打工人，最怕的就是第二天照镜子看到干瘪瘪的脸😭 这款玻尿酸面膜简直是我的续命神器！\n\n💧24小时持续补水不是说说而已：\n✅ 深层补水：玻尿酸分子直达肌底\n✅ 紧致肌肤：熬夜后的松弛感瞬间改善\n✅ 抗衰老：细纹真的肉眼可见地淡化了\n\n用完第二天皮肤水润到发光，同事都问我是不是换了护肤品🤩\n\n#医美新趋势 #护肤黑科技 #熬夜党必备 #玻尿酸面膜\n\n姐妹们，这个真的值得囤！"
}

Worker 工具示例​

示例 1：邮件发送器（系统内置）​

基于真实案例的 Worker 工具配置。

{
  "type": "operator",
  "config": {
    "id": "7eb51af1-1f84-416c-8295-3a03b20391de",
    "name": "邮件发送器",
    "type": "operator",
    "method": "default",
    "identifier": "email",
    "inputPorts": [
      {
        "name": "to",
        "type": "string",
        "label": "收件人",
        "required": true
      },
      {
        "name": "content",
        "type": "string",
        "label": "邮件内容",
        "required": true
      },
      {
        "name": "subject",
        "type": "string",
        "label": "邮件主题",
        "required": true
      },
      {
        "name": "attachments",
        "type": "array",
        "label": "附件",
        "required": false
      }
    ],
    "outputPorts": [
      {
        "name": "success",
        "type": "boolean",
        "label": "发送状态"
      },
      {
        "name": "messageId",
        "type": "string",
        "label": "消息ID"
      }
    ]
  },
  "position": {
    "x": 330,
    "y": 105
  },
  "defaultInputs": {
    "to": "joshua@magecommerce.com",
    "subject": "测试邮件"
  },
  "metadata": {
    "origin": "built-in",
    "runtime": {
      "type": "worker",
      "config": {}
    }
  }
}

示例 2：文档处理工具​

处理 PDF 文档的内容提取。

{
  "name": "PDF 文档处理器",
  "identifier": "pdf-processor",
  "description": "提取和处理 PDF 文档内容",
  "executionType": "worker",
  "methods": [
    {
      "name": "提取文本内容",
      "identifier": "extract-text",
      "inputSchema": {
        "type": "object",
        "required": ["fileUrl"],
        "properties": {
          "fileUrl": {
            "type": "string",
            "title": "PDF 文件地址",
            "format": "uri",
            "isPort": true
          },
          "pageRange": {
            "type": "object",
            "title": "页面范围",
            "properties": {
              "start": {"type": "number", "title": "起始页", "minimum": 1},
              "end": {"type": "number", "title": "结束页", "minimum": 1}
            }
          },
          "extractImages": {
            "type": "boolean",
            "title": "提取图片",
            "default": false
          }
        }
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "title": "提取的文本内容"
          },
          "images": {
            "type": "array",
            "title": "提取的图片",
            "items": {
              "type": "object",
              "properties": {
                "url": {"type": "string", "title": "图片地址"},
                "page": {"type": "number", "title": "所在页面"}
              }
            }
          },
          "metadata": {
            "type": "object",
            "title": "文档元数据",
            "properties": {
              "pageCount": {"type": "number", "title": "总页数"},
              "title": {"type": "string", "title": "文档标题"},
              "author": {"type": "string", "title": "作者"}
            }
          }
        }
      }
    }
  ]
}

API 工具示例​

示例 1：自定义邮件发送 API​

基于真实案例的 API 工具配置。

{
  "type": "operator",
  "config": {
    "id": "4e269cee-3a80-4049-a9c3-177b9fd6f9b5",
    "name": "发送邮件plus",
    "type": "operator",
    "method": "default",
    "identifier": "email-operator",
    "inputPorts": [
      {
        "name": "cc",
        "type": "array",
        "label": "抄送",
        "required": false
      },
      {
        "name": "to",
        "type": "string",
        "label": "收件人",
        "required": true
      },
      {
        "name": "bcc",
        "type": "array",
        "label": "密送",
        "required": false
      },
      {
        "name": "html",
        "type": "string",
        "label": "HTML内容",
        "required": false
      },
      {
        "name": "text",
        "type": "string",
        "label": "文本内容",
        "required": false
      },
      {
        "name": "subject",
        "type": "string",
        "label": "邮件主题",
        "required": true
      },
      {
        "name": "attachment_files",
        "type": "array",
        "label": "附件文件",
        "required": false
      }
    ],
    "outputPorts": [
      {
        "name": "data",
        "type": "object",
        "label": "返回数据"
      },
      {
        "name": "success",
        "type": "boolean",
        "label": "发送状态"
      }
    ]
  },
  "position": {
    "x": -90,
    "y": -45
  },
  "defaultInputs": {
    "to": "joshua@magecommerce.com",
    "text": "测试邮件内容",
    "subject": "测试邮件"
  },
  "metadata": {
    "runtime": {
      "type": "rest-api",
      "config": {
        "headers": [],
        "timeout": 30000,
        "serverUrl": "https://api.genitask.cn",
        "retryPolicy": {
          "intervalMs": 1000,
          "maxAttempts": 3
        },
        "method": "POST",
        "caching": {
          "enabled": false,
          "ttlSeconds": 3600
        },
        "endpoint": "https://api.genitask.cn/njs-operators/message/email_operator",
        "url": "https://api.genitask.cn/njs-operators/message/email_operator"
      }
    },
    "origin": "custom"
  }
}

示例 2：用户管理 API​

创建一个用户管理工具，提供用户的增删改查功能。

工具配置​

{
  "name": "用户管理 API",
  "identifier": "user-management-api",
  "description": "提供用户信息的增删改查功能",
  "category": "api",
  "executionType": "api",
  "configuration": {
    "schema": {
      "type": "api",
      "properties": {
        "serverUrl": {
          "type": "string",
          "title": "服务器地址",
          "required": true,
          "description": "用户 API 服务器地址"
        },
        "apiKey": {
          "type": "string",
          "title": "API 密钥",
          "format": "password",
          "required": true,
          "description": "API 访问密钥"
        }
      }
    },
    "values": {
      "serverUrl": "https://api.example.com",
      "apiKey": ""
    }
  }
}

获取用户信息方法​

{
  "name": "获取用户信息",
  "identifier": "get-user",
  "description": "根据用户ID获取用户详细信息",
  "inputSchema": {
    "type": "object",
    "required": ["userId"],
    "properties": {
      "userId": {
        "type": "string",
        "title": "用户ID",
        "description": "要查询的用户ID",
        "isPort": true
      },
      "includeProfile": {
        "type": "boolean",
        "title": "包含详细资料",
        "description": "是否包含用户详细资料",
        "default": false
      }
    }
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "user": {
        "type": "object",
        "title": "用户信息",
        "properties": {
          "id": {"type": "string", "title": "用户ID"},
          "name": {"type": "string", "title": "用户名"},
          "email": {"type": "string", "title": "邮箱"},
          "createdAt": {"type": "string", "title": "创建时间"}
        }
      },
      "success": {
        "type": "boolean",
        "title": "执行状态"
      }
    }
  },
  "configuration": {
    "schema": {
      "type": "object",
      "properties": {
        "method": {
          "type": "string",
          "title": "请求方法",
          "enum": ["GET"],
          "default": "GET"
        },
        "endpoint": {
          "type": "string",
          "title": "接口路径",
          "required": true
        }
      }
    },
    "values": {
      "method": "GET",
      "endpoint": "/api/users/{userId}"
    }
  }
}

MCP 工具示例​

示例 1：智能文本分析​

使用 AI 模型进行文本分析。

{
  "name": "智能文本分析器",
  "identifier": "ai-text-analyzer",
  "description": "使用 AI 模型进行文本分析和处理",
  "executionType": "mcp",
  "systemConfiguration": {
    "schema": {
      "type": "mcp",
      "properties": {
        "serverUrl": {
          "type": "string",
          "title": "MCP 服务器地址",
          "required": true
        },
        "model": {
          "type": "string",
          "title": "AI 模型",
          "enum": ["gpt-4", "gpt-3.5-turbo", "claude-3"],
          "default": "gpt-4"
        },
        "apiKey": {
          "type": "string",
          "title": "API 密钥",
          "format": "password",
          "required": true
        }
      }
    }
  },
  "methods": [
    {
      "name": "情感分析",
      "identifier": "sentiment-analysis",
      "inputSchema": {
        "type": "object",
        "required": ["text"],
        "properties": {
          "text": {
            "type": "string",
            "title": "待分析文本",
            "maxLength": 5000,
            "isPort": true
          },
          "language": {
            "type": "string",
            "title": "文本语言",
            "enum": ["zh", "en", "auto"],
            "default": "auto"
          }
        }
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "sentiment": {
            "type": "string",
            "title": "情感倾向",
            "enum": ["positive", "negative", "neutral"]
          },
          "confidence": {
            "type": "number",
            "title": "置信度",
            "minimum": 0,
            "maximum": 1
          },
          "keywords": {
            "type": "array",
            "title": "关键词",
            "items": {"type": "string"}
          }
        }
      }
    }
  ]
}

Container 工具示例​

示例 1：Python 数据处理​

使用 Python 容器进行复杂数据处理。

{
  "name": "Python 数据处理器",
  "identifier": "python-data-processor",
  "description": "使用 Python 进行复杂数据分析和处理",
  "executionType": "container",
  "systemConfiguration": {
    "schema": {
      "type": "container",
      "properties": {
        "image": {
          "type": "string",
          "title": "Docker 镜像",
          "default": "python:3.9-slim"
        },
        "command": {
          "type": "string",
          "title": "执行命令",
          "default": "python /app/processor.py"
        },
        "environment": {
          "type": "object",
          "title": "环境变量",
          "properties": {
            "PYTHONPATH": {
              "type": "string",
              "default": "/app"
            }
          }
        },
        "resources": {
          "type": "object",
          "title": "资源限制",
          "properties": {
            "memory": {"type": "string", "default": "1Gi"},
            "cpu": {"type": "string", "default": "1"}
          }
        }
      }
    }
  },
  "methods": [
    {
      "name": "数据统计分析",
      "identifier": "statistical-analysis",
      "inputSchema": {
        "type": "object",
        "required": ["dataset"],
        "properties": {
          "dataset": {
            "type": "array",
            "title": "数据集",
            "description": "要分析的数据集",
            "isPort": true
          },
          "analysisType": {
            "type": "string",
            "title": "分析类型",
            "enum": ["descriptive", "correlation", "regression"],
            "default": "descriptive"
          },
          "outputFormat": {
            "type": "string",
            "title": "输出格式",
            "enum": ["json", "csv", "html"],
            "default": "json"
          }
        }
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "statistics": {
            "type": "object",
            "title": "统计结果",
            "properties": {
              "mean": {"type": "number", "title": "平均值"},
              "median": {"type": "number", "title": "中位数"},
              "std": {"type": "number", "title": "标准差"}
            }
          },
          "charts": {
            "type": "array",
            "title": "图表数据",
            "items": {
              "type": "object",
              "properties": {
                "type": {"type": "string", "title": "图表类型"},
                "data": {"type": "object", "title": "图表数据"}
              }
            }
          }
        }
      }
    }
  ]
}

工作流集成示例​

示例：医美营销文案生成流程​

基于真实案例的工作流，展示智能体和 Worker 工具的组合使用。

{
  "workflow": {
    "name": "医美产品小红书文案发布",
    "description": "自动化执行医美产品在小红书平台的文案发布流程，包含内容生成、合规检查、定时发布及数据反馈",
    "edges": [
      {
        "source": "agent-1747982793576:answer",
        "target": "operator-1747982806154:content"
      }
    ],
    "nodes": {
      "agent-1747982793576": {
        "type": "agent",
        "config": {
          "name": "医美营销Pro",
          "description": "专注医美行业的智能营销专家"
        },
        "position": {"x": -135, "y": 105},
        "defaultInputs": {},
        "metadata": {"origin": "built-in"}
      },
      "operator-1747982806154": {
        "type": "operator",
        "config": {
          "name": "邮件发送器",
          "identifier": "email"
        },
        "position": {"x": 330, "y": 105},
        "defaultInputs": {
          "to": "joshua@magecommerce.com",
          "subject": "新文案生成通知"
        },
        "metadata": {
          "origin": "built-in",
          "runtime": {"type": "worker", "config": {}}
        }
      }
    }
  }
}

工作流执行过程：

  1. 智能体生成内容：根据产品信息生成小红书文案
  2. 邮件通知：将生成的文案通过邮件发送给相关人员

连接说明：

  • 智能体的 answer 输出连接到邮件发送器的 content 输入
  • 实现了从内容生成到通知发送的自动化流程

示例：用户注册流程​

展示如何在工作流中组合使用多个工具。

{
  "workflow": {
    "name": "用户注册流程",
    "description": "完整的用户注册和欢迎流程",
    "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"
      }
    ]
  }
}

测试示例​

单元测试​

{
  "testSuite": {
    "name": "智能体工具测试",
    "tests": [
      {
        "name": "医美文案生成测试",
        "operatorId": "medical-beauty-agent",
        "methodId": "generate-content",
        "input": {
          "product": "玻尿酸面膜",
          "features": "深层补水、紧致肌肤",
          "target": "25-35岁职场女性",
          "scenario": "熬夜加班后的肌肤修复"
        },
        "expectedOutput": {
          "answer": "包含产品特性和目标人群的小红书文案"
        }
      },
      {
        "name": "邮件发送测试",
        "operatorId": "email",
        "methodId": "default",
        "input": {
          "to": "test@example.com",
          "subject": "测试邮件",
          "content": "这是一封测试邮件"
        },
        "expectedOutput": {
          "success": true,
          "messageId": "msg-12345"
        }
      }
    ]
  }
}

性能测试​

{
  "performanceTest": {
    "name": "智能体性能测试",
    "operatorId": "medical-beauty-agent",
    "methodId": "generate-content",
    "scenarios": [
      {
        "name": "单次内容生成",
        "concurrency": 1,
        "duration": "30s",
        "input": {
          "product": "玻尿酸面膜",
          "features": "深层补水"
        },
        "expectations": {
          "averageResponseTime": "< 3s",
          "errorRate": "< 1%"
        }
      },
      {
        "name": "并发内容生成",
        "concurrency": 10,
        "duration": "60s",
        "input": {
          "product": "玻尿酸面膜",
          "features": "深层补水"
        },
        "expectations": {
          "averageResponseTime": "< 5s",
          "errorRate": "< 5%",
          "throughput": "> 2 req/s"
        }
      }
    ]
  }
}

最佳实践总结​

1. 设计原则​

  • 单一职责：每个工具专注于一个特定功能
  • 接口稳定：保持向后兼容的接口设计
  • 错误友好：提供清晰的错误信息和处理

2. 配置管理​

  • 分层配置：区分工具级和方法级配置
  • 敏感信息：使用系统配置存储敏感数据
  • 默认值：为所有可选参数提供合理默认值

3. 性能优化​

  • 缓存策略：为适合的操作启用缓存
  • 资源限制：设置合理的资源使用限制
  • 超时处理：配置适当的超时和重试机制

4. 安全考虑​

  • 输入验证：严格验证所有输入参数
  • 权限控制：实现适当的访问控制
  • 审计日志：记录重要操作的审计信息

相关文档​