Skip to main content

Scopes & visibility

Agent Flow's scopes are lexical and statically decidable. One chain, outermost to innermost:

workflow  : input, context, use aliases (agent/team)
pipeline  : (inherits workflow) + completed stage results (source-order progressive)
stage     : (inherits pipeline) + stage results completed earlier in source order
block     : if then / else bodies
map       : the parallel-map loop variable
verify    : check names (visible to pass when only)

Inner sees outer; siblings never see each other.

Key rules​

Inside a stage: earlier results are visible​

A stage can read results from stages completed earlier in source order:

stage a -> A { ... }
stage b -> B { ... }
stage c -> C {
  let x = a        // ✓ a is complete
  let y = b        // ✓ b is complete
  return x
}

Later stages are not yet in scope. Reading a later or missing name produces unknown-variable.

At pipeline level: progressive visibility​

Pipeline-level statements see the results of every stage earlier in source order:

stage summary -> TriageSummary { ... }

if summary.urgent_count > 0 {          // stage result at pipeline level
  emit progress { attention: true }
}

let binds in the current scope​

let takes effect in the current scope; reusing a name in the same scope is duplicate-variable. Inner scopes (if blocks, map bodies) may reference outer variables; separate scopes (then vs else) may each have their own same-named let.

input and context​

  • input: the declared workflow parameter, typed by the input type (possibly external); validated against its Schema first — failing raises WorkflowInputValidationError
  • context: host-injected read-only JSON. Declaring context: ContextType enables static member checks and runtime Schema validation; omitting the declaration leaves it as any

Common traps and their diagnostics​

TrapDiagnostic
Reading a later or missing stage resultunknown-variable
Shorthand field { plan } with no visible planunknown-variable
Same-scope let reuseduplicate-variable
Reserved word as the map variable (as task)a hard syntax error

Shorthand object fields​

input {
  request: input
  plan                    // equivalent to plan: plan — plan must be visible
}

Example: a full tour of the scopes​

Excerpted from examples/data-report.flow:

stage profile -> DataProfile {
  require unique(input.columns[*].name)     // workflow-scope input
    else fail "column names must be unique"
  let result = agent(analyst) { /*...*/ expect DataProfile }
  return result                              // stage-scope let
}

stage charts -> ChartSpec[] {                     // earlier profile is visible
  let specs = agent(analyst) {
    input { table: input, profile: profile } // input and earlier stage result both usable
    expect ChartSpec[]
  }
  return specs
}

stage report -> text {                            // earlier profile and charts are visible
  let narrative = agent(analyst) {
    input { profile: profile, charts: charts }
    expect text
  }
  return narrative
}

return { profile: profile, charts: charts, summary: report }  // pipeline sees all

Next steps​