Workflow builder

The Workflow Agent builder converts a description into an ordered, inspectable workflow definition. It is designed for draft review, route analysis, and simulation rather than live activation. Use this page to understand the information shown in the builder and the decisions you can make without assuming that every visible route or control is executable.

Builder layout

The builder brings several views of the same draft together. A step list presents the proposed sequence. Route-readiness information explains how each app interaction might be reached. A read-only JSON panel exposes the structured definition, while the workflow preview summarizes the result in a form suited to simulation.

The initial prompt can arrive through the prompt search parameter on the build route. Draft generation is deterministic for the supplied description and available app data. Because the app source can fall back to a fixture, the same prompt may encounter a smaller discovery set in another environment.

The main areas serve different purposes:

No single panel should be read as proof of execution. The builder keeps canExecute=false visible for generated connector review and states that no external app is contacted.

Steps

Each step should represent one understandable unit of work. A draft normally begins with an event or source operation, then introduces transformations, checks, or destination actions in the order they would be evaluated.

Review the sequence for hidden dependencies. If a later step expects data that no earlier step provides, the draft needs revision. If two different actions have been combined into one step, split the intent in the description and regenerate the draft. The current product is strongest when the workflow can be expressed as a straightforward ordered path.

A step can refer to an app action even when the corresponding connector is not executable. The route status tells you how far the product can reason about that action. suggested_only represents a conceptual relationship. bridge_available points to a known bridge path. api_mcp_possible identifies a route that may be possible through API or MCP configuration. native denotes a native route in the data model, while coming_soon remains unavailable.

The execution-route value adds another dimension, such as native, a named bridge, webhook, http_api, mcp, generated_connector, or none. Keep the definition in draft form whenever the route status, connection state, or activation gate is incomplete.

Inputs

Inputs describe the data a step expects. They may be literal values from the workflow description, references to a detected app, or values intended to come from an earlier step. Their purpose is to make the draft’s assumptions visible before a simulation is requested.

Check that each input has an identifiable source and a clear destination. Avoid putting secrets into free-form text. Credential references belong to the connection layer, not inside the workflow prompt or read-only JSON.

When mapping values between apps, inspect names and types rather than assuming that similar labels are compatible. The current sources do not establish a universal schema-mapping engine, so field-level behavior should remain as specific as the draft displays it. If the builder cannot explain where a value originates, revise the description or mark the step as unresolved.

Inputs can also expose readiness problems. A required source image, credential, approval context, or provider configuration may be absent. Such a gap should block the affected preview path instead of being replaced by a default that the repository does not define.

Conditions

The required Conditions section does not correspond to a verified general visual branching editor. The builder can reflect checks and gates that arise from the draft, route confidence, credential state, approval requirements, and simulation outcome, but the supplied sources do not establish arbitrary branches, loops, or a complete condition authoring surface.

Treat condition-like behavior as explicit draft logic. If the description says that an action should occur only when a value meets a criterion, verify that the generated steps represent that check plainly. Do not assume support for nested expressions, multiple branches, retries, compensation, or parallel paths unless the draft visibly provides them.

For a workflow that depends on complex branching, divide the idea into smaller drafts. One draft can validate the main path, while a separate design note records the unsupported branch. This keeps the preview honest and prevents a natural-language condition from being mistaken for a live control-flow guarantee.

Approvals

Approval gates identify actions that should not progress without a decision. In the builder, they are part of the preview and activation-check model. The associated approval page renders simulation-derived packets, but its Approve, Reject, and Request changes controls are disabled.

An approval requirement can still be useful during drafting. It tells the operator where sensitive or externally consequential work would need review. The packet can summarize the proposed action, route, evidence, and reason for the gate. It does not create a signed decision, and it must not be confused with the runtime approval records documented for agent runs elsewhere.

If a step requires approval, leave it gated through simulation. Do not remove the requirement merely to obtain a cleaner preview. A simulation may show that the action would pause or remain blocked; that is a valid result for the current product state.

Validation

Validation checks whether the draft has enough coherent information to produce a preview. It can expose missing apps, unsupported routes, absent credentials, unresolved approvals, or definition errors. The outcome should explain which part of the draft needs attention rather than imply that the workflow is ready for production.

Use the builder’s visible gates as separate checks:

• draft status confirms that a definition was constructed;
• route status explains whether a candidate path exists;
• simulation status records the no-write evaluation;
• approval status shows whether a gate remains unresolved;
• live execution remains locked in the inspected milestone.

Compare the step list, route information, and read-only JSON after every substantial edit. If they disagree, keep the record as a draft and document the mismatch. A successful validation followed by a successful simulation is the strongest supported result. It is still not an activation event, remote write, durable run, or proof that a configured provider will accept a future request.

Compare the visual and structured definitions

The step list and read-only JSON should describe the same workflow. Check step identifiers, app references, action names, inputs, and order. A mismatch can indicate that the UI is rendering a simplified summary or that the draft changed without every panel updating. Because the JSON is read-only, correct the source description or supported builder input and regenerate rather than editing the structure outside the product.

Route confidence should also be interpreted with the structured definition. A confident app match can still point to none as the execution route, while a lower-confidence suggestion may need operator confirmation before the draft is trusted. The source does not establish a numerical confidence contract, so describe the visible readiness outcome rather than publishing thresholds.

Step review pattern

For each step, write down the event or input that starts it, the app action it proposes, the values it consumes, and the output expected by the next step. Then inspect the candidate route. This exposes skipped transformations and accidental circular dependencies without requiring a live execution attempt.

When a step proposes a sensitive write, verify that the draft marks an approval gate. When a step depends on a credential, ensure the value is referenced through a connection rather than copied into the definition. A step that cannot meet these conditions should remain unresolved.

What validation does not cover

Builder validation does not verify remote schemas, provider permissions, third-party rate limits, webhook delivery, scheduler behavior, or MCP tool output. It also does not prove that an illustrative generated connector passed security review. Those checks belong to future implementation and operational testing. The current validator establishes that the preview definition is internally reviewable and that known local gates are represented.

Editing strategy

Make one category of change at a time. First correct the app roles, then the step order, then inputs, then gates. Regenerating after several unrelated changes can make it hard to identify why the route or simulation result changed.

The current builder is deterministic for the supplied description and loaded data, but the loaded app source can differ across environments. A draft created from fixture data may not reproduce identically where the production-derived CSV is available.

Route-confidence consequences

Route confidence can guide review without becoming an execution guarantee. A strong match can still be blocked by setup or policy. A weak match can produce a reasonable draft that requires human confirmation. Do not publish numeric thresholds or translate confidence into availability unless the interface provides a documented rule.

When no route is represented, keep the step as a design requirement or remove it from the supported preview. Assigning a familiar bridge by hand would bypass the loader’s readiness model.

Approval placement

Place the gate immediately before the consequential action it protects. A broad approval at the start of the workflow can hide which later step needs review, while a gate after the action would be meaningless. The preview should make the proposed change and evidence visible before the boundary.

Validation response

A validation message should be handled according to its domain. Fix definition errors in the description or supported inputs. Fix setup errors in integrations. Leave policy, live-blocked, coming-soon, and disabled states unresolved. This separation prevents repeated draft regeneration from masking a product limitation.

Builder exit criteria

Leave the builder when the draft is internally coherent, every unresolved input is visible, route status is understood, sensitive actions remain gated, and the simulation can explain where execution would stop. Do not keep editing merely to remove warning states that describe real product limitations. A transparent blocked draft is more useful than a polished definition that implies unsupported behavior.

Definition ownership

Treat the generated definition as a product-created draft tied to the current prompt and source data. The repository does not verify collaborative editing, locking, version ownership, or external import. Avoid presenting the read-only JSON as a stable public workflow format.

Read-only JSON usage

Use the JSON view to inspect identifiers, step order, inputs, and route data. Copying it into another system or editing it externally is not a supported deployment path. Builder evidence does not publish a stable import contract, schema-version policy, or compatibility guarantee for generated definitions.

Consistency after regeneration

After regenerating, verify that previously resolved gates did not reappear under another step or route. A new draft is a fresh preview and should be reviewed on its own terms.