Skip to main content

Operator best practices

Reliable operators have a narrow purpose, explicit contract, safe retries, least-privilege authorization, and observable results.

One method, one action​

Prefer getCustomer, listInvoices, and createTicket over a generic runOperation. A focused method is easier to map in workflows and easier for an agent to select correctly.

Use unique names across the runtime tool catalog. Duplicate runtime tool names can make model selection and result rendering ambiguous even if internal registration keys differ.

Design typed contracts​

  • Use stable business identifiers.
  • Make required fields genuinely required.
  • Define array items and nested objects.
  • Use enums for closed value sets.
  • Describe units, timezone, formats, and value meaning.
  • Reject unknown fields when the operation should be strict.
  • Return stable IDs and typed facts.

Avoid returning display text as the only result. The UI can format structured data, but downstream nodes cannot reliably parse a sentence.

Model empty results explicitly​

An empty read is not an execution error. Return an explicit state such as:

{
  "success": true,
  "results": [],
  "total": 0
}

A failed request should return or raise a distinct error with a safe code and message. This distinction prevents agents from claiming that data exists when the tool returned none.

Make write operations idempotent​

Retries can duplicate email, payment, ticket, or record-creation actions. For consequential writes:

  • accept or derive an idempotency key;
  • record the resulting resource ID;
  • treat a replay as reuse, not a second write;
  • require confirmation when invoked interactively;
  • do not retry validation or authorization failures.

Choose timeout and retries intentionally​

  • Operator timeout must fit inside the task or turn budget.
  • Retry only transient failures.
  • Use bounded backoff rather than immediate loops.
  • Rate-limit repeated warnings.
  • Preserve execution and request IDs in errors.
  • Cancel remote work when the runtime and provider support it.

Protect secrets and data​

  • Keep credentials in managed connections or Secrets.
  • Apply least-privilege Space and remote-system permissions.
  • Mask sensitive inputs and outputs in logs.
  • Do not log complete resumes, documents, API headers, or generated curl commands containing data.
  • Return only fields the caller needs and may access.
  • Treat tool results as untrusted content when rendering.

Support agent tool selection​

An agent-facing description should answer:

  1. What exact action does the tool perform?
  2. When should it be selected?
  3. When should a different tool be selected?
  4. What identifiers or evidence must be supplied?
  5. What does an empty result mean?

For Dataset tools, preserve these boundaries:

  • structured query for exact typed conditions and IDs;
  • count for exact totals;
  • full-text search for literal text;
  • vector search for concepts, similarity, and cross-language matching.

Do not encode one industry's vocabulary as a global runtime rule. Industry-specific selection guidance belongs in the relevant agent or solution template.

Keep results observable​

Expose status, duration, safe arguments, structured result, and error details to the execution timeline. Application plugins may provide richer cards, but should not discard the underlying operator result.

For asynchronous operations, expose progress and the final resource or execution ID. Do not return “processing” as a final success if no background job was actually created.

Test at contract boundaries​

Test more than the happy path:

  • required and optional inputs;
  • wrong types and extra fields;
  • empty and multiple results;
  • unicode and locale-specific text;
  • large nested values;
  • unauthorized resource;
  • connection failure, rate limit, timeout, and cancellation;
  • safe retry and duplicate write;
  • workflow mapping and agent tool rendering.

After changing a contract, run the workflows and agents that consume it. Unit tests for a helper do not replace an end-to-end contract test.

Version changes​

Prefer additive optional fields. For a breaking change, create a new identifier or method, move verified consumers, then retire the previous contract. Do not silently reinterpret an existing field.

Review checklist​

  • Unique, action-oriented name
  • Clear applicability description
  • Typed input and output Schema
  • Explicit empty result
  • Least-privilege connection and Space access
  • Safe timeout, retry, and idempotency behavior
  • Sensitive values excluded from logs
  • Structured result visible to workflow and Chat
  • Success, error, empty, duplicate, and cancellation tests
  • Consumer regression completed before activation