Context Scope

Context Scope controls data visibility and flow between actions—selecting which upstream namespaces an action can read from the record, what passes through to output, and what gets excluded.

:::warning Required context_scope is required on every action. Omitting it raises a ConfigurationError. Every action must declare its data dependencies explicitly via observe, passthrough, or drop.

Many examples in these docs show a single key and leave context_scope out to stay short. They are fragments, not whole actions: add a context_scope when you copy one into a workflow. :::

Directives

Directive	Purpose	In LLM Context	In Output
observe	Include specific fields in LLM context	Yes	No
drop	Exclude specific fields from context	No	No
passthrough	Forward fields directly to output	No	Yes

Syntax

yaml

YAML

context_scope:
  observe:
    - upstream_action.field_name
    - another_action.nested.field
  drop:
    - source.unused_field
    - upstream_action.internal_field
  passthrough:
    - upstream_action.preserve_this
    - source.metadata

Observe Directive

The observe directive selects which upstream namespaces and fields are visible to the action. When specified, only listed namespaces are included in the LLM context.

yaml

YAML

- name: Cluster_Validation_Agent
  dependencies: [canonicalize_facts, group_by_similarity, cluster_list]
  context_scope:
    observe:
      - canonicalize_facts.candidate_facts_list
      - cluster_list.semantic_unique_id
      - group_by_similarity.num_similar_facts
      - source.page_content  # Can include source data

Drop Directive

The drop directive excludes fields from the LLM context. All other fields are included unless observe is also specified.

yaml

YAML

- name: fact_extractor
  context_scope:
    drop:
      - source.syllabus    # Reference data not needed
      - source.url         # URL not relevant

Passthrough Directive

The passthrough directive forwards fields directly to the action output without including them in the LLM context. Data flows around the LLM rather than through it.

yaml

YAML

- name: Cluster_Validation_Agent
  dependencies: [canonicalize_facts, group_by_similarity]
  context_scope:
    observe:
      - canonicalize_facts.candidate_facts_list
    passthrough:
      - group_by_similarity.grouped_facts   # Forward without LLM seeing
      - source.url                          # Preserve for downstream

:::warning Passthrough preserves output — it does not feed downstream context passthrough keeps a field in this action's own output record (for lineage or export). It does not make that field available to later actions through this action. A downstream action that needs the value must observe it from its original producing action (for example observe: [source.url]), not from the action that passed it through.

In particular, observe: [some_action.*] expands only to some_action's own output fields — it does not pull in fields that some_action merely passed through. Relying on an upstream passthrough to satisfy a downstream observe can make the field resolve empty at runtime, silently, because the field is still declared on the consumer's schema. :::

Seed Data

Static reference data can be loaded via seed. See Seed Data for details.

yaml

YAML

defaults:
  context_scope:
    seed:
      exam_syllabus: $file:syllabus.json
  data_source:
    type: local
    folder: ./staging
    file_type: [json]
  expect:
    repair: auto
    max_iterations: 3
  batch_max_workers: 6

Note: data_source, expect, and batch_max_workers are workflow-level defaults that can also appear in the defaults: block. They are documented in Defaults and Run Modes.

Version Field Patterns

When consuming outputs from version actions, field names are prefixed to avoid collisions. Use wildcard syntax to reference all iterations:

yaml

YAML

- name: extract_raw_qa
  versions:
    range: [1, 3]

- name: flatten_questions
  dependencies: [extract_raw_qa]
  context_scope:
    observe:
      - extract_raw_qa.*  # Matches extract_raw_qa_1_*, extract_raw_qa_2_*, etc.

See Version Actions for complete documentation.

Auto-Inferred Context Dependencies

Actions referenced in context_scope or the prompt but not in dependencies are automatically treated as context dependencies. They are read from the record, which carries the namespace of every action upstream of it, so a context dependency must be upstream of the action through its dependencies.

yaml

YAML

- name: extract_data
- name: enrich_data
  dependencies: [extract_data]
- name: validate_data
  dependencies: [enrich_data]

- name: generate_report
  dependencies: [validate_data]  # Primary input source
  context_scope:
    observe:
      - validate_data.*        # From input files
      - enrich_data.*          # Auto-inferred: upstream of validate_data
      - extract_data.*         # Auto-inferred: upstream of enrich_data

How it works:

1. validate_data is in dependencies → its output files are processed as input
2. enrich_data and extract_data are only in context_scope → auto-inferred as context dependencies
3. Context dependencies are read from the namespaces on each input record, so the data comes from the same record

Preflight refuses an action that names one that is not upstream of it, such as an action that runs beside or after it or one on a parallel branch: that action's namespace is not sure to be on the records it reads. To read it, depend on an action downstream of it, or on the action itself as well — the fan-in pattern, where multiple upstream actions feed into one action:

yaml

YAML

- name: final_action
  dependencies: [action_A, action_B, action_C]  # Fan-in pattern
  context_scope:
    observe:
      - action_A.*   # Primary input (first in list)
      - action_B.*   # Fan-in dependency
      - action_C.*   # Fan-in dependency

Resolution Order

1. Observe filter - If observe is specified, start with only those fields
2. Drop filter - Remove any fields in drop list
3. Passthrough merge - After LLM processing, merge passthrough fields into output

Passthrough fields never enter the LLM context—they join the output after processing.

Best Practices

1. Use observe for focus: When LLM needs only specific fields
2. Use drop for noise reduction: When most fields are needed but some aren't
3. Use passthrough for data lineage: Preserve data that downstream actions need

Combined Example

yaml

YAML

- name: generate_explanation
  dependencies: [generate_summary]
  context_scope:
    observe:
      - generate_summary.summary    # LLM needs this
    passthrough:
      - source.url                  # Preserve for downstream
    drop:
      - generate_summary.debug_info # Internal, not needed

Debugging Context

Enable prompt_debug to see the rendered context:

yaml

YAML

- name: my_action
  prompt_debug: true

See Also

• Version Actions - Loop configuration and consumption patterns
• Field References - Field reference syntax and validation
• Seed Data - Loading static reference data