Custom operators

Create a custom operator when no active built-in operator or Datasource operation provides the required external action. The current user-facing custom runtime is REST API; OpenAPI import creates REST API operator methods from an existing contract.

Before creating one

Check the active operator catalog first. Reuse a built-in operator when it already provides the behavior, because the platform maintains its implementation, fixes, and runtime integration.

Create a custom REST API operator when:

• a business system exposes an HTTPS API;
• the action has a stable input and output contract;
• credentials can be stored in a managed connection or Secret;
• timeout, retry, and idempotency behavior are understood.

Do not use an operator as a place to store arbitrary scripts or credentials.

Create manually

1. Open Console → Operators and choose Create.
2. Enter a unique identifier, name, description, category, and tags.
3. Select the REST API execution type.
4. Configure the server URL and authentication connection.
5. Add one method per external operation.
6. Define the input and output Schema for each method.
7. Map HTTP path, query, headers, and body from typed inputs.
8. Configure timeout and safe retry behavior.
9. Test the method before activation.

Keep test and production endpoints in environment configuration so the operator contract remains the same between environments.

Import OpenAPI

OpenAPI import is useful when the remote service already has a maintained OpenAPI document.

1. Choose import by URL or supported file upload.
2. Select the operations to import.
3. Review the generated operator identifier and method names.
4. Verify Server URL, content type, parameters, request body, response Schema, and authentication.
5. Remove methods and fields that users should not call.
6. Test representative responses before activation.

Import is a starting point, not proof that the external API is safe or compatible. Generated descriptions often need business context so workflow authors and agents choose the correct method.

See OpenAPI support.

Authentication and secrets

• Prefer a managed connection, ConfigMap Secret, or environment reference.
• Do not hard-code tokens in headers, defaults, examples, or exported definitions.
• Grant the remote credential only the required scope.
• Mask sensitive inputs and outputs from logs.
• Rotate the credential without changing the operator Schema.

Test matrix

Before activation, test at least:

Case	Expected behavior
Valid request	Structured success output
Valid request with no data	Explicit empty result, not an error
Missing or invalid input	Validation error before remote execution
Invalid credential	Clear authorization failure without secret leakage
Remote 4xx	Final business or request error
Remote 5xx / network interruption	Retry only if configured and safe
Timeout	Bounded failure with diagnostic metadata
Duplicate write request	Idempotent result or explicit duplicate protection

Then add the operator to a test workflow and verify mapping, logs, retries, and downstream output.

Activate and expose

Activating an operator makes it eligible for authorized product catalogs. It does not automatically give every agent access. To expose it as an agent tool, ensure its tool definition, agent configuration, Chat mode, local provider, and Space permissions allow it.

For consequential write actions, require confirmation and return the affected resource ID and state. For read actions, return structured records and an explicit total or empty result where applicable.

Change management

Treat the operator Schema as an API contract. Adding an optional field is usually safer than renaming or changing the type of an existing field. If a breaking change is required:

1. create a new method or operator identifier;
2. update and test every workflow and agent consumer;
3. activate the new contract;
4. retire the old contract only after usage reaches zero.

Related guides

• Operator configuration
• OpenAPI support
• Operator examples
• Operator best practices