|
| 1 | +# gr.Workflow |
| 2 | + |
| 3 | +`gr.Workflow` is a visual, node-based AI pipeline builder built into Gradio. It lets you chain together Hugging Face Spaces, models, datasets, and your own Python functions on a drag-and-drop canvas: |
| 4 | + |
| 5 | +<img width="1901" alt="image" src="https://github.com/user-attachments/assets/a77bf9a8-c264-4037-80e1-2b37c5e529d4" /> |
| 6 | + |
| 7 | + |
| 8 | +## Quickstart |
| 9 | + |
| 10 | +The simplest possible Workflow app: |
| 11 | + |
| 12 | +```python |
| 13 | +import gradio as gr |
| 14 | + |
| 15 | +gr.Workflow().launch() |
| 16 | +``` |
| 17 | + |
| 18 | +Open the app, drag Spaces and models from the sidebar onto the canvas, connect their ports, and hit **Run**. As you create nodes and edges, a `workflow.json` file will automatically be created in your working directory. You can also use a coding agent to write or edit this file, allowing you to create workflows programmatically. |
| 19 | + |
| 20 | +## Binding Python functions |
| 21 | + |
| 22 | +Pass your own Python functions via `bind=` and they appear as callable nodes on the canvas. Gradio inspects the function signature to auto-generate input/output ports. |
| 23 | + |
| 24 | +```python |
| 25 | +import gradio as gr |
| 26 | + |
| 27 | +def summarize(text: str) -> str: |
| 28 | + return text[:200] |
| 29 | + |
| 30 | +gr.Workflow(bind=[summarize]).launch() |
| 31 | +``` |
| 32 | + |
| 33 | +Use a dict to give nodes explicit names: |
| 34 | + |
| 35 | +```python |
| 36 | +gr.Workflow(bind={"My Summarizer": summarize}).launch() |
| 37 | +``` |
| 38 | + |
| 39 | +## Defining edges in code |
| 40 | + |
| 41 | +For pipelines you want to ship with a fixed topology, declare edges programmatically: |
| 42 | + |
| 43 | +```python |
| 44 | +import gradio as gr |
| 45 | + |
| 46 | +def clean(text: str) -> str: |
| 47 | + return text.strip().lower() |
| 48 | + |
| 49 | +def tag(text: str) -> str: |
| 50 | + return f"[processed] {text}" |
| 51 | + |
| 52 | +gr.Workflow( |
| 53 | + bind=[clean, tag], |
| 54 | + edges=[("clean", "tag")], |
| 55 | +).launch() |
| 56 | +``` |
| 57 | + |
| 58 | +Each edge is a `(from_fn, to_fn)` tuple. Use `"fn_name.port_label"` to target a specific port when a node has multiple inputs or outputs. |
| 59 | + |
| 60 | +> **Note:** `edges=` is only applied when no workflow file exists yet. If `workflow.json` already exists, `edges=` is ignored — delete the file to regenerate the topology from `bind` and `edges`. |
| 61 | +
|
| 62 | +## Loading from a JSON file |
| 63 | + |
| 64 | +Pass a `graph=` path to load a saved workflow topology. The canvas reads from the file on each page load and autosaves back to it when you make edits. |
| 65 | + |
| 66 | +```python |
| 67 | +gr.Workflow(graph="workflow.json").launch() |
| 68 | +``` |
| 69 | + |
| 70 | +If the file doesn't exist yet, it's created on first save. Combine `graph=` with `bind=` to pre-wire Space nodes alongside your Python functions. |
| 71 | + |
| 72 | +## Workflow JSON format |
| 73 | + |
| 74 | +A workflow is a JSON file with three node collections: |
| 75 | + |
| 76 | +```json |
| 77 | +{ |
| 78 | + "schema_version": "2", |
| 79 | + "name": "My Pipeline", |
| 80 | + "references": [ |
| 81 | + { |
| 82 | + "id": "ref_image", "label": "Input Photo", "role": "reference", |
| 83 | + "asset_type": "image", |
| 84 | + "inputs": [{"id": "in", "label": "Image", "type": "image"}], |
| 85 | + "outputs": [{"id": "out","label": "Image", "type": "image"}], |
| 86 | + "x": 80, "y": 120, "width": 220, "height": 124, "data": {} |
| 87 | + } |
| 88 | + ], |
| 89 | + "operators": [ |
| 90 | + { |
| 91 | + "id": "op_flux", "label": "FLUX.1", "role": "operator", |
| 92 | + "kind": "space", |
| 93 | + "space_id": "black-forest-labs/FLUX.1-schnell", |
| 94 | + "endpoint": "/infer", |
| 95 | + "inputs": [{"id": "in_0", "label": "Prompt", "type": "text", "required": true}], |
| 96 | + "outputs": [{"id": "out_0","label": "Result","type": "image","output_index": 0}], |
| 97 | + "x": 400, "y": 120, "width": 220, "height": 124, "data": {} |
| 98 | + } |
| 99 | + ], |
| 100 | + "subjects": [ |
| 101 | + { |
| 102 | + "id": "sub_img", "label": "Output Image", "role": "subject", |
| 103 | + "asset_type": "image", |
| 104 | + "inputs": [{"id": "in", "label": "Image", "type": "image"}], |
| 105 | + "outputs": [{"id": "out","label": "Image","type": "image"}], |
| 106 | + "x": 700, "y": 120, "width": 220, "height": 107, "data": {} |
| 107 | + } |
| 108 | + ], |
| 109 | + "edges": [ |
| 110 | + { |
| 111 | + "id": "e1", |
| 112 | + "from_node_id": "ref_image", "from_port_id": "out", |
| 113 | + "to_node_id": "op_flux", "to_port_id": "in_0", |
| 114 | + "type": "image" |
| 115 | + } |
| 116 | + ] |
| 117 | +} |
| 118 | +``` |
| 119 | + |
| 120 | +| Collection | Role | |
| 121 | +|---|---| |
| 122 | +| `references` | Inputs — uploaded files, editable text, literal values | |
| 123 | +| `operators` | Processing steps — Spaces, models, datasets, Python functions | |
| 124 | +| `subjects` | Outputs — the results being created | |
| 125 | + |
| 126 | +### Operator kinds |
| 127 | + |
| 128 | +| `kind` | What it calls | |
| 129 | +|---|---| |
| 130 | +| `"space"` | Any Gradio Space on the Hub via `gradio_client` | |
| 131 | +| `"model"` | HF Inference API — set `pipeline_tag` to select the task | |
| 132 | +| `"dataset"` | Streams rows from any Hub dataset | |
| 133 | +| `"fn"` | A Python function passed via `bind=` | |
| 134 | + |
| 135 | +## Port types |
| 136 | + |
| 137 | +Ports are typed so the canvas can validate connections. Supported types: |
| 138 | + |
| 139 | +`image` · `audio` · `video` · `text` · `number` · `boolean` · `gallery` · `file` · `json` · `model3d` |
| 140 | + |
| 141 | +## Fan-out pipelines |
| 142 | + |
| 143 | +One reference can feed multiple operators simultaneously — they run in parallel: |
| 144 | + |
| 145 | +```python |
| 146 | +# workflow.json excerpt — one product photo → 4 FLUX Kontext branches |
| 147 | +"edges": [ |
| 148 | + {"from_node_id": "ref_product", ..., "to_node_id": "op_kontext_0", ...}, |
| 149 | + {"from_node_id": "ref_product", ..., "to_node_id": "op_kontext_1", ...}, |
| 150 | + {"from_node_id": "ref_product", ..., "to_node_id": "op_kontext_2", ...}, |
| 151 | + {"from_node_id": "ref_product", ..., "to_node_id": "op_kontext_3", ...} |
| 152 | +] |
| 153 | +``` |
| 154 | + |
| 155 | +## Deploying to Spaces |
| 156 | + |
| 157 | +A Workflow app is a standard Gradio app — deploy it to Hugging Face Spaces exactly like any other, by uploading the code to a Space, or by simply running in your terminal: |
| 158 | + |
| 159 | +``` |
| 160 | +gradio deploy |
| 161 | +``` |
| 162 | + |
| 163 | +On a Space, the canvas authenticates visitors via OAuth. The Space owner gets write access (can edit and save the workflow); visitors get a read-only view and can run the pipeline with their own HF token. As a result, you should set `hf_oauth: true` [in your Space](https://huggingface.co/docs/hub/en/spaces-oauth). |
| 164 | + |
| 165 | +## API access |
| 166 | + |
| 167 | +Every Workflow app is a Gradio app, meaning that it exposes a Gradio REST API endpoint for each output (subject) node. The endpoint name is derived from the subject's label — for example, a subject labelled "Output Image" becomes `/output_image`. Use `client.view_api()` to see the exact names for your workflow: |
| 168 | + |
| 169 | +```python |
| 170 | +from gradio_client import Client |
| 171 | + |
| 172 | +client = Client("your-username/my-workflow") |
| 173 | +client.view_api() # lists available endpoints and their parameters |
| 174 | + |
| 175 | +result = client.predict("a sunset over mountains", api_name="/output_image") |
| 176 | +``` |
| 177 | + |
| 178 | +This also means that you can reuse your workflows within larger workflows, making it possible to build modular and complex applications with Gradio Workflows! |
0 commit comments