A Flow is a defined sequence of steps in a Qi workspace, with checkpoints where a person can be required to approve before it continues. It coordinates people, agentic oracles, tools, evidence and decisions. Plan one when you already know the order the work happens in, and you need each step to be repeatable and open to inspection. This page helps you write the Flow down as states, actors and rules.
This is a design guide. It helps you plan, and it gives you nothing to run. For paths you can follow to a working result today, see Choose your path.
| You end with | A Flow design: the question it answers, its trigger, actors and states, who may act in each state, the evidence each step needs, the human approvals, and what each result triggers. |
| Who decides | You set the steps and who may act at each one. Where a step turns on a claim, a decision oracle produces the facts and the IXO decision engine applies the rules. A person approves at the checkpoints you set. |
What you are designing
Most Flows on IXO follow the same sequence:
- A domain is registered for what the work is about: a person, an organisation, a project, an asset, a place, a service or an agent. Its controllers, services, resources, accounts and relationships are set up.
- A person, a service or an oracle is authorised to act on the domain, on a claim or on its evidence. On IXO that authority is a delegation (a UCAN).
- A person, a service or an oracle submits a claim: work was completed, evidence was collected, eligibility was met, or an outcome occurred.
- The claim is checked and decided. A decision oracle produces the facts, and the IXO decision engine applies the rules and signs the decision.
- The decision is recorded. It can set a payment, a governance step, an escalation, a notification, a credential or the next step of the Flow in motion.
- Decided claims feed analytics, agent evaluation and later decisions.
Core concepts shows the claim, the evidence and the decision as records.
If your Flow is one of these kinds, a more specific guide goes further:
| The Flow | Plan it with |
|---|---|
| Takes claims from submission to a decision | Design a verified claims workflow |
| Turns measurements into verified outcomes | Design a digital MRV workflow |
| Releases funding when an outcome is verified | Design outcomes-based financing |
| Has an agent review evidence and support a person's decision | Agent evaluations |
Design steps
Write the question the Flow answers
Start with a Flow that answers one operational question, such as:
- Can this participant be onboarded?
- Is this claim complete?
- Does this evidence satisfy the protocol?
- Should this outcome be approved?
- Should this value be released?
- Should this task go to a person?
Choose the trigger
Decide what starts the Flow: a claim submission, an onboarding request, a marketplace order, a scheduled review, a data update, a governance decision or an outside event.
List the actors
List who takes part and keep their roles apart: submitters, reviewers, the decision oracle that checks claims, approvers, funders, operators, agents, services and observers. Write what each one is responsible for.
Map the states
Write the Flow as states, not only as tasks. For example: Draft, Submitted, Evidence Required, In Review, Approved, Disputed, Settled, Closed.
On chain a dispute is a record of its own, separate from the claim. If your Flow has a disputed state, design it around how claim disputes work.
Say who may act in each state
For each state, write who can act, which tools they can use, which data they can read, and which actions move the Flow to another state. Do the same for each agentic oracle: the task it does and the tools it may use.
Set the evidence and the rules
For each step, list the evidence it needs. Then name the Blueprint that holds the rules: the claim form, the evidence rules, the rubric, and who may approve. Design a Blueprint covers that.
Mark the human approvals
Mark each state where a person must approve before the Flow continues, and say where a case goes when it has to be escalated.
Decide what each result triggers
For each decision the Flow can reach, write what follows: the record that changes, the notification that is sent, the handoff, and the next action.
Write the test cases
Write at least these, each with the result you expect:
- A case where everything goes right.
- A case with missing evidence.
- A case that is rejected.
- A case that is escalated.
Test the Flow against all four before it goes into production.
What a Flow does not do
- It does not decide a claim. It carries the claim to the check and acts on the result. A decision oracle and the IXO decision engine do the deciding. See Design an evaluator.
- It does not turn a decision into a payment. A decision says what the rules concluded. Payment needs someone with authority over the money to have allowed it. See What each record proves.
- It does not give anyone authority. Each actor still needs the role, grant or delegation for the step they perform.
Where a Flow is built
Use the Flow Builder agentic oracle in qi.space to turn your process, actors, triggers, actions, tools and approvals into an executable workflow design.