depends_on to ask for a field only after another field has a value. Add CORRECTIONS: true in a FLOW step so that changing the first answer clears the answers that depend on it.
Concept
A dependency links two fields. Three mechanisms create one. They answer different questions.
The first two control when a field is asked. The progressive collection article covers them in full. This article covers what that article does not: chains of dependencies, what happens when the customer changes an earlier answer, the compile-time checks, and source rules.
A dependency does not check a value.
depends_on: [country] never tests that the region belongs to the country. To compare two values, see Enforce business rules with constraints.
Minimal working example
A delivery agent collects a location from the country down to the city. Each level depends on the one above. A customs ID is needed only outside the US. When the customer changes the country, the agent clears the region and city and asks again.agents/delivery-address-collector.agent.abl
- All variables are
GATHERfields. The customer supplies each one. confirmreads all four.customs_idis empty for a US address.
How it works
- At the start of each turn, the runtime lists the active fields. A progressive field is active when every field in its
depends_onlist has a value. - The step asks for the active fields that are still missing. At first, only
countryis active. - A chain opens one level per answer:
country, thenregion, thencity. - A field has a value when it is not null, not undefined, and not an empty string.
When the customer changes an earlier answer
This applies to aFLOW step with CORRECTIONS: true.
- The runtime reads the reply with the already-collected fields included.
- A valid value that differs from the stored one counts as a correction.
- The runtime clears every field that depends on the corrected field, directly or through a chain. Changing
countryclearsregionandcity. - A dependent that the customer re-gives in the same reply keeps its new value.
- The agent says the field was updated and may ask again for the cleared fields. Override the wording with the
gather_correction_appliedandgather_correction_dependents_clearedkeys inMESSAGES. - A correction that fails validation is rejected. The runtime clears that field and asks again.
depends_on only. A field gated by when: is not cleared. Its condition is checked again on the next turn.
Compile-time checks
The compiler checksdepends_on inside one GATHER block, at the top level or in one step.
Common variations
Accept a value only from the customer
satisfied_by lists the sources allowed to fill a field: user_input, authoritative_tool, system. A value from any other source is rejected. Omit it to accept any source.
Use this when a field must come from the customer and must not be filled by a tool. Pair it with a dependency when the customer’s answer only makes sense after an earlier one.
Dependencies in a top-level GATHER
The samedepends_on and when: rules work in a top-level GATHER. Clearing dependents after a change is not available there. It runs only in a FLOW step with CORRECTIONS: true. In a top-level GATHER, the runtime does not clear dependents for you.
Verification
- Run the validator. Expect no errors and no warnings.
- Say “Germany”. Expect the agent to ask for the region only.
- Say “Bavaria”. Expect a question for the city.
- Say “Munich”. Expect a question for the customs ID, because the country is not the US.
- Say “Actually, the country is the US.” Expect the agent to confirm the change and to ask again for the region and city. Expect no customs ID question.
- Say “Texas” and “Austin”. Expect the confirmation with the US address.
- In the trace, find the
correction_invalidationevent. ItscorrectedFieldsandinvalidatedFieldsshow what was cleared. - For
Refund_Approval_Intake, expect no approval code question until the amount is set.
Production readiness checklist
- Every
depends_onname exists in the sameGATHERblock. - Every dependent field is read by
COMPLETEor a later step. - Steps that collect a chain set
CORRECTIONS: true. - Tests cover a change to each field that others depend on, including a field in the middle of a chain.
- A value that depends on another value, such as a region in a country, is checked by a lookup or a constraint. A dependency alone does not check it.
MESSAGEStext for the correction notices matches your brand voice and languages.