Zum Hauptinhalt springen

Scripts and Agents

Scripts and Agents are actions inside a workflow version. Each action owns its name, configuration and input bindings. Save and publish the workflow to save and publish all its steps together. Authoring never executes JavaScript, invokes tools or calls a model.

Workflow ownership and publication​

Create a workflow, create its working version, then replace definition.actions when editing its steps. A Script action has type: "script" and config.source; an Agent has type: "agent" and config.instructions. Both may have an optional name and explicit input_bindings. The action UUID identifies the step within the workflow graph.

Publishing the workflow freezes all inline configuration and execution contracts atomically. It requires workflows:manage, workflows:code:execute for code steps, and the grants required by selected tools. Copying a workflow version copies its steps. Editing that copy cannot change the published version or an existing run. There are no separate Script/Agent resources to select, publish, archive or delete.

A working version can contain incomplete steps; its validation_issues identify fields that must be completed before publication. Published workflow versions remain immutable. Use the workflow version's lock_version for optimistic concurrency; a stale value returns 409.

Content and replacement semantics​

This example replaces the workflow's complete action list with one Script action. Retain the other actions when editing an existing graph; edges must still reference nodes present in that graph.

{
"lock_version": 0,
"definition": {
"actions": [
{
"id": "00000000-0000-4000-8000-000000000002",
"type": "script",
"name": "Prepare task",
"config": {
"source": "export function main(input) { return {summary: input.case_id}; }",
"input_schema": {
"type": "object",
"properties": { "case_id": { "type": "string", "maxLength": 64 } },
"required": ["case_id"],
"additionalProperties": false
},
"allowed_tools": [],
"record_access": [],
"tour_template_ids": []
},
"input_bindings": [
{ "type": "literal", "input_name": "case_id", "value": "CASE-42" }
]
}
]
}
}

Script output_schema is read-only: static analysis infers it from main(input, tools), the input contract and the exact selected SDK tool types. JavaScript and precise JSDoc return types are supported. Saving incomplete or invalid source succeeds with no derived output and a #/definition/actions/0/config/source publication issue containing the compiler diagnostic and source line/column. Public GET returns these saved issues without running analysis. Clearing input also clears the derived output. Publishing independently reanalyzes source, then freezes the exact contract; an unprovable return cannot publish. Analysis runs without executing the Script or its tools. Selected tool grants are required during analysis. Concurrent edits or tool-contract changes during analysis return 409; infrastructure unavailability returns 503 without committing any version change. Existing publications and runs remain immutable.

The inferred root is a closed JSON object. Fields can contain strings, numbers, booleans, nested objects, homogeneous arrays, optional properties and nullable values. Inferred strings have a 16,384-character limit and arrays have a 100-item limit, enforced again at runtime. Unconstrained JSON.parse results, recursive types and incompatible conditional shapes require a precise JSDoc return annotation. An annotation does not validate external data; the runtime still checks it.

Generated declarations expose Input, Tools and the string alias DateTime through the virtual ./workflow-contracts module. There is no generated Output type. Returning a declared timestamp preserves its date-time annotation for downstream Wait steps. Explicit source annotations can use import("./workflow-contracts").DateTime; ordinary strings do not gain that annotation merely because they resemble timestamps. A reached Wait validates the actual timestamp independently.

The editor can request advisory analysis with POST /frontend/v2/workflows/scripts/editor/analyze, using source, optional input_schema and allowed_tools. It returns an optional inferred output_schema and bounded diagnostics with source positions. API and MCP clients can author and publish entirely through the public version endpoints; they do not need this editor endpoint.

Agents use instructions, model_id, budget, max_output_tokens and the typed output configuration, alongside input contracts and capability fields. Their compiled output_schema is read-only. Script-specific fields never appear on Agents; Agent-specific fields never appear on Scripts. Total content is limited to 64 KiB UTF-8.

  • The outer workflow-version request is a merge patch. Its actions array replaces the entire list.
  • Each action's config, schemas, budgets, scopes and output mode are complete replacements within that list. Omitted optional fields are cleared; omitted defaulted fields use their defaults. Remove schema properties by omitting them in the replacement, not by supplying null tombstones.
  • Empty allowed_tools, record_access and tour_template_ids lists remove those capabilities. Null lists, duplicate selections and unsupported entries return 422.
  • Unknown or inapplicable fields reject the entire save. Error pointers include the action index, for example #/definition/actions/0/config/input_schema.

Contracts use a bounded JSON Schema Draft 2020-12 subset. Root type is object; objects declare properties and additionalProperties:false, and arrays declare items. Supported types are object, array, string, integer, number and boolean; nested types may pair with null. Agent contracts and inferred Script output use property names matching [a-z][a-z0-9_]{0,63}, excluding constructor and prototype.

Supported keywords are type, title, description, properties, required, additionalProperties, items, minItems/maxItems (0–100), minLength/maxLength (0–16384), minimum, maximum, scalar enum (1–50 values), and string format:"date-time". Only the root may declare $schema, with value https://json-schema.org/draft/2020-12/schema. References, remote resolution, regex, other unions and unknown keywords are rejected.

Script input contracts also preserve safe original data keys, including camelCase and Unicode, and accept string formats date and uuid. Names contain 1–64 UTF-16 code units, cannot be blank or contain control characters, and exclude __proto__, constructor and prototype. These are data keys inside the declared payload; fixed API property names remain snake_case. Generated JavaScript declarations quote keys when necessary. A nested key containing a dot can be retained inside an object input, but is not offered as an ambiguous dotted field path.

Each schema and patch is bounded to 16 KiB UTF-8, 1,024 JSON nodes and 24 JSON levels. Complete schemas allow eight nested schema levels and 32 properties per object. Missing contracts mean unconfigured content. Runtime validates actual inputs and outputs against the frozen contracts. Date-time outputs can be used by Wait steps, which also validate the actual timestamp.

Agent output formats​

Each Agent step has one output configuration. A new Agent step defaults to Text; copying a workflow version preserves its selected format and configuration. Every mode uses the same bounded Agent runner, provider accounting and runtime validation.

ModeConfigurationValues available to later steps
Text{"mode":"text"}output.text, a string of at most 16,384 characters
Classification{"mode":"classification","options":[…]}output.option_id, exactly one configured option UUID
Structured{"mode":"structured","schema":{…}}The fields of the declared bounded JSON object

Classification options contain a client-generated UUID id, a nonblank label of 1–128 characters, and an optional nonblank description of at most 1,024 characters. IDs must be distinct and remain stable when labels are edited. At most 50 options are allowed; publication needs at least two. Saving zero or one option retains an incomplete draft with validation issues and no compiled output schema. Structured output can likewise be left unconfigured in a draft; publication needs a valid schema. Metadata remains subject to the overall content and generated-schema bounds.

Publication also limits the complete Agent output schema to 24 optional properties and 16 nullable types, including nested objects and array items. A property is optional when absent from its containing object's required array; a nullable type is paired with null. Drafts exceeding these execution limits remain readable and editable, with validation_issues on #/definition/actions/0/config/output/schema, but cannot publish until corrected. The runtime still validates every value against the original published schema, including string lengths and numeric bounds.

For example, use this output configuration when replacing an Agent action:

{
"output": {
"mode": "classification",
"options": [
{
"id": "00000000-0000-4000-8000-000000000081",
"label": "Urgent",
"description": "Needs prompt attention"
},
{ "id": "00000000-0000-4000-8000-000000000082", "label": "Routine" }
]
}
}

output is a closed union distinguished by mode. Supply only the fields belonging to that mode. Text uses {"mode":"text"}, Classification uses mode and options, and Structured uses mode and optional schema. Switching modes replaces the previous configuration as part of the action replacement. No field-clearing tombstones are needed.

Text and Classification expose their compiled contract for reference rather than a separate schema editor. Structured uses the existing bounded field/schema editor. Publication freezes the mode, options, labels/descriptions and compiled schema. Old workflow runs continue to use the exact selected publication after new options or formats are published. An answer outside the classification set fails output validation; confirmed model usage and cost remain recorded even when no output is accepted. Formats do not grant capabilities: Agents start without tools, and changing format leaves explicitly selected tools unchanged.

Values in Agent instructions​

instructions remains a plain string. Insert captured trigger values as {{record.attributes.name}}, {{record.display_name}}, {{schedule.timezone}} or {{input.customer}}. Reference an earlier output with {{steps.4f0c2a1e-0000-4000-8000-000000000001.output.title}}. Whitespace inside the braces is allowed. Braces that do not form a reference remain literal text.

Publication validates each reference against the trigger fields, declared output contracts and preceding steps. An invalid reference points to #/definition/actions/<index>/config/instructions. The system prompt retains the configured string. Captured values and accepted outputs are supplied in a separate JSON object in the initial user message, explicitly marked as untrusted task data. They cannot change instructions, grant tools or authorize actions. Missing optional values, explicit nulls and skipped sources become empty text; structured values retain their JSON types. References inside supplied values are never expanded. A missing receipt for a source that must have run fails execution with output_unavailable instead of silently hiding broken state.

Resolution caches each source within one initial-message assembly, enforces the UTF-8 request byte budget, and retains the values in the conversation journal for subsequent turns. Preview reads the configured instructions from the workflow definition and shows a bounded excerpt; it neither calls the model nor claims that execution-dependent values have been resolved.

Execution contracts and capabilities​

Publication requires source/instructions and complete contracts: Script output is inferred from source, while Agent output is declared explicitly. Agents also require a supported exact model_id from agents.models in GET /api/v2/workflows/capabilities and an output limit of 1–8192 tokens, default 2048, within the aggregate budget. The catalog and matching workflows_capabilities_get MCP tool require workflows:manage, return the complete host catalog without pagination, and make no provider call. An existing publication keeps its exact configuration even when the current catalog changes.

Every catalog model includes is_default. Exactly one model is marked when the environment's configured default is available; otherwise all are false. Clients preselect the marked model for new Agent steps and leave the selection empty when none is marked. The frontend authoring context includes the same flag, so choosing a new step's default does not require an additional request.

Agent budgets bound tokens, model calls, tool calls, duration and estimated provider cost across attempts. max_cost_microusd is a positive integer in millionths of USD: 100000 means USD 0.10; the maximum is 100000000. This provider-cost ceiling is distinct from tenant billing. Provider usage and dispatch-time pricing remain shared accounting evidence; publication does not freeze future prices. Missing price/reservation headroom prevents paid admission. New Agent steps default to 50000 total tokens, 8 model calls, 16 local READ calls, 120 seconds of active execution and 250000 micro-USD (USD 0.25). Copying a workflow version preserves its existing budget. Web request limits and human question limits are separate from the local READ-call count; every model round still uses the same token, duration and cost budget.

GET /api/v2/workflows/tools returns capabilities available to the caller, with exact argument/output schemas, effect classification, required grants and supported_step_kinds. Use the returned kinds to select tools for Scripts or Agents; tool effects alone are not an eligibility contract. Scripts support tasks.get@1, tasks.create@1, tasks.update@1, tasks.complete@1, records.get@1, records.update@1, records.upsert@1 and the seven Tour tools. Agents support tasks.get@1, records.get@1, the three Tour READ tools, web.search@1 and web.fetch@1. Select exact references such as {"name":"tasks.get","version":1}. Publication rechecks grants and freezes tool contracts. Task creation requires an explicit type (simple or visit); Visit Tasks also require a complete location. Task read/create/update results include the complete fixed location, or null for a non-visit Task. Task update can replace that whole value. There is one current version of each tool; no pre-release compatibility variants are retained. Record tools additionally require explicit object/operation/attribute scopes in record_access.

Scripts freeze main(input, tools), 1 second guest CPU, 25 seconds wall time, 32 MiB guest heap, 256 MiB isolate memory, 128 MiB child JVM heap, 64 stack frames, 8 KiB logs and 64 KiB input/output. A Script publication permits at most 16 selected tool calls, or zero with no capabilities. The host provides tools.call(name, version, arguments); host classes, filesystem, arbitrary imports, network requests and ambient credentials are unavailable. Each run uses a fresh child.

Agents freeze their model-specific inference settings, base prompt, payload bounds and selected tool contracts separately from Script resource limits. Publication executes neither kind. Unprovable Script source cannot publish; runtime failures remain possible and are reported on the run. Local effects use durable receipts: committed effects remain if a later step fails. An interrupted JavaScript heap is not automatically restarted to repeat effects.

Agent web tools​

The editor presents Read records, Read tasks, Search the web, Read web pages and Ask a human in one Tools section. Optional tools start unchecked. allowed_tools is the complete selected reference list; replace it to change selection. Human clarification retains its separate typed configuration. A prompt cannot enable an unchecked capability. Checking a tool does not expand record scope, input mappings or the saved budget.

Search and page retrieval run through the configured AI provider. Agent inputs, results from other checked tools and human answers may be used in external queries or URLs. Select inputs and tools accordingly; a domain restriction limits destinations, not which available fields the model may use.

{
"allowed_tools": [
{ "name": "web.search", "version": 1 },
{ "name": "web.fetch", "version": 1 }
],
"web": {
"max_search_calls": 3,
"max_fetch_calls": 5,
"allowed_domains": ["example.com"]
}
}

web is optional preferences, independent of selection. If any web tool is selected, publication materializes defaults of 3 searches, 5 fetches and unrestricted public domains, even when web is omitted. The workflow publication freezes these settings and a 2048 content-token retrieval preference. Without a selected web tool, there is no executable web contract.

Each call limit is an integer from 1 to 20. At most 20 domains are accepted; hostnames are normalized to lowercase, match subdomains, and cannot contain a scheme, path, IP address or local host suffix. An empty domain list removes the restriction. In a replacement action, omitting web clears preferences without unchecking selected tools. Null inner fields are invalid. Existing publications and runs retain their exact selected tools and settings.

Each paid model call offers at most one use of each selected native tool. Native pauses resume as another durable model Activity. The lifetime limits include failed attempts; READ and human continuations preserve the same native context and limits. Retrieved content is untrusted input.

Native web calls use a conservative local input allowance because provider token counting does not support these tools. Admission includes estimated tokens and search fees; fetched PDFs and provider processing can exceed the allowance, so this is not an invoice cap. Confirmed usage is retained and an actual overrun prevents further execution. Missing usage or pricing also prevents continuation. Final source links, confirmed web counts and estimated fees are available in run history.

Input bindings​

Input bindings select an explicit payload for the inline step. Each binding has a type:

[
{
"type": "field",
"input_name": "summary",
"source_node_id": "00000000-0000-4000-8000-000000000002",
"field_path": "output.summary",
"default_value": "Not supplied"
},
{ "type": "literal", "input_name": "priority", "value": 2 }
]

Field sources must come from a trigger or a step preceding the consumer on at least one path. A source skipped on the taken path supplies default_value when configured, otherwise JSON null. Publication requires the target input to accept null unless a valid default is configured, including for optional inputs. Declared source types and any literal/default values must also match the selected input property. A missing optional source property uses default_value when supplied; otherwise the optional target property is omitted. A required target needs a guaranteed value or a valid default. Explicit source null, empty text, false and zero remain values: defaults do not replace them. Defaults cannot hide a failed step or a corrupt/missing receipt from a source that must have run.

The same skipped-value check applies to record fields, record IDs and upsert keys: their target contract must accept null. Record IDs and upsert keys therefore require a source that runs on every path. Wait timestamps must also come from a source that runs on every path. A title containing a potentially skipped output must also contain nonblank literal text, so taking the other branch cannot leave the title empty. Update Task still requires its target Task source to run on every path.

value and default_value accept JSON up to 16 KiB UTF-8, 1024 nodes and 16 nested levels, including explicit null when the target permits it. Reserved object keys are rejected. Values must satisfy the declared types, constraints and date/UUID formats without coercion. Omitting default_value means no default. The input_bindings array replaces as a whole when its containing action is replaced, so remove a default by leaving it out of that replacement; default_value: null declares a null default. Bindings have at most 32 unique input names. Removing a binding removes that data from the runtime payload; a required input then needs another mapping. Omitting bindings selects an empty payload, never automatic provider disclosure.

The editor initializes a new inline Script from the directly preceding step's declared output, preserving nested types and optional properties in explicit input fields and bindings. Trigger and Task sources use their declared captured fields. Unsupported or oversized contracts require explicit narrowing. Control-only steps and ambiguous joins do not invent pass-through values. Advanced mapping can rename or remove inputs, choose earlier values, and set literals/defaults. Copying a workflow preserves its steps' explicit input contracts. Agents begin with explicit input selection; their selected values are sent to the configured model during execution.

Preview never executes Scripts or Agents and reports reachable outputs as unknown. See record actions for typed record values and workflow versions for graph authoring.

Declared resource references​

GET /api/v2/workflows/references lists workflow dependencies for a target resource. Send target_type (tour_template, object_definition or object_attribute) and target_id. An attribute also requires its owning object_id; other target types reject that parameter. The endpoint requires workflows:manage and the target's read permission.

scope=current includes current drafts, current publications and creation origins of non-deleted workflows. A paused workflow's current publication still blocks deletion. scope=all also includes retained historical versions and deleted workflows. blocks_deletion=true selects blockers only. Origins and historical references do not block deletion. Responses use items/page, with zero-based page, size 1–100 (default 20), and deterministic workflow/version/source ordering.

Rows include workflow identity, is_workflow_enabled, source node/version and configuration location, typed target, relationship and blocks_deletion. They describe declared capabilities, not observed execution: an Agent's allowed template may never actually be used. Dynamic references inside source text or prompts are not inferred. Resource delete endpoints return a typed 409 with target identity when a current dependency prevents deletion, without leaking workflow details.

Workflow and workflow-version lifecycle webhooks cover changes to code steps. MCP exposes the same workflow lifecycle operations and workflows_references_list.

Inspect execution results​

Scripts and Agents execute from the admitted workflow version. Workflow Runs exposes accepted inputs/outputs, bounded Script logs, committed Task/record effects and Agent usage. Agent activity is paginated and reports retained, partial or expired content. Raw provider requests, responses, physical attempts and accounting reservation details require the separate system-admin inspection API; customer workflow permissions do not grant access to those diagnostics.

Tour template access​

Script and Agent configurations accept tour_template_ids, a distinct set of at most 100 workspace template UUIDs. Omission or [] in a replacement action clears the set; null is invalid. The set is validated when authoring/publishing and retained in the workflow publication’s execution contract. It limits named-template reads, searches and creation. When a Script allows tours.create, publication also captures the protected Default identity so an omitted template selector applies Default through the shared Tour creation service. An empty explicit set grants no named-template access. Older published scopes without captured Default authority must be republished before using that fallback; adding Tasks to Default still requires Task creation authority at execution. Agents can read/select templates and Tours; they cannot invoke Tour writes. See Tour workflow actions for tools, bindings, current-reference semantics and the separate explicit Create tour action after Agent selection.

Payload bounds​

The serialized UTF-8 workflow definition, including inline steps, is bounded to 1 MiB. Layout is bounded to 64 KiB. Each Script source or Agent instructions is bounded to 64 KiB; a graph may have at most 20 actions. Compiled steps together are bounded to 128 KiB at publication. The encrypted admission snapshot has a 1536 KiB plaintext bound, including captured input and compiled contracts. Exceeding a bound rejects the save or admission atomically with field-level 422 validation; the server never truncates source or captured input.