跳到主要内容

工具概览

工具（Operator）是 GeniSpace 工作流系统的核心执行单元，负责处理具体的业务逻辑和数据操作。每个工具都是一个独立的功能模块，可以接收输入数据，执行特定的操作，并产生输出结果。

什么是工具​

工具是工作流中的基本构建块，类似于编程中的函数或方法。它们具有以下特征：

  • 输入/输出定义：每个工具都有明确的输入和输出数据结构
  • 配置参数：支持灵活的配置选项来适应不同的使用场景
  • 可复用性：同一个工具可以在多个工作流中重复使用
  • 独立执行：每个工具都是独立的执行单元，便于调试和维护

工具执行运行时​

工具按其执行运行时（即工具实际运行的位置和方式）进行划分。在当前版本中，端到端实现并已发布的运行时有两种：

  • Worker：运行在 GeniSpace Worker 服务中的内置工具。当前已发布的 14 个内置工具全部使用该运行时。
  • REST API（rest-api）：调用外部 HTTP/HTTPS 接口的自定义工具。

智能体（Agent）节点是工作流中一种独立的节点类型（由 AI 模型驱动），此处一并介绍以便理解上下文。

规划中 / 当前版本未发布

本文中的 MCP 与 Container 仅作为规划用途的概念性运行时进行说明，当前版本尚未提供，预留给后续路线图 / 企业版。相关配置片段仅用于示意其预期形态。

1. 智能体（Agent）节点​

智能体节点是基于 AI 模型的智能处理单元，能够理解自然语言指令并生成智能化的输出。它是一种独立的工作流节点类型，通常与工具配合连接使用。

特点：

  • 基于大语言模型（LLM）的智能处理
  • 支持自然语言提示词模板
  • 可配置系统提示词和用户提示词
  • 支持记忆、知识库、互联网搜索等增强功能

适用场景：

  • 内容生成和创作
  • 智能分析和决策
  • 自然语言处理
  • 智能客服和对话

配置示例：

{
  "type": "agent",
  "name": "医美营销Pro",
  "description": "专注医美行业的智能营销专家",
  "promptTemplate": "请为【{{product}}】撰写小红书种草文案，核心卖点：{{features}}",
  "systemPrompt": "你是一位精通医美行业的小红书运营专家...",
  "model": {
    "identifier": "deepseek-v3",
    "name": "DeepSeek-V3",
    "apiType": "openai"
  }
}

2. REST API 工具​

REST API 工具（运行时 rest-api）用于调用外部 HTTP/HTTPS 接口，是连接外部服务的桥梁。从 OpenAPI/Swagger 文档导入的自定义工具即使用该运行时。

特点：

  • 支持 RESTful API 调用
  • 灵活的请求配置（方法、头部、参数等）
  • 自动处理认证和错误重试
  • 支持多种数据格式（JSON、XML、表单等）

适用场景：

  • 调用第三方服务 API
  • 数据同步和集成
  • 外部系统交互
  • 微服务间通信

配置示例：

{
  "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 工具​

Worker 工具是系统内置的工具，运行在 GeniSpace 的 Worker 服务中，提供常见的数据处理和业务逻辑功能。当前已发布的 14 个内置工具全部使用该运行时。

特点：

  • 高性能本地执行
  • 丰富的内置功能库
  • 支持复杂的数据处理逻辑
  • 无需外部依赖

适用场景：

  • 文档处理和转换
  • 数据清洗和格式化
  • 文本分析和处理
  • 图像和媒体处理
  • 数学计算和统计

内置工具类别（按目录中实际发布情况）：

  • utilities（实用工具）：邮件发送器、通用 API 调用、REST 客户端、微信公众号图文发布、数据转换、默认数据源
  • database（数据库）：SQL 模板操作符、MySQL 表结构读取、PostgreSQL 表结构读取
  • code（代码）：JavaScript 执行器
  • embedding（向量化）：多模态向量化
  • text（文本）：文档阅读器
  • storage（存储）：存储操作器
  • variable（变量）：全局变量操作器

完整的 14 个内置工具清单见 系统工具。

配置示例：

{
  "runtime": {
    "type": "worker",
    "config": {}
  },
  "identifier": "email",
  "name": "邮件发送器"
}

4. MCP 工具（规划中 — 未发布）​

当前版本未提供

MCP 运行时属于概念性 / 规划中内容，以下说明与片段仅示意预期设计。

MCP（Model Context Protocol）工具旨在与支持 MCP 协议的 AI 模型和服务进行交互。

特点：

  • 标准化的 AI 模型接口
  • 支持多种 AI 服务提供商
  • 统一的上下文管理
  • 智能对话和推理能力

适用场景：

  • AI 对话和问答
  • 文本生成和摘要
  • 智能分析和决策
  • 自然语言处理

配置示例：

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

5. Container 工具（规划中 / 企业版 — 未发布）​

当前版本未提供

Container 运行时预留给后续路线图 / 企业版，以下说明与片段仅示意预期设计。

Container 工具基于 Docker 容器技术，可以运行任意的容器化应用和服务。

特点：

  • 完全隔离的执行环境
  • 支持任意编程语言和框架
  • 可扩展的资源配置
  • 版本化的部署管理

适用场景：

  • 复杂的业务逻辑处理
  • 特定语言或框架的应用
  • 需要特殊运行环境的任务
  • 第三方工具和服务集成

配置示例：

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

工具在工作流中的角色​

数据流处理​

工具通过输入和输出端口连接，形成数据处理管道：

输入数据 → 智能体A → 中间结果 → 工具B → 最终输出

实际工作流示例​

基于真实案例的工作流结构：

智能体（内容生成） → Worker工具（邮件发送）

连接方式：

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

并行执行​

多个工具可以并行处理不同的数据分支：

输入 → 分发工具 → 工具A → 合并工具 → 输出
              → 工具B →
              → 工具C →

工具配置结构​

实际的工具配置结构​

基于真实案例，工具的配置结构包含：

{
  "type": "operator",  // 或 "agent"
  "config": {
    "id": "工具唯一ID",
    "name": "工具显示名称",
    "type": "operator",
    "method": "default",  // 执行的方法
    "identifier": "工具标识符",
    "inputPorts": [
      {
        "name": "参数名",
        "type": "数据类型",
        "label": "显示标签",
        "required": true/false
      }
    ],
    "outputPorts": [
      {
        "name": "输出名",
        "type": "数据类型", 
        "label": "显示标签"
      }
    ]
  },
  "position": {"x": 100, "y": 200},
  "defaultInputs": {
    "参数名": "默认值"
  },
  "metadata": {
    "origin": "built-in" | "custom",
    "runtime": {
      // 已发布运行时："worker"（全部内置工具）与 "rest-api"（自定义 HTTP）。
      // "container" / "mcp" 为规划中内容，当前版本未发布。
      "type": "worker" | "rest-api",
      "config": {}
    }
  }
}

自定义工具 vs 系统内置工具​

系统内置工具​

优势：

  • 开箱即用，无需配置
  • 经过充分测试，稳定可靠
  • 性能优化，执行效率高
  • 官方维护和更新

限制：

  • 功能相对固定
  • 无法满足特殊业务需求
  • 更新依赖系统版本

自定义工具​

优势：

  • 完全自主控制
  • 可以实现任意业务逻辑
  • 快速响应业务变化
  • 支持私有化部署

创建方式：

  • 手动创建：从零开始配置工具的输入输出和业务逻辑
  • OpenAPI 导入：从 OpenAPI/Swagger 文档快速导入多个 API 方法作为工具（导入为 rest-api 工具）
  • Docker 容器：预留给后续路线图 / 企业版，当前版本未提供
注意事项
  • 需要自行开发和维护
  • 需要考虑安全性和稳定性
  • 需要编写详细的文档

工具开发最佳实践​

1. 设计原则​

  • 单一职责：每个工具只负责一个明确的功能
  • 幂等性：相同输入应该产生相同输出
  • 错误处理：优雅处理异常情况
  • 性能考虑：避免长时间阻塞操作

2. 输入输出设计​

  • 使用清晰的数据结构定义
  • 提供详细的字段说明
  • 考虑向后兼容性
  • 支持可选参数

3. 配置管理​

  • 区分用户配置和系统配置
  • 提供合理的默认值
  • 支持环境变量覆盖
  • 敏感信息加密存储

4. 测试和文档​

  • 编写完整的单元测试
  • 提供使用示例
  • 记录已知限制和注意事项
  • 维护版本更新日志

下一步​