Visual Flow Editor

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

The visual editor is the portal surface for inspecting and editing orchestration_flow assets as a node graph instead of raw YAML.

What It Represents

Each node corresponds to a flow step. Edges represent execution transitions such as next, on_success, on_failure, branches, cases, parallel_steps, and join_from.

The editor is most useful when you want to:

inspect a flow graph quickly
move between canvas and YAML
debug the shape of a flow during authoring
understand how a release-bound flow is structured

Current Step Taxonomy

The current public flow schema includes these step types:

task
llm_call
retrieval
embedding
condition
parallel
join
loop
switch
subflow
agent
agent_handoff
approval
error_handler
return

Older editor descriptions that refer to action as a step type are stale. task is the current action-driven step type.

YAML Round-Trip

The editor is expected to round-trip the same flow contract documented in Flows. That means the YAML surface should use current fields such as:

trigger.type
goal and tools for agent
action for task
{{trigger.field}}, {{flow.inputs.field}}, {{steps.id.output}}, {{ctx.field}}, and {{release.role}} expressions

Example:


name: Classifier Flow
description: Classify a user query
trigger:
  type: api_request
  inputs_schema:
    type: object
    required: [query]
    properties:
      query:
        type: string
entry_step: classify
steps:
  - id: classify
    type: llm_call
    inputs:
      messages:
        - role: user
          content: "Classify the following query: {{trigger.query}}"
    next: respond
  - id: respond
    type: return
    output:
      result: "{{steps.classify.output.content}}"

Expression Assistance

The editor should help authors compose current runtime expressions, especially:

Expression Pattern	Meaning
`{{trigger.<field>}}`	input payload field
`{{flow.inputs.<field>}}`	alias for input payload
`{{steps.<step_id>.output}}`	full prior-step output
`{{steps.<step_id>.output.<field>}}`	nested prior-step output
`{{ctx.<field>}}`	shared context value
`{{release.<role>}}`	active release binding by role

Older editor references to trigger.inputs.* or context.* are not the current runtime contract.

Authoring workflow

Use the visual editor for graph shape and the YAML panel for exact contract review:

Start from a template, generated flow, or existing orchestration_flow asset version.
Inspect nodes and transition edges on the canvas.
Edit step-specific fields in YAML when precision matters.
Validate the flow before creating a new immutable asset version.
Bind the new flow version into a draft release and run release validation.

Canvas edits should preserve stable step IDs. Changing a step ID can invalidate references such as next, branch targets, join_from, and {{steps.<step_id>.output}} expressions.

Edge semantics

Edge source	Meaning
`next`	Normal sequential transition
`on_success`	Transition after a successful task-like step
`on_failure`	Transition after a failed task-like step
`branches`	Named condition branches
`cases`	Switch-case transitions
`parallel_steps`	Parallel fan-out
`join_from`	Join dependency references

If a graph edit removes a target step, the corresponding edge field must be removed or redirected before the flow can be safely released.

Debugging Expectations

The visual editor is a useful inspection surface, but treat the current source of truth as:

the stored flow content
control-plane validation
runtime execution and evidence APIs

Use the editor to understand and refine a flow, then validate the flow before attaching it to a release.

Common validation failures after visual edits include:

Failure	Fix
Missing `entry_step` target	Point `entry_step` at an existing step ID
Unknown transition target	Update or remove the stale edge
Unreachable required step	Add a transition path from `entry_step`
Flow uses provider-routed steps without `model_policy` binding	Add a release binding with role `model_policy`
Flow uses `embedding` without an embedding route	Add `model_policy.embedding_route` before activation

Best Practices

Use the editor and YAML together. The canvas is good for graph shape; the YAML is better for precise contract review.

Prefer current contract terms. Use task, not action, and current binding expressions when editing nodes.

Validate after graph edits. Structural changes can easily leave stale branch targets or unreachable steps if they are not revalidated.