---
title: "Create a Flow"
url: https://developers.dagio.ai/flows/
---

# Create a Flow

   
                      
                                                                          
             
              
          
   

## Start from the expected result

A Flow organizes work needed to produce a result. **Prepare a quote** receives a client and need, builds a proposal, requests review and retains the approved version. It is more than a sequence of AI messages.

In Studio, name the Flow, declare inputs and add steps. Connect their dependencies. Authoring tools and AI use the same definitions; the Surface engine retains execution, waits and decisions.

| Element      | Expected values                      | Description                       |
| ------------ | ------------------------------------ | --------------------------------- |
| Inputs       | Typed Fields or parameters           | Information needed to start       |
| Steps        | Human work, AI or admitted operation | Execution and tracking units      |
| Dependencies | Existing step keys without cycles    | Ordering and possible parallelism |
| Result       | Declared Surface or deliverable      | What the Flow produces            |
| Approval     | Decision and authorized reviewer     | Human checkpoint                  |
| Recovery     | Error and wait policy                | Continuity after interruption     |

## Example: prepare a quote

```text
Inputs: client and need
1. Qualify → identify missing information
2. Prepare → draft from rates and procedure
3. Review → request the manager’s decision
4. Finalize → retain the approved quote
Result: Quote record linked to Client
```

## Start from an Action

**Prepare proposal** collects the need and client. Confirmation starts the Flow and opens progress. An open client can supply initial context; required inputs are still checked before launch.

Before confirming, review the proposed Flow as cards and a graph. Items **created when you confirm**
are distinguished from the model's **planned steps**: a possible path is not work already started.
Check dependencies and the choices offered, then return to the inputs if you want to change them.
If the graph cannot be displayed, reopen the review rather than confirming without that overview.

If the start is confirmed but progress cannot be opened, try opening progress again. Do not repeat
the Action to resolve this read problem.

## Follow a run

AI and client integrations use `surface_flow_instance_read` for an exact execution,
`surface_flow_execution_discover` to open it from its Work, and
`surface_flow_signal_references` for authorized signal choices. These same interfaces cover typed
waits, delays, signals, failures and cancellation. Review with `surface_flow_transition_prepare`,
then confirm that exact intention with `surface_flow_transition_apply`; a read or discovery is not
confirmation and does not grant execution rights.

A selected Work step must belong to its declared source: the authored step Query or an actual
occurrence in the Flow's own scope. Search and pagination only change what is displayed; they do
not grant or remove permission to select a step. Recovery rereads that exact selection natively
before reopening its capabilities, rather than treating a visible row or a descendant as proof.

In **Action Required**, find the approval and input requests addressed to you. The count describes
the items displayed, not an assumed total while the list is still loading. Use **Show more** to
continue, or **Refresh** after a read failure. Opening a request returns to its progress and review;
it does not confirm the decision for you.

Open the Flow from its work to see its current state, steps and history. You do not need to find a technical execution identifier. The steps and history each show how many items are loaded and offer their own continuation; a partial page is not the complete run.

History dates identify when changes were recorded. They do not claim to measure how long an external service worked. Inputs and outputs remain with their authorized sources and results, rather than being copied into progress messages.

Use the actions offered for the current run. A failed step does not automatically permit another business attempt. Choose an approval decision or branches explicitly, then review and confirm the proposed intervention. If a confirmation response is lost, resume that same confirmation instead of starting another run. Live progress is not confirmation that an intervention was committed.

Conversation cards open the same run view in the application that issued the card. A review card returns to the intervention review; a result card opens its recorded state without repeating the action. Run tracking does not replace your content editor or open the technical execution document.

When you ask about this Flow, Surface supplies its operating instructions and the versions
consulted. After the application changes, current instructions remain separate from those retained
by the run: opening another Workspace does not replace your question's target. If the Flow state or
your access has changed, refresh its run view before continuing; Surface does not substitute another
guide.

For a delayed step, the run view shows its recorded resume date. A stop request remains distinct from confirmed cancellation while work is still awaiting a stop confirmation. Failure details distinguish a rejected approval, an expired wait and an uncertain external outcome; none alone grants permission to retry. Signal forms ask only for the declared values and your decision, not a technical event identifier. Surface retains that identity with your confirmation so retrying a lost response does not submit a second signal.

When a signal asks for a record or a Result, choose it from the list defined by the application.
Search and pages keep that selection's scope. Surface checks the chosen version again before using
it; a Result also retains its actual Task and action provenance. If the source or your access has
changed, refresh the choice rather than entering an identifier or replacing it with another record.

When a wait requests a reference, choose it from the authorized content offered by Surface. Search
and subsequent pages remain tied to that wait. Choosing a reference does not send the signal: your
other values remain in the form until you review and confirm.

## Use the selected Task’s operating context

When you ask AI about a Flow Task, keep that Task as the exact target. If its Model declares
several operating Actions, choose the intended one before loading its instructions. Discovery
shows the available choices; it does not run the Task, read its evidence or approve its result.

Surface keeps the Flow's original captured references separate from the current application's
instructions and permissions. A missing original context is reported explicitly, not replaced by
another Task's context or a different guide. See [working with AI](https://developers.dagio.ai/ai/) for the MCP discovery
and instruction reads.

## Definition and execution

A Flow definition is reusable. Each run has its own inputs, steps and result. Changing the definition does not silently rewrite running work. Versioning, migration and recovery preserve traceability.

Continue with [steps](https://developers.dagio.ai/steps/), [waits](https://developers.dagio.ai/waits/) and [results](https://developers.dagio.ai/results/).

<!-- surface-examples:start -->

## Applied examples : Prepare a quote

The Flow declares Client and Need inputs, an executable step and a bounded budget.

### Configuration

Fragment placed in `flowBlueprints[].composition`. [Properties and accepted values](https://developers.dagio.ai/reference/flow-composition/).

```json
{
  "contract": "FlowComposition@1",
  "rootWorkNodeKey": "prepare-quote",
  "stateSurfaceDefinitionPath": "workspace/work/surface/preparation",
  "subflowLinkTypePath": null,
  "entryStepKey": "prepare",
  "inputs": [
    {
      "key": "client",
      "type": "surface-reference",
      "provenance": "caller",
      "minimum": 1,
      "maximum": 1
    },
    {
      "key": "need",
      "type": "text",
      "provenance": "caller",
      "minimum": 1,
      "maximum": 1
    }
  ],
  "contexts": [],
  "outputs": [],
  "steps": [
    {
      "key": "prepare",
      "kind": "task",
      "workNodeKey": "prepare",
      "actionKey": "prepare",
      "inputs": {},
      "outputs": [
        {
          "key": "proposal",
          "type": "result-reference",
          "provenance": "canonical",
          "minimum": 1,
          "maximum": 1,
          "result": "reference"
        }
      ],
      "reservedCostUnits": 1,
      "maximumAttempts": 1
    }
  ],
  "budgets": {
    "maximumDepth": 2,
    "maximumOccurrences": 20,
    "maximumConcurrency": 2,
    "maximumIterations": 3,
    "maximumDurationMilliseconds": 86400000,
    "maximumCostUnits": 100,
    "maximumStateBytes": 32000
  }
}
```

### Variation and connection

Fragment placed in `flowBlueprints[].composition.inputs`. [Properties and accepted values](https://developers.dagio.ai/reference/flow-composition/).

```json
[
  {
    "key": "client",
    "type": "surface-reference",
    "provenance": "caller",
    "minimum": 1,
    "maximum": 1
  },
  {
    "key": "need",
    "type": "text",
    "provenance": "caller",
    "minimum": 1,
    "maximum": 1
  }
]
```

### UI layout example

The illustrative layout below places this configuration in the Clients/Quotes app. Insert each fragment at the stated location, with Field, Query and Action references matching the Model declarations.

1. Qualify need
2. Prepare proposal
3. Wait for decision
4. Retain result

<!-- surface-examples:end -->