Layer Workflows

Overview

A workflow is a multi-step pipeline a studio built in Layer's Blueprint editor and published. Where Forge runs one model with parameters you choose, a workflow runs a graph someone already designed, tested, and standardised. When one exists for the task, it is usually the better answer: it encodes decisions the studio has already made.

Call get_workflow_instructions before the first workflow run in a session. The shared loop and the spend gate are in the layer skill.

If a sibling skill named here is missing from your available skills, ask the user to install it (npx skills add layerai/skills --skill <name>); unattended, proceed from tool schemas and flag the gap.

Check for one first

Before building a multi-step sequence out of Forge runs, call list_workflows with the workspace id and the fulltext filter set to what the user is trying to make. Results come back ordered by relevance. A studio that has a published pipeline for character turnarounds does not want an improvised one, and the improvised version will not match the assets already in the game.

This is worth one cheap read-only call at the start of any task with more than one generation step.

The input schema is the contract

Every workflow defines its own inputs, and list_workflows returns the full JSON schema per workflow. Treat that schema as the source of truth, not the workflow's name or description. Two workflows that both say "character sheet" can take entirely different inputs.

Read it before composing the run, and pass exactly what it declares. Two input types have traps:

• Files. Upload first and pass the returned file_id, or pass the file_id an earlier run already produced. Never pass a URL where the schema wants a file id.
• Styles. A style input takes a reference set's set_id from list_reference_sets. A base_model_id is not a valid value there, and passing one fails in a way that reads like a workflow bug.

When a required input has no obvious value, ask the user rather than inventing one. A workflow run that completes with a wrong input still costs full price.

Estimate, execute, poll

estimate_workflow_price with the workflow id and the intended inputs returns the price without executing. Present it as a table: what the workflow produces, which workspace pays, price against balance. Above 20 CUs, ask and wait for an explicit yes.

execute_workflow returns a run_id and poll_interval_seconds. get_workflow_run reports status through PENDING, RUNNING, then SUCCESS, FAILURE, or CANCELLED, and reports step information while running.

Workflows take longer than single generations, so report progress periodically as "completed steps / total steps" rather than polling silently. cancel_workflow_run stops a run and releases reserved Creative Units; units already consumed are not refunded.

Worked example

"Run our character turnaround pipeline on this concept."

1. list_workflows with fulltext: "turnaround", which returns the workflow and its input schema.
2. Read the schema. It wants a character_image file id, a view_count integer, and an optional style.
3. The concept came from an earlier run, so it already has a file_id. No upload needed.
4. estimate_workflow_price with those inputs. It returns 34 CUs against a balance of 900, which is over the gate, so present the table and wait for an explicit yes.
5. execute_workflow, with a session_name so the outputs group in the Layer app.
6. get_workflow_run at poll_interval_seconds, reporting "3 / 7 steps" as it goes.
7. On SUCCESS, present the outputs as a table with links. Each output carries a file_id that can feed the next run directly.

Common mistakes

• Improvising a multi-step sequence in Forge without checking list_workflows first.
• Guessing inputs from the workflow's name instead of reading its schema.
• Passing a base_model_id to a style input that wants a reference set set_id.
• Passing a URL where the schema declares a file id.
• Executing without an estimate, or clearing 20 CUs without an explicit yes.
• Polling a long run silently, with no step progress reported.
• Re-uploading an asset that a previous run already produced.