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
actionsarray 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_accessandtour_template_idslists remove those capabilities. Null lists, duplicate selections and unsupported entries return422. - 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.
| Mode | Configuration | Values 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.