Operators
An operator is a reusable, schema-defined action. It receives typed input, performs one operation, and returns a structured result. Operators are available as workflow nodes and, when explicitly exposed and authorized, as tools for agents.
Operators, tools, and agent nodes
| Concept | Primary purpose | Who controls execution |
|---|---|---|
| Operator | Deterministic, reusable business or data operation | Workflow runtime or an authorized agent tool |
| Agent tool | Capability presented to a model with a name, description, and input schema | Agent runtime and its authorization policy |
| Agent node | Uses a task agent for language understanding or structured generation | Workflow runtime |
| MCP tool | External capability supplied through an MCP server | Agent runtime, MCP connection, and Space authorization |
An operator can become an agent tool, but the terms are not interchangeable. The agent only receives tools enabled for its type, current mode, Space, and application.
Available execution types
Built-in operators
Built-in operators execute in GeniSpace Worker and cover common platform functions, including:
- Dataset query, count, vector search, and full-text search;
- data transformation and utility operations;
- document and media processing;
- database schema and SQL-related utilities;
- HTTP, messaging, and supported platform integrations.
The catalog is the source of truth for the operators enabled in your environment.
REST API operators
A custom REST API operator calls an external HTTPS endpoint. You define the method, URL, headers, input schema, output schema, timeout, and retry behavior. Secrets should be stored in an authorized connection or environment configuration, not pasted into a workflow or prompt.
OpenAPI import can create operator definitions from an existing service contract. Always review the generated schemas, authentication, and server URL before activation.
Datasource operations
Datasource operations use a configured connection to query or update an external business system. Connection permissions and the active Space determine what is available.
Operator lifecycle
- Find or create — choose a built-in operator, create a REST API operator, or import OpenAPI.
- Define the contract — use clear field names, descriptions, required properties, types, and output structure.
- Configure authorization — connect credentials and grant only the required Space permissions.
- Test — run representative success, empty-result, validation-error, remote-error, and timeout cases.
- Activate — only active operators appear in the relevant workflow or agent catalogs.
- Use and monitor — inspect structured output, execution duration, retries, and error details.
- Update carefully — changing a field type or required input can affect every workflow and agent using the operator.
Use an operator in a workflow
- Open a task in WorkflowStudio.
- Add a node from Tools, Dataset, or Data Sources.
- Map upstream outputs to the operator's typed inputs.
- Configure defaults, environment variables, timeout, and error handling.
- Connect the structured output to downstream nodes.
- Save and use Run Now with representative input before enabling the trigger.
The execution panel shows node input, result, duration, retry, and error information. Keep sensitive values out of test payloads and logs.
Expose an operator to an agent
An agent needs more than access to an operator record. The runtime builds a tool catalog using the agent form, Chat mode, application-local providers, Space authorization, and configuration. To make selection reliable:
- use a unique action-oriented name;
- describe when the tool should and should not be used;
- keep required input minimal and typed;
- return structured facts rather than a display-only sentence;
- distinguish exact query/count, full-text search, and vector search;
- provide meaningful empty and error results;
- require confirmation for destructive or consequential actions.
Chat renders supported results in the execution process. Some application-local tools also render a dedicated plugin card, such as Workbench draft changes or Assistant resource creation.
Dataset operator selection
| User need | Preferred operation |
|---|---|
| Exact field condition, sorting, pagination, or IDs | Structured query |
| Total number of matching records | Count |
| Literal names, identifiers, or phrases | Full-text search |
| Concept, capability, similarity, or cross-language matching | Vector search |
Vector Top-K results are candidates for evaluation, not proof that every returned record meets the condition. Output fields and filters must use names and types defined by the Dataset schema.
Design checklist
- Does the name describe one operation?
- Are input and output types explicit?
- Can an empty result be distinguished from an execution failure?
- Are retries safe, especially for write operations?
- Are credentials kept outside the operator payload?
- Does the operation enforce Space authorization?
- Can users inspect the result without exposing sensitive fields?
- Have existing workflows and agents been checked before a contract change?