Authoring Workflows

A tool workflow turns a sequence of HTTP calls into a single named tool that an agent can invoke. The gateway holds the OpenAPI spec, the credentials, and the orchestration logic; the agent supplies inputs and receives a single result.

A workflow is an ordered list of steps. Each step calls one operation from a registered API spec, optionally extracts values from the response, and feeds those values to subsequent steps via Handlebars templates.

Anatomy of a workflow

The POST /v1/workflows request body has this shape:

Each step:

There is no query_template, no header_template, and no per-step credential override. The credential resolution path comes from the API spec; query parameters and headers are not currently templated.

Current step limitations

The implementation has a few honest gaps that workflow authors should know up front:

• Path parameters are not interpolated. The gateway concatenates base_url + the operation's path literally. If the OpenAPI path is /runs/{run_id}, the gateway hits /runs/{run_id} verbatim. Use operations whose paths are static, or model the dynamic parts in the body where the upstream API supports it.
• Query strings are not templated. Parameters declared in query on the OpenAPI operation are not threaded through from input or step state.
• Headers are not templated beyond the credential headers the gateway injects on every request.
• body_template is sent on every request method, including GET. The template is required and must always render valid JSON. For methods where the body is unused, render "{}" and rely on the upstream API to ignore it.

These are real constraints of the current engine, not policy. Pick API operations whose path and query surface match what you can actually parameterize today.

The Handlebars context

The gateway uses handlebars with the default helper set only — no custom helpers are registered. That means the helpers available in templates are exactly:

The render context exposes two top-level keys:

For convenience the input is also exposed at the top of the state map under the key input, so {{input.foo}} and {{state.input.foo}} resolve to the same value.

If a step extractor names a value run_id and the step is named create_run, then later steps reference it as {{state.create_run.run_id}}.

JSONPath extractors

Extractors run after each step and pull values out of the response body. The gateway uses the jsonpath_lib implementation.

When an extractor produces multiple matches, only the first match is stored in state. The engine takes the first element of the result list and writes it under <step_name>.<key>. If you need the full list, model your workflow to extract a single nested array (e.g. $.items) and let the agent destructure on the receiving end.

Example

"extractors": {
  "run_id": "$.data.id",
  "plan_id": "$.data.relationships.plan.data.id"
}

After this step (named create_run), the workflow state holds create_run.run_id and create_run.plan_id, available in subsequent templates as {{state.create_run.run_id}}.

Error policies

on_error is required on every step. The supported variants come from the engine:

Choose AbortWorkflow when the next step depends on this step's extractors. Choose Continue for best-effort enrichment steps. Choose RetryN for idempotent calls against flaky upstreams.

{ "on_error": "AbortWorkflow" }
{ "on_error": "Continue" }
{ "on_error": { "RetryN": 3 } }

A worked example: Terraform Cloud plan

The following workflow drives a Terraform Cloud run end-to-end: create the run, fetch its current state, then pull the plan output. It assumes the API spec from the Petstore + Terraform Cloud examples is already registered with the ID captured in $TFC_SPEC_ID.

curl -X POST https://gateway.example.com/v1/workflows \
  -H "Authorization: Bearer $OPERATOR_JWT" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"terraform_plan_and_fetch\",
    \"description\": \"Create a Terraform Cloud run, wait for the plan, return its JSON output\",
    \"api_spec_id\": \"$TFC_SPEC_ID\",
    \"input_schema\": {
      \"type\": \"object\",
      \"required\": [\"workspace_id\"],
      \"properties\": {
        \"workspace_id\": { \"type\": \"string\" },
        \"message\": { \"type\": \"string\" }
      }
    },
    \"steps\": [
      {
        \"name\": \"create_run\",
        \"operation_id\": \"create_run\",
        \"body_template\": \"{\\\"data\\\":{\\\"attributes\\\":{\\\"message\\\":\\\"{{input.message}}\\\"},\\\"relationships\\\":{\\\"workspace\\\":{\\\"data\\\":{\\\"id\\\":\\\"{{input.workspace_id}}\\\",\\\"type\\\":\\\"workspaces\\\"}}}}}\",
        \"extractors\": {
          \"run_id\": \"$.data.id\",
          \"plan_id\": \"$.data.relationships.plan.data.id\"
        },
        \"on_error\": \"AbortWorkflow\"
      },
      {
        \"name\": \"get_run\",
        \"operation_id\": \"get_run\",
        \"body_template\": \"{}\",
        \"extractors\": {
          \"plan_status\": \"$.data.attributes.status\"
        },
        \"on_error\": { \"RetryN\": 2 }
      },
      {
        \"name\": \"get_plan_output\",
        \"operation_id\": \"get_plan_output\",
        \"body_template\": \"{}\",
        \"extractors\": {},
        \"on_error\": \"AbortWorkflow\"
      }
    ]
  }"

A successful response returns the workflow ID:

{ "id": "1f7e3b2c-5d4a-4f6c-9b1a-3e8f2c4d5b67" }

What this example does — and does not — do

The workflow demonstrates extractors and Handlebars input substitution into a request body. It does not model the part of Terraform Cloud's API that requires waiting for the plan to leave pending state.

The gateway has no built-in poll loop at the workflow level. There is no wait_until step, no poll policy, no per-step delay. The supported error policies (AbortWorkflow, Continue, RetryN) all retry against the same URL immediately with no backoff — they exist to handle transient upstream failures, not to model long-running asynchronous APIs.

The honest pattern for asynchronous upstreams: the agent invokes the workflow once, inspects the returned plan_status, and re-invokes the workflow (or just the relevant operation via the API Explorer) until the status is what it wants. The polling logic lives in the agent loop, not in the workflow.

Invoking a workflow

Workflows are invoked over the SEAL invoke endpoint by name. The agent supplies an input object that conforms to input_schema; the gateway validates the schema, runs the steps, and returns:

{
  "workflow_id": "1f7e3b2c-5d4a-4f6c-9b1a-3e8f2c4d5b67",
  "execution_id": "exec-abc123",
  "result": { "...": "the response body of the final step" },
  "state": { "create_run.run_id": "run-x9", "create_run.plan_id": "plan-7", "...": "..." }
}

The result field is the parsed JSON body of the last successfully executed step. The state map is the full extractor state, useful for debugging.

Lifecycle

There is no PUT /v1/workflows/{id} in the current implementation. To change a workflow you must delete and re-register it. Workflow IDs are not stable across edits.

In-flight invocations against a deleted workflow are unaffected — the gateway loaded the workflow record into the engine before starting the steps. New invocations against a deleted workflow return 404 NotFound.

Tenant scope

Like API specs, every workflow is registered against the caller's tenant. Tenant-scoped workflows are visible only to that tenant; system-global workflows (registered with no tenant claim) are visible to all. The list endpoint already filters appropriately.

A workflow registered under tenant A cannot reference an API spec registered under tenant B — registration validates that every step's operation_id exists in the referenced spec, and the spec lookup is itself tenant-scoped.

Audit events

Workflow lifecycle and execution emit a stream of events into the gateway's event store:

Workflow deletion is not currently audited as a domain event.

Common errors at registration

Next steps

• API Explorer — for ad-hoc one-shot calls that don't justify a workflow.
• Ephemeral CLI Tools — for tool surfaces that don't fit the HTTP-call shape.
• Credential Resolution — every workflow inherits its API spec's credential path; understand which strategy matches your upstream.