starred/windmill
1
0
Fork 0
mirror of https://github.com/windmill-labs/windmill.git synced 2026-09-05 08:02:18 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
cd96503dcd42c494a61478e3c0af8a119db2087b
windmill/openflow.openapi.yaml
T
hugocasaandClaude Opus 4.8 a368d49bd8 feat(ai-agent): support reasoning effort in AI agent workflow steps (#9886) 
* feat(ai-agent): support reasoning effort in AI agent workflow steps

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(ai-agent): round-trip native Anthropic thinking blocks and fix DeepSeek/Mistral reasoning

Address review: native Anthropic now captures the signed thinking block during streaming and replays it before tool_use across iterations (prevents a 400 on multi-turn tool use). DeepSeek 'off' sends thinking:{type:disabled} instead of the rejected reasoning_effort:none, and Mistral drops temperature when reasoning is on.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(ai-agent): move reasoning effort into the provider/model selector

Store reasoning_effort on ProviderConfig (next to the model) instead of a separate flow arg, and render the selector inside AIProviderPicker under the model dropdown. Add an explicit 'off' option on models that disable reasoning by omission (e.g. Claude), so reasoning can always be turned off from the UI.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(ai-agent): use DropdownV2 for reasoning effort, matching copilot chat

Replace the Select combobox with the same DropdownV2 action-menu the copilot chat reasoning selector uses. Each option carries an action instead of a bound value, so click selection is unambiguous and there is no typeahead/sentinel-value mismatch on the off/default entries.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* chore(ai-agent): regenerate system prompts for ProviderConfig.reasoning_effort

Refresh system_prompts/auto-generated and cli skills.gen after adding reasoning_effort to the OpenFlow ProviderConfig schema (check-freshness).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(ai-agent): clear stale reasoning effort on model change; dedup bedrock reasoning folding

Address cubic review: (P1) the reasoning picker now clears the stored effort when the newly selected model doesn't accept it (e.g. carrying 'xhigh' from Opus onto a model that tops out at 'high'), not only when the model can't reason at all. (P3) the proxy's accumulate_reasoning_delta now delegates to the shared bedrock_stream_event_to_reasoning_delta so worker and proxy folding can't drift.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(ai-agent): stream reasoning summary and show a thinking affordance in flow chat

Add StreamingEvent::ReasoningTokenDelta, emitted from every worker reasoning path (Anthropic native thinking deltas, Bedrock, Gemini thought parts, OpenAI-compatible reasoning_content, OpenAI Responses reasoning_summary_text with summary:auto). The flow chat parses it and renders a collapsible 'Thinking' affordance on the assistant message (thinking tokens bill regardless of display, so surfacing the summary is billing-neutral).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(ai-agent): persist streamed reasoning onto the finished chat message

Reasoning isn't stored server-side, so the completion re-poll (which swaps temp messages for the persisted ones) was dropping the streamed thinking summary. Carry it onto the final assistant message so the 'Thought process' affordance survives the run.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(ai-agent): match flow-chat thinking box to the copilot chat reasoning UI

Replace the plain <details> thinking affordance with the same bordered, collapsible reasoning box the copilot chat uses (chevron + Brain/spinner + 'Thinking' header, markdown body, expand-while-streaming/collapse-on-answer).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(ai-agent): attribute streamed reasoning per turn by content; drop duplicated comment

Address review: the completion-poll carry-over now matches each temp assistant turn's thinking summary to its persisted message by content, so a multi-turn response (reasoning -> tool call -> final answer) no longer misattributes an earlier turn's thinking to the final answer or drops intermediate turns. Also removes a leftover duplicated comment block above the AIReasoningEffortPicker effect.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(ai-agent): address review round 2 (carry-over edges, off-token validity, aria, test)

cubic round 2: (1) reasoning carry-over now consumes temp turns in order verifying content, so identical/empty-content multi-turn responses attribute thinking correctly and reasoning-only turns aren't dropped; (2) the picker's stale-value check only accepts the off token when the model can actually disable reasoning; (3) add aria-expanded to the Thinking toggle; (4) add a test for the failed tool_result path.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(ai-agent): add bottom margin below the flow-chat thinking box

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(ai-agent): don't request OpenAI reasoning summary, matching the copilot chat

OpenAI gates reasoning summaries behind org verification, so requesting summary: auto would 400 for unverified orgs. The copilot chat requests effort only and never asks for a summary; align the worker with it (reasoning: { effort }) and drop the now-unreachable summary-delta parsing. OpenAI reasoning no longer streams a summary in flow chat (consistent with the copilot); Anthropic/Bedrock/Gemini/DeepSeek reasoning display is unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(ai-agent): scope reasoning carry-over to newly persisted messages

cubic round 3: matching by content over the full history could attach a new turn's reasoning to an older message with identical text. Restrict eligible targets to the messages just fetched for this response (via afterSeq), so historical turns are never touched.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(ai-agent): carry reasoning newest-first instead of gating on the final poll

cubic round 4: gating the carry-over on the final poll's filteredResponse dropped reasoning for messages already fetched by an earlier streaming poll (their id is excluded by afterSeq). Walk persisted newest-first and consume the newest matching pending summary, stopping once summaries run out. This response's turns are always at the end, so they claim their own reasoning (P1) before older history is reached (P2), regardless of which poll persisted them.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(ai-agent): drop flow-chat reasoning display, keep backend + effort picker

The chat-side thinking box relied on non-deterministically matching streamed (ephemeral) reasoning back onto persisted messages, which kept spawning edge cases. Remove the flow-chat display entirely (ChatMessage box, FlowChatManager carry-over/threading, parseStreamDeltas reasoning) and keep the sound backend: per-provider reasoning-effort requests, thinking-block round-trips for tool calls, and ReasoningTokenDelta streaming. A display can be built on top later, deterministically (e.g. once the stream carries the persisted message id).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(ai-agent): include reasoning_effort in default-config compare; document reasoning_token_delta

Codex/Pi nits: isSameAsStoredConfig now compares reasoning_effort so the 'use as personal default' toggle reflects effort-only changes; openflow streaming-events doc lists the reasoning_token_delta event (regenerated auto prompts).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-04 17:16:07 +02:00

1302 lines
45 KiB
YAML
Raw Blame History

openapi: '3.0.3'
info:
version: 1.747.0
title: OpenFlow Spec
contact:
name: Ruben Fiszel
email: ruben@windmill.dev
url: https://windmill.dev
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
paths: {}
externalDocs:
description: documentation portal
url: https://windmill.dev
components:
schemas:
OpenFlow:
type: object
description: Top-level flow definition containing metadata, configuration, and the flow structure
properties:
summary:
type: string
description: Short description of what this flow does
description:
type: string
description: Detailed documentation for this flow
value:
$ref: '#/components/schemas/FlowValue'
schema:
type: object
description: JSON Schema for flow inputs. Use this to define input parameters, their types, defaults, and validation. For resource inputs, set type to 'object' and format to 'resource-<type>' (e.g., 'resource-stripe')
on_behalf_of_email:
type: string
description: The flow will be run with the permissions of the user with this email.
required:
- summary
- value
FlowValue:
type: object
description: The flow structure containing modules and optional preprocessor/failure handlers
properties:
modules:
type: array
description: Array of steps that execute in sequence. Each step can be a script, subflow, loop, or branch
items:
$ref: '#/components/schemas/FlowModule'
failure_module:
description: Special module that executes when the flow fails. Receives error object with message, name, stack, and step_id. Must have id 'failure'. Only supports script/rawscript types
$ref: '#/components/schemas/FlowModule'
preprocessor_module:
description: Special module that runs before the first step on external triggers. Must have id 'preprocessor'. Only supports script/rawscript types. Cannot reference other step results
$ref: '#/components/schemas/FlowModule'
same_worker:
type: boolean
description: If true, all steps run on the same worker for better performance
preserve_step_tags:
type: boolean
description: If true and the flow runs on a custom worker tag, steps that declare their own non-empty tag run on it instead of inheriting the flow tag. Steps without their own tag still inherit the flow tag.
concurrent_limit:
type: number
description: Maximum number of concurrent executions of this flow
concurrency_key:
type: string
description: Expression to group concurrent executions (e.g., by user ID)
concurrency_time_window_s:
type: number
description: Time window in seconds for concurrent_limit
debounce_delay_s:
type: integer
description: Delay in seconds to debounce flow executions
debounce_key:
type: string
description: Expression to group debounced executions
debounce_args_to_accumulate:
type: array
description: Arguments to accumulate across debounced executions
items:
type: string
max_total_debouncing_time:
type: integer
description: Maximum total time in seconds that a job can be debounced
max_total_debounces_amount:
type: integer
description: Maximum number of times a job can be debounced
skip_expr:
type: string
description: JavaScript expression to conditionally skip the entire flow
cache_ttl:
type: number
description: Cache duration in seconds for flow results
cache_ignore_s3_path:
type: boolean
delete_after_secs:
type: integer
description: If set, delete the flow job's args, result and logs after this many seconds following job completion
flow_env:
type: object
description: "Environment variables available to all steps. Values can be strings, JSON values, or special references: '$var:path' (workspace variable) or '$res:path' (resource)."
additionalProperties: {}
priority:
type: number
description: Execution priority (higher numbers run first)
early_return:
type: string
description: JavaScript expression to return early from the flow
chat_input_enabled:
type: boolean
description: Whether this flow accepts chat-style input
notes:
type: array
description: Sticky notes attached to the flow
items:
$ref: '#/components/schemas/FlowNote'
groups:
type: array
description: Semantic groups of modules for organizational purposes
items:
$ref: '#/components/schemas/FlowGroup'
required:
- modules
Retry:
type: object
description: Retry configuration for failed module executions
properties:
constant:
type: object
description: Retry with constant delay between attempts
properties:
attempts:
type: integer
description: Number of retry attempts
seconds:
type: integer
description: Seconds to wait between retries
exponential:
type: object
description: Retry with exponential backoff (delay doubles each time)
properties:
attempts:
type: integer
description: Number of retry attempts
multiplier:
type: integer
description: Multiplier for exponential backoff
seconds:
type: integer
minimum: 1
description: Initial delay in seconds
random_factor:
type: integer
minimum: 0
maximum: 100
description: Random jitter percentage (0-100) to avoid thundering herd
retry_if:
$ref: '#/components/schemas/RetryIf'
FlowNote:
type: object
description: A sticky note attached to a flow for documentation and annotation
properties:
id:
type: string
description: Unique identifier for the note
text:
type: string
description: Content of the note
position:
type: object
description: Position of the note in the flow editor
properties:
x:
type: number
description: X coordinate
y:
type: number
description: Y coordinate
required:
- x
- y
size:
type: object
description: Size of the note in the flow editor
properties:
width:
type: number
description: Width in pixels
height:
type: number
description: Height in pixels
required:
- width
- height
color:
type: string
description: Color of the note (e.g., "yellow", "#ffff00")
type:
type: string
enum: [free, group]
description: Type of note - 'free' for standalone notes, 'group' for notes that group other nodes
locked:
type: boolean
default: false
description: Whether the note is locked and cannot be edited or moved
contained_node_ids:
type: array
items:
type: string
description: For group notes, the IDs of nodes contained within this group
required:
- id
- text
- color
- type
FlowGroup:
type: object
description: A semantic group of flow modules for organizational purposes. Does not affect execution — modules remain in their original position in the flow. Groups provide naming and collapsibility in the editor. Members are computed dynamically from all nodes on paths between start_id and end_id.
properties:
summary:
type: string
description: Display name for this group
note:
type: string
description: Markdown note shown below the group header
autocollapse:
type: boolean
default: false
description: If true, this group is collapsed by default in the flow editor. UI hint only.
start_id:
type: string
description: ID of the first flow module in this group (topological entry point)
end_id:
type: string
description: ID of the last flow module in this group (topological exit point)
color:
type: string
description: Color for the group in the flow editor
required:
- start_id
- end_id
RetryIf:
type: object
description: Conditional retry based on error or result
properties:
expr:
type: string
description: JavaScript expression that returns true to retry. Has access to 'result' and 'error' variables
required:
- expr
StopAfterIf:
type: object
description: Early termination condition for a module
properties:
skip_if_stopped:
type: boolean
description: If true, following steps are skipped when this condition triggers
expr:
type: string
description: JavaScript expression evaluated after the module runs. Can use 'result' (step's result) or 'flow_input'. Return true to stop
error_message:
type: string
nullable: true
description: Custom error message when stopping with an error. Mutually exclusive with skip_if_stopped. If set to a non-empty string, the flow stops with this error. If empty string, a default error message is used. If null or omitted, no error is raised.
error_include_result:
type: boolean
description: "When stopping with an error (error_message set), embed the stopping step's own result inside the raised error object (as error.result) instead of discarding it. The top-level result stays { error }. Defaults to false."
required:
- expr
FlowModule:
type: object
description: A single step in a flow. Can be a script, subflow, loop, or branch
properties:
id:
type: string
description: Unique identifier for this step. Used to reference results via 'results.step_id'. Must be a valid identifier (alphanumeric, underscore, hyphen)
value:
$ref: '#/components/schemas/FlowModuleValue'
stop_after_if:
description: Early termination condition evaluated after this step completes
$ref: '#/components/schemas/StopAfterIf'
stop_after_all_iters_if:
description: For loops only - early termination condition evaluated after all iterations complete
$ref: '#/components/schemas/StopAfterIf'
skip_if:
type: object
description: Conditionally skip this step based on previous results or flow inputs
properties:
expr:
type: string
description: JavaScript expression that returns true to skip. Can use 'flow_input' or 'results.<step_id>'
required:
- expr
sleep:
description: Delay before executing this step (in seconds or as expression)
$ref: '#/components/schemas/InputTransform'
cache_ttl:
type: number
description: Cache duration in seconds for this step's results
cache_ignore_s3_path:
type: boolean
timeout:
description: Maximum execution time in seconds (static value or expression)
$ref: '#/components/schemas/InputTransform'
delete_after_secs:
type: integer
description: If set, delete the step's args, result and logs after this many seconds following job completion
summary:
type: string
description: Short description of what this step does
mock:
type: object
description: Mock configuration for testing without executing the actual step
properties:
enabled:
type: boolean
description: If true, return mock value instead of executing
return_value:
description: Value to return when mocked
suspend:
type: object
description: Configuration for approval/resume steps that wait for user input
properties:
required_events:
type: integer
description: Number of approvals required before continuing
timeout:
type: integer
description: Timeout in seconds before auto-continuing or canceling
resume_form:
type: object
description: Form schema for collecting input when resuming
properties:
schema:
type: object
description: JSON Schema for the resume form
user_auth_required:
type: boolean
description: If true, only authenticated users can approve
user_groups_required:
description: Expression or list of groups that can approve
$ref: '#/components/schemas/InputTransform'
self_approval_disabled:
type: boolean
description: If true, the user who started the flow cannot approve
hide_cancel:
type: boolean
description: If true, hide the cancel button on the approval form
continue_on_disapprove_timeout:
type: boolean
description: If true, continue flow on timeout instead of canceling
priority:
type: number
description: Execution priority for this step (higher numbers run first)
continue_on_error:
type: boolean
description: If true, flow continues even if this step fails
retry:
description: Retry configuration if this step fails
$ref: '#/components/schemas/Retry'
debouncing:
description: "Debounce configuration for this step (EE only)"
type: object
properties:
debounce_delay_s:
type: integer
description: Delay in seconds to debounce this step's executions across flow runs
debounce_key:
type: string
description: "Expression to group debounced executions. Supports $workspace and $args[name]. Default: $workspace/flow/<flow_path>-<step_id>"
debounce_args_to_accumulate:
type: array
description: Array-type arguments to accumulate across debounced executions
items:
type: string
max_total_debouncing_time:
type: integer
description: Maximum total time in seconds before forced execution
max_total_debounces_amount:
type: integer
description: Maximum number of debounces before forced execution
required:
- value
- id
InputTransform:
description: Maps input parameters for a step. Can be a static value or a JavaScript expression that references previous results or flow inputs
oneOf:
- $ref: '#/components/schemas/StaticTransform'
- $ref: '#/components/schemas/JavascriptTransform'
- $ref: '#/components/schemas/AiTransform'
discriminator:
propertyName: type
mapping:
static: '#/components/schemas/StaticTransform'
javascript: '#/components/schemas/JavascriptTransform'
ai: '#/components/schemas/AiTransform'
StaticTransform:
type: object
description: Static value passed directly to the step. Use for hardcoded values or resource references like '$res:path/to/resource'
properties:
value:
description: The static value. For resources, use format '$res:path/to/resource'
type:
type: string
enum:
- static
required:
- type
JavascriptTransform:
type: object
description: JavaScript expression evaluated at runtime. Can reference previous step results via 'results.step_id' or flow inputs via 'flow_input.property'. Inside loops, use 'flow_input.iter.value' for the current iteration value
properties:
expr:
type: string
description: JavaScript expression returning the value. Available variables - results (object with all previous step results), flow_input (flow inputs), flow_input.iter (in loops)
type:
type: string
enum:
- javascript
required:
- expr
- type
AiTransform:
type: object
description: Value resolved by the AI runtime for this input. The AI engine decides how to satisfy the parameter.
properties:
type:
type: string
enum:
- ai
required:
- type
# Provider configuration schemas
AIProviderKind:
type: string
description: Supported AI provider types
enum:
- openai
- azure_openai
- azure_foundry
- anthropic
- mistral
- deepseek
- googleai
- groq
- openrouter
- togetherai
- customai
- aws_bedrock
ProviderConfig:
type: object
description: Complete AI provider configuration with resource reference and model selection
properties:
kind:
$ref: '#/components/schemas/AIProviderKind'
resource:
type: string
description: Resource reference in format '$res:{resource_path}' pointing to provider credentials
model:
type: string
description: Model identifier (e.g., 'gpt-4', 'claude-3-opus-20240229', 'gemini-pro')
reasoning_effort:
type: string
description: Provider-native reasoning effort token (e.g. 'low', 'high', 'none') for models that support extended thinking. Optional; unset leaves the provider default.
required:
- kind
- resource
- model
StaticProviderTransform:
type: object
description: Static provider configuration passed directly to the AI agent
properties:
value:
$ref: '#/components/schemas/ProviderConfig'
type:
type: string
enum:
- static
required:
- type
- value
ProviderTransform:
description: Provider configuration - can be static (ProviderConfig), JavaScript expression, or AI-determined
oneOf:
- $ref: '#/components/schemas/StaticProviderTransform'
- $ref: '#/components/schemas/JavascriptTransform'
- $ref: '#/components/schemas/AiTransform'
discriminator:
propertyName: type
mapping:
static: '#/components/schemas/StaticProviderTransform'
javascript: '#/components/schemas/JavascriptTransform'
ai: '#/components/schemas/AiTransform'
# Memory configuration schemas
MemoryOff:
type: object
description: No conversation memory/context
properties:
kind:
type: string
enum:
- 'off'
required:
- kind
MemoryAuto:
type: object
description: Automatic context management
properties:
kind:
type: string
enum:
- auto
context_length:
type: integer
description: Maximum number of messages to retain in context
memory_id:
type: string
description: Identifier for persistent memory across agent invocations
required:
- kind
MemoryMessage:
type: object
description: A single message in conversation history
properties:
role:
type: string
enum:
- user
- assistant
- system
content:
type: string
required:
- role
- content
MemoryManual:
type: object
description: Explicit message history
properties:
kind:
type: string
enum:
- manual
messages:
type: array
items:
$ref: '#/components/schemas/MemoryMessage'
required:
- kind
- messages
MemoryConfig:
description: Conversation memory configuration
oneOf:
- $ref: '#/components/schemas/MemoryOff'
- $ref: '#/components/schemas/MemoryAuto'
- $ref: '#/components/schemas/MemoryManual'
discriminator:
propertyName: kind
mapping:
'off': '#/components/schemas/MemoryOff'
auto: '#/components/schemas/MemoryAuto'
manual: '#/components/schemas/MemoryManual'
StaticMemoryTransform:
type: object
description: Static memory configuration passed directly to the AI agent
properties:
value:
$ref: '#/components/schemas/MemoryConfig'
type:
type: string
enum:
- static
required:
- type
- value
MemoryTransform:
description: Memory configuration - can be static (MemoryConfig), JavaScript expression, or AI-determined
oneOf:
- $ref: '#/components/schemas/StaticMemoryTransform'
- $ref: '#/components/schemas/JavascriptTransform'
- $ref: '#/components/schemas/AiTransform'
discriminator:
propertyName: type
mapping:
static: '#/components/schemas/StaticMemoryTransform'
javascript: '#/components/schemas/JavascriptTransform'
ai: '#/components/schemas/AiTransform'
FlowModuleValue:
description: The actual implementation of a flow step. Can be a script (inline or referenced), subflow, loop, branch, or special module type
oneOf:
- $ref: '#/components/schemas/RawScript'
- $ref: '#/components/schemas/PathScript'
- $ref: '#/components/schemas/PathFlow'
- $ref: '#/components/schemas/ForloopFlow'
- $ref: '#/components/schemas/WhileloopFlow'
- $ref: '#/components/schemas/BranchOne'
- $ref: '#/components/schemas/BranchAll'
- $ref: '#/components/schemas/Identity'
- $ref: '#/components/schemas/AiAgent'
discriminator:
propertyName: type
mapping:
rawscript: '#/components/schemas/RawScript'
script: '#/components/schemas/PathScript'
flow: '#/components/schemas/PathFlow'
forloopflow: '#/components/schemas/ForloopFlow'
whileloopflow: '#/components/schemas/WhileloopFlow'
branchone: '#/components/schemas/BranchOne'
branchall: '#/components/schemas/BranchAll'
identity: '#/components/schemas/Identity'
aiagent: '#/components/schemas/AiAgent'
RawScript:
type: object
description: Inline script with code defined directly in the flow. Use 'bun' as default language if unspecified. The script receives arguments from input_transforms
properties:
# to be made required once migration is over
input_transforms:
type: object
description: Map of parameter names to their values (static or JavaScript expressions). These become the script's input arguments
additionalProperties:
$ref: '#/components/schemas/InputTransform'
content:
type: string
description: The script source code. Should export a 'main' function
language:
type: string
description: Programming language for this script
enum:
- deno
- bun
- python3
- go
- bash
- powershell
- postgresql
- mysql
- bigquery
- snowflake
- mssql
- oracledb
- graphql
- nativets
- php
- rust
- ansible
- csharp
- nu
- java
- ruby
- rlang
- duckdb
# for related places search: ADD_NEW_LANG
path:
type: string
description: Optional path for saving this script
lock:
type: string
description: Lock file content for dependencies
type:
type: string
enum:
- rawscript
tag:
type: string
description: Worker group tag for execution routing
concurrent_limit:
type: number
description: Maximum concurrent executions of this script
concurrency_time_window_s:
type: number
description: Time window for concurrent_limit
custom_concurrency_key:
type: string
description: Custom key for grouping concurrent executions
is_trigger:
type: boolean
description: If true, this script is a trigger that can start the flow
assets:
type: array
description: External resources this script accesses (S3 objects, resources, etc.)
items:
type: object
required:
- path
- kind
properties:
path:
type: string
description: Path to the asset
kind:
type: string
description: Type of asset
enum:
- s3object
- resource
- ducklake
- datatable
- volume
access_type:
type: string
nullable: true
description: Access level for this asset
enum: [r, w, rw]
alt_access_type:
type: string
nullable: true
description: Alternative access level
enum: [r, w, rw]
required:
- type
- content
- language
- input_transforms
PathScript:
type: object
description: Reference to an existing script by path. Use this when calling a previously saved script instead of writing inline code
properties:
input_transforms:
type: object
description: Map of parameter names to their values (static or JavaScript expressions). These become the script's input arguments
additionalProperties:
$ref: '#/components/schemas/InputTransform'
path:
type: string
description: Path to the script in the workspace (e.g., 'f/scripts/send_email')
hash:
type: string
description: Optional specific version hash of the script to use
type:
type: string
enum:
- script
tag_override:
type: string
description: Override the script's default worker group tag
is_trigger:
type: boolean
description: If true, this script is a trigger that can start the flow
required:
- type
- path
- input_transforms
PathFlow:
type: object
description: Reference to an existing flow by path. Use this to call another flow as a subflow
properties:
input_transforms:
type: object
description: Map of parameter names to their values (static or JavaScript expressions). These become the subflow's input arguments
additionalProperties:
$ref: '#/components/schemas/InputTransform'
path:
type: string
description: Path to the flow in the workspace (e.g., 'f/flows/process_user')
type:
type: string
enum:
- flow
required:
- type
- path
- input_transforms
ForloopFlow:
type: object
description: Executes nested modules in a loop over an iterator. Inside the loop, use 'flow_input.iter.value' to access the current iteration value, and 'flow_input.iter.index' for the index. Supports parallel execution for better performance on I/O-bound operations
properties:
modules:
type: array
description: Steps to execute for each iteration. These can reference the iteration value via 'flow_input.iter.value'
items:
$ref: '#/components/schemas/FlowModule'
iterator:
description: JavaScript expression that returns an array to iterate over. Can reference 'results.step_id' or 'flow_input'
$ref: '#/components/schemas/InputTransform'
skip_failures:
type: boolean
description: If true, iteration failures don't stop the loop. Failed iterations return null
type:
type: string
enum:
- forloopflow
parallel:
type: boolean
description: If true, iterations run concurrently (faster for I/O-bound operations). Use with parallelism to control concurrency
parallelism:
description: Maximum number of concurrent iterations when parallel=true. Limits resource usage. Can be static number or expression
$ref: '#/components/schemas/InputTransform'
squash:
type: boolean
required:
- modules
- iterator
- skip_failures
- type
WhileloopFlow:
type: object
description: Executes nested modules repeatedly while a condition is true. The loop checks the condition after each iteration. Use stop_after_if on modules to control loop termination
properties:
modules:
type: array
description: Steps to execute in each iteration. Use stop_after_if to control when the loop ends
items:
$ref: '#/components/schemas/FlowModule'
skip_failures:
type: boolean
description: If true, iteration failures don't stop the loop. Failed iterations return null
type:
type: string
enum:
- whileloopflow
parallel:
type: boolean
description: If true, iterations run concurrently (use with caution in while loops)
parallelism:
description: Maximum number of concurrent iterations when parallel=true
$ref: '#/components/schemas/InputTransform'
squash:
type: boolean
required:
- modules
- skip_failures
- type
BranchOne:
type: object
description: Conditional branching where only the first matching branch executes. Branches are evaluated in order, and the first one with a true expression runs. If no branches match, the default branch executes
properties:
branches:
type: array
description: Array of branches to evaluate in order. The first branch with expr evaluating to true executes
items:
type: object
properties:
summary:
type: string
description: Short description of this branch condition
expr:
type: string
description: JavaScript expression that returns boolean. Can use 'results.step_id' or 'flow_input'. First true expr wins
modules:
type: array
description: Steps to execute if this branch's expr is true
items:
$ref: '#/components/schemas/FlowModule'
required:
- modules
- expr
default:
type: array
description: Steps to execute if no branch expressions match
items:
$ref: '#/components/schemas/FlowModule'
type:
type: string
enum:
- branchone
required:
- branches
- default
- type
BranchAll:
type: object
description: Parallel branching where all branches execute simultaneously. Unlike BranchOne, all branches run regardless of conditions. Useful for executing independent tasks concurrently
properties:
branches:
type: array
description: Array of branches that all execute (either in parallel or sequentially)
items:
type: object
properties:
summary:
type: string
description: Short description of this branch's purpose
skip_failure:
type: boolean
description: If true, failure in this branch doesn't fail the entire flow
modules:
type: array
description: Steps to execute in this branch
items:
$ref: '#/components/schemas/FlowModule'
required:
- modules
type:
type: string
enum:
- branchall
parallel:
type: boolean
description: If true, all branches execute concurrently. If false, they execute sequentially
required:
- branches
- type
AgentTool:
type: object
description: A tool available to an AI agent. Can be a flow module or an external MCP (Model Context Protocol) tool
properties:
id:
type: string
description: Unique identifier for this tool. Cannot contain spaces - use underscores instead (e.g., 'get_user_data' not 'get user data')
summary:
type: string
description: Short description of what this tool does (shown to the AI)
value:
$ref: '#/components/schemas/ToolValue'
required:
- id
- value
ToolValue:
description: The implementation of a tool. Can be a flow module (script/flow) or an MCP tool reference
oneOf:
- $ref: '#/components/schemas/FlowModuleTool'
- $ref: '#/components/schemas/McpToolValue'
- $ref: '#/components/schemas/WebsearchToolValue'
discriminator:
propertyName: tool_type
mapping:
flowmodule: '#/components/schemas/FlowModuleTool'
mcp: '#/components/schemas/McpToolValue'
websearch: '#/components/schemas/WebsearchToolValue'
FlowModuleTool:
description: A tool implemented as a flow module (script, flow, etc.). The AI can call this like any other flow module
allOf:
- type: object
properties:
tool_type:
type: string
enum:
- flowmodule
required:
- tool_type
- $ref: '#/components/schemas/FlowModuleValue'
WebsearchToolValue:
type: object
description: A tool implemented as a websearch tool. The AI can call this like any other websearch tool
properties:
tool_type:
type: string
enum:
- websearch
required:
- tool_type
McpToolValue:
type: object
description: Reference to an external MCP (Model Context Protocol) tool. The AI can call tools from MCP servers
properties:
tool_type:
type: string
enum:
- mcp
resource_path:
type: string
description: Path to the MCP resource/server configuration
include_tools:
type: array
description: Whitelist of specific tools to include from this MCP server
items:
type: string
exclude_tools:
type: array
description: Blacklist of tools to exclude from this MCP server
items:
type: string
required:
- tool_type
- resource_path
AiAgent:
type: object
description: AI agent step that can use tools to accomplish tasks. The agent receives inputs and can call any of its configured tools to complete the task
properties:
input_transforms:
type: object
description: Input parameters for the AI agent mapped to their values
properties:
provider:
$ref: '#/components/schemas/ProviderTransform'
output_type:
allOf:
- $ref: '#/components/schemas/InputTransform'
description: |
Output format type.
Valid values: 'text' (default) - plain text response, 'image' - image generation
user_message:
allOf:
- $ref: '#/components/schemas/InputTransform'
description: The user's prompt/message to the AI agent. Supports variable interpolation with flow.input syntax.
system_prompt:
allOf:
- $ref: '#/components/schemas/InputTransform'
description: System instructions that guide the AI's behavior, persona, and response style. Optional.
streaming:
allOf:
- $ref: '#/components/schemas/InputTransform'
description: |
Boolean. If true, stream the AI response incrementally.
Streaming events include: token_delta, reasoning_token_delta, tool_call, tool_call_arguments, tool_execution, tool_result
memory:
$ref: '#/components/schemas/MemoryTransform'
output_schema:
allOf:
- $ref: '#/components/schemas/InputTransform'
description: |
JSON Schema object defining structured output format. Used when you need the AI to return data in a specific shape.
Supports standard JSON Schema properties: type, properties, required, items, enum, pattern, minLength, maxLength, minimum, maximum, etc.
Example: { type: 'object', properties: { name: { type: 'string' }, age: { type: 'integer' } }, required: ['name'] }
user_attachments:
allOf:
- $ref: '#/components/schemas/InputTransform'
description: |
Array of file references (images or PDFs) for the AI agent.
Format: Array<{ bucket: string, key: string }> - S3 object references
Example: [{ bucket: 'my-bucket', key: 'documents/report.pdf' }]
max_completion_tokens:
allOf:
- $ref: '#/components/schemas/InputTransform'
description: |
Integer. Maximum number of tokens the AI will generate in its response.
Range: 1 to 4,294,967,295. Typical values: 256-4096 for most use cases.
temperature:
allOf:
- $ref: '#/components/schemas/InputTransform'
description: |
Float. Controls randomness/creativity of responses.
Range: 0.0 to 2.0 (provider-dependent)
- 0.0 = deterministic, focused responses
- 0.7 = balanced (common default)
- 1.0+ = more creative/random
max_iterations:
allOf:
- $ref: '#/components/schemas/InputTransform'
description: |
Number. Limits how many times the agent can loop through reasoning and tool use.
Range: 1-1000.
required:
- provider
- user_message
- output_type
tools:
type: array
description: Array of tools the agent can use. The agent decides which tools to call based on the task
items:
$ref: '#/components/schemas/AgentTool'
type:
type: string
enum:
- aiagent
tag:
type: string
description: Worker group tag for execution routing. If not set, the AI agent step runs on the flow's tag (default `flow`)
omit_output_from_conversation:
type: boolean
default: false
description: If true, this AI agent step does not persist its assistant or tool messages to the flow conversation when chat mode is enabled.
parallel:
type: boolean
description: If true, the agent can execute multiple tool calls in parallel
required:
- tools
- type
- input_transforms
Identity:
type: object
description: Pass-through module that returns its input unchanged. Useful for flow structure or as a placeholder
properties:
type:
type: string
enum:
- identity
flow:
type: boolean
description: If true, marks this as a flow identity (special handling)
required:
- type
FlowStatus:
type: object
properties:
step:
type: integer
modules:
type: array
items:
$ref: '#/components/schemas/FlowStatusModule'
user_states:
additionalProperties: true
preprocessor_module:
allOf:
- $ref: '#/components/schemas/FlowStatusModule'
failure_module:
allOf:
- $ref: '#/components/schemas/FlowStatusModule'
- type: object
properties:
parent_module:
type: string
retry:
type: object
properties:
fail_count:
type: integer
failed_jobs:
type: array
items:
type: string
format: uuid
required:
- step
- modules
- failure_module
FlowStatusModule:
type: object
properties:
type:
type: string
enum:
- WaitingForPriorSteps
- WaitingForEvents
- WaitingForExecutor
- InProgress
- Success
- Failure
id:
type: string
job:
type: string
format: uuid
count:
type: integer
progress:
type: integer
iterator:
type: object
properties:
index:
type: integer
itered:
type: array
items: {}
itered_len:
type: integer
args: {}
flow_jobs:
type: array
items:
type: string
flow_jobs_success:
type: array
items:
type: boolean
flow_jobs_duration:
type: object
properties:
started_at:
type: array
items:
type: string
duration_ms:
type: array
items:
type: integer
branch_chosen:
type: object
properties:
type:
type: string
enum: [branch, default]
branch:
type: integer
required:
- type
branchall:
type: object
properties:
branch:
type: integer
len:
type: integer
required:
- branch
- len
approvers:
type: array
items:
type: object
properties:
resume_id:
type: integer
approver:
type: string
required:
- resume_id
- approver
failed_retries:
type: array
items:
type: string
format: uuid
skipped:
type: boolean
agent_actions:
type: array
items:
type: object
oneOf:
- type: object
properties:
job_id:
type: string
format: uuid
function_name:
type: string
type:
type: string
enum: [tool_call]
module_id:
type: string
required:
- job_id
- function_name
- type
- module_id
- type: object
properties:
call_id:
type: string
format: uuid
function_name:
type: string
resource_path:
type: string
type:
type: string
enum: [mcp_tool_call]
arguments:
type: object
required:
- call_id
- function_name
- resource_path
- type
- type: object
properties:
type:
type: string
enum: [web_search]
required:
- type
- type: object
properties:
type:
type: string
enum: [message]
required:
- content
- type
agent_actions_success:
type: array
items:
type: boolean
required: [type]
Reference in New Issue View Git Blame Copy Permalink