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

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 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, waits and results.

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.

{
  "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.

[
  {
    "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

SurfaceClients / North StudioExample

Create a FlowPrepare a quote

Clients

✓

Qualify needCompleted

✓

Prepare proposalCompleted

03

Wait for decisionDecision required

04

Retain resultUpcoming

Preparation is awaiting a decision

The proposal and its sources remain available while waiting.

Review proposal