Guide · composition

Compose with artifact inputs

Some workflows can accept an existing artifact as input instead of generating everything from scratch. This guide shows how an author wires that up, and how the same workflow runs whether you supply an artifact or let it generate one.

Example workflow
generate-research-infographic
Input artifact
research / research-report
Mechanism
artifactReference intake field + satisfiedBy
Output
visual / infographic

The idea

A workflow is a function over artifacts: it can produce one and consume one. The research infographic needs a research report to visualize. It can obtain that report two ways:

Generate

Run the research-report sub-workflow inline to produce a fresh report, then visualize it.

Supply

Pass an existing report artifact you already reviewed and liked; the workflow skips generation and visualizes that one.

1. Declare the input (author)

Add an intake field of type artifactReference, constrained to the class and type the workflow knows how to read. Typing matters: it lets the run-time picker filter candidates and lets the platform validate what you pass.

intake fieldjson
{
  "name": "sourceReport",
  "type": "artifactReference",
  "required": false,
  "description": "An existing research report to visualize",
  "artifactClass": "research",
  "artifactType": "research-report"
}

2. Let the input satisfy the step (author)

Mark the report step satisfiedBy the input field. When a report is supplied, the engine skips the sub-workflow and binds the supplied report into that step’s output slot — so downstream steps that read {step-1.report.summary} work unchanged.

runtime stepjson
{
  "id": "step-1",
  "name": "Research report",
  "kind": "subWorkflow",
  "subWorkflow": { "templateId": "generate-research-report" },
  "satisfiedBy": "inputs.sourceReport"
}

3a. Run by supplying an artifact

Pass the report’s id in intake. The engine loads it, exposes it at inputs.sourceReport, and the report step is skipped.

POST /v1/runs — supplyjson
{
  "templateId": "generate-research-infographic",
  "intake": {
    "topic": "The history of dinosaurs",
    "aspectRatio": "3:4",
    "sourceReport": "artifact-7c4e91aa"
  }
}

3b. Or run by generating

Omit the optional input and the workflow generates a fresh report through the sub-workflow, exactly as before. The two requests differ by a single field.

POST /v1/runs — generatejson
{
  "templateId": "generate-research-infographic",
  "intake": {
    "topic": "The history of dinosaurs",
    "aspectRatio": "3:4"
  }
}

What changes in the run

  1. Supplied

    The report step is skipped; the run records the supplied artifact id as provenance. No child run, no report-generation cost.

  2. Generated

    The report step runs as a child sub-workflow, producing its own report artifact, with cost rolled up into the parent run.

  3. Either way

    The infographic step reads the same report reference and produces the same artifact shape, linked back to the report it used.

Validation runs before execution: a supplied artifact must exist, be in your scope, and match the field’s declared class/type — otherwise the run is rejected with a clear error.