Skip to main content

Operator examples

These examples focus on contracts and selection patterns that can be used in current workflows and agent tool catalogs. Replace sample URLs and field names with your authorized resources.

Example 1: read a customer from a REST API​

Create a REST API operator with one read-only method:

{
  "name": "getCustomer",
  "description": "Read one customer by the exact platform customer ID",
  "inputSchema": {
    "type": "object",
    "required": ["customerId"],
    "properties": {
      "customerId": { "type": "string", "minLength": 1 }
    },
    "additionalProperties": false
  },
  "outputSchema": {
    "type": "object",
    "required": ["found"],
    "properties": {
      "found": { "type": "boolean" },
      "customer": {
        "type": ["object", "null"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "status": { "type": "string" }
        }
      }
    }
  }
}

Map customerId to the URL path and map a remote 404 to { "found": false, "customer": null }. Keep authentication in a managed connection. Because the method is read-only, a short retry for transient network failure is normally safe.

Example 2: create an external ticket safely​

A write method should expose an idempotency value:

{
  "name": "createSupportTicket",
  "description": "Create one support ticket after user approval",
  "inputSchema": {
    "type": "object",
    "required": ["title", "description", "idempotencyKey"],
    "properties": {
      "title": { "type": "string", "minLength": 1 },
      "description": { "type": "string", "minLength": 1 },
      "priority": { "type": "string", "enum": ["LOW", "MEDIUM", "HIGH"] },
      "idempotencyKey": { "type": "string", "minLength": 8 }
    },
    "additionalProperties": false
  },
  "outputSchema": {
    "type": "object",
    "required": ["ticketId", "status"],
    "properties": {
      "ticketId": { "type": "string" },
      "status": { "type": "string" },
      "created": { "type": "boolean" }
    }
  }
}

Require confirmation when exposed to an agent. Pass idempotencyKey to the remote service and return the stable ticket ID whether the request created or reused the ticket.

Example 3: choose the correct Dataset operation​

Suppose a candidate Dataset contains id, name, education_level, work_experience, and a configured vector field.

QuestionOperationReason
“Open candidate ID 42”Structured query with typed idsExact identity is known
“How many records are in the Dataset?”CountExact total, no record pagination
“Find the name Chen Siyuan”Full-text search or exact field queryLiteral name
“Who has transferable offshore construction experience?”Vector searchConceptual and potentially cross-language

For vector search, request identity and evidence fields:

{
  "text": "offshore construction, safety systems, heavy engineering and transferable project experience",
  "limit": 20,
  "outputFields": [
    "id",
    "name",
    "current_location",
    "work_experience",
    "project_experience"
  ]
}

Evaluate returned experience before recommending a person. Top-K is not a business qualification. If an output field does not exist in the Dataset Schema, remove or replace it before executing.

Example 4: connect an operator in WorkflowStudio​

For a customer escalation workflow:

  1. Manual or event trigger receives customerId and issue.
  2. getCustomer returns the customer and found flag.
  3. An If/Else node stops with a clear result when found is false.
  4. A task agent classifies severity into a strict output Schema.
  5. createSupportTicket runs only for the approved branch.
  6. A final Transform node returns ticketId, status, and classification.

Test the found, not-found, low-priority, high-priority, duplicate event, remote failure, and timeout paths.

Example 5: render an agent tool result​

The Chat execution process should preserve the structured result:

if (event.type === 'tool.execution') {
  const metadata = event.metadata ?? {};
  renderToolActivity({
    name: String(metadata.toolName ?? 'Tool'),
    arguments: metadata.arguments,
    result: metadata.result,
    error: metadata.error,
    pluginId: metadata.pluginId,
  });
}

Do not replace the tool result with only “Tool completed.” A registered plugin can render a dedicated card, while the raw structured value remains available for inspection.