Dynamic Flows
View SourceA dynamic Flow can select the next Action or Flow from runtime data. Use a
terminal Jido.Flow.Dispatch when the current Flow must make that selection.
Dispatch does not add a node to a running graph or change the current graph.
It completes the current Flow, then its expander can continue the same
Jido.Exec call with another executable.
Use Jido.Flow.new/1 instead when application code must construct the graph
itself at runtime. See Flow Data Definitions.
How Dispatch Works
A Dispatch has two Actions:
- The decision Action receives the Dispatch parameters and returns a map.
- The expander Action receives that complete map.
- The expander returns a final result or selects the next executable.
The expander can return either form:
{:ok, final_result}
{:continue, next_input, next_executable}A normal result completes the Flow. A continuation completes the Flow and runs the selected Action or Flow next. The same context, timeout, and continuation budget apply to the complete chain.
Define A Dispatch
This example asks one Action to select a route. A second Action converts that decision into a final result or a continuation.
defmodule MyApp.Actions.ChooseRoute do
use Jido.Action, name: "choose_route"
@impl true
def run(%{mode: :finish, value: value}, _context) do
{:ok, %{route: :finish, value: value}}
end
def run(%{mode: :continue, value: value, target: target}, _context) do
{:ok, %{route: :continue, value: value, target: target}}
end
end
defmodule MyApp.Actions.ExpandRoute do
use Jido.Action, name: "expand_route"
@impl true
def run(%{route: :finish, value: value}, _context) do
{:ok, %{value: value}}
end
def run(%{route: :continue, value: value, target: target}, _context) do
{:continue, %{value: value}, target}
end
end
defmodule MyApp.Flows.DynamicRoute do
use Jido.Flow, name: "dynamic_route"
flow do
step "prepare", value <- input(:value) do
{:ok, %{value: value}}
end
dispatch "route",
decision: MyApp.Actions.ChooseRoute,
expander: MyApp.Actions.ExpandRoute,
params: %{
mode: input(:mode),
target: input(:target),
value: result("prepare", :value)
}
output result("route")
end
endThe selected target can be an Action module, a Flow module, or a runtime
%Jido.Flow{} value:
Jido.Exec.run(MyApp.Flows.DynamicRoute, %{
mode: :continue,
target: MyApp.Actions.Next,
value: 3
})Target selection is application code. Only select trusted executable values. A stored name or external value must first pass through an application-owned registry.
Use Action Modules For Dispatch
Dispatch uses Action modules for its decision and expander. The decision gets
the resolved Dispatch params. The expander gets the complete decision
result. Both targets can be handwritten or generated Action modules.
Flow does not accept inline bodies for either role.
Dispatch Rules
Every Flow with Dispatch must follow these rules:
- The Flow has only one Dispatch.
- Dispatch is the last component.
- Flow output is the complete Dispatch result, such as
result("route"). - Only the expander can return
{:continue, input, target}. - The decision and all other Flow components cannot continue.
- Dispatch works only with run-to-completion execution.
- A Flow with Dispatch cannot be used as a Subflow.
These rules make the boundary clear: the graph completes before another executable starts.
Output Validation And Effects
When the expander returns {:ok, result}, the current Flow owns the result and
applies its output schema. Decision and expander Actions can return an optional
third element with a proper list of effect requests. Flow collects decision
effects before expander effects.
When the expander returns a continuation, the selected executable owns final output validation and the final output. Earlier effects remain in the same list, before the next executable's effects. Failure anywhere in the chain returns no executable effects. See Execution.
A continuation selects the next executable:
def run(params, _context) do
{:continue, params, MyApp.Actions.Finalize}
endDo not start a nested Jido.Exec call from the expander. Return a continuation
so one Exec call owns the complete chain.
Define Dispatch With Data
All Flow authoring forms produce the same canonical Dispatch value.
{:ok, flow} =
Jido.Flow.new(%{
output: Jido.Flow.Ref.result("route"),
components: [
%{
kind: :dispatch,
name: "route",
decision: MyApp.Actions.ChooseRoute,
expander: MyApp.Actions.ExpandRoute,
params: %{mode: Jido.Flow.Ref.input(:mode), value: Jido.Flow.Ref.input(:value)}
}
],
name: "dynamic_route"
})Use Jido.Flow.Dispatch.new/1 for direct canonical construction. Use
Jido.Flow.Codec and a trusted Registry when stored JSON defines the Flow.
Build A Bounded Loop
A continued Action can return to the dynamic Flow. This supports tool loops and other bounded decision cycles:
defmodule MyApp.Actions.RunTool do
use Jido.Action, name: "run_tool"
@impl true
def run(%{call: call, messages: messages}, context) do
with {:ok, result} <- MyApp.Tools.call(call, context) do
messages = messages ++ [%{role: :tool, content: result}]
{:continue, %{messages: messages}, MyApp.Flows.Reason}
end
end
endOne Jido.Exec.run/4 call owns the full chain. Set both limits for loops:
Jido.Exec.run(MyApp.Flows.Reason, input, context,
max_continuations: 12,
timeout: 30_000
)max_continuations defaults to 256 and accepts 0 through 10_000. The
timeout covers the complete chain. run_async/4 uses the same rules, and its
handle represents the complete chain.
Continue From A Root Action
A root Action can also select the next executable without a Flow:
def run(%{tool: tool, arguments: arguments}, _context) do
{:continue, arguments, tool}
endThe input must be a map. The target can be an Action module, a Flow module, or a runtime Flow value. The current context passes to the target without a change.
The complete input cannot be a Jido.Action.Output envelope. Put an envelope
in a named map field when the next executable must receive it:
{:continue, %{output: Jido.Action.Output.raw("complete")}, MyApp.Actions.Next}Target resolution belongs to the current executable. If the complete-call timeout expires before the target descriptor resolves, the timeout error belongs to the current executable. After resolution, the selected target owns its execution lifecycle.
Use Dispatch when earlier Flow work supplies the decision. Use a root Action continuation when no graph is needed.